Dokumentace REST API

Začínáme

1. V nastavení účtu na sluzba.placla.cz si v sekci API klíče vytvořte klíč. Zobrazí se jen jednou — uložte si ho. Pro podávání nabídek a odevzdávání článků zaškrtněte „povolit i zápis".
2. Klíč posílejte v hlavičce každého požadavku:

curl -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/me

Odpověď:

{"id":1234,"login":"vaslogin","role":"bloger","scopes":["read"],
 "credit":{"available":1500,"blocked":0}}

Autentizace a oprávnění

Odpovědi, chyby, limity

Vše je JSON v UTF-8. Seznamy vrací obálku se stránkováním:

{"data": [...], "strana": 1, "na_stranu": 50, "celkem": 3614}

Parametry ?strana= (od 1) a ?na_stranu= (max 200) fungují na /v1/deals. Ostatní seznamy (např. /v1/blogs/{id}/demands) vrací vždy vše — poptávek dostupných pro jeden blog nebývá tolik, aby stránkování potřebovaly.

Každá odpověď nese hlavičky X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (unix čas obnovení okna), takže limit vidíte průběžně, ne až při chybě 429.

Bezpečné opakování požadavků: když POST spadne na timeoutu a nevíte, jestli prošel, klidně ho pošlete znovu. POST …/offers vrátí 409 nabidka_existuje (= první pokus prošel) a POST …/article vrátí 409 clanek_odevzdan; stav si vždy ověříte i přes GET /v1/deals/{id}.

Idempotency-Key: zápisovému požadavku můžete přidat hlavičku Idempotency-Key: <váš řetězec, 8-100 znaků>. Opakování se stejným klíčem operaci neprovede podruhé — vrátí se uložená odpověď prvního provedení (s hlavičkou Idempotency-Replayed: true). Klíče se uchovávají 7 dní. Důrazně doporučeno u peněžních operací inzerenta (akceptace, proplacení, storno).

Chyba má vždy stejný tvar. support_code uveďte při dotazu na podporu:

{"error": {"code": "nabidka_existuje",
  "message": "Na tuto poptávku už nabídka blogu existuje.",
  "support_code": "PC-4A5CAE"}}

Limity: 60 požadavků za minutu na klíč; vkládání nabídek navíc 15 za 5 sekund.

Stavy obchodu (state)

Obchod (deal) vzniká nabídkou blogu na poptávku a prochází stavy — nabídka a obchod sdílí jedno id. Hlavní (šťastná) cesta:

Odbočky z hlavní cesty:

• z nabidnuto: inzerent nabídku odmitnuto, nebo ji bloger sám stáhne → zruseno; nabídka s cenou vyšší než základ poptávky je nabidnuto_vyssi (jinak se chová stejně);
• z ke_schvaleni: inzerent článek reklamuje → arbitraz, kterou rozhodčí uzavře buď proplacením (proplaceno), nebo bez něj (arbitraz_neproplaceno);
• storno a proplaceno_text jsou historické stavy, jen ke čtení.

U stavů odmitnuto/zruseno nese pole reason důvod; article_url je vyplněné od stavu ke_schvaleni.

Bloger — čtení

# poptávky pro blog 123
curl -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/blogs/123/demands

# vaše proplacené obchody, po třech
curl -H "Authorization: Bearer VAS_KLIC" \
  "https://api.placla.cz/v1/deals?state=proplaceno&na_stranu=3"

Každý obchod v odpovědi obsahuje web_url — hotový odkaz na jeho detail na webu PlaCly (podle role klíče vede do blogerské, nebo inzerentské sekce). Používejte ho místo skládání adresy ručně, tvar webových adres se může změnit.

Přírůstková synchronizace: každý obchod nese changed_at (čas poslední změny) a GET /v1/deals?zmeneno_od=2026-08-28T10:00:00 vrátí jen obchody změněné od daného času — není potřeba procházet vše. Pozor: u obchodů z doby před zavedením tohoto pole (srpen 2026) je changed_at čas nasazení, ne skutečné poslední změny.

{
  "id": 12345,              // ID vašeho účtu
  "login": "mujblog",
  "role": "bloger",         // bloger | inzerent - podle účtu, ke kterému klíč patří
  "scopes": ["read", "write"],
  "credit": {
    "available": 1250,      // volný kredit v Kč
    "blocked": 450          // blokováno v běžících obchodech
  }
}

