REST API — POLITRAN

Základní URL

Všechny endpointy jsou pod prefixem https://www.politran.cz/api (JSON).

BASE = https://www.politran.cz/api

Obsah

Autentizace a tokeny

API používá Bearer token (Laravel Sanctum). Každý požadavek musí obsahovat hlavičku:

Authorization: Bearer váš_token

Způsob A — Token v uživatelském rozhraní (doporučeno pro integrace)

Pro vytvoření tokenů se musíte přihlásit.

Způsob B — Token přes API (email + heslo)

Jednorázové získání tokenu bez UI (vhodné pro skripty nebo první test):

POST https://www.politran.cz/api/auth/token

{
  "email": "vas@email.cz",
  "password": "heslo",
  "token_name": "muj-skript"  // volitelné
}

Odpověď obsahuje pole token — použijte je v hlavičce Authorization.

Organizace (více firem)

Pokud má uživatel přístup k více organizacím jako zadavatel, API ve výchozím stavu použije první z nich.

Pro konkrétní firmu pošlete hlavičku:

X-Organisation-Id: 123

Hodnota musí odpovídat organizaci, ke které má uživatel přístup (viz odpověď u /auth/token, pole organisations).

Endpointy

GET /notices

Seznam oznámení vlastněných vaší organizací (zadavatel).

Query: status, date_from, date_to, per_page (max 100)

GET /notices/{id}

Detail jednoho oznámení včetně stavu a hlavních polí.

POST /notices

Vytvoří nové oznámení ve stavu DRAFT. V těle musí být mimo jiné publisher_org_id (existující vydavatel v systému).

Odpověď 201: id, short_code, status.

POST /notices/{id}/send-to-publisher

Odešle koncept vydavateli (stejná pravidla jako v aplikaci — povinná pole musí být vyplněna). Po úspěchu je stav SENT_TO_PUBLISHER.

Stavy oznámení

Příklady (curl)

Nahraďte TOKEN a případně ID organizace / oznámení.

Seznam oznámení

curl -s "https://www.politran.cz/api/notices" \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json"

Detail

curl -s "https://www.politran.cz/api/notices/1" \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json"

Nové oznámení

curl -s -X POST "https://www.politran.cz/api/notices" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "publisher_org_id": 1,
    "advertiser_info": "Firma s.r.o., IČO …",
    "campaign_start_date": "2026-01-01",
    "campaign_end_date": "2026-01-31",
    "complaint_mechanism": "https://example.com/stiznost"
  }'

Odeslat vydavateli

curl -s -X POST "https://www.politran.cz/api/notices/1/send-to-publisher" \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json"

Jak mít API „skvělé“

Doporučení pro vývojáře a provoz:

• Verze a stabilita — držte kontrakt odpovědí (JSON klíče); při změnách zvažte verzi v URL (/v1/) nebo changelog.
• Idempotence — u akcí typu „odešli“ používejte u klienta kontrolu stavu (GET) před opakováním, aby nedošlo k dvojímu odeslání (u nás přechod z DRAFT jinam už nejde vrátit stejným tlačítkem).
• Tokeny — minimální oprávnění, token na integraci pojmenujte, neaktivní mažte; nikdy do Gitu ani do veřejných ticketů.
• Chyby — API vrací JSON s error a často errors u 422; logujte tělo odpovědi, ne jen HTTP kód.
• Limit — na API platí běžný rate limit (např. 60 požadavků/min/IP); při hromadných operacích používejte stránkování a backoff.
• HTTPS — v produkci vždy TLS; Bearer token v nešifrovaném kanálu neposílejte.
• OpenAPI — dlouhodobě lze doplnit strojově čitelný popis (Swagger/OpenAPI) pro generování klientů — dejte vědět, pokud to budete chtít jako další krok.

Chyby