ZAYUNO / DOCSPortalda ochish ↗AI agent index ↗

Provider API reference

Contract version: 1.0.0. This page is generated from packages/contracts/src/provider-protocol.ts. Do not edit examples independently.

Implement ZAYUNO_TO_PROVIDER routes on your provider backend. The webhook entry is PROVIDER_TO_ZAYUNO. Core management routes live in the separate Zayuno Core API guide.

OpenAPI 3.1 JSON — schemas, required fields and request/response examples.
Postman collection — requests with environment placeholders.
Capabilities — read-only vs transactional; physical fulfillment also requires active locations.
Authentication — outbound auth and inbound webhook signing are separate.

Provider-to-Zayuno status events use POST https://api.zayuno.uz/api/v1/webhooks/{providerSlug}. Never send production status updates to your own backend URL.

Request parameters

Use the IDs and field names from the request schema. Base URLs, path parameters and query parameters are not interchangeable. Encode path IDs, send JSON bodies for POST requests, and use the authentication mode selected in the portal.

GET /provider-info

Provider metadata, advertised capabilities, geography and supported verticals

Property	Value
Capability	`METADATA`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	DISCOVERY_READONLY, TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	No JSON request body
Response schema	ProviderInfo

Request

GET /provider-info — no JSON body.

Response example

{
  "id": "provider_shopla",
  "slug": "shopla",
  "name": "Shopla Online Mart",
  "status": "ACTIVE",
  "type": "RETAIL",
  "environment": "LIVE",
  "category": "RETAIL",
  "subcategory": "online_marketplace",
  "geography": [
    "UZ"
  ],
  "adapterType": "remote-http",
  "authMethod": "API_KEY",
  "capabilities": [
    "METADATA",
    "HEALTH",
    "LOCATIONS",
    "CATALOG",
    "SEARCH",
    "QUOTE",
    "ACTION_CREATE",
    "ACTION_STATUS",
    "PAYMENT_OPTIONS",
    "ACTION_CANCEL",
    "WEBHOOK"
  ],
  "supportContact": {
    "email": "support@shopla.uz",
    "phone": "+998712000000",
    "telegram": "@shoplasupport"
  },
  "metadata": {}
}

Required response fields: id, slug, name, status, type, capabilities.

GET /health

Deterministic health check protocol with latency and system status

Property	Value
Capability	`HEALTH`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	DISCOVERY_READONLY, TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	No JSON request body
Response schema	HealthCheckResult

Request

GET /health — no JSON body.

Response example

{
  "status": "HEALTHY",
  "latencyMs": 18,
  "timestamp": "2026-08-24T10:00:00.000Z",
  "details": {
    "uptimeSeconds": 86400
  }
}

Required response fields: status, latencyMs, timestamp.

GET /locations

Physical branches, warehouses, pickup locations, or fulfillment centers

Property	Value
Capability	`LOCATIONS`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	DISCOVERY_READONLY, TRANSACTIONAL
Requirement	When declared; see fulfillment/location requirements
Request schema	No JSON request body
Response schema	Location[]

Request

GET /locations — no JSON body.

Response example

[
  {
    "id": "loc_main",
    "providerId": "provider_shopla",
    "providerLocationId": "branch_1",
    "name": "Main Branch",
    "address": "Tashkent, Amir Temur 1",
    "latitude": 41.311081,
    "longitude": 69.240562,
    "serviceRadiusKm": 10,
    "isActive": true,
    "metadata": {}
  }
]

Required response fields: id, providerId, providerLocationId, name, address.

GET /catalog

Full catalog hierarchy with categories, offerings, variants, and option groups

Property	Value
Capability	`CATALOG`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	DISCOVERY_READONLY, TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	No JSON request body
Response schema	Catalog

Request

GET /catalog — no JSON body.

Response example

