Cobranças e clientes — /invoices e /billing (descontinuado)

WARNING

Prefira a API v1 para cadastro de clientes. As cobranças ainda não têm equivalente na v1 — use estes endpoints até que exista.

Todas 🔒 (Authorization: Bearer <token>) e operam sobre a conta ativa. Valores monetários em reais (decimal). search em cobranças por CPF/CNPJ dispara uma sincronização com o banco emissor.

Recursos duplicados: /invoices ≡ /billing/charges, /clients ≡ /billing/clients, /invoices_groups ≡ /billing/charge-groups.

---

Cobranças

GET /invoices · /billing/charges

Entrada (query, todos opcionais):

Campo	Tipo	Observação
search	string (≤100)	NSU, documento ou nome do cliente
status_id	int/lista	um ou vários separados por vírgula
payment_method	string/lista	PIX, BOLETO, BOLEPIX, CREDIT_CARD
client_id	int	existente
per_page	int 1–500	default 15
page	int	default 1
order_by	string	created_at, due_date, payment_date, id
order_dir	string	asc, desc
created_at_start/_end	YYYY-MM-DD
due_date_start/_end	YYYY-MM-DD
payment_date_start/_end	YYYY-MM-DD

Saída: 200. Em /billing/* e *v2*: { data: [cobranças], meta: {...}, ... }. Nas demais: coleção de cobranças. Cada item: { id, code, value, amount_paid, payment_date, status:{...}, description, payment_method, due_date, client:{id,name,email,document}, pix:{txid,qrcode,status,...}|null, boleto:{txid,barcode,digitableLine,status,...}|null, created_by, created_at }.

POST /invoices · /billing/charges

Cria a cobrança e gera Pix/Boleto/Bolepix/Cartão conforme payment_method.

Entrada (corpo JSON):

Campo	Tipo	Regras
value ou amount	number	obrigatório (um dos dois), ≥ 0.01
payment_method	string	obrigatório, enum: PIX, BOLETO, BOLEPIX, CREDIT_CARD
due_date	date	obrigatório, ≥ hoje
client_id	int	se informado, usa o cliente existente
name, email, document	string	obrigatórios se não enviar client_id (phone opcional) — cliente é criado
webhook	url	opcional — URL para os eventos desta cobrança
description	string ≤500	opcional
details, instructions	string	opcionais
amount_rate	number	opcional (juros/mora)
type_rate	string	ABSOLUTE ou PERCENTAGE
discount	number	opcional
days_discount	number	dias antes do vencimento; a data resultante não pode ser < hoje
type_discount	string	ABSOLUTE ou PERCENTAGE
tag / tag_id / establishment_id	int	opcional, existente
charge_group_id	int	opcional, existente
payment_plan_id	int	opcional
installments	int 1–120	opcional
address.{street,number,district,city,state,zipcode}	string	obrigatórios se payment_method = CREDIT_CARD
card.{card_number,brand,cvv,expiry_month,expiry_year,cardholder_name,document}	string	obrigatórios se CREDIT_CARD; brand ∈ visa,mastercard

Saída: 200 — a cobrança criada, com pix e/ou boleto embutidos. 400/422 em falha bancária ou validação (uma cobrança com status = failed é registrada).

GET /invoices/{id} · /billing/charges/{id}

Entrada: path id (id ou code da cobrança). Saída: 200, envelope data = a cobrança (com client, tag, pix, boleto, createdBy), message: "Detalhes da Cobrança". 404 se não existir.

PUT/PATCH /invoices/{id} · /billing/charges/{id}

Só cobranças pendentes. Regenera o Pix se o valor mudar; regera o PDF.

Entrada (corpo JSON, opcionais): value|amount (≥0.01), amount_rate, type_rate (ABSOLUTE/PERCENTAGE), discount (≥0), due_date (≥ hoje), description (≤500), details, instructions, webhook (url), payment_method (enum), tag_id.

Saída: 200, chave charge = cobrança atualizada, message: "Cobrança atualizada com sucesso!"404 se não existir; erro se não estiver pendente.

DELETE /invoices/{id} · /billing/charges/{id}

Entrada: path id. Saída: 200, data = a cobrança, message: "Cobrança apagado com sucesso!" (marca status = DELETED).

GET /billing/charges/{id}/download-pdf

Entrada: path id (id ou code). Saída: 200, Content-Type: application/pdf, Content-Disposition: attachment; filename="fatura_{id}.pdf". Erro 500 se falhar a geração.

POST /invoices/{id}/notify

Entrada: path id (id ou code). Saída: 200, data: { charge_id, email }, message: "Notificação enviada com sucesso!"400 se o cliente não tiver e-mail; 404 se a cobrança não existir.

POST /billing/charges/{id}/notify · POST /billing/charges/notify

Enfileira notificações multicanal. Com {id} na URL notifica uma cobrança; sem, use ids[]/id no corpo.

Entrada (corpo JSON):

Campo	Tipo	Regras
ids ou id	array/valor	ids ou codes (só na rota sem {id})
channels	array	obrigatório, ≥1, itens em email,whatsapp,sms
message	string ≤1000	opcional

Saída: 200, data: { count }, message: "Notificações enfileiradas com sucesso!"400 sem cobrança informada; 404 se nenhuma for encontrada.

GET /reports/invoices

Entrada (query): group_by (obrigatório, days|months), date_start (obrigatório, data), date_end (obrigatório, ≥ date_start). Saída: 200, data = linhas agregadas { reference_date, status_id, status:{id,title,description}, total_qtd, total_amount_paid, total_value }, message: "Relatório de cobranças gerado com sucesso."

POST /invoices/with-plan

Gera as parcelas de um plano de pagamento. Entrada (corpo JSON): payment_plan_id (obrigatório, da própria conta) + os mesmos campos de POST /invoices (value/amount, payment_method, due_date, client_id ou name+email+document+phone, tag, installments, ...). Saída: 201, data = array de cobranças geradas, message: "Parcelas do plano geradas com sucesso!"

POST /billing/simulate-payment/{id}/charges — restrito

Marca uma cobrança como paga em ambiente de teste (contas 1, 2, 3). Entrada: path id (id ou code). Saída: 200, data = a cobrança, message: "Pagamento simulado com sucesso!"403 fora das contas de teste; 400 se já estava paga.

POST /billing/simulate-payment

Simula valores por método — não cria nada. Entrada (corpo JSON): amount (obrigatório, ≥0.01), installments (obrigatório, 1–12). Saída: 200, data:

{
 "pix": { "method": "pix", "installments": 1, "installment_value": 100, "total_amount": 100.99 },
 "boleto": { "method": "boleto", "installments": 1, "installment_value": 100, "total_amount": 102.5 },
 "credit_card": { "method": "credit_card", "installments": 3, "installment_value": 33.33, "total_amount": 99.99, "original_amount": 100 },
 "simulation_details": { "requested_amount": 100, "requested_installments": 3, "preferred_method": "credit_card", "installments_summary": "3x de R$ 33,33" }
}

---

Grupos de cobrança — /invoices_groups · /billing/charge-groups

GET /invoices_groups

Entrada (query): per_page (default 15), page (default 1), search (nome). Saída: 200, { data: [grupos de cobrança], meta: {...} }.

POST /invoices_groups

Entrada (corpo JSON): name (obrigatório, ≤255), slug (opcional, ≤100, único), description (opcional), json (opcional, JSON válido). Saída: 201, grupo de cobrança, message: "Grupo de cobrança criado com sucesso!"

GET /invoices_groups/{id}

Entrada: path id. Saída: 200, grupo de cobrança. 404 se não existir.

PUT/PATCH /invoices_groups/{id}

Entrada (corpo JSON, opcionais): name (≤255), description, json (JSON), code (≤50, único), slug (≤255, único). Saída: 200, grupo de cobrança, message: "Grupo de cobrança atualizado com sucesso!"

DELETE /invoices_groups/{id}

Entrada: path id. Saída: 200 { "message": "Grupo de cobrança removido com sucesso!" }.

---

Clientes — /clients · /billing/clients

cliente (Administration): { id, code, name, email, phone, document, type, gender, birthdate, status, address:{...}|null, metadata, created_at, updated_at }.

GET /clients

Entrada (query): per_page (15), page (1), search (nome/documento), type (individual/company), gender, status, created_at_start/_end, updated_at_start/_end, birthdate_start/_end. Saída: 200, { data: [clientes], meta: {...} }.

POST /clients

Entrada (corpo JSON):

Campo	Tipo	Regras
name	string	obrigatório, ≤255
email	string	obrigatório, e-mail, ≤255
document	string	obrigatório, CPF ou CNPJ válido
type	string	obrigatório, individual ou company
phone	string	opcional, ≤20
gender	string	opcional, male/female
birthdate	date	opcional
address	object	opcional; se enviado, street, city, state obrigatórios; também number, zip, country, observation
metadata	array	opcional; itens { label (obrigatório), value }
fb_id, fb_access_token	string	opcionais

Saída: 200 — o cliente criado (status = ACTIVE).

GET /clients/{code}

Entrada: path code (código único do cliente). Saída: 200, cliente (com address), message: "Informações sobre o cliente". 404 se não existir.

PUT/PATCH /clients/{code}

Entrada (corpo JSON, todos sometimes): name, email, phone, type, gender, birthdate, address (mesma estrutura do POST), metadata, fb_id, fb_access_token. Aceita code ou id no path. Saída: 201, cliente, message: "Cliente atualizado com sucesso!" 404 se não existir.

DELETE /clients/{code}

Entrada: path code ou id. Saída: 204, data = cliente, message: "Cliente apagado com sucesso!" (marca status = DELETED e remove das listagens).

---

Planos de pagamento — /payment-plans

GET /payment-plans

Entrada: header Authorization. Saída: 200, data = array de planos, message: "Planos de Pagamento listados com sucesso!"

POST /payment-plans

Entrada (corpo JSON):

Campo	Tipo	Regras
description	string	obrigatório, ≤255
interval	int	obrigatório, ≥1
interval_type	string	obrigatório, months/weeks/days
installments_count	int	obrigatório, ≥1

Saída: 201, data = plano, message: "Plano de Pagamento criado com sucesso!"

GET /payment-plans/{id}

Entrada: path id. Saída: 200, data = plano, message: "Detalhes do Plano de Pagamento". 404 se não existir.

PUT/PATCH /payment-plans/{id}

Entrada (corpo JSON): mesmos campos de POST (todos obrigatórios). Saída: 200, data = plano, message: "Plano de Pagamento atualizado com sucesso!"

DELETE /payment-plans/{id}

Entrada: path id. Saída: 200, message: "Plano de Pagamento removido com sucesso!"

---

Links de pagamento — /billing/payment-links

Cada link: { id, title, description, amount, currency, is_variable_amount, min_amount, max_amount, status:{value,label}, payment_methods[], expires_at, max_uses, uses_count, success_url, cancel_url, webhook_url, reference_code, public_url, created_at, updated_at }.

GET /billing/payment-links

Entrada (query): id, status, search (título/descrição/reference_code), created_start/created_end, updated_start/updated_end, due_date_start/due_date_end, created_by, updated_by, order (asc/desc, default desc), per_page (15), page (1). Saída: 200, { data: [links de pagamento], meta: {...}, summary: { all: {value,label,count,amount}, <status>: {...} }, message }.

POST /billing/payment-links

Entrada (corpo JSON):

Campo	Tipo	Regras
title	string	obrigatório, ≤255
payment_methods	array	obrigatório, ≥1, itens em PIX,BOLETO,CARD
amount	number	obrigatório se is_variable_amount = false; ≥0
is_variable_amount	bool	opcional (default false)
min_amount	number	obrigatório se is_variable_amount = true; ≥0
max_amount	number	opcional, ≥0, > min_amount
currency	string(3)	opcional (default BRL)
description	string	opcional
expires_at	date	opcional, futura
max_uses	int	opcional, ≥1
success_url, cancel_url, webhook_url	url	opcionais
pass_transaction_fee_to_customer	bool	opcional
send_client_id	bool	opcional
reference_code	string ≤255	opcional (gerado se ausente)
client_id	int	opcional, existente
installments	int 1–12	opcional

Saída: 200, link de pagamento, message: "Link de pagamento criado com sucesso."

GET /billing/payment-links/{id}

Entrada: path id (o identificador público do link). Saída: 200, link de pagamento (com creator, updater, customer), message: "Link de pagamento recuperado com sucesso." 404 se não existir.

PUT/PATCH /billing/payment-links/{id}

Entrada (corpo JSON, opcionais): payment_methods (itens PIX/BOLETO/CARD; não pode remover método já usado em pagamento), pass_transaction_fee_to_customer, send_client_id, expires_at (futura), max_uses (≥1), success_url, cancel_url, installments (1–12). Link expirado não pode ser atualizado. Saída: 200, link de pagamento, message: "Link de pagamento atualizado com sucesso."

DELETE /billing/payment-links/{id}

Entrada: path id (o identificador público do link). Saída: 200, message: "Link de pagamento removido com sucesso."

GET /billing/payment-links/{id}/payments

Entrada: path id; query per_page (15). Saída: 200, { data: [pagamentos], meta: {...}, message } — todos os pagamentos do link (ordem desc por criação).

GET /billing/payment-links/{id}/paid-payments

Entrada: path id; query per_page (15). Saída: 200, { data: [pagamentos], meta: {...}, message } — apenas status = paid.

---

Transferência interna — POST /transfers/internal

Executa um Pix real de uma conta Sicredi para uma conta Sicoob (isento de taxas).

Entrada (corpo JSON):

Campo	Tipo	Regras
token	string	obrigatório — token da conta de destino (Sicoob), existente
amount	number	obrigatório, ≥0.01
description	string ≤255	opcional

Saída: 200, data: { txid, amount, status: "REALIZED" }, message: "Transferência Realizada com sucesso via Pix (Isenta de Taxas)." Erros: 403 se a origem não for Sicredi; 400 se o destino não for Sicoob, sem chave Pix, saldo insuficiente ou transação duplicada nos últimos 30 min; 500 em falha de comunicação bancária.