====== THORR Kommunikációs API ======


===== Paraméterek =====

^ Paraméter ^ Leírás ^
| ido |//(opcionális)// \\ idő típusú adat megadásának dátum formátuma **ISO 8601** \\ ''YYYY-MM-DD HH:mm:ss.ppp'' (Postgresql-ben használt timestamp formátum) |
| b64_xml | Base64 kódolásban egy XML adatstruktúra. \\ Az XML-ben a ''<DATA_TRANSFER>...</DATA_TRANSFER>'' kulcsok között kell lennie az átadott adatnak. |
| bizszam | //(opcionális)// \\ Tágabb értelemben vett bizonylatszám. Használata a legtöbb esetben opcionális. Ha megadásra kerül lekérdezés esetén, abban az esetben csak a bizonylatszámmal rendelkező rekord (rendelés, stb.) kerül visszaadásra. |
| művelet | eVIR-ben ezeket ''dok'' kulcsoknak nevezzük. Ezzel adható meg a kívánt funkcionalitás. |
| token | A feéhasználó, illetve jelen esetben a kommunikáló eszköz azonosítására szolgál. \\ A token létrehozásával és használatával kapcsolatban lásd [[evir:rendszer:api:api_altalanos]] |

A paramétereket POST és GET metódussal is át lehet adni. Egyszerűbb esetekben célszerű lehet magában sz URL-ben megadni, pl: <code>https://........./cgi-bin/index.cgi?token=A1B2C3D4&dok=thorr_api_get_material_change&ido=2020-03-01%2012:34</code>

===== Implementált funkciók =====

==== Változott cikkek ====
  * **dok:** thorr_api_get_material
  * **Paraméter:** ido
  * **Leírás:** A paraméterként megadott idő óta változott vagy létrejött cikkek adatai
  * **Thorr dokumentum:** 
  * **Adatok:**
  <code>
  MATERIAL_CODE => Cikkszám,
  MATERIAL_NAME => Cikk megnevezése,
  MATERIAL_TYPE => 'T',
  M_ACTIVE => Termék aktív-e, '1' vagy '0', 
  </code>

----
==== Új cikkek ====
  * **dok:** thorr_api_get_material_new
  * **paraméter:** ido
  * **Leírás:** A paraméterként megadott idő óta létrehozott új cikkek adatai.\\ Már nincs használatban.
  * **Thorr dokumentum:** 
  * **Adatok:** 
<code>
ld: 'Változott cikkek'
</code>

----
==== Változott partnerek ====
  * **dok:** thorr_api_get_shipto
  * **Paraméter:** ido
  * **Leírás:** A paraméterként megadott idő óta változott vagy létrejött partnerek adatai
  * **Thorr dokumentum:** 
  * **Adatok:** 
<code>

  SHIPTO_CODE => Partner id,
  SHIPTO_NAME => Partner név,
  
Partner cím:

  SHIPTO_COUNTRY => Országkód,
  SHIPTO_CITY => Város,
  SHIPTO_STREET => Közterület,
  SHIPTO_POST_CODE => Irányítószám,
    
Jelenleg a CUST adatok megegyeznek a SHIPTO adatokkal:   

   CUST_CODE => Partner id,
   CUST_NAME => Partner név,
   
Partner cím:

   CUST_COUNTRY => Országkód,
   CUST_CITY => Város,
   CUST_STREET =>  Közterület,
   CUST_POST_CODE => Irányítószám,
 
</code>

----
==== Új partnerek ====
  * **dok:** thorr_api_get_shipto_new
  * **Paraméter:** ido
  * **Leírás:** A paraméterként megadott idő óta létrejött új partnerek adatai \\ Nincs használatban
  * **Thorr dokumentum:** 
  * **Adatok:** <code>lsd. Változott partnerek </code>

