===== Vevői rendelés API =====

Az eVIR rendszer lehetőséget biztosít külső rendszer számára számla készítésére.

Az általános [[evir:rendszer:api:api_altalanos|API]] leírásban szerepelnek az alapok, ezért itt már csak a specifikus részek szerepelnek.

A kommunikáció JSON alapkon zajlik, a követező módon:
<code>
https://evir.hu/cegnev/cgi-bin/index.cgi?json={"token":"jMuPFcKJdyKYqMZ7iGiLpxF/32k","dok":"api_rendeles_vevoi",...........}
</code>

----

a JSON adat egy hash, melynek kulcsai az alábbi jelentésekkel bírnak


=== API hívás paraméterei ===

^ mező ^ + ^ tipus/érték ^ jelentés ^
| token | M | string | a klienst azonosító evir felhasználó tokenje (evir felhasználó jelszavának módosításakor kiíródik) | 
| dok | M | "api_rendeles_vevoi" | az api hívást azonosítja |
| muvelet | *1 | "0", "M1", "P1", "M1P2", "P1M2", "P1M0" | hogyan jöjjön létre a bizonylat: [[bizonylat_muvelet|bizonylat művelet]] |
| email_cim | | string(100) | email cím "valami@example.com" formátumban |

  * ''*1'' Rendelés létrehozásakor hogyan készüljön bizonylat: [[bizonylat_muvelet|bizonylat művelet]]
    * ''0'' Csak a bizonylatszámot adja oda
    * ''M1'' A bizonylatot email-ben elküldi, és odaadja a bizonylatszámot
    * ''P1'' ''P1M0'' A bizonylatból PDF-et készít.
    * ''M1P2'' ''P1M2'' A bizonylatból PDF-et készít és a bizonylatot email-ben el is küldi

=== Partner adatai ===

A vevő partner adatai. [[bizonylat_partner_adatok|partner adatok]]

^ mező ^ + ^ tipus/érték ^ jelentés ^
| partner_id | *1 | szám | partner_id |

  * ''*1'' Lehet új partner adatokat megadni vagy meglévő partnerrel dolgozni
    * Ha a partner már rögzítve van az eVIR-ben, akkor elegendő az azonosítóját, a  ''partner_id''-t megadni. Semmilyen más partner adatot nem kell megadni.
    * Ha új partnernek készül a rendelés, akkor a ''partner_id'' mezőt ki kell hagyni, és minden egyéb partner adatot megfelelően ki kell tölteni.

^ mező ^ + ^ tipus/érték ^ jelentés ^
| partner_tipus | M | "cég" vagy "személy" | |
| partner_nev | M | string(90) | partner neve |
| partner_cim_orszag | M | string(2) | ország kétbetűs kódja, (pontosan 2 karakter) |
| partner_cim_orszag_nev | *1 | string | ország megnevezése. Megegyezik az evir törzsadatai szerinti névvel (maximum 50 karakter) |
| partner_cim_irszam | M | string(10) | irányítószám |
| partner_cim_varos | M | string(40) | település neve (maximum 40 karakter)
| partner_cim_cim | M | string(60) | közterület neve. nem bontott cím esetén házszám stb. egyben |
| partner_cim_jelleg | *2 | string(40) | közterület jellege |
| partner_cim_hazszam | *2 | string(20) | házszám |
| partner_cim_epulet | *2 | string(40) | épület |
| partner_cim_lepcsohaz | *2 | string(20) | lépcsőház |
| partner_cim_ajto | *2 | string(20) | ajtó |
| partner_adoszam | C | string(20) | adószám |
| partner_csoport_adoszam | C | string(20) | csoportazonosító szám |
| partner_kozadoszam | C | string(20) | Közösségi adószám |
| partner_third_adoszam | C | string(20) | Közösségen kívüli adószám |

  * ''M'' kötelezően Meg kell adni (mandatory)
  * ''*1'' Amennyiben az ország még nem szerepel az eVIR-ben, akkor kötelező megadni
  * ''*2'' Bontott cím esetén a közterület jellege mezőt ki kell tölteni, és minden egyéb cím adatot a megfelelő mezőben kell szerepeltetni.
  * ''C'' Csak cég esetén adható meg

=== Szállítási cím ===

A szállítási címet NEM kötelező megadni. Ha megadja, akkor a szállítási cím adatait az alábbi módon kell megadni.

