VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Armazém e separação

Listas de separação

Lista, consulta e cria as listas de separação dos pedidos do seller.

Listar listas de separação

Uma lista de separação (picking list) é a tarefa de ir ao estoque buscar os itens de um pedido. Quando um pedido do seller é criado e o seller já tem ao menos um depósito, a plataforma cria a lista sozinha. A listagem devolve só o cabeçalho (items vazio).

GET/api/v1/vendor/erp/pickingSeller

Lista as listas de separação

Parâmetros de consulta

statusstring
openpickingpackedcancelled
Estado da lista. Valor desconhecido devolve lista vazia.
pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar listas de separação

bash
curl "$BASE_URL/api/v1/vendor/erp/picking?status=open" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar listas de separação

200Listas retornadas
json
{
  "lists": [
    {
      "id": "10426b19-4e8e-48b1-98a5-dae83ff3ab29",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39",
      "order_number": "PEDIDO-20261011-0004",
      "status": "open",
      "assigned_to": null,
      "notes": "",
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z",
      "item_count": 1,
      "items": []
    }
  ],
  "total": 1
}

Campos da resposta

listsarray

Listas da página, mais novas primeiro.

iduuid
Id da lista de separação.
vendor_iduuid
Seller dono.
order_iduuid
Pedido a separar. Há uma única lista por pedido.
order_numberstring
Número do pedido mostrado ao cliente. Pode vir vazio.
statusstring
openpickingpackedcancelled
Estado da lista.
assigned_touuid
Usuário que assumiu a lista. null enquanto open.
notesstring
Anotação; recebe o motivo do cancelamento.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
item_countinteger
Número de itens. Atenção: a rota de detalhe devolve sempre 0; conte o vetor items.
itemsarray

Itens da lista. Vazio na listagem; preenchido no detalhe e nas ações.

iduuid
Id do item.
picking_list_iduuid
Lista a que o item pertence.
product_iduuid
Produto a separar.
product_namestring
Nome do produto no momento da criação da lista.
requested_qtyinteger
Quantidade pedida.
picked_qtyinteger
Quantidade já separada (começa em 0).
shortage_reasonstring
Motivo da falta, preenchido quando picked_qty < requested_qty.
updated_atdatetime
Última alteração.
totalinteger
Total que atende ao filtro.

Erros: Listar listas de separação

StatusQuandoCorpo
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Consultar lista

GET/api/v1/vendor/erp/picking/{id}Seller

Consulta uma lista de separação

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da lista de separação.

Exemplo de requisição: Consultar lista

bash
curl "$BASE_URL/api/v1/vendor/erp/picking/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Consultar lista