----
==== Szállítói megrendelések ====
  * **dok:** thorr_api_get_inbound
  * **Paraméter:** ido
  * **Leírás:** A paraméterként megadott időpont után létrejött [[evir:rendeles:szallitoi:szallitoi_rendeles|Szállítói megrendelések]] adatai, melyeknek az állapota:"szállítandó". \\ **Fontos**: Egy szállítói megrendelésen egy cikkszám csak egyszer szerepeljen.
  * **Thorr dokumentum:** 
  * **Adatok:** 
<code>
  PO_HEAD =>
    PO_NUMBER => Berendelésszám,
    SUPPLIER_CODE => Rendelésen szereplő Partner id,
  PO_ITEM => 
    MATERIAL_CODE => Cikkszám,
    EXPECTED_QUANTITY => Mennyiség,
    PO_ITEM_ID => Tétel id: eviren belüli unique azonosító a berendelés tételéhez, 
</code>

----
==== Betárolás szállítói megrendelés alapján ====
  * **dok:** thorr_api_po_itemupdate
  * **Paraméter:** b64_xml
  * **Leírás:** A kapott XML alapján az eVIR készít egy [[evir:raktar:raktar_bevetelezes|Raktári bevételezést]], pontosabban egy "Bevételezés szállítólevélről" műveletet hajt végre, ahol a tételek a visszakapott szállítói rendelés tételei lesznek. \\ Egy betárolás visszaigazolás API hívás csak egyetlen  szállítói megrendelésre hivatkozhat. \\ A kapott XML-ben szereplő termékek mennyisége nem haladhatja meg a szállítói rendelésben szeplő mennyiséget. Kevesebb lehet, ekkor az eVIR-ben a rendelés állapota részteljesített lesz. A részteljesített megrendeléshez további betárolásokat lehet indítani egészen addig, ameddig szerepel rajta nem teljesített termék. A részteljesített megrendelést az eVIR felületen lehet lezárni, ha további beszállítások nem várhatóak hozzá.
  * **Thorr dokumentum:** 
  * **Adatok:** <code>...</code>

----

==== Betárolás szállítói rendelés nélkül ====
  * **dok:** thorr_api_inbound_itemupdate
  * **Paraméter:** b64_xml
  * **Leírás:** A kapott XML alapján az eVIR készít egy [[evir:raktar:raktar_bevetelezes|Raktári bevételezést]], pontosabban egy "Bevételezés szállítólevélről" műveletet hajt végre, ahol a tételek az xml-ben felsorolt tételek lesznek. \\ A beszállítónak szerepelnie kell az evirben, mint partner, a cikkszámoknak szerepelnie kell a cikktörzsben, ezen kívül más megkötés nincs a bevételezendőkre vonatkozóan.
  * **Thorr dokumentum:** 
  * **Adatok:** <code><?xml version="1.0" encoding="iso-8859-2"?>
  <DATA_TRANSFER>
    <HEADER>
      <FILE_ID>Mint az eddigi</FILE_ID>
      <TIMESTAMP>20210611113852821</TIMESTAMP>
      <SENDER>THORR</SENDER>
      <FUNCTION>INBOUND</FUNCTION>
      <SUBFUNCTION>ITEMUPDATE</SUBFUNCTION>
    </HEADER>
    <DETAIL>
      <INBOUND_HEAD>
        <INBOUND_ID>Bevételezés egyedi azonosító</INBOUND_ID>
        <VENDOR_ID>111111</VENDOR_ID>
        <VENDOR_SHIPMENT_NO>EVR1</VENDOR_SHIPMENT_NO>
      </INBOUND_HEAD>
      <INBOUND_DETAIL>
        <INBOUND_ITEM>
          <INBOUND_ITEM_ID>1</INBOUND_ITEM_ID>
            <MATERIAL_CODE>XXXXXXX</MATERIAL_CODE>
           <STORED_QUANTITY>20</STORED_QUANTITY>
        </INBOUND_ITEM>
        <INBOUND_ITEM>
          <INBOUND_ITEM_ID>2</INBOUND_ITEM_ID>
            <MATERIAL_CODE>YYYYYYY</MATERIAL_CODE>
            <STORED_QUANTITY>30</STORED_QUANTITY>
        </INBOUND_ITEM>
      </INBOUND_DETAIL>
    </DETAIL>
  </DATA_TRANSFER>
