CENTRAL DE AJUDA

Central de Ajuda

O que vale para todas as rotas: como se autenticar, idempotência, erros e como migrar de outra provedora.

Autenticação e permissões

Use o token de 1 hora do /oauth/token em Authorization: Bearer. Peça outro quando faltar pouco ou ao receber 401. A chave sk_ direta no Bearer também funciona. A chave define o que o token pode fazer: o campo scope do pedido é ignorado.

Escopo	Permissão da sua chave	Rotas
`account.read`	`balance:read`	GET /accounts/balances
`transactions.read`	`transactions:read`	GET /accounts/transactions, GET /accounts/transactions/{id}/details
`pix.read / cob.read`	`pix:read`	GET /accounts/keys, GET /pix/payments/*, GET /cob, GET /cob/{txid}, GET /pix, GET /pix/{endToEndId}
`pix.write`	`pix:send`	POST /pix/payments/dict, POST /pix/payments/qrc
`cob.write`	`pix:write`	PUT /cob/{txid}, POST /cob
`internal-transfer.write`	`transfers:write`	POST /internal-transfers
`internal-transfer.read`	`transactions:read`	GET /internal-transfers/{endToEndId}, GET /internal-transfers/idempotencyKey/{key}

Certificado de cliente (mTLS): opcional por padrão. Se o seu banco ligou a trava para a sua conta, a chamada precisa dele (403 certificate_required sem ele).

O que este banco não oferece

Se você já integra com outra API no padrão ONZ, estas rotas existem lá e NÃO existem aqui. Chamá-las devolve 501 com error not_supported (e uma mensagem), nunca um 404: o banco não oferece o recurso.

Recurso	Rotas
`TED`	POST /ted, GET /ted/{id}, GET /ted/idempotencyKey/{key}
`Pix por dados bancários (manual)`	POST /pix/payments/manu
`Cobrança Pix com vencimento, lotes e locations`	/cobv, /lotecobv, /loc, /loc/{id}/txid
`Pix Automático (recorrência)`	/rec, /solicrec, /cobr, /locrec, /webhookrec, /webhookcobr
`Aviso por chave Pix (use os webhooks por tipo)`	/webhook, /webhook/{chave}
`Criar ou apagar chave Pix, desafio de chave`	POST /accounts/keys, DELETE /accounts/keys/{key}, POST /accounts/keys/challenge
`Extrato consolidado da conta do banco`	POST /accounts/consolidated-statement, POST /accounts/consolidated-hourly-statement
`Estatísticas de pessoa e de chave`	GET /statistics/person/{document}, GET /statistics/key/{key}
`Abertura de contas de terceiros (BaaS) e consignado`	/accounts/{id}, /onboarding, /econsigado/*

O seu extrato é o da sua conta: GET /accounts/transactions. Cada cliente do banco enxerga só a própria conta.

Outras funções da sua conta

Além das rotas desta página, o seu banco liberou estas funções na API v1. O mesmo token (Authorization: Bearer) vale nelas; a referência completa de cada uma está na documentação da v1.

Função	Rotas	Permissão da chave
`Transferência entre contas (também na v2: /internal-transfers)`	POST /v1/transfers	transfers:write
`Links de pagamento`	POST /v1/payment-links, GET /v1/payment-links	pix:write
`Split de recebimentos`	GET/PUT /v1/split, GET /v1/split/lookup, GET /v1/split/history	split:read, split:write
`Split para chave Pix`	PUT /v1/split/pix	split:write
`Folha de pagamento`	/v1/payroll/*	payroll:read, payroll:write
`Emitir boleto de cobrança`	POST /v1/boleto/charges	boleto:write

Referência completa: /docs (API v1).

Idempotência

Todo pagamento exige o cabeçalho x-idempotency-key (1 a 50 letras e números). Repetir a mesma chave devolve o MESMO pagamento, sem pagar duas vezes. Se a conexão cair e você não souber se o pedido chegou, repita com a mesma chave ou consulte GET /pix/payments/idempotencyKey/{chave}.

Erros

{
  "type": "onz-0008",
  "title": "Invalid request",
  "status": 400,
  "detail": "Saldo insuficiente",
  "instance": "/api/v2/pix/payments/dict",
  "statusCode": 400,
  "error": "insufficient_funds",
  "message": "Saldo insuficiente"
}

type	title	Quando
`onz-0001`	Invalid credentials	clientId ou clientSecret inválidos (401)
`onz-0002`	Invalid params	Campo faltando ou inválido; a mensagem diz qual (400)
`onz-0003`	Invalid token	Token ausente, inválido, expirado ou chave revogada (401)
`onz-0004`	Internal server error	Falha nossa; guarde o ref (500)
`onz-0005`	Server shutting down	Sistema ocupado: repita em instantes (503)
`onz-0006`	Invalid token role	A chave não tem a permissão da rota, o banco desligou a função ou falta o certificado mTLS (403)
`onz-0007`	Invalid pix entry	Chave Pix inválida (400)
`onz-0008`	Invalid request	Uma regra de negócio recusou (saldo, limite, destinatário…), limite de chamadas ou rota que o banco não tem. Nada foi debitado (400, 429, 501)
`onz-0009`	Pix not found	Pagamento, cobrança ou transferência não encontrados nesta conta (404)
`onz-0010`	Invalid QR code	QR Code inválido ou com valor diferente do informado (400)
`onz-0011`	Invalid idempotency key	Faltou ou é inválida a x-idempotency-key (400)
`onz-0012`	Webhook not found	Webhook não encontrado (404)

O corpo do erro traz type (o código onz-XXXX da tabela), title, status, detail e instance, e também statusCode, error (o código detalhado, como insufficient_funds) e message. Decida pelo código HTTP e pelo type; o campo error diz o motivo exato. Em erro 5xx vem também um ref: guarde-o ao falar com o suporte.

Migrando de outra provedora

Troque a URL base por https://SEU-BANCO/api/v2.
Troque clientId e clientSecret pelos da sua chave (veja Autenticação).
POST /pix/payments/dict e /qrc respondem 202 com { endToEndId, eventDate, id, payment, type }. O endToEndId pode vir nulo até o Pix seguir; consulte pela chave de idempotência.
GET /pix/payments/{endToEndId} devolve { data: {...} }. Também aceita o transactionId.
O campo id é um número estável, mas não serve para consultar: use endToEndId ou transactionId.
Os códigos de erro (type onz-XXXX) e os nomes dos escopos que o token devolve (pix.write, cob.write, account.read…) são os mesmos; ao criar a chave no painel, as permissões têm nomes próprios (pix:send, pix:write…): veja a tabela de permissões.

Integrando com IA

Toda esta documentação, em texto puro, está em /docs/v2/llms.txt (acrescente ?lang=en para inglês). Cole o conteúdo no seu assistente e peça o código.