Jak hledat a zakládat zákazníky v adresáři Pohody

Adresář je v Pohodě srdcem všech dokladů. Když je faktura nebo objednávka navázaná na záznam v adresáři, vidíte u zákazníka všechny jeho doklady, saldo i historii. Když se adresa jen opíše, vznikne doklad „bez vazby“ — a přehledy podle odběratelů přestanou sedět.

V tomhle návodu si ukážeme, jak zákazníka v adresáři najít, jak ho založit a jak potom jeho ID použít v dokladech.

Najít zákazníka podle IČ

IČ je nejspolehlivější způsob, jak firmu najít:

curl "https://api.apios.cz/api/v1/address?ico=12345678" \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN"

{
  "data": [
    {
      "id": 25,
      "company": "ABC s.r.o.",
      "name": "Jan Novák",
      "street": "Václavské nám. 109",
      "city": "Praha",
      "zip": "11000",
      "ico": "12345678",
      "dic": "CZ12345678",
      "email": "jan.novak@abc.cz",
      "maturity": 14
    }
  ],
  "count": 1
}

Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:

Podle stejného principu hledáte i podle dalších údajů: company (název firmy), name (kontaktní osoba), city, zip, dic nebo number (číslo záznamu v adresáři). Filtry se dají kombinovat.

Důležité je pole id — to je interní ID záznamu, kterým se na zákazníka odkazujete v dokladech.

Založit nového zákazníka

Pokud zákazník v adresáři není, založte ho:

curl -X PUT https://api.apios.cz/api/v1/address \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "ABC s.r.o.",
    "name": "Jan Novák",
    "street": "Václavské nám. 109",
    "city": "Praha",
    "zip": "11000",
    "ico": "12345678",
    "dic": "CZ12345678",
    "email": "jan.novak@abc.cz",
    "phone": "+420 777 123 456",
    "maturity": 14
  }'

Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:

Povinné jsou name, street, city a zip. Užitečná nepovinná pole:

• maturity — počet dní splatnosti, který se předvyplní na fakturách,
• price_ids — cenová hladina odběratele (např. velkoobchod),
• ad_group a ad_key — skupiny a klíčová slova pro třídění adresáře,
• ship_to_addresses — jedna nebo víc dodacích adres,
• account_number a bank_code — bankovní účet zákazníka.

Odpověď vrátí ID nového záznamu:

{
  "success": true,
  "message": "Adresa byla úspěšně vytvořena",
  "data": { "id": 58, "action_type": "add" }
}

Postup „najdi, jinak založ“

V integraci e-shopu nebo CRM se nejvíc osvědčil tento postup:

1. Má zákazník IČ? Hledejte podle ico.
2. Nenašel se? Založte ho přes PUT /api/v1/address.
3. ID si uložte u zákazníka ve svém systému, ať příště nemusíte hledat.
4. V dokladech posílejte customer_id místo adresy — viz import objednávky nebo vystavení faktury.

Úprava kontaktu

Zákazník změnil e-mail nebo sídlo? Upravte jen to, co se změnilo:

curl -X PATCH https://api.apios.cz/api/v1/address/25 \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "fakturace@abc.cz" }'

Totéž volání najdete v dokumentaci se všemi parametry a můžete si ho tam rovnou vyzkoušet:

Synchronizace s CRM

Pokud mají obchodníci kontakty v CRM a účetní v Pohodě, dřív nebo později se rozejdou. Parametr last_changes vrátí jen záznamy změněné od zadaného okamžiku, takže CRM si může jednou za hodinu stáhnout, co se v Pohodě změnilo:

curl "https://api.apios.cz/api/v1/address?last_changes=2026-10-19T08:00:00" \
  -H "X-AUTH-TOKEN: VAS_API_TOKEN"