# Ozon Bridge AI Guide

Guide version: `2026.09.09-2`

Last updated: `2026-09-09T05:03:04Z`

Bridge-contract compatibility: `v0.1.19`; command families `OZON_API_V1`, `OZON_BATCH_RESULT_V1`, `OZON_HELP_V2`, and `OZON_GUIDANCE_RESULT_V2`.

Authority note: this is a stable public protocol guide. Live `OZON_GUIDANCE_RESULT_V2` remains authoritative for currently available capability clusters, sections, operations, and refinements. If this page and live guidance disagree, live guidance wins.

## Quick protocol {#quick-protocol}

1. Preserve the user's business question and define the time period, scope, units, and desired evidence.
2. Decide whether the answer needs private Ozon evidence, external public context, or both.
3. If the exact operation is uncertain, identify the semantic cluster; do not guess an alias.
4. Ask for current runtime instructions with a separate `OZON_HELP_V2` message.
5. If guidance returns a refinement, use the separate `OZON_GUIDANCE_RESULT_V2` step it specifies.
6. Emit a separate, explicit `OZON_API_V1` command only after the operation and parameters are known.
7. Keep the command envelope exact: one allowed operation alias and one `params` object.
8. Before each request, say what is being checked, why, and what evidence is expected.
9. Execute independent commands sequentially and count logical versus physical requests.
10. For dependent work, pass only opaque identifiers returned by the previous result.
11. Continue pagination one explicit page or cursor at a time; never invent a token.
12. After each result, state what it proves, what it does not prove, what is missing, and whether another read is needed.
13. Keep facts, calculations, hypotheses, and causal claims separate.
14. Stop when the evidence covers the stated question, explain coverage limits, then provide the business answer.

## Find the instruction you need {#task-navigation}

Use this table as the first navigation surface. “Semantic cluster” is a discovery hint, not a frozen operation allowlist.

