Nech ste malá firma, veľký podnik alebo dodávateľ softvéru, rozhranie API spoločnosti Qvalia vám ponúka jediný štandardizovaný spôsob integrácie so sieťou Peppol s voliteľnou podporou ďalších tokov EDI, inteligentného spracovania dokumentov a obohacovania údajov.
Prostredníctvom služby Invoicing API môžete pracovať s Peppol správami súvisiacimi s faktúrami, ako sú BIS Billing faktúra), BIS Billing Note (dobropis), BIS Self-Billing Invoice (samofaktúra), BIS Self-Billing Credit Note (samodobropis) a BIS Invoice Response na faktúru), a v prípade potreby ich doplniť o Message Level Response (odpoveď na úrovni správy) pre technické potvrdenia súvisiace s faktúrami a inými Peppol správami.
API môže:
- Pomôžte malej spoločnosti rýchlo začať posielať faktúry Peppol
- Podpora veľkých podnikov so štruktúrovanými tokmi správ s veľkým objemom
- Softvér na fakturáciu energie a ERP systémy, ktoré vyžadujú pripojenie viacerých používateľov pre mnohých zákazníkov
V tejto príručke sa naučíte:
- Nastavte transakčné API Qvalia ako svoj Peppol a EDI hub
- Vymeňte svoju prvú faktúru Peppol prostredníctvom API
- Rozšírte svoje možnosti nad rámec faktúr na objednávky, katalógy a ďalšie dokumenty
- Umožňuje škálovateľné modely s viacerými nájomcami pre dodávateľov softvéru
- Pridajte pokročilé funkcie umelej inteligencie na obohatenie údajov a extrakciu PDF.
Prehľad: API pre Peppol a EDI
Peppol API poskytuje jednotné rozhranie pre elektronické obchodné správy prostredníctvom Peppol a EDI. Je navrhnuté tak, aby podporovalo základné scenáre, ako napríklad:
- Faktúry a dobropisy
- Objednávky a odpovede na objednávky
- Zmeny a zrušenie objednávok
- Katalógy a aktualizácie položiek
- Oznámenie o odoslaní
- Odpovede na úrovni správ a aktualizácie stavu
Všetky koncové body používajú spoločný dizajnový princíp:
- HTTP koncové body založené na REST
- Podpora formátov JSON aj XML
- UBL 2.1 ako základný dátový model
- Spracovanie chýb pomocou štandardných stavových kódov HTTP
Pre vás to znamená, že môžete uvažovať v kategóriách obchodných správ namiesto sietí a protokolov. Vytvárate platné dokumenty založené na UBL; Qvalia spracováva vrstvu Peppol a EDI na pozadí.
Začíname: predpoklady a nastavenie
Na začatie práce s rozhraním Peppol API spoločnosti Qvalia potrebujete len niekoľko základných informácií:
Účet Qvalia
Vaša organizácia je zaregistrovaná ako zákazník Qvalia. Dostanete registračné číslo účtu, ktoré jednoznačne identifikuje váš účet vo všetkých transakčných volaniach.
Kľúč API
Overovanie sa vykonáva prostredníctvom kľúča API, pričom pre testovacie a produkčné prostredia sa používajú samostatné kľúče. Všetky volania sa vykonávajú cez HTTPS s moderným TLS.
Číslo registrácie účtu v ceste URL
Transakčné volania obsahujú vaše číslo registrácie účtu (accountRegNo) v ceste. Napríklad:
POST /transaction/{accountRegNo}/invoices/outgoingVoľba formátu: JSON alebo XML
Môžete si vybrať JSON alebo XML prostredníctvom štandardných HTTP hlavičiek (Content-Type a Accept). Ak nie je explicitne zvolený žiadny formát, predvoleným formátom je JSON.
Akonáhle sú tieto prvky na mieste, ste pripravení začať testovať prevádzku Peppol s Qvalia.
Krok za krokom: integrácia vášho prvého toku faktúr Peppol (odosielanie a prijímanie)
Táto časť vás prevedie typickou prvou integráciou medzi vaším systémom a transakčným API Qvalia, ktorá zahŕňa odosielanie aj prijímanie faktúr Peppol.
Krok 1: Začnite v sandboxe
Začnite integráciou do prostredia sandboxu:
- Základná URL adresa (príklad): https://api-qa.qvalia.com
- Rovnaký model overovania, koncové body a štruktúra ako vo výrobe
To vám umožňuje vytvárať a testovať bez ovplyvnenia skutočných zákazníkov alebo finančných tokov.
Krok 2: Použite svoj API kľúč a číslo účtu (accountRegNo)
V konfigurácii uložte:
- Váš API kľúč (pre sandbox)
- Vaše kontoRegNo
Každá žiadosť by mala obsahovať:
- Autorizačná hlavička s kľúčom API
- accountRegNo v ceste koncového bodu, napríklad:
Vystavené faktúry:/transaction/{accountRegNo}/invoices/outgoing
Prichádzajúce faktúry (pull):/transaction/{accountRegNo}/invoices/incoming
Krok 3: Vyberte JSON alebo XML (na báze UBL)
Všetky transakcie používajú ako základný štandard UBL 2.1.
Môžete buď:
- Generovať UBL 2.1 XML alebo
- Použite reprezentáciu UBL JSON, ktorá mapuje rovnakú štruktúru do polí JSON.
Formát riadia hlavičky:
JSON (predvolené)
Content-Type: application/jsonAccept: application/jsonXML
Content-Type: application/xmlAccept: application/xmlTáto flexibilita vám umožňuje integrovať rozhranie Peppol API do prostredí JSON-first aj XML-first.
Krok 4: Priraďte svoju faktúru k UBL
Ďalej priraďte svoj interný model faktúry k prvkom UBL. K dispozícii sú formáty UBL JSON aj UBL XML.
- Informácie v hlavičke (faktúra, dátum vystavenia, kód typu faktúry)
- Strany (Účtovná strana dodávateľa, Účtovná strana zákazníka)
- Súčty (Daňový súčet, Právny peňažný súčet)
- Riadky (InvoiceLine, Item, Price, TaxCategory)
Cieľom je zabezpečiť, aby:
- Všetky povinné polia sú vyplnené
- Hodnoty sú v súlade s príslušným profilom Peppol (napríklad BIS Billing)
- Sú splnené vaše vlastné obchodné požiadavky (referencie, nákladové strediská, kódy projektov)
Potom to serializujete ako JSON alebo XML, v závislosti od vášho výberu formátu. Pre prichádzajúce faktúry použijete rovnakú štruktúru UBL pri čítaní, overovaní a mapovaní údajov z Qvalia do vášho interného modelu.
Krok 5a: Odoslanie odchádzajúcej faktúry Peppol
Krok 5.1: Odoslanie odchádzajúcej faktúry Peppol
S pripraveným odchádzajúcim dátovým nákladom, príklad koncového bodu:
POST https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/outgoingZahrnúť:
- Autorizačná hlavička s vaším API kľúčom
- Správna hlavička Content-Type (JSON alebo XML)
- Údajová časť faktúry založená na UBL v tele požiadavky
Qvalia overí faktúru, odošle ju prostredníctvom siete Peppol aleboVAN a vráti odpoveď s identifikátormi a stavom.
Krok 5.2: Prijímanie prichádzajúcich faktúr Peppol
Na načítanie prichádzajúcich faktúr z Qvalia prostredníctvom API zvyčajne:
Zavolajte prichádzajúci koncový bod, napríklad:
GET https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/incomingVoliteľne môžete:
- Filtrovanie alebo stránkovanie výsledkov (v závislosti od nastavenia)
- Použite koncové body „read“ na rozlíšenie nových a už spracovaných faktúr.
Vrátený UBL JSON alebo XML sa potom zmapuje do vášho interného dátového modelu na účely zverejnenia, schválenia alebo ďalšieho spracovania.
Krok 6: Spracovanie monitorovania, odpovedí a chýb
Transakčné API používa predvídateľné kódy stavu HTTP, ktoré môžete priradiť k protokolom, monitorovaniu a správam používateľov. Typické vzory:
- 200 OK – Žiadosť bola úspešná a údaje boli vrátené.
- 204 Žiaden obsah – Úspešná požiadavka, žiadne telo nie je k dispozícii
- 400 / 422 – Neplatné údaje alebo schéma; upravte svoje dáta alebo analýzu
- 401 / 403 – Problémy s overením alebo oprávnením
- 404 – Zdroj nebol nájdený (často ide o problém s cestou alebo ID)
- 409 – Konflikt, napríklad duplicity
- 429 – Dosiahnutý limit rýchlosti; spomaľte svoje požiadavky
- 500 – Interná chyba; skúste to znova alebo informujte podporu, ak problém pretrváva
Rovnaké postupy platia bez ohľadu na to, či faktúry odosielate alebo prijímajte.
Použite protokol transakcií na operatívne sledovanie
Okrem odpovedí API sa môžete kedykoľvek prihlásiť do Qvalia a skontrolovať aktivitu v protokole transakcií. Tým získate prehľad o tom, čo sa deje vo vašej integrácii, vrátane napríklad:
- Odoslané a prijaté faktúry
- Stav jednotlivých transakcií
- Podrobnosti o chybe a spätná väzba o overení
- Technické a obchodné časové značky
Protokol transakcií je užitočný pre:
- Tímy prvej línie podpory a prevádzkové tímy, ktoré nepracujú priamo s API
- Riešenie konkrétnych problémov nahlásených zákazníkmi alebo internými používateľmi
- Overenie, či sa zmeny vo vašej integrácii správajú podľa očakávaní vo výrobe
HTTP stavové kódy a protokol transakcií spoločne poskytujú ucelený obraz: váš systém môže programovo reagovať na odpovede, zatiaľ čo váš tím môže v prípade potreby priamo v Qvalia vyšetrovať a sledovať situáciu.
Viac ako faktúry: rozšírte svoje využitie rozhrania Peppol API
Akonáhle máte faktúry na mieste, je jednoduché rozšíriť integráciu na kompletné portfólio správ Peppol.
Typické rozšírenia zahŕňajú:
Objednávky. Prijímanie a odosielanie štruktúrovaných objednávok elektronicky
Odpovede na objednávky a zmeny. Potvrdzovanie, upravovanie alebo rušenie objednávok
Katalógy. Udržovanie informácií o produktoch a cenách v elektronických katalógoch
Oznámenia o odoslaní. Komunikácia informácií o zásielkach
Odpovede na úrovni správ. Sledovanie potvrdení na technickej a obchodnej úrovni
Vzhľadom na to, že všetky tieto funkcie využívajú rovnaký dizajn API, model overovania a dátový model UBL 2.1, nepotrebujete pre každý typ dokumentu samostatné projekty alebo brány. Nové prípady použitia môžete aktivovať v závislosti od vývoja vašej firmy alebo požiadaviek vašich zákazníkov.
Tu sa stáva hmatateľným sľub „jedno rozhranie Peppol API bez ohľadu na potreby“: tá istá integrácia slúži malým dodávateľom, veľkým podnikom aj komplexným platformovým scenárom.
Partner API pre fakturačný softvér a ERP systémy
Ak ste dodávateľom softvéru – prevádzkujete fakturačnú platformu, ERP, účtovné riešenie alebo integračnú platformu – vaše požiadavky sú trochu odlišné. S Partner API od Qvalia môžete nastaviť konfiguráciu pre viacerých používateľov na výmenu správ pre koncových používateľov, vrátane správy Peppol ID .
Partner API pre Peppol je potrebné, ak potrebujete:
- Obsluhujte mnoho koncových zákazníkov z jednej platformy
- Zachovajte jasné oddelenie údajov a transakcií jednotlivých zákazníkov.
- Vyhnite sa prevádzkovaniu vlastného prístupového bodu Peppol alebo brány EDI.
Model spoločnosti Qvalia zameraný na partnerstvo je navrhnutý špeciálne na tento účel.
Ako funguje nastavenie partnera
- Vaša spoločnosť je zaradená ako partner a dostane identifikačný kód partnera.
- Môžete si vybrať medzi dvoma spôsobmi spracovania správ koncových používateľov: 1) konsolidovaný zdieľaný používateľský účet alebo 2) individuálne účty Qvalia pre každého koncového používateľa, každý s vlastným číslom účtu (accountRegNo).
- API volania zahŕňajú kontext vášho partnera aj konkrétny zákaznícky účet, čo vám umožňuje odosielať a prijímať správy v ich mene.
Príklad: Implementácia partnera
Začlenenie
- Vaša organizácia dostane partnerské poverenia a konfiguráciu, vrátane partnerRegNo a API kľúča.
- Nastavíte jedinú integráciu smerom k API Qvalia pomocou
/partner/{partnerRegNo}predpona pre všetky volania v rámci partnera.
Zoznámenie zákazníka s vaším produktom
- Keď zákazník aktivuje Peppol/elektronickú fakturáciu vo vašom používateľskom rozhraní, pre daného zákazníka sa vytvorí alebo prepojí účet Qvalia.
- Číslo účtu zákazníka (accountRegNo) ukladáte spolu s vaším vlastným identifikačným číslom zákazníka, aby ste mohli riešiť transakcie podľa jednotlivých zákazníkov.
Odosielanie a prijímanie transakcií na zákazníka
Vaša aplikácia generuje alebo spotrebováva dáta UBL (faktúry, objednávky atď.) rovnakým spôsobom ako štandardné rozhranie API transakcií. Ak chcete odosielať alebo prijímať transakcie v mene konkrétneho zákazníka, voláte rozhranie API transakcií prostredníctvom vzoru URI s predponou partnera:
/partner/{partnerRegNo}/transaction/{accountRegNo}/{message-type}/{direction}Napríklad:
- Odoslanie odchádzajúcej faktúry:
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/outgoing(POST) - Načítanie prichádzajúcich faktúr:
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/incoming(GET) - Použitie
readvarianty, kde je to vhodné, pridanímreadna ceste.
Qvalia smeruje a prijíma správy tak, ako keby boli odoslané alebo prijaté priamo zákazníkom, s úplnou sledovateľnosťou podľa účtu.
Výhody pre dodávateľov softvéru
- Jedna technická integrácia, mnoho zákazníkov, využívanie konzistentného modelu partnerstva a účtov.
- Nie je potrebné prevádzkovať a udržiavať vlastnú sieť Peppol alebo EDI.
- Ľahké rozšírenie na nové trhy, mandáty a typy správ prostredníctvom opätovného použitia rovnakého vzoru integrácie partnerov.
Dodatočná funkcia: obohatenie umelou inteligenciou
Okrem dopravy a konektivity ponúka Qvalia aj rozširujúce rozhranie API, ktoré môže obohatiť transakcie o klasifikáciu položiek, spracovanie pred a po transakcii a ďalšie funkcie a ktoré dokáže s minimálnym úsilím extrahovať a transformovať dokumenty PDF na bohaté, štruktúrované a overené údaje.
Rozširujúce API je navrhnuté ako asynchrónna služba:
- Prostredníctvom API odošlete súbor s faktúrou (napr. PDF alebo XML).
- V odpovedi dostanete pollingId.
- Vykonávate kontrolu stavu, kým nie je obohatenie dokončené.
- Získate štruktúrovaný výsledok JSON s obohatenými informáciami.
Tento výsledok môže zahŕňať:
- Analyzovaný obsah faktúry extrahovaný z pôvodného súboru
- Overenie podľa Peppol alebo iných obchodných pravidiel
- Normalizované polia vhodné pre analytiku, automatizáciu a pracovné postupy umelej inteligencie
Vzor implementácie
Typická integrácia vyzerá takto:
Odošlite faktúru za obohatenie
Vyvolajte koncový bod, priložte súbor s faktúrou a všetky relevantné metadáta a
Uložte vrátené pollingId.
POST /enrichment/{accountRegNo}/invoicePrieskum o dokončení
Volajte v bezpečných intervaloch. Počas spracovania API potvrdzuje, že úloha stále beží. Po dokončení vráti stav a odkazy na výsledok obohatenia.
GET /enrichment/{accountRegNo}/{pollingId}Načítanie konkrétnych typov obohatenia
Vyvolajte na získanie konkrétneho výstupu obohatenia – napríklad podrobné údaje o faktúrach alebo výsledky validácie Peppol. Vložte to do svojho účtovného systému, analytického stacku alebo automatizačnej logiky.
GET /enrichment/{accountRegNo}/{pollingId}/{enrichmentType}Prípady použitia
- Malé podniky
Môžu ťažiť z inteligentného spracovania dokumentov na podnikovej úrovni; čisté, štruktúrované údaje bez investícií do zložitých nástrojov OCR alebo validácie. - Large
Môžu štandardizovať údaje z faktúr a dokumentov naprieč subjektmi, systémami a geografickými oblasťami a umožniť lepšiu kontrolu údajov, analýzu a automatizáciu účtovníctva. - Dodávatelia softvéru a partneri
Môžu integrovať pokročilé funkcie obohacovania priamo do svojich produktov bez nutnosti vytvárať vlastné parsingové a pravidlové moduly.
Vo všetkých prípadoch je prístup k tejto technológii jednoduchý: rovnaký účet a bezpečnostný model ako v prípade rozhrania API pre transakcie a malá sada jasne definovaných koncových bodov.
Prístup k rozhraniu Peppol API pre akúkoľvek firmu
API spoločnosti Qvalia je navrhnuté tak, aby vám poskytlo zjednodušený a škálovateľný prístup k sieti Peppol, bez ohľadu na typ vašej spoločnosti:
- Malá firma, ktorá potrebuje vymieňať elektronické faktúry v súlade s predpismi
- Veľký podnik spravujúci veľké objemy tokov viacerých subjektov
- Dodávateľ softvéru ponúkajúci fakturačné, ERP alebo finančné riešenia pre mnohých zákazníkov
Ďalší krok je jednoduchý: pripojte sa k sandboxu, odošlite svoju prvú testovaciu faktúru a začnite plánovať, ako sa Peppol, EDI a obohatenie môžu stať integrálnou súčasťou vašich operácií alebo produktu – namiesto samostatného, komplexného projektu.