</code>

----
==== Teljesíthető vevői rendelés ====
  * **dok:** thorr_api_get_order
  * **Paraméterek:** bizszam
  * **Leírás:** A "teljesíthető" állapotban levő [[evir:rendeles:vevoi:vevoi_rendeles|Vevői rendelés]] adatainak lekérése. \\ Ha a ''bizszam'' paraméter megadásra kerül, akkor kizárólag a paraméterként megadott bizonylatszámú rendelés adatai kerülnek átadásra. \\ Szűrés nélkül valamennyi olyan megrendelés adatai szerepelnek a válasz XML-ben, amelyeknek az átvétele még nem került visszaigazolásra. A megrendelés tételei közül kizárólag a termékek kerülnek átadásra, minden más (pl. szolgáltatások) kiszűrésre kerülnek belőlük.
  * **Thorr dokumentum:** 
  * **Adatok:** 
<code>
  ORDER_HEAD=>
    ORDER_NUMBER  => Rendelésszám,
    DELIVERY_DATE => Szállítási határidő,
    SHIPTO_CODE  => Rendelésen szereplő Partner Id,
    CUST_CODE    => Rendelésen szereplő Partner Id, megegyezik a SHIPTO_CODE-al,
    CUSTOMER_PICKUP => 'N',
    ORDER_NOTE => Megjegyzés,
 
  ORDER_ITEM => 
     MATERIAL_CODE => Cikkszám,
     QUANTITY => Mennyiség,
     ITEM_ID => Tétel id, Eviren belüli unique azonosító a rendelés tételéhez
     ST_LOC_CODE => Az Eviren beállított Főraktárának az azonosítója,
</code>

----
==== Letöltött vevői rendelések visszaigazolása ====
  * **dok:** thorr_api_order_confirmed
  * **Paraméter:** b64_xml
  * **Leírás:** Az eVIR-ből sikeresen letöltött és Thorr által feldolgozott vevői rendelések visszaigazolása. A funkció célja, hogy a ''thorr_api_get_order'' API hívással csak olyan megrendelés adatai kerüljenek átadásra, amelyekkel még Thorr még nem rendelkezik.
  * **Thorr dokumentum:** 
  * **Adatok:** <code>
<DETAIL>
  <ORDER_HEAD>
    <ORDER_NUMBER> Rendelés száma </ORDER_NUMBER>
  </ORDER_HEAD>
</DETAIL>
<DETAIL>
  ...
</DETAIL>
</code>


----

==== Összekészített rendelés visszaigazolás ====
  * **dok:** thorr_api_order_picked
  * **Paraméter:** b64_xml
  * **Leírás:** Az eVIR-ből sikeresen letöltött és Thorr által feldolgozott vevői rendelés raktári összekészítettségének visszaigazolása. Az API hívásakor az eVIR-ben szereplő rendelés alapján egy [[evir:szallitolevel:szallitolevel|szállítólevelet]] készítünk. A szállítólevél számát a *bizszam* mezőben adjuk vissza. A rendelés folyamat állapotát "Szállítónak átadva"-ra állítjuk.
  * **Thorr dokumentum:** 4.1, PICKED
  * **Adatok:** 
