Shipments API - Venddor API

Shipments Endpoints

The Shipments API allows you to manage shipment information for orders in the Venddor platform. This documentation outlines the available endpoints and their supported HTTP methods.

Base URL: https://www.venddor.com.br/api

Available Endpoints

GET POST /shipments

This endpoint allows you to retrieve all shipments or create a new shipment record.

Supported Methods

Method	Description	Usage
GET	Retrieve all shipments	Use pagination parameters to limit results. See Pagination section for details.
POST	Create a new shipment	Requires a JSON body with shipment details.

Create Example

List Response

{
  "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"
}

{
  "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
  }
}

GET PUT DELETE /shipments/:id

This endpoint allows you to work with a specific shipment identified by its ID.

Path Parameters

Parameter	Type	Description
id*	integer	The unique identifier of the shipment

Supported Methods

Method	Description	Usage
GET	Retrieve a specific shipment	Returns detailed information about the specified shipment
PUT	Update a shipment	Requires a JSON body with fields to update
DELETE	Delete a shipment	Permanently removes the shipment from the system

Important: Deleting a shipment does not cancel the actual delivery. It only removes the shipment record from the system. To cancel an actual delivery, you need to contact the carrier directly.

Update Example

Response Example

{
  "status": "delivered",
  "actual_delivery_date": "2025-04-17T14:25:00Z",
  "delivery_notes": "Package delivered to front desk"
}

{
  "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
    }
  ]
}

Shipment Status Values

Status	Description
`pending`	Shipment has been created but not yet processed
`processing`	Order is being prepared for shipping
`shipped`	Package has been handed over to the carrier
`in_transit`	Package is in transit with the carrier
`out_for_delivery`	Package is out for delivery today
`delivered`	Package has been delivered successfully
`failed_delivery`	Delivery attempt was made but failed
`returned`	Package was returned to sender
`cancelled`	Shipment was cancelled

Tip: You can filter shipments by status using the status query parameter. For example, /shipments?status=delivered will return only delivered shipments.