Integrace

API pro agentury a marketing týmy

API rozhraní pro týmy, které chtějí napojit objednávky social media služeb do vlastního workflow. Vyžaduje schválení přístupu.

Co řeší veřejná část

Návrh pro server-to-server integrace

Oddělené API přístupy podle projektu

Stav objednávky přes veřejný nebo serverový identifikátor

Klíče a interní napojení zůstávají pouze na serveru

Požádat o přístup Prohlédnout služby

Rozhraní

Kurátorované služby, ne chaotický panel

Tyto stránky drží veřejný slib oddělený od provozní logiky, platebních interních procesů a admin správy.

Bezpečné hranice

API nesmí vystavovat interní klíče, dodavatelské chyby ani provozní kategorie. Veřejné rozhraní má pracovat s kurátorovanými SMM produkty.

Stav objednávek

Automatizace má navázat na stejný princip jako storefront: platba, fulfillment a stav objednávky jsou oddělené a auditovatelné.

Integrace

Co ze stránek převedete přes API

REST API

Volání jako u veřejné objednávky: služba, odkaz, množství. Bez interních provozních polí.

Idempotentní operace

POST /orders používá hlavičku Idempotency-Key, aby opakovaný request nezaložil druhou objednávku.

Server-only secrets

API klíče zůstávají na serveru. Veřejná část aplikace se k nim nedostane.

Polling status

Stav objednávky čtete přes publicId. Webhooks jsou plánované, ne součást live veřejného kontraktu.

API v1

Backend endpointy jsou připravené

Rozhraní pracuje jen s veřejnými službami, předplaceným wallet kreditem a veřejným trackingem. Provider ID, náklady a raw payloady zůstávají interní.

GET/api/smm/v1/services

Veřejný seznam aktivních služeb, CZK cena, limity a dostupnost.

POST/api/smm/v1/orders

Vytvoří objednávku z předplaceného kreditu pro DB API klíče. Vyžaduje Bearer token a Idempotency-Key.

GET/api/smm/v1/orders/{publicId}

Vrací veřejný tracking objednávky přes publicId bez provider internals.

Pro koho

Pro koho je API určeno

API je vhodné pro týmy s vyšším objemem nebo automatizovaným workflow. Pro jednotlivé objednávky doporučujeme veřejný checkout.

Orientačně 50+ objednávek měsíčně

Agentury

Spravujete desítky klientských kampaní. API se vám hodí, pokud objednávky vznikají automaticky z briefu nebo kampaňového toolu.

Orientačně 50+ objednávek měsíčně

Marketing týmy in-house

Děláte performance pro vlastní značku přes vícero kanálů a chcete sjednotit objednávky s ostatními nástroji.

Partnerský review

Automatizační platformy

Provozujete nástroj pro správu social media a chcete napojit naše služby jako další integraci. Potřebujeme partnerský review.

Možnosti

Co API umí

Čtyři hlavní operace, které pokryjí typický agenturní use case.

Načtení katalogu služeb

GET seznam aktivních služeb s CZK cenou, limity a aktuální dostupností. Pomůže synchronizovat váš interní katalog.

Vytvoření objednávky

POST se serviceId, URL, množstvím a kontaktem. U DB-backed API klíčů se cena strhne z předplaceného wallet kreditu a odpověď vrátí SMM-* publicId se statusUrl.

Sledování stavu

GET veřejný status objednávky. Můžete pollovat nebo přeposlat klientovi přímo veřejný odkaz.

Refill request

U vybraných balíčků s refillem můžete podat žádost o doplnění. Schvalujeme manuálně v rámci smluvních podmínek.

Bezpečnost

Bezpečnost a token

Tokeny jsou citlivé jako přístup k předplacenému wallet kreditu. Pracujte s nimi výhradně na serveru.

Authorization: Bearer

Doporučený způsob autentizace. Token posílejte v hlavičce Authorization, nikdy v URL ani v klientském kódu.

Live kontrakt

Scopes a revokace

Přístup omezujeme přes scopes, stav klienta a rotaci tokenů. Síťová omezení řešíme individuálně mimo live veřejný kontrakt.

Rotace tokenu

Token je možné kdykoli rotovat. Doporučujeme rotaci minimálně jednou ročně nebo po každé personální změně v týmu.

Únik tokenu

Při podezření na únik nás okamžitě kontaktujte. Token zneplatníme a vystavíme nový bez přerušení provozu.

Pozor: Autentizace přes token v URL není podporovaná. Použijte hlavičku Authorization: Bearer nebo serverovou hlavičku x-smm-api-key.

Code samples

Tři jazyky pokrývají většinu integrací. DB-backed objednávky čerpají prepaid wallet kredit a vrací publicId ve formátu SMM-*.

Code samples

Tři ukázky pro vaše integrace

V ukázkách používáme placeholder <YOUR_API_TOKEN> nebo process.env.SMM_API_TOKEN. Skutečný token získáte po schválení API přístupu — nikdy ho nevkládejte do klientského kódu. DB-backed objednávky se hradí z prepaid wallet kreditu a vrací publicId ve formátu SMM-*.

GET/api/smm/v1/services

Načtení katalogu služeb

GET seznam aktivních služeb s CZK cenou, limity a dostupností. Tento endpoint nevyžaduje token, ale doporučujeme volat ho z vašeho serveru.

curl -X GET "https://koupitsledujici.cz/api/smm/v1/services" \
  -H "Accept: application/json"

POST/api/smm/v1/orders

Vytvoření objednávky

POST objednávky pro DB-backed API klíče používá prepaid wallet kredit a vyžaduje Idempotency-Key. Odpověď vrací veřejné publicId ve formátu SMM-* a statusUrl.

