Convenções da API

Requisições

• Corpo e respostas em JSON (Content-Type: application/json).
• Cabeçalhos de autenticação em todas as rotas, menos a de token: veja Autenticação.
• Valores em reais com ponto decimal (150.00) e datas no formato AAAA-MM-DD.

Respostas

A maior parte das rotas responde neste formato:

{
  "code": 200,
  "success": true,
  "data": { "...": "..." },
  "message": "Operação realizada com sucesso."
}

Algumas rotas usam outro envelope (por exemplo, { "data", "meta" } nas listas paginadas). O formato de cada rota de Pix está em Pix pela API.

Erros

Código	Significado	O que fazer
401	Token ausente, expirado ou inválido	Peça um novo token
403	O usuário não tem acesso à conta do cabeçalho account, ou não tem a permissão da rota. Sem a permissão, o corpo traz required_permissions (ex.: ["send_pix"]): basta ter uma delas	Confira o id da conta e as permissões do usuário (permissions no login)
404	Registro não existe ou é de outra conta	Confira o id
422	Dados inválidos ou regra de negócio recusada	Leia message e, quando houver, os campos em data ou errors
500	Erro interno ou falha no banco parceiro	Tente de novo mais tarde. Em Pix e cobranças, use Idempotency-Key para não duplicar

Exemplo de 422 na criação de cobrança (os erros por campo vêm em errors):

{
  "message": "O campo data de vencimento é obrigatório.",
  "errors": { "due_date": ["O campo data de vencimento é obrigatório."] }
}

Em outras rotas, os erros por campo vêm em data, com "success": false.

Evitar operação duplicada

As rotas que enviam Pix e a criação de cobrança aceitam o cabeçalho opcional . Se a conexão cair e você repetir a mesma requisição com a mesma chave, a operação é feita uma vez só. Detalhes em Pix pela API.

Principais rotas

Recurso	Rotas	Referência
Clientes	GET POST /billing/clients, GET PUT DELETE /billing/clients/{id}	Abaixo
Cobranças	GET POST /billing/charges, GET PUT DELETE /billing/charges/{id}, POST /billing/charges/{id}/cancel, POST /billing/charges/{id}/webhook	Exemplos
Pix, chaves e transferências Pix	/banking/pix/*	Pix pela API
Pagamento de boletos	/banking/boleto/payments*	Pix pela API
Avisos de pagamento	GET /access/webhook-notifications	Webhooks

Criar cobrança: campos principais

POST /billing/charges

Campo	Obrigatório	Regras
payment_method	Sim	PIX, BOLETO ou BOLEPIX
amount	Sim	Valor em reais, a partir de 0.01, dentro dos limites da conta
due_date	Boleto e BolePix	AAAA-MM-DD, hoje ou depois. No Pix é opcional
client_id	Não	Cliente já cadastrado em /billing/clients
name, email, document	Boleto e BolePix sem client_id	Dados do cliente informados na hora. No Pix são opcionais
description	Não	Até 500 caracteres
webhook	Não	URL que recebe o aviso de pagamento (Webhooks)

Veja também

• Exemplos de código
• Webhooks