^ mező ^ + ^ tipus/érték ^ jelentés ^
| szall_nev | M | string(90) | partner neve |
| szall_cim_orszag | M | string(2) | ország kétbetűs kódja, (pontosan 2 karakter) |
| szall_cim_orszag_nev | *1 | string | ország megnevezése. Megegyezik az evir törzsadatai szerinti névvel (maximum 50 karakter) |
| szall_cim_irszam | M | string(10) | irányítószám |
| szall_cim_varos | M | string(40) | település neve (maximum 40 karakter)
| szall_cim_cim | M | string(60) | közterület neve. nem bontott cím esetén házszám stb. egyben |
| szall_cim_jelleg | *2 | string(40) | közterület jellege |
| szall_cim_hazszam | *2 | string(20) | házszám |
| szall_cim_epulet | *2 | string(40) | épület |
| szall_cim_lepcsohaz | *2 | string(20) | lépcsőház |
| szall_cim_ajto | *2 | string(20) | ajtó |

  * ''M'' kötelezően Meg kell adni (mandatory)
  * ''*1'' Amennyiben az ország még nem szerepel az eVIR-ben, akkor kötelező megadni
  * ''*2'' Bontott cím esetén a közterület jellege mezőt ki kell tölteni, és minden egyéb cím adatot a megfelelő mezőben kell szerepeltetni.


=== Számlázásiási cím ===

A számlázási címet NEM kötelező megadni. Ha megadja, akkor a számlázási cím adatait az alábbi módon kell megadni.

^ mező ^ + ^ tipus/érték ^ jelentés ^
| szla_nev | M | string(90) | partner neve |
| szla_cim_orszag | M | string(2) | ország kétbetűs kódja, (pontosan 2 karakter) |
| szla_cim_orszag_nev | *1 | string | ország megnevezése. Megegyezik az evir törzsadatai szerinti névvel (maximum 50 karakter) |
| szla_cim_irszam | M | string(10) | irányítószám |
| szla_cim_varos | M | string(40) | település neve (maximum 40 karakter)
| szla_cim_cim | M | string(60) | közterület neve. nem bontott cím esetén házszám stb. egyben |
| szla_cim_jelleg | *2 | string(40) | közterület jellege |
| szla_cim_hazszam | *2 | string(20) | házszám |
| szla_cim_epulet | *2 | string(40) | épület |
| szla_cim_lepcsohaz | *2 | string(20) | lépcsőház |
| szla_cim_ajto | *2 | string(20) | ajtó |

  * ''M'' kötelezően Meg kell adni (mandatory)
  * ''*1'' Amennyiben az ország még nem szerepel az eVIR-ben, akkor kötelező megadni
  * ''*2'' Bontott cím esetén a közterület jellege mezőt ki kell tölteni, és minden egyéb cím adatot a megfelelő mezőben kell szerepeltetni.


=== Rendelés általános paraméterei ===

[[bizonylat_rendeles_adatok|Rendelés adatai]]

^ mező ^ + ^ tipus/érték ^ jelentés ^
| arkat | *1 | string(20) | árkategória (ha nincs megadva, akkor a partnerhez rendelt, vagy alapértelmezett árkategória lesz) ebből következik a számla pénzneme is |
| penznem | *1 | string(3) | pénznem |
| fizmod | | string(20) | fizetési mód, (beállítás szerinti hatással a teljdat, fizhat mezőkre) ha nincs megadva, alapértelmezett lesz) |
| rend_datum | | dátum | rendelés dátuma |
| szallhat| | dátum | szállítási határidő |
| hivatkozas | | string (30) | hivatkozás |
| megjegyzes | | string | Opcionális megjegyzés |
| nyelv | | string | a bizonylat nyelve (ha nincs megadva, HU) |
| webshop_type | | string | webshopot azonosító kód |
| webshop_id | | string | webshopban használt id |
| tetel_mezok | | tomb | tételsorokat tartalmazza. egy tételsor egy hash |

  * ''*1'' Az árkategória ''arkat'' és pénznem ''penznem'' mezők feldolgozásakor: 
    * Ha az árkategória meg van adva, akkor abból számolja ki a pénznemet is
    * Ha az árkategória nincs megadva, akkor a pénznem alapján próbál egy árkategóriát meghatározni.


----

=== Rendelés tétel mezői ===

A következő mezők a tetel_mezok tömbön belül többszörösen is megadható hashek adatszerkezete

