# WineSitting API documentation > Documentation for integrating with the WineSitting API. ## api ### documentation Build reliable integrations with the WineSitting REST API. - [Build with the WineSitting API.](https://app.winesitting.com/api/documentation/index.md): Build reliable integrations with the WineSitting REST API. - [Introduction](https://app.winesitting.com/api/documentation/introduction.md): Make your first authenticated request to the WineSitting API. - [Account](https://app.winesitting.com/api/documentation/reference/account.md): Account - [Addresses](https://app.winesitting.com/api/documentation/reference/addresses.md): Addresses - [Bottles](https://app.winesitting.com/api/documentation/reference/bottles.md): Bottles - [Create an address](https://app.winesitting.com/api/documentation/reference/create-address.md): Create an address - [Create an order](https://app.winesitting.com/api/documentation/reference/create-order.md): Creates an order. If `delivery_date` is omitted, WineSitting chooses the earliest valid delivery date. - [Delete an address](https://app.winesitting.com/api/documentation/reference/delete-address.md): The billing address cannot be deleted. - [Delete an order](https://app.winesitting.com/api/documentation/reference/delete-order.md): An order already in preparation cannot be deleted. - [Get an attachment](https://app.winesitting.com/api/documentation/reference/download-order-file.md): Get an attachment - [Get an attachment](https://app.winesitting.com/api/documentation/reference/download-putaway-file.md): Get an attachment - [Enums](https://app.winesitting.com/api/documentation/reference/enums.md): Enums - [Get a specific address](https://app.winesitting.com/api/documentation/reference/get-address.md): Get a specific address - [Check API status](https://app.winesitting.com/api/documentation/reference/get-api-status.md): Returns an empty JSON array when the API is available. - [Get current account information](https://app.winesitting.com/api/documentation/reference/get-current-account.md): Get current account information - [Get enum values](https://app.winesitting.com/api/documentation/reference/get-enum-values.md): Get enum values - [Get a specific invoice](https://app.winesitting.com/api/documentation/reference/get-invoice.md): Get a specific invoice - [Get delivery cost](https://app.winesitting.com/api/documentation/reference/get-order-delivery-cost.md): Send a complete order payload to receive an accurate delivery cost. - [Get earliest delivery date](https://app.winesitting.com/api/documentation/reference/get-order-earliest-delivery-date.md): Send an order payload to receive its earliest possible delivery date. - [Get invalid dates](https://app.winesitting.com/api/documentation/reference/get-order-invalid-dates.md): Returns invalid delivery dates from the current year through the following year for the supplied order. - [Get time slots](https://app.winesitting.com/api/documentation/reference/get-order-time-slots.md): Send a complete order payload to receive the available delivery slots. - [Get a specific order](https://app.winesitting.com/api/documentation/reference/get-order.md): Get a specific order - [Get a specific putaway](https://app.winesitting.com/api/documentation/reference/get-putaway.md): Get a specific putaway - [Get a warehouse](https://app.winesitting.com/api/documentation/reference/get-warehouse.md): Get a warehouse - [Invoices](https://app.winesitting.com/api/documentation/reference/invoices.md): Invoices - [Get all addresses](https://app.winesitting.com/api/documentation/reference/list-addresses.md): Retrieves the addresses associated with the current account. - [Get all bottles](https://app.winesitting.com/api/documentation/reference/list-bottles.md): This endpoint is not paginated and returns the cellar in consolidated form. - [Get all invoices](https://app.winesitting.com/api/documentation/reference/list-invoices.md): Get all invoices - [Get all orders](https://app.winesitting.com/api/documentation/reference/list-orders.md): Lists orders using the shared pagination parameters. - [Get all putaways](https://app.winesitting.com/api/documentation/reference/list-putaways.md): Get all putaways - [Get all transactions](https://app.winesitting.com/api/documentation/reference/list-transactions.md): Retrieves cellar movements associated with the current account. - [Get all active storage warehouses](https://app.winesitting.com/api/documentation/reference/list-warehouses.md): Returns WineSitting warehouses that are active and available for storage. - [Orders](https://app.winesitting.com/api/documentation/reference/orders.md): Orders - [Putaways](https://app.winesitting.com/api/documentation/reference/putaways.md): Putaways - [Status](https://app.winesitting.com/api/documentation/reference/status.md): Status - [Transactions](https://app.winesitting.com/api/documentation/reference/transactions.md): Transactions - [Update an address](https://app.winesitting.com/api/documentation/reference/update-address.md): Send all address fields, including unchanged values. - [Update current account information](https://app.winesitting.com/api/documentation/reference/update-current-account.md): Send the complete account payload. Preference values are available from the Enums operation. - [Send attachments](https://app.winesitting.com/api/documentation/reference/upload-order-files.md): Upload one or more files while the order status is `NEW`. - [Warehouses](https://app.winesitting.com/api/documentation/reference/warehouses.md): Warehouses - [WebHooks](https://app.winesitting.com/api/documentation/webhook.md): Use webhooks to be notified about events that happen during "order" process. ## Optional - [OpenAPI specification](https://app.winesitting.com/api/documentation/specs.yaml): Complete WineSitting API specification in OpenAPI format. --- # Full Documentation Content ## Everything you need to get started[​](#resources-title "Direct link to Everything you need to get started") Follow the concepts first, then jump directly into the resources you need. ### [Understand the fundamentals](https://app.winesitting.com/api/documentation/api/documentation/introduction/.md) [Learn about environments, authentication, errors, pagination, and shared API conventions.](https://app.winesitting.com/api/documentation/api/documentation/introduction/.md) [Read the introduction](https://app.winesitting.com/api/documentation/api/documentation/introduction/.md) ### [Explore API resources](https://app.winesitting.com/api/documentation/api/documentation/reference/account/.md) [Browse accounts, addresses, bottles, orders, putaways, invoices, transactions, enums, and webhooks.](https://app.winesitting.com/api/documentation/api/documentation/reference/account/.md) [Browse resources](https://app.winesitting.com/api/documentation/api/documentation/reference/account/.md) ### [Authenticate your requests](https://app.winesitting.com/bearer) [Generate a Bearer token and use it to securely access your WineSitting environment.](https://app.winesitting.com/bearer) [Generate an API key](https://app.winesitting.com/bearer) --- # Introduction The WineSitting API lets you connect your systems to your WineSitting account. Follow this guide to obtain an API key, validate your connection, and make your first request. ## Before you start[​](#before-you-start "Direct link to Before you start") You need: * access to a WineSitting account; * access to the target environment; * a WineSitting API key. caution API keys grant access to your WineSitting data. Never commit them to source control or expose them in browser or mobile application code. ## 1. Choose an environment[​](#1-choose-an-environment "Direct link to 1. Choose an environment") WineSitting provides two environments: | Environment | Base URL | Purpose | | ------------- | ---------------------------------------- | ----------------------------------------------------------- | | Preproduction | `https://preprod.winesitting.com/api/v2` | Validate your integration with test data before going live. | | Production | `https://app.winesitting.com/api/v2` | Work with your live WineSitting account and data. | Access is granted by WineSitting. Validate your integration in preproduction before sending production requests. ## 2. Generate an API key[​](#2-generate-an-api-key "Direct link to 2. Generate an API key") Generate and manage your production API keys from the [WineSitting dashboard](https://app.winesitting.com/bearer). Contact WineSitting if you need access to preproduction or do not yet have an account. Send the key with every request using the Bearer authentication scheme: ``` Authorization: Bearer YourBearerToken ``` ## 3. Check the connection[​](#3-check-the-connection "Direct link to 3. Check the connection") Call the status endpoint to verify the environment URL and your API key: ``` curl --request GET \ --url "https://app.winesitting.com/api/v2/status" \ --header "Accept: application/json" \ --header "Authorization: Bearer YourBearerToken" ``` A successful request returns: ``` [] ``` An HTTP `401` response means that the Bearer token is missing or invalid. ## 4. Make your first API request[​](#4-make-your-first-api-request "Direct link to 4. Make your first API request") Retrieve the account associated with the API key: ``` curl --request GET \ --url "https://app.winesitting.com/api/v2/account" \ --header "Accept: application/json" \ --header "Authorization: Bearer YourBearerToken" ``` You can now use the [API reference](https://app.winesitting.com/api/documentation/api/documentation/reference/account/.md) to explore the available resources, parameters, request bodies, and response examples. ## Request conventions[​](#request-conventions "Direct link to Request conventions") Requests and responses use JSON unless an operation explicitly documents a file upload or download. Send `Accept: application/json` with JSON requests and add `Content-Type: application/json` when the request contains a JSON body. WineSitting uses standard HTTP methods: * `GET` retrieves a resource or collection; * `POST` creates a resource or runs a calculation; * `PUT` replaces an existing resource; * `DELETE` removes a resource. info For `PUT` requests, send the complete resource representation, including unchanged values. Retrieve the current resource first, update the required fields, and then send the full payload. Paths, parameters, and headers are case-sensitive. Always use the exact names shown in the reference. ## Pagination[​](#pagination "Direct link to Pagination") Paginated collection endpoints accept these optional query parameters: | Parameter | Default | Description | | --------- | ------- | --------------------------------------- | | `offset` | `0` | Number of items to skip. | | `limit` | `30` | Number of items to return, up to `500`. | | `order` | `desc` | Sort direction: `asc` or `desc`. | The `X-Total-Count` response header contains the total number of matching resources, independently of `offset` and `limit`. ``` curl --request GET \ --url "https://app.winesitting.com/api/v2/orders?offset=20&limit=20&order=asc" \ --header "Accept: application/json" \ --header "Authorization: Bearer YourBearerToken" ``` The reference identifies which collection endpoints support pagination. For example, the consolidated [Bottles](https://app.winesitting.com/api/documentation/api/documentation/reference/bottles/.md) endpoint returns the complete cellar and is not paginated. ## Errors[​](#errors "Direct link to Errors") WineSitting uses conventional HTTP response codes: * `2xx` means the request succeeded; * `400` means the request or JSON payload is invalid; * `401` means authentication failed; * `403` means the account cannot perform the operation; * `404` means the requested resource does not exist; * `422` means validation failed; * `5xx` means an unexpected server error occurred. Each operation documents its possible responses and their payloads. Do not rely only on the status text: inspect the returned JSON problem details when handling an error. ## Data formats[​](#data-formats "Direct link to Data formats") * Dates and times use the `Europe/Paris` timezone unless an operation states otherwise. * Country values use [ISO 3166-1 alpha-2 codes](https://www.iso.org/obp/ui/#search/code), such as `FR`. * Phone numbers use the [E.164 format](https://www.twilio.com/docs/glossary/what-e164), such as `+33612345678`. * JSON responses are encoded as UTF-8. ## Next steps[​](#next-steps "Direct link to Next steps") * Retrieve and update the authenticated [Account](https://app.winesitting.com/api/documentation/api/documentation/reference/account/.md). * Manage delivery [Addresses](https://app.winesitting.com/api/documentation/api/documentation/reference/addresses/.md). * Retrieve the consolidated [Cellar](https://app.winesitting.com/api/documentation/api/documentation/reference/bottles/.md). * Create and monitor [Orders](https://app.winesitting.com/api/documentation/api/documentation/reference/orders/.md). * Receive updates using [Webhooks](https://app.winesitting.com/api/documentation/api/documentation/webhook/.md). --- # Account Retrieve and update the authenticated WineSitting account. ## [📄️Get current account information](https://app.winesitting.com/api/documentation/api/documentation/reference/get-current-account/.md) [Get current account information](https://app.winesitting.com/api/documentation/api/documentation/reference/get-current-account/.md) ## [📄️Update current account information](https://app.winesitting.com/api/documentation/api/documentation/reference/update-current-account/.md) [Send the complete account payload. Preference values are available from the Enums operation.](https://app.winesitting.com/api/documentation/api/documentation/reference/update-current-account/.md) --- # Addresses Manage delivery addresses belonging to the authenticated account. ## [📄️Get all addresses](https://app.winesitting.com/api/documentation/api/documentation/reference/list-addresses/.md) [Retrieves the addresses associated with the current account.](https://app.winesitting.com/api/documentation/api/documentation/reference/list-addresses/.md) ## [📄️Get a specific address](https://app.winesitting.com/api/documentation/api/documentation/reference/get-address/.md) [Get a specific address](https://app.winesitting.com/api/documentation/api/documentation/reference/get-address/.md) ## [📄️Create an address](https://app.winesitting.com/api/documentation/api/documentation/reference/create-address/.md) [Create an address](https://app.winesitting.com/api/documentation/api/documentation/reference/create-address/.md) ## [📄️Update an address](https://app.winesitting.com/api/documentation/api/documentation/reference/update-address/.md) [Send all address fields, including unchanged values.](https://app.winesitting.com/api/documentation/api/documentation/reference/update-address/.md) ## [📄️Delete an address](https://app.winesitting.com/api/documentation/api/documentation/reference/delete-address/.md) [The billing address cannot be deleted.](https://app.winesitting.com/api/documentation/api/documentation/reference/delete-address/.md) --- # Bottles Retrieve the cellar as consolidated wine, format and packaging references. A logistic reference uses the `wine_id|format|box` format, for example `1234|0.75|bottles`. ## [📄️Get all bottles](https://app.winesitting.com/api/documentation/api/documentation/reference/list-bottles/.md) [This endpoint is not paginated and returns the cellar in consolidated form.](https://app.winesitting.com/api/documentation/api/documentation/reference/list-bottles/.md) --- # Create an address ``` POST /addresses ``` Create an address ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 * 422 Address created successfully. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. Request payload or query string validation failed. --- # Create an order ``` POST /orders ``` Creates an order. If `delivery_date` is omitted, WineSitting chooses the earliest valid delivery date. Unless `allow_partial_fulfillment` is enabled, every requested bottle must be available in sufficient quantity. We strongly recommend letting WineSitting compute the earliest delivery date. If a date is supplied, preparation starts the same working day for orders created before 1pm and the next working day otherwise. Shipping then adds one day for departments 75, 92, 93, 94, 28, 45, 60, 77, 78, 91 and 95; three days in France up to 24 bottles; four days in France above 24 bottles; and six days for the rest of the world. Deliveries only occur on working days. Delivery time boundaries must be provided together and must span at least two hours within the same available slot group. An order cannot be edited after creation; delete it and create a new one instead. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 Order created successfully. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. --- # Delete an address ``` DELETE /addresses/:id ``` The billing address cannot be deleted. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Deleted address. Its identifier is null after deletion. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Delete an order ``` DELETE /orders/:id ``` An order already in preparation cannot be deleted. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Deleted order. Its identifier is null after deletion. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Get an attachment ``` GET /orders/:id/files/:attachment ``` Get an attachment ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Binary attachment. **Response Headers** * **Content-Disposition** Attachment filename. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Get an attachment ``` GET /putaways/:id/files/:attachment ``` Get an attachment ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Binary attachment. **Response Headers** * **Content-Disposition** Attachment filename. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Enums Retrieve the supported values for account preferences and resource statuses. ## [📄️Get enum values](https://app.winesitting.com/api/documentation/api/documentation/reference/get-enum-values/.md) [Get enum values](https://app.winesitting.com/api/documentation/api/documentation/reference/get-enum-values/.md) --- # Get a specific address ``` GET /addresses/:id ``` Get a specific address ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Address returned successfully. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Check API status ``` GET /status ``` Returns an empty JSON array when the API is available. ## Responses[​](#responses "Direct link to Responses") * 200 * 401 The API is available. The Bearer token is missing or invalid. --- # Get current account information ``` GET /account ``` Get current account information ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Current account information. The Bearer token is missing or invalid. --- # Get enum values ``` GET /enums ``` Get enum values ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 422 Enum values returned successfully. The Bearer token is missing or invalid. Request payload or query string validation failed. --- # Get a specific invoice ``` GET /invoices/:id ``` Get a specific invoice ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Invoice returned successfully. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Get delivery cost ``` GET /orders/delivery-cost ``` Send a complete order payload to receive an accurate delivery cost. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 Delivery cost returned successfully. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. --- # Get earliest delivery date ``` GET /orders/earliest-delivery-date ``` Send an order payload to receive its earliest possible delivery date. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 Earliest delivery date returned successfully. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. --- # Get invalid dates ``` GET /orders/invalid-dates ``` Returns invalid delivery dates from the current year through the following year for the supplied order. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 Invalid delivery dates returned successfully. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. --- # Get time slots ``` GET /orders/time-slots ``` Send a complete order payload to receive the available delivery slots. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 Available delivery slots. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. --- # Get a specific order ``` GET /orders/:id ``` Get a specific order ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Order returned successfully. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Get a specific putaway ``` GET /putaways/:id ``` Get a specific putaway ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 403 * 404 Putaway returned successfully. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Get a warehouse ``` GET /warehouses/:id ``` Get a warehouse ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 * 404 Warehouse returned successfully. The Bearer token is missing or invalid. Resource not found. --- # Invoices Retrieve invoices belonging to the authenticated account. ## [📄️Get all invoices](https://app.winesitting.com/api/documentation/api/documentation/reference/list-invoices/.md) [Get all invoices](https://app.winesitting.com/api/documentation/api/documentation/reference/list-invoices/.md) ## [📄️Get a specific invoice](https://app.winesitting.com/api/documentation/api/documentation/reference/get-invoice/.md) [Get a specific invoice](https://app.winesitting.com/api/documentation/api/documentation/reference/get-invoice/.md) --- # Get all addresses ``` GET /addresses ``` Retrieves the addresses associated with the current account. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Addresses returned successfully. **Response Headers** * **X-Total-Count** Total number of matching resources, independently from `offset` and `limit`. **Example: **`42` The Bearer token is missing or invalid. --- # Get all bottles ``` GET /bottles ``` This endpoint is not paginated and returns the cellar in consolidated form. ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Consolidated cellar returned successfully. The Bearer token is missing or invalid. --- # Get all invoices ``` GET /invoices ``` Get all invoices ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Invoices returned successfully. **Response Headers** * **X-Total-Count** Total number of matching resources, independently from `offset` and `limit`. **Example: **`42` The Bearer token is missing or invalid. --- # Get all orders ``` GET /orders ``` Lists orders using the shared pagination parameters. Tracking pages can be built as `https://winesitting.aftership.com/{tracking_number}?lang=fr`. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Orders returned successfully. **Response Headers** * **X-Total-Count** Total number of matching resources, independently from `offset` and `limit`. **Example: **`42` The Bearer token is missing or invalid. --- # Get all putaways ``` GET /putaways ``` Get all putaways ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Putaways returned successfully. **Response Headers** * **X-Total-Count** Total number of matching resources, independently from `offset` and `limit`. **Example: **`42` The Bearer token is missing or invalid. --- # Get all transactions ``` GET /transactions ``` Retrieves cellar movements associated with the current account. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 * 422 Transactions returned successfully. **Response Headers** * **X-Total-Count** Total number of matching resources, independently from `offset` and `limit`. **Example: **`42` Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. Request payload or query string validation failed. --- # Get all active storage warehouses ``` GET /warehouses ``` Returns WineSitting warehouses that are active and available for storage. ## Responses[​](#responses "Direct link to Responses") * 200 * 401 Active storage warehouses returned successfully. The Bearer token is missing or invalid. --- # Orders Create and retrieve orders, calculate delivery options and manage order attachments. ## [📄️Get all orders](https://app.winesitting.com/api/documentation/api/documentation/reference/list-orders/.md) [Lists orders using the shared pagination parameters.](https://app.winesitting.com/api/documentation/api/documentation/reference/list-orders/.md) ## [📄️Get a specific order](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order/.md) [Get a specific order](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order/.md) ## [📄️Create an order](https://app.winesitting.com/api/documentation/api/documentation/reference/create-order/.md) [Creates an order. If \`delivery\_date\` is omitted, WineSitting chooses the earliest valid delivery date.](https://app.winesitting.com/api/documentation/api/documentation/reference/create-order/.md) ## [📄️Delete an order](https://app.winesitting.com/api/documentation/api/documentation/reference/delete-order/.md) [An order already in preparation cannot be deleted.](https://app.winesitting.com/api/documentation/api/documentation/reference/delete-order/.md) ## [📄️Get delivery cost](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-delivery-cost/.md) [Send a complete order payload to receive an accurate delivery cost.](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-delivery-cost/.md) ## [📄️Get time slots](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-time-slots/.md) [Send a complete order payload to receive the available delivery slots.](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-time-slots/.md) ## [📄️Get earliest delivery date](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-earliest-delivery-date/.md) [Send an order payload to receive its earliest possible delivery date.](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-earliest-delivery-date/.md) ## [📄️Get invalid dates](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-invalid-dates/.md) [Returns invalid delivery dates from the current year through the following year for the supplied order.](https://app.winesitting.com/api/documentation/api/documentation/reference/get-order-invalid-dates/.md) ## [📄️Send attachments](https://app.winesitting.com/api/documentation/api/documentation/reference/upload-order-files/.md) [Upload one or more files while the order status is \`NEW\`.](https://app.winesitting.com/api/documentation/api/documentation/reference/upload-order-files/.md) ## [📄️Get an attachment](https://app.winesitting.com/api/documentation/api/documentation/reference/download-order-file/.md) [Get an attachment](https://app.winesitting.com/api/documentation/api/documentation/reference/download-order-file/.md) --- # Putaways Retrieve putaways and their attachments. ## [📄️Get all putaways](https://app.winesitting.com/api/documentation/api/documentation/reference/list-putaways/.md) [Get all putaways](https://app.winesitting.com/api/documentation/api/documentation/reference/list-putaways/.md) ## [📄️Get a specific putaway](https://app.winesitting.com/api/documentation/api/documentation/reference/get-putaway/.md) [Get a specific putaway](https://app.winesitting.com/api/documentation/api/documentation/reference/get-putaway/.md) ## [📄️Get an attachment](https://app.winesitting.com/api/documentation/api/documentation/reference/download-putaway-file/.md) [Get an attachment](https://app.winesitting.com/api/documentation/api/documentation/reference/download-putaway-file/.md) --- # Status Check that the WineSitting API is available. ## [📄️Check API status](https://app.winesitting.com/api/documentation/api/documentation/reference/get-api-status/.md) [Returns an empty JSON array when the API is available.](https://app.winesitting.com/api/documentation/api/documentation/reference/get-api-status/.md) --- # Transactions Retrieve cellar movements belonging to the authenticated account. ## [📄️Get all transactions](https://app.winesitting.com/api/documentation/api/documentation/reference/list-transactions/.md) [Retrieves cellar movements associated with the current account.](https://app.winesitting.com/api/documentation/api/documentation/reference/list-transactions/.md) --- # Update an address ``` PUT /addresses/:id ``` Send all address fields, including unchanged values. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 * 403 * 404 * 422 Address updated successfully. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. Request payload or query string validation failed. --- # Update current account information ``` PUT /account ``` Send the complete account payload. Preference values are available from the Enums operation. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 * 422 Updated account information. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. Request payload or query string validation failed. --- # Send attachments ``` POST /orders/:id/files ``` Upload one or more files while the order status is `NEW`. Accepted extensions are jpg, jpeg, png, gif, pdf, doc, docx, odt, rtf, xls, xlsx, ods, csv, txt, md, ppt, pptx and odp. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 * 400 * 401 * 403 * 404 Order with the new attachments. Invalid JSON, content type, request payload or business rule. The Bearer token is missing or invalid. The authenticated account cannot access or modify this resource. Resource not found. --- # Warehouses Retrieve WineSitting storage warehouses and their public information. ## [📄️Get all active storage warehouses](https://app.winesitting.com/api/documentation/api/documentation/reference/list-warehouses/.md) [Returns WineSitting warehouses that are active and available for storage.](https://app.winesitting.com/api/documentation/api/documentation/reference/list-warehouses/.md) ## [📄️Get a warehouse](https://app.winesitting.com/api/documentation/api/documentation/reference/get-warehouse/.md) [Get a warehouse](https://app.winesitting.com/api/documentation/api/documentation/reference/get-warehouse/.md) --- # WebHooks Use webhooks to be notified about events that happen during "order" process. ## Webhook terminology[​](#webhook-terminology "Direct link to Webhook terminology") An event is an "order" update (when WineSitting start to prepare the order or deliver an order). Each occurrence has a corresponding Event object. Webhook endpoint is a unique URL defined by users to which WineSitting sends events. Webhooks refers to the overall concept of sending notifications to webhook endpoints. Interacting with a third-party API like WineSitting can introduce two problems: * Services not directly responsible for making an API request may still need to know the response of that request, * Some events, like pickup or delivery and many events, are not the result of a direct API request. Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens associated with your "order". When the event occurs (for example when an "order" is delivered), WineSitting creates an Event object. This object contains all the relevant information about what just happened, including the type (order, ...), the event (create or update) and the data associated with that event (the complete updated "order" object, same result of retrieve an "order"). WineSitting then sends the Event object to URL of your account’s webhooks settings via an HTTP POST request. All event types are described in [WebHook event type](#the-webhook-event-type) section. ## When to use webhooks[​](#when-to-use-webhooks "Direct link to When to use webhooks") Webhooks are only necessary for behind-the-scenes update process. The results of most WineSitting requests (for example creating or getting a "order") are reported synchronously to your code and don’t require webhooks. When a "order" is being processed by WineSitting, you can do polling at fixed interval to get status update. Sometimes polling are not adapted, and a lot of request are send uselessly to get only few order updates : in this case webhook are perfectly adapted to send only update in asynchronous way. ## Configuring your webhook settings[​](#configuring-your-webhook-settings "Direct link to Configuring your webhook settings") Webhooks are configured inside API REST account settings of the Dashboard : . You can enter any URL you’d like to have events sent to, but this should be a dedicated page on your server, coded per the instructions below. API Keys and Webhooks are independent. ## Responding to a webhook[​](#responding-to-a-webhook "Direct link to Responding to a webhook") To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. WineSitting ignores all information returned in the request headers or request body as it uses "fire and forget" pattern. No retry policy are currently supported. ## Best practices[​](#best-practices "Direct link to Best practices") Before going live, test that your webhook is working properly on pre-production by creating test command to receiving webhook events. If your webhook script performs complex logic, or makes network calls, it’s possible the script would time out before WineSitting sees its complete execution. As WineSitting needs to stay fast, it uses "fire and forget" pattern when sending notifications. Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events. ## The webhook event object[​](#the-webhook-event-object "Direct link to The webhook event object") | Attribute name | Type | Description | | -------------- | ------------------------------------------------------- | ------------------ | | type | [WebHook event type](#the-webhook-event-type) | Type of event | | operation | [WebHook event operation](#the-webhook-event-operation) | Type of operation | | object | One of the WineSitting object | The updated object | | date | | Current date | ## The webhook event type[​](#the-webhook-event-type "Direct link to The webhook event type") | Webhook event type | Description | | ------------------ | ------------------------------------------------------------------- | | ORDER | All events concerning order (for example when a order is delivered) | | PUTAWAY | Only on create | ## The webhook event operation[​](#the-webhook-event-operation "Direct link to The webhook event operation") | Webhook event operation | Description | | ----------------------- | -------------------------------------------------------------------- | | CREATE | Create operation (for example when a new order is created) | | UPDATE | Update operation (for example when the status of a order is changed) | ---