API Documentation

Getting Started

The Vinosoma REST API allows you to manage your restaurant's wine inventory, register sales, and access restaurant information programmatically.

Base URL

https://app.vinosoma.com/rest

Authentication

Two authentication methods are supported:

  • API Key: Add X-API-Key header with your 32-character token
  • OAuth 2.0: Add Authorization: Bearer {token} header

Note: Contact your restaurant administrator to obtain API credentials.

Deprecated: The old /restaurant/wine route still works as an alias for /restaurant/inventory, but new integrations should use the inventory path as documented in the Swagger spec. To register a sale, use POST /restaurant/sale/{gtin}.

Example 1: Get Your Restaurant Info

Returns information about the restaurant your API token belongs to (whoami).

Request

curl -X GET "https://app.vinosoma.com/rest/restaurant/info" \
  -H "X-API-Key: your-api-key-here"

Response

{
  "data": {
    "id": 1,
    "name": "Restaurant Vino",
    "company_id": 5,
    "currency_code": "DKK",
    "currency_symbol": "kr"
  }
}

Example 2: Adjust Inventory Quantity

Add or remove bottles from inventory using a relative change. Use a positive value to add stock, negative to remove. If the wine isn't in your inventory yet, it will be created automatically.

Request

curl -X POST "https://app.vinosoma.com/rest/restaurant/inventory/5701234567890" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 5
  }'

Response

{
  "success": true,
  "message": "Added 5 to inventory",
  "data": {
    "wine_restaurant_id": 42,
    "wine_id": 128,
    "gtin": "5701234567890",
    "previous_amount": 19,
    "change": 5,
    "new_amount": 24
  }
}

Body Parameters

Parameter Type Required Description
quantity integer Yes Bottles to add (positive) or remove (negative). Cannot be 0.

Need to set absolute values? Use PUT /restaurant/inventory/{gtin} with fields like amount, purchase_price, sales_price, supplier_id, or low_stock_threshold.

Example 3: Register Wine Sale

Register a sale of wine bottles, automatically updating inventory.

Request

curl -X POST "https://app.vinosoma.com/rest/restaurant/sale/5701234567890" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 2,
    "sales_price": 149.00,
    "location_id": 5
  }'

Response

{
  "success": true,
  "message": "Sale registered successfully",
  "data": {
    "sale_id": 1523,
    "wine_id": 128,
    "quantity": 2,
    "unit_price": 149.0,
    "total_price": 298.0,
    "currency": "kr",
    "previous_stock": 24,
    "new_stock": 22
  }
}

Parameters

Parameter Type Required Description
gtin string (path) Yes Wine GTIN/barcode (in URL)
quantity integer No Number of bottles sold (default: 1)
sales_price float No Override price for this sale
location_id integer No Restaurant location where sale occurred

API Endpoints

Restaurant Info

GET /restaurant/info - Get your restaurant info (whoami)

Inventory Management

GET /restaurant/inventory - List wines in inventory (paginated)
GET /restaurant/inventory/{gtin} - Get wine in inventory by GTIN
POST /restaurant/inventory/{gtin} - Adjust quantity (relative ±)
PUT /restaurant/inventory/{gtin} - Set absolute values (amount, prices, etc.)
DELETE /restaurant/inventory/{gtin} - Remove wine completely from inventory

Sales

POST /restaurant/sale/{gtin} - Register a wine sale (decreases stock)

Locations (read-only)

GET /restaurant/location - List restaurant locations
GET /restaurant/location/{id} - Get location details

Webhooks

GET /restaurant/webhook - List your webhooks
POST /restaurant/webhook - Create new webhook
GET /restaurant/webhook/{id} - Get webhook details
PUT /restaurant/webhook/{id} - Update webhook
DELETE /restaurant/webhook/{id} - Delete webhook

Error Codes

Code Description
400 Bad Request - Invalid input data
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource does not exist
413 Request Too Large - Request body exceeds 10MB
415 Unsupported Media Type - Content-Type must be application/json
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error occurred
Interactive API Explorer (Swagger) | Back to Vinosoma