Receber um evento de sandbox
Recebe a notificação de pagamento do ambiente de teste e credita o livro de teste. O caminho, e não o parâmetro, decide qual banco recebe.
Autenticação
A chamada é autenticada pela assinatura do corpo cru, conferida antes de qualquer leitura do conteúdo.
Esta rota não exige escopo nomeado — o que não quer dizer que ela seja aberta: sem a credencial acima ela recusa.
Não há sessão nem chave de API aqui. A chamada é autenticada pela ASSINATURA do corpo cru, conferida antes de qualquer leitura do conteúdo; assinatura inválida recusa com 401.
Parâmetros
Caminho
| Nome | Tipo | Descrição |
|---|---|---|
gatewayobrigatório | texto | Qual gateway está entregando o evento. Ele não escolhe o banco de destino: o caminho já escolheu. |
Respostas
200 · sucesso
{
"outcome": "exemplo"
}400 · requisição inválida
O corpo não tem a forma esperada, ou falta o identificador do evento.
401 · não autenticado
A assinatura do corpo não confere.
404 · não encontrado
O gateway não é conhecido.
503 · indisponível
O banco de sandbox não está disponível.
Erros desta rota
| Status | Código | Quando | O que fazer |
|---|---|---|---|
| 400 | SANDBOX_WEBHOOK_INVALID_BODY | A assinatura conferiu e o corpo não tem a forma que este gateway entrega. O conteúdo só é lido depois que a assinatura passa, então chegar aqui já significa que a origem é legítima e o formato é que está errado. | Confira o corpo contra o formato do gateway que você está simulando. Reenviar o mesmo corpo devolve o mesmo 400, e nada foi creditado no livro de teste. |
| 400 | SANDBOX_WEBHOOK_MISSING_EVENT_ID | O corpo veio sem o identificador do evento. Ele é o que impede a mesma notificação entregue duas vezes de creditar duas vezes, e sem ele não há como distinguir uma reentrega de um evento novo. | Inclua o identificador do evento e reenvie. Use o MESMO valor ao simular uma reentrega, e um valor novo para um evento novo. |
| 401 | SANDBOX_WEBHOOK_UNAUTHENTIC | A assinatura do corpo cru não confere. A recusa acontece antes de qualquer leitura do conteúdo, então nada do que estava no corpo foi processado nem registrado. | Assine o corpo CRU, byte a byte, com o segredo do ambiente de teste, sem reserializar o JSON antes de assinar. Reenviar sem corrigir a assinatura devolve sempre o mesmo 401. |
| 404 | SANDBOX_WEBHOOK_GATEWAY_UNKNOWN | O gateway nomeado no caminho não é um dos que esta instalação conhece. | Corrija o segmento do caminho. Repetir com o mesmo nome devolve o mesmo 404. |
| 503 | SANDBOX_WEBHOOK_DATABASE_ABSENT | Esta instalação não tem banco de teste provisionado, então não há livro de teste onde creditar o evento. É do nosso lado, e nada no que você envia causou isso. | Reporte a ocorrência a quem opera a instalação. Repetir a entrega não muda o resultado enquanto o ambiente não existir. |
Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.