Metody a procedury Web API

Hlavní metody rozhraní

Na rozhraní Web API jsou publikovány následující metody:

Metoda test

HTTP metoda: GET

Vypíše verzi Web API, zkontroluje připojení k databázi a ověří oprávnění komunikace pro zaslané x-api-key.

GET /test HTTP/1.1
Host: server:port
x-api-key: your-api-key

Odpověď (příklad):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "version": "4.0.0.0",
  "database": "connected",
  "authorized": true
}

Metoda getData

HTTP metoda: GET, POST

Zprostředkovává hlavní komunikaci mezi aplikací třetí strany a ESO9. Tato metoda slouží k získání dat z databáze ESO9.

GET /getData?vltyp=1&conditions=... HTTP/1.1
Host: server:port
Content-Type: application/json
x-api-key: your-api-key

nebo

POST /getData HTTP/1.1
Host: server:port
Content-Type: application/json
x-api-key: your-api-key

{
  "vltyp": 1,
  "conditions": [ ... ]
}

Parametry:

• vltyp – Typ procedury (číslo identifikující konkrétní proceduru)
• conditions – Podmínky filtrování dat (volitelné)

Metoda getDataAsync

HTTP metoda: GET, POST

Umožňuje asynchronní zpracování požadavků. Vhodná pro dlouhodobě běžící dotazy, které by mohly překročit timeout synchronního volání.

POST /getDataAsync HTTP/1.1
Host: server:port
Content-Type: application/json
x-api-key: your-api-key

{
  "vltyp": 1,
  "conditions": [ ... ]
}

Konfigurace: Pro použití této metody je potřeba v web.configu nastavit dvě vlastnosti:

• CommandTimeoutAsync – Timeout v sekundách
• ConnStrSQLAsync – Speciální connection string s Asynchronous Processing=true

Odpověď (v průběhu zpracování):

{
  "status": "processing",
  "requestId": "guid-string",
  "message": "Dotaz je zpracováván"
}

Výsledek lze später zjistit voláním metody s vltyp = 997 a předaným requestId.

Databázové procedury

Web API zprostředkovává volání následujících databázových procedur:

Procedura	Popis
SPWSCALL_TXTSUBJEKT	Subjekty
SPWSCALL_TXTSUBJADR	Adresní údaje subjektů
SPWSCALL_TXTSUBJOSOBA	Fyzické osoby subjektů
SPWSCALL_TXTSUBJBUCET	Účty subjektů
SPWSCALL_TXTZBOZI	Zboží
SPWSCALL_TXTZBOZSKL	Skladové zásoby zboží
SPWSCALL_TXTUCETZAP	Účetní zápisyа
SPWSCALL_TXTHDOK	Hlavičky dokladů
SPWSCALL_TXTUCETZAP_NESPSALDO	Nesplacené salda účetních zápisů
SPWSCALL_TXTSDOKZBOZSKL	Řádky dokladů se skladovými zásobami
SPWSCALL_TXTARCHSUMUCETZAP	Archivní sumy účetních zápisů
SPWSCALL_TXTUDALOST	Událost
SPWSCALL_TXTSDOK	Řádky dokladů
SPWSCALL_GETRESULT	Výsledek zpracování
SPWSCALL_GETPOPISPROC	Popis procedury

Formáty komunikace

Každá procedura podporuje komunikaci v obou formátech:

• XML – Strukturovaný XML formát
• JSON – JSON formát pro aplikace preferující modernější syntax

Format se specifikuje v HTTP záhlaví Content-Type:

• Content-Type: application/xml
• Content-Type: application/json

Autentizace

Všechny volání metod je potřeba opatřit hlavičkou x-api-key obsahující autorizační klíč:

x-api-key: your-unique-api-key

Autorizační klíč se nastavuje v konfiguraci Web API a kontroluje se při každém volání.

Pravidla volání

Pravidla pro metodu test

• Bez parametrů
• Může být volána bez x-api-key (pro diagnostiku)
• Vrátí informace o stavu serveru

Pravidla pro metodu getData

1. Povinný parametr: vltyp (číslo procedury)
2. Volitelné podmínky: conditions (pole objektů se filtry)
3. Odpověď obsahuje pole objektů s daty
4. Maximální timeout lze nastavit v CommandTimeout

Pravidla pro metodu getDataAsync

1. Vhodná pro dotazy, které by mohly překročit timeout
2. Vrátí requestId pro pozdější dotaz na výsledek
3. Výsledek se zjistí voláním s vltyp = 997
4. Databáze pokračuje v zpracování i po návratu odpovědi