Provider Operations Dashboard and Moderation
This document is part of the public Zayuno provider contract. Any externally visible change to provider onboarding, action visibility, payment reporting, moderation, or lifecycle rules must update this document and the changelog in the same change set.
Customer contacts and business hours
In the provider workspace, open Biznesim → Aloqa va ish vaqti. This section is available before and after publication. iiko connection cards also link here. Changes do not reset certification or approval.
Owners and assigned developers (or platform admins) can read and replace these settings with their dashboard JWT:
GET /api/v1/providers/:slug/operations
PUT /api/v1/providers/:slug/operations
Authorization: Bearer <provider-dashboard-jwt>
PUT requires all three fields; credentials, publication and moderation fields are rejected:
{
"supportContact": {
"phone": "+998900000001",
"telegram": "@restaurant_support",
"website": "https://example.uz",
"supportNote": "Buyurtma raqamini ayting, yordam beramiz."
},
"workingHours": {
"timezone": "Asia/Tashkent",
"schedule": [
{ "day": "MONDAY", "open": "09:00", "close": "23:00" },
{ "day": "TUESDAY", "open": "09:00", "close": "23:00" }
]
},
"acceptingOrders": true
}
The number and contacts above are illustrative. Public contacts may also include
email and supportUrl (HTTPS). Empty supportContact: {} clears contacts.
The old supportContact.workingHours string is retained for compatibility;
only the top-level structured workingHours controls order acceptance.
schedule contains up to 28 intervals. Days use uppercase English weekday
names. Missing days are closed. Multiple non-overlapping intervals are supported.
Opening is inclusive; closing is exclusive. 18:00–02:00 closes the following
day. 00:00–24:00 means a full day. Equal times and overlaps are rejected.
IANA timezones are validated; DST gaps and repeated times are handled by the
server. workingHours: null removes schedule restrictions; a configured empty
schedule closes the business all week.
GET/PUT settings and public provider discovery return workingHours, structured
supportContact, operationalStatus and nextOpenAt. get_provider,
find_providers and list_providers expose the same public fields in MCP.
There are no credentials or internal moderation fields in this public projection.
| Operational status | Discovery | New quote/create |
|---|---|---|
OPEN | Visible if published and eligible | Allowed by existing capability rules |
CLOSED | Remains visible | HTTP 409 PROVIDER_CLOSED |
TEMPORARILY_UNAVAILABLE | Manual pause remains visible | HTTP 409 PROVIDER_TEMPORARILY_UNAVAILABLE |
UNKNOWN | Remains visible | Existing rules apply; hours have not been configured |
acceptingOrders: false takes precedence over hours. Existing health/publication
and compliance safeguards remain in force. Operational status is distinct from
provider lifecycle status (ACTIVE, DRAFT, etc.).
nextOpenAt is null while open, paused, unconfigured or closed all week. Otherwise
it is an ISO timestamp with the provider timezone offset, for example
2026-10-06T09:00:00+05:00. Agents should use this server decision, not calculate
hours themselves. Closed/pause error envelopes carry the same status and next
opening time, and are not retryable immediately. Idempotent replay of an existing
action, tracking, cancellation and payment for existing actions remain usable.
The mobile provider card shows status and a disclosure for support links and the weekly schedule. Providers can still be selected while closed to view their details; the backend remains responsible for execution safeguards.
Provider-scoped action dashboard
Authenticated provider owners, developers, and analysts can use:
GET /api/v1/providers/me/dashboard
Authorization: Bearer <provider-dashboard-jwt>
Supported filters:
| Parameter | Meaning |
|---|---|
query | Action ID, external action ID, customer name, or phone |
status | Normalized action status |
paymentStatus | PENDING, AUTHORIZED, PAID, FAILED, or REFUNDED |
from, to | ISO date or timestamp range |
minTotal, maxTotal | Non-negative action total range |
sort | newest, oldest, total_asc, or total_desc |
limit, offset | Pagination; limit is capped at 100 |
The response includes global provider metrics, filtered action summaries, and pagination. The API always derives the provider ID from the authenticated account. A provider ID supplied by the browser is never trusted.
{
"metrics": {
"totalActions": 32,
"pendingActions": 4,
"paidActions": 19,
"completedActions": 17,
"failedActions": 2
},
"actions": [
{
"publicId": "ZY-EXAMPLE-10001",
"status": "IN_PROGRESS",
"paymentStatus": "PAID",
"paymentStatusSource": "PROVIDER_REPORTED",
"total": 155000,
"currency": "UZS",
"customerName": "Example Customer",
"customerPhoneMasked": "+99890***567"
}
],
"pagination": { "total": 1, "limit": 50, "offset": 0, "hasMore": false }
}
PAID means the provider integration reported that payment state. It does not
prove bank settlement unless the provider's payment integration explicitly
supplies settlement data.
Provider-scoped action detail
GET /api/v1/providers/me/actions/:actionId
Authorization: Bearer <provider-dashboard-jwt>
The endpoint accepts a Zayuno public ID, internal action ID, or provider external action ID. It returns the item lines, normalized action and payment status, provider-reported payment source, customer fulfillment details, cancellation/failure explanation, and chronological timeline. It returns 404 for actions belonging to another provider.
Cancellation and failure reasons
Provider adapters should send a concise, user-safe explanation for terminal events. Prefer a stable machine-readable reason code in the event payload and a clear human description. Suggested codes include:
CUSTOMER_CANCELLEDPROVIDER_REJECTEDITEM_UNAVAILABLEPAYMENT_TIMEOUTPAYMENT_FAILEDDUPLICATE_ACTIONINVALID_CUSTOMER_INFORMATIONPROVIDER_TIMEOUTSYSTEM_ERROROTHER
Do not place secrets, card data, passwords, OTP values, or unnecessary identity documents in a reason or timeline description.
Moderation lifecycle
DRAFT -> PENDING_APPROVAL -> APPROVED -> ACTIVE
|-> CHANGES_REQUESTED -> DRAFT -> PENDING_APPROVAL
|-> REJECTED
ACTIVE --------------------------------------> SUSPENDED
Every non-approval decision requires:
reasonCode: stable category;reason: partner-visible explanation (minimum 12 characters);requiredChanges: actionable checklist when applicable;internalNote: optional operations-only note.
Partner-visible reasons are returned in provider metadata. Review history and internal notes are kept only for operations and must never be exposed by public discovery endpoints. Resubmitting an integration clears the current visible reason while preserving the audit history.
CHANGES_REQUESTED applications may update their integration and resubmit.
REJECTED or SUSPENDED applications cannot reset themselves to DRAFT by
editing the base URL; Operations must explicitly reopen them.
POST /api/v1/admin/providers/:slug/reopen
Authorization: Bearer <admin-jwt>
Operations provider filters
The admin endpoint supports filtering by query, provider status, review status, provider type, capability, category, geography, certification state, owner email, and registration date range:
GET /api/v1/admin/providers?reviewStatus=PENDING_APPROVAL&certified=true
Authorization: Bearer <admin-jwt>
The response is { data, total, pagination }.
Documentation rule
The following changes require documentation and changelog updates in the same pull request or release bundle:
- public API request or response changes;
- MCP tool or capability changes;
- provider onboarding and certification changes;
- action, payment, cancellation, or moderation lifecycle changes;
- dashboard workflows that providers depend on.
Run pnpm test:docs-contract before release. Internal refactors that do not
change observable behavior do not require a public contract update.