{
  "providerSlug": "shopla",
  "categories": [
    {
      "id": "cat_drinks",
      "slug": "drinks",
      "title": "Ichimliklar",
      "description": "Issiq va sovuq ichimliklar",
      "displayOrder": 1,
      "offeringsCount": 1
    }
  ],
  "offerings": [
    {
      "id": "item_coffee_latte",
      "providerId": "provider_shopla",
      "offeringCode": "COFFEE-LATTE",
      "title": "Latte",
      "description": "Freshly brewed espresso with velvety steamed milk",
      "categorySlug": "drinks",
      "categoryTitle": "Ichimliklar",
      "basePrice": 30000,
      "currency": "UZS",
      "isAvailable": true,
      "variants": [
        {
          "id": "var_standard",
          "name": "Standard (300ml)",
          "basePrice": 30000,
          "isAvailable": true,
          "metadata": {}
        },
        {
          "id": "var_large",
          "name": "Large (450ml)",
          "basePrice": 38000,
          "isAvailable": true,
          "metadata": {}
        }
      ],
      "optionGroups": [
        {
          "id": "grp_milk",
          "name": "Sut turi",
          "isRequired": false,
          "minSelections": 0,
          "maxSelections": 1,
          "options": [
            {
              "id": "opt_whole",
              "name": "Oddiy sut",
              "priceDelta": 0,
              "isDefault": true,
              "isAvailable": true,
              "metadata": {}
            },
            {
              "id": "opt_oat",
              "name": "Suli suti (Oat milk)",
              "priceDelta": 6000,
              "isDefault": false,
              "isAvailable": true,
              "metadata": {}
            }
          ]
        }
      ],
      "tags": [
        "coffee",
        "hot-drinks"
      ],
      "metadata": {}
    }
  ],
  "version": "2026.1",
  "updatedAt": "2026-08-24T10:00:00.000Z"
}

Required response fields: providerSlug, categories, offerings.

GET /offerings/:id

Single offering deep lookup by offering ID or offeringCode with option groups

Property	Value
Capability	`CATALOG`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	DISCOVERY_READONLY, TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	No JSON request body
Response schema	Offering

Request

GET /offerings/:id — no JSON body.

Response example

{
  "id": "item_coffee_latte",
  "providerId": "provider_shopla",
  "offeringCode": "COFFEE-LATTE",
  "title": "Latte",
  "description": "Freshly brewed espresso with velvety steamed milk",
  "categorySlug": "drinks",
  "categoryTitle": "Ichimliklar",
  "basePrice": 30000,
  "currency": "UZS",
  "isAvailable": true,
  "variants": [
    {
      "id": "var_standard",
      "name": "Standard (300ml)",
      "basePrice": 30000,
      "isAvailable": true,
      "metadata": {}
    },
    {
      "id": "var_large",
      "name": "Large (450ml)",
      "basePrice": 38000,
      "isAvailable": true,
      "metadata": {}
    }
  ],
  "optionGroups": [
    {
      "id": "grp_milk",
      "name": "Sut turi",
      "isRequired": false,
      "minSelections": 0,
      "maxSelections": 1,
      "options": [
        {
          "id": "opt_whole",
          "name": "Oddiy sut",
          "priceDelta": 0,
          "isDefault": true,
          "isAvailable": true,
          "metadata": {}
        },
        {
          "id": "opt_oat",
          "name": "Suli suti (Oat milk)",
          "priceDelta": 6000,
          "isDefault": false,
          "isAvailable": true,
          "metadata": {}
        }
      ]
    }
  ],
  "tags": [
    "coffee",
    "hot-drinks"
  ],
  "metadata": {}
}

Required response fields: id, providerId, offeringCode, title, basePrice.

GET /search

Real-time keyword and parameter search over provider catalog items

Property	Value
Capability	`SEARCH`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	DISCOVERY_READONLY, TRANSACTIONAL
Requirement	When declared; see fulfillment/location requirements
Request schema	No JSON request body
Response schema	Offering[]

Request

GET /search — no JSON body.

Response example

