ApiComPREM

Api (application programming interface) - aplikačné programové rozhranie (API) je súbor definícií podprogramov, komunikačných protokolov a nástrojov pre vývoj softvéru.

Com (communication) - z latinského communicare, čo znamená "zdieľať",

Prem - program Premier,

ApiComPrem - komunikačný nástroj pre zdieľanie dát v programe Premier.

Aplikácia slúži pre softvér tretích strán, ktoré majú možnosť priamo komunikovať s programom Premier.

ApiComPrem komunikuje cez protokol HTTP 1.1 metódou POST. Odosielané a prijaté dáta sú vo formáte JSON.

JavaScript Object Notation (javascriptový objektový zápis, JSON) je spôsob zápisu dát (dátový formát) nezávislý na počítačovej platforme, určený pre prenos dát, ktoré môžu byť organizované v poliach alebo zoskupené v objektoch. Vstupom je ľubovoľná dátová štruktúra (číslo, reťazec, boolean, objekt alebo z nich zložene pole), výstupom je vždy reťazec. Zložitosť hierarchie vstupnej premennej nie je teoreticky nijako obmedzená.

Header (hlavička HTTP):

POST /api/comm HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic Z3JhczpncjE3
ID-UJ: c8175fe2-5aba-460e-a492-5da487105394
Content-Length: xy
{
        JSON command
}

Authorization                   Meno a heslo používateľa z programu Premier vo formáte Base64.

ID-UJ                                 nastavenie ID účtovnej jednotky na servery HTTP

Content-Length              dĺžka odoslaných dát (JSON command)

Všeobecný popis ApiComPrem súborov

ApiComPrem.dll

• trieda volania HTTP / HTTPS, server
• komunikácia s SQL
• jednoduché SQL procedúry (select)
• registrovanie CLR SQL procedúr cez AutoRegisterAsm
• podpora pre VFP (čítanie DBF tabuliek, mem súborov, volanie procedúr z VFP, ...)
• štruktúry tried
• štruktúry tabuliek
• triedy pre JSON
• šifrovanie hesiel
• práca s certifikátmi
• čítanie Premier licencie
• ...

ApiComPremForm.exe

• nastavenie komunikácie (funguje iba s SQL verziou programu Premier)
• nastavenie účtovných jednotiek
• testovací server pre vývojárov
• testovací formulár pre vývojárov

ApiComPremSql.dll

• CLR SQL procedúry

ApiComService.exe

• windows služba pre volanie ApiComPrem.dll
• podpora pre inštalovanie a odinštalovanie služby

ApiComPremUpdate.exe

• aktualizácia ApiComPrem z FTP
• podpora automatického spustenia na pozadí

setup.xml

• uložená konfigurácia ApiComPrem

Newtonsoft.Json.dll

