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

Endereços do armazém

Cadastra, lista, altera, apaga e importa em lote os endereços (corredor, prateleira, posição) dentro dos depósitos.

Listar endereços

Um endereço (location) é uma posição dentro de um depósito: corredor (aisle), prateleira (shelf) ou posição de caixa (bin). É o que permite dizer onde exatamente um produto está. A lista vem ordenada por depósito e por código, sem paginação.

GET/api/v1/vendor/erp/wms/locationsSeller

Lista os endereços do armazém

Parâmetros de consulta

warehouse_iduuid
Só endereços deste depósito.

Exemplo de requisição: Listar endereços

Resposta: Listar endereços

200Endereços retornados

Campos da resposta

locationsarray

Endereços.

iduuid
Id do endereço.
vendor_iduuid
Seller dono.
warehouse_iduuid
Depósito onde o endereço fica.
warehouse_namestring
Nome do depósito.
codestring
Código do endereço, único dentro do depósito (por exemplo A-01-03).
typestring
aisleshelfbin
Nível do endereço.
activeboolean
Se o endereço está em uso.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.
totalinteger
Quantidade devolvida.

Erros: Listar endereços

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list locations","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
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 endereço

POST/api/v1/vendor/erp/wms/locationsSeller

Cria um endereço

Corpo da requisição

warehouse_iduuidobrigatório
Depósito do seller onde o endereço fica.
codestringobrigatório
Código do endereço. Único por depósito entre os não apagados.
typestringobrigatório
aisleshelfbin
Nível do endereço. Aceita maiúsculas.
activebooleanpadrão: true
Se o endereço está em uso.

Exemplo de requisição: Criar endereço

Resposta: Criar endereço

201Endereço criado

Campos da resposta

iduuid
Id do endereço.
vendor_iduuid
Seller dono.
warehouse_iduuid
Depósito onde o endereço fica.
warehouse_namestring
Nome do depósito.
codestring
Código do endereço, único dentro do depósito (por exemplo A-01-03).
typestring
aisleshelfbin
Nível do endereço.
activeboolean
Se o endereço está em uso.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Criar endereço

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400code em branco.{"error":"vendorerp: code required"}
400type inválido.{"error":"vendorerp: type must be aisle|shelf|bin"}
400warehouse_id ausente.{"error":"vendorerp: warehouse_id required"}
404O depósito não existe ou é de outro seller.{"error":"warehouse not found"}
400Já existe um endereço com esse código no depósito (a plataforma devolve uma mensagem genérica de banco de dados).{"error":"a database error occurred"}
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"}

Alterar endereço

Substitui os dados do endereço (PUT completo: warehouse_id, code e type são obrigatórios).

PUT/api/v1/vendor/erp/wms/locations/{id}Seller

Altera um endereço

Parâmetros de caminho

iduuidobrigatório
Id (UUID) do endereço.

Corpo da requisição

warehouse_iduuidobrigatório
Depósito do seller onde o endereço fica.
codestringobrigatório
Código do endereço. Único por depósito entre os não apagados.
typestringobrigatório
aisleshelfbin
Nível do endereço. Aceita maiúsculas.
activebooleanpadrão: true
Se o endereço está em uso.

Exemplo de requisição: Alterar endereço

Resposta: Alterar endereço

200Endereço alterado

Campos da resposta

iduuid
Id do endereço.
vendor_iduuid
Seller dono.
warehouse_iduuid
Depósito onde o endereço fica.
warehouse_namestring
Nome do depósito.
codestring
Código do endereço, único dentro do depósito (por exemplo A-01-03).
typestring
aisleshelfbin
Nível do endereço.
activeboolean
Se o endereço está em uso.
created_atdatetime
Criação.
updated_atdatetime
Última alteração.

Erros: Alterar endereço

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400code em branco.{"error":"vendorerp: code required"}
400type inválido.{"error":"vendorerp: type must be aisle|shelf|bin"}
404O depósito não existe ou é de outro seller.{"error":"warehouse not found"}
404O endereço não existe ou é de outro seller.{"error":"location 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"}
Omitir active reativa o endereço

active vale true quando não vem no corpo.

Apagar endereço