{
  "id": 8570,
  "name": "Můj blog",
  "url": "https://mujblog.cz",
  "type": "web",                     // web | social
  "approved": true,                  // schválen redakcí PlaCly
  "min_price": 300,                  // vaše minimální cena za článek (Kč)
  "monthly_visitors": 1250,          // měsíční UIP, který jste zadali
  "monthly_visitors_updated": "2026-08-01 09:12:00",  // starší než měsíc = poptávky se nevrací
  "writing_service": 1,              // 0 nenabízím / 1 nabízím / 2 automaticky
  "writing_price_per_ns": 200,       // cena napsání za normostranu (Kč)
  "da": 24,                          // Domain Authority (Moz)
  "metrics_updated": "2026-08-15 03:00:00",
  "published_count": 37              // kolik článků blog přes PlaClu publikoval
}

{
  "id": 54899,
  "name": "Článek o chytré domácnosti",
  "url": "https://cilovy-web.cz",     // web, na který povede odkaz z článku
  "vip": false,                       // true = VIP poptávka určená přímo vašemu blogu
  "type": "web",
  "keywords": "chytrá domácnost, automatizace",
  "ns": 1,                            // požadovaný rozsah v normostranách
  "publication": false,               // true = inzerent dodá hotový text, jen publikujete
  "expectation": "Praktické zkušenosti, ne reklamní text.",
  "reward": 225                       // vaše odměna při základní ceně (Kč)
}

{
  "id": 19310814,
  "state": "akceptovano",             // viz Stavy obchodu
  "blog":   {"id": 8570,  "name": "Můj blog"},
  "demand": {"id": 54898, "name": "Článek o chytré domácnosti"},
  "web_url": "https://sluzba.placla.cz/bloger/pripominka.php?deal=19310814",
  "changed_at": "2026-08-28 14:02:11",  // čas poslední změny (pro ?zmeneno_od=)
  "price": 450,                       // cena obchodu (co platí inzerent)
  "ns": 1,
  "express_hours": 0,                 // 0 = bez expresního dodání
  "article_url": null,                // URL publikovaného článku (od stavu ke_schvaleni)
  "reason": null,                     // důvod u stavů odmitnuto/zruseno
  "rating": null,                     // hodnocení článku inzerentem (1-5)
  "claim": {"open": false, "count": 0},          // reklamace: detail dá /deals/{id}/claims
  "unread_messages": 0,                          // obsah dá /deals/{id}/messages
  "writing": {                        // napsání textu redakcí PlaCly
    "ordered": false,
    "text_state": null,
    "editor_price": null,
    "approved_by_advertiser": false
  },
  "services": [],                     // zakoupené extra služby k obchodu
  "reward": 225                       // vaše odměna (jen v blogerské odpovědi)
}

// GET /v1/deals/{id} vrací totéž, ale "demand" nese PLNÉ zadání poptávky
// (keywords, keyword_urls, links_mode, description, expectation, ns,
//  publication, attachment) - i po akceptaci.

{
  "pending": [                        // publikováno, čeká na proplacení (stavy ke_schvaleni + arbitraz)
    {
      "deal_id": 19310823,
      "blog": "Můj blog",
      "demand": "Článek o chytré domácnosti",
      "article_url": "https://mujblog.cz/chytra-domacnost/",
      "in_arbitration": false,
      "reward": 225
    }
  ],
  "paid_monthly": [                   // skutečně vyplacené částky, po měsících (?rok= omezí rok)
    {"month": "2026-08", "count": 3, "amount": 750}
  ]
}

Bloger — zápis (scope write)

POST/v1/blogs/{id}/offers — podání nabídky

# základní cena poptávky
curl -X POST -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"demand_id": 54898}' https://api.placla.cz/v1/blogs/123/offers

# vyšší nabídka: reward = vaše požadovaná odměna v Kč, note = nápad na článek
curl -X POST -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"demand_id": 54898, "reward": 500, "note": "Napsal bych to jako case study."}' \
  https://api.placla.cz/v1/blogs/123/offers

{"id":19310814,"state":"nabidnuto","demand_id":54898,"blog_id":123,
 "price":450,"reward":225}

Vyšší nabídka musí přesáhnout základní odměnu poptávky (jinak 422 nizka_vyssi_nabidka). Existuje-li k poptávce z blogu jakýkoli obchod, vrací se 409 nabidka_existuje.

POST/v1/blogs/{b}/demands/{d}/decline — odmítnutí poptávky

