> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Obter Cliente
> Acesse o perfil completo de um cliente, incluindo histórico de compras, métricas de gastos e transações recentes para personalizar atendimento e estratégias de fidelização.
#### Escopo
```bash theme={null}
read orders
```
## O que é este endpoint?
Este endpoint retorna uma visão detalhada de um cliente específico que realizou compras pagas nos seus produtos. Além dos dados cadastrais, a resposta inclui **métricas de compra** e as **transações mais recentes**, permitindo que você entenda o comportamento e o valor desse cliente para o seu negócio.
Por motivos de privacidade e segurança, informações sensíveis como telefone e documento são retornadas de forma mascarada.
***
## Por que obter os dados detalhados de um cliente?
Conhecer o histórico e o valor de um comprador permite tomar decisões mais assertivas em atendimento, marketing e retenção.
Tenha em mãos o histórico de compras e o valor total gasto para oferecer um suporte mais rápido, humanizado e contextualizado.
Use as métricas de gastos e quantidade de pedidos para reconhecer compradores de alto valor e criar experiências exclusivas.
Analise as transações recentes para identificar padrões de compra e criar ofertas direcionadas no momento certo.
Entenda o perfil de gastos do cliente para definir políticas de desconto, condições especiais ou limites de crédito.
***
## Casos de uso
Quando um cliente entra em contato, acesse seu perfil completo em segundos. Veja o histórico de compras, valores gastos e pedidos recentes para resolver dúvidas, confirmar pagamentos ou escalar solicitações com contexto completo.
Identifique clientes com alto total de pedidos pagos ou ticket médio elevado para convidá-los para programas VIP, oferecer benefícios exclusivos ou antecipar lançamentos.
Analise clientes com transações antigas e pouca recorrência para disparar campanhas de reengajamento com ofertas personalizadas baseadas no histórico de compras.
Entenda o comportamento de compra individual: ticket médio, frequência, método de pagamento preferido e produtos adquiridos. Use esses dados para recomendações personalizadas.
***
## Insights que podem ser obtidos
A métrica `totalSpent` mostra o quanto o cliente já investiu nos seus produtos. Compreender esse valor ajuda a priorizar atendimento, definir investimentos em retenção e calcular o retorno de ações específicas.
Ao analisar `paidOrderCount` e as transações recentes, você consegue identificar se o cliente compra com regularidade, se está inativo ou se teve um pico de interesse recente.
O campo `averageOrder` revela o valor típico de compra do cliente. Isso é essencial para criar ofertas compatíveis com o perfil de gastos e aumentar o valor do carrinho.
***
## Response
* `customer.id` — Identificador do cliente
* `customer.name` — Nome do cliente
* `customer.email` — E-mail do cliente
* `customer.birthDate` — Data de nascimento
* `customer.phone` — Telefone mascarado
* `customer.docType` — Tipo de documento (`cpf`, `cnpj`)
* `customer.docNumber` — Número do documento mascarado
* `totalSpent` — Valor total gasto em pedidos pagos
* `paidOrderCount` — Quantidade de pedidos pagos
* `totalOrdersCount` — Total de pedidos (incluindo pendentes/cancelados)
* `averageOrder` — Valor médio dos pedidos pagos
* `transactions` — Lista com até 3 pedidos mais recentes
* `transactions[].id` — Identificador do pedido
* `transactions[].amount` — Valor do pedido
* `transactions[].status` — Status do pedido
* `transactions[].createdAt` — Data de criação
Clientes com alto valor de vida útil (LTV) merecem atenção especial. Ao combinar os dados deste endpoint com informações de assinaturas e campanhas, você consegue criar experiências personalizadas que aumentam a retenção e o faturamento por cliente.
## OpenAPI
````yaml GET /public_api/customers/{id}/
openapi: 3.0.3
info:
title: Cakto API
version: 1.0.0
description: Documentação da API pública do Cakto.
servers:
- url: https://api.cakto.com.br
description: Cakto API
security: []
paths:
/public_api/customers/{id}/:
get:
tags:
- customers
description: >-
Public API for listing customers who bought from the authenticated
seller.
Queries customer.Customer through orders to get customers who purchased
from the authenticated user.
operationId: customers_retrieve
parameters:
- in: path
name: id
schema:
type: integer
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerDetail'
examples:
Successo:
value:
averageOrder: 97
totalSpent: 291
paidOrderCount: 3
totalOrdersCount: 3
transactions:
- id: order_101
amount: '97.00'
status: paid
createdAt: '2025-10-03T11:19:35.019507-03:00'
- id: order_102
amount: '97.00'
status: paid
createdAt: '2025-10-02T14:22:10.123456-03:00'
- id: order_103
amount: '97.00'
status: paid
createdAt: '2025-09-28T09:05:00.987654-03:00'
customer:
id: 1
name: João da Silva
email: joao@example.com
birthDate: '1990-05-15'
phone: '*********7777'
docType: cpf
docNumber: 111******77
description: Corpo da resposta status 200
'401':
description: Request não autenticado devido à ausência ou invalidez do token.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedError'
examples:
Token ausente ou inválido:
$ref: '#/components/examples/UnauthenticatedErrorExample'
'404':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
NãoEncontrado:
value:
detail: Não encontrado.
summary: Não encontrado
description: Cliente não encontrado ou sem pedidos pagos nos seus produtos.
security:
- OAuth Token: []
components:
schemas:
CustomerDetail:
type: object
properties:
averageOrder:
type: number
description: Valor médio dos pedidos pagos
totalSpent:
type: number
description: Valor total gasto em pedidos pagos
paidOrderCount:
type: integer
description: Quantidade de pedidos pagos
totalOrdersCount:
type: integer
description: Total de pedidos
transactions:
type: array
items:
$ref: '#/components/schemas/CustomerTransaction'
description: Lista com até 3 pedidos mais recentes
customer:
$ref: '#/components/schemas/CustomerPublic'
required:
- averageOrder
- customer
- paidOrderCount
- totalOrdersCount
- totalSpent
- transactions
UnauthenticatedError:
type: object
properties:
detail:
type: string
CustomerTransaction:
type: object
properties:
id:
type: string
description: Identificador do pedido
amount:
type: string
description: Valor do pedido
status:
type: string
description: Status do pedido
createdAt:
type: string
format: date-time
description: Data de criação do pedido
required:
- amount
- createdAt
- id
- status
CustomerPublic:
type: object
properties:
id:
type: integer
readOnly: true
name:
type: string
title: Nome
description: Nome completo do cliente
maxLength: 255
email:
type: string
format: email
description: Endereço de email do cliente
maxLength: 254
birthDate:
type: string
format: date
nullable: true
title: Nascimento
description: Data de nascimento do cliente
phone:
type: string
readOnly: true
docType:
nullable: true
title: Tipo de Documento
description: |-
Tipo do documento (ex: cpf, cnpj)
* `cpf` - CPF
* `cnpj` - CNPJ
* `dni` - DNI
* `cuit` - CUIT
oneOf:
- $ref: '#/components/schemas/DocTypeEnum'
- $ref: '#/components/schemas/BlankEnum'
- $ref: '#/components/schemas/NullEnum'
docNumber:
type: string
readOnly: true
required:
- docNumber
- email
- id
- name
- phone
DocTypeEnum:
enum:
- cpf
- cnpj
- dni
- cuit
type: string
description: |-
* `cpf` - CPF
* `cnpj` - CNPJ
* `dni` - DNI
* `cuit` - CUIT
BlankEnum:
enum:
- ''
NullEnum:
enum:
- null
examples:
UnauthenticatedErrorExample:
summary: Token ausente ou inválido
description: Token ausente ou inválido
value:
detail: As credenciais de autenticação não foram fornecidas.
securitySchemes:
OAuth Token:
type: http
scheme: bearer
in: header
name: Authorization
description: >-
Token de autenticação do tipo `Bearer {access_token}`, onde
`{access_token}` é o token obtido no fluxo de
[autenticação](/authentication).
````