> For the complete documentation index, see [llms.txt](https://apidoc.toplojas.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.toplojas.com.br/funcionamento/solucao-de-problemas.md).

# Solução de Problemas

Reunimos aqui os problemas mais comuns na integração com a API e como resolvê-los. Sempre que uma requisição falhar, verifique também o elemento **`Mensagem`** retornado no corpo da resposta — ele indica a causa do erro.

{% content-ref url="/pages/-MOhyjfrwXCAIeHNbhHn" %}
[Erros](/funcionamento/erros.md)
{% endcontent-ref %}

## 🔒 Recebo 401 (não autorizado) mesmo com o token

Verifique, nesta ordem:

* **Esqueceu o `Bearer`?** O header `Authorization` deve começar com `Bearer` (com espaço), seguido do token. Exemplo: `Authorization: Bearer AAAA...`.
* **O token foi atualizado?** Ao clicar em **Atualizar Token** no painel, o token anterior é **invalidado**. Se sua integração parou de funcionar de repente, gere e configure o token atual.

Detalhes em [Conectando na API](/funcionamento/conectando-na-api.md) e [Geração de Token](/funcionamento/geracao-de-token.md).

## 🧩 Recebo 400 (campos essenciais faltando)

O código **400** indica que faltam informações essenciais na requisição. As causas mais comuns:

* Faltou o header **`Loja`** (o Identificador da Loja).
* Faltou o header **`Authorization`** (o Token).
* O módulo ou a ação não foram informados corretamente.

## 🔗 Recebo 404 (módulo ou ação não localizados)

* **Confira a barra final (`/`) da rota.** Todas as rotas da API terminam com `/` — por exemplo, `/pedidos/` e `/pedidos/1000/`. Uma rota sem a barra final pode não ser localizada.
* Confira se o nome do módulo/ação está escrito corretamente.

## 🈶 Acentos chegam quebrados

Toda troca de dados deve ser feita em **JSON com charset UTF-8**. Se caracteres acentuados aparecem corrompidos, garanta que sua requisição envia e lê os dados em UTF-8.

Veja os padrões esperados em [Considerações Gerais](/funcionamento/consideracoes-gerais.md).

## 📄 Recebo 422 (falha de validação)

O código **422** indica que os dados enviados não passaram na validação. O corpo da resposta traz o campo **`Mensagem`** com o motivo (por exemplo, um campo obrigatório não preenchido). Ajuste os dados conforme a indicação e reenvie.

## 🔔 Meu webhook não está recebendo notificações

* **Firewall:** garanta que o IP `177.136.232.132` está na lista branca do seu servidor.
* **UserAgent:** garanta que o UserAgent `Toplojas (+https://www.toplojas.com.br/)` não está sendo bloqueado.
* **Resposta:** seu endpoint precisa responder **HTTP 200**; qualquer outro código é interpretado como falha. O sistema tenta reenviar até **3 vezes**, a cada **10 minutos**.
* **SSL:** a URL do webhook precisa ter **SSL** e aceitar **POST** em **JSON**.

Detalhes completos em [Webhook](/funcionamento/webhook.md).

{% hint style="info" %}
Não encontrou seu problema aqui? Consulte as [Perguntas Frequentes (FAQ)](/funcionamento/faq.md) ou teste a requisição no [Simulador Online](/funcionamento/utilizando-o-simulador-online.md) para comparar com o esperado.
{% endhint %}