Dokumenty
Faktúry a dobropisy
Plus samostatné fakturovanie a odpovede na faktúry
Formáty
JSON alebo UBL XML
Na základe UBL 2.1, jeden dokument na jednu požiadavku
Podujatia
Podpísané webhooky
Prijaté, doručené, oneskorené a neúspešné
Dostupnosť
99,8 % za mesiac
Zmluvné, s kreditmi za služby
Odoslať faktúru s jednou žiadosťou
Faktúru odošlite vo formáte JSON alebo UBL XML na odosielací koncový bod vášho účtu. Qvalia ju overí, vyhľadá príjemcu v systéme Peppol a doručí ju. Rovnaký postup platí aj pre dobropisy, dokumenty o samofakturácii a odpovede na faktúry.
- Testovacie prostredie na adrese api-test.qvalia.com, produkčné prostredie na adrese api.qvalia.com
- API kľúč v hlavičke „Authorization“ alebo token s krátkou platnosťou (JWT)
- Hlavička „Idempotency-Key“ zabezpečuje bezpečnosť opakovaných pokusov
● ● ●
Žiadosť v Sandboxe: zaslať faktúru
curl -X POST \
"https://api-test.qvalia.com/transaction/$ACCOUNT_REG_NO/invoices/outgoing" \
-H "Authorization: $QVALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @invoice.jsonAko prebieha spracovanie faktúry prostredníctvom API
Váš systém funguje prostredníctvom jedného rozhrania API. Spoločnosť Qvalia prevádzkuje prístupový bod Peppol, ktorý za ním stojí.
1. Odoslať
Na jednu požiadavku odošlite jeden dokument. Ak sú údaje neplatné alebo ak príjemca nie je zaregistrovaný pre daný typ dokumentu a nie je nakonfigurovaný žiadny iný kanál doručenia, rozhranie API vráti stabilný chybový kód 422 ešte pred odoslaním akýchkoľvek údajov.
2. Overiť a odovzdať
Qvalia overí súlad dokumentu s platnými pravidlami Peppol, vyhľadá prístupový bod príjemcu a doručí dokument prostredníctvom AS4.
3. Sledujte stav
Webhooky informujú o doručení, prebiehajúcich opakovaných pokusoch a zlyhaniach. Koncový bod stavu vráti najnovší stav každého dokumentu bez obsahu dokumentu.
4. Prijímať
Prichádzajúce faktúry a odpovede čakajú na prichádzajúcich koncových bodoch. Koncový bod na čítanie vráti neprečítané dokumenty a označí ich ako prečítané, takže nasledujúce volanie vráti len nové dokumenty.
Fakturačné dokumenty a koncové body
Každá cesta začína /transaction/{accountRegNo}, registračné číslo vášho účtu. Každý typ dokumentu má koncové body pre odosielanie a prijímanie, koncový bod na čítanie neprečítaných dokumentov a koncový bod pre stav.
| Dokument | Koncový bod | Špecifikácia Peppol |
| Faktúra | /invoices | Peppol BIS Billing .0 |
| Dobropis | /creditnotes | Peppol BIS Billing .0 |
| Faktúra na základe vlastného vyúčtovania | /selfbillinginvoices | Peppol BIS – Samostatné fakturovanie |
| Kreditná nota na základe vlastnej fakturácie | /selfbillingcreditnotes | Peppol BIS – Samostatné fakturovanie |
| Odpoveď na faktúru | /invoiceresponses | BIS Invoice Response Peppol BIS Invoice Response |
| Odpoveď na úrovni správy | /messagelevelresponses | BIS Message Level Response Peppol BIS Message Level Response |
To, aké typy dokumentov váš účet používa, závisí od služby a tarifného plánu. Schémy požiadaviek a odpovedí nájdete v referenčných materiáloch k rozhraniu API pre faktúry a rozhraniu API pre dobropisy. Informácie o všetkých rozhraniach API spoločnosti Qvalia nájdete v časti Rozhrania API Peppol a vývojárske nástroje.
Pred odoslaním skontrolujte príjemcu
Pred odoslaním faktúry si vyhľadajte informácie o identifikácii účastníka ( Peppol ID ). Odpoveď ukáže, či je účastník zaregistrovaný v sieti Peppol a aké typy dokumentov môže prijímať, takže váš systém môže upozorniť na chýbajúce alebo nesprávne ID ešte predtým, ako sieť faktúru odmietne.
- Obmedzte kontrolu na jeden typ dokumentu pomocou
docTypeRoot, napríkladInvoicealeboCreditNote - Peppol ID je názov programu a identifikátor, napríklad
0007:1234567890 - Rovnaké základné URL adresy a overovanie ako v prípade rozhrania Transaction API
● ● ●
Žiadosť v testovacom prostredí: vyhľadanie príjemcu
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"Vytvorené pre integráciu do výrobných procesov
Podrobnosti, ktoré rozhodujú o tom, či integrácia funguje aj pri veľkom objeme, sú všetky zdokumentované v referenčnej príručke k API.
- Bezpečné opakované pokusy
Po odoslaní idempotentného kľúča opakovaná žiadosť vráti pôvodnú odpoveď namiesto vytvorenia druhej faktúry. - Podpísané webhooky
Každá udalosť obsahuje ID udalosti a po nastavení tajného kľúča na podpis aj podpis, ktorý môžete overiť. - Záznam udalosti po dobu 30 dní
Akékoľvek doručené udalosť si môžete znovu vyvolať podľa jej ID, napríklad po výpadku na vašej strane. - Stav bez obsahu
Zosúlaďte veľké objemy údajov pomocou jednoduchých záznamov o stave, filtrovaných podľa dátumu, ID dokumentu alebo času aktualizácie. - Vymazať limity frekvencie
Limity sa počítajú na jeden účet a odpoveď 429 vám oznámi, ako dlho máte čakať. - Prílohy
Do správy pridajte súbory PDF a obrázky. Celá žiadosť vrátane príloh a kódovania Base64 nesmie prekročiť limit 100 MB stanovený organizáciou Peppol.
Jedna faktúra, formát, ktorý vyhovuje každému príjemcovi
Faktúru zašlite raz. Spoločnosť Qvalia ju overí, vyhľadá príjemcu a doručí ju prostredníctvom siete Peppol vo formáte Peppol BIS Billing 3.0 alebo Peppol PINT. Ak príjemca nie je pripojený k sieti Peppol, spoločnosť Qvalia môže faktúru doručiť prostredníctvom EDI, vo formáte PDF e-mailom, v tlačenej podobe alebo cez internetové bankovníctvo B2C na vybraných trhoch. Ide o doplnkové kanály doručenia, nie o špecifikácie Peppol. Zistite, ktoré formáty obchodných správ spoločnosť Qvalia podporuje.
Ak váš systém nedokáže vygenerovať faktúru vo formáte Peppol BIS, nahrajte faktúru v tom formáte, v akom ju systém už vytvára: Svefaktura 1.0, EDIFACT INVOIC, cXML, Finvoice 3.0, XRechnung, CII alebo XML vo formátoch ZUGFeRD a Factur-X. Qvalia ju prevedie do formátu Peppol BIS Billing 3.0, overí jej správnosť a odošle. Pozrite si čas ť o odosielaní faktúr vo vašom existujúcom formáte.
Vyberte si východiskový bod
Softvérové platformy
Integrovaný Peppol
Ponúknite svojim zákazníkom elektronickú fakturáciu. Partner API vytvorí ich účty a identifikátory Peppol a Invoicing API zabezpečí prenos ich dokumentov.
Tímy ERP a financií
Prístupový bod Peppol
Prepojte svoj ERP alebo finančný systém so systémom Peppol prostredníctvom API, SFTP alebo hotového konektora.
Vývojári
Stručný návod na začatie
Postupujte krok za krokom od API kľúča až po vašu prvú faktúru v testovacom prostredí, vrátane príkladov požiadaviek.
Často kladené otázky k fakturačnému rozhraniu API
Čo je to rozhranie API pre elektronickú fakturáciu?
API pre elektronickú fakturáciu umožňuje vášmu softvéru odosielať a prijímať štruktúrované elektronické faktúry bez toho, aby musel sám vytvárať sieťové pripojenie. Vďaka fakturačnému API spoločnosti Qvalia váš systém odosiela faktúry vo formáte JSON alebo UBL XML, pričom Qvalia ich overuje a doručuje prostredníctvom siete Peppol.
Aké fakturačné doklady môžem odosielať a prijímať?
Faktúry, dobropisy, faktúry a dobropisy na základe vlastnej fakturácie a odpovede na faktúry, pričom každý z nich má koncové body pre odchádzajúce a prichádzajúce údaje. To, aké typy dokumentov váš účet používa, závisí od služby a tarifného plánu.
Musím poznať systém Peppol BIS, aby som mohol používať toto API?
Vaše dokumenty sú v súlade so špecifikáciou Peppol BIS Billing 3.0, vo formáte JSON alebo XML založenom na UBL 2.1. Ukážkové údaje na stránke api.qvalia.io zobrazujú kompletnú faktúru a chyby validácie odkazujú na pravidlo, ktoré je potrebné opraviť. Pozrite si článok Ako funguje validácia Peppol.
Je tam pieskovisko?
Áno. Testovacie prostredie na adrese api-test.qvalia.com používa vlastný kľúč API, takže môžete testovať svoje vlastné systémy bez toho, aby to malo vplyv na skutočných zákazníkov. Prístup k API a testovaciemu prostrediu je zahrnutý v pláne Connect „ Medium “.
Ako môžem zabrániť tomu, aby som tú istú faktúru odoslal dvakrát?
Pri každom odoslaní pošlite hlavičku „Idempotency-Key“. Ak požiadavku zopakujete, napríklad po uplynutí časového limitu, rozhranie API vráti pôvodnú odpoveď namiesto vytvorenia druhého dokumentu. Nové odoslanie s rovnakým ID dokumentu a príjemcom vráti stav 409 Conflict, pokiaľ sa nerozhodnete dokument prepísať.
Ako zistím, či bola faktúra doručená?
Prihláste sa na odber webhookov pre udalosti doručenia a chyby alebo kontrolujte stav prostredníctvom koncového bodu. Webhook, ktorý váš koncový bod neprijme, sa už znovu neodosiela, preto ako bezpečnostnú poistku vykonávajte pravidelnú kontrolu stavu. Akúkoľvek doručenú udalosť je možné znovu načítať počas 30 dní.
Ako môžem prijímať prichádzajúce faktúry?
Prihláste sa na webhook pre nové dokumenty a následne načítajte faktúru z koncového bodu pre prichádzajúce údaje. Koncový bod na čítanie vráti neprečítané faktúry a označí ich ako prečítané.
Koľko stojí rozhranie API pre fakturáciu?
Prístup k API je zahrnutý v pláne Connect „ Medium “. Ceny pre partnerov a podniky závisia od objemu a modelu poskytovania. Pozrite si časť Plány a ceny.