<code>
<DETAIL>
  <ORDER_HEAD>
    <ORDER_NUMBER>Rendelésszám</ORDER_NUMBER>
    <DELIVERY_NOTE_NR>Megjegyzés</DELIVERY_NOTE_NR>
    <RECEIPT_DATE>Teljesítési dátum</RECEIPT_DATE>
  </ORDER_HEAD>
  <ORDER_DETAIL>
    <ORDER_ITEM>
        <PICKED_QUANTITY>Darabszám</PICKED_QUANTITY>
        <ITEM_ID> Tétel id </ITEM_ID>
    </ORDER_ITEM>
    <ORDER_ITEM>
       ...
    </ORDER_ITEM>
  </ORDER_DETAIL>
</DETAIL>
 </code>

----

==== Kiszállított rendelés visszaigazolás ====
  * **dok:** thorr_api_order_delivered
  * **Paraméter:** b64_xml
  * **Leírás:** Az eVIR-ből sikeresen letöltött és Thorr által feldolgozott vevői rendelés kiszállításának  visszaigazolása. A rendelés folyamat állapotát "Teljesítve"-re állítjuk. Ha a paraméterként kapott XML-ben az összes mennyiség 0, akkor úgy értelmezzük, hogy a rendelés nem lett kiszállítva, így sztornózzuk a kiállított szállítólevelet, a rajta szereplő tételek visszakerülnek készletre.
  * **Thorr dokumentum:** 4.1, DELIVERED
  * **Adatok:** <code> ... </code>


==== Aktuális készlet, leltárív ====

  * **dok:** thorr_api_actual_stock
  * **Paraméter:** b64_xml
  * **Leírás:** Az XML-ből kapott adatokból készítünk egy [[evir:raktar:leltar:leltar|vak leltárt]] a főraktárra nézve.
  * **Thorr dokumentum:** 8.0, ACTUAL STOCK 
  * **Adatok:** 
<code><DETAIL>
  <STOCK>
      <MATERIAL_CODE> cikkszám </MATERIAL_CODE>
      <QUANTITY> mennyiség </QUANTITY>
      <ST_LOC_CODE> evir raktárkód </ST_LOC_CODE>
  </STOCK>
</DETAIL>
<DETAIL>
...
</DETAIL>
</code>
 

----

===== Általános információk =====
  * Azoknál az API hívásoknál, amelyeknél lehetőség van paraméterként ''ido''-t megadni, csak a megadott időpontnál újabb adatok kerülnek visszaadásra. Idő megadása nélkül a szűrés nélküli, azaz az összes adat kérdezhető le egyszerre.
  * Sikeres lekérdezés esetén XML fájl kerül visszaadásra
  * Az XML file névében, valamint a HEADER TIMESTAMP mezőben visszaadásra kerül a lekérdezéskori eVIR oldali timestamp, ami a következő lekérdezések ''ido'' paramétereként folytatólagos lekérdezéshez használható. Ilyen módon nem kritikus a küldő és fogadó rendszer órájának szinkronban tartása.
  * A visszaadott adatok szerkezete és tartalma a jövőben változhat az specifikáció és az üzleti igényeknek megfelelően. 

===== Limitációk, problémák, defektek =====
  * A SHIPTO és CUST adatok a partner elsődleges címadataiból jönnek, függetlenül attól, hogy esetleg van a partnernek külön szállítási, számlázási, vagy bármilyen más címe


===== Fejlesztési segédlet, jogosultság =====

Az API használathoz a felhasználónak a ''Rendszer->API->Thorr->API Form'' menüponthoz kell jogosultságot adni, ami jelenleg a **th01** és **th02** jogokat takarja. 

Fejlesztési segédletként ezen a menüponton elérhető egy form, ahol megadható az idő és a megfelelő gomb megnyomásával lekérdezhetők az adatok. Ez a használat a fejlesztést segítendően létezik. A paraméterezése kicsit eltér az itt dokumentálttól, de a visszaadott eredmény megegyezik.


----
A dokumentáció alapján használható eVIR verzió: 18179
----
A fejlesztéshez használt Thorr specifikáció: {{ :spec:thorr_xpertrade_interface.pdf |}}