Prázdné tělo. Hromadně: POST /v1/blogs/{b}/demands/decline odmítne všechny aktuálně dostupné poptávky blogu.

POST/v1/deals/{id}/article — odevzdání článku

curl -X POST -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"url": "https://vasblog.cz/nazev-clanku/"}' \
  https://api.placla.cz/v1/deals/19310814/article

{"id":19310814,"state":"ke_schvaleni","article_url":"https://vasblog.cz/nazev-clanku/"}

URL musí vést na doménu blogu, být veřejně dostupná a dosud nepoužitá. Má-li obchod extra služby s URL, přidejte "extra_urls": {"ID_SLUZBY": ["https://..."]}.

POST / DELETE/v1/deals/{id}/writing — napsání textu redakcí

Objednání (blokuje se vám cena za NS × rozsah) a zrušení s vratkou. Vyžaduje zapnuté napsání textu u blogu (writing_service).

POST/v1/blogs — založení blogu

curl -X POST -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"name": "Můj blog", "url": "https://mujblog.cz", "monthly_visitors": 1200,
       "description": "Popis blogu pro inzerenty, alespoň 250 znaků..."}' \
  https://api.placla.cz/v1/blogs

Popis musí mít alespoň 250 znaků; sociální profily (Facebook/Twitter) přes API zakládat nelze. Blog čeká na schválení redakcí — do té doby se mu nenabízí poptávky. Moz metriky se načtou automaticky.

PATCH/v1/blogs/{id} — úprava blogu

curl -X PATCH -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"min_price": 300, "monthly_visitors": 1250}' https://api.placla.cz/v1/blogs/123

Pole: name, description, note, min_price, monthly_visitors, writing_service (0/1/2), writing_price_per_ns. Minima cen se hlídají (422 nizka_cena). Hodnoty writing_service: 0 = napsání textu nenabízíte, 1 = nabízíte (objednává se u dealu), 2 = automaticky u každého obchodu. Cena je writing_price_per_ns za normostranu.

Extra služby blogu

Inzerent — čtení

Inzerent — zápis (scope write)

Operace s penězi. Všechny běží v databázové transakci a podporují Idempotency-Key (viz Odpovědi, chyby, limity) — při nejistotě po timeoutu požadavek bezpečně zopakujte se stejným klíčem. {id} u nabídek i obchodů je vždy ID dealu z /v1/demands/{id}/offers nebo /v1/deals.

POST/v1/offers/{id}/accept — akceptace nabídky

# prostá akceptace za cenu nabídky
curl -X POST -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -H "Idempotency-Key: moje-akceptace-19310814" \
  -d '{}' https://api.placla.cz/v1/offers/19310814/accept

# s nižší cenou, extra službami, klíčovými slovy a poznámkou
curl -X POST -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"price": 400, "services": [3], "note": "Prosím publikovat do pátku.",
       "keywords": [{"keyword": "chytrá domácnost", "url": "https://cilovy-web.cz/produkty"}]}' \
  https://api.placla.cz/v1/offers/19310814/accept

{"id":19310814,"state":"akceptovano","price":400,"credit_remaining":850}

Pravidla: nižší cenu (price) přijímají jen blogeři, kteří ji mají povolenou — viz lower_price_allowed u nabídky (jinak 422 nizsi_cena_nepovolena); musí být alespoň 75 % nabídnuté ceny (422 cena_pod_minimem); kredit musí pokrýt celou cenu včetně služeb (422 nedostatecny_kredit); u poptávky s dodáním hotového textu (publication: true) je povinné pole article_text. Akceptací se cena přesouvá z volného kreditu do blokace — bloger peníze dostane až proplacením. Bloger je notifikován mailem a webhookem deal.accepted.

{
  "id": 54899,
  "name": "Článek o chytré domácnosti",
  "url": "https://cilovy-web.cz",
  "price": 450,                       // co za článek platíte (Kč)
  "state": "aktivni",
  "vip": false,
  "type": "web",
  "keywords": "chytrá domácnost, automatizace",
  "keyword_urls": [                   // klíčová slova s cílovými URL odkazů
    {"keyword": "chytrá domácnost", "url": "https://cilovy-web.cz/produkty"}
  ],
  "links_mode": 1,
  "description": "Chceme recenzi z pohledu běžného uživatele...",
  "expectation": "Praktické zkušenosti, ne reklamní text.",
  "ns": 1,
  "publication": false,               // true = dodáváte hotový text
  "attachment": null                  // příloha zadání, je-li nahraná
}

