API de Clientes (Cliente)

sta API cria e gerencia clientes do modelo `Cliente`. Ela suporta listagem com filtros, criação/atualização (upsert) individual ou em lote, consulta de detalhe e atualização parcial. - Base path: `/a

Endpoints

• GET /api/clients — Lista clientes com filtros opcionais

• POST /api/clients — Upsert (cria/atualiza) 1 ou vários clientes

• GET /api/clients/<id> — Detalhe de um cliente

• PATCH /api/clients/<id> — Atualiza campos parciais de um cliente

Serialização do Cliente (resumo)

A resposta retorna o cliente normalizado com estes campos:

{
  "id": 123,
  "integration_id": "abc-123",
  "name": "Maria Silva",
  "cpf": "00011122233",
  "phone": "[phone]",
  "email": "[email protected]",
  "birth_date": "1990-05-20",
  "gender": "F",
  "image": "https://...",
  "observation": "VIP",
  "risk_score": 10,
  "created_at": "2025-01-01T12:34:56",
  "updated_at": "2025-01-02T09:00:00",
  "age": 35,
  "is_blocked": false
}

Campos aceitos no payload

A API aceita dois formatos de entrada. Você pode usar qualquer um; a API normaliza para o formato interno.

1. Formato simplificado:

• name, cpf, phone, email, birth_date, gender, image, integration_id

Regras importantes:

• Upsert usa, nesta ordem de prioridade, integration_id ou cpf.

• Datas de nascimento aceitas: YYYY-MM-DD ou DD/MM/YYYY.

• Strings vazias ("") ou null NÃO sobrescrevem valores existentes.

• Ao criar/alterar e houver mudança relevante, o campo age é recalculado automaticamente.

Listar clientes — GET /api/clients

Query params:

• cpf: filtra por CPF exato.

• id_beepay: filtra por id_beepay exato.

• search: busca por nome ou CPF (icontains).

• limit: número máximo de resultados (padrão: 50).

Resposta:

{
  "count": 2,
  "results": [ {"id": 1, ...}, {"id": 2, ...} ]
}

Exemplo:

curl -H "Authorization: Bearer $TOKEN" \
  "${API_URL}/api/clients?search=maria&limit=20"

Upsert em lote/único — POST /api/clients

• Aceita um objeto ou uma lista de objetos.

• Tenta localizar por integration_id; se ausente, por cpf.

• Aplica somente campos não vazios e diferentes dos já persistidos.

Resposta (sempre agrega o resultado; sucesso parcial possível):

{
  "created": [ {"id": 10, ...}, {"id": 11, ...} ],
  "errors": [ {"index": 1, "error": "Falta identificador (integration_id ou cpf)."} ]
}

• index refere-se à posição do item na lista enviada.

• Status HTTP: 201 se houve pelo menos um item criado/atualizado; senão 400.

Exemplos:

• Objeto único (formato simplificado):

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "integration_id": "abc-123",
    "name": "Maria Silva",
    "cpf": "00011122233",
    "phone": "[phone]",
    "email": "[email protected]",
    "birth_date": "20/05/1990",
    "gender": "F",
  }' \
  ${API_URL}/api/clients

• Em lote (misto, com erro em um item):

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '[
    {"cpf": "00011122233", "name": "Maria Silva"},
    {"name": "Sem identificador"}
  ]' \
  ${API_URL}/api/clients

Detalhe — GET /api/clients/

Exemplo:

curl -H "Authorization: Bearer $TOKEN" \
  ${API_URL}/api/clients/123

• 404 caso o cliente não exista.

Atualização parcial — PATCH /api/clients/

• Aceita tanto formato simplificado quanto interno.

• Campos vazios não sobrescrevem.

• Se birth_date mudar para um valor válido, a idade é recalculada.

Exemplo:

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"phone": "[phone]", "observation": "Cliente fidelidade"}' \
  ${API_URL}/api/clients/123

Códigos de status

• 200 — sucesso em GET/PATCH

• 201 — sucesso em POST (houve pelo menos uma criação/atualização)

• 400 — erro de validação ou nenhum item processado com sucesso no POST

• 401 — não autenticado

• 404 — recurso não encontrado (GET /api/clients/<id>)

Notas e boas práticas

• Idempotência: enviar novamente um mesmo payload com o mesmo integration_id ou cpf não cria duplicados; atualiza campos não vazios.

• Normalização de datas: prefira YYYY-MM-DD para evitar ambiguidades.

• Telefones/emails/nome: são tratados como strings; remoção (limpar valor) não é suportada via string vazia, apenas omitindo o campo ou aplicando regra específica no backend futuro.

Exemplos com Python (requests)

import requests

API_URL = "https://seu-servidor"
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# Upsert único
payload = {
    "integration_id": "123",
    "name": "Maria Silva",
    "cpf": "00011122233",
}
r = requests.post(f"{API_URL}/api/clients", json=payload, headers=headers)
print(r.status_code, r.json())

# Patch parcial
patch = {"phone": "[phone]"}
r = requests.patch(f"{API_URL}/api/clients/123", json=patch, headers=headers)
print(r.status_code, r.json())

---