Részletes dokumentáció: [[bizonylat_tetel_adatok|tétel adatok]]

^ mező ^ + ^ tipus/érték ^ jelentés ^
| tetel_tipusa | M *1 | termék raktár szolgáltatás vegosszetgi_engedmeny raktar_cikktorzs | [[bizonylat_tetel_adatok|tétel tipusa]] |
| tetel_forrasraktar | *2 | string | annak a raktárnak a kódja, ahonnan a terméket eladja. szolgáltatás (és előlegszámla) esetén nem kell megadni |
| tetel_cikkszam | M | string | a termék vagy szolgáltatás cikkszáma |
| tetel_menny | M | szám | az eladott mennyiség (pozitív szám) |
| tetel_netto | M | szám | nettó eladási egységár |
| tetel_megj | O | string | tételhez kapcsolódó megjegyzés szöveg (opcionális) |

  * ''M'' kötelezően Meg kell adni (mandatory)
  * ''O'' Opcionális
  * ''*1'' tétel tipusa, További részletek: [[bizonylat_tetel_adatok|tétel adatok]] oldalon
    * ''termék'': termék katalógusból (raktárkészlet foglalás nélkül)
    * ''raktár'': termék raktárkészlet foglalással
    * ''szolgáltatás'': szolgáltatás
    * ''vegosszegi_engedmeny'': rendelés végösszegéből adandó engedmény egy összegben
    * ''raktar_cikktorzs'': termék raktárkészlet foglalással a lehetőségek szerint
  * ''*2'' tetel_forrasraktar megadása ''termék'' és ''raktar_cikktorzs'' tételtipus esetén kötelező megadni. Egyébként nincs használatban.


A következő adatokat akkor kell megadni, ha a szolgáltatás cikkszám még nem szerepel a cikktörzsben. termék esetén nem használható

^ mező ^ + ^ tipus/érték ^ jelentés ^
| tetel_cikk_rogzites | *3 | "" vagy "szolg_fix" vagy "szolg_gen" | Hogyan kell a cikkszámot rögzíteni |
| tetel_cikk_megnevezes | R | string | a cikk megnevezése |
| tetel_cikk_afa | R | string | az áfakulcsot azonosító szám vagy szöveg |
| tetel_cikk_megys | R | string | Mennyiségi egység |
| tetel_cikk_unit | R | szám | legkisebb mennyiség |

  * ''*3'' tetel_cikk_rogzites ha meg van adva, akkor az 'R' jelű rögzítendő mezőket ki kell tölteni
  * ''R'' tetel_cikk_rogzites esetén megadandó adatok.


==== API hívás visszatérési értéke ====

Az api hívás paraméterétől, és a működés sikerességétől függően a visszatérési érték az alábbiak lehetnek.

[[api_valaszok|API válaszok]]

  * Sikeres PDF dokumentum
  * JSON válaszüzenet
  * Egyéb HTTP válaszüzenet

==== Példa JSON adatok ====

=== Minimális példa ===

Partner törzsadatból, bizonylatot nem nyomtatja, nem küldi email-ben

<code>
{
   "token":"...",
   "dok":"rendeles_api_felvesz",
   "muvelet":"0",
   "penznem":"HUF",
   "partner_id":"4",
   "tetel_mezok":[
      {
         "tetel_tipusa":"termék",
         "tetel_menny":"1",
         "tetel_netto":"1000",
         "tetel_cikkszam":"c1"
      }
   ]
}
</code>

Példa válaszüzenet JSON formátumban

<code>
[
   {
      "status":"OK",
      "rendelesszam":"RE2021000012",
      "message":[
         {
            "time":"2021.09.27 19:22:31.51",
            "message":"Rendelés rögzítve.",
            "level":"Info"
         },
         {
            "message":"status=OK",
            "level":"SysInfo",
            "time":"2021.09.27 19:22:31.58"
         },
         {
            "level":"SysInfo",
            "message":"rendelesszam=RE2021000012",
            "time":"2021.09.27 19:22:31.58"
         }
      ],
      "choice":{
         "back":{
            "session":{
               "proc":"back",
               "cid":"cZ9cvPgKHU",
               "lid":"zTsqM0LBHU",
               "sid":"QKYYSPhvHU"
            },
            "data":{}
         }
      },
      "framename":"main",
      "result":null
   }
]
</code>

----