Topics

Environments

To make the API as explorable as possible, two environments are available :

• Preproduction : testing and advanced staging environment, you have to use the preproduction environment before pushing your app to production.
  Use that specific URL for preproduction : http://preprod.winesitting.com/api/v2
• Production : real environment, after preproduction validation, you will be able to deploy to production.
  Use that specific URL for production : https://app.winesitting.com/api/v2

info

In both case you need to ask WineSitting for access to these environments.

URL strategy

The API endpoints URL are constructed with this following pattern : environment/version/resource/service/{parameters}.

• environment : environment you want to use.
• version : the API version you want to use. Current API version is v2
• resource : the resource path you want to access. A resource is described in this documentation with “API” suffix and can be accessed with a path.
  For example, the Addresses API can be accessed with the resource path /addresses.
• service : service path you want to use.
  For example, GET /bottles/consolidated let you get your cellar in a consolidated way.
• parameters : some services require one or more parameters. In this case, the documentation URL contains parameter names surrounded with { and }, and this parameter will be replaced in real case by the value.

Finally, the verb of HTTP method (GET, POST, PATCH, DELETE) is necessary to get the complete URL.

Authentication

Authenticate your account when using the API by including a Bearer token in the Authorization header.

You can manage your API keys on the WineSitting Dashboard at https://app.winesitting.com/bearer. If you don’t have an account, you can contact WineSitting here or by clicking on the chat at the bottom right of your interface.

Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

You need to provide the Bearer token every time you request the REST API methods. Include it in the HTTP headers using the Authorization header with the Bearer scheme.

info

URL parameters or headers are case-sensitive !

Example request with HTTP headers

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

note

Make sure to replace YourBearerToken with your API key.

Errors

WineSitting API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an technical error with WineSitting servers (these are rare).

Each service contains his own specific error codes, and the general error codes are described bellow.

Error name	HTTP status Code	Description
internal_error	500 Internal Server Error	Internal server error
not_found	404 Not found	No service found for request URL
not_implemented	404 Not found	Not implemented, available in further release
request_content_type_invalid	400 Bad Request	Invalid request content type, header “Content-Type” is probably not specified with value “application/json”
credentials_invalid	401 Unauthorized	Invalid credential, Bearer Token is invalid
not_sufficient_rights_invalid	401 Unauthorized	Authenticated API account has not sufficient rights
account_blocked	403 Forbidden	Authenticated API account is blocked
invalid_json	400 Bad Request	Json request content is not valid

HTTP Verbs

Where possible, WineSitting API uses appropriate HTTP verbs for each action.

• GET : Used for retrieving resources.
• POST : Used for creating resources.
• PUT : Used for updating resources.
• DELETE : Used for deleting resources.

info

The PUT verb means that you have to send all the parameters, even the ones that don't change. You should GET the resource first, then PUT the updated resource.

Date and time format

WineSitting API uses conventional timestamp format. Dates are in Europe/Paris timezone.

Example : 2024-08-28 11:55:27.000000

Country code format

WineSitting API uses ISO 3166-1 alpha-2 codes.

Example : France => FR

Phone number format

WineSitting API uses E164 format for phone numbers.

Example : 0612345678 => +33612345678

Content type

WineSitting API uses JSON for requests and responses, so all HTTP requests must specify Content-Type header with value application/json. You should also want to specify the Accept header with value application/json to make sure you get JSON responses.

All JSON responses will be encoded in UTF-8, so response header content-type is defined with value application/json; charset=utf-8.

Pagination

All top-level API resources have support for bulk fetches via “list” API methods. For instance you can list bottles, addresses, orders, invoices, transactions, wine comments and wine prices.

These list API methods share a common query string structure, taking three optional parameters: offset, limit, order.

Query Parameter	Default	Description
offset	0	the requested offset (ex: 0 for the first item).
limit	30	The number of items to list (ex: 10)
order	desc	The order of the list (asc or desc)

Example request

$ curl --request GET --url 'https://app.winesitting.com/api/v2/bottles?offset=20&limit=20&order=asc' \
       --header 'Authorization: Bearer YourBearerToken' \
       --header 'content-type: application/json'

Versioning

When we make backwards-incompatible changes to the API, we release new versions. The current version is v2. Read our API upgrade guide to see our API changelog and to learn more about backwards compatibility.

All requests need to have version in their URL. This documentation lists every available versions.