Dokumentace API - Zákazníci

Základní informace

Základní informace k API, autentizaci, stavovým kódům, HTTP metodám, datovým typům a další najdete na API v2 základní informace

Seznam zákazníků

• URI: /api/v2/customers/?creation_time_from={creation_time_from} &last_update_time_from={last_update_time_from} &active_yn={active_yn} &blocked_yn={blocked_yn} &language={language} &pricelist={pricelist} &page={page}
• HTTP metoda: GET
• hlavičky:
  • Authorization: Basic dGVzdDp0ZXN0
  • Content-Type: application/json
• parametry - slouží pro filtrování výstupu:
  • creation_time_from (date) - pouze zákazníci vytvoření od data
  • last_update_time_from (date) - pouze zákazníci u kterých došlo ke změně od data
  • code (string) - kód zákazníka
  • active_yn (bool) - aktivní / neaktivní
  • blocked_yn (bool) - blokovaní / neblokovaní
  • language (language) - jazyk zákazníka
  • pricelist (string) - ceník
  • email (string) - email
  • phone (string) - telefon
  • company_name (string) - název firmy
  • company_number (string) - DIČ
  • company_vat_number (string) - IČO
  • page (int) - stránka, pokud není definováno, vrací vždy stranu 1

Odpověď

Seznam zákazníků je dostupný po jednotlivých stranách, výstup je omezen na 100 položek na stránku.

• tělo:
  • current_page (int) - aktuální strana
  • current_page_items (int) - počet položek na aktuální straně
  • number_of_pages (int) - celkový počet stran
  • number_of_items (int) - celkový počet položek
  • customers (array) - pole objektů se zákazníky
    • customer_id (int) - ID zákazníka
    • type (string) - typ zákazníka, možné hodnoty jsou:
      • contact - kontakt (neregistrovaný zákazník)
      • customer - zákazník (registrovaný zákazník)
      • company - firma (registrovaný zákazník který má navíc firemní údaje)
    • degree (string) - titul
    • firstname (string) - křestní jméno
    • surname (string) - příjmení
    • nickname (string) - přezdívka
    • code (string) - kód zákazníka
    • language (language) - jazyk zákazníka
    • newsletter_yn (bool) - chce / nechce dostávat newsletter
    • newsletter_accept (string) - akceptuje zákazník newsletter (náhrada za newsletter_yn), možné hodnoty jsou:
      • notset - nenastaveno
      • no - ne
      • yes - ano
      • excluded - vyloučen (dle nastavení zákazník neotevřel určitý počet newsletteru)
    • pricelist (string) - ceník zákazníka
    • turnover (string) - obrat zákazníka
    • company (object) - firemní údaje
      • name (string) - název firmy
      • company_number (string) - IČO
      • vat_number (string) - DIČ
    • communication (object) - komunikace
      • phone (string) - telefon
      • fax (string) - FAX
      • im (string) - instant messaging
    • login (object) - přihlašovací údaje
      • active_yn (bool) - aktivní / neaktivní
      • blocked_yn (bool) - blokovaný / neblokovaný
      • email (string) - email
    • groups (array) - skupiny do kterých je zákazník zařazen
    • addresses (object) - adresy
      • billing (object) - fakturační adresa
        • street (string) - ulice
        • city (string) - město
        • state (string) - kraj
        • zip_code (string) - PSČ
        • country_id (country) - země
      • postal (array) - pole objektů s doručovacímy adresami
        • company_name (string) - název firmy
        • firstname (string) - křestní jméno
        • surname (string) - příjmení
        • street (string) - ulice
        • city (string) - město
        • state (string) - kraj
        • zip_code (string) - PSČ
        • country_id (country) - země
    • metas (array) - pole objektů s vlastními poli zákazníků
      • key (string) - klíč vlastního pole
      • type (string) - typ vlastního pole (hodnoty mohou být: radio, checkbox, input, date, email, number, select, multiselect, textarea, formatted)
      • value (string) - hodnota vlastního pole, v případě kdy je hodnota vlastního pole společná pro všechny jazyky
      • values (array) - pole objektů s hodnotami, v případě kdy není hodnota vlastního pole společná pro všechny jazyky
        • language (language) - specifikace jazykové mutace
        • value (string) - hodnota
    • creation_time (date) - datum a čas vytvoření
    • last_update_time (date) - datum a čas poslední změny
    • admin_url (string) - URL do detailu zákazníka v administraci

Aktualizace zákazníků

• URI: /api/v2/customers
• HTTP metoda: PUT
• hlavičky:
  • Authorization: Basic dGVzdDp0ZXN0
  • Content-Type: application/json
• tělo:
  • zákazníci se párují podle email. V odpovědi jsou všechni zákazníci kteří byli v požadavku.
  • customers (array) - pole objektů se zákazníky
    • email (string) - email zákazníka
    • newsletter_accept (string) - akceptuje zákazník newsletter, možné hodnoty jsou:
      • notset - nenastaveno
      • no - ne
      • yes - ano
      • excluded - vyloučen (dle nastavení zákazník neotevřel určitý počet newsletteru)
    • metas (array) - pole objektů s vlastními poli
      • key (string) - klíč vlastního pole
      • value (string) - hodnota vlastního pole

• příklad požadavku

  PUT /api/v2/orders HTTP/1.1
  Content-Type: application/json
  Authorization: Basic dGVzdDp0ZXN0
  
  {
      "customers": [
          {
              "email": "support01622708061@upgates.com",
              "newsletter_accept": "yes",
              "metas": [
                  {
                      "key":"custom_key_1",
                      "value": "1"
                  }
              ]
          }
      ]
  }

Odpověď

• tělo:
  • customers (array) - pole objektů se zákazníky
    • email (string) - email zákazníka
    • updated_yn (bool) - příznak jestli se zákazník aktualizoval
    • messages (array) - pole objektů chybových zpráv a upozornění při zpracování objednávky
      • object (string) - název objektu (část JSONu) kterého se zpráva týká
      • property (string) - hodnota které se zpráva týká
      • message (string) - text zprávy

• příklad odpovědi (HTTP 200 OK)

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "customers": [
          {
              "email": "",
              "updated_yn": "",
              "messages": [
                  {
                      "object": "",
                      "property": "",
                      "message": ""
                  }
              ]
          }
      ]
  }

Ověření přihlášení

• URI: /api/v2/customers/login

• HTTP metoda: POST

• hlavičky:

  • Authorization: Basic dGVzdDp0ZXN0
  • Content-Type: application/json

• tělo:

  • email (email) - přihlašovací email
  • password (string) - heslo

• příklad požadavku

  POST /api/v2/orders HTTP/1.1
  Content-Type: application/json
  Authorization: Basic dGVzdDp0ZXN0
  
  {
      "email": "",
      "password": ""
  }

Odpověď

• tělo:
  • authenticated (bool) - když vrací true je to platný přihlašovací email a heslo
  • messages (array) - pole objektů chybových zpráv a upozornění
    • object (string) - název objektu (část JSONu) kterého se zpráva týká
    • property (string) - hodnota které se zpráva týká
    • message (string) - text zprávy

• příklad odpovědi (HTTP 200 OK)

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "authenticated": "",
      "messages": [
          {
              "object": "",
              "property": "",
              "message": ""
          }
      ]
  }