Guia de Debugging

Quick Reference

WhatDebugar problemas de integração com a API A55 de forma eficaz

WhyReduza o tempo de resolução quando algo der errado

Reading Time10 min

DifficultyIntermediate

PrerequisitesIntegração sandbox funcional

Usando request_id para suporte

Toda resposta da API A55 inclui um request_id no corpo da resposta. Esse identificador permite que o suporte da A55 rastreie sua requisição exata através do pipeline de processamento.

{
  "uuid": "chg_abc123...",
  "status": "declined",
  "request_id": "req_7f3a2b1c-4d5e-6f78-9a0b-cdef12345678"
}

Ao entrar em contato com tech.services@a55.tech, sempre inclua:

O request_id
Timestamp da requisição (UTC)
O endpoint e método HTTP
O código de status HTTP recebido

Códigos de Status HTTP

Código	Significado	Ação
`200`	Sucesso	Processe a resposta
`201`	Criado	Recurso criado com sucesso
`400`	Requisição Inválida	Corrija o corpo da requisição — verifique campos obrigatórios e formatos
`401`	Não Autorizado	Token expirado ou inválido — reautentique
`403`	Proibido	Suas credenciais não têm permissão para este recurso
`404`	Não Encontrado	Verifique a URL e o UUID do recurso
`409`	Conflito	Chave de idempotência duplicada com payload diferente
`422`	Entidade Não Processável	Validação falhou — veja `error.details` para erros por campo
`429`	Muitas Requisições	Rate limit atingido — aguarde e retente com backoff
`500`	Erro Interno do Servidor	Problema do lado da A55 — retente com backoff exponencial
`502/503`	Serviço Indisponível	Indisponibilidade temporária — retente com backoff exponencial

Lendo Respostas de Erro

A A55 retorna respostas de erro estruturadas:

{
  "error": {
    "code": "INVALID_CARD_NUMBER",
    "message": "The card number failed Luhn validation",
    "details": [
      {
        "field": "card.number",
        "reason": "Must be a valid card number (Luhn check failed)"
      }
    ]
  },
  "request_id": "req_7f3a2b1c..."
}

Campo	Descrição
`error.code`	Código de erro legível por máquina — use na lógica de tratamento de erros
`error.message`	Descrição legível por humanos
`error.details`	Array de erros de validação por campo (quando aplicável)

Testes no Sandbox

O ambiente sandbox reproduz o comportamento de produção:

Use cartões de teste da referência de cartões de teste
Teste todos os cenários de recusa que seu código trata
Webhooks disparam no sandbox da mesma forma que em produção
Os rate limits são os mesmos (100 req/min)

# Quick sandbox health check
curl -s -o /dev/null -w "%{http_code}" \
  "https://sandbox.api.a55.tech/api/v1/health/"
# Expected: 200

Debugging de Webhooks

Desenvolvimento local com ngrok

# Start ngrok tunnel
ngrok http 8080

# Use the HTTPS URL as your webhook_url
# https://abc123.ngrok.io/webhooks/a55

Usando webhook.site

Acesse webhook.site
Copie sua URL única
Defina-a como webhook_url na criação da cobrança
Inspecione os payloads recebidos no navegador

Verificando a entrega

Se os webhooks não estão chegando:

Confirme que seu endpoint retorna HTTP 200 em até 5 segundos
Verifique se seu endpoint é acessível publicamente (não está atrás de VPN/firewall)
Verifique se a validação da assinatura HMAC não está rejeitando payloads válidos
Verifique as retentativas da A55 — webhooks são retentados até 5 vezes com backoff exponencial

Transições de Status da Cobrança

Se uma cobrança está presa em um status inesperado:

# Poll charge status
curl -s "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/?charge_uuid=${CHARGE_UUID}" \
  -H "Authorization: Bearer ${A55_ACCESS_TOKEN}" | python3 -m json.tool

Fluxos de status comuns:

Fluxo	Status
Cobrança bem-sucedida	`pending` → `authorized` → `captured` → `settled`
Cobrança com captura automática	`pending` → `confirmed` → `settled`
Cobrança recusada	`pending` → `declined`
Cobrança reembolsada	`settled` → `refunded`
Desafio 3DS	`pending` → `awaiting_3ds` → `authorized` → `captured`

Flags de Debug do cURL

Saída detalhada (`-v`)

Mostra headers de requisição/resposta e handshake TLS:

curl -v -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
  -H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00", "currency": "BRL"}' 2>&1

Rastreamento completo (`--trace`)

Captura cada byte enviado e recebido:

curl --trace trace.log -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/" \
  -H "Authorization: Bearer ${A55_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00", "currency": "BRL"}'

# Review the trace
less trace.log

Tempo de resposta

curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\nHTTP: %{http_code}\n" \
  "https://sandbox.api.a55.tech/api/v1/health/"

Erros Comuns →Evite as 15 principais armadilhas de integração Rate Limiting →Trate respostas 429 corretamente Ciclo de Vida do Status →Entenda as transições de status da cobrança

Quick Reference

Usando request_id para suporte​

Códigos de Status HTTP​

Lendo Respostas de Erro​

Testes no Sandbox​

Debugging de Webhooks​

Desenvolvimento local com ngrok​

Usando webhook.site​

Verificando a entrega​

Transições de Status da Cobrança​

Flags de Debug do cURL​

Saída detalhada (-v)​

Rastreamento completo (--trace)​

Tempo de resposta​