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.xml v 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.

  1. Príprava. Nainštalujte requests a nastavte svoje údaje. Kroky 2 až 6 vložte do súboru postman.py vedľa invoice.xml a spustite python3 postman.py (na Windowse python 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"
  2. Prihláste sa. Uvidíte Token OK. Token platí 15 minút, potom krok zopakujte.

    postman.py
    import 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")
  3. Odošlite faktúru. ACCEPTED = prijatá na doručenie, REJECTED = neodoslaná. Opakovanie s rovnakým Idempotency-Key ju 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"])
  4. 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"]
  5. Stiahnite faktúru do received.xml ako 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")
  6. 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.

JSON
{
  "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.