Přeskočit na obsah
API dokumentace

Začínáme

Za pět minut budete mít klíč, ID firmy a první odpověď API.

1. Vytvořte API klíč

V aplikaci Poštárna otevřete Nastavení › Datové zdroje › API klíče a zvolte Nový API klíč.

  • Název: k čemu klíč slouží, například „CRM synchronizace“.
  • Platnost: poslední den platnosti (nejdéle 730 dní dopředu), nebo bez omezení. Klíč, který se 180 dní nepoužije, sám přestane fungovat.
  • Role: co klíč smí. Klíč nikdy nedostane víc práv než člověk, který ho vytváří, a přestane fungovat, když jeho autor z firmy odejde.
  • Přístup: plný (čtení i změny) nebo jen čtení (jen trasy, které nic nemění).

Klíč má tvar pst_ a 43 znaků. Zobrazí se jen jednou, Poštárna si ukládá jen jeho otisk. Uložte ho do správce hesel nebo proměnné prostředí, nikdy do kódu v repozitáři. Firma může mít nejvýš 20 platných klíčů.

Jakou roli klíči dát

Role určují úroveň v jednotlivých modulech (none, read, full). Každá operace v referenci uvádí modul a úroveň, kterou potřebuje.

Rolecontactscampaignscontentsettingsbilling
account_admin (správce účtu)fullfullfullfullfull
marketing_manager (marketing)fullfullfullreadnone
content_manager (obsah)nonereadfullnonenone
data_analyst (analytik)readreadreadnonenone
developer (vývojář)nonereadnonereadnone
finance (finance)nonenonenonenonefull
  • Pro běžnou integraci (kontakty, objednávky, kampaně, automatizace) stačí marketing_manager.
  • Účtové webhooky, feedy, kupóny, stavy objednávek a odesílací domény potřebují settings na úrovni full, tedy roli account_admin.
  • Role developer nevidí kontakty; pro integraci s kontakty ji nepoužívejte samotnou.
  • Moduly users a api_keys (členové, pozvánky, API klíče, připojené aplikace) klíč nikdy nedostane, ani s plným přístupem. Tyto trasy vrátí 403 forbidden / api_key.

2. Připravte proměnné prostředí

Terminál
export POSTARNA_API_KEY="pst_váš_klíč_zde"          # klíč z kroku 1
export POSTARNA_USER="vas.email@example.cz"         # e-mail člena firmy (jen pro HTTP Basic)

Všechny příklady v dokumentaci čtou klíč z POSTARNA_API_KEY a ID firmy z TENANT.

3. Zjistěte ID firmy

Cesty API v1 obsahují veřejné ID firmy: /api/v1/tenants/{tenant}/.... Zjistíte ho z API kompatibilního se SmartEmailingem, které ID firmy nepotřebuje:

Požadavek: GET /api/v3/account-info
curl -sS -X GET "https://www.postarna.cz/api/v3/account-info" \
  -u "$POSTARNA_USER:$POSTARNA_API_KEY"
Odpověď: 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}. Stejné ID ukazuje aplikace na stránce API klíčů.

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

4. První volání API v1

E-shopy firmy (každý má svou měnu a jazyk; ID e-shopu budete potřebovat skoro všude):

Požadavek: 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"
Odpověď: 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žadavek: 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"
Odpověď: 200 OK
{
  "items": [],
  "total": 0,
  "page": 1,
  "pageSize": 2
}

5. Dvě možnosti přihlášení

  • Bearer (doporučeno): Authorization: Bearer pst_....
  • HTTP Basic: uživatelské jméno je e-mail aktivního člena firmy, heslo je API klíč. Funguje na API v1 i v3 (tak se přihlašuje i SmartEmailing). Seznam použitelných e-mailů je na stránce API klíčů.

Cookie ani CSRF hlavičku API klíč nepotřebuje; ty používá jen webová aplikace.

6. Když něco nejde

Bez klíče (nebo s neplatným, propadlým či zrušeným klíčem) server odpoví 401:

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

Neplatný parametr vrátí 400 validation a v message název parametru:

Požadavek: 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"
Odpověď: 400 Bad Request
{
  "error": {
    "code": "validation",
    "message": "pageSize"
  }
}

Všechny kódy chyb s významem a nápravou: Chyby a limity.

Co dál