VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Clientes do seller

Lista e exportação de clientes

Lista os clientes do seller com totais de compra, abre o detalhe de um cliente, resume a base e exporta tudo em CSV.

Estas quatro leituras mostram ao seller quem compra dele. Todos os totais (pedidos, valor gasto, primeiro e último pedido) consideram só os pedidos do próprio seller, nunca o histórico do cliente em outros sellers. Não há privilégio fino: qualquer usuário do seller consegue ler.

Listar clientes

GET/api/v1/vendor/customersSeller

Lista paginada de clientes do seller

Devolve os clientes que já pediram ao seller e os que estão na carteira própria, com totais. Passando id, a mesma rota devolve o detalhe de um cliente (veja abaixo).

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora da faixa volta para 20.
searchstring
Busca por trecho do nome, sobrenome, e-mail, razão social ou nome fantasia (sem diferenciar maiúsculas).
sort_bystringpadrão: total_spent
first_namelast_namedisplay_nameemailorder_counttotal_spentlast_order_atcreated_at
Coluna de ordenação. Valor desconhecido ordena por valor gasto (maior primeiro) e número de pedidos.
sort_dirstringpadrão: asc
ascdesc
Direção, quando sort_by é informado. Qualquer valor que não seja desc vale asc.
filterstring
overduenever_orderedportfolio
Recorte operacional. overdue: passou da frequência esperada (precisa estar configurada). never_ordered: está na carteira e nunca comprou. portfolio: só quem foi posto na carteira. Vazio traz todos; outro valor é ignorado.
iduuid
Quando informado, devolve o detalhe desse cliente e ignora os demais parâmetros.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/vendor/customers?per_page=20&sort_by=total_spent&sort_dir=desc" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Clientes do seller
json
{
  "customers": [
    {
      "user_id": "4f44f104-bbe0-4d2e-b497-c1afbe19d7c5",
      "first_name": "Vinícius",
      "last_name": "Nunes",
      "email": "vinicius.nunes@example.com",
      "phone": "+5551953268977",
      "order_count": 45,
      "total_spent": 4366331,
      "last_order_at": "2026-09-04T19:44:46.593557Z",
      "first_order_at": "2026-05-31T16:46:46Z",
      "city": "",
      "state": "",
      "status": "A",
      "user_type": "customer",
      "email_verified": true,
      "registered_at": "2026-05-31T15:59:45Z",
      "person_type": "F",
      "cpf": "123.456.789-09",
      "display_name": "Vinícius Nunes",
      "in_portfolio": false,
      "days_since_last_order": 37,
      "days_overdue": 0,
      "expected_order_freq_days": 0
    }
  ],
  "total": 7187,
  "page": 1,
  "per_page": 20,
  "total_pages": 360
}

Campos da resposta

customersarray
Clientes da página. null quando nenhum cliente combina.
totalinteger
Total de clientes que combinam com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho aplicado.
total_pagesinteger
Total de páginas.
customers[].user_iduuid
Id do cliente na loja.
customers[].first_namestring
Nome. Para pessoa jurídica guarda a razão social.
customers[].last_namestring
Sobrenome.
customers[].emailstring
E-mail.
customers[].phonestring
Telefone, quando há.
customers[].order_countinteger
Pedidos do cliente neste seller. 0 para quem só está na carteira.
customers[].total_spentinteger
Soma dos pedidos válidos neste seller, em centavos.
customers[].first_order_atstring
Primeiro pedido neste seller (RFC 3339). Ausente se nunca comprou.
customers[].last_order_atstring
Último pedido neste seller. Ausente se nunca comprou.
customers[].citystring
Cidade do endereço principal do cliente. Vazio sem endereço.
customers[].statestring
UF do endereço principal.
customers[].statusstring
Situação da conta do cliente, em letra (por exemplo A, ativo).
customers[].user_typestring
Tipo da conta; aqui, customer.
customers[].email_verifiedboolean
Se o e-mail foi confirmado.
customers[].registered_atstring
Quando a conta foi criada.
customers[].person_typestring
FJ
F pessoa física, J pessoa jurídica.
customers[].cpfstring
CPF, sem máscara. Ausente se não há.
customers[].cnpjstring
CNPJ, sem máscara. Ausente se não há.
customers[].legal_namestring
Razão social (PJ).
customers[].trade_namestring
Nome fantasia (PJ).
customers[].display_namestring
Melhor nome para exibir: fantasia, razão social ou nome da pessoa.
customers[].in_portfolioboolean
Se o cliente está na carteira própria do seller.
customers[].days_since_last_orderinteger
Dias desde o último pedido neste seller. Ausente se nunca comprou.
customers[].days_overdueinteger
Dias além da frequência esperada. 0 quando em dia ou quando a frequência não está configurada.
customers[].expected_order_freq_daysinteger
Frequência esperada do seller, em dias (0 = não configurada). É igual para todos os clientes.

