### REST API Endpoints Overview Source: https://api-docs.virtualstock.com/index This section outlines the available REST API endpoints for managing suppliers, products, stock, orders, and order status. ```APIDOC ## REST API Endpoints ### Description The Virtualstock REST API allows for the creation and management of suppliers, products, stock availability, orders, and order status information between retailers and suppliers. ### Authentication Authentication details will be provided upon setup. Typically involves API credentials. ### API Modules - **Order Management**: Endpoints for managing orders. - **Supplier Management**: Endpoints for managing supplier information. - **Product & Stock Management**: Endpoints for managing product data and stock levels. ### Base URL `https://api.sandbox.virtualstock.com` ``` -------------------------------- ### Breaking Change Policy Source: https://api-docs.virtualstock.com/index Understand Virtualstock's policy on breaking and non-breaking changes to ensure smooth integration updates. ```APIDOC ## Breaking Change Policy ### Description This policy defines what constitutes a breaking change versus a non-breaking change in the Virtualstock API, helping developers prepare for updates. ### Breaking Changes Changes that may require modifications to your application to prevent integration disruption. Examples include: - Changes to permission definitions. - Removal of allowed parameters, request fields, or response fields. - Addition of a required parameter or request field without default values. - Changes to endpoint functionality. - Introduction of new validation rules. ### Non-Breaking Changes Changes that do not require immediate application modifications and can be adapted to at your own pace. Examples include: - Addition of new endpoints. - Addition of new methods to existing endpoints. - New fields in responses. - New optional request fields or parameters. - New required request fields with default values. - Changes to the order of fields in responses. - Addition of optional request headers. - Removal of redundant request headers. - Changes to data length within fields. - Changes to overall response size. - Changes to error messages (rely on HTTP response codes and error codes). - Fixes to HTTP response codes and error codes. ``` -------------------------------- ### Order tracking status updates via Webhook Source: https://api-docs.virtualstock.com/index This section outlines the specifications for receiving order tracking status updates via a retailer-built REST API (Webhook). ```APIDOC ## Order tracking status updates via Webhook ### Introduction The purpose of this Webhook API is for a retailer to receive all the orders tracking status updates that are made by suppliers or their carriers. The retailer will need to build a REST API to the specifications detailed below, and Virtualstock will require the URL and credentials to start receiving these updates. ### Authentication #### Method Basic Authentication #### Details Usernames and passwords for the environment that Virtualstock needs to interact with need to be provided to Virtualstock when the API is ready for testing. ### Content Types This service sends JSON content with a `Content-Type` header set to `application/json`. ``` -------------------------------- ### POST /websites/api-docs_virtualstock Source: https://api-docs.virtualstock.com/index This endpoint is used to send shipment payload data to Virtualstock. It accepts various tracking and order details, including item information. ```APIDOC ## POST /websites/api-docs_virtualstock ### Description This endpoint is used to send shipment payload data to Virtualstock. It accepts various tracking and order details, including item information. ### Method POST ### Endpoint /websites/api-docs_virtualstock ### Parameters #### Request Body - **channel** (Text100) - Optional - An Order Channel that you have configured for your instance of Virtualstock. Channels are used to separate orders by Region, or Buying groups within one organisation. Use "" if you do not use Channels. - **carrier** (Text100) - Required - Carrier name e.g. “Green van” - **dispatched_date** (DateTime) - Required - The Date that the supplier provided to Virtualstock to indicate when the order was Dispatched from their warehouse. - **estimated_delivery_date** (DateTime) - Required - The Date that the supplier provided to Virtualstock to indicate when the order in expected to arrive. - **order_number** (Text100) - Required - Unique order reference - **tracking_number** (Text100) - Required - The consignment or tracking number provided to Virtualstock by the supplier when they Dispatch the order. - **tracking_url** (Text255) - Optional - Some suppliers will provide the Carrier's website tracking URL. This is very often not populated, but Virtualstock will pass it on if we receive it from suppliers - **status** (Text50) - Required - The current tracking status of the order item, e.g PENDING, DELIVERED. - **checkpoint_time** (DateTime) - Required - A number generated by Virtualstock, unique to each tracking message - **tracking_message** (Text255) - Required - Comment related to the status change. e.g. “Arrived at Hub” - **items** (Array) - Required - An array of item objects, each containing line_ref, part_number, and quantity. - **line_ref** (Text100) - Required - The line reference is unique to each line on the order. - **part_number** (Text255) - Required - The unique identifier for the product - **quantity** (Positive Integer) - Required - The number of items from the original order that are Dispatched with this shipment. - **ts** (Integer) - Required - A unique timestamp ### Request Example ```json { "channel": "CHANNEL1", "carrier": "DPD", "dispatched_date": "2019-05-23T00:00:00+0000", "estimated_delivery_date": "2019-05-23T00:00:00+0000", "order_number": "ORDER121821", "tracking_number": "TXD98798798798", "tracking_url": "https://www.some.site.com/tracking", "status": "DELIVERED", "checkpoint_time": "2019-05-23T13:09:51+0000", "tracking_message": "Manchester HUB", "items": [ { "line_ref": "001", "part_number": "sku-002014", "quantity": 10 } ], "ts": 15484698531106 } ``` ### Response #### Success Response (200) - **message** (string) - A success message indicating the payload was processed. #### Response Example ```json { "message": "Shipment data processed successfully." } ``` ### Error Handling - **400 Bad Request**: Raised if the request contains malformed data (ParseError, ValidationError). - **401 Unauthenticated**: Raised when an incoming request includes incorrect authentication or fails permission checks (AuthenticationFailed, NotAuthenticated). - **403 Forbidden**: Raised when an authenticated request fails the permission checks (PermissionDenied). - **429 Too Many Requests**: Raised when an incoming request fails the throttling checks (Throttled). ``` -------------------------------- ### Virtualstock Order Dispatch Payload (JSON) Source: https://api-docs.virtualstock.com/index This JSON payload represents the data structure for dispatching order information to the Virtualstock API. It includes details about the shipment, tracking, and items. The `channel` field is optional. ```json { "channel": "CHANNEL1", //(optional) "carrier": "DPD", "dispatched_date": "2019-05-23T00:00:00+0000", "estimated_delivery_date": "2019-05-23T00:00:00+0000", "order_number": "ORDER121821", "tracking_number": "TXD98798798798", "tracking_url": "https://www.some.site.com/tracking", "status": "DELIVERED", "checkpoint_time": "2019-05-23T13:09:51+0000", "tracking_message": "Manchester HUB", "items": [ { "line_ref": "001", "part_number": "sku-002014", "quantity": 10 } ], "ts": 15484698531106 //(unique timestamp) } ``` -------------------------------- ### API Throttling Limit Source: https://api-docs.virtualstock.com/index Information regarding the rate limits imposed on API requests and the behavior when these limits are exceeded. ```APIDOC ## API Throttling Limit ### Description Details the rate limiting policy for the Virtualstock API. ### Limit All API requests are limited to **250** requests per minute. ### Behavior on Exceeding Limit If you exceed this limit, you will receive an error message informing you when you are next able to make another API call. The API will return a status code of `429` and a message in the response like: `Request was throttled. Expected available in XX.0 seconds.` Example Scenario: You can call the API 250 times in the first few seconds of the minute, but then have to wait until the next minute to call again. ``` -------------------------------- ### REST API Error Codes Source: https://api-docs.virtualstock.com/index This section details the standard HTTP status codes returned by the REST API and their meanings. ```APIDOC ## REST API Error Codes ### Description Provides a list of common HTTP status codes returned by the API and their descriptions. ### Error Codes - **200 OK**: The request you made returned successfully. - **201 Created**: Your POST was successful and the entity you submitted has been created on our platform. - **400 Bad Request**: Your payload contains an invalid value or a missing value or is not structured correctly. - **401 Unauthorised**: Your authentication credentials are incorrect. - **404 Not found**: Your URL / Endpoint is not correct or contains an invalid REST ID. - **429 Request was throttled**: See the details on throttling below. - **500 Internal Server Error**: Our service is in a degraded state or is in scheduled downtime for a release. Note: A secondary error code and a message will indicate the specific type of error that occurred. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.