Skip to main content
Version: v2

Upgrade guide

The industry standards and best practices are constantly evolving. To keep up with the latest trends and to provide you with the best possible experience, we regularly update our API.

This guide is intended to help you upgrade your application to the latest version of the WineSitting API.

URL​

The base URL of the API has changed. You must now use https://app.winesitting.com/api/v2 instead of https://app.winesitting.com/v1.

Authentication​

We reworked the authentication system to make it more secure and easier to use.

The old way of authenticating was to use AccessKey and SecretKey in the header of your requests. You must now use a Bearer token in the Authorization header.

$ curl --request GET \
       --url 'https://app.winesitting.com/api/v2/addresses' \
       --header 'Authorization: Bearer YourBearerToken' \
       --header 'content-type: application/json'
info

You need to get new API keys from the WineSitting Application at https://app.winesitting.com/bearer.

Dates format​

We have changed the format of the dates in the API when they are returned.

The dates were returned in the following format : 2024-07-15T15:29:27+02:00. They are now returned in the following format :

{
  "date": "2024-07-15 15:29:27.000000",
  "timezone_type": 3,
  "timezone": "Europe/Paris"
}

Status and states codes​

We have changed the way we represent status and states in the API. We now use a more descriptive way to represent them. The statuses were returned in the following format : "status": 0, They are now returned in the following format :

"status": {
  "value": 0,
  "name": "NEW",
  "label": "En attente de préparation"
},
info

You can get all the possible values for a status by calling the GET /enums?label={enum} endpoint. See Enums for more information.

PUT requests for updating resources​

We have changed the way you update resources in the API. You can't use the PATCH method anymore, you must use the PUT method. This results in a more consistent and predictable API calls.

info

You now need to send the full resource object in the body of the request. Please check the documentation of the ressources you are updating to see the required fields.

Bottles representation​

We have changed the way bottles are represented in the API. We use the same representation everywhere : Orders, Putaways, Bottles. Bottles are now always represented in a consolidated way and have a reference field.

info

This results in two consequences :

  • The GET /bottles/consolidated endpoint is replaced by GET /bottles.
  • The GET /bottles/{id} endpoint is not available anymore.

Get Out Requests to Orders Renaming​

We renamed all the /get-out-requests endpoints to /orders. This change is also reflected in the documentation.

Get Out Request payload​

Now called Orders, the payload of the PUT /orders endpoint has changed.

The main changes are :

  • The address fields are now grouped under an address field.
  • The bottles and boxes fields are now grouped under a content field which is much simpler.
  • (int) is_pickup becomes (bool) pickup.
  • (int) auto_qty becomes (bool) allow_partial_fulfillment.
  • The half_day field is removed and replace by delivery_start and delivery_end fields.

Example​

$ curl --request POST --url 'https://app.winesitting.com/v1/get-out-request' \
--header 'Authorization: Bearer YourBearerToken' \
--header 'content-type: application/json' \
--data '
{
  "content": [
    {
      "reference": "14126|0.75|bottles",
      "quantity": 1
    },
    {
      "reference": "16243|0.75|bottles",
      "quantity": 4
    },
    {
      "reference": "16243|0.75|cbo6",
      "quantity": 1
    },
    {
      "reference": "16243|0.75|cbo12",
      "quantity": 1
    },
  ],
  "allow_partial_fulfillment": true,
  "pickup": false,
  "address": {
    "firstname": "Test",
    "lastname": "Test",
    "street1": "86 rue Baron le Roy",
    "city": "Paris",
    "zipcode": "75012",
    "country": "FR",
    "phone": "+33123456789"
  }
}
'
note

It is not possible to edit an order once it has been created. You need to delete the order and create a new one.

Wine Prices and Wine Comments​

We have changed the urls for updating/deleting Wine Prices and Wine Comments.

The new urls are :

  • PUT /wine-comments/{{wineId}}/{{wineFormat}}
  • DELETE /wine-comments/{{wineId}}/{{wineFormat}}

Webhooks​

In API v1 Webhooks url are linked to an API Key. It's not the case anymore : you can now create Bearers and Webhooks independently.

As API v1 Keys are meant to be removed, you should migrate your Webhooks urls to the new system.