[
  {
    "id": "item_coffee_latte",
    "providerId": "provider_shopla",
    "offeringCode": "COFFEE-LATTE",
    "title": "Latte",
    "description": "Freshly brewed espresso with velvety steamed milk",
    "categorySlug": "drinks",
    "categoryTitle": "Ichimliklar",
    "basePrice": 30000,
    "currency": "UZS",
    "isAvailable": true,
    "variants": [
      {
        "id": "var_standard",
        "name": "Standard (300ml)",
        "basePrice": 30000,
        "isAvailable": true,
        "metadata": {}
      },
      {
        "id": "var_large",
        "name": "Large (450ml)",
        "basePrice": 38000,
        "isAvailable": true,
        "metadata": {}
      }
    ],
    "optionGroups": [
      {
        "id": "grp_milk",
        "name": "Sut turi",
        "isRequired": false,
        "minSelections": 0,
        "maxSelections": 1,
        "options": [
          {
            "id": "opt_whole",
            "name": "Oddiy sut",
            "priceDelta": 0,
            "isDefault": true,
            "isAvailable": true,
            "metadata": {}
          },
          {
            "id": "opt_oat",
            "name": "Suli suti (Oat milk)",
            "priceDelta": 6000,
            "isDefault": false,
            "isAvailable": true,
            "metadata": {}
          }
        ]
      }
    ],
    "tags": [
      "coffee",
      "hot-drinks"
    ],
    "metadata": {}
  }
]

Required response fields: id, providerId, offeringCode, title, basePrice.

POST /quote

Itemized price calculation with binding total, subtotal, fees and expiration

Property	Value
Capability	`QUOTE`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	RequestQuoteInput
Response schema	NormalizedQuote

Request

{
  "providerSlug": "shopla",
  "locationId": "loc_main",
  "items": [
    {
      "offeringId": "item_coffee_latte",
      "variantId": "var_standard",
      "quantity": 2,
      "selectedOptions": [
        {
          "groupId": "grp_milk",
          "optionId": "opt_whole",
          "quantity": 1
        }
      ]
    }
  ]
}

Response example

{
  "id": "quote_123",
  "providerSlug": "shopla",
  "locationId": "loc_main",
  "currency": "UZS",
  "subtotal": 60000,
  "totalFees": 10000,
  "totalDiscount": 0,
  "total": 70000,
  "lines": [
    {
      "offeringId": "item_coffee_latte",
      "offeringTitle": "Latte",
      "variantId": "var_standard",
      "quantity": 2,
      "unitPrice": 30000,
      "optionsTotal": 0,
      "lineTotal": 60000,
      "selectedOptions": [
        {
          "groupId": "grp_milk",
          "optionId": "opt_whole",
          "name": "Oddiy sut",
          "priceDelta": 0
        }
      ]
    }
  ],
  "fees": [
    {
      "name": "Yetkazib berish xizmati",
      "amount": 10000
    }
  ],
  "discounts": [],
  "expiresAt": "2026-08-24T10:15:00.000Z",
  "metadata": {}
}

Required response fields: id, providerSlug, lines, subtotal, total, expiresAt.

POST /actions

Order/booking creation with idempotency and provider payment checkout handoff

Property	Value
Capability	`ACTION_CREATE`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	CreateActionInput
Response schema	NormalizedAction

Request

{
  "idempotencyKey": "idemp_unique_98765",
  "providerSlug": "shopla",
  "quoteId": "quote_123",
  "customer": {
    "name": "Ali Valiyev",
    "phone": "+998901234567"
  },
  "destination": {
    "raw": "Tashkent, Amir Temur 1"
  },
  "items": [
    {
      "offeringId": "item_coffee_latte",
      "quantity": 2
    }
  ],
  "userConfirmed": true
}

Response example

{
  "id": "act_12345",
  "publicId": "ZY-SHOPLA-12345",
  "externalActionId": "ord_provider_999",
  "providerSlug": "shopla",
  "quoteId": "quote_123",
  "status": "AWAITING_PAYMENT",
  "paymentStatus": "PENDING",
  "subtotal": 60000,
  "fees": 10000,
  "discount": 0,
  "total": 70000,
  "currency": "UZS",
  "customer": {
    "name": "Ali Valiyev",
    "phone": "+998901234567"
  },
  "lines": [
    {
      "offeringId": "item_coffee_latte",
      "offeringTitle": "Latte",
      "quantity": 2,
      "unitPrice": 30000,
      "optionsTotal": 0,
      "lineTotal": 60000
    }
  ],
  "nextAction": {
    "type": "OPEN_URL",
    "url": "https://checkout.shopla.uz/pay/act_12345",
    "label": "Shopla xavfsiz to‘lov sahifasiga o‘tish"
  },
  "fulfillmentType": "STANDARD",
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "metadata": {}
}

