Guia do tenant BaaS

Bem-vindo à API CorpX BaaS. Este guia é para o tenant que opera em https://tenant.api.corpx.com. Quem recebeu credencial no internet banking deve usar a seção Internet banking — este texto não é o onboarding dele.

URLs Base

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) são emitidos pela CorpX; os demais o próprio tenant manager cria no painel. Ver o Guia de Autenticação.

Headers Obrigatórios

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:

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.
• 429 dict_lookup_limit_exceeded → a cota de consulta de chave PIX da sua conta fechou. Não repita a chamada: veja qual janela estourou e leia Consultas de chave PIX, que descreve como o consumo é medido e acompanhado.
• 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.
• Balde de consultas PIX: o seu consumo de DICT por conta e por janela de tempo, e as consultas recusadas por limite. Ver Consultas de chave PIX.
• 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 (assinatura em X-Signature) e NONE.

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