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
`pix.read / cob.read`	`pix:read`	GET /accounts/keys, GET /pix/payments/*, GET /cob/{txid}
`pix.write`	`pix:send`	POST /pix/payments/dict
`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).

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

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://bank.granseuk.com/api/v2.
Troque clientId e clientSecret pelos da sua chave (veja Autenticação).
POST /pix/payments/dict responde 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.

O que ainda não existe

Criação de chave Pix por API (as chaves são criadas no painel) e devolução de Pix recebido.
Boletos (/billets) e TED neste formato.
Cobrança com vencimento (/cobv), recorrente (/cobr) e Pix Automático.
Chave de sandbox (sk_sbx_) não troca token; use a v1 para testar sem dinheiro real.

Rotas deste padrão que ainda não existem respondem 501 not_supported, com a explicação (por exemplo, POST /accounts/keys).

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.