> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores de integración

> Soluciones para problemas comunes con integraciones, API y webhooks de SalesOS.

# Errores de integración

Guía para diagnosticar y resolver problemas comunes con las integraciones de SalesOS, incluyendo API, webhooks y SalesOS Connect.

## Errores de API

<AccordionGroup>
  <Accordion title="Error 401 - No autenticado">
    **Causa:** Token de acceso inválido, expirado o ausente.

    **Soluciones:**

    1. Verifica que estás incluyendo el header `Authorization: Bearer TU_TOKEN`
    2. Comprueba que el token no ha expirado (revisa el campo `exp` del JWT)
    3. Solicita un nuevo token usando tu refresh token
    4. Verifica que las credenciales OAuth sean correctas
  </Accordion>

  <Accordion title="Error 403 - No autorizado">
    **Causa:** El token es válido pero no tiene permisos suficientes.

    **Soluciones:**

    1. Verifica los scopes de tu token (ejemplo: `read:leads`, `write:leads`)
    2. Asegúrate de que tu usuario tiene el rol necesario para la operación
    3. Solicita los scopes necesarios al generar el token
  </Accordion>

  <Accordion title="Error 429 - Rate limit excedido">
    **Causa:** Has superado el límite de solicitudes por minuto.

    **Soluciones:**

    1. Revisa los headers `X-RateLimit-*` para conocer tu uso
    2. Implementa una cola de solicitudes con backoff exponencial
    3. Optimiza tus llamadas para reducir la cantidad de solicitudes
    4. Considera actualizar tu plan para obtener un límite mayor
  </Accordion>

  <Accordion title="Error 500 - Error interno del servidor">
    **Causa:** Error en el servidor de SalesOS.

    **Soluciones:**

    1. Espera unos minutos y reintenta la solicitud
    2. Verifica si hay un incidente activo en la página de status
    3. Si el error persiste, contacta al soporte técnico con los detalles de la solicitud
  </Accordion>
</AccordionGroup>

## Problemas con webhooks

<AccordionGroup>
  <Accordion title="No recibo notificaciones de webhook">
    **Verificaciones:**

    1. Confirma que el webhook está **activo** en la configuración
    2. Verifica que la URL del endpoint es accesible públicamente
    3. Comprueba que tu servidor responde con código `200`
    4. Revisa los logs de tu servidor para ver si las solicitudes están llegando
    5. Verifica que suscribiste los eventos correctos
  </Accordion>

  <Accordion title="Webhook desactivado automáticamente">
    SalesOS desactiva webhooks después de 5 intentos fallidos de entrega.

    **Solución:**

    1. Verifica y corrige el problema en tu endpoint
    2. Reactiva el webhook desde la configuración
    3. Implementa un manejo correcto de errores que responda `200`
  </Accordion>

  <Accordion title="Firma del webhook no coincide">
    **Verificaciones:**

    1. Usa el cuerpo raw de la solicitud (no el parseado) para verificar la firma
    2. Verifica que estás usando el secreto correcto
    3. Asegúrate de usar HMAC-SHA256 para el cálculo
  </Accordion>
</AccordionGroup>

## Problemas con SalesOS Connect (n8n)

<AccordionGroup>
  <Accordion title="El workflow no se ejecuta">
    1. Verifica que el workflow está **activo** (no solo guardado)
    2. Comprueba las credenciales de SalesOS en n8n
    3. Revisa el log de ejecuciones para identificar errores
    4. Verifica que el trigger está configurado correctamente
  </Accordion>

  <Accordion title="Error de autenticación en n8n">
    1. Actualiza las credenciales de SalesOS en n8n
    2. Genera un nuevo token de acceso si el actual expiró
    3. Verifica que el token tiene los scopes necesarios
  </Accordion>
</AccordionGroup>

## Problemas con NFS-e

<AccordionGroup>
  <Accordion title="Error al registrar cliente">
    1. Comprueba que los datos del cliente están completos (CNPJ/CPF, razón social)
    2. Verifica si el cliente ya existe (duplicado)
  </Accordion>

  <Accordion title="NFS-e rechazada por la prefectura">
    1. Revisa los datos fiscales de tu empresa (CNPJ, inscripción municipal)
    2. Verifica el código de servicio utilizado
    3. Comprueba los datos del tomador del servicio
    4. Consulta el mensaje de error específico devuelto por la prefectura
  </Accordion>
</AccordionGroup>

<Tip>
  Al reportar un error de integración al soporte, incluye: el endpoint utilizado, el método HTTP, los headers de la respuesta y el cuerpo de la respuesta de error.
</Tip>

<Note>
  Para soporte técnico con integraciones, contacta a [suporte@play2sell.com](mailto:suporte@play2sell.com) con los detalles del error.
</Note>