Guia de Integração da API

Bem-vindo à API CorpX. Este guia foi escrito para equipes parceiras que estão integrando com as APIs /v1 e webhooks. Ele complementa a documentação técnica e foca nas informações necessárias para começar a operar em produção.

URLs Base

Ambiente	URL Base	Observações
dev (sandbox)	—	Temporariamente desativado. O ambiente de sandbox será reativado em breve. Entre em contato com o suporte para mais informações.
prd	https://tenant.api.corpx.com	Produção, monitorado 24/7

A URL de produção e as credenciais OAuth são fornecidas durante o onboarding. Substitua os placeholders nos exemplos pelos valores atribuídos ao seu tenant.

Autenticação

Os parceiros se autenticam diretamente no nosso Identity Provider. Dois fluxos são suportados:

• Client Credentials – integrações machine-to-machine. Use o client id/secret emitido pela CorpX e solicite tokens no endpoint de token.
• Authorization Code – fluxos baseados em navegador. A CorpX provisiona as redirect URIs e retorna o authorization code para sua aplicação.

Inclua o access token em todas as chamadas:

Authorization: Bearer <access_token>

Os tokens contêm o contexto do tenant e as roles necessárias, portanto nenhum header adicional é necessário para identificação.

Cada credencial tem escopos que delimitam as rotas que ela alcança (e, opcionalmente, as contas). Se a credencial não tiver o escopo da rota, a resposta é 403 insufficient_scope nomeando o que falta. Os escopos que movimentam dinheiro (pix_out.create, ted.create, internal_transfer.create, boleto_payment.create, refund.create, med.decide) são emitidos pela CorpX; os demais o próprio tenant manager cria no painel. Ver o Guia de Autenticação.

Headers Obrigatórios

Header	Quando	Descrição
X-Tenant-Id	Em toda chamada, exceto /v1/health	Identifica o tenant em cargas de trabalho multi-tenant. Obrigatório pelo API Gateway e WAF.
Idempotency-Key	Todas as operações POST/PUT/PATCH	Único por requisição. A API CorpX armazena a resposta no DynamoDB e retorna HTTP 409 se o payload diferir.
Content-Type	POST/PUT/PATCH	Sempre application/json.

Comportamento de Idempotência

• Idempotency-Key é obrigatório em endpoints mutáveis (/v1/accounts/{accountId}/pix/out, /v1/accounts/{accountId}/pix/out/refund, etc.).
• As chaves expiram após 24 horas.
• Uma segunda requisição com a mesma chave e payload idêntico retorna HTTP 200/202 com o body em cache.
• Uma segunda requisição com a mesma chave e payload diferente retorna HTTP 409 idempotency_conflict.

Datas e horários

Os campos de data/hora seguem ISO 8601 / RFC 3339 e sempre trazem o fuso explícito — leia o offset, não assuma. Há dois casos:

• UTC (Z) — webhooks (occurredAt e campos dentro de data) e os timestamps "do nosso lado" nas respostas REST (createdAt, updatedAt, completedAt, reconciledAt, fetchedAt, saldo, QR createdAt/expiresAt/ paidAt).
• Horário de Brasília (-03:00) — o horário da transação no extrato e nos lookups de transação: campo timestamp (extrato//pix/transactions) e occurredAt (/pix/payments/lookup, boleto), incluindo fee.occurredAt. O dia-calendário do filtro startDate/endDate também é BRT.

Para requisições que pedem instante (ex.: expirationDate em QR dinâmico), use RFC 3339 com fuso explícito (Z ou offset). Detalhes: página Webhooks.

Matriz de Autorização

O sistema avalia a combinação (subject, action, resource, tenant). Ações expostas para parceiros:

Tipo de Recurso	Exemplo de Resource Key	Ações
account	account:123456	read, pix_send, pix_qr_create, pix_qr_static_create, pix_qr_due_date_create, pix_qr_capture, pix_qr_cancel, pix_qr_read, pix_refund, pix_invoice_read
account_holder	account-holder:123456	pix_key_list, pix_key_preview, pix_key_create, pix_key_delete, internal_transfer_create, ted_transfer_create

Decisões negadas retornam HTTP 403 forbidden. Entre em contato com o suporte da CorpX se precisar de novas ações ou roles.

Catálogo de Erros

Todas as respostas utilizam o envelope documentado em errors.md. Destaques:

• 400 missing_headers → header ausente ou malformado.
• 401 invalid_signature → falha HMAC na ingestão de webhook.
• 409 idempotency_conflict → conflito de idempotência.
• 429 rate_limit → burst padrão de 100 rps, sustentado 6.000 rph por tenant.
• 429 partner_rate_limited → o liquidante recusou a chamada por excesso de requisições. Não é limite da sua conta nem da sua cota; repita com exponential backoff.
• 5xx partner_error → API CorpX indisponível ou falha do parceiro. Recomendamos implementar retries (até três vezes) com exponential backoff.

Portal do Integrador

Use o Portal do Integrador para operações administrativas e monitoramento:

• Link: https://backoffice.api.corpx.com
• Funcionalidades: dashboard com dados da conta, saldos disponível/bloqueado/total, transações recentes e extrato.
• Webhooks: configuração e manutenção de URLs de entrega.

Webhooks

Eventos Disponíveis

• GET /v1/webhooks/events - Listar tipos de eventos disponíveis

Saída (API CorpX → Tenant)

• Headers de entrega: X-Webhook-Event, X-Webhook-ID, X-Webhook-Tenant, Authorization, Idempotency-Key.
• IP Whitelist: 34.138.140.223, 34.138.161.100, 35.231.250.193, 35.196.71.29, 34.138.56.192.
• Retries: exponential backoff (até 6 tentativas) e DLQ para replay manual.
• Retry: Use POST /v1/webhooks/{subscriptionId}/deliveries/{deliveryId}/retry para reenviar uma entrega que falhou.
• Tipos de autenticação suportados: HMAC, API_KEY, BASIC, BEARER, IP_WHITELIST.

Checklist de Testes

1. Autenticação: Solicite suas credenciais de produção e obtenha seu primeiro token OAuth2.
2. Recebimento (QR Codes): Gere um QR code dinâmico e verifique seu status usando os exemplos em examples.md.
3. Pagamento (Cashout): Realize uma transferência PIX out usando uma chave de teste.
4. Gestão de Conta: Consulte o saldo e obtenha o extrato de transações recentes.
5. Chaves PIX: Liste, consulte e cadastre chaves PIX para o titular da conta.
6. Webhooks: Valide o recebimento de notificações e use o replay quando necessário.
7. MED: Liste infrações e disputas abertas para sua conta.

Suporte e Contatos

• Canal Slack: Canal privado por cliente — solicite acesso à equipe CorpX durante o onboarding.
• E-mail: api@corpx.com