> ## 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.

# Erros de Integração

> Resolva problemas com integrações, API, webhooks e conexões externas no SalesOS.

# Erros de Integração

Guia para diagnosticar e resolver problemas com integrações, API e webhooks.

## Erros de API

<AccordionGroup>
  <Accordion title="401 Unauthorized — Token inválido ou expirado">
    **Causa:** O token JWT expirou ou é inválido.

    **Solução:**

    1. Verifique se o token não expirou (duração padrão: 24h)
    2. Solicite um novo token usando suas credenciais
    3. Confirme que o Client ID e Secret estão corretos
    4. Verifique se o token está sendo enviado no header `Authorization: Bearer TOKEN`
  </Accordion>

  <Accordion title="403 Forbidden — Sem permissão">
    **Causa:** O token não possui os scopes necessários para a operação.

    **Solução:**

    1. Verifique os scopes do seu token em [jwt.io](https://jwt.io)
    2. Solicite um novo token com os scopes necessários
    3. Confirme que o cargo do usuário permite a ação
  </Accordion>

  <Accordion title="429 Too Many Requests — Rate limit excedido">
    **Causa:** Mais de 100 requisições por minuto com o mesmo token.

    **Solução:**

    1. Implemente controle de taxa no seu lado
    2. Use o header `Retry-After` para saber quando tentar novamente
    3. Implemente backoff exponencial nas retentativas
    4. Otimize suas chamadas usando paginação e filtros
  </Accordion>

  <Accordion title="409 Conflict — Duplicata detectada">
    **Causa:** Tentativa de criar um registro que já existe (ex: lead com mesmo e-mail).

    **Solução:**

    1. A resposta inclui o ID do registro existente
    2. Use PATCH para atualizar em vez de POST para criar
    3. Implemente verificação prévia antes de criar registros
  </Accordion>

  <Accordion title="500 Internal Server Error">
    **Causa:** Erro interno no servidor do SalesOS.

    **Solução:**

    1. Tente novamente após alguns segundos
    2. Se persistir, anote o `X-Request-ID` do header de resposta
    3. Entre em contato com o suporte informando o Request ID
  </Accordion>
</AccordionGroup>

## Erros de Webhook

<AccordionGroup>
  <Accordion title="Webhook não está recebendo eventos">
    1. Verifique se o webhook está **ativo** em **Configurações > Webhooks**
    2. Confirme que os **eventos corretos** estão selecionados
    3. Verifique se a URL do endpoint está acessível publicamente
    4. Confira os **logs de webhook** para ver tentativas de entrega
    5. Teste com o botão **Enviar teste** na configuração do webhook
  </Accordion>

  <Accordion title="Webhook desativado automaticamente">
    O SalesOS desativa webhooks após 5 retentativas sem sucesso.

    **Solução:**

    1. Corrija o endpoint para responder com status `200`
    2. Garanta que o endpoint responde em menos de 10 segundos
    3. Reative o webhook em **Configurações > Webhooks**
  </Accordion>

  <Accordion title="Assinatura do webhook inválida">
    1. Verifique se está usando o **secret correto** para validar
    2. Use HMAC-SHA256 com o body completo da requisição (raw, não parsed)
    3. Compare com o header `X-SalesOS-Signature`
  </Accordion>
</AccordionGroup>

## Erros de NFS-e

<AccordionGroup>
  <Accordion title="Erro na emissão de NFS-e">
    1. Verifique se os dados do cliente estão completos (CNPJ, endereço, etc.)
    2. Confirme que os códigos de serviço estão corretos
    3. Verifique se a empresa está habilitada para emissão na prefeitura
    4. Consulte o log de erros detalhado do SalesOS Pay
  </Accordion>

  <Accordion title="Cliente não encontrado">
    1. Verifique se o CNPJ/CPF está válido (dígitos corretos)
    2. Cadastre o cliente antes de emitir
  </Accordion>
</AccordionGroup>

## Diagnóstico geral

<Steps>
  <Step title="Verifique os logs">
    Acesse **Configurações > Integrações > Logs** para ver o histórico de requisições e respostas.
  </Step>

  <Step title="Teste a conectividade">
    Use o botão **Testar conexão** disponível em cada integração.
  </Step>

  <Step title="Verifique credenciais">
    Confirme que todas as chaves e tokens estão corretos e não expiraram.
  </Step>

  <Step title="Consulte o status">
    Acesse [status.play2sell.com](https://status.play2sell.com) para verificar se há problemas conhecidos.
  </Step>
</Steps>

<Tip>
  Sempre inclua o `X-Request-ID` ao reportar problemas ao suporte. Isso acelera significativamente a investigação.
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Contato" icon="headset" href="/pt/support/contact">
    Fale com o suporte técnico.
  </Card>

  <Card title="API Overview" icon="code" href="/pt/api/overview">
    Referência completa da API.
  </Card>
</CardGroup>