Checklist prático para falhas frequentes na integração. Paths e scopes: Mapa de endpoints.
Checklist do produto BaaS. Separação plataforma vs conta: Sobre o BaaS. Mapa de rotas: Mapa de endpoints.
| Sintoma | Verificar |
|---|
Invalid request signature | hmac_secret do contexto correto (plataforma vs conta) |
| PATH completo com /api/v2, sem host, sem / final |
| QUERY idêntica à URL |
| BODY byte a byte ([] em GET assinados) |
| timestamp e nonce iguais na mensagem e nos headers X-* |
| Token não expirado |
| Sintoma | Verificar |
|---|
404 Customer not found em PF/PJ | POST + PATCH da proposta concluídos: pacote cadastral com password e OTP (email_verification_code, phone_verification_code) |
| Reprovação em compliance | email_verification_code e phone_verification_code no PATCH da proposta |
422 em PF/PJ | files[] no PATCH de PF/PJ, não na proposta |
Invalid documents from company type | company_type bate com tipos em files[] (PJ) |
| OTP expirado | resend-email ou resend-sms na proposta; GET antes do PATCH |
Guia: Onboarding.
| Sintoma | Verificar |
|---|
| Pagamento por chave falha | Consultar DICT (POST …/key-managements/consult) antes de pagar |
| Dados do recebedor rejeitados | Não alterar campos retornados pela consulta DICT |
| Pagamento duplicado | Novo idempotency_key a cada intenção de pagamento |
| QR cash-in falha | Chave Pix ativa na conta antes de gerar cobrança |
| Sintoma | Verificar |
|---|
422 na confirmação | Seguir wizard: consultar → revisar → (atualizar) → confirmar |
| Sessão expirada | Guardar reference da consulta; reiniciar se expirar |
| Fora da janela | Respeitar canPayToday, minPaymentTime, maxPaymentTime na revisão |
| Sintoma | Verificar |
|---|
| Sem callback de credenciais | Webhook da plataforma (seller-webhooks) com AccountCredentials + created |
| Sem evento Pix na conta | Webhook da conta (/baas/webhooks) com evento correto em events[] |
| Duplicidade no receptor | Idempotência: event_id (conta) ou account_uuid + evento (plataforma) |
403 no cadastro | Um registro seller por entity + event_type; scopes baas.seller-webhooks.* ou baas.webhooks.* |
| Sintoma | Verificar |
|---|
| 401 em qualquer rota | Token ausente, expirado ou malformado. Refaça login ou use refresh. |
| 403 | Scope ausente no JWT. O campo scope do login é uma string com permissões separadas por espaço. Após alterar scopes, é necessário novo login. |
| Login 400/401 | Basic Auth (client_id:client_secret), grant_type=client_credentials, host de ambiente correto. |
Lista de scopes de sandbox: Chaves de teste.
| Sintoma | Verificar |
|---|
| 403 em saldo / extrato / dados / chaves | Scopes contas.saldo.read, contas.extrato.read, contas.read, contas.chaves.read. |
Extrato 422 com violacoes | Query incompleta: data_inicio, data_fim, offset e limit são obrigatórios. Prefira YYYY-MM-DD. offset começa em 0. |
| Extrato “vazio” | Intervalo sem movimentos processados; ajuste datas/tipo (saida | entrada). |
| Formato do extrato | Resposta é lista indexada ("0", "1", …) + correlationId — não um array items[]. Ver Extrato. |
| Saldo | Campo blocked_balance faz parte do contrato. Ver Saldo. |
| Sintoma | Verificar |
|---|
| 403 | Scopes cob.read / cob.write ou webhooks.read / webhooks.write. |
| Cobrança 400 “inválida” | txid inexistente ou fora do contexto da conta do token. |
| Webhook sem POST (recebimento) | Cadastre eventos: ["recebimento"] na mesma chave do QR. Endpoint HTTPS responder 2xx. Ver Webhook de recebimento. |
| Webhook sem POST (pagamento) | Cadastre eventos: ["pagamento"] e/ou ["pagamento-falha"] em qualquer chave da conta pagadora. Ver Webhook de pagamento. |
| Efeito duplicado no sistema interno | Retentativas HTTP reenviam o mesmo evento. Implemente idempotência no receptor (endToEndId antes de responder 2xx). Ver Recebimento e Pagamento. |
| Sintoma | Verificar |
|---|
Pagamento fica em status: "0" | Falta confirmar com id + valor. |
| 403 | Scopes pix.read / pix.write. |
| Pagamento efetivado sem webhook | Cadastre eventos: ["pagamento"] em uma chave da conta pagadora. Para falha: ["pagamento-falha"]. Alternativa: listar / consultar. |
| Sintoma | Verificar |
|---|
| 429 | Respeite Retry-After ou backoff. Evite polling agressivo. Ver Rate limits. |
Muitas rotas devolvem erros no formato:
{
"type": "https://pix.bcb.gov.br/api/v2/error/OperacaoInvalida",
"title": "...",
"status": 422,
"detail": "...",
"violacoes": {}
}
Use status e violacoes (quando existir) para diagnosticar validação. Detalhe HTTP: Códigos de erro.
Respostas de sucesso costumam incluir correlationId. Guarde-o ao abrir chamado de suporte.