200Lista com itens
json
{
  "id": "10426b19-4e8e-48b1-98a5-dae83ff3ab29",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39",
  "order_number": "PEDIDO-20261011-0004",
  "status": "open",
  "assigned_to": null,
  "notes": "",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z",
  "item_count": 0,
  "items": [
    {
      "id": "d70ce8fe-594a-411f-ba3b-7ef97fbc1ce2",
      "picking_list_id": "10426b19-4e8e-48b1-98a5-dae83ff3ab29",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Notebook Slim Rosa",
      "requested_qty": 2,
      "picked_qty": 0,
      "shortage_reason": "",
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ]
}

Campos da resposta

iduuid
Id da lista de separação.
vendor_iduuid
Seller dono.
order_iduuid
Pedido a separar. Há uma única lista por pedido.
order_numberstring
Número do pedido mostrado ao cliente. Pode vir vazio.
statusstring
openpickingpackedcancelled
Estado da lista.
assigned_touuid
Usuário que assumiu a lista. null enquanto open.
notesstring
Anotação; recebe o motivo do cancelamento.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
item_countinteger
Número de itens. Atenção: a rota de detalhe devolve sempre 0; conte o vetor items.
itemsarray

Itens da lista. Vazio na listagem; preenchido no detalhe e nas ações.

iduuid
Id do item.
picking_list_iduuid
Lista a que o item pertence.
product_iduuid
Produto a separar.
product_namestring
Nome do produto no momento da criação da lista.
requested_qtyinteger
Quantidade pedida.
picked_qtyinteger
Quantidade já separada (começa em 0).
shortage_reasonstring
Motivo da falta, preenchido quando picked_qty < requested_qty.
updated_atdatetime
Última alteração.

Erros: Consultar lista

StatusQuandoCorpo
404A lista não existe ou é de outro seller.{"error":"picking list not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Criar lista a partir de um pedido

Gera a lista de separação de um pedido do seller, com um item por linha do pedido. É idempotente: se o pedido já tem lista, devolve a existente (também com 201). Use quando a criação automática não aconteceu, por exemplo para pedidos antigos.

POST/api/v1/vendor/erp/picking/from-orderSeller

Cria a lista de separação de um pedido

Corpo da requisição

order_iduuidobrigatório
Pedido do seller. Um pedido pai (sem seller) é recusado.

Exemplo de requisição: Criar lista a partir de um pedido

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/picking/from-order" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39"
}'

Resposta: Criar lista a partir de um pedido

201Lista criada ou já existente
json
{
  "id": "10426b19-4e8e-48b1-98a5-dae83ff3ab29",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_id": "87fdfd05-07bf-4031-a468-219fc35e4e39",
  "order_number": "PEDIDO-20261011-0004",
  "status": "open",
  "assigned_to": null,
  "notes": "",
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z",
  "item_count": 1,
  "items": [
    {
      "id": "d70ce8fe-594a-411f-ba3b-7ef97fbc1ce2",
      "picking_list_id": "10426b19-4e8e-48b1-98a5-dae83ff3ab29",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Notebook Slim Rosa",
      "requested_qty": 2,
      "picked_qty": 0,
      "shortage_reason": "",
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ]
}

Campos da resposta

iduuid
Id da lista de separação.
vendor_iduuid
Seller dono.
order_iduuid
Pedido a separar. Há uma única lista por pedido.
order_numberstring
Número do pedido mostrado ao cliente. Pode vir vazio.
statusstring
openpickingpackedcancelled
Estado da lista.
assigned_touuid
Usuário que assumiu a lista. null enquanto open.
notesstring
Anotação; recebe o motivo do cancelamento.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
item_countinteger
Número de itens. Atenção: a rota de detalhe devolve sempre 0; conte o vetor items.
itemsarray

Itens da lista. Vazio na listagem; preenchido no detalhe e nas ações.

iduuid
Id do item.
picking_list_iduuid
Lista a que o item pertence.
product_iduuid
Produto a separar.
product_namestring
Nome do produto no momento da criação da lista.
requested_qtyinteger
Quantidade pedida.
picked_qtyinteger
Quantidade já separada (começa em 0).
shortage_reasonstring
Motivo da falta, preenchido quando picked_qty < requested_qty.
updated_atdatetime
Última alteração.

Erros: Criar lista a partir de um pedido

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400order_id em branco.{"error":"vendorerp: order_id required"}
404O pedido não existe ou é de outro seller.{"error":"order not found"}
400O pedido é um pedido pai, sem seller.{"error":"vendorerp: order has no vendor (parent order)"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Veja também

  • Fluxo de separação
  • Endereços
Anterior
Saldos por endereço
Próxima
Fluxo de separação
Nesta página
  • Listar listas de separação
  • Exemplo de requisição: Listar listas de separação
  • Resposta: Listar listas de separação
  • Erros: Listar listas de separação
  • Consultar lista
  • Exemplo de requisição: Consultar lista
  • Resposta: Consultar lista
  • Erros: Consultar lista
  • Criar lista a partir de um pedido
  • Exemplo de requisição: Criar lista a partir de um pedido
  • Resposta: Criar lista a partir de um pedido
  • Erros: Criar lista a partir de um pedido
  • Veja também