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.

Example 1: List Restaurants

Get a list of all active restaurants in the system.

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",
      "email": "info@vino.dk",
      "phone": "+45 12345678",
      "address": "Vinvej 10, Copenhagen",
      "created_at": "2025-01-15 10:30:00"
    },
    {
      "id": 2,
      "name": "Bistro Grape",
      "email": "hello@grape.dk",
      "phone": "+45 87654321",
      "address": "Druevej 5, Aarhus",
      "created_at": "2025-02-20 14:15:00"
    }
  ],
  "total": 2
}

Example 2: Add Wine to Inventory

Add a wine to your restaurant's inventory using its GTIN (barcode).

Request

curl -X POST "https://app.vinosoma.com/rest/restaurant/wine" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "5701234567890",
    "purchase_price": 75.50,
    "sales_price": 149.00,
    "amount": 24,
    "low_stock_threshold": 6
  }'

Response

{
  "success": true,
  "message": "Wine added to inventory",
  "data": {
    "wine_restaurant_id": 42,
    "restaurant_id": 1,
    "wine_id": 128,
    "purchase_price": 75.5,
    "sales_price": 149.0,
    "amount": 24,
    "supplier_id": null,
    "low_stock_threshold": 6,
    "wine": {
      "name": "Château Margaux 2015",
      "vintage": 2015,
      "gtin": "5701234567890",
      "winery_name": "Château Margaux"
    }
  }
}

Parameters

Parameter Type Required Description
gtin string Yes* GTIN/barcode (or use wine_id)
wine_id integer Yes* Internal wine ID (or use gtin)
purchase_price float No Purchase price per bottle
sales_price float No Sales price per bottle
amount integer No Initial stock quantity
low_stock_threshold integer No Alert when stock falls below this

Example 3: Register Wine Sale

Register a sale of wine bottles, automatically updating inventory.

Request

curl -X POST "https://app.vinosoma.com/rest/restaurant/wine/sale" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "5701234567890",
    "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,
    "previous_stock": 24,
    "new_stock": 22
  }
}

Parameters

Parameter Type Required Description
gtin string Yes* Wine GTIN (or use wine_id)
wine_id integer Yes* Wine ID (or use gtin)
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 - List all restaurants
GET /restaurant/info/{id} - Get restaurant details
GET /restaurant/info/find-by-gtin?gtin={gtin} - Find which restaurant has a wine

Wine Management

GET /restaurant/wine - List wines in inventory
GET /restaurant/wine/{id} - Get wine details
POST /restaurant/wine - Add wine to inventory
POST /restaurant/wine/sale - Register wine sale
PUT /restaurant/wine/{id} - Update wine details
DELETE /restaurant/wine/{id} - Remove wine from inventory

Locations

GET /restaurant/location - List restaurant locations
POST /restaurant/location - Create new location
PUT /restaurant/location/{id} - Update location
DELETE /restaurant/location/{id} - Delete location

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