Endpoints de remessas

Todas as URLs da API de remessas: listar e criar remessas, e consultar, atualizar ou excluir uma remessa pelo id.

A API de remessas gerencia as informações de remessa dos pedidos na plataforma Venddor. Esta página descreve as duas URLs da API e os métodos HTTP que cada uma aceita. A referência mostra a URL base como https://www.venddor.com.br/api; nos exemplos abaixo ela aparece como $BASE_URL/api.

A coleção de remessas

O caminho /shipments retorna todas as remessas (GET) ou cria uma remessa nova (POST).

Método	Descrição	Uso
GET	Retorna todas as remessas	Use os parâmetros de paginação para limitar os resultados. Veja Paginação.
POST	Cria uma remessa nova	Exige um corpo JSON com os detalhes da remessa.

GET/api/shipmentsAdmin

Retornar todas as remessas

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments"

Resposta

200Remessas retornadas

json

{
  "shipments": [
    {
      "shipment_id": 987,
      "order_id": 5432,
      "tracking_number": "BR54321X098Y",
      "carrier": "Correios Sedex",
      "shipping_date": "2025-04-15T08:30:00Z",
      "estimated_delivery_date": "2025-04-18T18:00:00Z",
      "status": "shipped",
      "shipping_cost": 25.50
    },
    {
      "shipment_id": 986,
      "order_id": 5431,
      "tracking_number": "BR54320X097Y",
      "carrier": "Correios PAC",
      "shipping_date": "2025-04-15T09:15:00Z",
      "estimated_delivery_date": "2025-04-22T18:00:00Z",
      "status": "shipped",
      "shipping_cost": 15.75
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 42
  }
}

POST/api/shipmentsAdmin

Criar uma remessa nova

Esta requisição exige um corpo JSON com os detalhes da remessa. A referência mostra este exemplo.

Exemplo de requisição

bash

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 5432,
  "shipping_method_id": 3,
  "tracking_number": "BR54321X098Y",
  "carrier": "Correios Sedex",
  "shipping_date": "2025-04-15T08:30:00Z",
  "estimated_delivery_date": "2025-04-18T18:00:00Z",
  "items": [
    {
      "product_id": 143,
      "quantity": 1
    },
    {
      "product_id": 156,
      "quantity": 2
    }
  ],
  "shipping_cost": 25.50,
  "tracking_url": "https://www.correios.com.br/rastreamento/BR54321X098Y",
  "notes": "Fragile items, handle with care"
}'

Uma remessa específica

O caminho /shipments/:id trabalha com uma remessa, identificada pelo id. Ele aceita GET, PUT e DELETE.

Método	Descrição	Uso
GET	Retorna uma remessa específica	Devolve informações detalhadas da remessa indicada
PUT	Atualiza uma remessa	Exige um corpo JSON com os campos a atualizar
DELETE	Exclui uma remessa	Remove a remessa do sistema de forma permanente

GET/api/shipments/{id}Admin

Consultar uma remessa específica

Parâmetros de caminho

idintegerobrigatório

O identificador único da remessa.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments/987"

Resposta

200Remessa retornada

json

{
  "shipment_id": 987,
  "order_id": 5432,
  "tracking_number": "BR54321X098Y",
  "carrier": "Correios Sedex",
  "shipping_date": "2025-04-15T08:30:00Z",
  "estimated_delivery_date": "2025-04-18T18:00:00Z",
  "actual_delivery_date": "2025-04-17T14:25:00Z",
  "status": "delivered",
  "shipping_cost": 25.50,
  "tracking_url": "https://www.correios.com.br/rastreamento/BR54321X098Y",
  "notes": "Fragile items, handle with care",
  "delivery_notes": "Package delivered to front desk",
  "items": [
    {
      "product_id": 143,
      "product_name": "Premium Wireless Headphones",
      "quantity": 1
    },
    {
      "product_id": 156,
      "product_name": "USB-C Charging Cable",
      "quantity": 2
    }
  ]
}

PUT/api/shipments/{id}Admin

Atualizar uma remessa

Parâmetros de caminho

idintegerobrigatório

O identificador único da remessa.

A requisição exige um corpo JSON com os campos a atualizar. A referência mostra este exemplo.

Exemplo de requisição

bash

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments/987" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "delivered",
  "actual_delivery_date": "2025-04-17T14:25:00Z",
  "delivery_notes": "Package delivered to front desk"
}'

DELETE/api/shipments/{id}Admin

Excluir uma remessa

Parâmetros de caminho

idintegerobrigatório

O identificador único da remessa.

Exemplo de requisição

bash

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments/987"

Valores de status da remessa

Esta página lista o status da remessa em forma de palavras.

Status	Descrição
`pending`	A remessa foi criada, mas ainda não foi processada
`processing`	O pedido está sendo preparado para envio
`shipped`	O pacote foi entregue à transportadora
`in_transit`	O pacote está em trânsito com a transportadora
`out_for_delivery`	O pacote saiu para entrega hoje
`delivered`	O pacote foi entregue com sucesso
`failed_delivery`	Houve uma tentativa de entrega, mas ela falhou
`returned`	O pacote foi devolvido ao remetente
`cancelled`	A remessa foi cancelada