{
  "id": 19310814,                     // ID obchodu - stejné pak ve /v1/deals
  "state": "nabidnuto",               // nabidnuto | nabidnuto_vyssi
  "price": 450,                       // cena nabídky (u vyšší nabídky víc než základ)
  "deferred": false,                  // true ve výpisu ?state=odlozene
  "blog": {
    "id": 8570,
    "name": "Můj blog",
    "url": "https://mujblog.cz",
    "description": "Blog o bydlení a technologiích.",
    "monthly_visitors": 1250,
    "da": 24,                         // Domain Authority
    "pa": 31,                         // Page Authority
    "spam": 2,                        // spam skóre (méně = lépe)
    "score": 61,                      // PlaClaRank
    "verdict": "silver"               // gold | silver | bronze | fail
  }
}

Webhooky

Co je webhook: obrácené volání. Normálně se váš program ptá API („je něco nového?"); s webhookem dáte PlaCle adresu na svém serveru a PlaCla na ni sama pošle zprávu, jakmile se něco stane. Nemusíte nic hlídat — hotový přijímač ke zkopírování najdete v návodech.

PlaCla volá vaši HTTPS adresu při každé z těchto událostí (typ vždy poznáte z pole event v těle, neznámé názvy ignorujte — budoucí události přibudou pod novými):

Registrace: klíč se scope write — bloger i inzerent (události chodí podle role klíče, viz tabulka). URL musí být HTTPS, jinak registrace skončí chybou. Webhook je vázaný na API klíč — zneplatněním klíče zaniká a s novým klíčem je potřeba ho zaregistrovat znovu. Vlastní akce se vám neoznamují (vaše zpráva nevyvolá message.created).

# nastavení (secret se vrátí JEN teď - uložte si ho)
curl -X PUT -H "Authorization: Bearer VAS_KLIC" -H "Content-Type: application/json" \
  -d '{"url": "https://vasserver.cz/placla-webhook.php"}' https://api.placla.cz/v1/webhook

# stav / vypnutí
curl -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/webhook
curl -X DELETE -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/webhook

# rotace secretu (URL zůstává; vrátí nový secret - opět jen jednou)
curl -X POST -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/webhook/rotate-secret

# testovací doručení - pošle webhook.test HNED a vrátí, jak váš server odpověděl
curl -X POST -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/webhook/test

# log posledních 50 doručení (stav, počet pokusů, HTTP odpověď, další pokus)
curl -H "Authorization: Bearer VAS_KLIC" https://api.placla.cz/v1/webhook/deliveries

Když se objeví nová poptávka vhodná pro některý z vašich blogů, PlaCla pošle (typicky do 5 minut) POST s JSON tělem:

{"event": "demand.created",
 "demand": {"id": 54899, "name": "…", "url": "…", "vip": false, "type": "web",
            "keywords": "…", "ns": 1, "publication": false, "expectation": "…",
            "reward": 225},
 "blogs": [{"id": 123, "name": "Váš blog"}]}

Hlavička X-PlaCla-Signature obsahuje HMAC-SHA256 těla vaším secretem. Ověření v PHP:

$telo = file_get_contents('php://input');
$podpis = $_SERVER['HTTP_X_PLACLA_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $telo, VAS_SECRET), $podpis)) {
    http_response_code(403); exit;
}
$data = json_decode($telo, true);
// ... zpracování; odpovězte 200, jinak PlaCla doručení opakuje (5/10/20/40 min, max 5×)

Pravidla používání

• API je určeno pro práci s vlastním účtem — automatizaci nabídek, napojení blogu, přehledy. Klíč je osobní jako heslo: nesdílejte ho a nevkládejte do veřejného kódu ani do JavaScriptu na stránce.
• Respektujte limity (aktuální stav vidíte v hlavičkách X-RateLimit-*). Obcházení limitů více klíči, hromadné vytěžování dat mimo vlastní účet nebo zásahy do provozu služby vedou ke zneplatnění klíčů, případně účtu.
• Za akce provedené vaším klíčem odpovídáte vy — platí stejná pravidla jako pro akce na webu (podmínky PlaCly).
• Změny API se řídí pravidly v changelogu: nová pole a události mohou přibývat kdykoli, existující se v /v1 nemění.

OpenAPI a AI asistenti

Strojově čitelný popis API (pro Postman, generátory klientů): openapi.yaml

PlaCla API v1 · dotazy a hlášení chyb (se support_code): [email protected]