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 */
        }
    ]
}