Dokumenty
Faktury a dobropisy
Plus vlastní fakturace a odpovědi na faktury
Formáty
JSON nebo UBL XML
Na základě UBL 2.1, jeden dokument na jeden požadavek
Události
Podepsané webhooky
Přijato, doručeno, zpožděno a neúspěšné
Dostupnost
99,8 % za měsíc
Smluvní, s kreditními body za služby
Odeslat fakturu s jednou žádostí
Fakturu odešlete ve formátu JSON nebo UBL XML na odchozí koncový bod vašeho účtu. Qvalia ji ověří, vyhledá příjemce v systému Peppol a doručí ji. Stejným způsobem se postupuje i u dobropisů, dokumentů vlastní fakturace a odpovědí na faktury.
- Testovací prostředí na adrese api-test.qvalia.com, produkční prostředí na adrese api.qvalia.com
- API klíč v hlavičce Authorization nebo token s krátkou platností (JWT)
- Záhlaví „Idempotency-Key“ zajišťuje bezpečnost opakovaných pokusů
● ● ●
Žádost v Sandboxu: zaslat fakturu
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.jsonJak se faktura zpracovává prostřednictvím API
Váš systém využívá jedno API. Společnost Qvalia za ním provozuje přístupový bod Peppol.
1. Odeslat
Na jeden požadavek odešlete jeden dokument. Pokud jsou údaje neplatné nebo pokud příjemce není pro daný typ dokumentu zaregistrován a není nakonfigurován žádný jiný kanál doručení, API před odesláním jakýchkoli dat vrátí stabilní chybový kód 422.
2. Ověřit a doručit
Qvalia porovná dokument s platnými pravidly Peppol, vyhledá přístupový bod příjemce a doručí dokument prostřednictvím AS4.
3. Sledujte stav
Webhooky informují o doručení, probíhajících opakovaných pokusech a selháních. Koncový bod pro stav vrací nejnovější stav každého dokumentu bez obsahu dokumentu.
4. Přijmout
Příchozí faktury a odpovědi čekají na příchozích koncových bodech. Koncový bod pro čtení vrací nepřečtené dokumenty a označí je jako přečtené, takže další volání vrátí pouze nové dokumenty.
Fakturační dokumenty a koncové body
Každá cesta začíná /transaction/{accountRegNo}, registrační číslo vašeho účtu. Každý typ dokumentu má koncové body pro odesílání a přijímání, koncový bod pro čtení nepřečtených dokumentů a koncový bod pro stav.
| Dokument | Koncový bod | Specifikace Peppol |
| Faktura | /invoices | Peppol BIS Billing .0 |
| Dobropis | /creditnotes | Peppol BIS Billing .0 |
| Faktura na základě vlastního vyúčtování | /selfbillinginvoices | Peppol BIS – vlastní fakturace |
| Kreditní doklad na základě vlastní fakturace | /selfbillingcreditnotes | Peppol BIS – vlastní fakturace |
| Odpověď na fakturu | /invoiceresponses | BIS Invoice Response Peppol BIS Invoice Response |
| Odpověď na úrovni zprávy | /messagelevelresponses | BIS Message Level Response Peppol BIS Message Level Response |
To, jaké typy dokumentů váš účet používá, závisí na službě a tarifu. Schémata požadavků a odpovědí najdete v referenčních materiálech k rozhraní API pro faktury a k rozhraní API pro dobropisy. Informace o všech rozhraních API služby Qvalia najdete v části „Rozhraní API Peppol a nástroje pro vývojáře“.
Před odesláním zkontrolujte příjemce
Než fakturu odešlete, vyhledejte si identifikační kód účastníka ( Peppol ID ). Odpověď ukáže, zda je účastník registrován v síti Peppol a jaké typy dokumentů může přijímat, takže váš systém může upozornit na chybějící nebo nesprávný identifikační kód ještě předtím, než síť fakturu odmítne.
- Omezte kontrolu na jeden typ dokumentu pomocí
docTypeRoot, napříkladInvoiceneboCreditNote - Peppol ID je název programu a identifikátor, například
0007:1234567890 - Stejné základní URL adresy a ověřování jako u rozhraní Transaction API
● ● ●
Žádost v testovacím prostředí: vyhledání příjemce
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"Vytvořeno pro integraci do výrobních procesů
Podrobnosti, které rozhodují o tom, zda integrace obstojí při velkém objemu, jsou všechny popsány v referenční příručce k API.
- Bezpečné opakované pokusy
Odešlete klíč idempotence a při opakovaném požadavku se vrátí původní odpověď namísto vytvoření druhé faktury. - Podepsané webhooky
Každá událost obsahuje ID události a, jakmile nastavíte podpisový klíč, také podpis, který můžete ověřit. - Záznam událostí po dobu 30 dnů
Jakoukoli doručenou událost můžete znovu načíst podle jejího ID, například po výpadku na vaší straně. - Stav bez obsahu
Provádějte hromadné odsouhlasení pomocí jednoduchých záznamů o stavu, filtrovaných podle data, ID dokumentu nebo času aktualizace. - Vymazání limitů frekvence
Limity se počítají na jeden účet a odpověď 429 vám sdělí, jak dlouho musíte počkat. - Přílohy
Do zprávy přidejte soubory PDF a obrázky. Celá žádost, včetně příloh a kódování Base64, nesmí překročit limit 100 MB stanovený standardem Peppol.
Jedna faktura, formát, který vyhovuje každému příjemci
Fakturu odešlete jednou. Qvalia ji ověří, vyhledá příjemce a doručí ji v síti Peppol ve formátu Peppol BIS Billing 3.0 nebo Peppol PINT. Pokud příjemce není připojen k síti Peppol, může Qvalia doručit fakturu prostřednictvím EDI, jako soubor PDF e-mailem, v tištěné podobě nebo do internetových bank B2C na vybraných trzích. Jedná se o doplňkové kanály doručení, nikoli o specifikace Peppol. Podívejte se, jaké formáty obchodních zpráv Qvalia podporuje.
Pokud váš systém nedokáže generovat faktury ve formátu Peppol BIS, nahrajte fakturu v tom formátu, v jakém ji již vytváří: Svefaktura 1.0, EDIFACT INVOIC, cXML, Finvoice 3.0, XRechnung, CII nebo XML ve formátech ZUGFeRD a Factur-X. Qvalia ji převede do formátu Peppol BIS Billing 3.0, ověří její správnost a odešle ji. Viz odesílání faktur ve vašem stávajícím formátu.
Vyberte si výchozí bod
Softwarové platformy
Integrovaný Peppol
Nabídněte svým zákazníkům elektronickou fakturaci. Partner API jim vytvoří účty a identifikátory Peppol a Invoicing API zajistí přenos jejich dokumentů.
Týmy ERP a financí
Přístupový bod Peppol
Propojte svůj ERP systém nebo finanční systém se službou Peppol prostřednictvím API, SFTP nebo hotového konektoru.
Vývojáři
Průvodce rychlým spuštěním
Postupujte krok za krokem od API klíče až po svou první fakturu v testovacím prostředí, včetně příkladů požadavků.
Často kladené otázky k API pro fakturaci
Co je to API pro elektronickou fakturaci?
API pro elektronickou fakturaci umožňuje vašemu softwaru odesílat a přijímat strukturované elektronické faktury, aniž by bylo nutné navazovat síťové připojení. Díky fakturačnímu API společnosti Qvalia váš systém odesílá faktury ve formátu JSON nebo UBL XML a společnost Qvalia je ověřuje a doručuje prostřednictvím sítě Peppol.
Jaké fakturační doklady mohu odesílat a přijímat?
Faktury, dobropisy, faktury a dobropisy na základě vlastního vyúčtování a odpovědi na faktury, přičemž u každého z nich existují koncové body pro odesílání i přijímání. To, jaké typy dokumentů váš účet využívá, závisí na službě a tarifu.
Musím znát systém Peppol BIS, abych mohl používat toto API?
Vaše dokumenty jsou v souladu se specifikací Peppol BIS Billing 3.0 a jsou ve formátu JSON nebo XML založeném na UBL 2.1. Ukázková data na api.qvalia.io obsahují kompletní fakturu a chyby při ověřování odkazují na pravidlo, podle kterého je třeba dokument opravit. Viz článek Jak funguje ověřování Peppol.
Je tam pískoviště?
Ano. Sandbox na adrese api-test.qvalia.com používá vlastní klíč API, takže můžete provádět testy na svých vlastních systémech, aniž by to mělo dopad na skutečné zákazníky. Přístup k API a sandboxu je zahrnut v rámci tarifu Connect „ Medium “.
Jak mohu zabránit tomu, abych odeslal stejnou fakturu dvakrát?
Při každém odeslání přiložte hlavičku „Idempotency-Key“. Pokud požadavek zopakujete, například po uplynutí časového limitu, API vrátí původní odpověď, místo aby vytvořilo druhý dokument. Nové odeslání se stejným ID dokumentu a příjemcem vrátí stavovou chybu 409 Conflict, pokud se nerozhodnete dokument přepsat.
Jak poznám, že byla faktura doručena?
Přihlaste se k odběru webhooků pro události doručení a chyby, nebo načtěte stavový koncový bod. Webhook, který váš koncový bod nepřijme, se již znovu neodesílá, proto jako bezpečnostní opatření provádějte pravidelnou kontrolu stavu. Jakoukoli doručenou událost lze znovu načíst po dobu 30 dnů.
Jak mohu přijímat příchozí faktury?
Přihlaste se k odběru webhooku pro nové dokumenty a poté načtěte fakturu z koncového bodu pro příchozí data. Koncový bod pro čtení vrátí nepřečtené faktury a označí je jako přečtené.
Kolik stojí rozhraní API pro fakturaci?
Přístup k API je zahrnut v tarifu Connect „ Medium “. Ceny pro partnery a podniky závisí na objemu a modelu poskytování služeb. Viz Tarify a ceny.
