{ "openapi": "3.1.0", "info": { "title": "Zayuno Provider Contract", "version": "1.0.0", "description": "Canonical Provider Integration API contract for AI Agent action execution" }, "servers": [ { "url": "https://api.yourbusiness.uz/zayuno", "description": "Provider HTTPS Base URL" } ], "paths": { "/provider-info": { "get": { "summary": "Provider metadata, advertised capabilities, geography and supported verticals", "operationId": "metadata_metadata", "tags": [ "METADATA" ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInfo" }, "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": {} } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/health": { "get": { "summary": "Deterministic health check protocol with latency and system status", "operationId": "health_health", "tags": [ "HEALTH" ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthCheckResult" }, "example": { "status": "HEALTHY", "latencyMs": 18, "timestamp": "2026-08-24T10:00:00.000Z", "details": { "uptimeSeconds": 86400 } } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/locations": { "get": { "summary": "Physical branches, warehouses, pickup locations, or fulfillment centers", "operationId": "locations_locations", "tags": [ "LOCATIONS" ], "parameters": [ { "name": "activeOnly", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Filter only active locations" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "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": {} } ] } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/catalog": { "get": { "summary": "Full catalog hierarchy with categories, offerings, variants, and option groups", "operationId": "catalog_catalog", "tags": [ "CATALOG" ], "parameters": [ { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location / branch filter" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Category slug filter" }, { "name": "context", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON string of dynamic context parameters" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" }, "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" } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/offerings/{id}": { "get": { "summary": "Single offering deep lookup by offering ID or offeringCode with option groups", "operationId": "catalog_offering", "tags": [ "CATALOG" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Offering ID or offeringCode" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offering" }, "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": {} } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/search": { "get": { "summary": "Real-time keyword and parameter search over provider catalog items", "operationId": "search_search", "tags": [ "SEARCH" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search keyword query" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 }, "description": "Max items to return" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Category slug filter" }, { "name": "locationId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location filter" }, { "name": "context", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON string of dynamic context parameters" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Offering" } }, "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": {} } ] } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/quote": { "post": { "summary": "Itemized price calculation with binding total, subtotal, fees and expiration", "operationId": "quote_quote", "tags": [ "QUOTE" ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizedQuote" }, "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": {} } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestQuoteInput" }, "example": { "providerSlug": "shopla", "locationId": "loc_main", "items": [ { "offeringId": "item_coffee_latte", "variantId": "var_standard", "quantity": 2, "selectedOptions": [ { "groupId": "grp_milk", "optionId": "opt_whole", "quantity": 1 } ] } ] } } } } } }, "/actions": { "post": { "summary": "Order/booking creation with idempotency and provider payment checkout handoff", "operationId": "action_create_action_create", "tags": [ "ACTION_CREATE" ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizedAction" }, "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": {} } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateActionInput" }, "example": { "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 } } } } } }, "/actions/{id}": { "get": { "summary": "Polling and real-time status inquiry for created action/order", "operationId": "action_status_action_status", "tags": [ "ACTION_STATUS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Action ID" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizedAction" }, "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": {} } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/actions/{id}/payment-options": { "get": { "summary": "Available payment methods discovery for a pending action", "operationId": "payment_options_payment_options", "tags": [ "PAYMENT_OPTIONS" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Action ID" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOption" } }, "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 } ] } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } } } }, "/actions/{id}/cancel": { "post": { "summary": "Action/order cancellation lifecycle with reason description", "operationId": "action_cancel_action_cancel", "tags": [ "ACTION_CANCEL" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Action ID" } ], "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] }, { "hmacAuth": [] } ], "responses": { "200": { "description": "Muvaffaqiyatli javob", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelActionResult" }, "example": { "success": true, "actionId": "act_12345", "previousStatus": "AWAITING_PAYMENT", "newStatus": "CANCELLED", "message": "Foydalanuvchi buyurtmani bekor qildi", "refundInitiated": false } } } }, "400": { "description": "Noto‘g‘ri so‘rov parametri yoki validation xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INVALID_ARGUMENT", "message": "Kiritilgan parametrlar Zod schemaga mos emas." } } } }, "401": { "description": "Autentifikatsiya xatosi (API kalit yoki token noto‘g‘ri)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "UNAUTHORIZED", "message": "Provider API kaliti talab qilinadi." } } } }, "404": { "description": "Resurs topilmadi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "NOT_FOUND", "message": "So‘ralgan endpoint yoki ID mavjud emas." } } } }, "422": { "description": "Semantik yoki moliyaviy biznes mantiq xatosi (masalan: quote expired yoki quote math invalid)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "QUOTE_MATH_INVALID", "message": "Total narx subtotal + fees - discount formulasiga mos kelmadi." } } } }, "500": { "description": "Provider ichki server xatosi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "INTERNAL_ERROR", "message": "Provider serverida kutilmagan xatolik yuz berdi." } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelActionInput" }, "example": { "reason": "Foydalanuvchi buyurtmani bekor qildi" } } } } } } }, "webhooks": { "providerStatusEvent": { "post": { "summary": "Provider status update event delivery to Zayuno ingestion gateway", "description": "Signed with HMAC-SHA256 in x-zayuno-signature header over raw request body.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizedWebhookEvent" }, "example": { "eventId": "evt_123", "eventType": "action.status_updated", "providerSlug": "shopla", "actionId": "act_12345", "newStatus": "COMPLETED", "timestamp": "2026-08-24T10:00:00.000Z" } } } }, "responses": { "200": { "description": "Event accepted and processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } } }, "components": { "schemas": { "ProviderInfo": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 160 }, "logoUrl": { "type": "string", "maxLength": 96000 }, "iconUrl": { "type": "string", "format": "uri" }, "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "additionalProperties": false }, "manifest": { "type": "object", "properties": { "version": { "type": "number", "enum": [ 1 ] }, "certification": { "type": "object", "properties": { "safeTestEnvironment": { "type": "boolean", "enum": [ true ] } }, "required": [ "safeTestEnvironment" ], "additionalProperties": false, "description": "Certification traffic marked with x-zayuno-certification-run cannot charge or fulfil real orders; quotes expire within 5 seconds" }, "certificationInput": { "type": "object", "properties": { "parameters": { "type": "object", "additionalProperties": {} }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Customer full name, if required by the capability" }, "phone": { "type": "string", "minLength": 6, "description": "Customer phone number, if required by the capability" }, "email": { "type": "string", "format": "email", "nullable": true }, "externalId": { "type": "string" } }, "additionalProperties": false }, "locations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 80 }, "address": { "type": "object", "properties": { "raw": { "type": "string", "minLength": 1, "description": "Human-readable address or destination description" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false } }, "required": [ "raw" ], "additionalProperties": false }, "locationId": { "type": "string", "minLength": 1 } }, "required": [ "role" ], "additionalProperties": false } }, "fulfillmentType": { "type": "string" } }, "additionalProperties": false, "description": "Non-production fixture inputs for capability certification; never real customer data" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "object", "additionalProperties": { "type": "object", "properties": { "inputMode": { "type": "string", "enum": [ "OFFERING", "PARAMETERS", "EITHER" ] }, "required": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 100 }, "parametersSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ], "default": "object" }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array", "object" ] }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "enum": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 50 }, "format": { "type": "string", "enum": [ "date", "date-time", "email", "uri", "uuid" ] }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "minLength": { "type": "integer", "minimum": 0 }, "maxLength": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "minItems": { "type": "integer", "minimum": 0 }, "maxItems": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "default": {}, "examples": { "type": "array", "maxItems": 10 }, "items": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties/properties/parametersSchema/properties/properties/additionalProperties" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties/properties/parametersSchema/properties/properties/additionalProperties" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "default": {} }, "required": { "type": "array", "items": { "type": "string" }, "default": [] }, "additionalProperties": { "type": "boolean", "default": true } }, "additionalProperties": false }, "customerRequirements": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "OPTIONAL", "REQUIRED", "NOT_NEEDED" ] }, "phone": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties/properties/customerRequirements/properties/name" }, "email": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties/properties/customerRequirements/properties/name" } }, "additionalProperties": false } }, "additionalProperties": false } }, "customerRequirements": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties/properties/customerRequirements" }, "parametersSchema": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties/properties/parametersSchema" }, "supportedFulfillmentModes": { "type": "array", "items": { "type": "string" } }, "fulfillmentRequirements": { "type": "object", "additionalProperties": { "$ref": "#/properties/manifest/properties/requirements/additionalProperties" } }, "supportedLocationRoles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 80 }, "required": { "type": "boolean" }, "title": { "type": "string", "maxLength": 100 } }, "required": [ "role" ], "additionalProperties": false } }, "supportedPaymentMethods": { "type": "array", "items": { "type": "string" } }, "supportedCurrencies": { "type": "array", "items": { "type": "string" } }, "lifecycle": { "type": "object", "properties": { "status": { "type": "boolean" }, "cancel": { "type": "boolean" }, "webhook": { "type": "boolean" } }, "additionalProperties": false }, "branding": { "$ref": "#/properties/branding" }, "presentationHints": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "actionLabel": { "type": "string", "maxLength": 100 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "maxLength": 160 }, "label": { "type": "string", "maxLength": 100 }, "format": { "type": "string", "enum": [ "text", "date", "money", "link" ] } }, "required": [ "path", "label" ], "additionalProperties": false }, "maxItems": 30 } }, "additionalProperties": false } }, "required": [ "version" ], "additionalProperties": false }, "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "SANDBOX", "ACTIVE", "SUSPENDED", "DISABLED" ] }, "type": { "type": "string", "enum": [ "RETAIL", "DELIVERY", "SERVICES", "BOOKINGS", "TICKETING", "DIGITAL", "COMMERCE", "OTHER" ] }, "environment": { "type": "string", "enum": [ "LIVE", "SANDBOX", "STAGING" ], "default": "LIVE" }, "fulfillmentMode": { "type": "string", "enum": [ "ONSITE", "DELIVERY", "PICKUP", "REMOTE", "HYBRID" ] }, "category": { "type": "string", "enum": [ "FOOD_AND_DRINK", "RETAIL", "TRANSPORT", "TICKETING", "TRAVEL", "ACCOMMODATION", "RECRUITMENT", "LOGISTICS", "HEALTHCARE", "HOME_SERVICES", "PROFESSIONAL_SERVICES", "DIGITAL_SERVICES", "OTHER" ], "default": "OTHER" }, "subcategory": { "type": "string", "minLength": 1, "maxLength": 100 }, "geography": { "type": "array", "items": { "type": "string" }, "default": [ "UZ" ] }, "adapterType": { "type": "string", "default": "sandbox" }, "authMethod": { "type": "string", "enum": [ "API_KEY", "BEARER_TOKEN", "HMAC_SIGNATURE", "OAUTH2_CLIENT_CREDENTIALS", "NONE" ], "default": "API_KEY" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "METADATA", "HEALTH", "LOCATIONS", "CATALOG", "SEARCH", "QUOTE", "ACTION_CREATE", "ACTION_STATUS", "ACTION_CANCEL", "PAYMENT_OPTIONS", "WEBHOOK" ] } }, "baseUrl": { "type": "string" }, "supportContact": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "phone": { "type": "string" }, "telegram": { "type": "string" }, "email": { "type": "string" }, "workingHours": { "type": "string" }, "supportUrl": { "type": "string" }, "supportNote": { "type": "string", "maxLength": 500 }, "locale": { "type": "string" } }, "additionalProperties": false } ] }, "isCertified": { "type": "boolean", "default": false }, "isPublished": { "type": "boolean", "default": false }, "contractVersion": { "type": "string", "default": "v1 legacy" }, "complianceStatus": { "type": "string", "enum": [ "COMPLIANT", "RECERTIFICATION_REQUIRED", "FAILED", "GRANDFATHERED" ], "default": "RECERTIFICATION_REQUIRED" }, "profile": { "type": "string", "enum": [ "READ_ONLY", "TRANSACTIONAL" ], "default": "READ_ONLY" }, "discoveryVisibility": { "type": "string", "enum": [ "VISIBLE", "LIMITED", "HIDDEN" ], "default": "HIDDEN" }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "slug", "name", "status", "type", "capabilities" ], "additionalProperties": false }, "HealthCheckResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "HEALTHY", "DEGRADED", "DOWN" ] }, "latencyMs": { "type": "number", "minimum": 0 }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status", "latencyMs", "timestamp" ], "additionalProperties": false }, "CatalogCategory": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "displayOrder": { "type": "integer", "default": 0 }, "parentCategorySlug": { "type": "string" }, "offeringsCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "slug", "title" ], "additionalProperties": false }, "OptionItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priceDelta": { "type": "number", "default": 0 }, "isDefault": { "type": "boolean", "default": false }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name" ], "additionalProperties": false }, "OptionGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "minSelections": { "type": "integer", "minimum": 0, "default": 0 }, "maxSelections": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1 }, "isRequired": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priceDelta": { "type": "number", "default": 0 }, "isDefault": { "type": "boolean", "default": false }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name" ], "additionalProperties": false }, "default": [] } }, "required": [ "id", "name" ], "additionalProperties": false }, "OfferingVariant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "e.g. \"Standard\", \"Pro\", \"Small\", \"Large\"" }, "sku": { "type": "string" }, "basePrice": { "type": "number", "minimum": 0 }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name", "basePrice" ], "additionalProperties": false }, "Offering": { "type": "object", "properties": { "presentationHints": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "actionLabel": { "type": "string", "maxLength": 100 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "maxLength": 160 }, "label": { "type": "string", "maxLength": 100 }, "format": { "type": "string", "enum": [ "text", "date", "money", "link" ] } }, "required": [ "path", "label" ], "additionalProperties": false }, "maxItems": 30 } }, "additionalProperties": false }, "id": { "type": "string" }, "providerId": { "type": "string" }, "offeringCode": { "type": "string", "description": "Provider-specific catalog item identifier" }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "categorySlug": { "type": "string" }, "categoryTitle": { "type": "string" }, "imageUrl": { "type": "string", "maxLength": 2048 }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "$ref": "#/properties/imageUrl" }, "altText": { "type": "string", "maxLength": 255 }, "order": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 }, "thumbnailUrl": { "$ref": "#/properties/imageUrl" }, "aspectRatio": { "type": "string", "pattern": "^(\\d+:\\d+)$" } }, "required": [ "url" ], "additionalProperties": false }, "maxItems": 10 }, "basePrice": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "enum": [ "UZS", "USD", "EUR" ], "default": "UZS" }, "isAvailable": { "type": "boolean", "default": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "e.g. \"Standard\", \"Pro\", \"Small\", \"Large\"" }, "sku": { "type": "string" }, "basePrice": { "type": "number", "minimum": 0 }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name", "basePrice" ], "additionalProperties": false }, "default": [] }, "optionGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "minSelections": { "type": "integer", "minimum": 0, "default": 0 }, "maxSelections": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1 }, "isRequired": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priceDelta": { "type": "number", "default": 0 }, "isDefault": { "type": "boolean", "default": false }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name" ], "additionalProperties": false }, "default": [] } }, "required": [ "id", "name" ], "additionalProperties": false }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "parametersSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ], "default": "object" }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array", "object" ] }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "enum": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 50 }, "format": { "type": "string", "enum": [ "date", "date-time", "email", "uri", "uuid" ] }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "minLength": { "type": "integer", "minimum": 0 }, "maxLength": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "minItems": { "type": "integer", "minimum": 0 }, "maxItems": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "default": {}, "examples": { "type": "array", "maxItems": 10 }, "items": { "$ref": "#/properties/parametersSchema/properties/properties/additionalProperties" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/properties/parametersSchema/properties/properties/additionalProperties" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "default": {} }, "required": { "type": "array", "items": { "type": "string" }, "default": [] }, "additionalProperties": { "type": "boolean", "default": true } }, "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "providerId", "offeringCode", "title", "basePrice" ], "additionalProperties": false }, "Catalog": { "type": "object", "properties": { "providerSlug": { "type": "string" }, "locationId": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "displayOrder": { "type": "integer", "default": 0 }, "parentCategorySlug": { "type": "string" }, "offeringsCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "slug", "title" ], "additionalProperties": false } }, "offerings": { "type": "array", "items": { "type": "object", "properties": { "presentationHints": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "actionLabel": { "type": "string", "maxLength": 100 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "maxLength": 160 }, "label": { "type": "string", "maxLength": 100 }, "format": { "type": "string", "enum": [ "text", "date", "money", "link" ] } }, "required": [ "path", "label" ], "additionalProperties": false }, "maxItems": 30 } }, "additionalProperties": false }, "id": { "type": "string" }, "providerId": { "type": "string" }, "offeringCode": { "type": "string", "description": "Provider-specific catalog item identifier" }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "categorySlug": { "type": "string" }, "categoryTitle": { "type": "string" }, "imageUrl": { "type": "string", "maxLength": 2048 }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "$ref": "#/properties/offerings/items/properties/imageUrl" }, "altText": { "type": "string", "maxLength": 255 }, "order": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0 }, "thumbnailUrl": { "$ref": "#/properties/offerings/items/properties/imageUrl" }, "aspectRatio": { "type": "string", "pattern": "^(\\d+:\\d+)$" } }, "required": [ "url" ], "additionalProperties": false }, "maxItems": 10 }, "basePrice": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "enum": [ "UZS", "USD", "EUR" ], "default": "UZS" }, "isAvailable": { "type": "boolean", "default": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "e.g. \"Standard\", \"Pro\", \"Small\", \"Large\"" }, "sku": { "type": "string" }, "basePrice": { "type": "number", "minimum": 0 }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name", "basePrice" ], "additionalProperties": false }, "default": [] }, "optionGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "minSelections": { "type": "integer", "minimum": 0, "default": 0 }, "maxSelections": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1 }, "isRequired": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priceDelta": { "type": "number", "default": 0 }, "isDefault": { "type": "boolean", "default": false }, "isAvailable": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name" ], "additionalProperties": false }, "default": [] } }, "required": [ "id", "name" ], "additionalProperties": false }, "default": [] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "parametersSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ], "default": "object" }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array", "object" ] }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "enum": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 50 }, "format": { "type": "string", "enum": [ "date", "date-time", "email", "uri", "uuid" ] }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "minLength": { "type": "integer", "minimum": 0 }, "maxLength": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "minItems": { "type": "integer", "minimum": 0 }, "maxItems": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "default": {}, "examples": { "type": "array", "maxItems": 10 }, "items": { "$ref": "#/properties/offerings/items/properties/parametersSchema/properties/properties/additionalProperties" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/properties/offerings/items/properties/parametersSchema/properties/properties/additionalProperties" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "default": {} }, "required": { "type": "array", "items": { "type": "string" }, "default": [] }, "additionalProperties": { "type": "boolean", "default": true } }, "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "providerId", "offeringCode", "title", "basePrice" ], "additionalProperties": false } }, "parametersSchema": { "$ref": "#/properties/offerings/items/properties/parametersSchema" }, "version": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "providerSlug", "categories", "offerings" ], "additionalProperties": false }, "Location": { "type": "object", "properties": { "id": { "type": "string" }, "providerId": { "type": "string" }, "providerLocationId": { "type": "string", "description": "External provider identifier for this branch or location" }, "name": { "type": "string", "minLength": 1 }, "address": { "type": "string", "minLength": 1 }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false }, "operatingHours": { "type": "object", "properties": { "open": { "type": "string", "description": "Opening time e.g. \"09:00\"" }, "close": { "type": "string", "description": "Closing time e.g. \"22:00\"" }, "days": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "Active days of week [1=Mon..7=Sun]" } }, "required": [ "open", "close", "days" ], "additionalProperties": false }, "serviceRadiusKm": { "type": "number", "minimum": 0, "default": 10 }, "isActive": { "type": "boolean", "default": true }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "providerId", "providerLocationId", "name", "address" ], "additionalProperties": false }, "RequestQuoteInput": { "type": "object", "properties": { "providerSlug": { "type": "string", "minLength": 1, "description": "Unique provider slug" }, "locationId": { "type": "string", "description": "Optional provider location identifier" }, "items": { "type": "array", "items": { "type": "object", "properties": { "offeringId": { "type": "string", "minLength": 1, "description": "Target offering or item identifier" }, "variantId": { "type": "string", "description": "Optional variant identifier" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1, "description": "Quantity of units" }, "selectedOptions": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "optionId": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1, "description": "How many units of this option apply to EACH requested base item. For an item quantity of N, the option charge is priceDelta × selected option quantity × N." } }, "required": [ "groupId", "optionId" ], "additionalProperties": false }, "default": [], "description": "Selected customizations or options" } }, "required": [ "offeringId" ], "additionalProperties": false }, "default": [], "description": "Offering inputs; may be empty only if the provider manifest permits parameter-based input" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 80 }, "address": { "type": "object", "properties": { "raw": { "type": "string", "minLength": 1, "description": "Human-readable address or destination description" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false } }, "required": [ "raw" ], "additionalProperties": false }, "locationId": { "type": "string", "minLength": 1 } }, "required": [ "role" ], "additionalProperties": false } }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Customer full name, if required by the capability" }, "phone": { "type": "string", "minLength": 6, "description": "Customer phone number, if required by the capability" }, "email": { "type": "string", "format": "email", "nullable": true }, "externalId": { "type": "string" } }, "additionalProperties": false }, "paymentMethod": { "type": "string" }, "fulfillmentType": { "type": "string", "description": "Fulfillment mode (e.g. STANDARD, EXPRESS, PICKUP, DIGITAL)" }, "destination": { "$ref": "#/properties/locations/items/properties/address", "description": "Optional physical delivery address or service destination" }, "promoCode": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Optional provider-issued promotion or discount code. The provider validates and prices it; Zayuno never invents discounts." }, "parameters": { "type": "object", "additionalProperties": {}, "description": "Optional domain or provider-specific parameters" }, "environment": { "type": "string", "description": "Target execution environment context (e.g. LIVE, SANDBOX). Defaults to LIVE." } }, "required": [ "providerSlug" ], "additionalProperties": false }, "NormalizedQuote": { "type": "object", "properties": { "requirements": { "type": "object", "properties": { "inputMode": { "type": "string", "enum": [ "OFFERING", "PARAMETERS", "EITHER" ] }, "required": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 100 }, "parametersSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ], "default": "object" }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array", "object" ] }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "enum": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 50 }, "format": { "type": "string", "enum": [ "date", "date-time", "email", "uri", "uuid" ] }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "minLength": { "type": "integer", "minimum": 0 }, "maxLength": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "minItems": { "type": "integer", "minimum": 0 }, "maxItems": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "default": {}, "examples": { "type": "array", "maxItems": 10 }, "items": { "$ref": "#/properties/requirements/properties/parametersSchema/properties/properties/additionalProperties" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/properties/requirements/properties/parametersSchema/properties/properties/additionalProperties" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "default": {} }, "required": { "type": "array", "items": { "type": "string" }, "default": [] }, "additionalProperties": { "type": "boolean", "default": true } }, "additionalProperties": false }, "customerRequirements": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "OPTIONAL", "REQUIRED", "NOT_NEEDED" ] }, "phone": { "$ref": "#/properties/requirements/properties/customerRequirements/properties/name" }, "email": { "$ref": "#/properties/requirements/properties/customerRequirements/properties/name" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Additional requirements for creating the action from this quote" }, "id": { "type": "string", "description": "Unique platform quote ID" }, "providerSlug": { "type": "string" }, "locationId": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "offeringId": { "type": "string" }, "offeringTitle": { "type": "string" }, "variantId": { "type": "string" }, "variantTitle": { "type": "string" }, "unitPrice": { "type": "number", "minimum": 0 }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "optionsTotal": { "type": "number", "default": 0 }, "lineTotal": { "type": "number", "minimum": 0 }, "selectedOptions": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "optionId": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1, "description": "How many units of this option apply to EACH requested base item. For an item quantity of N, the option charge is priceDelta × selected option quantity × N." } }, "required": [ "groupId", "optionId" ], "additionalProperties": false }, "default": [] } }, "required": [ "offeringId", "offeringTitle", "unitPrice", "quantity", "lineTotal" ], "additionalProperties": false } }, "subtotal": { "type": "number", "minimum": 0, "description": "Base item subtotal" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "e.g. \"Fulfillment Fee\", \"Processing Fee\", \"Service Fee\"" }, "amount": { "type": "number", "minimum": 0 } }, "required": [ "name", "amount" ], "additionalProperties": false }, "default": [] }, "totalFees": { "type": "number", "minimum": 0, "default": 0 }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number", "minimum": 0 } }, "required": [ "amount" ], "additionalProperties": false }, "default": [] }, "totalDiscount": { "type": "number", "minimum": 0, "default": 0 }, "total": { "type": "number", "minimum": 0, "description": "Final payable amount in quote currency" }, "currency": { "type": "string", "enum": [ "UZS", "USD", "EUR" ], "default": "UZS" }, "expiresAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when quote prices expire; Z and numeric offsets are accepted" }, "estimatedDurationMinutes": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "parameters": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "providerSlug", "lines", "subtotal", "total", "expiresAt" ], "additionalProperties": false }, "CreateActionInput": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "description": "Unique client-generated idempotency key (UUID or cryptographically random string). Server auto-generates if omitted." }, "providerSlug": { "type": "string", "minLength": 1, "description": "Target provider slug" }, "quoteId": { "type": "string", "minLength": 1, "description": "Verified quote ID reviewed and confirmed by the user before submission" }, "locationId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "offeringId": { "type": "string", "minLength": 1 }, "variantId": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1 }, "selectedOptions": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "optionId": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1 } }, "required": [ "groupId", "optionId" ], "additionalProperties": false }, "default": [] } }, "required": [ "offeringId" ], "additionalProperties": false }, "default": [], "description": "Offering inputs, or empty for declared parameter-based actions" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 80 }, "address": { "type": "object", "properties": { "raw": { "type": "string", "minLength": 1, "description": "Human-readable address or destination description" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false } }, "required": [ "raw" ], "additionalProperties": false }, "locationId": { "type": "string", "minLength": 1 } }, "required": [ "role" ], "additionalProperties": false } }, "promoCode": { "type": "string", "minLength": 1, "maxLength": 64 }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Customer full name, if required by the capability" }, "phone": { "type": "string", "minLength": 6, "description": "Customer phone number, if required by the capability" }, "email": { "type": "string", "format": "email", "nullable": true }, "externalId": { "type": "string" } }, "additionalProperties": false, "description": "Customer contact info when required by the provider or fulfillment flow" }, "destination": { "$ref": "#/properties/locations/items/properties/address", "description": "Optional destination address or fulfillment location" }, "fulfillmentType": { "type": "string", "description": "e.g. STANDARD, EXPRESS, PICKUP, DIGITAL" }, "paymentMethod": { "type": "string", "description": "e.g. \"payme\", \"card\", \"cash\", \"invoice\"" }, "parameters": { "type": "object", "additionalProperties": {}, "description": "Custom parameters passed to provider adapter" }, "environment": { "type": "string", "description": "Target execution environment context (e.g. LIVE, SANDBOX). Defaults to LIVE." }, "quote": { "type": "object", "properties": { "id": { "type": "string" }, "subtotal": { "type": "number", "minimum": 0 }, "fees": { "type": "number", "minimum": 0, "default": 0 }, "discount": { "type": "number", "minimum": 0, "default": 0 }, "total": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "enum": [ "UZS", "USD", "EUR" ], "default": "UZS" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "offeringId": { "type": "string" }, "offeringTitle": { "type": "string" }, "variantId": { "type": "string" }, "variantTitle": { "type": "string" }, "unitPrice": { "type": "number", "minimum": 0 }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "optionsTotal": { "type": "number", "default": 0 }, "lineTotal": { "type": "number", "minimum": 0 }, "selectedOptions": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "optionId": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1, "description": "How many units of this option apply to EACH requested base item. For an item quantity of N, the option charge is priceDelta × selected option quantity × N." } }, "required": [ "groupId", "optionId" ], "additionalProperties": false }, "default": [] } }, "required": [ "offeringId", "offeringTitle", "unitPrice", "quantity", "lineTotal" ], "additionalProperties": false }, "default": [] } }, "required": [ "subtotal", "total" ], "additionalProperties": false, "description": "Canonical verified quote snapshot passed down to provider adapter" }, "userConfirmed": { "type": "boolean", "enum": [ true ], "description": "Must be true after the user explicitly confirms the reviewed quote" } }, "required": [ "providerSlug", "quoteId", "userConfirmed" ], "additionalProperties": false }, "NormalizedAction": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 80 }, "address": { "type": "object", "properties": { "raw": { "type": "string", "minLength": 1, "description": "Human-readable address or destination description" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "type": "string" }, "postalCode": { "type": "string" }, "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ], "additionalProperties": false } }, "required": [ "raw" ], "additionalProperties": false }, "locationId": { "type": "string", "minLength": 1 } }, "required": [ "role" ], "additionalProperties": false } }, "id": { "type": "string", "description": "Internal UUID" }, "publicId": { "type": "string", "description": "Public-facing reference ID (e.g. \"ZY-ACT-12345\")" }, "providerSlug": { "type": "string" }, "providerName": { "type": "string" }, "externalActionId": { "type": "string", "description": "External ID assigned by the provider system" }, "quoteId": { "type": "string" }, "locationId": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATED", "AWAITING_PAYMENT", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED", "FAILED" ] }, "nextAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OPEN_URL", "REDIRECT", "CONFIRMATION_REQUIRED", "NONE" ], "default": "OPEN_URL" }, "url": { "type": "string", "format": "uri", "description": "Provider-owned checkout or verification URL" }, "label": { "type": "string", "default": "Pay now" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "url" ], "additionalProperties": false, "description": "Provider-owned checkout or handoff instructions" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "offeringId": { "type": "string" }, "offeringTitle": { "type": "string" }, "variantId": { "type": "string" }, "variantTitle": { "type": "string" }, "unitPrice": { "type": "number", "minimum": 0 }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "optionsTotal": { "type": "number", "default": 0 }, "lineTotal": { "type": "number", "minimum": 0 }, "selectedOptions": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "optionId": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 1, "description": "How many units of this option apply to EACH requested base item. For an item quantity of N, the option charge is priceDelta × selected option quantity × N." } }, "required": [ "groupId", "optionId" ], "additionalProperties": false }, "default": [] } }, "required": [ "offeringId", "offeringTitle", "unitPrice", "quantity", "lineTotal" ], "additionalProperties": false } }, "subtotal": { "type": "number", "minimum": 0 }, "fees": { "type": "number", "minimum": 0, "default": 0 }, "discount": { "type": "number", "minimum": 0, "default": 0 }, "total": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "enum": [ "UZS", "USD", "EUR" ], "default": "UZS" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Customer full name, if required by the capability" }, "phone": { "type": "string", "minLength": 6, "description": "Customer phone number, if required by the capability" }, "email": { "type": "string", "format": "email", "nullable": true }, "externalId": { "type": "string" } }, "additionalProperties": false }, "destination": { "$ref": "#/properties/locations/items/properties/address" }, "fulfillmentType": { "type": "string", "default": "STANDARD" }, "paymentMethod": { "type": "string" }, "paymentStatus": { "type": "string", "enum": [ "PENDING", "AUTHORIZED", "PAID", "FAILED", "REFUNDED" ], "default": "PENDING" }, "paymentUrl": { "type": "string", "format": "uri", "description": "Legacy checkout URL alias (prefer nextAction.url)" }, "idempotencyKey": { "type": "string" }, "supportContact": { "type": "object", "properties": { "phone": { "type": "string" }, "telegram": { "type": "string" }, "email": { "type": "string" }, "workingHours": { "type": "string" }, "supportUrl": { "type": "string" }, "supportNote": { "type": "string", "maxLength": 500 }, "locale": { "type": "string" } }, "additionalProperties": false, "description": "Official support and escalation channels for the provider" }, "parameters": { "type": "object", "additionalProperties": {}, "default": {} }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATED", "AWAITING_PAYMENT", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED", "FAILED" ] }, "description": { "type": "string" }, "source": { "type": "string", "enum": [ "AI_AGENT", "PROVIDER_WEBHOOK", "SYSTEM_WORKER", "USER", "ADMIN" ] }, "payload": { "type": "object", "additionalProperties": {} }, "createdAt": { "$ref": "#/properties/nextAction/properties/expiresAt" } }, "required": [ "id", "status", "description", "source", "createdAt" ], "additionalProperties": false }, "default": [] }, "createdAt": { "$ref": "#/properties/nextAction/properties/expiresAt" }, "updatedAt": { "$ref": "#/properties/nextAction/properties/expiresAt" } }, "required": [ "id", "publicId", "providerSlug", "status", "lines", "subtotal", "total", "createdAt", "updatedAt" ], "additionalProperties": false }, "GetActionInput": { "type": "object", "properties": { "providerSlug": { "type": "string" }, "actionId": { "type": "string", "minLength": 1, "description": "Public ID (e.g. \"ZY-ACT-12345\") or UUID" }, "environment": { "type": "string", "description": "Target execution environment context (defaults to LIVE)" } }, "required": [ "actionId" ], "additionalProperties": false }, "CancelActionInput": { "type": "object", "properties": { "providerSlug": { "type": "string" }, "actionId": { "type": "string", "minLength": 1, "description": "Public action ID or UUID" }, "reasonCode": { "type": "string", "enum": [ "CUSTOMER_CANCELLED", "PROVIDER_REJECTED", "ITEM_UNAVAILABLE", "PAYMENT_TIMEOUT", "PAYMENT_FAILED", "DUPLICATE_ACTION", "INVALID_CUSTOMER_INFORMATION", "PROVIDER_TIMEOUT", "SYSTEM_ERROR", "OTHER" ], "description": "Stable cancellation category; defaults to CUSTOMER_CANCELLED" }, "reason": { "type": "string", "minLength": 3, "maxLength": 500, "description": "Clear human-readable reason for cancellation" }, "environment": { "type": "string", "description": "Target execution environment context (defaults to LIVE)" } }, "required": [ "actionId" ], "additionalProperties": false }, "CancelActionResult": { "type": "object", "properties": { "success": { "type": "boolean" }, "actionId": { "type": "string", "description": "Stable Zayuno public action reference" }, "externalActionId": { "type": "string", "description": "Provider action identifier, when the caller is authorized to use it" }, "previousStatus": { "type": "string", "enum": [ "CREATED", "AWAITING_PAYMENT", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED", "FAILED" ] }, "newStatus": { "type": "string", "enum": [ "CREATED", "AWAITING_PAYMENT", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED", "FAILED" ] }, "message": { "type": "string" }, "refundInitiated": { "type": "boolean", "default": false } }, "required": [ "success", "actionId", "previousStatus", "newStatus", "message" ], "additionalProperties": false }, "PaymentOption": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "e.g. \"Payme\", \"Click\", \"Bank Card\", \"Cash / Offline\"" }, "type": { "type": "string", "enum": [ "PAYME", "CLICK", "UZUM", "CARD_ONLINE", "CASH_ON_DELIVERY", "INVOICE", "EXTERNAL_PROVIDER" ] }, "isOnline": { "type": "boolean", "default": true }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Provider-supplied external secure payment URL" }, "qrCodeUrl": { "type": "string", "format": "uri" }, "instructions": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "type": "string", "enum": [ "UZS", "USD", "EUR" ], "default": "UZS" }, "default": [ "UZS" ] }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "id", "name", "type" ], "additionalProperties": false }, "NormalizedWebhookEvent": { "type": "object", "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "action.created", "action.status_updated", "action.completed", "action.cancelled", "action.failed", "payment.received", "payment.failed", "catalog.updated", "location.status_changed" ] }, "providerSlug": { "type": "string" }, "actionId": { "type": "string" }, "externalActionId": { "type": "string" }, "newStatus": { "type": "string", "enum": [ "CREATED", "AWAITING_PAYMENT", "CONFIRMED", "PROCESSING", "COMPLETED", "CANCELLED", "FAILED" ] }, "newPaymentStatus": { "type": "string", "enum": [ "PENDING", "AUTHORIZED", "PAID", "FAILED", "REFUNDED" ] }, "timestamp": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "payload": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "eventId", "eventType", "providerSlug", "timestamp" ], "additionalProperties": false }, "DynamicServiceContext": { "type": "object", "properties": { "origin": { "type": "string", "minLength": 1, "maxLength": 160 }, "destination": { "type": "string", "minLength": 1, "maxLength": 160 }, "startAt": { "type": "string", "format": "date-time" }, "endAt": { "$ref": "#/properties/startAt" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 0, "default": 1 }, "children": { "type": "integer", "minimum": 0, "default": 0 }, "infants": { "type": "integer", "minimum": 0, "default": 0 } }, "additionalProperties": false }, "locale": { "type": "string", "minLength": 2, "maxLength": 20 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80 }, "preferences": { "type": "object", "additionalProperties": {}, "default": {} } }, "additionalProperties": false }, "DynamicParameterDeclaration": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ], "default": "object" }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "properties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array", "object" ] }, "title": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "enum": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 50 }, "format": { "type": "string", "enum": [ "date", "date-time", "email", "uri", "uuid" ] }, "minimum": { "type": "number" }, "maximum": { "type": "number" }, "minLength": { "type": "integer", "minimum": 0 }, "maxLength": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "minItems": { "type": "integer", "minimum": 0 }, "maxItems": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "default": {}, "examples": { "type": "array", "maxItems": 10 }, "items": { "$ref": "#/properties/properties/additionalProperties" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/properties/properties/additionalProperties" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "default": {} }, "required": { "type": "array", "items": { "type": "string" }, "default": [] }, "additionalProperties": { "type": "boolean", "default": true } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error description" }, "details": { "type": "object", "description": "Optional structured diagnostic error details" } } } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-provider-api-key", "description": "Static secret key issued or configured by provider" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token issued by provider" }, "hmacAuth": { "type": "apiKey", "in": "header", "name": "x-zayuno-signature", "description": "HMAC-SHA256 signature calculated over raw request body" } } }, "x-zayuno-webhook-ingestion": { "method": "POST", "url": "https://api.zayuno.uz/api/v1/webhooks/:providerSlug", "description": "Provider-to-Zayuno signed event destination." } }