Consultar Cliente (Visão Completa)
Utilize o token obtido na autenticação para consultar a situação completa de um cliente pelo CPF: se é ativo, se já foi cliente, meses ativo somados entre todos os contratos, dados cadastrais, pets, contratos, agendamentos e comandas com compra de produto — agregado entre todas as franquias onde o CPF tem contrato.
Esta rota é mais ampla que Consultar Contratos do Cliente: inclui contratos do tipo Energia (a outra rota não inclui) e retorna um objeto muito mais detalhado — situação, dados cadastrais, pets, agendamentos e comandas, além dos contratos. Use esta rota quando precisar da visão 360° do cliente; use contract/by-document quando só precisar da lista de contratos elegíveis pra anexar um PDF.
🔍 Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| document | string (path) | ✅ | CPF do cliente, com ou sem máscara (ex: 855.578.539-10 ou 85557853910) |
Exemplo de Requisição
GET /integration/client/by-document/85557853910
Authorization: Bearer <token>
📋 Campos da Resposta — Situação
| Campo | Tipo | Descrição |
|---|---|---|
| document | string | CPF consultado, normalizado (só dígitos, sem pontuação) |
| is_active_client | boolean | true se o cliente tem pelo menos um contrato com status Ativo ou Inadimplente no momento da consulta. Contrato Interrompido não conta como ativo (é uma pausa de assinatura, não uma associação vigente) |
| was_client | boolean | true se o cliente chegou a ativar assinatura alguma vez — ou seja, algum contrato tem first_membership_date preenchido. Um contrato que ficou só em Aberto ou Negado (nunca pagou) não conta |
| last_year_as_client | number | null | Ano do first_membership_date mais recente entre os contratos do cliente. null se was_client for false |
| total_active_months | number | Soma, entre todos os contratos do cliente (todas as franquias), da quantidade de meses que cada contrato ficou ativo. Ver regra de cálculo abaixo |
| cancellation_reason | string | null | Motivo do cancelamento mais recente do cliente (contrato cancelado mais recente). null se o cliente nunca cancelou ou se o motivo não foi registrado |
total_active_months é calculadoPara cada contrato, o período ativo vai de first_membership_date até: last_membership_date (quando preenchido); senão, hoje se o contrato ainda está Ativo/Inadimplente; senão, status_date do contrato (data da última mudança de status — cobre contratos já cancelados sem last_membership_date preenchido). Os meses de cada contrato são somados — sem deduplicar sobreposição entre contratos simultâneos (raro, mas possível se o cliente tiver dois contratos ativos ao mesmo tempo).
📋 Campos da Resposta — Dados Cadastrais
| Campo | Tipo | Descrição |
|---|---|---|
| string | null | E-mail do cliente | |
| zipcode | string | null | CEP do cliente |
| gender | string | null | Sexo |
| civil_status | string | null | Estado civil |
| cellular | string | null | Celular |
| franchises | string[] | Nomes de todas as franquias onde o cliente teve contrato |
Quando o mesmo CPF tem cadastro em mais de uma franquia, os campos acima vêm do cadastro mais antigo (primeira franquia onde o CPF se cadastrou) — mesmo critério de "unidade primária" usado na tela interna de clientes unificados da franqueadora.
🐾 Campos da Resposta — Pets
pets é uma lista, deduplicada por nome + data de nascimento (uma renovação de contrato costuma re-listar o mesmo pet, então ele aparece só uma vez aqui).
| Campo | Tipo | Descrição |
|---|---|---|
| pets[].name | string | Nome do pet |
| pets[].birth | string (date) | Data de nascimento |
| pets[].age_years | number | Idade em anos, calculada a partir de birth |
| pets[].carry | string | Porte do pet: Pequeno, Médio ou Grande — valor cadastrado no contrato, não é calculado a partir do peso |
| pets[].breed | string | null | Raça |
| pets[].type | string | null | Espécie (ex: Cachorro, Gato) |
📅 Campos da Resposta — Agendamentos
| Campo | Tipo | Descrição |
|---|---|---|
| schedulings.total | number | Quantidade total de agendamentos do cliente, em todas as franquias |
| schedulings.items[].id | number | ID do agendamento |
| schedulings.items[].date | string (datetime) | Data/hora do agendamento |
| schedulings.items[].date_end | string (datetime) | null | Data/hora do fim do agendamento |
| schedulings.items[].status | string | Status do agendamento (ex: Agendado, Realizado) |
| schedulings.items[].service | string | null | Nome do serviço agendado |
| schedulings.items[].pet_name | string | Nome do pet do agendamento |
🛒 Campos da Resposta — Compras
purchases só considera comandas com pelo menos um produto vendido — uma comanda só de serviço (ex: um banho sem venda de produto) não entra aqui, ela já aparece em schedulings ou nos contracts.
| Campo | Tipo | Descrição |
|---|---|---|
| purchases.total | number | Quantidade de comandas do cliente que tiveram venda de produto |
| purchases.items[].command_id | number | ID da comanda |
| purchases.items[].number | string | Número da comanda |
| purchases.items[].pet_name | string | Nome do pet atendido na comanda |
| purchases.items[].status | string | Status da comanda (ex: Aberta, Fechada) |
| purchases.items[].status_date | string (date) | Data do status atual da comanda |
| purchases.items[].total | string | Valor total da comanda |
| purchases.items[].products[].title | string | Nome do produto comprado |
| purchases.items[].products[].qty | number | Quantidade comprada |
| purchases.items[].services[].title | string | Nome do serviço realizado na mesma comanda |
| purchases.items[].services[].qty | number | Quantidade do serviço |
📄 Campos da Resposta — Contratos
contracts traz todos os contratos do cliente, mais recente primeiro (inclui contratos do tipo Energia).
| Campo | Tipo | Descrição |
|---|---|---|
| contracts[].id | number | ID do contrato |
| contracts[].number | string | Número do contrato |
| contracts[].status | string | Status atual (ex: Aberto, Ativo, Inadimplente, Interrompido, Cancelado) |
| contracts[].status_date | string (date) | Data da última mudança de status |
| contracts[].first_membership_date | string (date) | null | Data em que o contrato ficou ativo pela primeira vez |
| contracts[].last_membership_date | string (date) | null | Data de fim da associação (nem sempre preenchida — ver regra de total_active_months acima) |
| contracts[].active_months | number | Meses ativo deste contrato especificamente (mesma regra de total_active_months, mas só deste contrato) |
| contracts[].franchise | string | Franquia responsável por este contrato |
| contracts[].plan_title | string | null | Nome do plano contratado |
| contracts[].plan_value | string | Valor do plano |
| contracts[].payment_form | string | null | Forma de pagamento crua: creditcard, debitcard, pix, boleto ou energy_bill |
| contracts[].payment_form_label | string | null | Forma de pagamento traduzida: Cartão de Crédito, Cartão de Débito, PIX, Boleto ou Energia |
| contracts[].sales_channel | string | null | Canal de vendas pelo qual o contrato foi fechado |
| contracts[].is_financial_responsible | boolean | true se o próprio cliente é o titular/responsável financeiro do contrato (não um dependente) |
| contracts[].cancellation_reason | string | null | Motivo de cancelamento deste contrato específico, se cancelado |
Exemplo de Resposta (200)
{
"document": "85557853910",
"is_active_client": true,
"was_client": true,
"last_year_as_client": 2024,
"total_active_months": 37,
"email": "cliente@exemplo.com",
"zipcode": "13010000",
"gender": "Feminino",
"civil_status": "Solteira",
"cellular": "11988887777",
"franchises": ["Unidade Centro"],
"pets": [
{ "name": "Rex", "birth": "2019-03-01", "age_years": 6, "carry": "Médio", "breed": "SRD", "type": "Cachorro" }
],
"schedulings": {
"total": 12,
"items": [
{ "id": 1, "date": "2024-05-10T13:00:00.000Z", "date_end": "2024-05-10T14:00:00.000Z", "status": "Realizado", "service": "Banho e Tosa", "pet_name": "Rex" }
]
},
"purchases": {
"total": 5,
"items": [
{ "command_id": 1, "number": "000045", "pet_name": "Rex", "status": "Fechada", "status_date": "2024-05-10", "total": "89.90", "products": [{ "title": "Ração X", "qty": 1 }], "services": [] }
]
},
"contracts": [
{
"id": 1,
"number": "000123",
"status": "Ativo",
"status_date": "2023-01-10",
"first_membership_date": "2023-01-10",
"last_membership_date": null,
"active_months": 20,
"franchise": "Unidade Centro",
"plan_title": "Plano Gold",
"plan_value": "129.90",
"payment_form": "creditcard",
"payment_form_label": "Cartão de Crédito",
"sales_channel": "Indicação",
"is_financial_responsible": true,
"cancellation_reason": null
}
],
"cancellation_reason": null
}
⚠️ Respostas
| Código | Descrição |
|---|---|
| 200 | Retorna o objeto completo com a situação do cliente |
| 401 | Token ausente ou inválido |
| 404 | Nenhum contrato nem cadastro de cliente encontrado para o CPF informado (error_document_not_exist) |