| User or business need | Guide section | Semantic cluster where relevant |
| --- | --- | --- |
| Sales or revenue data | [Sales analytics](#sales-analytics) | `sales_analytics` |
| Stocks | [Current stock](#stock-inventory) | `stock_inventory` |
| Warehouse or logistics information | [Fulfillment and supply](#fulfillment-supply) | `fulfillment_supply` |
| Supply status | [Fulfillment and supply](#fulfillment-supply) | `fulfillment_supply` |
| Order or posting data | [Fulfillment and supply](#fulfillment-supply) | `fulfillment_supply` |
| Prices or promotions | [Prices and promotions](#prices-promotions) | runtime guidance |
| Returns or cancellations | [Returns and cancellations](#returns-cancellations) | runtime guidance |
| Finance | [Finance](#finance) | runtime guidance |
| Reviews or questions | [Reviews and questions](#reviews-questions) | runtime guidance |
| Search visibility or SEO | [Search visibility](#search-visibility) | `search_visibility` |
| Advertising campaigns | [Performance advertising](#performance-advertising) | `advertising_performance` |
| Advertising SKU statistics | [Performance advertising](#performance-advertising) | `advertising_performance` |
| Bids or competitive bids | [Performance advertising](#performance-advertising) | `advertising_performance` |
| A report or file | [Reports and files](#reports-files) | runtime guidance |
| HTTP 429 | [Errors and recovery](#errors-recovery) | — |
| 4xx or 5xx | [Errors and recovery](#errors-recovery) | — |
| A privacy block | [Privacy and personal data](#privacy) | — |
| A cursor or page token | [Pagination](#pagination) | — |
| A report code | [Reports and files](#reports-files) | — |
| A file reference | [Reports and files](#reports-files) | — |
| Multiple independent reads | [Independent commands and batch](#batch) | — |
| Multiple dependent reads | [Dependent chains](#dependent-chains) | — |
| Unsure which operation exists | [Command discovery](#guidance) | ask live guidance |
| External or current context | [External and public context](#external-context) | — |
| Zero versus unavailable | [Missing, null, and zero](#missing-null-zero) | — |
| Units | [Units and monetary semantics](#units) | — |
| When evidence collection is complete | [Completion rules](#completion) | — |

## What Ozon Bridge is {#what-ozon-bridge-is}

Ozon Bridge is a read-only instruction and data path for an AI working with an Ozon Seller account. The normal flow is:

`user -> preferred AI -> Ozon Bridge -> Ozon Seller / Performance data -> AI analysis -> business answer`

The user does not need Ozon API knowledge. The AI translates the business question into an evidence plan, uses the Bridge contract, and explains the result in business terms. The Bridge does not decide the user's intent, invent operations, or grant permissions.

This architecture is deliberately hybrid. The public guide supplies stable protocol, reasoning, recovery, privacy, and interpretation rules. Runtime `OZON_HELP_V2` and `OZON_GUIDANCE_RESULT_V2` supply the current capability surface. The guide is not a duplicate authoritative operation registry.

## 30-second protocol {#protocol}

For a normal read: restate the question; define dates and scope; choose or discover a cluster; obtain live guidance if needed; issue one explicit read; inspect the complete result envelope; continue only with evidence-backed pagination or dependencies; distinguish coverage from completeness; answer with facts and limits.

Do not use a command to “see what happens.” Every request must have a stated business purpose and an expected evidence role.

## Command envelope {#command-envelope}

The canonical executable form is:

```text
OZON_API_V1
{"operation":"allowed_alias","params":{}}
```

`OZON_API_V1` is the command boundary. The JSON object must have the allowed top-level fields for the current contract: `operation` and `params`; `params` is the operation's parameter object. Use the exact alias and parameter shape returned by live guidance or current contract evidence.

The AI must not put transport or authentication controls in the command. Do not send `url`, `host`, `method`, `headers`, `Authorization`, bearer material, `Client-Id`, `Api-Key`, cookies, access tokens, or secrets. These are Bridge-owned or forbidden fields, not assistant-controlled parameters. Never put credentials in prose or examples.

An invalid envelope is a validation failure, not permission to rewrite and execute a different request. Keep command text separate from surrounding explanation when the current adapter contract requires it.

## How to discover a command {#guidance}

Use this exact reasoning flow:

`uncertain operation -> semantic cluster -> OZON_HELP_V2 -> OZON_GUIDANCE_RESULT_V2 -> optional section refinement -> separate OZON_API_V1`

Help and API execution are different protocol phases. Do not mix a help marker and an API command in one assistant response when the current contract requires separate responses. A help response does not execute a provider request. Guidance may identify an operation, required fields, constraints, or a section refinement; the AI then emits the final explicit command.

Never invent aliases from Ozon's public API documentation, a remembered integration, or a previous response. If current guidance does not expose an operation, treat it as unavailable for this Bridge session.

## Semantic cluster index {#semantic-clusters}

Clusters organize a business need for discovery; they do not freeze the current allowlist. Ask live guidance for the current operations and refinements in the selected cluster.

| Cluster | Meaning |
| --- | --- |
| `sales_analytics` | Revenue, ordered units, returns/cancellations when entitled, delivery counts, product/category breakdowns, and period comparisons. |
| `stock_inventory` | Current stock for products selected by product or offer identifiers; not historical sales or a general catalogue. |
| `fulfillment_supply` | Read-only FBO postings and supply-order information; privacy-sensitive surfaces remain governed by runtime policy. |
| `search_visibility` | Search-query and search-performance information for selected product SKUs, subject to current entitlement and limits. |
| `advertising_performance` | Performance advertising investigation: campaigns, products, statistics, placements, and bids only where current runtime guidance exposes a supported read. |
| `account_access` | Roles and access diagnostics for the configured Seller credentials. |
| Other current clusters | Use `OZON_HELP_V2`; do not infer a cluster or alias from this table. |

The public page intentionally does not publish a frozen operation registry. A current runtime may add, retire, block, or refine operations without changing this URL.

## Before every API request {#before-request}

The AI must explain three things before emitting `OZON_API_V1`:

- what it is checking;
- why that check answers part of the user's question;
- what evidence it expects to receive and what would remain unresolved.

For example: “I am checking the current bounded FBO posting page for the requested period because it tests fulfillment evidence. I expect a page and possibly a continuation cursor; it will not prove that later pages are empty unless pagination ends.”

## After every result {#after-result}

For each result, explain: what was received; what it proves; what it does not prove; what is still missing; and why another read is or is not necessary.

Inspect the result envelope before interpreting business fields. A successful HTTP status is not by itself proof of complete data, entitlement, historical coverage, unit scale, or causality.

## Independent commands and batch {#batch}

For `N` explicit independent commands, the Bridge may perform at most `N` sequential physical business requests. The logical result count may be different because the runtime can apply documented planning or projection, but the AI must not assume hidden work.

There is no hidden retry, pagination loop, fan-out, or report polling. A batch is complete only when the response is a valid `OZON_BATCH_RESULT_V1` envelope: verify its version marker, ordered entries, per-entry status/error, request execution evidence, and logical/physical counts where present. Do not treat a partial batch as an all-success answer.

Independent commands have no data dependency and can be planned together. The final response should map each result back to its original business question.

## Dependent chains {#dependent-chains}

A dependent chain uses an opaque value returned by an earlier result. Examples include `cursor`, `offset`, `last_id`, `page`, `campaignIds` discovered from a prior result, a report code, a file reference, or another provider identifier.

The sequence is explicit: read A; inspect the actual value; issue B with that exact value; inspect B; continue only if B returns the next value. Never invent a future identifier, copy a placeholder, or replace an absent identifier with an empty string. If a chain breaks, report the missing dependency rather than changing the business question.

## Pagination {#pagination}

Use one explicit continuation at a time. Preserve the original filters, date range, scope, and limit unless current guidance says otherwise. Pass the exact returned cursor/offset/page token and record which pages were collected.

Stop when the provider indicates no continuation. One page is not the whole account, and a non-empty page is not evidence that later pages are identical. Do not hide pagination requests or claim completeness before the chain ends.

## HTTP/provider errors and recovery {#errors-recovery}

Handle HTTP `429`, other `4xx`/`5xx`, `result.error`, and policy blocks as evidence about that request—not as a reason to guess a new operation.

- `429` means rate limiting or quota evidence. Surface the sanitized error, respect any explicitly returned guidance, and do not invent universal headers or automatic delays.
- `4xx` may indicate validation, entitlement, authentication, privacy, or provider policy. Preserve the original business question and explain the category.
- `5xx` or transport failure means the provider result is unavailable or incomplete for this attempt. Do not claim zero data.
- `result.error` is part of the result contract even if the HTTP response was delivered.
- A privacy or entitlement block must not be bypassed by changing fields, endpoint guesses, or credentials.

There is no hidden retry. If another request is appropriate, explain why and issue it explicitly under the normal request budget. Never change the business question merely to obtain HTTP 200.

## Privacy and personal data {#privacy}

Ozon Bridge is read-only and privacy-gated. Personal or customer-sensitive fields may be redacted, omitted, blocked, or unavailable according to the operator-controlled privacy setting and current policy. Do not ask for a bypass, weaken a gate, or copy redacted data from another source.

Avoid requesting customer data by default. A report option such as `with.customer_data` is explicit scope and must not be enabled for a general diagnostic. Do not publish or repeat credentials, tokens, customer names, addresses, phones, emails, order-linked personal details, or private URLs.

## Read-only boundary {#read-only}

The Bridge may read evidence; it does not claim to have changed prices, promotions, bids, budgets, cards, campaigns, products, orders, returns, or supply records. A GET-shaped provider endpoint can still be mutation-like; runtime policy wins.

Words such as “updated,” “applied,” “activated,” “changed,” or “fixed” require independently verified write evidence, which is outside this read-only surface. Say “observed,” “retrieved,” or “the provider returned” for reads.

## Evidence integrity {#evidence-integrity}

Where present, inspect and report these technical fields:

| Field | Why it matters |
| --- | --- |
| `http_status` | Provider/transport status; not a completeness claim. |
| `external_request_executed` | Whether a provider request actually ran; false is not zero business data. |
| `error` | Sanitized error or policy reason. |
| `exact_request_preserved` | Whether the executed command remained the requested command. |
| `command_transformed` | Whether documented planning/transformation occurred. |
| logical/physical counts | Distinguish requested results from provider calls. |
| pagination | Continuation and coverage state. |
| `rate_limit` | Explicit quota/rate evidence only. |
| `entitlement` | Account capability/access state and partial coverage. |

If a field is absent, say it is absent; do not infer a favorable value.

## Missing, null, omitted, unavailable, versus zero {#missing-null-zero}

These states are different:

- `0` is an explicit numeric zero.
- `null` is an explicit null and needs the field's contract meaning.
- omitted is no value in the response.
- missing/unavailable may reflect scope, entitlement, redaction, provider behavior, or an incomplete request.
- an empty list is an explicit empty collection, but only for the returned scope.

Never convert unavailable, redacted, omitted, or null into `0`. Preserve the raw state, name the evidence, and ask for another read only when it can resolve the distinction.

## Partial evidence versus whole-account conclusions {#partial-evidence}

State the coverage boundary with every conclusion. Examples:

- FBO is not the entire business; FBS, rFBS, or other flows may be outside the read.
- One page is not a complete list until pagination ends.
- One campaign is not all advertising.
- One placement is not all advertising.
- Current state is not historical state.
- Advertising-attributed orders are not all orders.
- A selected SKU is not the whole catalogue.

Use “within the requested period/scope/page” unless the evidence truly covers the whole requested population.

## Dates and periods {#dates}

Translate “today,” “yesterday,” and “last N days” into explicit calendar or timestamp bounds. State the timezone used, especially around midnight and daylight-saving boundaries. Preserve the provider’s inclusive/exclusive boundary semantics when known; otherwise label the interpretation.

Do not mix a current snapshot with a historical period. A report generated now may contain data for an earlier period; name both generation time and data period when available.

## Units and monetary semantics {#units}

Never infer units merely because another field uses a known scale. Establish units using this evidence hierarchy:

1. the current Bridge/provider contract for that exact field;
2. an explicit unit or currency in the same response;
3. a current authoritative provider explanation;
4. a controlled comparison with a known value, clearly labeled as a check;
5. otherwise report the raw value and say the unit is unresolved.

Do not silently divide or multiply money, percentages, weights, quantities, or rates. Preserve currency and precision. A calculation based on unresolved units remains unresolved.

## Fact, calculation, hypothesis, and causality {#reasoning}

Label the claim type:

- **Fact:** directly returned by the Bridge/provider within a stated scope.
- **Calculation:** arithmetic derived from returned facts; show the formula and inputs.
- **Hypothesis:** a plausible explanation that needs more evidence.
- **Causality:** a supported cause-and-effect claim; do not infer it from correlation, timing, or spend alone.

Use cautious language such as “consistent with” until the evidence rules out competing explanations.

## Sales analytics {#sales-analytics}

Use `sales_analytics` for revenue, ordered units, period totals/comparisons, and product/category analytics exposed by current guidance. Universal and subscription-dependent metrics can differ. A result may be partial when a metric, dimension, sort, filter, or historical window is not entitled.

Do not promise detailed order/customer records from a sales aggregate. For “sales for a week,” define the week and timezone, request the smallest evidence surface that answers it, and distinguish revenue from units, orders, returns, and cancellations.

## Current stock {#stock-inventory}

Use `stock_inventory` for current inventory selected by the identifiers the current guidance accepts. Current stock is not historical sales, warehouse history, or a complete product-card catalogue. State whether the response is aggregate, product-filtered, warehouse-specific, or paginated. A stock zero is meaningful only when the requested item and scope were actually returned.

## Fulfillment and supply {#fulfillment-supply}

Use `fulfillment_supply` for FBO posting lists and supply-order evidence when live guidance exposes the read. Keep posting listing, fetching multiple supply orders by returned IDs, and fetching one supply-order detail as separate operations or dependent steps according to guidance.

Do not expose privacy-sensitive posting surfaces merely because an endpoint exists in historical material. Live policy and entitlement decide what is selectable. Record filters, page/cursor coverage, and flow boundaries.

## Prices and promotions {#prices-promotions}

Start with live guidance. Use the current runtime operation and current field semantics; do not copy a historical alias or assume a price field means an applied promotion. Read-only evidence can describe observed prices, promotion participation, or candidate terms, but cannot claim that a price or promotion was changed.

## Returns and cancellations {#returns-cancellations}

Discover the current read operation and distinguish returned, cancelled, pending, and conditional states. A report or aggregate may cover only a period, flow, or status subset. Do not approve, reject, or initiate a return/cancellation through this read-only Bridge.

## Finance {#finance}

Discover current finance/accrual operations at runtime. Preserve the accounting period, currency, posting type, pagination identifier, and whether amounts are accruals, settlements, fees, or other categories. Do not use an old finance operation after live guidance retires or replaces it.

## Reviews and questions {#reviews-questions}

Ask live guidance for the current read surface and privacy scope. Separate review text, question/answer state, counts, and ratings. Do not expose personal data or claim that a response was posted; the public guide does not authorize mutations.

## Search visibility {#search-visibility}

Use `search_visibility` for selected-SKU search-query or detailed search-performance evidence when current guidance exposes it and the account is entitled. Summary query views and detailed breakdowns can have different limits, sorts, historical windows, and subscription requirements. Do not turn selected-SKU evidence into a whole-catalogue SEO conclusion.

## Performance advertising {#performance-advertising}

Treat advertising as an investigation with explicit scope, not a spend-only diagnosis. Start by discovering campaigns if the current live guidance exposes campaign reads. If a campaign identifier is needed, use the actual returned `campaignId` for a separate refinement. Then investigate the available product mapping, SKU statistics, date range, placement, product campaign strategy, product bids, exact SKU minimum bids, and competitive bids as separate supported reads.

The repository’s latest provider evidence keeps exact Performance paths, host/authentication, schemas, quotas, history, and access restrictions contract-pending. Therefore this public section documents the reasoning workflow only; it does not promote candidate paths or aliases to a frozen allowlist. Live `OZON_GUIDANCE_RESULT_V2` wins.

Interpretation boundaries:

- competitive bid is evidence about competition, not automatically a mandatory minimum bid;
- an exact SKU minimum bid must be tied to the exact returned SKU and current field contract;
- placement scope must not be generalized to all placements;
- product-campaign strategy is not proof of actual delivery or causality;
- local sorting, filtering, or aggregation is analysis, not an API operation;
- spend alone does not diagnose poor advertising—check exposure, clicks, conversions, attribution, period, placement, bids, products, and entitlement where available;
- do not create, activate, deactivate, change budget, change bids, or add/remove products through this read-only Bridge.

## Reports and files {#reports-files}

Generated reports are dependent chains, not one magical operation:

`create report -> receive actual report code -> status/info -> receive actual file reference -> retrieve file`

Use the exact report code returned by create. Use the exact file reference returned by status/info. Create, status/info, and retrieval are separate explicit reads; there is no hidden polling, hardcoded report code, hardcoded file reference, or indefinite wait. Keep report period, requested fields, privacy options, and file status visible in the final evidence.

## External and public context {#external-context}

External/public context may be used for current market, policy, competitor, or public product information when it materially helps answer the business question and the AI can identify its source and date. Keep it separate from private Ozon evidence. Public context cannot fill a missing private field, prove an account-specific fact, or override a Bridge result.

## When data collection is complete {#completion}

Collection is complete when the stated question is answered by sufficient evidence for its scope, all required pages/dependencies have ended, known errors and partial coverage are disclosed, and unresolved fields are explicitly named. Then give the business answer in plain language, followed by the terminal marker only if the current product contract requires one. A terminal marker is not a substitute for the answer.

## Common failure patterns {#common-mistakes}

| Wrong | Right |
| --- | --- |
| Guess an operation alias. | Use the semantic cluster and live help/guidance. |
| Put `method`, URL, headers, or auth in `OZON_API_V1`. | Send only the contract envelope; Bridge owns transport/auth. |
| Mix help and API execution in one response. | Complete help/guidance, then emit a separate API command. |
| Retry or paginate invisibly. | Explain and issue one explicit continuation at a time. |
| Treat HTTP 200 as complete truth. | Inspect result evidence, entitlement, errors, and coverage. |
| Convert null/unavailable to zero. | Preserve the original state and explain it. |
| Call one page the whole account. | Report the exact page/filter/flow scope. |
| Diagnose advertising from spend alone. | Investigate campaign, product, SKU, placement, bids, and outcomes. |
| Claim a price/bid/campaign was changed. | Keep the read-only boundary and say what was observed. |
| Hardcode report codes, file refs, or future cursors. | Use only identifiers returned by the preceding result. |

## Examples {#examples}

The aliases below are examples of the established read contract; current availability and parameters still come from live guidance.

### One read

```text
OZON_API_V1
{"operation":"analytics_data","params":{"date_from":"2026-09-01","date_to":"2026-09-07","dimension":"day","metrics":["revenue"]}}
```

### Two independent reads in one batch

```text
OZON_API_V1
{"operation":"analytics_data","params":{"date_from":"2026-09-01","date_to":"2026-09-07","dimension":"day","metrics":["revenue"]}}

OZON_API_V1
{"operation":"stocks_current","params":{"filter":{"offer_id":["OFFER-EXAMPLE"]}}}
```

This requests two independent reads; the result must identify both ordered entries. It does not authorize hidden retries or hidden pagination.

### Dependent pagination

```text
OZON_API_V1
{"operation":"posting_fbo_list","params":{"filter":{"since":"2026-09-01T00:00:00Z","to":"2026-09-02T00:00:00Z"},"limit":1}}
```

If the result returns `has_next=true` and an opaque `cursor`, the next command copies that returned cursor exactly, with the original filter and limit. The placeholder is never invented.

### Discovery before execution

```text
OZON_HELP_V2
{"cluster":"sales_analytics"}
```

Read the resulting `OZON_GUIDANCE_RESULT_V2`, select an operation shape, then send a separate `OZON_API_V1` command. A help request does not execute Ozon.

## Version, authority, and change log {#version-authority}

Guide version `2026.09.09-2` is the public content version. The guide is generated from this Markdown source and metadata; update the source and rebuild rather than editing generated copies.

Authority order:

1. current runtime `OZON_GUIDANCE_RESULT_V2` for available clusters, sections, operations, and refinements;
2. the current `OZON_API_V1` / result-envelope contract implemented by the Bridge;
3. current provider evidence and explicitly labeled live-test evidence;
4. this public guide for stable cross-cutting rules and navigation;
5. historical repository notes only as provenance, never as current allowlist authority.

The current repository evidence used for this edition includes the Ozon Bridge README and append-only documentation, guided command-discovery specification, current handoff, batch contract checkpoint, read-only allowlist/corrections, error/rate-limit fragment, report fragments, Performance exact-probe evidence, and live ordinary-account pagination/evidence records. Historical or design-only material was not promoted when later/current evidence left a contract unresolved.

Change log:

- `2026.09.09-1`: initial public hybrid AI guide and direct-IP deployment surface.
- `2026.09.09-2`: canonical public URL migrated to the HTTPS hostname `docs.selleragents.ru`.
- Future changes: append a new guide version, retain the stable URL, rebuild, and update the authority note if the live contract changes.

## Hybrid architecture rationale {#hybrid-architecture}

Keep the architecture hybrid. A public guide is centrally updateable, avoids a huge startup prompt, reduces repeated context cost, offers stable deep links and human inspection, works across AI providers, and carries cross-cutting rules without extra Ozon API calls.

It also has limits: an AI may have no web access, reject raw-IP HTTP, encounter a fetch failure, use a stale cache, or outlive a static guide update. The minimal command grammar must therefore remain in the startup prompt, and live help/guidance must remain runtime authority. The guide never replaces live cluster/guidance machinery.