Skip to content

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âmetroTipoDescrição
searchstringBusca por nome, e-mail ou documento
per_pageintegerItens por página (padrão: 15)
pageintegerPá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" }
  ]
}
CampoTipoObrigatórioRegras
namestringSimmáx. 255 caracteres
emailstringSime-mail válido
documentstringSimCPF ou CNPJ válido; único na conta
typestringSimindividual ou company
phonestringNãomáx. 20 caracteres
genderstringNãomale ou female
birthdatedateNãoformato YYYY-MM-DD
addressobjectNãoEndereço completo
address.streetstringCond.obrigatório se address informado
address.citystringCond.obrigatório se address informado
address.statestringCond.obrigatório se address informado
metadataarrayNãoArray 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ódigoDescrição
422Documento 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ódigoDescrição
404Cliente 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âmetroTipoObrigatórioValores / Formato
periodstringNãotoday, yesterday, last_7_days, last_15_days, last_30_days, last_90_days, current_month, previous_month, current_year, previous_year
start_datedateNão*YYYY-MM-DD — obrigatório se end_date informado
end_datedateNão*YYYY-MM-DD — obrigatório se start_date informado; deve ser ≥ start_date
group_bystringNãoday, week, month (padrão), year
top_limitintegerNão1–20 (padrão: 5)

Se nenhum parâmetro de período for informado, usa o mês corrente como padrão. period e start_date/end_date sã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:

CampoDescrição
kpis.total_clientesTotal de clientes da conta (exceto excluídos via soft delete)
kpis.clientes_ativosClientes com status = "2" (ACTIVE)
kpis.clientes_inativosClientes com status = "-1" (DELETED/desativado)
kpis.variacao_aquisicaoVariação percentual de novos clientes no período vs. período anterior equivalente
aquisicao_mensal[].monthLabel do período em português (Jan, Fev, Sem 23, 01/06, etc.)
aquisicao_mensal[].novosQuantidade de clientes criados (created_at) no sub-período
top_clientes_ltv[].nomeNome do cliente
top_clientes_ltv[].ltvLTV: soma de amount_paid de todas as cobranças pagas pelo cliente (all-time)

Agrupamentos e labels geradas:

group_byChave SQLExemplo de label
dayYYYY-MM-DD01/06
weekSegunda-feira da semana (YYYY-MM-DD)Sem 23
monthYYYY-MMJun
yearYYYY2025

Erros:

CódigoDescrição
401Não autenticado
422Parâ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_ltv considera 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_mensal agrupa por created_at do cliente.