Clientes

Cadastre quem paga você e ligue cada cobrança a um cliente.

Um cliente é quem paga as suas cobranças. Ligar a cobrança a ele (customerId) deixa o extrato e o painel mais claros e permite ver tudo o que aquela pessoa pagou. E-mail, celular e CPF/CNPJ ficam criptografados e só voltam para a sua conta.

​

Criar um cliente

POST /v1/customers · escopo customers:write

name · string · required

2 a 120 caracteres.

email · string | null

E-mail válido.

phone · string | null

Celular com DDD (com ou sem +55), só números ou formatado.

document · string | null

CPF ou CNPJ válido, com ou sem pontuação.

curl -X POST https://bukio-backend-production.up.railway.app/v1/customers \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ana Souza", "email": "[e-mail]", "phone": "11999998888", "document": "123.456.789-09" }'

{
  "id": "0d6c1a7e-5b7f-4f3e-9b2a-1c2d3e4f5a6b",
  "name": "Ana Souza",
  "email": "[e-mail]",
  "phone": "11999998888",
  "document": "12345678909",
  "createdAt": "2026-10-08T15:00:00.000Z"
}

​

Listar, ver, alterar e excluir

Método	Rota	Escopo	O que faz
GET	/v1/customers	customers:read	todos os clientes ativos (lista simples, sem cursor)
GET	/v1/customers/{id}	customers:read	um cliente
PATCH	/v1/customers/{id}	customers:write	muda name, email, phone ou document; null limpa o campo
DELETE	/v1/customers/{id}	customers:write	esconde o cliente ({ "removed": true }); as cobranças antigas mantêm o nome dele

​

Clientes que vêm do link de pagamento

Quando um link de pagamento pede dados (customerFields), quem paga vira cliente automaticamente e a cobrança já nasce ligada a ele.