Public resources: Markdown guide · navigation manifest · LLM index

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

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

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

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

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

The canonical executable form is:

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

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

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.

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

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

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

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

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

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

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

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

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

Where present, inspect and report these technical fields:

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

Missing, null, omitted, unavailable, versus 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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/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

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

Examples

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

One read

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

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

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

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

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

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.