Spravovaný Connector pre ERP
Napojte svoj ERP systém do siete Peppol. Za jeden deň.
Sme jediný digitálny poštár na Slovensku, ktorý poskytuje jednoduchú "zásuvku" do siete Peppol pre ERP systémy
Prístup vytvárame manuálne po overení integrátora. Verejný self-service nie je dostupný.
Connector je nová odporúčaná cesta pre ERP. Existujúce SAPI a Enterprise API integrácie nemusia migrovať.
Najrýchlejší začiatok
Odošlite doklad, sledujte jeho stav a odpovedzte z jedného klienta.
Oficiálne SDK sa postará o prihlásenie a pri každom volaní vie, ku ktorej firme patrí doklad. Ak používate vlastného HTTP klienta, celý postup je zdokumentovaný. Stav môžete spoľahlivo kontrolovať pravidelne alebo si zapnúť okamžité upozornenia.
Odporúčané · TypeScript SDK
npm i @epostak/sdk
import { EPostak } from "@epostak/sdk";
const client = new EPostak({
clientId: process.env.EPOSTAK_CONNECTOR_CLIENT_ID!,
clientSecret: process.env.EPOSTAK_CONNECTOR_CLIENT_SECRET!,
baseUrl: "https://dev.epostak.sk/api/v1",
});
const customer = client.connector.customers.for("erp-acme");
const document = await customer.documents.send({
externalId: "invoice-2026-0042",
number: "2026-0042",
buyerReference: "OBJ-2026-0042",
recipient: { country: "SK", taxId: "2120123456" },
lines: [
{ description: "ERP service", quantity: 1, unitPrice: 100, vatRate: 23 },
],
});
const page = await customer.events.list({ limit: 100 });
for (const event of page.events) {
if (event.type === "document.received") {
await customer.documents.acknowledge(
event.documentId,
`erp:${event.documentId}`,
);
}
}
console.log(document.id, page.nextCursor);Rovnaký jednoduchý postup pre každú firmu je pripravený v šiestich SDK. TypeScript je na npm; Python, PHP, .NET, Java a Ruby sú dostupné ako zdrojový kód na GitHube.
Postup s vlastným HTTP klientom
1. POST /api/v1/auth/tokenPrihláste aplikáciu pridelenými údajmi. Získaný krátkodobý prístup používajte až do jeho expirácie.
2. POST /api/v1/connector/documentsPošlite ID zákazníka a dokladu, údaje faktúry a kľúč, ktorý zabráni duplicitnému vytvoreniu.
3. GET /api/v1/connector/eventsPravidelne čítajte zmeny stavu. Pozíciu poslednej spracovanej zmeny uložte až po úspešnom spracovaní v ERP.
4. POST …/{documentId}/acknowledge alebo /respondJedným volaním potvrdíte import do ERP, druhým odošlete rozhodnutie protistrane, napríklad {"status":"accepted"}.
ePošťák schváli integrátora, priradí firmy a zabezpečí ich Peppol registráciu. Po dokončení registrácie nastavíte každej firme vlastné stabilné ID zákazníka z ERP.
Od ERP po dôkaz
Vy dodáte doklad. Connector riadi doručenie.
ERP pozná svojho zákazníka a faktúru. Sieťové vyhľadanie, elektronický formát, kontrolu, frontu a obnovu po chybe preberá ePošťák.
Vaše ERP pošle
- ID zákazníka, ktoré už máte v ERP
- údaje faktúry v JSON
- IČO, DIČ, IČ DPH alebo Peppol ID, ak ho poznáte
ePošťák vybaví
- overí prístup k zákazníkovi
- nájde príjemcu a overí, či môže faktúru prijať
- zostaví a validuje e-faktúru
- zaradí odoslanie, opakuje pokus a obnoví stav
ERP dostane
- ID dokladu pre ďalšie volania
- zrozumiteľný stav dokladu
- udalosti, históriu a dôkazy
Vo väčšine prípadov stačí bežné firemné alebo daňové ID príjemcu. Peppol ID zadáte iba vtedy, keď ho už poznáte.
Čo pošlete a čo dostanete
Pošlete údaje faktúry. Dostanete jedno ID a jasný ďalší krok.
ID zákazníka prepojí doklad so správnou schválenou firmou. Ak rovnaké odoslanie po výpadku zopakujete, Connector nevytvorí duplicitný doklad.
POST /api/v1/connector/documents
Authorization: Bearer <token>
Idempotency-Key: erp-acme:invoice:2026-0042
{
"customerRef": "erp-acme",
"externalId": "invoice-2026-0042",
"number": "2026-0042",
"recipient": {
"country": "SK",
"taxId": "2120123456"
},
"lines": [{
"description": "Mesačná licencia",
"quantity": 1,
"unitPrice": 100,
"vatRate": 23
}]
}{
"id": "8e4b8f0e-21d3-4d2a-9c2b-24a3f8a0c111",
"customerRef": "erp-acme",
"externalId": "invoice-2026-0042",
"state": "queued",
"replayed": false,
"links": {
"self": "/api/v1/connector/documents/8e4b…",
"evidence": "/api/v1/connector/documents/8e4b…/evidence"
}
}Odoslať teraz alebo neskôr
Doklad môžete hneď odoslať alebo ho iba pripraviť. V odpovedi vždy uvidíte, či ho ešte môžete odoslať alebo zrušiť.
Bezpečné opakovanie
Ak spojenie vypadne, zopakujte rovnaké odoslanie s rovnakým kľúčom. Connector vráti ten istý doklad a nevytvorí duplikát.
Jedno ID počas celého spracovania
Rovnaké ID dokladu použijete počas čakania, odosielania, doručenia, čítania zmien aj získania dôkazov.
Od odoslania po potvrdenie
ERP vždy vie, čo sa s dokladom deje a čo môže urobiť ďalej.
Doklad vytvoríte raz. Potom čítate jeho stav, použijete ponúknutú akciu a prijmete zmeny pravidelnou kontrolou alebo okamžitým upozornením.
Vytvoriť alebo vypísať
POST /api/v1/connector/documents · GET /api/v1/connector/documentsPošlete údaje faktúry. Rovnaká cesta vám vráti zoznam dokladov zvolenej firmy.
Načítať detail
GET /api/v1/connector/documents/{documentId}Vráti aktuálny stav a iba tie akcie, ktoré sú v tej chvíli bezpečné.
Odoslať alebo zrušiť pripravený doklad
POST …/{documentId}/send · POST …/{documentId}/cancelERP nemusí poznať vlastné pravidlá; použije odoslanie alebo zrušenie, ktoré ponúkne detail dokladu.
Čítať zmeny
GET /api/v1/connector/eventsZmeny prinášajú stav odoslaných aj prijatých dokladov. Poslednú pozíciu uložte až po úspešnom spracovaní v ERP.
Prijímať zmeny okamžite
PUT /api/v1/connector/webhook · POST /api/v1/connector/webhook/test · GET …/webhook/deliveries/{deliveryId}Voliteľné okamžité upozornenia nastavíte raz pre celý účet. Každá zmena uvedie, ktorej firmy sa týka. V debuggeri nájdete firmu cez customerRef, presné odoslané body, každý pokus, zrozumiteľnú príčinu a bezpečný replay.
Potvrdiť spracovanie
POST /api/v1/connector/documents/{documentId}/acknowledgeERP môže potvrdenie bezpečne zopakovať. Potvrdí tým iba vlastný import prijatého dokladu; protistrane sa nič neposiela.
Odpovedať protistrane
POST /api/v1/connector/documents/{documentId}/respond?customerRef=...Telo {"status":"accepted"} odošle odpoveď protistrane. Dostupné stavy: received, in_process, under_query, conditionally_accepted, rejected, accepted a paid.
Odoslať teraz alebo neskôr
Doklad môžete hneď odoslať alebo iba pripraviť na neskôr. Odpoveď vždy ukáže, či je dostupné odoslanie alebo zrušenie.
Bezpečné opakovanie po výpadku
Po prerušení zopakujete rovnaké odoslanie. Connector vráti pôvodný doklad, takže ERP nemusí hádať, či vznikol duplikát.
Pravidelná kontrola alebo okamžité upozornenie
Stav môžete pravidelne kontrolovať alebo si zapnúť okamžité upozornenia. Pravidelná kontrola zostáva spoľahlivým zdrojom po výpadku.
Čo si ERP potrebuje pamätať
Päť údajov stačí na odoslanie, príjem aj dohľadanie dokladu.
Peppol identifikátory a sieťové pravidlá rieši ePošťák. Vo svojom kóde pracujete s údajmi zákazníka, dokladu, stavom a dostupnými akciami.
ID zákazníka v ERPPošlete ID, ktoré už pre firmu používate v ERP. Nastavíte ho v Integrátorskom portáli; po prvom použití zostáva uzamknuté.
Údaje príjemcuV recipient pošlete krajinu a IČO, DIČ alebo IČ DPH. Presné Peppol ID je voliteľné.
ID dokladuRovnaké ID použijete pre detail, zmeny stavu, podporu aj dôkazy.
Stav dokladuJasný stav povie, či doklad čaká, odosiela sa, je doručený alebo potrebuje pozornosť.
Dostupné akcieConnector ponúkne iba bezpečné akcie, ktoré môžete v danom stave vykonať. Medzi nimi je aj samostatná odpoveď na prijatú faktúru.
Jednoduchšia integrácia
Začnete jedným dokladom a pokračujete podľa jeho stavu.
ERP odošle faktúru, dostane jej ID a pri každom ďalšom kroku vidí, čo môže bezpečne urobiť. Nemusí skladať samostatné postupy pre odoslanie, príjem a obnovu po chybe.
| Oblasť | Predtým bolo treba skladať viac krokov | Teraz vás vedie jeden doklad |
|---|---|---|
| Kde začať | Pri každej fáze bolo treba vybrať správnu technickú operáciu. | Pošlete doklad a ďalšie bezpečné akcie dostanete priamo v odpovedi. |
| Identita príjemcu | ERP muselo poznať sieťové a adresovacie detaily. | Zadáte krajinu a bežné IČO, DIČ alebo IČ DPH príjemcu. |
| Odoslanie neskôr | Fronta a jej akcie sa implementovali ako samostatný postup. | Pri doklade zvolíte odoslať teraz alebo pripraviť na neskôr. |
| Obnova po chybe | ERP muselo samo spájať výsledky s opakovanými pokusmi. | Opakované volanie vráti ten istý doklad a nevytvorí duplikát. |
| Stav a príjem | Stav, prijaté doklady a synchronizácia mali rozdielne postupy. | Na jednom mieste čítate stav, prijaté doklady, potvrdenie aj odpoveď protistrane. |
Pokročilé možnosti zostávajú dostupné, ale na bežné odoslanie, príjem a získanie dôkazov ich nemusíte implementovať.
Bez zásahu do existujúcich integrácií
Nový Connector môžete nasadiť bez zmien v SAPI a Enterprise API.
Existujúce integrácie na SAPI, Enterprise API aj staršom Connectore pokračujú rovnako. Nový Connector je jednoduchšia voľba pre nové ERP napojenia; súčasné volania, hlavičky ani prihlásenie nemusíte meniť.
Connector
Odporúčaná cesta pre nové ERP integrácie, ktoré nechcú riešiť formáty, adresovanie a pravidlá Peppol.
Enterprise API
Pre tímy, ktoré potrebujú riadiť jednotlivé operácie, viac firiem a vlastný postup spracovania.
SAPI
Štandardizovaný kontrakt ostáva dostupný pre existujúcich testerov a integrácie, ktoré potrebujú kompatibilitu so SAPI-SK.
Voliteľné nástroje
Základné odosielanie funguje aj bez ďalších nástrojov.
Na bežnú integráciu stačí odoslať doklad a čítať jeho zmeny. Mapper a balík pre podporu použite iba vtedy, keď riešia konkrétny problém.
Mapper
Ak ERP nevie vytvoriť odporúčaný formát, Mapper preloží jeho JSON, CSV, XML alebo extrakt faktúry. Výsledok potom odošlete rovnakým spôsobom ako bežný doklad.
POST /api/v1/connector/mapperBalík pre podporu a dôkazy
Pri diagnostike alebo audite získate technický balík a doručovacie dôkazy pre konkrétny doklad bez rozširovania základného ERP modelu.
GET /api/v1/connector/documents/{documentId}/support-packetManuálne overený prístup
Sandbox pripravíme po krátkom overení integrátora.
Nevytvárame verejný self-service ani automaticky nevydávame identity. Chránime tak produkčné dáta, zákaznícke väzby aj dôveru v integrátorský program.
info@epostak.sk · odpovedáme na konkrétny integračný zámer
- 01
Napíšte nám
Uveďte firmu, produkt alebo účel integrácie a meno aj e-mail technického kontaktu.
- 02
Prístup vytvorí operátor
Po overení pripravíme oddelený sandbox, prihlasovacie údaje a schválené firmy vrátane ich Peppol registrácie.
- 03
Prepojíte ID zákazníkov
Po dokončení Peppol registrácie priradíte každej schválenej firme ID, ktoré už používate v ERP. Connector podľa neho vždy vyberie správnu firmu.
- 04
Overíme celý tok
Otestujete odoslanie, sledovanie stavu, príjem, potvrdenie aj odpoveď protistrane. Produkčný go-live schvaľujeme osobitne.