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ý.

Vývojári pripájajú ERP systém cez ePošťák Connector k elektronickému doručovaniu
01ERP pošle bežné údaje faktúry
02ePošťák vybaví formát, kontrolu aj doručenie
03Zákazníka označíte ID, ktoré už používate

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

Otvoriť všetkých 6 SDK na GitHube
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. 1. POST /api/v1/auth/token

    Prihláste aplikáciu pridelenými údajmi. Získaný krátkodobý prístup používajte až do jeho expirácie.

  2. 2. POST /api/v1/connector/documents

    Pošlite ID zákazníka a dokladu, údaje faktúry a kľúč, ktorý zabráni duplicitnému vytvoreniu.

  3. 3. GET /api/v1/connector/events

    Pravidelne čítajte zmeny stavu. Pozíciu poslednej spracovanej zmeny uložte až po úspešnom spracovaní v ERP.

  4. 4. POST …/{documentId}/acknowledge alebo /respond

    Jedný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í

  1. overí prístup k zákazníkovi
  2. nájde príjemcu a overí, či môže faktúru prijať
  3. zostaví a validuje e-faktúru
  4. 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.

Údaje z ERP
Bežné účtovné údaje
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
  }]
}
Odpoveď ePošťáka
201 Created
{
  "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"
  }
}
ID dokladu a povolené akcie
01

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ť.

02

Bezpečné opakovanie

Ak spojenie vypadne, zopakujte rovnaké odoslanie s rovnakým kľúčom. Connector vráti ten istý doklad a nevytvorí duplikát.

03

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.

01
documents

Vytvoriť alebo vypísať

POST /api/v1/connector/documents · GET /api/v1/connector/documents

Pošlete údaje faktúry. Rovnaká cesta vám vráti zoznam dokladov zvolenej firmy.

02
detail

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é.

03
dostupné akcie

Odoslať alebo zrušiť pripravený doklad

POST …/{documentId}/send · POST …/{documentId}/cancel

ERP nemusí poznať vlastné pravidlá; použije odoslanie alebo zrušenie, ktoré ponúkne detail dokladu.

04
zmeny stavu

Čítať zmeny

GET /api/v1/connector/events

Zmeny prinášajú stav odoslaných aj prijatých dokladov. Poslednú pozíciu uložte až po úspešnom spracovaní v ERP.

05
okamžité upozornenia

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.

06
acknowledge

Potvrdiť spracovanie

POST /api/v1/connector/documents/{documentId}/acknowledge

ERP môže potvrdenie bezpečne zopakovať. Potvrdí tým iba vlastný import prijatého dokladu; protistrane sa nič neposiela.

07
respond

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 ERP

Poš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íjemcu

V recipient pošlete krajinu a IČO, DIČ alebo IČ DPH. Presné Peppol ID je voliteľné.

ID dokladu

Rovnaké ID použijete pre detail, zmeny stavu, podporu aj dôkazy.

Stav dokladu

Jasný stav povie, či doklad čaká, odosiela sa, je doručený alebo potrebuje pozornosť.

Dostupné akcie

Connector 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 krokovTeraz 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íjemcuERP muselo poznať sieťové a adresovacie detaily.Zadáte krajinu a bežné IČO, DIČ alebo IČ DPH príjemcu.
Odoslanie neskôrFronta a jej akcie sa implementovali ako samostatný postup.Pri doklade zvolíte odoslať teraz alebo pripraviť na neskôr.
Obnova po chybeERP muselo samo spájať výsledky s opakovanými pokusmi.Opakované volanie vráti ten istý doklad a nevytvorí duplikát.
Stav a príjemStav, 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/mapper

Balí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-packet

Manuá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

  1. 01

    Napíšte nám

    Uveďte firmu, produkt alebo účel integrácie a meno aj e-mail technického kontaktu.

  2. 02

    Prístup vytvorí operátor

    Po overení pripravíme oddelený sandbox, prihlasovacie údaje a schválené firmy vrátane ich Peppol registrácie.

  3. 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.

  4. 04

    Overíme celý tok

    Otestujete odoslanie, sledovanie stavu, príjem, potvrdenie aj odpoveď protistrane. Produkčný go-live schvaľujeme osobitne.