> ## 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.
# Listar Clientes
> Consulte sua base de compradores pagantes para análises, integrações com CRM, segmentação de campanhas e acompanhamento do relacionamento com clientes.
#### Escopo
```bash theme={null}
read orders
```
## O que é este endpoint?
Este endpoint permite acessar todos os clientes que já realizaram pelo menos uma compra paga nos seus produtos. É a porta de entrada para entender quem são seus compradores, como está evoluindo sua base e como usar esses dados para crescer de forma mais inteligente.
Por motivos de privacidade e segurança, informações sensíveis como telefone e documento são retornadas de forma mascarada.
***
## Por que consultar sua base de clientes?
Ter acesso consolidado aos seus compradores vai muito além de uma simples listagem. É a base para estratégias de retenção, automação e crescimento.
Identifique grupos de clientes para criar ofertas direcionadas, reengajamento e campanhas personalizadas.
Sincronize sua base de compradores com ferramentas de relacionamento, atendimento e automação de marketing.
Acompanhe a evolução da base de compradores ao longo do tempo e meça a saúde da aquisição de clientes.
Localize rapidamente o cadastro de um cliente para validar compras, acompanhar pedidos ou prestar atendimento.
***
## Casos de uso
Recupere todos os clientes pagantes e sincronize os dados com plataformas de CRM para centralizar o histórico de relacionamento. Dados como nome, e-mail e documento permitem criar ou atualizar contatos, iniciar fluxos de automação e organizar clientes por segmentos.
Localize clientes específicos para criar campanhas direcionadas, ofertas exclusivas ou estratégias de reengajamento. Combine buscas por nome, e-mail ou documento para montar listas precisas.
Combine este endpoint com os dados de pedidos para encontrar clientes que compram com frequência. Essa segmentação é ideal para programas de fidelidade, ofertas VIP e estratégias de retenção.
Utilize os dados dos clientes em conjunto com pedidos e assinaturas para construir dashboards mais completos e acompanhar métricas como total de clientes, novos compradores no mês e taxas de recorrência.
Quando um cliente entra em contato com o suporte, use a busca para localizar o cadastro rapidamente e validar compras, pedidos ou dados pessoais sem perder tempo.
***
## Insights que podem ser obtidos
Acompanhe a evolução do número de compradores ao longo do tempo para entender como sua operação está expandindo e se suas estratégias de aquisição estão funcionando.
Utilize os dados para manter um histórico único do cliente em sistemas externos, melhorando ações de retenção, comunicação pós-venda e experiência do consumidor.
Agrupe clientes por características, comportamento de compra ou periodicidade para criar campanhas com maior taxa de conversão e menor custo de aquisição.
***
## Busca
Localize clientes rapidamente utilizando o parâmetro `search`. A busca é textual e abrange os seguintes campos:
* `name` — Nome do cliente
* `email` — E-mail do cliente
* `phone` — Telefone do cliente
* `docNumber` — Número do documento
**Exemplo:** `?search=joao`
Retorna clientes que possuam o termo informado em qualquer um dos campos suportados.
***
## Ordenação
Utilize o parâmetro `ordering` para organizar os clientes da forma mais conveniente para sua operação.
Campos suportados: `id`, `name`
Use o prefixo `-` para ordenação decrescente.
**Exemplo:** `?ordering=-name` — Retorna os clientes em ordem alfabética inversa (Z → A).
***
## Response
* `id` — Identificador do cliente
* `name` — Nome do cliente
* `email` — E-mail do cliente
* `birthDate` — Data de nascimento
* `phone` — Telefone mascarado (ex: `*********0979`)
* `docType` — Tipo de documento (`cpf`, `cnpj`)
* `docNumber` — Número do documento mascarado (ex: `504******05`)
Uma base de clientes crescente indica aquisição eficiente, mas o verdadeiro valor está na capacidade de transformar compradores em clientes recorrentes. Combine estes dados com pedidos, assinaturas e métricas de receita para acompanhar todo o ciclo de vida do cliente.
## OpenAPI
````yaml GET /public_api/customers/
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/:
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_list
parameters:
- name: limit
required: false
in: query
description: Número de resultados a serem retornados por página.
schema:
type: integer
- name: ordering
required: false
in: query
description: Which field to use when ordering the results.
schema:
type: string
- name: page
required: false
in: query
description: Número da página a ser retornada.
schema:
type: integer
- name: search
required: false
in: query
description: A search term.
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCustomerList'
description: ''
'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'
security:
- OAuth Token: []
components:
schemas:
PaginatedCustomerList:
type: object
properties:
count:
type: integer
example: 123
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=4
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?page=2
results:
type: array
items:
$ref: '#/components/schemas/CustomerPublic'
UnauthenticatedError:
type: object
properties:
detail:
type: string
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).
````