Aparência
Clientes
Prefixo base: /billing
Todas as rotas requerem autenticação JWT + conta ativa.
Headers obrigatórios:
Authorization: Bearer {token}
Content-Type: application/json
account: {account_id}GET /billing/clients
Lista os clientes da conta com paginação e busca.
Query params:
| Parâmetro | Tipo | Descrição |
|---|---|---|
search | string | Busca por nome, e-mail ou documento |
per_page | integer | Itens por página (padrão: 15) |
page | integer | Página atual |
Response 200:
json
{
"data": [
{
"id": 5,
"code": "CLT-abc123",
"name": "Maria Oliveira",
"email": "maria@exemplo.com",
"phone": "11999998888",
"document": "98765432100",
"type": "individual",
"gender": "female",
"birthdate": "1985-03-20",
"status": "2",
"charges_count": 10,
"paid_charges_count": 7,
"pending_charges_count": 3,
"total_paid_value": "1050.00",
"total_pending_value": "450.00",
"total_value": "1500.00",
"address": null,
"created_at": "2025-01-10T08:00:00.000000Z"
}
],
"meta": {
"current_page": 1,
"per_page": 15,
"total": 42,
"last_page": 3
}
}POST /billing/clients
Cria um novo cliente na conta.
Body:
json
{
"name": "João Santos",
"email": "joao@exemplo.com",
"phone": "11988887777",
"document": "12345678901",
"type": "individual",
"gender": "male",
"birthdate": "1990-05-10",
"address": {
"street": "Rua das Flores",
"number": "100",
"zip": "01310-100",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"observation": "Apto 42"
},
"metadata": [
{ "label": "Contrato", "value": "CT-2025-001" }
]
}| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | Sim | máx. 255 caracteres |
email | string | Sim | e-mail válido |
document | string | Sim | CPF ou CNPJ válido; único na conta |
type | string | Sim | individual ou company |
phone | string | Não | máx. 20 caracteres |
gender | string | Não | male ou female |
birthdate | date | Não | formato YYYY-MM-DD |
address | object | Não | Endereço completo |
address.street | string | Cond. | obrigatório se address informado |
address.city | string | Cond. | obrigatório se address informado |
address.state | string | Cond. | obrigatório se address informado |
metadata | array | Não | Array de { label, value } |
Response 201:
json
{
"data": {
"id": 6,
"code": "CLT-def456",
"name": "João Santos",
"email": "joao@exemplo.com",
"document": "12345678901",
"type": "individual",
"status": "2",
"created_at": "2025-07-01T10:00:00.000000Z"
}
}Erros:
| Código | Descrição |
|---|---|
| 422 | Documento duplicado na conta, e-mail inválido, tipo inválido |
Regras de negócio:
- Se o cliente tiver e-mail e
wants_email_notifications = true, recebe e-mail de boas-vindas.
GET /billing/clients/{id}
Retorna os detalhes de um cliente, por id numérico.
Response 200:
json
{
"data": {
"id": 5,
"code": "CLT-abc123",
"name": "Maria Oliveira",
"email": "maria@exemplo.com",
"document": "98765432100",
"type": "individual",
"status": "2",
"address": {
"street": "Av. Paulista",
"number": "1000",
"city": "São Paulo",
"state": "SP",
"zip": "01310-100"
}
},
"message": "Informações sobre o cliente"
}Erros:
| Código | Descrição |
|---|---|
| 404 | Cliente não encontrado |
PUT /billing/clients/{id}
Atualiza os dados de um cliente, por id numérico.
Body: Mesmos campos do POST, todos opcionais (use sometimes).
json
{
"name": "Maria Oliveira Santos",
"phone": "11977776666",
"address": {
"street": "Rua Nova",
"number": "200",
"city": "São Paulo",
"state": "SP"
},
"metadata": [
{ "label": "Observação", "value": "Cliente VIP" }
]
}Response 201:
json
{
"data": { ... },
"message": "Cliente atualizado com sucesso!"
}DELETE /billing/clients/{id}
Remove o cliente (soft delete), por id numérico.
Response 204: Sem body
GET /customers/reports
Relatório de clientes para o dashboard. Retorna KPIs de base, série de aquisição e ranking dos clientes com maior LTV.
Query params:
| Parâmetro | Tipo | Obrigatório | Valores / Formato |
|---|---|---|---|
period | string | Não | today, yesterday, last_7_days, last_15_days, last_30_days, last_90_days, current_month, previous_month, current_year, previous_year |
start_date | date | Não* | YYYY-MM-DD — obrigatório se end_date informado |
end_date | date | Não* | YYYY-MM-DD — obrigatório se start_date informado; deve ser ≥ start_date |
group_by | string | Não | day, week, month (padrão), year |
top_limit | integer | Não | 1–20 (padrão: 5) |
Se nenhum parâmetro de período for informado, usa o mês corrente como padrão.
periodestart_date/end_datesão mutuamente exclusivos — use um ou outro.
Response 200:
json
{
"data": {
"kpis": {
"total_clientes": 1245,
"clientes_ativos": 1120,
"clientes_inativos": 125,
"variacao_aquisicao": 12.0
},
"aquisicao_mensal": [
{ "month": "Jan", "novos": 45 },
{ "month": "Fev", "novos": 52 },
{ "month": "Mar", "novos": 48 }
],
"top_clientes_ltv": [
{ "nome": "Tech Solutions LTDA", "ltv": 125000.00 },
{ "nome": "Farmácia Central", "ltv": 85000.00 },
{ "nome": "Distribuidora ABC", "ltv": 62000.00 }
]
}
}Descrição dos campos:
| Campo | Descrição |
|---|---|
kpis.total_clientes | Total de clientes da conta (exceto excluídos via soft delete) |
kpis.clientes_ativos | Clientes com status = "2" (ACTIVE) |
kpis.clientes_inativos | Clientes com status = "-1" (DELETED/desativado) |
kpis.variacao_aquisicao | Variação percentual de novos clientes no período vs. período anterior equivalente |
aquisicao_mensal[].month | Label do período em português (Jan, Fev, Sem 23, 01/06, etc.) |
aquisicao_mensal[].novos | Quantidade de clientes criados (created_at) no sub-período |
top_clientes_ltv[].nome | Nome do cliente |
top_clientes_ltv[].ltv | LTV: soma de amount_paid de todas as cobranças pagas pelo cliente (all-time) |
Agrupamentos e labels geradas:
group_by | Chave SQL | Exemplo de label |
|---|---|---|
day | YYYY-MM-DD | 01/06 |
week | Segunda-feira da semana (YYYY-MM-DD) | Sem 23 |
month | YYYY-MM | Jun |
year | YYYY | 2025 |
Erros:
| Código | Descrição |
|---|---|
| 401 | Não autenticado |
| 422 | Parâmetros inválidos (período desconhecido, datas inconsistentes, group_by inválido) |
Regras de negócio:
- Clientes removidos via soft delete (
deleted_at IS NOT NULL) nunca entram nos totais. - O LTV em
top_clientes_ltvconsidera todas as cobranças pagas da conta, sem filtro de período, para refletir o valor histórico real do cliente. - Todos os sub-períodos sem dados aparecem na série com valor
0(sem lacunas no gráfico). - A série
aquisicao_mensalagrupa porcreated_atdo cliente.