Faz a exclusão lógica do endereço. Diferente do depósito, o endereço pode ser apagado mesmo com saldo; as linhas de saldo dele deixam de aparecer em Saldos por endereço.

DELETE/api/v1/vendor/erp/wms/locations/{id}Seller

Apaga um endereço

Parâmetros de caminho

iduuidobrigatório
Id (UUID) do endereço.

Exemplo de requisição: Apagar endereço

Resposta: Apagar endereço

200Endereço apagado

Campos da resposta

messagestring
Sempre location deleted.

Erros: Apagar endereço

StatusQuandoCorpo
404O endereço não existe ou é de outro seller.{"error":"location 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"}

Importar endereços

Cria vários endereços de uma vez a partir de um texto CSV enviado no JSON (não é upload de arquivo). Cada linha tem código e, opcionalmente, tipo; o separador pode ser vírgula ou ponto e vírgula e uma primeira linha de cabeçalho (code, codigo, código, endereco ou endereço) é ignorada. Sem tipo, vale bin. A importação não é atômica: linhas válidas são criadas mesmo que outras falhem.

POST/api/v1/vendor/erp/wms/locations/importSeller

Importa endereços de um CSV

Corpo da requisição

warehouse_iduuidobrigatório
Depósito de destino de todos os endereços.
contentstringobrigatório
Texto CSV, uma linha por endereço, por exemplo A-01-01,bin com quebras de linha \n.

Exemplo de requisição: Importar endereços

Resposta: Importar endereços

200Resultado da importação

Campos da resposta

createdinteger
Endereços criados.
duplicatesinteger
Linhas ignoradas porque o código já existe no depósito.
errorsarray
Uma mensagem em português por linha recusada, com o número da linha.

Erros: Importar endereços

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400warehouse_id ausente.{"error":"vendorerp: warehouse_id required"}
404O depósito não existe ou é de outro seller.{"error":"warehouse 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"}

Veja também

  • Saldos por endereço
  • Depósitos do ERP de estoque
Anterior
ERP de armazém e separação
Próxima
Saldos por endereço
Nesta página
  • Listar endereços
  • Exemplo de requisição: Listar endereços
  • Resposta: Listar endereços
  • Erros: Listar endereços
  • Criar endereço
  • Exemplo de requisição: Criar endereço
  • Resposta: Criar endereço
  • Erros: Criar endereço
  • Alterar endereço
  • Exemplo de requisição: Alterar endereço
  • Resposta: Alterar endereço
  • Erros: Alterar endereço
  • Apagar endereço
  • Exemplo de requisição: Apagar endereço
  • Resposta: Apagar endereço
  • Erros: Apagar endereço
  • Importar endereços
  • Exemplo de requisição: Importar endereços
  • Resposta: Importar endereços
  • Erros: Importar endereços
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/erp/wms/locations?warehouse_id=8204b8b8-e7e2-4b96-bba8-5a937fe001c8" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/wms/locations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "code": "A-01-03",
  "type": "bin"
}'
bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/wms/locations/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "code": "A-01-04",
  "type": "bin",
  "active": true
}'
bash
curl -X DELETE "$BASE_URL/api/v1/vendor/erp/wms/locations/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/wms/locations/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "content": "code,type\nA-01-01,bin\nA-01-02,bin\nA-02,shelf"
}'
json
{
  "locations": [
    {
      "id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
      "warehouse_name": "Depósito Central",
      "code": "A-01-03",
      "type": "bin",
      "active": true,
      "created_at": "2026-10-11T14:30:00Z",
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}
json
{
  "id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "warehouse_name": "Depósito Central",
  "code": "A-01-03",
  "type": "bin",
  "active": true,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}
json
{
  "id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "warehouse_name": "Depósito Central",
  "code": "A-01-04",
  "type": "bin",
  "active": true,
  "created_at": "2026-10-11T14:30:00Z",
  "updated_at": "2026-10-11T14:30:00Z"
}
json
{
  "message": "location deleted"
}
json
{
  "created": 2,
  "duplicates": 1,
  "errors": [
    "linha 4 (B-9): tipo inválido \"rack\", use aisle|shelf|bin"
  ]
}