Porovnat verze

Stará verze 6

changes.mady.by.user Former user

Uloženo na

v porovnání s

Nová verze 7

changes.mady.by.user Former user

Uloženo na

Klíč

  • Tento řádek byl přidán.
  • Tento řádek byl odstraněn.
  • Formátování bylo změněno.

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

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


Blok kódu
languagejs
{ "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

Blok kódu
languagejs
{ "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

Blok kódu
languagejs
{ "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:

Blok kódu
languagejs
  "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"
    }  ]


Varování
titleUpozornenie

Pri použití queryfields sa v niektorých prípadoch môže vrátiť chybová hláška Invalid column name 'názov', ktorá znamená nutnosť uviesť vo výpočte i dané pole.


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

Blok kódu
languagejs
    "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.

Blok kódu
languagejs
{
  "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:

Blok kódu
languagejs
{
    "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:

Image Added

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:

Image Added

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á.

Image Added


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".

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

Image Added

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

sdfsd




Obsah stránky

Obsah
classobsah