Skip to main content

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.

🔗 Consultar Cliente (Swagger)

Diferença para "Consultar Contratos do Cliente"

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âmetroTipoObrigatórioDescrição
documentstring (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​

CampoTipoDescrição
documentstringCPF consultado, normalizado (só dígitos, sem pontuação)
is_active_clientbooleantrue 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_clientbooleantrue 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_clientnumber | nullAno do first_membership_date mais recente entre os contratos do cliente. null se was_client for false
total_active_monthsnumberSoma, 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_reasonstring | nullMotivo do cancelamento mais recente do cliente (contrato cancelado mais recente). null se o cliente nunca cancelou ou se o motivo não foi registrado
Como total_active_months é calculado

Para 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​

CampoTipoDescrição
emailstring | nullE-mail do cliente
zipcodestring | nullCEP do cliente
genderstring | nullSexo
civil_statusstring | nullEstado civil
cellularstring | nullCelular
franchisesstring[]Nomes de todas as franquias onde o cliente teve contrato
Qual franquia é a fonte dos dados cadastrais

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).

CampoTipoDescrição
pets[].namestringNome do pet
pets[].birthstring (date)Data de nascimento
pets[].age_yearsnumberIdade em anos, calculada a partir de birth
pets[].carrystringPorte do pet: Pequeno, Médio ou Grande — valor cadastrado no contrato, não é calculado a partir do peso
pets[].breedstring | nullRaça
pets[].typestring | nullEspécie (ex: Cachorro, Gato)

📅 Campos da Resposta — Agendamentos​

CampoTipoDescrição
schedulings.totalnumberQuantidade total de agendamentos do cliente, em todas as franquias
schedulings.items[].idnumberID do agendamento
schedulings.items[].datestring (datetime)Data/hora do agendamento
schedulings.items[].date_endstring (datetime) | nullData/hora do fim do agendamento
schedulings.items[].statusstringStatus do agendamento (ex: Agendado, Realizado)
schedulings.items[].servicestring | nullNome do serviço agendado
schedulings.items[].pet_namestringNome 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.

CampoTipoDescrição
purchases.totalnumberQuantidade de comandas do cliente que tiveram venda de produto
purchases.items[].command_idnumberID da comanda
purchases.items[].numberstringNúmero da comanda
purchases.items[].pet_namestringNome do pet atendido na comanda
purchases.items[].statusstringStatus da comanda (ex: Aberta, Fechada)
purchases.items[].status_datestring (date)Data do status atual da comanda
purchases.items[].totalstringValor total da comanda
purchases.items[].products[].titlestringNome do produto comprado
purchases.items[].products[].qtynumberQuantidade comprada
purchases.items[].services[].titlestringNome do serviço realizado na mesma comanda
purchases.items[].services[].qtynumberQuantidade do serviço

📄 Campos da Resposta — Contratos​

contracts traz todos os contratos do cliente, mais recente primeiro (inclui contratos do tipo Energia).

CampoTipoDescrição
contracts[].idnumberID do contrato
contracts[].numberstringNúmero do contrato
contracts[].statusstringStatus atual (ex: Aberto, Ativo, Inadimplente, Interrompido, Cancelado)
contracts[].status_datestring (date)Data da última mudança de status
contracts[].first_membership_datestring (date) | nullData em que o contrato ficou ativo pela primeira vez
contracts[].last_membership_datestring (date) | nullData de fim da associação (nem sempre preenchida — ver regra de total_active_months acima)
contracts[].active_monthsnumberMeses ativo deste contrato especificamente (mesma regra de total_active_months, mas só deste contrato)
contracts[].franchisestringFranquia responsável por este contrato
contracts[].plan_titlestring | nullNome do plano contratado
contracts[].plan_valuestringValor do plano
contracts[].payment_formstring | nullForma de pagamento crua: creditcard, debitcard, pix, boleto ou energy_bill
contracts[].payment_form_labelstring | nullForma de pagamento traduzida: Cartão de Crédito, Cartão de Débito, PIX, Boleto ou Energia
contracts[].sales_channelstring | nullCanal de vendas pelo qual o contrato foi fechado
contracts[].is_financial_responsiblebooleantrue se o próprio cliente é o titular/responsável financeiro do contrato (não um dependente)
contracts[].cancellation_reasonstring | nullMotivo 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ódigoDescrição
200Retorna o objeto completo com a situação do cliente
401Token ausente ou inválido
404Nenhum contrato nem cadastro de cliente encontrado para o CPF informado (error_document_not_exist)