Metody a procedury Web API

Publikované metody

Na rozhraní ESO9 Web API jsou publikovány tři metody.

Metoda	HTTP	Účel
test	GET	Vypíše verzi Web API, zkontroluje připojení k databázi a povolení komunikace pro zaslaný x-api-key.
getData	GET, POST	Zprostředkovává hlavní komunikaci mezi aplikací třetí strany a ESO9.
getDataAsync	GET, POST	Zpracuje požadavek asynchronně. Používá se pro operace, které mohou přesáhnout synchronní timeout.

Hlavičky požadavků

Metoda test

Pro úspěšné volání metody test je potřeba v hlavičce požadavku zaslat přidělený x-api-key.

Pokud je v hlavičce požadavku zaslán Content-Type pro XML nebo JSON, výsledek je vrácen v daném formátu. Pokud zaslán není, použije se výchozí formát z parametru DefContentType.

Metody getData a getDataAsync

Hlavička požadavku musí obsahovat:

Hlavička	Popis
Content-Type	Domluvený formát komunikace: application/xml nebo application/json. Jiné formáty nejsou podporovány.
x-api-key	Identifikátor třetí strany.
x-eso9-signature	Podpis zasílané zprávy směrem do ESO9. Algoritmus výpočtu je popsaný v samostatném dokumentu X-ESO9-SIGNATURE.

Pokud některá z povinných hlaviček chybí, podpis je neplatný nebo mu vypršela časová platnost, Web API vrátí chybové hlášení.

Obecný formát požadavku

Tělo požadavku musí odpovídat formátu uvedenému v Content-Type.

XML požadavek

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

Element vlTyp obsahuje domluvenou celočíselnou hodnotu, podle které ESO9 rozpozná požadovanou operaci. Element params obsahuje samotná vstupní data.

Web API kontroluje, že tělo požadavku odpovídá očekávanému formátu, elementy vlTyp a params nejsou prázdné a vlTyp je celočíselná hodnota.

JSON požadavek

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

Elementy vltyp a params mají stejný význam jako v XML komunikaci.

Obecný formát odpovědi

Výsledkem volání je XML nebo JSON podle použitého formátu komunikace.

XML odpověď

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

JSON odpověď

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

Význam základních položek:

Položka	Popis
id	ID výsledku, tedy IDWS_JOURNAL.
vlResult	Stav výsledku požadavku.
data	Vrácená data nebo chybové hlášení.

Základní hodnoty vlResult:

Hodnota	Význam
1	Požadavek byl zpracován ihned a výsledek je v položce data.
0	Požadavek bude zpracován později a na výsledek je potřeba se znovu dotázat podle id.
-1	V zaslaných datech byla chyba a výsledek nemohl být zpracován.
-2	U asynchronního volání požadovaná operace nedoběhla v časovém limitu a dál běží v databázi.

Hodnoty lze podle dohody rozšířit.

Pravidla pro getDataAsync

Metoda getDataAsync používá stejné hlavičky a stejný formát těla jako getData. Rozdíl je ve způsobu zpracování.

Každý požadavek je spuštěn v samostatném vlákně a v databázi může pokračovat i po vypršení timeoutu. Pokud požadavek nedoběhne do limitu CommandTimeoutAsync, třetí straně se vrátí informace s ID záznamu požadavku v databázi, hodnotou vlResult = -2 a informací o probíhajícím zpracování.

Příklad odpovědi při pokračujícím zpracování:

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

Pro zjištění výsledku se následně volá getData s vltyp = 997 a s hodnotou idws_journal vrácenou předchozím voláním.

Pokud požadavek stále běží v databázi, vrací se odpověď s informací o nedokončeném zpracování. Pokud již doběhl, vrací se uložený výsledek daného požadavku.

Uživatelská procedura spWSCall_UzivProc

Veškerá komunikace mezi ESO9 a třetí stranou probíhá na databázovém serveru. Uživatelské procedury musí mít předem definované rozhraní a jejich výsledkem je update tabulky WS_JOURNAL, kde je uložen výsledek dotazu ve formátu XML nebo JSON, stav výsledku a čas výsledku.

Uživatelské procedury se volají z hlavní procedury obecného rozhraní:

dbo.spWSCall_UzivProc
  @Send_API_KEY varchar(600),
  @VLTYP smallint,
  @params varchar(max),
  @vlFormat smallint,
  @IDWS_JOURNAL int,
  @IDLOGUSER int

Parametry:

Parametr	Popis
@Send_API_KEY	API key přidělené třetí straně. Identifikuje volající stranu.
@VLTYP	Určuje, jaká procedura je volaná.
@params	Vstupní data zaslaná třetí stranou.
@vlFormat	Typ komunikace: 1 = XML, 2 = JSON.
@IDWS_JOURNAL	ID záznamu v WS_JOURNAL, kam se ukládá výsledek volání procedury.
@IDLOGUSER	ID uživatele pro záznamy v logovací databázi, nastavené ve web.config parametrem IDLogUser.

Seznam standardních procedur

Pro vyhrazené hodnoty 1-1000 jsou od verze ESO9 6.6 postupně zapracovávány hlavní procedury. Procedury jsou zapracovávány pro XML i JSON a každá je volána vlastní procedurou, která zprostředkovává rozparsování XML nebo JSONu.

vltyp	API SQL procedura	Standardní SQL procedura
1	spWSCall_TxtSubjekt	spTXT_SUBJEKT
2	spWSCall_TxtSubjAdr	spTXT_SUBJADR
3	spWSCall_TxtSubjOsoba	spTxt_SubjOsoba
4	spWSCall_TxtSubjBUcet	spTxt_SubjBUcet
5	spWSCall_TxtZbozi	spTxt_Zbozi
6	spWSCall_TxtZbozSkl	spTxt_ZbozSkl
7	spWSCall_TxtUcetZap	spTxt_UcetZap
8	spWSCall_TxtHDOK	spTxt_HDOK
9	spWSCall_TxtUcetZap_NespSaldo	sptxt_UcetZap_NespSaldo
10	spWSCall_TxtSDokZbozSkl	spTXT_SDokZbozSkl
11	spWSCall_TxtArchSumUcetZap	spTXT_ArchSumUcetZap
12	spWSCall_TxtUdalost	spTxt_Udalost
13	spWSCall_TxtSDOK	sptxt_SDOK
997	spWSCall_GetResult	-
1000	spWSCall_GetPopisProc	spWSCall_GetPopisProc

Podrobné XML a JSON rozhraní jednotlivých standardních procedur je uvedené na samostatné stránce Detailní rozhraní procedur. Pro nové integrace je nutné ověřit konkrétní seznam podporovaných položek pro daný vltyp.

Speciální procedury

spWSCall_GetResult

Slouží pro zjištění výsledku požadavku spuštěného přes getDataAsync.

XML:

<data>
  <vlTyp>997</vlTyp>
  <params>
    <idws_journal></idws_journal>
  </params>
</data>

JSON:

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

spWSCall_GetPopisProc

Slouží pro zjištění popisu procedury podle jména.

XML:

<data>
  <vlTyp>1000</vlTyp>
  <params>
    <proc_name></proc_name>
  </params>
</data>

JSON:

{
  "vltyp": 1000,
  "params": [
    {
      "proc_name": "spWSCall_TxtSubjekt"
    }
  ]
}