SAPI-SK fejlesztőknek

Mi a SAPI-SK

A SAPI-SK a nemzeti REST-felület az ügyfélrendszer (ERP, webáruház, könyvelőszoftver) és az Access Point között. A cél egy egységes, szállítófüggetlen mód arra, hogy a „digitális postáson” keresztül bizonylatokat küldjön és fogadjon, az egyes szolgáltatók saját API-ja helyett. A SAPI-SK támogatását ezért tekintse biztosítéknak a szállítói bezáródás (vendor lock-in) ellen.

Hitelesítés

OAuth2 client_credentials használatos. A portálon API-tokent hoz létre: ennek UUID-ja szolgál client_id-ként, a vpt_… érték pedig client_secret-ként. A POST /sapi/auth/token hívással rövid élettartamú access tokent és refresh tokent kap; az access tokent ezután az Authorization: Bearer … fejlécben küldi. Az API-token visszavonása a portálon azonnal érvényteleníti a kiadott tokeneket is.

Küldés és fogadás

• Küldés: POST /sapi/document/send az X-Peppol-Participant-Id fejléccel (a résztvevő, akinek a NEVÉBEN küld: az Ön cége vagy az Ön tokenje alatti ügyfél; a címzettet a dokumentum metaadatai tartalmazzák) és az Idempotency-Key fejléccel (biztonságos ismétlés duplikátumok nélkül). Tömegesen a POST /sapi/document/batch hívással (hívásonként legfeljebb 100 bizonylat).
• Kézbesítési állapot: a GET /sapi/document/sent a küldött bizonylatok állapotát adja vissza (pending → delivered / rejected az MLS-átvételi igazolásból, vagy undeliverable, ha a címzettnek nincs címe a Peppol-hálózatban), ?since= paraméterrel a növekményes letöltéshez.
• Fogadás: GET /sapi/document/receive (lapozás, szűrés állapot szerint) és a feldolgozás visszaigazolása az acknowledge hívással.
• Bizonyítékok és PI-bejelentések (1.8.14-től): minden bizonylat hordoz egy fsReport objektumot (reported / pending / not_required indoklással, a bejelentés azonosítója és a C5 verdiktje), a küldöttek statusReason-t és xmlSha256-ot is; egyszerre legfeljebb 200 bizonylat állapota a POST /sapi/document/sent/status hívással, idővonal a GET /sapi/document/sent/{id}/events hívással. A webhookok hordozzák az fsReport-ot és az új invoice.report_pending és invoice.report_rejected eseményeket.
• Token állapota / megújítás / visszavonás: külön végpontok a /sapi/auth/* alatt.

Sandbox és idempotencia

A szerződést a sandboxban próbálhatja ki a valódi kézbesítés kockázata nélkül: a sandbox ellenőrzi a kéréseket, és mock válaszokat ad. Küldéskor mindig használjon Idempotency-Key-t: ugyanannak a kérésnek az ismétlésekor (pl. időtúllépés után) nem keletkezik duplikált bizonylat. A kulcsot a számla valamilyen állandó jellemzőjéből vezesse le (pl. a számla azonosítója vagy száma az Ön rendszerében); ugyanahhoz a számlához egy új kulcs megkerüli ezt a védelmet. Ha a bizonylatot a küldés előtti ellenőrzésünk elutasította (pl. érvényesítési hiba), a hálózatba semmi sem ment ki, és semmi sem kerül bejelentésre a Pénzügyi Igazgatóságnak: javítsa ki, és küldje el újra ugyanazzal a kulccsal, a kiállítás dátumával a tényleges küldés napja szerint. A kézbesített számlát nem küldjük újra, jóváírással vagy terheléssel javítjuk. A hibákat a POST /sapi/document/validate (küldés nélkül ellenőrzi a bizonylatot) és a GET /sapi/discovery (a címzett a Peppol-hálózatban van-e) hívásokkal előzheti meg.

Hol találja a részleteket

A végpontok teljes listája, kérés-/válaszpéldák és hibakódok a műszaki dokumentációnkban találhatók (SAPI-SK szakasz), a géppel olvasható OpenAPI 3.1 specifikációval együtt. Javasoljuk, hogy a sandboxban kezdjen, és csak utána térjen át az éles rendszerre.