Veja também

API legada/Referência completa/Remessas

Endpoints de remessas

Todas as URLs da API de remessas: listar e criar remessas, e consultar, atualizar ou excluir uma remessa pelo id.

A coleção de remessas

O caminho /shipments retorna todas as remessas (GET) ou cria uma remessa nova (POST).

Método	Descrição	Uso
GET	Retorna todas as remessas	Use os parâmetros de paginação para limitar os resultados. Veja Paginação.
POST	Cria uma remessa nova	Exige um corpo JSON com os detalhes da remessa.

GET/api/shipmentsAdmin

Retornar todas as remessas

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments"

Resposta

200Remessas retornadas

json

{
  "shipments": [
    {
      "shipment_id": 987,
      "order_id": 5432,
      "tracking_number": "BR54321X098Y",
      "carrier": "Correios Sedex",
      "shipping_date": "2025-04-15T08:30:00Z",
      "estimated_delivery_date": "2025-04-18T18:00:00Z",
      "status": "shipped",
      "shipping_cost": 25.50
    },
    {
      "shipment_id": 986,
      "order_id": 5431,
      "tracking_number": "BR54320X097Y",
      "carrier": "Correios PAC",
      "shipping_date": "2025-04-15T09:15:00Z",
      "estimated_delivery_date": "2025-04-22T18:00:00Z",
      "status": "shipped",
      "shipping_cost": 15.75
    }
  ],
  "params": {
    "page": 1,
    "items_per_page": 10,
    "total_items": 42
  }
}

POST/api/shipmentsAdmin

Criar uma remessa nova

Esta requisição exige um corpo JSON com os detalhes da remessa. A referência mostra este exemplo.

Exemplo de requisição

bash

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 5432,
  "shipping_method_id": 3,
  "tracking_number": "BR54321X098Y",
  "carrier": "Correios Sedex",
  "shipping_date": "2025-04-15T08:30:00Z",
  "estimated_delivery_date": "2025-04-18T18:00:00Z",
  "items": [
    {
      "product_id": 143,
      "quantity": 1
    },
    {
      "product_id": 156,
      "quantity": 2
    }
  ],
  "shipping_cost": 25.50,
  "tracking_url": "https://www.correios.com.br/rastreamento/BR54321X098Y",
  "notes": "Fragile items, handle with care"
}'

Uma remessa específica

O caminho /shipments/:id trabalha com uma remessa, identificada pelo id. Ele aceita GET, PUT e DELETE.

Método	Descrição	Uso
GET	Retorna uma remessa específica	Devolve informações detalhadas da remessa indicada
PUT	Atualiza uma remessa	Exige um corpo JSON com os campos a atualizar
DELETE	Exclui uma remessa	Remove a remessa do sistema de forma permanente

GET/api/shipments/{id}Admin

Consultar uma remessa específica

Parâmetros de caminho

idintegerobrigatório

O identificador único da remessa.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments/987"

Resposta

200Remessa retornada

json

{
  "shipment_id": 987,
  "order_id": 5432,
  "tracking_number": "BR54321X098Y",
  "carrier": "Correios Sedex",
  "shipping_date": "2025-04-15T08:30:00Z",
  "estimated_delivery_date": "2025-04-18T18:00:00Z",
  "actual_delivery_date": "2025-04-17T14:25:00Z",
  "status": "delivered",
  "shipping_cost": 25.50,
  "tracking_url": "https://www.correios.com.br/rastreamento/BR54321X098Y",
  "notes": "Fragile items, handle with care",
  "delivery_notes": "Package delivered to front desk",
  "items": [
    {
      "product_id": 143,
      "product_name": "Premium Wireless Headphones",
      "quantity": 1
    },
    {
      "product_id": 156,
      "product_name": "USB-C Charging Cable",
      "quantity": 2
    }
  ]
}

PUT/api/shipments/{id}Admin

Atualizar uma remessa

Parâmetros de caminho

idintegerobrigatório

O identificador único da remessa.

A requisição exige um corpo JSON com os campos a atualizar. A referência mostra este exemplo.

Exemplo de requisição

bash

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments/987" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "delivered",
  "actual_delivery_date": "2025-04-17T14:25:00Z",
  "delivery_notes": "Package delivered to front desk"
}'

DELETE/api/shipments/{id}Admin

Excluir uma remessa

Parâmetros de caminho

idintegerobrigatório

O identificador único da remessa.

Exemplo de requisição

bash

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/shipments/987"

Valores de status da remessa

Esta página lista o status da remessa em forma de palavras.

Status	Descrição
`pending`	A remessa foi criada, mas ainda não foi processada
`processing`	O pedido está sendo preparado para envio
`shipped`	O pacote foi entregue à transportadora
`in_transit`	O pacote está em trânsito com a transportadora
`out_for_delivery`	O pacote saiu para entrega hoje
`delivered`	O pacote foi entregue com sucesso
`failed_delivery`	Houve uma tentativa de entrega, mas ela falhou
`returned`	O pacote foi devolvido ao remetente
`cancelled`	A remessa foi cancelada