API documentation for POS integrations
How to connect a Point of Sales system (or other system) to Vinify.
This allows you to have your POS be always in sync with your cellar/wine list/stock count/analytics in Vinify.
We are flexible and not limited to the documentation below.
For any questions, please contact Roko Cupic: rcupic@profico.hr
TLDR;
Articles (products/wines) are created and edited in Vinify and sent to the POS. Vinify functions as the master database of articles.
When an article is sold via the POS, the POS sends the data to Vinify, which allows Vinify to update the cellar quantity of the article.
Vinify requirements
Authentification
One Vinify cellar is connected to one POS account. Vinify is open to various authentication methods. For an initial integration version, only POS API must implement the authentication.
Authentications that Vinify consumes for current integrations:
API-Key and ID combination. The API-Key is valid forever
Username + Password and JWT token with expiration
API-Key and API-Secret + Hashing of requests
Each restaurant can have its own credentials or Vinify can have credentials authorized for accessing data for multiple restaurants.
Articles
Groups
Articles are organised in groups that make it easy for Sommeliers to find an article in the POS. It would be great if articles from the same group can inherit the same settings.
Groups function like folders, and it is recommended to have multiple layers. Articles are placed within groups and preferably inherit some metadata, such as tax.
Hierarchy example: Wine -> Red wine -> Italy -> Piedmont
Groups could have different VAT, color and additional attributes.
Articles
Essential entities of the integration are articles. Vinify must be able to somehow create and update articles within POS. Recommended approach is to use HTTP POST and PATCH methods with a JSON body.
The most important article properties:
Article name
Selling price
TAX (can be inherited from article group)
Vinify can include other properties to complete POS requirements. Examples:
Quantity
Buying prices
Article group
Endpoint for reading articles is also desirable so that the Vinify team can verify if articles are correctly synchronized with Vinify products.
Glass articles
Used for selling wines by the glass via the POS system.
Glass articles are separate articles and transactions are processed differently.
Transactions
The most important information for us is amount of sold articles and article identification, because for that amount we will decrement cellar article quantity. We can process transactions either continuously or once a day.
When Vinify products are imported, everything should be ready for sale. The assumption is that POS logs every transaction and maintains historical data. An API to retrieve transactions is necessary so that Vinify can pull the transactions and update quantities accordingly.
The recommended method is to pull transactions using the HTTP GET method, with the response body in JSON format.
Another possible solution is to create a Vinify endpoint that receives transaction data whenever an article is sold. Each sale would be automatically visible within Vinify. However, the preferred approach is to pull transactions directly from the source (POS) as needed.
Transaction data must contain article identification, transaction timestamp, number of sold units, total selling price and transaction type.
The endpoint should accept a restaurant filter and ISO timestamp range filter which will return transactions made within specified range.
Launching new clients
New clients are launched manually by admins. After a client is created in POS, we will link his cellar with the POS account.