Gestão de Clientes

O módulo de clientes permite o gerenciamento completo da base de pagadores, incluindo dados cadastrais, endereços e metadados personalizados.

---

Listagem de Clientes

[GET] /billing/clients (ou /clients)

Retorna uma lista paginada de todos os clientes vinculados à conta.

Parâmetros de Filtro (Query String):

Campo	Tipo	Descrição
search	String	Busca inteligente por Nome, E-mail, Documento ou Telefone.
type	String	Filtrar por tipo: individual (PF) ou company (PJ).
gender	String	Filtrar por gênero: male, female, other.
status	Mixed	Filtrar por status do cliente.
created_at_start / created_at_end	Date	Intervalo de data de criação (Y-m-d).
updated_at_start / updated_at_end	Date	Intervalo de data de atualização (Y-m-d).
birthdate_start / birthdate_end	Date	Intervalo de data de nascimento (Y-m-d).
per_page	Integer	Itens por página (default: 15).
page	Integer	Número da página.

Resposta (200 OK):

{
  "data": [
    {
      "client_id": 5,
      "name": "João Lima da Silva",
      "email": "joao.lima@gmail.com",
      "phone": {
        "formatted": "(11) 98888-7777",
        "raw": "11988887777"
      },
      "document": {
        "formatted": "123.456.789-01",
        "raw": "12345678901"
      },
      "type": "individual",
      "gender": "male",
      "birthdate": {
        "formatted": "15 de maio de 1990",
        "raw": "1990-05-15"
      },
      "code": "cl_5f0a1b2c",
      "status": "active",
      "created_at": {
        "formatted": "há 2 meses",
        "raw": "2024-10-01T10:00:00.000000Z"
      }
    }
  ],
  "meta": {
    "total": 120,
    "page": 1,
    "per_page": 15
  }
}

---

Criação de Cliente

[POST] /billing/clients

Cadastra um novo cliente com informações pessoais e de endereço.

Payload:

{
  "name": "Maria Oliveira",
  "email": "maria@email.com",
  "document": "12345678900",
  "phone": "11988887777",
  "type": "individual",
  "gender": "female",
  "birthdate": "1990-05-15",
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "zip": "01234567",
    "city": "São Paulo",
    "state": "SP",
    "country": "Brasil"
  },
  "metadata": [
    { "label": "Segmento", "value": "Premium" }
  ]
}

---

Detalhes do Cliente

[GET] /billing/clients/\{code\}

Retorna os dados completos de um cliente específico através do seu código (code).

---

Atualização de Cliente

[PUT] /billing/clients/\{code\}

Permite modificar as informações de um cliente existente. Aceita atualizações parciais.

---

Remover Cliente

[DELETE] /billing/clients/\{id_ou_code\}

Realiza a exclusão lógica do cliente (Soft Delete).

---

Colunas e Schema

Coluna	Descrição
id	Identificador interno.
code	Hash público para uso na API/Frontend.
name	Nome completo ou Razão Social.
email	E-mail principal.
document	CPF ou CNPJ (será limpo automaticamente).
phone	Telefone com ou sem máscara.
type	individual ou company.
gender	male, female ou other.
metadata	Dados JSON personalizados.

---

Atualizado em: 07/05/2026