Alunos (Clientes)
Gerenciamento de clientes (alunos) no sistema de cobrança.
Listagem de Alunos
[GET] /clients
Lista todos os alunos/clientes cadastrados na conta autenticada.
Headers
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | Bearer Token | Sim | Token JWT |
| Accept | string | Sim | application/json |
Request (Sem parâmetros)
GET /clients
Request (Com Paginação e Busca)
GET /clients?per_page=15&page=1&search=João
Response (200 OK)
json
{
"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"
},
"metadata": [
{
"label": "Curso",
"value": "Direito"
}
],
"address": {
"street": "Rua Exemplo",
"number": "123",
"zip": "01001000",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"observation": "Apto 42"
},
"fb_id": null,
"fb_access_token": null,
"code": "cl_5f0a1b2c",
"status": "active",
"created_at": {
"formatted": "há 2 meses",
"raw": "2024-10-01T10:00:00.000000Z"
},
"updated_at": {
"formatted": "há 1 semana",
"raw": "2024-12-20T10:00:00.000000Z"
}
}
],
"meta": {
"total": 120,
"page": 1,
"limit": 15,
"total_pages": 8,
"has_next_page": true,
"has_prev_page": false
}
}Criação de Aluno
[POST] /clients
Cadastra um novo aluno/cliente com endereço e metadados opcionais.
Request (Corpo Completo)
json
{
"name": "Ana Oliveira",
"email": "ana@gmail.com",
"phone": "11977776666",
"document": "98765432109",
"type": "individual",
"gender": "female",
"birthdate": "1995-10-20",
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zip": "01311100",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"observation": "Próximo ao MASP"
},
"metadata": [
{
"label": "Polo",
"value": "Centro"
}
]
}Response (201 Created)
json
{
"data": {
"client_id": 8,
"name": "Ana Oliveira",
"email": "ana@gmail.com",
"phone": {
"formatted": "(11) 97777-6666",
"raw": "11977776666"
},
"document": {
"formatted": "987.654.321-09",
"raw": "98765432109"
},
"type": "individual",
"gender": "female",
"birthdate": {
"formatted": "20 de outubro de 1995",
"raw": "1995-10-20"
},
"metadata": [
{
"label": "Polo",
"value": "Centro"
}
],
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zip": "01311100",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"observation": "Próximo ao MASP"
},
"fb_id": null,
"fb_access_token": null,
"code": "cl_abc12345",
"status": "active",
"created_at": {
"formatted": "há 1 segundo",
"raw": "2024-12-26T15:20:00.000000Z"
},
"updated_at": {
"formatted": "há 1 segundo",
"raw": "2024-12-26T15:20:00.000000Z"
}
}
}Ver Detalhes do Aluno
[GET] /clients/{code}
Retorna as informações detalhadas de um aluno através de seu código (code).
Request
GET /clients/cl_abc12345
Response (200 OK)
json
{
"data": {
"client_id": 8,
"name": "Ana Oliveira",
"email": "ana@gmail.com",
"phone": {
"formatted": "(11) 97777-6666",
"raw": "11977776666"
},
"document": {
"formatted": "987.654.321-09",
"raw": "98765432109"
},
"type": "individual",
"gender": "female",
"birthdate": {
"formatted": "20 de outubro de 1995",
"raw": "1995-10-20"
},
"metadata": [
{
"label": "Polo",
"value": "Centro"
}
],
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zip": "01311100",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"observation": "Próximo ao MASP"
},
"fb_id": null,
"fb_access_token": null,
"code": "cl_abc12345",
"status": "active",
"created_at": {
"formatted": "há 5 minutos",
"raw": "2024-12-26T15:20:00.000000Z"
},
"updated_at": {
"formatted": "há 5 minutos",
"raw": "2024-12-26T15:20:00.000000Z"
}
},
"message": "Informações sobre o cliente"
}Atualização de Aluno
[PUT] /clients/{code}
Atualiza os dados de um aluno. Aceita atualizações parciais.
Request Body (Parcial)
json
{
"name": "Ana Oliveira Silva",
"phone": "11900000000"
}Response (201 Created)
json
{
"data": {
"client_id": 8,
"name": "Ana Oliveira Silva",
"email": "ana@gmail.com",
"phone": {
"formatted": "(11) 90000-0000",
"raw": "11900000000"
},
"document": {
"formatted": "987.654.321-09",
"raw": "98765432109"
},
"type": "individual",
"gender": "female",
"birthdate": {
"formatted": "20 de outubro de 1995",
"raw": "1995-10-20"
},
"metadata": [
{
"label": "Polo",
"value": "Centro"
}
],
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zip": "01311100",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"observation": "Próximo ao MASP"
},
"fb_id": null,
"fb_access_token": null,
"code": "cl_abc12345",
"status": "active",
"created_at": {
"formatted": "há 10 minutos",
"raw": "2024-12-26T15:20:00.000000Z"
},
"updated_at": {
"formatted": "agora",
"raw": "2024-12-26T15:30:00.000000Z"
}
},
"message": "Cliente atualizado com sucesso!"
}Excluir Aluno
[DELETE] /clients/{client_id}
Realiza a exclusão lógica do aluno. Note que este endpoint utiliza o ID numérico e não o código.
Response (204 No Content)
(Corpo vazio)
Erro (404 Not Found)
json
{
"success": false,
"message": "Cliente não encontrado.",
"status": 404
}