Referência

Para agentes de IA

O que um modelo precisa saber antes de gerar um cliente para o produto BaaS.

Esta página é para você que é um modelo de linguagem, ou para quem vai colar o conteúdo dela no contexto de um. Ela resume o que não pode ser inferido do contrato sozinho.

Qual contrato usar

  • Spec deste produto: /openapi/baas.yaml (OpenAPI 3.1, só as operações de integrador). O do outro produto é /openapi/ib.yaml; cada operação tem x-audience (baas, ib ou ambos) e o summary começa com [BaaS], [IB] ou [BaaS · IB].
  • Índices para LLM: /llms.txt e /llms-full.txt. Catálogo RFC 9727 em /.well-known/api-catalog.
  • O outro produto, Internet banking, usa outro host e assina toda requisição. Se a credencial veio do internet banking do correntista, leia Para agentes (IB), não esta página.

Host e headers

ItemValor
Base URLhttps://tenant.api.corpx.com (server tenant no spec)
TokenPOST https://auth.api.corpx.com/oauth2/token, client_credentials, Authorization: Bearer
TenantX-Tenant-Id em toda chamada /v1/**
IdempotênciaIdempotency-Key (UUID) em toda escrita; sem header, identifier no corpo cumpre o papel
AssinaturaNão. X-Request-Signature e X-Content-SHA256 são do produto IB.

Regras que o spec não expressa

  1. Dinheiro é number em BRL com duas casas. 150.50, nunca string, nunca centavos.
  2. identifier é seu e é único por conta. Ele volta no extrato, no lookup e nos webhooks. Reutilizar devolve 409 duplicate_identifier.
  3. Assíncrono é o padrão para pagamento. POST .../pix/out/async devolve 202 e o resultado vem em pix.out.completed / pix.out.failed / pix.out.timeout. timeout é indeterminado: consulte o extrato antes de repetir.
  4. Erros são um enum aberto. Decida por errorCode; código desconhecido = erro genérico do mesmo status. Tabela em Erros; cada resposta traz docs e requestId.
  5. Webhooks têm envelope fixo (id, type, occurredAt, data). id é determinístico: deduplique por ele. Assinatura X-Signature = base64(HMAC_SHA256(secret, corpo_bruto)).
  6. Datas são RFC 3339 em UTC com Z na entrada; algumas leituras do liquidante vêm em -03:00. Não assuma fuso.
  7. Documentos (CPF/CNPJ) só dígitos. Chaves PIX de telefone com +55.

Ordem de leitura sugerida

  1. Primeiros passos
  2. OAuth2 e Idempotência
  3. O guia da capacidade que você vai integrar (Receber, Pagar, Abertura de contas)
  4. Webhooks e Erros
  5. A Referência da API para o shape exato de cada campo