Required response fields: providerSlug, quoteId, userConfirmed.

GET /actions/:id

Polling and real-time status inquiry for created action/order

Property	Value
Capability	`ACTION_STATUS`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	No JSON request body
Response schema	NormalizedAction

Request

GET /actions/:id — no JSON body.

Response example

{
  "id": "act_12345",
  "publicId": "ZY-SHOPLA-12345",
  "externalActionId": "ord_provider_999",
  "providerSlug": "shopla",
  "quoteId": "quote_123",
  "status": "PROCESSING",
  "paymentStatus": "PAID",
  "subtotal": 60000,
  "fees": 10000,
  "discount": 0,
  "total": 70000,
  "currency": "UZS",
  "customer": {
    "name": "Ali Valiyev",
    "phone": "+998901234567"
  },
  "lines": [
    {
      "offeringId": "item_coffee_latte",
      "offeringTitle": "Latte",
      "quantity": 2,
      "unitPrice": 30000,
      "optionsTotal": 0,
      "lineTotal": 60000
    }
  ],
  "fulfillmentType": "STANDARD",
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:05:00.000Z",
  "metadata": {}
}

Required response fields: id, publicId, providerSlug, status, lines, subtotal, total, createdAt, updatedAt.

GET /actions/:id/payment-options

Available payment methods discovery for a pending action

Property	Value
Capability	`PAYMENT_OPTIONS`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	TRANSACTIONAL
Requirement	When declared; see fulfillment/location requirements
Request schema	No JSON request body
Response schema	PaymentOption[]

Request

GET /actions/:id/payment-options — no JSON body.

Response example

[
  {
    "id": "pay_click",
    "name": "Click",
    "type": "CLICK",
    "checkoutUrl": "https://checkout.shopla.uz/pay/act_12345?method=click",
    "isAvailable": true
  },
  {
    "id": "pay_payme",
    "name": "Payme",
    "type": "PAYME",
    "checkoutUrl": "https://checkout.shopla.uz/pay/act_12345?method=payme",
    "isAvailable": true
  }
]

Required response fields: id, name, type.

POST /actions/:id/cancel

Action/order cancellation lifecycle with reason description

Property	Value
Capability	`ACTION_CANCEL`
Direction	`ZAYUNO_TO_PROVIDER`
Profiles	TRANSACTIONAL
Requirement	When declared; see fulfillment/location requirements
Request schema	CancelActionInput
Response schema	CancelActionResult

Request

{
  "reason": "Foydalanuvchi buyurtmani bekor qildi"
}

Response example

{
  "success": true,
  "actionId": "act_12345",
  "previousStatus": "AWAITING_PAYMENT",
  "newStatus": "CANCELLED",
  "message": "Foydalanuvchi buyurtmani bekor qildi",
  "refundInitiated": false
}

Required response fields: success, actionId, previousStatus, newStatus, message.

POST /api/v1/webhooks/:providerSlug

Provider status update delivery to Zayuno signed with HMAC-SHA256

Property	Value
Capability	`WEBHOOK`
Direction	`PROVIDER_TO_ZAYUNO`
Profiles	TRANSACTIONAL
Requirement	Required in the listed profiles
Request schema	NormalizedWebhookEvent
Response schema	WebhookIngestionResponse

Request

{
  "eventId": "evt_123",
  "eventType": "action.status_updated",
  "providerSlug": "shopla",
  "actionId": "act_12345",
  "newStatus": "COMPLETED",
  "timestamp": "2026-08-24T10:00:00.000Z"
}

Response example

{
  "success": true
}

Required event request fields: eventId, eventType, providerSlug, timestamp.