/yandex-direct

name: yandex-direct
description: "[RU: интеграция Яндекс.Директ API v5 — кампании, ставки, отчёты, автостратегии, песочница] Yandex.Direct API v5 — JSON over HTTPS, OAuth Bearer + Client-Login for agencies, Campaigns/AdGroups/Ads/Keywords/Bids/KeywordBids/BidModifiers/Reports services, units-based daily quota, sandbox at api-sandbox.direct.yandex.com, TSV reports with processingMode online/offline/auto and 201/202 polling via Retry-After. Use when: yandex direct, яндекс директ, direct api v5, JSON-RPC, CampaignsService, AdsService, BidsService, Reports TSV, units, sandbox, песочница, Client-Login, agency, агентский кабинет, auto bidding, автостратегии, WB_MAXIMUM_CLICKS, PAY_FOR_CONVERSION, поисковые/РСЯ, micro-currency. SKIP: web analytics (→yandex-metrica); SERP scraping (→xmlstock); Wordstat (→mutagen); Google Ads (→google-ads); myTarget/VK Ads (→vk-ads)."
stacks:
  - yandex-direct
  - ru-ads
  - python
  - nodejs
tags:
  - ads
  - ppc
  - ru
  - yandex
  - direct
  - json-rpc
  - oauth
source: vechkasov-global-skills
risk: high-stakes

<!-- versions:start -->

Version Requirements

**Primary pins:**

• Yandex Direct API: `v5 (stable, JSON over HTTPS; api.direct.yandex.com/json/v5/{service})`
• Sandbox: `api-sandbox.direct.yandex.com/json/v5/{service}`
• Python: `3.14.x`
• Node.js: `24.x (Active LTS)`

> Verify against current Yandex Direct release notes before production use.

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. Read the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Programmatic campaign management in Yandex.Direct: create, update, suspend, archive via `CampaignsService`
• Bulk bid updates and strategy switching via `BidsService` / `KeywordBidsService`
• Loading keywords with negatives and operators via `KeywordsService`; tracking `Status` / `State` transitions (DRAFT/MODERATION/ACCEPTED/REJECTED)
• Creating and moderating ads (`AdsService`): TextAd, DynamicTextAd, MobileAppAd, ImageAd, CpcVideoAd, SmartAdBuilderAd
• Pulling statistics through the **Reports API** (TSV) with `processingMode` (online/offline/auto), 201/202 polling honoring `Retry-After`
• Working from an agency account: passing `Client-Login` per client, spending agency units via `Use-Operator-Units: true`
• Testing integration in the **sandbox** at `api-sandbox.direct.yandex.com` without burning real budgets
• Building your own client / connector (Python httpx, Node.js fetch) with units accounting, retry on 5xx/transient codes, manual idempotency
• Integrating into CRM/dashboard: pull account structure, adjust CPC from conversion signals, sync negative keywords

Do not use this skill when

• Web traffic analytics and goals from the site → `yandex-metrica` (cascade marker)
• SERP scraping, position tracking, snippet parsing → `xmlstock` (cascade marker)
• Wordstat frequency and keyword competition → `mutagen` (cascade marker)
• Google Ads / Google Ads API (different platform, different auction model) → `google-ads` cascade
• myTarget / VK Ads / VKontakte advertising → `vk-ads` / `mytarget` cascade
• Static on-site ad blocks, direct sales without auction
• Plain stats viewing through UI — Direct API is only needed for automation and scale

Purpose

Yandex.Direct API v5 is the official programmatic interface to Yandex's paid search and display platform. It manages campaigns (Search / Network / Master of Campaigns / Unified Performance / Dynamic / Smart banners / Mobile app / CPC Video / CPM Banner), ad groups, ads of all types, keywords and targetings, bids (manual and auto-strategies), reports (TSV), dictionaries, budget forecasts, and XML import/export.

This skill is **high-stakes** because:

1. **Every write call spends real budget.** `AdsService.add` and `BidsService.set` start serving and consume client money. A misplaced zero in `MaxCpc` = hundreds of thousands of rubles burned in an hour. Every write requires a sandbox dry-run plus explicit confirmation of magnitudes. 2. **Units economy.** Each method costs units from a per-account daily limit. Overrun → `error 153` (UnitsLimitExceeded) and the batch ends up in an inconsistent state. Estimate cost before each batch; parse `Units: consumed/remaining/daily-limit` from every response. 3. **`Client-Login` is mandatory for agencies.** Forget it and the call runs against the agency's own account instead of the client's → auth error or, worse, silent change to the wrong account. Enforce in middleware and assert on `Units-Used-Login` in responses. 4. **Partial errors in batch operations.** `AddResults` / `UpdateResults` may contain a mix of `Id` and `Errors` per item. A 200 OK does not mean the batch fully succeeded — iterate per element. 5. **Reports API has its own lifecycle.** `processingMode=offline` returns HTTP 201 (queued) or 202 (forming); polling must respect `Retry-After`. Ignoring it → 429 / IP or account throttling. Maximum 5 parallel reports. 6. **Sandbox ≠ production data.** Sandbox campaigns are not shown to real users; stats are synthetic. Sandbox is still the right place to validate request structure and error handling without spending money. 7. **No built-in idempotency.** Repeating `add` with the same body creates a duplicate. Maintain client-side dedup by business key (name + parent id) or a unique external index on returned `Id`. 8. **Token revocation.** OAuth tokens can be revoked by the user — every request then fails with `error_code 1002` / `506`. Refresh logic and an "auth degraded" sentinel are required. 9. **10 000 IDs per selection.** `SelectionCriteria.Ids` accepts up to 10 000; more → `error 17`. Chunk client-side. 10. **`suspend` ≠ `archive`.** Suspend pauses (reversible); archive is terminal and locks editing. Confusing them = losing the ability to mutate the object.

This skill owns Direct-domain knowledge: endpoints, headers, units economy, Reports lifecycle, agency access modeling, error se