Visão geral

38 endpoints, um formato de erro, uma autenticação. Com playground para testar aqui mesmo.

Base URL: https://bukio-backend-production.up.railway.app

Todos os endpoints ficam sob /v1 e exigem o cabeçalho de autenticação:

Authorization: Bearer bk_live_sua_chave

Cada página desta seção tem um playground. Cole a sua chave bk_live_ e dispare a requisição direto do navegador, sem sair da documentação. Lembre: não existe sandbox, então cobrança criada no playground é real.

​

Convenções

Dinheiro vai em centavos, inteiro

amount: 4990 é R$ 49,90. Todo campo de valor (amount, fee, total, available, blocked, mínimos) é um inteiro em centavos. Nunca decimal, nunca texto.

O prefixo do ID diz o que é

BKY- cobrança, LNK- link de pagamento, SAQ- e SAQ-API- saque, ENV- Pix enviado, EST- estorno, MED- devolução, TRF- transferência, TAR- tarifa, SUB- movimento de subconta, sacc_ subconta (nas rotas da subconta, o seu externalId também vale), UUID para cliente. Guarde o identificador inteiro.

Erro tem sempre a mesma forma

{ "error": { "code", "message", "details"? }, "requestId" }. Trate pelo code (estável); mostre a message (português). Lista completa em Erros.

Listagem pagina com cursor

?limit= (1 a 100, padrão 50) e ?cursor=. A resposta traz items e nextCursor (null = acabou). Do mais novo para o mais antigo. Links e clientes vêm em lista simples, sem cursor.

Idempotency-Key em tudo que move dinheiro

Obrigatória em cobrança, saque e nos movimentos de subconta (enviar, transferir, devolver): 8 a 128 caracteres, única por pedido. Repetir com os mesmos dados devolve o mesmo resultado; com dados diferentes, 422 IDEMPOTENCY_KEY_REUSED.

Data é sempre ISO 8601 em UTC

2026-10-08T15:04:12.318Z. Converta para o fuso de quem vê.

Só os campos documentados

Campo desconhecido no corpo responde 422 VALIDATION com details.fields. Corpo de até 256 KB. null limpa um campo onde a documentação diz que aceita.

​

O mapa

Grupo	Endpoints	Escopos
Saldo	saldo e prévia de tarifa	balance:read
Cobranças	criar, listar, consultar	payments:write (Pix), card:write (cartão), crypto:write (cripto), transactions:read
Links de pagamento	criar, listar, consultar, editar, excluir, cobranças do link	payments:write, transactions:read
Extrato	movimentações, uma movimentação, extrato resumido	transactions:read
Saques	pedir, listar, consultar	withdrawals:write, transactions:read
Subcontas	criar, listar, consultar, editar, excluir, movimentos, enviar da principal, transferir entre subcontas, devolver à principal, saque do cliente	subaccounts:write, withdrawals:write, transactions:read
Clientes	listar, consultar, criar, editar, excluir	customers:read, customers:write
MED	listar, consultar, responder	/meds/list, /meds/get, /meds/respond

​

Limites que valem lembrar

O quê	Valor
Chamadas por conta	100 por minuto, somando todas as rotas e chaves
Criar cobrança	100 por minuto
Saque	20 por minuto
Links de pagamento	60 criações ou edições por hora; 200 links por conta
Corpo	até 256 KB

Tabela completa em Limites de requisição.