SDK
Prepojte svoj softvér s Digitálnou Poštárkou
Odosielajte a prijímajte e-faktúry cez Peppol priamo zo svojho softvéru. Stačí HTTPS a JSON podľa štandardu SAPI-SK.
Čo budete potrebovať
- Client ID a Secret: Nastavenia profilu → API prístupy → Generovať prístupy. Secret sa zobrazí iba raz. Ak už prístupy máte, použite ich: nové zneplatnia staré.
- Peppol ID firmy (
0245:+ DIČ): Zmeniť subjekt → Upraviť → PEPPOL ID. - Faktúru
invoice.xmlv UBL (EN 16931, CIUS-SK, max. 10 MB), kde predávajúcim je vaša firma. - Nástroje podľa kroku 1.
Rýchly štart
Vyberte jazyk a postupujte krok za krokom.
Príprava. Nainštalujte
requestsa nastavte svoje údaje. Kroky 2 až 6 vložte do súborupostman.pyvedľainvoice.xmla spustitepython3 postman.py(na Windowsepython postman.py) v tom istom okne.macOS / Linux# Install the requests library python3 -m pip install requests # Your details (replace these) export CLIENT_ID="YOUR_CLIENT_ID" export CLIENT_SECRET="YOUR_CLIENT_SECRET" export PEPPOL_ID="0245:1234512345"Windows (PowerShell)# Install the requests library python -m pip install requests # Your details (replace these) $env:CLIENT_ID = "YOUR_CLIENT_ID" $env:CLIENT_SECRET = "YOUR_CLIENT_SECRET" $env:PEPPOL_ID = "0245:1234512345"Prihláste sa. Uvidíte
Token OK. Token platí 15 minút, potom krok zopakujte.postman.pyimport os, uuid, requests API = "https://api.digitalnapostarka.sk/api/v1" # Call the API; stop with the server's message on any error def api(method, path, **kwargs): r = requests.request(method, API + path, timeout=30, **kwargs) if not r.ok: raise SystemExit(f"Error {r.status_code}: {r.text}") return r.json() # Sign in with your details auth = api("POST", "/auth/token", json={ "grant_type": "client_credentials", "client_id": os.environ["CLIENT_ID"], "client_secret": os.environ["CLIENT_SECRET"], }) # Headers for every invoice request headers = { "Authorization": f"Bearer {auth['access_token']}", "X-Peppol-Participant-Id": os.environ["PEPPOL_ID"], } print("Token OK")Odošlite faktúru.
ACCEPTED= prijatá na doručenie,REJECTED= neodoslaná. Opakovanie s rovnakýmIdempotency-Keyju druhýkrát neodošle.Odoslanie je ostré
Faktúra naozaj odíde príjemcovi. Posielajte iba tú, ktorú chcete doručiť.
postman.py# Read invoice.xml with open("invoice.xml", encoding="utf-8") as f: xml = f.read() # Same file, same key: running the script again never sends the invoice twice key = str(uuid.uuid5(uuid.NAMESPACE_URL, xml)) # Send it and show the result sent = api("POST", "/document/send", json={"payload": xml}, headers={**headers, "Idempotency-Key": key}) print(sent["status"], sent["providerDocumentId"])Pozrite si prijaté faktúry. Nepotvrdené, najstaršie prvé, max. 100 na stránku (ďalšia cez
pageToken). ID prvej sa použije v ďalších krokoch. Prázdny zoznam znamená, že zatiaľ nič neprišlo: tu skončite.postman.py# Get the received invoices you haven't acknowledged yet page = api("GET", "/document/receive", params={"status": "RECEIVED"}, headers=headers) for doc in page["documents"]: print(doc["documentId"], "from", doc["senderParticipantId"]) if not page["documents"]: raise SystemExit("No new invoices yet.") # Keep the first invoice's ID for the next steps document_id = page["documents"][0]["documentId"]Stiahnite faktúru do
received.xmlako pôvodné UBL XML.postman.py# Download the invoice and save it as received.xml doc = api("GET", f"/document/receive/{document_id}", headers=headers) with open("received.xml", "w", encoding="utf-8") as f: f.write(doc["payload"]) print("Saved received.xml")Potvrďte prevzatie, až keď je faktúra uložená u vás. Potom sa už medzi nepotvrdenými nezobrazí.
postman.py# Confirm the invoice is stored on your side api("POST", f"/document/receive/{document_id}/acknowledge", headers=headers) print("Acknowledged", document_id)
Hotovo. V integrácii opakujte kroky 4 až 6 pravidelne, napr. každých pár minút, a to pre každú faktúru v zozname.
Chyby
Všetky chyby majú tento tvar. retryable povie, či zopakovať, correlation_id nám pošlite pri riešení problému.
{
"error": {
"category": "VALIDATION",
"code": "idempotency_key_conflict",
"message": "Idempotency-Key was already used with a different payload",
"retryable": false,
"correlation_id": "550e8400-e29b-41d4-a716-446655440000"
}
}Chcete sa na faktúry len pýtať AI, napr. Claude či ChatGPT? Použite MCP server.