• Serializing a Deserializing ľubovoľného objektu .NET s výkonným JSON Serializing Json.NET. (https://www.newtonsoft.com/json)

JSON command

Používajú sa dva typy príkazov:

• OUT -čítanie dát z API servera
• IN - zapisovanie dát na API server

OUT príkaz (výstupný formát)

Formát HTTP_OUT

• Result
• CommandIn
• Error
  • { row }
    • number
    • desc
    • Warning
      • { row }
        • desc
        • help
        • Data
          •  vráti JSON dáta v závislosti od príkazu

Príklad načítania zoznamu všetkých príkazov s popisom použitia

{ "command": {
    "inComm": "INFO",
    "inParam": {
      "parameters": {
        "prikaz": "FULL"
      } } } }

inComm - názov príkazu

inParam - parametre príkazu, ktoré sa líšia podľa požadovaného inComm

Vrátený JSON v prípade úspešného načítania (RESULT – OK)

CommandIn - vrátený poslaný príkaz

Data - vrátí dáta podľa typu príkazu

{ "Result":"OK",
    "CommandIn":"INFO",
    "Data":
    [ {
            "CommList":
            [ {
                    "INFO":
                    {
                        "ID": 100,
                        "nazov": "INFO",
                        "pouziva_param": true,
                        "parametre":
                        [ {
                                "name": "table_name",
                                "is_required": false,
                                "desc": "nazov tabulky pre nacitanie struktury",
                                "format": "S",
                                "order": 0
                            }, {
                                "name": "prikaz",
                                "is_required": false,
                                "desc": "informacie o prikaze (FULL - posle vsetky)",
                                "format": "S",
                                "order": 0
                            } ],
                        "popis": "nacitanie inform.udajov",
                        "typ_prikazu": "OUT"
                    } },

Keď nastane chyba v spracovaní (RESULT - ERR)

Error - číslo a popis chyby. API nepošle žiadne pole "Data"
Warning - upozorní na nesprávne naplnené parametre, a v prípade, že RESULT = OK, tak polia Data sú vytvorené. Warning môže mať viac riadkov

{ "Result":"ERR",
    "CommandIn":"INFO",
    "Error":
    [  {
            "number":502,
            "desc":"Tabulka sa nenasla."
        } ],
    "Warning":
    [
        {
            "desc":"chyba spracovanie SQL stru.tabulky [Exception Type: System.Data.SqlClient.SqlException, Message: Invalid object name 'SDFASFA'.]]"
        } ] }

K príkazu command sa môže pridať príkaz "queryFields" ,ktorý určuje vrátené polia použitých tabuliek povolených v inComm:

  "queryFields": [ {
      "tableName": "FA_OUT",
      "tableFields": "INTER,CISLO,ZKKOD,STKOD,K_SYMBOL,OBJEDNAVKA,DOD_LIST,BANKA_DOKL,BANKA_NAZ"  },{
      "tableName": "POLOZKY",
      "tableFields": "FAKTURA,MNOZSTVI,CENA_MJ,CENA_SLV,CENA,CENA_DPH,SAZBA_DPH"
    }  ]

Keď logika inComm povolí, je možnosť poslať vlastné podmienky (parametre výberu) "queryCondition" príkazu:

    "queryCondition": {
      "tableName": "FA_OUT",
      "conditions": [ {
          "fieldName": "INTER",
          "relationalOperator": "=",
          "value": "15"
        } ] }

IN príkaz (vstupný formát)

Formát HTTP_in

• Command
  •  inComm
  •  inParam
    • Parameters
      • názvy a hodnoty parametrov v závislosti od príkazu
•  queryCondition
  • { row }
    • tableName
    • conditions
      • logicalOperator
      • fieldName
      • relationalOperator
      • value
      • queryFields
        • { row }
          • tableName
          • tableFields
          • Select
          • Data

Používa rovnakú logiku ako OUT príkaz + doplnené o pole „DATA“, ktoré sa posielajú na server.

{
  "command": {
    "inComm": "PARTNERI_ADD",
    "inParam": {
      "parameters": {
        "typCmd": null
      }
    }
  },
  "Data": {
    "INTER": 0,
    "ODBERATEL": true,
    "ID": "057fe3f7-3363-49ab-88bc-8c6342ad9a33",
    "CISLO": "0123456789",
    "NAZEV": "Test ADD",
    "ALT_NAZEV": null,
    "ULICE": null,
    "PSC": null,
    "MESTO": null,
    "STAT": null,
    "ICO": null,
    "DIC": null,
    "KON_PRIJEM": null,
    "MOBIL": null,
    "E_MAIL": null
  }
}

Všeobecné špecifikácie v príkazoch

Vstupný formát Timestamp:    rrrr-MM-dd HH: mm: ss
                                                   (HH = 24 hod. Formát, príklad: 2020-01-31 19:55:00)
Vstupný formát Dátumu:          rrrr-MM-dd

Chybové hlásenia

Vrátené chybové hlásenia majú spravidla tento formát:

{
    "Result": "ERR",                                                       /* OK/ERR */
    "CommandIn": "FA_OUT",                                                 /* názov príkazu */
    "Error": [
        {
            "number": 900,                                                 /* číslo chyby */
            "desc": "Exception Type: System.Data.SqlClient.SqlException, Message: Invalid column name 'inter'." /* podrobnosti k chybe */
        }
    ]
}

Prehľad chybových hlášok v result

Arithmetic overflow error converting expression to data type - došlo k pretečeniu hodnoty, keď je v databáze nižšia, než ktorú sa pokúšate zapísať

Invalid column name 'nazov' - obvykle sa zobrazí pri použití queryFields, kde je nutné uviesť vo výpočte aj povinnú databázovú položku

Musí byť vyplnený aspoň jeden z parametrov [ 'nazov'] alebo [queryConditions] - chýba vyplnenie aspoň jednej z uvedených povinných položiek

Can not continue the execution because the session is in the kill state - môže nastať v prípade volania príkazov za sebou, kedy sa nestihne vrátiť Result z predchádzajúceho príkazu a dochádza k stornu. Maximálny čas pre spracovanie jedného príkazu je nastavený v API na 2 min. Tento maximálny čas spojenia by si mal súčasne nastaviť a strážiť vo svojom programe aj programátor.

Chyba: 3521 - Požadovaná mena nie je v nastavení pre Kurzový lístok ČNB. Pre tuzemskú faktúru menu neudávajte - je nutné mať v Premier povolenú požadovanú menu:

Chyba: 3514 ... - chybný parameter FORMA vo faktúrach
Chyba: 3005 ... - všeobecná chyba SQL
Chyba: 3006 ... - názov partnera už existuje
Chyba: 3007 ... - požadované ID [xy] pre update partnera som nenašiel

ApiComPremForm

Pokiaľ nie je správne nastavený Compatibility Level v administrácii MS SQL, zobrazí sa pri Teste pripojenia táto chyba:

ApiComPremForm: Nastavenie HTTP

Slúži na nastavenie základných parametrov. Uložené nastavenie preberá HTTP server aj služba ApiComPremService, ktorá musí byť po vykonaní zmien reštartovaná.

Ak nie sú nainštalované SQL procedúry v SQL databáze, môže ApiComPrem vyhadzovať pri odosielaní príkazov chyby, potom je potrebné vykonať reinštaláciu procedúr hr. "Reinstall SQL CLR" a zároveň musí byť správne nastavená a programom prístupná cesta "Default cesta k HTML".

Tlačidlo Pridanie nového záznamu (= pripojenie ku konkrétnej firme v SQL verzii programu Premier)

Konfigurácia sa zapisuje do súboru setup.xml, ktorý môžete v prípade potreby upraviť aj ručne, dáta nie sú zašifrované.

ApiComPremForm: HTTP server

sdfsdVizuálne zobrazenie komunikácie HTTP servera. Po spustení preberá nastavenia z predchádzajúceho kroku a funguje iba s SQL verziou programu Premier.
Pri spustení http serveru sa kontroluje verzia ApiComSQL.dll a automaticky sa nainštalujú alebo preinštalujú požadované SQL procedúry na SQL servery. Pokiaľ k preinštalovaniu SQL procedúr nedôjde z nejakého dôvodu automaticky, možno použiť v Nastavení http tlačidlo Reinstal SQL CRL.

Image Added

ApiComPremService

Služba HTTP server, nahrádza spustenie vizuálneho formulára HTTP server. Inštaláciu vykonávajte ako správca. Všetky nastavenia sa preberajú z Nastavení http (súbor setup.xml).

Inštalácia:          ApiComPremService.exe "/ install
Odinštalácia:     ApiComPremService.exe "/ uninstall

Ak si nastavíte spustenie príkazu "ApiComPremUpdate.exe -auto" v plánovači úloh v požadovanú dobu, dôjde k zastaveniu spustenej služby a k automatickej aktualizácii programu.

ApiComPremForm: HTTP klient

Slúži na skladanie, vyskúšanie a ladenie všetkých odosielaných príkazov.

URI - IP adresa, na ktorej beží serverová časť http server.

Port - musí byť zhodný s nastavením.

ID UJ - ID účtovnej jednotky, musí byť zhodné s nastavením.

Basic authorization - je označenie pre jednoduchú autentizáciu pri prístupe na webové stránky. Webový server vyzve pomocou protokolu HTTP pristupujúceho klienta, aby poslal v rámci požiadavky na stránku tiež autentizačné informácie (tj. meno a heslo).

Užívateľ - užívateľ zavedený v IS Premier, s nastavenými právami pre čítanie, prípadne zápis podľa potreby s ohľadom na možnosti vzdialeného prístupu do systému.

Heslo - používateľ MUSÍ mať vložené heslo.

Create JSON Post - vytvorenie príkazu.

JSON parametre, kde je uvedená hodnota null, sa nemusia odosielať na server, v príkladoch sú uvádzané pre prehľadnosť.

Post - odoslanie vytvoreného príkazu

Ak vrátená dáta (JSON Result) sú príliš veľké, vytvorí sa súbor s výstupom v podadresári / temp. Ukladajú sa tu aj stiahnuté obrázky.