# Agency plán: DB-backed API klíč strhává objednávky z prepaid wallet kreditu.
# Odpověď vrátí publicId "SMM-ABCDEFGH23456789" a statusUrl pro tracking.
curl -X POST "https://koupitsledujici.cz/api/smm/v1/orders" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Idempotency-Key: agency-plan-klient-001-2026-05-12" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "instagram-sledujici",
    "platform": "instagram",
    "targetUrl": "https://www.instagram.com/example",
    "quantity": 500,
    "email": "ucetni@agentura.cz",
    "termsAccepted": true,
    "clientReference": "klient-001"
  }'

GET/api/smm/v1/orders/{publicId}

Stav objednávky

GET veřejný tracking objednávky přes publicId. Stav vrací stejné hodnoty jako veřejný odkaz, žádná interní provider data.

curl -X GET "https://koupitsledujici.cz/api/smm/v1/orders/SMM-ABCDEFGH23456789" \
  -H "Accept: application/json"

Limity

Limity API

Limity drží stabilitu pro všechny partnery. Detail upravíme v rámci smlouvy podle vašeho objemu.

Manual gate

Požadavky za minutu

Smluvní throttling podle integrace

Manual gate

Objednávky za den

Denní limit nastavíme při onboardingu

Podle katalogu

Množství na objednávku

Dle konkrétní služby a její dostupnosti

Manual gate

Max paralelních volání

Dohodneme podle provozního profilu

Limity jsou smluvní provozní pravidlo, ne veřejný runtime quota contract. Konkrétní technické limity a chování při překročení potvrdíme před aktivací API přístupu.

Fakturace

Fakturace API

DB-backed API objednávky se hradí z předplaceného wallet kreditu. Fakturace shrnuje dobíjení a spotřebu.

Měsíční souhrn

Jedna faktura za měsíc se spotřebou. Přijde e-mailem v PDF a strukturovaném formátu.

Dobití kreditu

Wallet kredit dobíjíte před čerpáním API. Create-order request pak nestrhává kartu, ale používá dostupný prepaid zůstatek.

B2B reverse charge

Pro plátce DPH v EU mimo ČR aplikujeme reverse charge dle platné legislativy.

Přístup

Jak požádat o přístup

API není veřejné. Po obdržení e-mailu si projdeme váš use case, vybraný plán a prepaid wallet vazbu.

Co poslat

Název agentury / firmy a IČO
Předpokládaný měsíční objem objednávek
Hlavní use case (orchestrace kampaní, interní tooling, klientský dashboard, …)
Platformy, které vás primárně zajímají
Kontaktní osoba pro technické otázky

Požádat o API přístup

FAQ

Časté otázky k API

Existuje minimální měsíční objem?

Orientačně doporučujeme 50+ objednávek měsíčně, abyste API plně využili. Pro nižší objemy je v drtivé většině efektivnější veřejný checkout.

Jaké je SLA?

Standardní orientační dostupnost API je 99,5 % měsíčně. Závazné SLA upravíme v rámci smlouvy podle objemu a vašich potřeb.

Existuje test mode / sandbox?

Pro testování poskytujeme oddělené API tokeny s nižšími limity a označením v dashboardu. Detaily nastavíme po schválení přístupu.

Podporujete idempotenci?

Při vytváření objednávky lze poslat clientReference pro vaši reconciliaci. Serverová deduplikace opakovaných create-order requestů zatím není součástí veřejného kontraktu.

Co dělat při úniku tokenu?

Kontaktujte support, token okamžitě zneplatníme a vystavíme nový. Doporučujeme rotovat tokeny minimálně jednou ročně.

Plánujete webhooks?

Webhooks pro stav objednávky jsou v plánu. Aktuálně doporučujeme polling endpoint pro status objednávky s rozumným intervalem.

Začněte

Domluvte si přístup

API přístup vám zařídíme do několika pracovních dnů po obdržení žádosti. Detaily plánu, tokenů a prepaid wallet kreditu řešíme bilaterálně.

Požádat o API přístup Zobrazit dokumentaci

Jak to funguje

Stejný princip jako veřejné objednávky

1
Krok 1
Vyberete službu
Platforma, typ a počet. Cenu vidíte rovnou na kartě.
2
Krok 2
Vložíte odkaz
Profil, video, příspěvek nebo kanál. Bez hesla i bez aplikace.
3
Krok 3
Zaplatíte kartou
Pár kliknutí přes Stripe. Doklad dorazí e-mailem.
4
Krok 4
Sledujete průběh
Veřejný odkaz se stavem. Žádné hádání, žádný účet.

Výhody

Stejný český základ pro veřejné objednávky

Bez registrace

Žádné účty ani hesla. Stačí e-mail, ten dostane doklad a odkaz na stav objednávky.

Platba kartou v CZK

Stripe checkout jako u běžného eshopu. Visa, Mastercard, Apple Pay i Google Pay.

Vidíte, kdy to dorazí

Po platbě dostanete veřejný odkaz, kde sledujete průběh. Otevřete si ho kdykoli.

Doklad pro účetnictví

Klasická česká faktura v CZK přijde e-mailem hned po zaplacení. Hodí se i firmám.

Jen ověřené balíčky

Nemáme tisíc položek pro každý vrtoch. Jen služby, které drží kvalitu a dávají smysl.

Refill u vybraných balíčků

Pojistka pro případ poklesu po doručení. Označení uvidíte rovnou u ceny balíčku.

Stav objednávky

Sledujte průběh přes veřejný odkaz

Po zaplacení dostanete přehledný odkaz se stavem objednávky. Bez registrace, bez hledání v e-mailu a bez interních technických detailů.

Najít objednávku Vybrat službu

Příklad průběhu

Přijato
Zaplaceno
•Zařazeno
Probíhá
Dokončeno