Clientes

Estas rotas devolvem o cadastro dos clientes da empresa: quem são, como falar com eles, onde moram e quanto compraram. Servem para sincronizar a carteira com um CRM externo, medir clientes novos por mês e cruzar o cliente com eventos, orçamentos e cobranças pelo clientId.

Escopo exigido: clients:read. Sem ele, as rotas respondem scope_missing.

Este é o escopo mais sensível da API

O cadastro sai completo: nome, CPF ou CNPJ, e-mail, telefone, endereço e inscrições. Por isso o escopo é separado do CRM, e só quem enxerga os clientes no Festero consegue conceder. Dê esta permissão apenas a sistemas em que você confia e que precisam do cadastro. Continuam fora: anotações internas, o documento do representante legal e qualquer dado de convidado ou de criança.

Testar na referência interativa

Listar clientes

GET /v1/clients

Lista os clientes da empresa, da alteração mais antiga para a mais recente, com paginação por cursor. Não existe busca por nome, telefone ou documento: a lista inteira sai paginada.

Parâmetro	Tipo	Descrição
isActive	true ou false	Só os ativos ou só os inativos. Sem o parâmetro, todos.
createdFrom	data yyyy-MM-dd	Só os cadastrados a partir desta data (inclusive), no horário de Brasília.
createdTo	data yyyy-MM-dd	Só os cadastrados até esta data (inclusive).
updatedSince	data e hora ISO 8601	Só os clientes alterados a partir deste instante.
limit	inteiro	Tamanho da página, de 1 a 100 (padrão 25).
cursor	texto	O nextCursor da página anterior.

curl "https://platform.festero.com.br/v1/clients?isActive=true&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "2a7b5c90-31de-4f68-b4a2-6e0d8c19f533",
      "name": "Marina Albuquerque",
      "kind": "person",
      "taxIdType": "cpf",
      "taxId": "11144477735",
      "email": "[email protected]",
      "phone": "71999990000",
      "street": "Rua das Acácias",
      "number": "120",
      "complement": null,
      "neighborhood": "Pituba",
      "postalCode": "41830000",
      "city": "Salvador",
      "state": "BA",
      "municipalRegistration": null,
      "stateRegistration": null,
      "fiscalEmail": null,
      "legalRepresentativeName": null,
      "isActive": true,
      "isAnonymized": false,
      "anonymizedAt": null,
      "eventsCount": 3,
      "createdAt": "2026-03-04T10:21:07-03:00",
      "updatedAt": "2026-09-12T16:40:02-03:00"
    }
  ],
  "nextCursor": null
}

Buscar um cliente

GET /v1/clients/{id}

Devolve um cliente pelo identificador, com os mesmos campos da lista. Responde 404 (not_found) se ele não existe ou é de outra empresa. A resposta traz ETag: veja Paginação e datas.

Campos do cliente

Campo	Tipo	Descrição
id	GUID	Identificador do cliente.
name	texto	Nome. Trechos que parecem telefone, e-mail ou documento aparecem como [oculto] (cliente criado pelo WhatsApp às vezes fica com o telefone no nome).
kind	texto	person (pessoa física) ou company (empresa), pelo tipo do documento.
taxIdType	texto ou null	cpf ou cnpj.
taxId	texto ou null	CPF ou CNPJ, só dígitos.
email, phone	texto ou null	Contato do cliente, como cadastrado.
street, number, complement, neighborhood, postalCode, city, state	texto ou null	Endereço. postalCode só com dígitos.
municipalRegistration, stateRegistration, fiscalEmail	texto ou null	Dados fiscais, usados na nota fiscal de serviço.
legalRepresentativeName	texto ou null	Representante legal, quando o cliente é uma empresa. O documento dele não sai.
isActive	booleano	Falso quando o cliente foi inativado.
isAnonymized, anonymizedAt	booleano, data	Verdadeiro quando o cliente pediu a anonimização (LGPD); o nome já vem substituído.
eventsCount	inteiro	Eventos do cliente em qualquer status, como a tela de Clientes.
createdAt, updatedAt	data e hora	Instantes do cadastro e da última alteração.

Resumo de um cliente

GET /v1/clients/{id}/summary

Resume o relacionamento comercial com o cliente.

Campo	Descrição
eventsCount, soldEventsCount	Eventos em qualquer status e eventos vendidos (upcoming e completed).
totalSpent	Soma do valor dos eventos vendidos.
receivedTotal, outstandingTotal	Quanto já foi recebido e quanto falta receber nas contas a receber do cliente.
lastEventDate, nextEventDate	Último evento passado e próximo evento, sem contar rascunhos e cancelados.
openQuotesCount, openOpportunitiesCount	Orçamentos em rascunho ou enviados e oportunidades em aberto.

Os três campos de dinheiro (totalSpent, receivedTotal, outstandingTotal) só vêm preenchidos quando a credencial também tem o escopo finance:read; sem ele ficam null e o resto da resposta continua.

Análise da carteira

GET /v1/clients/analytics

Os mesmos números da aba Clientes dos relatórios do Festero: clientes cadastrados, clientes com eventos no período, novos no último mês, receita média por cliente, os 10 que mais geraram receita e os clientes novos por mês (12 meses). A receita é a dos orçamentos aprovados cujo evento não foi cancelado.

Parâmetro	Tipo	Descrição
createdFrom	data yyyy-MM-dd	Só os eventos criados a partir desta data. Sem o parâmetro, toda a história.
createdTo	data yyyy-MM-dd	Só os eventos criados até esta data (inclusive).

O período filtra os eventos pela data de criação (como a tela). Os valores em dinheiro (averageRevenuePerClient e totalRevenue de cada cliente do ranking) só vêm com finance:read também.