Příklady a reference Web API

Ověření připojení metodou test

Metoda test slouží pro otestování komunikace a zjištění verze Web API. Pro úspěšné volání je potřeba v hlavičce zaslat přidělený x-api-key.

GET /ESO9APITest/test HTTP/1.1
Host: apr
x-api-key: prideleny-api-key
Accept: application/json

Pokud je v hlavičce uveden formát XML nebo JSON, odpověď se vrátí v daném formátu. Pokud formát uveden není, použije se výchozí formát z konfigurace DefContentType.

Volání getData ve formátu XML

Metoda getData zprostředkovává komunikaci mezi ESO9 a třetí stranou. Hlavička musí obsahovat Content-Type, x-api-key a x-eso9-signature.

POST /ESO9APITest/getData HTTP/1.1
Host: apr
Content-Type: application/xml
x-api-key: prideleny-api-key
x-eso9-signature: vypocitany-podpis

Tělo požadavku:

<data>
  <vlTyp>1001</vlTyp>
  <params>
    <ico>27624609</ico>
  </params>
</data>

Příklad odpovědi:

<result>
  <id>185</id>
  <vlResult>1</vlResult>
  <data>
    <rowSubjekt>
      <nazev>ESO9 international a.s.</nazev>
      <ico>27624609</ico>
      <dic>CZ27624609</dic>
    </rowSubjekt>
  </data>
</result>

Volání getData ve formátu JSON

POST /ESO9APITest/getData HTTP/1.1
Host: apr
Content-Type: application/json
x-api-key: prideleny-api-key
x-eso9-signature: vypocitany-podpis

Tělo požadavku:

{
  "vltyp": 1001,
  "params": [
    {
      "nazev": "eso"
    }
  ]
}

Příklad odpovědi:

{
  "id": 4,
  "vlResult": 1,
  "data": [
    {
      "nazev": "ESO9 international a.s.",
      "ico": "27624609",
      "dic": "CZ27624609"
    },
    {
      "nazev": "ESO9 Slovakia s.r.o.",
      "ico": "44452675",
      "dic": "SK2022706521"
    }
  ]
}

Volání getDataAsync

getDataAsync používá stejné hlavičky i stejný formát těla jako getData. Rozdíl je ve zpracování: požadavek může v databázi pokračovat i po vypršení timeoutu CommandTimeoutAsync.

POST /ESO9APITest/getDataAsync HTTP/1.1
Host: apr
Content-Type: application/json
x-api-key: prideleny-api-key
x-eso9-signature: vypocitany-podpis

{
  "vltyp": 7,
  "params": [
    {
      "kod_uctu": "311"
    }
  ]
}

Pokud požadavek nedoběhne v časovém limitu, vrátí se informace o běžícím zpracování:

{
  "id": 16,
  "vlResult": -2,
  "data": [
    {
      "error": [
        {
          "errorCode": "160",
          "errorMessage": "Požadovaná operace nedoběhla v časovém limitu"
        }
      ]
    }
  ]
}

Zjištění výsledku asynchronního volání

Výsledek asynchronního volání se zjišťuje voláním vltyp = 997 a předáním ID záznamu WS_JOURNAL, které vrátilo předchozí volání.

{
  "vltyp": 997,
  "params": [
    {
      "idws_journal": 16
    }
  ]
}

Pokud požadavek stále běží, vrátí se informace o nedokončené operaci:

{
  "id": 123,
  "vlResult": 1,
  "data": [
    {
      "resultForId": [
        {
          "errorCode": 160,
          "errorMessage": "Požadovaná operace nedoběhla v časovém limitu"
        }
      ],
      "idws_journal": 16
    }
  ]
}

Pokud již operace doběhla, odpověď obsahuje výsledek daného požadavku:

{
  "id": 22,
  "vlResult": 1,
  "data": [
    {
      "resultForId": {
        "id": 20,
        "vlResult": 1,
        "data": [
          {
            "...": "výsledek zpracování"
          }
        ]
      },
      "id": 16
    }
  ]
}

Pravidla pro XML

Při sestavování XML komunikace se mají dodržovat jednotná pravidla:

• Názvy elementů začínají malými písmeny.
• Pokud je název elementu složen z více slov, každé další slovo začíná velkým písmenem.

Bezpečnost a provozní doporučení

• Pro produkční provoz používejte HTTPS.
• x-api-key identifikuje volající stranu a nesmí být veřejně sdílený.
• API hash slouží pro výpočet podpisu x-eso9-signature; zacházejte s ním jako s tajemstvím.
• U metod getData a getDataAsync kontrolujte povinné hlavičky Content-Type, x-api-key a x-eso9-signature.
• Pro dlouho běžící operace používejte getDataAsync a následné zjištění výsledku přes vltyp = 997.
• Pro omezení opakovaných požadavků lze použít konfiguraci CheckReplayRequest a ReplayRequestTime.

Řešení problémů

Chybí povinná hlavička nebo je neplatný podpis

Zkontrolujte:

• zda je zaslán Content-Type s hodnotou application/xml nebo application/json,
• zda je zaslán platný x-api-key,
• zda je zaslán x-eso9-signature,
• zda podpis odpovídá zaslanému tělu požadavku,
• zda podpisu nevypršela platnost podle RequestMaxSecValidity.

getDataAsync nevrací data ihned

U asynchronního volání je to očekávané chování. Pokud požadavek překročí CommandTimeoutAsync, Web API vrátí ID požadavku a zpracování pokračuje v databázi. Výsledek získejte voláním vltyp = 997 s idws_journal.

Opakovaný požadavek je odmítnutý

Pokud je zapnutý CheckReplayRequest, nelze po dobu danou parametrem ReplayRequestTime opakovat stejný dotaz.