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

Carteira, importação e frequência

Põe e tira clientes da carteira própria do seller, liga clientes por CPF ou CNPJ com prévia e define a frequência de compra esperada.

A carteira própria é a lista de clientes que o seller quer acompanhar, tenham ou não comprado dele. Serve para o vendedor que já conhece seus clientes (de uma planilha, do ERP, da rua) e quer vê-los no painel antes do primeiro pedido, para saber quem nunca comprou. Estar na carteira é só um vínculo entre o seller e o cliente: não cria nem altera o usuário.

Quatro operações cuidam disso. Todas agem sobre o seller do token.

Pôr clientes na carteira

POST/api/v1/vendor/customers/portfolioSeller

Põe clientes existentes na carteira do seller

Liga os clientes informados à carteira. Repetir é seguro: quem já estava conta em already_there e não gera erro. Um id que não corresponde a nenhum usuário volta em not_found e o resto do lote segue.

Corpo da requisição

customer_idsarrayobrigatório
Ids (UUID) dos clientes. Pelo menos um. Todos precisam ser UUIDs válidos: um id malformado derruba a chamada inteira.
200Resultado do vínculo
json
{ "assigned": 1, "already_there": 0 }

Campos da resposta

assignedinteger
Clientes que entraram agora na carteira.
already_thereinteger
Clientes que já estavam.
not_foundarray
Ids sem usuário correspondente. Ausente quando todos foram achados.

Tirar clientes da carteira

DELETE/api/v1/vendor/customers/portfolioSeller

Tira clientes da carteira do seller

Remove só o vínculo com o seller. O cliente continua cadastrado, continua na carteira de outros sellers e, se tem pedidos com este seller, continua aparecendo na lista (agora sem in_portfolio).

Corpo da requisição

customer_idsarrayobrigatório
Ids (UUID) dos clientes a tirar. Pelo menos um.
200Clientes removidos
json
{ "removed": 1 }

Importar por CPF ou CNPJ

POST/api/v1/vendor/customers/importSeller

Liga clientes à carteira a partir de CPF ou CNPJ

Recebe uma lista de documentos e liga à carteira o cliente que tem cada um. É a rota para quem tem uma planilha de CPFs/CNPJs. Cada linha é decidida por si: uma inválida não derruba as outras.

Use dry_run: true primeiro: a plataforma confere tudo e devolve o que aconteceria, sem gravar nada. Depois repita sem dry_run.

Corpo da requisição

documentsarrayobrigatório
Lista de CPFs ou CNPJs, com ou sem pontuação. Pelo menos um. Linhas em branco são ignoradas.
dry_runbooleanpadrão: false
Se true, só simula.
200Prévia da importação
json
{
  "dry_run": true,
  "total": 3,
  "assigned": 1,
  "already_there": 0,
  "invalid": 1,
  "not_found": 1,
  "ambiguous": 0,
  "lines": [
    { "line": 1, "document": "123.456.789-09", "normalized": "12345678909", "status": "assigned", "customer_id": "91edc551-55cd-441e-b06a-360e34910f02" },
    { "line": 2, "document": "11111111111", "status": "invalid_document", "message": "não é um CPF nem um CNPJ válido" },
    { "line": 3, "document": "98765432100", "normalized": "98765432100", "status": "customer_not_found", "message": "nenhum cliente cadastrado com este documento" }
  ]
}

Campos da resposta

dry_runboolean
Se foi só simulação.
totalinteger
Linhas não vazias processadas.
assignedinteger
Linhas que entraram na carteira (ou entrariam, na simulação).
already_thereinteger
Linhas cujo cliente já estava na carteira.
invalidinteger
Linhas que não são CPF ou CNPJ válido.
not_foundinteger
Linhas válidas sem cliente cadastrado com o documento.
ambiguousinteger
Linhas cujo documento pertence a mais de um cliente.
linesarray
Desfecho de cada linha, na ordem enviada.
lines[].lineinteger
Posição na lista enviada, a partir de 1 (conta também as linhas em branco).
lines[].documentstring
Documento como enviado.
lines[].normalizedstring
Só dígitos. Ausente se o documento é inválido.
lines[].statusstring
assignedalready_thereinvalid_documentcustomer_not_foundambiguous_document
Desfecho da linha.
lines[].customer_iduuid
Cliente encontrado, quando há exatamente um.
lines[].messagestring
Explicação, em português, do desfecho quando não é assigned.

Definir a frequência de compra esperada

PUT/api/v1/vendor/customers/expected-frequencySeller

Define o intervalo esperado entre compras, em dias

Informa de quantos em quantos dias o seller espera que um cliente volte a comprar. É uma configuração do seller, igual para todos os clientes. A lista passa a trazer days_overdue e o filtro overdue passa a funcionar. 0 desliga.

Corpo da requisição

daysintegerobrigatório
Dias, maior ou igual a 0. Omitido vale 0.
200Frequência gravada
json
{ "expected_order_freq_days": 30 }

Exemplo de requisição

bash
# simular a importação
curl -X POST "$BASE_URL/api/v1/vendor/customers/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents": ["123.456.789-09", "12.345.678/0001-95"], "dry_run": true}'

# repetir sem dry_run para gravar
curl -X POST "$BASE_URL/api/v1/vendor/customers/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents": ["123.456.789-09", "12.345.678/0001-95"]}'

# tirar da carteira
curl -X DELETE "$BASE_URL/api/v1/vendor/customers/portfolio" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_ids": ["4f44f104-bbe0-4d2e-b497-c1afbe19d7c5"]}'

# frequência esperada de 30 dias
curl -X PUT "$BASE_URL/api/v1/vendor/customers/expected-frequency" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days": 30}'

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON.{"error":"INVALID_BODY","detail":"..."}
400customer_ids vazio ou ausente.{"error":"CUSTOMER_IDS_REQUIRED"}
400documents vazio ou ausente.{"error":"DOCUMENTS_REQUIRED"}
400days negativo.{"error":"EXPECTED_FREQ_INVALID","detail":"frequência esperada não pode ser negativa"}
401Sem token.{"error":"AUTH_REQUIRED"}
404O usuário não tem seller.{"error":"VENDOR_NOT_FOUND"}
500Algum id de customer_ids não é UUID.{"error":"VENDOR_CUSTOMER_ASSIGN_FAILED","detail":"o valor \"abc\" não é um uuid válido. ..."}
500Falha ao gravar a carteira. O código depende da rota: VENDOR_CUSTOMER_ASSIGN_FAILED (incluir), VENDOR_CUSTOMER_REMOVE_FAILED (remover), VENDOR_CUSTOMER_IMPORT_FAILED (importar).{"error":"VENDOR_CUSTOMER_IMPORT_FAILED","detail":"..."}
Documento duplicado é recusado, não adivinhado

Se dois clientes têm o mesmo CPF ou CNPJ, a linha volta ambiguous_document e ninguém é ligado. Resolva o cadastro duplicado com a loja antes de importar de novo.

Simule antes de gravar

dry_run não grava nada. Rode sempre a prévia com uma planilha nova e só grave quando invalid, not_found e ambiguous estiverem como esperado.

Veja também

  • Lista e exportação de clientes
  • Grupos de clientes
  • Visão geral
Anterior
Lista e exportação de clientes
Próxima
Grupos de clientes do seller
Nesta página
  • Pôr clientes na carteira
  • Tirar clientes da carteira
  • Importar por CPF ou CNPJ
  • Definir a frequência de compra esperada
  • Exemplo de requisição
  • Erros
  • Veja também