AI agent integration guide
Use this guide when implementing a Zayuno provider adapter with Codex, Claude Code, Cursor or another coding agent. The target is the provider's backend, not the Zayuno consumer app.
Read in this order
- Quickstart and base URL: identify the system you are building.
- Capabilities: select DISCOVERY_READONLY or TRANSACTIONAL and fulfillment mode.
- OpenAPI and generated endpoint reference: exact request, response, direction and required fields.
- Authentication, quotes, actions, webhooks.
- Certification and troubleshooting.
Machine-readable entry points
| URL | Purpose |
|---|---|
| https://partners.zayuno.uz/llms.txt | Compact discovery index |
| https://partners.zayuno.uz/llms-full.txt | All provider docs in one text document |
| https://partners.zayuno.uz/docs/{id}.md | One guide as raw Markdown |
| https://partners.zayuno.uz/docs/search-index.json | Titles, keywords and complete guide text |
| https://partners.zayuno.uz/openapi.json | Provider schemas and example payloads |
| https://partners.zayuno.uz/postman.json | Importable collection |
| https://partners.zayuno.uz/docs/ | Crawlable HTML, no JavaScript required |
These resources are generated in the same build as the portal. AI Kit can also export a framework-specific task and a provider-specific contract summary.
Contract precedence
Schema and canonical endpoint definitions in packages/contracts/src are the implementation source of truth. The generated OpenAPI and reference are derived from them. Explanatory guides describe workflow; they do not invent fields or loosen validation.
If an example, legacy provider response or AI-generated code conflicts with a schema, identify the mismatch and fix the adapter. Do not silently change the core contract. Optional values should be omitted when unavailable unless the schema explicitly permits null.
Implementation checklist
- Read the existing provider backend and its order model before editing.
- Record the task, files to change, tests and next steps in a local checklist.
- Map real catalog IDs, prices, variants, modifiers and availability.
- Implement only declared capabilities plus mandatory fulfillment requirements.
- Use server environment variables for keys. The provider creates PROVIDER_API_KEY; Zayuno supplies ZAYUNO_WEBHOOK_SECRET. Never paste their values in a prompt.
- Keep provider endpoints and Zayuno Core endpoints distinct. Status webhooks go from provider to Zayuno.
- Recompute quote totals server-side. Reject expired quotes and preserve explicit user confirmation before action creation.
- Persist idempotency across restarts. Retry with the same key returns the existing action.
- For HMAC, sign the exact raw body. The current protocol does not prepend a timestamp to the signature input.
- Return a provider-owned checkout URL when required; do not invent payment success.
- Run local schema and negative tests, then provider certification in an isolated test environment.
- Report completed vs unverified work, commands and remaining steps. Do not claim production readiness from the demo sandbox.
Minimum verification matrix
| Scenario | Evidence |
|---|---|
| Wrong API key | Rejected request |
| Malformed catalog | Schema identifies invalid field |
| Quantity or option changes | Server-calculated quote matches selection |
| Expired quote | No action created from stale terms |
| Duplicate action create | Same action ID, no double fulfillment |
| Invalid webhook signature | Rejected event |
| Provider timeout | Explicit error, no fake success |
| Payment pending | nextAction and status reflect provider truth |
Handoff template
Goal:
Provider type / fulfillment mode:
Capability profile:
Backend framework:
Contract version:
Completed:
Changed files:
Tests and exact results:
Not verified:
Next action:
Ready-to-use Agent Prompts
Prompt for Claude Code / Cursor / Codex
You are building the Zayuno Provider Adapter for our backend.
Canonical documentation:
- Full contract: https://partners.zayuno.uz/llms-full.txt
- OpenAPI Schema: https://partners.zayuno.uz/openapi.json
- Base URL & Quickstart: https://partners.zayuno.uz/docs/base-url.md
- Strict Certification v2: https://partners.zayuno.uz/docs/certification.md
Your Task:
Expose provider endpoints under our backend prefix (e.g. /zayuno):
1. GET /health: Health check, verifies x-provider-api-key header.
2. GET /provider-info: Returns metadata and manifest:
- Must include `manifest.certification.safeTestEnvironment: true`.
- Declare customerRequirements (e.g. `{ phone: "REQUIRED" }` or `{ email: "REQUIRED" }` or `{}`).
- Declare inputMode (`OFFERING` for catalog items, or `PARAMETERS` for parameter-only services).
- Provide `certificationInput` with valid test data.
3. GET /catalog: Returns active offerings with categories, variants, and modifiers.
4. POST /quote: Calculates authoritative total, fees, and discounts from our database (minimum 5s TTL).
5. POST /actions:
- Validates required fields first; returns HTTP 400/422 VALIDATION_ERROR on missing fields (never QUOTE_EXPIRED).
- Requires `userConfirmed: true` (rejects unconfirmed with ACTION_NOT_CONFIRMED).
- Deduplicates with `idempotencyKey`; returns identical action on retry, or HTTP 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD if payload changed.
6. GET /actions/:id: Returns canonical order status.
7. Webhook Dispatch: For every created test order, automatically dispatches signed POST to `https://api.zayuno.uz/api/v1/webhooks/{providerSlug}` with header `x-zayuno-signature` (HMAC-SHA256 over raw JSON) and event `action.status_updated`.
Strict Rules:
- Never guess prices or stock; calculate strictly from database records.
- Protect secrets: read PROVIDER_API_KEY and ZAYUNO_WEBHOOK_SECRET from environment variables.
- Verify each endpoint with cURL before declaring the task done.
Use AI Kit → framework → goal for a concrete task with canonical payloads and, when available, redacted certification errors. This page remains accessible without signing in.