{ "openapi": "3.1.0", "info": { "title": "Qazpila Public API", "description": "B2B-commerce API для AI-агентов и автоматизированных систем закупок. Foundation для recurring orders, dealer-pricing, multi-currency (KZT/RUB/USD). См. также `/llms.txt` и `/agents.txt` для high-level overview.", "version": "1.0.0", "contact": { "name": "Qazpila Integration", "email": "integration@qazpila.kz", "url": "https://www.qazpila.com/contacts" }, "license": { "name": "Proprietary — see /offer", "url": "https://www.qazpila.com/offer" }, "x-ai-instructions": "You are interacting with a B2B bandsaw blade supplier in Kazakhstan. Always include Idempotency-Key header (UUIDv4) for POST mutations. Use Bearer authentication with bot__ tokens for org-scoped operations. High-value orders may route to human approval — check order.status=\"awaiting_approval\" in response." }, "servers": [ { "url": "https://www.qazpila.com/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "health", "description": "Service health checks (no auth)" }, { "name": "products", "description": "Product catalog (public read)" }, { "name": "orders", "description": "Order creation and tracking (auth required)" }, { "name": "organizations", "description": "B2B organizations management (auth required)" } ], "paths": { "/health": { "get": { "tags": [ "health" ], "summary": "Service health check", "description": "Returns 200 OK with timestamp + version. No auth. Intended for uptime monitoring and agent connectivity check.", "security": [], "responses": { "200": { "description": "Service healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" } }, "required": [ "status", "timestamp" ] } } } } }, "x-rate-limit": "300 requests/minute", "x-idempotent": true } }, "/orders": { "get": { "tags": [ "orders" ], "summary": "List orders of the authenticated user / organization", "description": "Returns paginated list of orders. For bot-accounts: scoped to bot.organization_id. For human users: scoped to auth.uid().", "parameters": [ { "name": "status", "in": "query", "description": "Filter by order status", "schema": { "type": "string", "enum": [ "awaiting_approval", "awaiting_payment", "paid", "processing", "shipped", "delivered", "cancelled", "refunded" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "List of orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-rate-limit": "60 requests/minute per bot-token" }, "post": { "tags": [ "orders" ], "summary": "Create order", "description": "Creates new order with idempotency protection. Requires `Idempotency-Key` header (UUIDv4 recommended). High-value orders above org-configured threshold return `status: \"awaiting_approval\"` requiring human action.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUIDv4 — same key returns the same result for 24h (Stripe convention)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Spending limit exceeded (bot-token only)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Idempotency-Key conflict (same key, different payload)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-rate-limit": "30 requests/minute per bot-token", "x-idempotent": true, "x-ai-instructions": "Always generate fresh UUIDv4 for Idempotency-Key when creating new order. Reuse the same key only when retrying a failed request — never to \"force overwrite\" an existing order. Order with status=\"awaiting_approval\" means human review pending; do not retry until approved." } }, "/orders/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "orders" ], "summary": "Get order details", "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/organizations": { "post": { "tags": [ "organizations" ], "summary": "Create organization", "description": "Creates a new B2B organization owned by the authenticated user. Required Idempotency-Key.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } } }, "responses": { "201": { "description": "Organization created" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Idempotency conflict" } }, "x-idempotent": true } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bot__ (Phase 2 — coming Q3 2026) | Supabase JWT (transitional, pilots only)", "description": "Bot service-accounts: org-admin creates in /account/organization/bots. Tokens never logged in plaintext." } }, "schemas": { "Order": { "type": "object", "required": [ "id", "status", "total_kzt", "currency", "items", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "awaiting_approval", "awaiting_payment", "paid", "processing", "shipped", "delivered", "cancelled", "refunded" ] }, "total_kzt": { "type": "integer", "minimum": 0, "description": "Order total in KZT (integer)" }, "currency": { "type": "string", "enum": [ "KZT", "RUB", "USD" ], "default": "KZT" }, "org_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Organization scope (null for personal/B2C)" }, "actor_type": { "type": "string", "enum": [ "human", "bot" ], "description": "Who created this order" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "tracking_number": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "approval_required_until": { "type": "string", "format": "date-time", "nullable": true, "description": "For awaiting_approval orders: deadline for human action" } } }, "OrderItem": { "type": "object", "required": [ "sku", "quantity", "price_kzt" ], "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "price_kzt": { "type": "integer", "minimum": 0, "description": "Unit price in KZT at moment of order (snapshot)" } } }, "CreateOrderRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 } } } }, "org_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Override organization scope (must match bot-token org)" }, "shipping_address_id": { "type": "string", "format": "uuid", "nullable": true }, "currency": { "type": "string", "enum": [ "KZT", "RUB", "USD" ], "default": "KZT" }, "note": { "type": "string", "maxLength": 500, "nullable": true }, "subscription_id": { "type": "string", "format": "uuid", "nullable": true, "description": "If part of recurring subscription (Phase 4)" } } }, "CreateOrganizationRequest": { "type": "object", "required": [ "name", "tax_id" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "tax_id": { "type": "string", "description": "БИН (12 digits for KZ orgs)" }, "country": { "type": "string", "enum": [ "KZ", "RU", "UZ", "KG", "AM", "AZ", "BY", "MD", "TJ", "TM", "GE", "UA" ], "default": "KZ" } } }, "Problem": { "type": "object", "description": "RFC 7807 Problem Details for HTTP APIs", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Problem type URI" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string", "format": "uri", "nullable": true } } } }, "responses": { "BadRequest": { "description": "Invalid request payload", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Missing or invalid auth token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "Rate limit exceeded — see Retry-After header", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until rate-limit reset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "externalDocs": { "description": "Agent API guide + integration examples", "url": "https://www.qazpila.com/llms.txt" } }