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

Fluxo de separação

Assume a lista, separa item a item, embala ou cancela.

Assumir lista

Marca você como responsável pela lista e muda o estado de open para picking. Só uma lista open pode ser assumida.

POST/api/v1/vendor/erp/picking/{id}/claimSeller

Assume uma lista de separação

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da lista.

Exemplo de requisição: Assumir lista

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

Resposta: Assumir lista

200Lista assumida
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": "picking",
  "assigned_to": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "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: Assumir lista

StatusQuandoCorpo
400A lista não está open.{"error":"cannot claim list in status \"picking\""}
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"}

Separar item

Informa quanto de um item foi realmente separado. Pode ser chamada de novo para corrigir. Se separar menos do que o pedido, é preciso dizer o motivo da falta.

POST/api/v1/vendor/erp/picking/{id}/items/{itemId}/pickSeller

Registra a quantidade separada de um item

Parâmetros de caminho

iduuidobrigatório
Id da lista.
itemIduuidobrigatório
Id do item da lista (campo items[].id).

Corpo da requisição

quantityintegerobrigatório
Quantidade separada, de 0 até requested_qty. É o total do item, não um acréscimo.
shortage_reasonstring
Obrigatório quando quantity < requested_qty. Ignorado quando o item foi separado por inteiro.

Exemplo de requisição: Separar item

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/picking/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/items/8c5e2d3a-41b7-4f0a-9d6e-7a2b1c0d9e11/pick" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 1,
  "shortage_reason": "Uma unidade avariada"
}'

Resposta: Separar item

200Lista atualizada
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": "picking",
  "assigned_to": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "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": 1,
      "shortage_reason": "Uma unidade avariada",
      "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: Separar item

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400A lista não está em picking (assuma-a antes).{"error":"vendorerp: list is not in picking"}
400quantity negativa.{"error":"vendorerp: picked qty cannot be negative"}
400quantity maior que requested_qty.{"error":"vendorerp: picked qty exceeds requested"}
400Separou menos que o pedido sem informar shortage_reason.{"error":"vendorerp: shortage reason required when picking less than requested"}
404A lista ou o item não existe.{"error":"picking item 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"}

Embalar lista

Conclui a separação: o estado vai de picking para packed. A plataforma não confere se todos os itens foram separados e não mexe em estoque nem no status do pedido; atualize o pedido pelo fluxo de pedidos.

POST/api/v1/vendor/erp/picking/{id}/packSeller

Marca a lista como embalada

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da lista.

Exemplo de requisição: Embalar lista

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

Resposta: Embalar lista

200Lista embalada
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": "packed",
  "assigned_to": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "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: Embalar lista

StatusQuandoCorpo
400A lista não está em picking.{"error":"cannot move list from \"open\" to \"packed\""}
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"}

Cancelar lista

Cancela uma lista open ou picking. Uma lista packed ou já cancelled não pode ser cancelada.

POST/api/v1/vendor/erp/picking/{id}/cancelSeller

Cancela uma lista de separação

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da lista.

Corpo da requisição

reasonstring
Motivo, gravado em notes. O corpo inteiro é opcional.

Exemplo de requisição: Cancelar lista

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/picking/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Pedido cancelado pelo cliente"
}'

Resposta: Cancelar lista

200Lista cancelada
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": "cancelled",
  "assigned_to": null,
  "notes": "Pedido cancelado pelo cliente",
  "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: Cancelar lista

StatusQuandoCorpo
400A lista já foi embalada ou cancelada.{"error":"cannot move list from \"packed\" to \"cancelled\""}
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"}
Um corpo vazio é válido

claim e pack não leem corpo. cancel lê reason se existir, e ignora um corpo inválido.

Veja também

  • Listas de separação
Anterior
Listas de separação
Próxima
Canais de venda
Nesta página
  • Assumir lista
  • Exemplo de requisição: Assumir lista
  • Resposta: Assumir lista
  • Erros: Assumir lista
  • Separar item
  • Exemplo de requisição: Separar item
  • Resposta: Separar item
  • Erros: Separar item
  • Embalar lista
  • Exemplo de requisição: Embalar lista
  • Resposta: Embalar lista
  • Erros: Embalar lista
  • Cancelar lista
  • Exemplo de requisição: Cancelar lista
  • Resposta: Cancelar lista
  • Erros: Cancelar lista
  • Veja também