Preskočiť na obsah
API dokumentácia

Začíname

Za päť minút budete mať kľúč, ID firmy a prvú odpoveď API.

1. Vytvorte API kľúč

V aplikácii Poštárna otvorte Nastavenia › Dátové zdroje › API kľúče a zvoľte Nový API kľúč.

  • Názov: na čo kľúč slúži, napríklad „CRM synchronizácia“.
  • Platnosť: posledný deň platnosti (najdlhšie 730 dní dopredu), alebo bez obmedzenia. Kľúč, ktorý sa 180 dní nepoužije, sám prestane fungovať.
  • Rola: čo kľúč smie. Kľúč nikdy nedostane viac práv než človek, ktorý ho vytvára, a prestane fungovať, keď jeho autor odíde z firmy.
  • Prístup: plný (čítanie aj zmeny) alebo len na čítanie (len trasy, ktoré nič nemenia).

Kľúč má tvar pst_ a 43 znakov. Zobrazí sa len raz, Poštárna si ukladá len jeho odtlačok. Uložte ho do správcu hesiel alebo premennej prostredia, nikdy do kódu v repozitári. Firma môže mať najviac 20 platných kľúčov.

Akú rolu kľúču dať

Role určujú úroveň v jednotlivých moduloch (none, read, full). Každá operácia v referencii uvádza modul a úroveň, ktorú potrebuje.

Rolacontactscampaignscontentsettingsbilling
account_admin (správca účtu)fullfullfullfullfull
marketing_manager (marketing)fullfullfullreadnone
content_manager (obsah)nonereadfullnonenone
data_analyst (analytik)readreadreadnonenone
developer (vývojár)nonereadnonereadnone
finance (financie)nonenonenonenonefull
  • Na bežnú integráciu (kontakty, objednávky, kampane, automatizácie) stačí marketing_manager.
  • Účtové webhooky, feedy, kupóny, stavy objednávok a odosielacie domény potrebujú settings na úrovni full, teda rolu account_admin.
  • Rola developer nevidí kontakty; na integráciu s kontaktmi ju nepoužívajte samotnú.
  • Moduly users a api_keys (členovia, pozvánky, API kľúče, pripojené aplikácie) kľúč nikdy nedostane, ani s plným prístupom. Tieto trasy vrátia 403 forbidden / api_key.

2. Pripravte premenné prostredia

Terminál
export POSTARNA_API_KEY="pst_vas_kluc_tu"           # kľúč z kroku 1
export POSTARNA_USER="vas.email@example.sk"         # e-mail člena firmy (len pre HTTP Basic)

Všetky príklady v dokumentácii čítajú kľúč z POSTARNA_API_KEY a ID firmy z TENANT.

3. Zistite ID firmy

Cesty API v1 obsahujú verejné ID firmy: /api/v1/tenants/{tenant}/.... Zistíte ho z API kompatibilného so SmartEmailingom, ktoré ID firmy nepotrebuje:

Požiadavka: GET /api/v3/account-info
curl -sS -X GET "https://www.postarna.cz/api/v3/account-info" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "status": "ok",
  "meta": [],
  "data": {
    "account_id": 4,
    "guid": "3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f",
    "username": "admin@example.cz",
    "firstname": null,
    "surname": null,
    "company": "Example s.r.o.",
    "phone": null
  }
}

Hodnota data.guid je vaše {tenant}. Rovnaké ID zobrazuje aplikácia na stránke API kľúčov.

Terminál
export TENANT="3f6c2a1e-8b7d-4c5e-9f10-2a3b4c5d6e7f"   # data.guid z odpovede

4. Prvé volanie API v1

E-shopy firmy (každý má svoju menu a jazyk; ID e-shopu budete potrebovať takmer všade):

Požiadavka: GET /api/v1/tenants/{tenant}/shops
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/shops" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "items": [
    {
      "id": "7",
      "code": "cz",
      "displayName": "Example.cz",
      "domain": "example.cz",
      "currency": "CZK",
      "language": "cs",
      "active": true
    },
    {
      "id": "8",
      "code": "sk",
      "displayName": "Example.sk",
      "domain": "example.sk",
      "currency": "EUR",
      "language": "sk",
      "active": true
    }
  ]
}

Kontakty, dva na stránku:

Požiadavka: GET /api/v1/tenants/{tenant}/contacts
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts?pageSize=2" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "items": [],
  "total": 0,
  "page": 1,
  "pageSize": 2
}

5. Dve možnosti prihlásenia

  • Bearer (odporúčané): Authorization: Bearer pst_....
  • HTTP Basic: užívateľské meno je e-mail aktívneho člena firmy, heslo je API kľúč. Funguje na API v1 aj v3 (takto sa prihlasuje aj SmartEmailing). Zoznam použiteľných e-mailov je na stránke API kľúčov.

Cookie ani hlavičku CSRF API kľúč nepotrebuje; tie používa len webová aplikácia.

6. Keď niečo nejde

Bez kľúča (alebo s neplatným, prepadnutým či zrušeným kľúčom) server odpovie 401:

Požiadavka: GET /api/v1/tenants/{tenant}/shops
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/shops"
Odpoveď: 401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": ""
  }
}

Neplatný parameter vráti 400 validation a v message názov parametra:

Požiadavka: GET /api/v1/tenants/{tenant}/contacts
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts?pageSize=500" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 400 Bad Request
{
  "error": {
    "code": "validation",
    "message": "pageSize"
  }
}

Všetky kódy chýb s významom a nápravou: Chyby a limity.

Čo ďalej