Youklid API v2 Documentation

Base URL: https://api.youklid.cz/v2

Authentication: Bearer token in Authorization header

1. Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

2. Delegate Access

To access client data, you must first obtain delegation access:

2.1 Request OTP

POST/delegate/otp

{
  "email": "client@example.com"
}

2.2 Verify OTP

POST/delegate/verify-otp

{
  "email": "client@example.com",
  "otp": "123456"
}

2.3 List Delegations

GET/delegations

Returns all clients who have granted you access.

3. Catalog

GET/catalog

Returns all available services with their options, pricing, and availability.

Catalog structure follows Product-Option-Value model:

• Services (e.g., regular_cleaning, material)
• Options for each service (e.g., location, duration, start time, date)
• Available values for each option with price impacts

4. Cart Management

4.1 Add to Cart

POST/cart/add

{
  "delegate_user_id": 123,
  "items": [
    {
      "name": "regular_cleaning",
      "properties": [
        {"name": "location", "value": "praha"},
        {"name": "duration", "value": 5},
        {"name": "start", "value": 9},
        {"name": "date", "value": "2025-01-20"},
        {"name": "name", "value": "John Doe"},
        {"name": "address", "value": "Plzeňská 155/113"}
      ]
    },
    {
      "name": "details",
      "properties": [
        {"name": "phone", "value": "+420123456789"},
        {"name": "invoice_name", "value": "John Doe"},
        {"name": "invoice_address", "value": "Plzeňská 155/113"},
        {"name": "invoice_city", "value": "Praha"}
      ]
    }
  ]
}

4.2 View Cart

GET/cart?delegate_user_id=123

Returns all services currently in the client's cart.

4.3 Remove from Cart

DELETE/cart/remove

{
  "delegate_user_id": 123,
  "name": "regular_cleaning"
}

5. Order Processing

5.1 Checkout Cart

POST/cart/checkout

{
  "delegate_user_id": 123
}

Response:

{
  "status": "success",
  "message": "Cart checkout successful",
  "total_price": 3180,
  "order_id": 123456,
  "paid": false,
  "paygate_link": "https://pay1.comgate.cz/init?id=XXXX-XXXX-XXXX"
}

5.2 Create Payment

POST/pay

{
  "delegate_user_id": 123,
  "amount": 3380
}

Response:

{
  "status": "success",
  "link": "https://pay1.comgate.cz/init?id=XXXX-XXXX-XXXX",
  "amount": "3380",
  "currency": "CZK"
}

6. Order Tracking

GET/orders?delegate_user_id=123

Returns all orders for a specific client with status information.

Response:

{
  "status": "success",
  "orders": [
    {
      "id": 123456,
      "address": "Plzeňská 155/113",
      "start": "2025-07-12 08:00:00",
      "duration": 5,
      "state": "UPCOMING",
      "payment": "PAID",
      "price": 3180,
      "currency": "CZK"
    }
  ]
}

7. Order States

Service States:

• STORNO - Order cancelled
• UPCOMING - Scheduled for future
• IN_PROGRESS - Currently being performed
• DONE - Service completed

Payment States:

• CANCELED - Payment cancelled
• WAITING - Awaiting payment
• PAID - Payment completed

8. Error Handling

All endpoints return JSON responses with status and message fields:

{
  "status": "error",
  "message": "Error description"
}

Common Error Scenarios:

• Invalid API key: 401 Unauthorized
• Missing required properties: Returns list of required fields
• Unavailable services: Returns list of unavailable services
• Invalid property values: Returns list of invalid options
• User not found: When delegate_user_id doesn't exist

9. Implementation Flow

1. Obtain API key from dashboard
2. Request delegation access for client email
3. Client provides OTP, verify to get delegate_user_id
4. Fetch catalog to get available services and options
5. Add services to cart with required properties
6. Checkout cart to create order
7. Redirect client to payment link if payment required
8. Monitor order status using orders endpoint

10. Important Notes

• All prices are in CZK (Czech Koruna)
• Payment links expire after 30 minutes
• Catalog data should not be cached as availability changes frequently
• Use exact service names and property values from catalog
• Required properties must be set for each service
• Adding the same service to cart replaces the existing one

For support: devops@youklid.cz | For client support: info@youklid.cz