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

Importar e mover carteira

Substitui a carteira, importa clientes por CNPJ/CPF a partir de planilha, transfere ou copia clientes entre representantes e restaura vínculos temporários vencidos.

Operações em massa sobre a carteira. Quase todas trabalham por seller (vendor_id): o vendor_id vazio significa os vínculos globais (sem seller), e é preciso mandar o vendor_id do seller quando os representantes são do modo do seller.

Substituir a carteira

Apaga os vínculos permanentes do representante para aquele vendor_id e grava a lista enviada no lugar. Vínculos temporários e cópias não são tocados.

PUT/api/v1/admin/trade-reps/{id}/portfolioAdmin

Substitui os clientes permanentes de um representante

Parâmetros de caminho

idintegerobrigatório
Id do representante.

Corpo da requisição

customer_idsarrayobrigatório
Ids (UUID) dos clientes que ficam na carteira. Lista vazia limpa os vínculos permanentes.
vendor_idstring
Seller dos vínculos. Vazio = vínculos globais.
200Carteira substituída
json
{ "status": "ok", "count": 1 }

Importar clientes por CNPJ ou CPF

Resolve cada documento para um cliente da loja e o coloca na carteira. Aceita planilha (.xlsx ou .csv, até 8 MB, multipart/form-data) ou JSON com a lista colada. Use dry_run para ver o que aconteceria antes de gravar.

POST/api/v1/admin/trade-reps/{id}/portfolio/importAdmin

Importa a carteira a partir de documentos

Parâmetros de caminho

idintegerobrigatório
Id do representante.

Corpo da requisição (JSON)

documentsarray
Lista de CNPJ/CPF, com ou sem pontuação.
textstring
Texto colado com documentos separados por quebra de linha, vírgula, ponto e vírgula, tabulação ou espaço. Soma-se a documents.
dry_runbooleanpadrão: false
true resolve e relata sem gravar.
assign_if_elsewherebooleanpadrão: true
false pula clientes que já estão na carteira de outro representante.

Campos de formulário (planilha)

filefileobrigatório
Planilha .xlsx ou .csv. Toda célula com 10, 11, 13 ou 14 dígitos vira candidata a documento; o cabeçalho é ignorado.
dry_runstring
true1
Igual ao JSON.
assign_if_elsewherestring
false0
Igual ao JSON.
bash
curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/portfolio/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@carteira.xlsx" \
  -F "dry_run=true"
200Relatório da importação
json
{
  "dry_run": true,
  "total": 1,
  "assigned": 1,
  "already_in_portfolio": 0,
  "no_account": 0,
  "skipped_other_rep": 0,
  "invalid_document": 0,
  "rows": [
    {
      "input": "11222333000181",
      "document": "11222333000181",
      "status": "assigned",
      "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "name": "Priscila Gomes",
      "email": "priscila.gomes@example.com"
    }
  ]
}

Campos da resposta

dry_runboolean
Se foi só simulação.
totalinteger
Documentos processados.
assignedinteger
Colocados na carteira (ou que seriam, em dry_run).
already_in_portfoliointeger
Já estavam na carteira.
no_accountinteger
Nenhum cliente da loja tem esse documento.
skipped_other_repinteger
Pulados por estarem com outro representante (assign_if_elsewhere: false).
invalid_documentinteger
Documento inválido.
rowsarray
Um item por documento, com status igual a um dos contadores acima (assigned, already_in_portfolio, no_account, skipped_other_rep, invalid_document).
rows[].other_repsarray
Nomes de outros representantes que já têm o cliente. Informativo.
Planilha do Excel perde o zero à esquerda

Quando um CNPJ vira número no Excel ele perde o zero inicial (13 dígitos em vez de 14). A importação repõe o zero automaticamente em valores só numéricos, então a planilha pode ser usada como veio.

Transferir clientes

Move clientes de um representante para outro. Os dois precisam ter o mesmo owner_vendor_id. A transferência fica registrada com quem a fez.

POST/api/v1/admin/trade-reps/transferAdmin

Transfere clientes entre representantes

Corpo da requisição

from_rep_idintegerobrigatório
Representante de origem.
to_rep_idintegerobrigatório
Representante de destino. Diferente da origem.
customer_idsarray
Clientes a mover. Vazio (ou all_filtered: true) move toda a carteira ativa da origem para o vendor_id informado.
all_filteredboolean
true ignora customer_ids e move tudo.
kindstringpadrão: permanent
permanenttemporarypt
temporary (ou t) exige valid_until; ao vencer, o cliente pode voltar ao representante de origem.
valid_untilstring
Data final (RFC 3339) da transferência temporária.
vendor_idstring
Seller dos vínculos a mover. Vazio = vínculos globais.
200Resultado
json
{ "moved": 1, "copied": 0, "skipped": 0 }

Campos da resposta

movedinteger
Clientes movidos.
copiedinteger
Clientes copiados (só na cópia).
skippedinteger
Clientes que não estavam na carteira de origem com aquele vendor_id.

Copiar clientes

Igual à transferência, mas o cliente continua com a origem: passa a ter vínculo copy também com o destino.

POST/api/v1/admin/trade-reps/copyAdmin

Copia clientes para outro representante

Corpo da requisição

from_rep_idintegerobrigatório
Representante de origem.
to_rep_idintegerobrigatório
Representante de destino.
customer_idsarray
Clientes a copiar. Vazio (ou all_filtered: true) copia toda a carteira ativa da origem.
all_filteredboolean
true copia tudo.
temporaryboolean
true exige valid_until.
valid_untilstring
Data final da cópia temporária (RFC 3339).
vendor_idstring
Seller dos vínculos. Vazio = globais.

A resposta tem o mesmo formato da transferência, com copied preenchido.

Restaurar vínculos temporários vencidos

Devolve ao representante original os clientes de transferências temporárias que já passaram de valid_until e remove as cópias temporárias vencidas. Rode periodicamente (por exemplo, uma vez por dia) ou depois de uma data de corte.

POST/api/v1/admin/trade-reps/restore-expiredAdmin

Restaura vínculos temporários vencidos

200Restaurados
json
{ "restored": 3 }

Erros

StatusQuandoCorpo de exemplo
400id não é inteiro, ou corpo não é JSON.{"error":"invalid trade rep ID"}
400Importação sem nenhum documento reconhecido.{"error":"no documents found in the input"}
400Falta file no envio de planilha, ou arquivo ilegível.{"error":"file is required","detail":"..."}
400Transferência ou cópia inválida (origem e destino iguais, representantes de sellers diferentes, valid_until ausente, nada selecionado).{"error":"transfer failed","detail":"origin and destination must share the same owner_vendor_id"}
500Falha ao substituir ou importar (por exemplo, customer_id inexistente).{"error":"replace portfolio failed","detail":"..."}
401 / 403Sem token, módulo desligado ou sem privilégio.{"error":"module_disabled","module":"trade-reps"}
Corpo sem customer_ids move tudo

{"from_rep_id":2,"to_rep_id":30} transfere a carteira inteira de 2 para 30. Se a intenção é mover clientes específicos, envie sempre customer_ids preenchido. Faça um GET da carteira antes para conferir o tamanho.

Veja também

  • Carteira de clientes
  • Visão geral
Anterior
Carteira de clientes
Próxima
Sellers atendidos
Nesta página
  • Substituir a carteira
  • Importar clientes por CNPJ ou CPF
  • Transferir clientes
  • Copiar clientes
  • Restaurar vínculos temporários vencidos
  • Erros
  • Veja também