> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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](/ib/guias/comece-aqui/primeiros-passos) — este texto não é o onboarding dele.

## 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:

```http
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](/baas/guias/autenticacao/oauth2).

## 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 guarda a resposta por 24 horas 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).
  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](/baas/guias/conta/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.

A listagem `GET /v1/tenant/accounts` e a busca `GET /v1/tenant/accounts/search` não passam por esta matriz: são rotas do tenant e exigem o escopo de credencial `read`. O `read` da tabela acima é outra coisa — é a ação sobre uma conta já conhecida.

## 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](/baas/guias/pagar/consulta-dict), 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](/baas/guias/pagar/consulta-dict).
* 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. **Segurança**: Siga as [recomendações de segurança](/baas/guias/autenticacao/recomendacoes-de-seguranca): contexto do usuário nas saídas, allowlist de IP e credencial com o menor escopo.
3. **Recebimento (QR Codes)**: Gere um QR code dinâmico e verifique seu status usando os exemplos em `examples.md`.
4. **Pagamento (Cashout)**: Realize uma transferência PIX `out` usando uma chave de teste.
5. **Gestão de Conta**: Consulte o saldo e obtenha o extrato de transações recentes.
6. **Chaves PIX**: Liste, consulte e cadastre chaves PIX para o titular da conta.
7. **Webhooks**: Valide o recebimento de notificações e use o replay quando necessário.
8. **MED**: Liste infrações e disputas abertas para sua conta.
9. **Status de PIX**: logo depois de um PIX `out` assíncrono, chame `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...&waitForFinalStatus=10` e confira que a resposta traz o status final, ou o último estado se o prazo acabar. Use timeout de cliente de pelo menos 20 s.

## Suporte e Contatos

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