Detalhe de um cliente

Chamando GET /api/v1/vendor/customers?id={uuid} você recebe um único objeto, sem envelope. Só funciona para clientes que já têm pedido com o seller: qualquer outro usuário responde 404, para o seller não inspecionar contas alheias.

200Detalhe do cliente
json
{
  "user_id": "4f44f104-bbe0-4d2e-b497-c1afbe19d7c5",
  "first_name": "Vinícius",
  "last_name": "Nunes",
  "email": "vinicius.nunes@example.com",
  "phone": "+5551953268977",
  "cpf": "123.456.789-09",
  "language": "pt-BR",
  "registered_at": "2026-05-31T15:59:45Z",
  "city": "",
  "state": "",
  "person_type": "F",
  "display_name": "Vinícius Nunes",
  "order_count": 45,
  "total_spent": 4366331,
  "first_order_at": "2026-05-31T16:46:46Z",
  "last_order_at": "2026-09-04T19:44:46.593557Z",
  "in_portfolio": false,
  "days_since_last_order": 37,
  "days_overdue": 0,
  "expected_order_freq_days": 0
}

O detalhe repete os campos da lista e acrescenta language (idioma do cliente). Não traz status, user_type nem email_verified. Como na lista, pedidos cancelados e reembolsados não entram nos totais.

Resumo da base

GET/api/v1/vendor/customers/statsSeller

Totais da base de clientes do seller

Resume a base de clientes do seller em cinco números.

200Totais
json
{
  "total_customers": 7187,
  "repeat_customers": 4596,
  "total_revenue": 2737977730,
  "avg_order_value": 67354,
  "total_orders": 40650
}

Campos da resposta

total_customersinteger
Clientes distintos que compraram do seller.
repeat_customersinteger
Clientes com 2 ou mais pedidos.
total_revenueinteger
Receita total, em centavos.
avg_order_valueinteger
Ticket médio, em centavos.
total_ordersinteger
Total de pedidos.

Exportar em CSV

GET/api/v1/vendor/customers/exportSeller

Baixa todos os clientes do seller em CSV

Devolve todos os clientes (sem paginação) como arquivo text/csv em UTF-8 com BOM, para abrir direto no Excel. O nome vem em Content-Disposition: vendor-customers-AAAA-MM-DD.csv. Aqui o valor gasto vem em reais com ponto decimal, não em centavos.

Colunas, nesta ordem: User ID, First Name, Last Name, Email, Phone, City, State, Order Count, Total Spent (BRL), First Order (AAAA-MM-DD), Last Order, Person Type, Legal Name, Trade Name, CPF, CNPJ, In Portfolio (Y ou N), Days Since Last Order (- para quem nunca comprou), Days Overdue. Os cabeçalhos ficam em inglês.

Exemplo de requisição: exportar

bash
curl "$BASE_URL/api/v1/vendor/customers/export" \
  -H "Authorization: Bearer $TOKEN" \
  -o clientes.csv

Erros

StatusQuandoCorpo de exemplo
401Sem token.{"error":"AUTH_REQUIRED"}
404O usuário não tem seller, ou o cliente do ?id= não comprou deste seller.{"error":"VENDOR_NOT_FOUND"} ou {"error":"VENDOR_CUSTOMER_NOT_FOUND"}
500id que não é UUID válido.{"error":"VENDOR_CUSTOMER_DETAIL_FAILED","detail":"o valor \"abc\" não é um uuid válido. ..."}
500Falha ao montar a lista, o resumo ou o CSV. O código depende da rota: VENDOR_CUSTOMERS_LIST_FAILED (lista), VENDOR_CUSTOMER_STATS_FAILED (resumo), VENDOR_CUSTOMERS_EXPORT_FAILED (exportação).{"error":"VENDOR_CUSTOMERS_LIST_FAILED","detail":"..."}
Lista vazia é null

Se nenhum cliente combina com a busca ou o filtro, a resposta é {"customers": null, "total": 0, ...}. Faça customers ?? [] antes de percorrer.

O que conta como compra

Pedidos cancelados, reembolsados e semelhantes não entram em order_count, total_spent nem nas datas, tanto na lista quanto no detalhe. O que conta como "não compra" segue os status configurados pela loja.

Veja também

  • Carteira, importação e frequência
  • Grupos de clientes
  • Pedidos do seller
Anterior
Clientes do seller
Próxima
Carteira, importação e frequência
Nesta página
  • Listar clientes
  • Exemplo de requisição: listar
  • Resposta: listar
  • Detalhe de um cliente
  • Resumo da base
  • Exportar em CSV
  • Exemplo de requisição: exportar
  • Erros
  • Veja também