aPilot API

Úvod

Komunikační rozhraní, umožňuje oboustrannou výměnu dat s platformou aPilot (export a import).

Datový formát XML. Zabezpečeno přístupovými údaji ke konkrétním webům (jméno a heslo), které zakládá a vydává firma Pilot, bez nich API nelze použít a od přístupových údajů do administrace se liší. API je ve verzi 1.0.

Komunikace zahrnuje většinu dat modulů Katalog a Uživatelé, ostatní moduly nejsou podporovány.

Spojení

Spojení s komunikačními body aPilot jsou prováděny zabezpečeným protokolem HTTP, přístupové jméno a heslo k vyžádání u firmy Pilot. Pro export z aPilot slouží metoda HTTP GET, pro import do aPilot HTTP POST s XML daty v těle požadavku.

Adresa přístupových bodů vždy vychází z adresy administrace webu, např. https://apilot-cz.apilot.cz/api/v1/apilot/export/catalog-orders nebo https://apilot-cz.apilot.cz/api/v1/apilot/import/addressbook, kdy část apilot-cz je proměnlivá pro každou instanci aPilot.

Příklad volání API knihovnou CURL včetně předaných přihlašovacích údajů a souboru s daty pro import:

curl -X POST --user apilot:heslo --data @catalog=cards.xml https://apilot-cz.apilot.cz/api/v1/apilot/import/catalog-cards

Přístupové body

Export z aPilot

/api/v1/apilot/export/addressbook
- uživatelé adresáře, jejich firmy a dodací adresy
/api/v1/apilot/export/catalog-cards
- karty katalogu včetně jejich cen, stavu skladu a vazeb na obrázky, kategorie a ostatní agendy
/api/v1/apilot/export/catalog-params
- parametry karet katalogu
- vazba na kartu dle katalogového čísla
/api/v1/apilot/export/catalog-category
- číselník kategorií katalogu pro následné navázání na karty katalogu
/api/v1/apilot/export/catalog-tree
- číselník stromu katalogu pro následné zařazení karty katalogu
/api/v1/apilot/export/catalog-orders
- objednávky katalogu, posledních 300, včetně identifikace zákazníka a položek objednávek

Import do aPilot

/api/v1/apilot/import/addressbook
- uživatelé adresáře, jejich firmy a dodací adresy
- vyžaduje unikátní e-mailovou adresu každého uživatele
/api/v1/apilot/import/individual-prices
- individuální ceny karet katalogu uživatelů
- vazba na uživatele a kartu katalogu dle katalogového čísla
/api/v1/apilot/import/catalog-cards
- karty katalogu včetně jejich cen, stavu skladu, překladů a vazeb na obrázky, kategorie a ostatní agendy
- párování produktů dle katalogového čísla, které musí být u každé karty unikátní
/api/v1/apilot/import/catalog-cards-price
- aktualizace ceníku karet katalogu
- vazba na kartu dle katalogového čísla
/api/v1/apilot/import/catalog-cards-supply
- aktualizace stavu skladu karet katalogu
- vazba na kartu dle katalogového čísla
/api/v1/apilot/import/catalog-params
- parametry karet katalogu
- vazba na kartu dle katalogového čísla
/api/v1/apilot/import/catalog-category
- číselník kategorií katalogu pro následné navázání na karty katalogu
/api/v1/apilot/import/catalog-tree
- číselník stromu katalogu pro následné zařazení karty katalogu
/api/v1/apilot/import/catalog-orders
- aktualizace stavu objednávek (a odeslání automatických e-mailů zákazníkům)
- vazba číslem objednávky
- nelze importovat celé objednávky, pouze jim nastavit status

Struktura dat

Přístupové body očekávají konkrétní strukturu dat. Některé položky lze vynechat, v případě importu jsou ignorovány. Prázdné položky mažou předchozí hodnotu. Často je použita pouze vazba na jinou agendu v podobě celočíselného identifikátoru. API používá kódování UTF-8.

Struktura exportu objednávek

data - obalující element
- order - opakuje se pro každou exportovanou objednávku
  - id - pořadové čéslo objednávky, celé číslo
  - num - číslo objednávky generované v číselné řadě
  - created - datum a čas vzniku objednávky
  - status - status objednávky, odkazuje na číselník
  - note - poznámka zákazníka
  - person - identifikace nakupujícího
    - name - křestní jméno
    - surname - příjmení
    - city - město
    - street - ulice
    - house_number - číslo domu
    - zip - PSČ
    - country - stát
    - country_code - ISO kód země, dva znaky
    - user_contact - identifikátor registrovaného zákazníka, celé číslo
    - email - e-mailová adresa
  - company - pokud byl nákup na firmu
    - name - název
    - ico - IČO
    - dic - DIČ
    - user_customer - identifikátor registrované firmy, celé číslo
  - delivery - pokud byla zadána adresa dodání
    - name - křestní jméno
    - surname - příjmení
    - city - město
    - street - ulice
    - house_number - číslo domu
    - zip - PSČ
    - country - stát
    - country_code - ISO kód země, dva znaky
  - delivery - název zvolené dodací podmínky
  - payment - název zvolené platební podmínky
  - price - hodnota objednávky
    - sum - bez DPH
    - sum_vat - vč. DPH
    - currency - měna, ISO kód, tři znaky
    - discount - slevový kupón, pokud byl uplatněn
      - code - kód kupónu
      - sum - sleva bez DPH
      - sum_vat - sleva vč. DPH
  - cards - položky objednávky
    - card - opakuje se pro každou položku
      - cat - katalogové číslo objednávky
      - name - název položky
      - quantity - počet objednaných kusů
      - price - jednotková cena bez DPH
      - price_vat - jednotková cena vč. DPH
      - vat - sazba DPH

Vzorové soubory ke stažení

Přenos obrázků katalogu

Pro přenos obrázků ke kartám katalogu se využívá FTP přístup, který zajišťuje firma Pilot. Nahrané obrázky se poté přiřazují v datech předávaných na přístupový bod /api/v1/apilot/import/catalog-cards. Pro bezproblémové zobrazování obrázků na webu se doporučuje použít v názvu souborů pouze alfanumerické znaky, pomlčku a podtržítko a vyvarovat se použití velkých písmen a diakritiky.