Pole a co se bez nich rozbije
Není tu pole, které by bylo jen „hezké mít". Povinné znamená, že bez něj nefunguje nic; doporučené znamená, že se něco konkrétního zhorší — a poslední sloupec říká přesně co.
povinné
Bez něj je endpoint nepoužitelný a odpověď odmítneme.
doporučené
Všechno běží dál a něco měřitelného se zhorší. Tohle je ta tichá škoda.
volitelné
Pošlete, když ho máte. Dnes na něm nic nestojí.
Snapshot aktivních nabídek OffersSnapshot
JSON Schema · reference endpointů
| Pole | Typ | Úroveň | K čemu je | Když chybí |
|---|---|---|---|---|
| items[].external_id | string | povinné | Stabilní ID nabídky. Nikdy se nepoužije pro jinou nabídku. | Odpověď odmítneme. |
| items[].name | string | doporučené | Název nabídky, ať výpis vznikne bez volání detailu. | Jeden request na detail navíc u každé nabídky jen kvůli názvu. |
| items[].company.name | string | doporučené | Název firmy ze stejného důvodu. | Totéž co výše. |
Detail nabídky Offer
JSON Schema · reference endpointů
| Pole | Typ | Úroveň | K čemu je | Když chybí |
|---|---|---|---|---|
| external_id | string | povinné | Totéž ID jako ve snapshotu. | Odpověď odmítneme. |
| version | string | povinné | Neprůhledný otisk obsahu. Mění se, kdykoliv se změní obsah nabídky. | Odpověď odmítneme. |
| name | string | povinné | Název nabídky. Stane se z něj titulek kreativy. | Odpověď odmítneme. |
| description | string | povinné | Prostý text nebo HTML. Všechno, z čeho se píše text reklamy — čím bohatší, tím lepší reklama. | Odpověď odmítneme. |
| status | string published · pending · closed |
povinné | Kampaň běží jen u `published`; `closed` ji během minut zastaví. | Odpověď odmítneme. |
| updated_at | string (ISO 8601) | povinné | Kdy se nabídka naposled změnila. | Odpověď odmítneme. |
| company.name | string | povinné | Jméno inzerenta. Objeví se v kreativě a uvozuje text reklamy. | Odpověď odmítneme. |
| company.logo_url | string (URL) | doporučené | Veřejně dostupný HTTPS obrázek. Čtvercový nebo široký, aspoň 200 px. | Kreativa se vyrenderuje bez loga — funguje, jen vypadá obecně. |
| company.introduction | string | volitelné | Krátké představení firmy; dá textu reklamy něco navíc k samotné nabídce. | — |
| company.logo_approved | boolean | volitelné | Nastavte false, když logo není ověřené; pak ho do renderované kreativy nedáme. | — |
| area_id | string | doporučené | Vaše ID oboru nabídky. Jakýkoliv stabilní identifikátor z vaší vlastní taxonomie. | Každá kampaň startuje hned, místo aby dala nabídce pár dní obsadit se organicky, a publikum nemá zájmové cílení — je tedy širší a dražší. |
| area_root_id | string | doporučené | Kořen vašeho stromu oborů pro tutéž nabídku. | Reklamy jedou z výchozí stránky místo té, která oboru odpovídá. |
| locations[].city | string | doporučené | Město tak, jak ho píšete v inzerátu. Mapování na identifikátory reklamních systémů si děláme sami. Pole posílejte i prázdné — tím říkáte „remote", ne „ještě to neumíme". | Cílí se na celou zemi místo rádiusu 80 km kolem měst — platíme imprese lidem, kteří tam nikdy nedojedou. |
| language_code | string (ISO 639-1) | volitelné | Jazyk obsahu. Bez něj jazyk detekujeme z textu. | — |
| salaries[].minimum | integer | doporučené | Spodní hranice nabízené částky, v celých jednotkách měny. | Kreativa nemůže ukázat částku. Reklamy s uvedeným číslem měřitelně vydělávají víc. |
| salaries[].maximum | integer | volitelné | Horní hranice, když zveřejňujete rozpětí. | — |
| salaries[].currency | string (ISO 4217) | doporučené | Měna částky, např. `CZK`. | Částku z kreativy raději vypustíme, než abychom ji ukázali bez měny. |
| salaries[].measure | string hour · day · month · year · once |
doporučené | Období, ke kterému se částka vztahuje. | Předpokládáme měsíční částku, což u hodinové odměny vypadá jako nesmysl. |
Změnový výpis OfferChanges
JSON Schema · reference endpointů
| Pole | Typ | Úroveň | K čemu je | Když chybí |
|---|---|---|---|---|
| items[].external_id | string | povinné | Která nabídka se změnila. | Odpověď odmítneme. |
| items[].version | string | povinné | Její aktuální otisk obsahu. | Odpověď odmítneme. |
| items[].status | string published · pending · closed |
doporučené | Ušetří volání detailu, když potřebujeme jen stav. | Jeden request na detail u každé změněné nabídky jen kvůli tomu, jestli je pořád otevřená. |
| items[].updated_at | string (ISO 8601) | doporučené | Kdy se změnila. | Watermark se dá posunout jen na čas průchodu, takže pomalý průchod čte znovu nabídky, které už viděl. |
| next_page | scalar | null | povinné | Vracíme ho beze změny jako `page`. `null` ukončuje průchod. | Odpověď odmítneme. |
Kandidáti na kampaň CampaignCandidates
JSON Schema · reference endpointů
| Pole | Typ | Úroveň | K čemu je | Když chybí |
|---|---|---|---|---|
| items[].source_type | string visibility · ppc |
povinné | Jaký druh produktu kandidáta vytvořil. | Odpověď odmítneme. |
| items[].external_key | string | povinné | ID toho nákupu u vás. Pro nás neprůhledné; číslo je v pořádku. | Odpověď odmítneme. |
| items[].offer_external_id | string | povinné | Nabídka, ke které kampaň patří. | Odpověď odmítneme. |
| items[].product | string | povinné | Klíč produktu dohodnutý s námi — vybírá rozpočet, cíl kampaně i reklamní účet. | Odpověď odmítneme. |
| items[].window.since | string (ISO 8601) | povinné | Před tímhle okamžikem kampaň běžet nesmí. | Odpověď odmítneme. |
| items[].window.until | string (ISO 8601) | null | doporučené | Konec okna. U `ppc` smí být null, dopočítáme si ho z konfigurace produktu. | Kampaň běží výchozí dobu produktu místo okna, které jste prodali. |
| items[].status | string active · cancelled |
povinné | `cancelled` u téže dvojice kampaň zastaví. Zrušení nikdy nevyjadřuj vynecháním. | Odpověď odmítneme. |
| items[].updated_at | string (ISO 8601) | povinné | Podle něj funguje stránkování přes `updated_since`. | Odpověď odmítneme. |
| items[].budget_override | integer | null | volitelné | Rozpočet v haléřích. Přebije výchozí hodnotu produktu. | — |
| items[].delay_override_days | integer | null | volitelné | Přebije, jak dlouho čekáme před startem. | — |
| items[].first_campaign_boost | boolean | volitelné | Nový klient — start hned, bez čekání. Výchozí false. | — |
| next_page | scalar | null | povinné | Vracíme ho beze změny jako `page`. `null` ukončuje průchod. | Odpověď odmítneme. |
Počty reakcí ApplicationsStats
JSON Schema · reference endpointů
| Pole | Typ | Úroveň | K čemu je | Když chybí |
|---|---|---|---|---|
| external_id | string | povinné | Zopakované ID nabídky. | Odpověď odmítneme. |
| from | string (ISO 8601) | volitelné | Zopakovaná dolní hranice z dotazu. Hodí se při ladění, nic na ní nestojí. | — |
| count | integer | povinné | Kvalitní reakce od `from`. Musí to být celé číslo — číslo jako řetězec ignorujeme. | Odpověď odmítneme. |
| total_count | integer | doporučené | Všechny přihlášky od `from`. Musí být větší nebo rovno `count`, jinak ho bereme jako neznámé. | Grafy ukážou jen kvalitní reakce, bez informace, z kolika přihlášek vznikly. |
Chyba Error
JSON Schema · reference endpointů
| Pole | Typ | Úroveň | K čemu je | Když chybí |
|---|---|---|---|---|
| error.code | string | povinné | Krátký strojově čitelný kód. | Odpověď odmítneme. |
| error.message | string | povinné | Vysvětlení pro člověka. Skončí v našem provozním UI, takže ho piš pro člověka. | Odpověď odmítneme. |
Neznámá pole ignorujeme.
Posílejte klidně cokoliv dalšího, co váš systém má — klíče navíc parser nerozbijí. Zároveň to znamená, že můžeme do kontraktu přidávat pole, aniž bychom rozbili vaši implementaci.