Preskočiť na obsah
PRE VÝVOJÁROV · SIMFA API V1

Faktúry z vlastného kódu. Sedia na cent.

REST API pre e-shopy, interné systémy a automatizácie. Faktúry, dobropisy, kontakty a objednávky s tými istými pravidlami ako v appke: DPH, číslovanie, e-faktúry aj limity odosielania.

OpenAPI 3.1
  • OpenAPI 3.1 a príklady v štyroch jazykoch
  • ceny s DPH sedia na cent so zaplatenou sumou
  • chyby po slovensky, idempotencia, stránkovanie kurzorom
RÝCHLY ŠTART

Prvá faktúra za 5 minút

  1. 01

    Založ kľúč

    V SimFa otvor Nastavenia, záložku Integrácie, a založ ostrý kľúč s oblasťami, ktoré integrácia potrebuje. Celý kľúč sa ukáže raz. Ulož si ho do premennej prostredia SIMFA_API_KEY, nie do kódu ani do repozitára.

    Otvoriť Integrácie v SimFa
  2. 02

    Over kľúč

    Firma kľúča odpovie údajmi a plánom. Kľúč s preklepom server odmietne hneď, s vetou, čo je zle.

    curl https://api.simfa.sk/v1/company \
  -H "Authorization: Bearer $SIMFA_API_KEY"
    200
    {
  "id": "cmf0firma00000000000000001",
  "object": "company",
  "name": "Stolárstvo Javor s.r.o.",
  "ico": "59123451",
  "dic": "2029123451",
  "ic_dph": "SK2029123451",
  "vat_payer": true,
  "street": "Hlavná 12",
  "city": "Žilina",
  "zip": "010 01",
  "country": "SK",
  "iban": "SK3112000000198742637541",
  "email": "[email protected]",
  "peppol_id": "9950:SK2029123451",
  "default_due_days": 14,
  "invoice_language": "SK",
  "plan": "premium",
  "sandbox": false
}
  3. 03

    Pošli objednávku

    Objednávka zaplatená kartou sa stane uhradenou faktúrou s cenami s DPH presne podľa e-shopu. Hlavička Idempotency-Key zaručí, že opakované odoslanie po výpadku siete nevystaví druhú.

    curl https://api.simfa.sk/v1/orders \
  -H "Authorization: Bearer $SIMFA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: woocommerce-1042" \
  -d '{
  "external_id": "1042",
  "source": "woocommerce",
  "currency": "EUR",
  "payment_method": "card",
  "paid": true,
  "paid_on": "2026-10-16",
  "customer": {
    "name": "Jana Kováčová",
    "email": "[email protected]",
    "street": "Mierová 5",
    "city": "Bratislava",
    "zip": "821 05",
    "country": "SK",
    "external_id": "77"
  },
  "lines": [
    {
      "external_id": "501",
      "name": "Dubová doska 120 x 40 cm",
      "quantity": 1,
      "unit_price": "51.00",
      "vat_rate": 23
    },
    {
      "external_id": "502",
      "name": "Kniha Stolárske spoje",
      "quantity": 1,
      "unit_price": "14.25",
      "vat_rate": 5
    }
  ],
  "total": "65.25"
}'
    201
    {
  "object": "order_result",
  "status": "paid",
  "document_type": "invoice",
  "issue_on": "now",
  "warnings": [],
  "invoice": {
    "id": "cmf0doklad0000000000000001",
    "object": "invoice",
    "type": "invoice",
    "number": "2026-0411",
    "status": "paid",
    "payment_status": "paid",
    "issue_date": "2026-10-16",
    "due_date": "2026-10-30",
    "delivery_date": "2026-10-16",
    "currency": "EUR",
    "exchange_rate": null,
    "exchange_rate_date": null,
    "prices_include_vat": true,
    "vat_payer": true,
    "tax_regime": "standard",
    "customer": {
      "contact_id": "cmf0kontakt000000000000001",
      "name": "Jana Kováčová",
      "ico": null,
      "dic": null,
      "ic_dph": null,
      "street": "Mierová 5",
      "city": "Bratislava",
      "zip": "821 05",
      "country": "SK"
    },
    "document_discount": null,
    "totals": {
      "net": "55.03",
      "vat": "10.22",
      "gross": "65.25",
      "paid": "65.25",
      "due": "0.00"
    },
    "totals_eur": null,
    "lines": [
      {
        "kind": "item",
        "name": "Dubová doska 120 x 40 cm",
        "quantity": 1,
        "unit": "ks",
        "unit_price": "41.46",
        "unit_price_with_vat": "51.00",
        "vat_rate": 23,
        "discount": null,
        "net_amount": "41.46",
        "vat_amount": "9.54",
        "gross_amount": "51.00",
        "reverse_charge": false,
        "exemption_reason": null,
        "price_item_id": null
      },
      {
        "kind": "item",
        "name": "Kniha Stolárske spoje",
        "quantity": 1,
        "unit": "ks",
        "unit_price": "13.57",
        "unit_price_with_vat": "14.25",
        "vat_rate": 5,
        "discount": null,
        "net_amount": "13.57",
        "vat_amount": "0.68",
        "gross_amount": "14.25",
        "reverse_charge": false,
        "exemption_reason": null,
        "price_item_id": null
      }
    ],
    "vat_breakdown": [
      {
        "rate": 23,
        "net": "41.46",
        "vat": "9.54"
      },
      {
        "rate": 5,
        "net": "13.57",
        "vat": "0.68"
      }
    ],
    "variable_symbol": "20260411",
    "payment_method": "card",
    "iban": "SK3112000000198742637541",
    "language": "SK",
    "note": "Objednávka 1042.",
    "buyer_reference": null,
    "related_invoice_id": null,
    "external_id": "1042",
    "source": "woocommerce",
    "sent_at": null,
    "created_at": "2026-10-16T08:12:31.000Z",
    "updated_at": "2026-10-16T08:12:32.000Z",
    "links": {
      "pdf": "https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001/pdf",
      "ubl": "https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001/ubl"
    }
  }
}
PRIHLÁSENIE

Kľúč koná menom človeka

Každá požiadavka nesie hlavičku Authorization: Bearer simfa_live_… pre ostrú firmu alebo simfa_test_… pre skúšobnú. Kľúč má predponu, 40 náhodných znakov a kontrolný súčet, takže preklep spozná server bez databázy.

  • Kľúč patrí človeku, ktorý ho založil, a koná s jeho rolou. Keď z firmy odíde, kľúč prestane platiť.
  • Ostrý kľúč je súčasťou Premium. Založenie potvrdí kód z e-mailu a o každom novom kľúči príde bezpečnostný e-mail.
  • Kľúč, ktorý posiela doklady, potrebuje Overenú firmu.
  • Skúšobná firma je zadarmo a má testovacie kľúče (simfa_test_…). E-maily z nej dostanú len ľudia z firmy, nikto cudzí. Založíš ju jedným klikom v Nastaveniach, v záložke Integrácie.
  • Voliteľne povolené IP adresy a platnosť. Zrušenie v Nastaveniach platí hneď.
  • Kľúč patrí na server. Nevkladaj ho do prehliadača ani do aplikácie v telefóne.
OBLASTI

Kľúč smie len to, čo dostal

Oblasti sa vyberajú pri založení kľúča. Operácia, na ktorú kľúč oblasť nemá, vráti 403 missing_scope aj so zoznamom chýbajúcich oblastí.

OblasťČo dovolí
citanieČítať doklady a kontakty. Firma, faktúry, ponuky, dobropisy, kontakty, cenník a súbory dokladov (PDF, e-faktúra).
konceptyPripravovať koncepty. Založiť a upraviť koncept faktúry či dobropisu. Nič sa tým nevystaví ani neodošle.
vystavovanieVystavovať doklady. Koncept vystaví a pridelí mu číslo. Vystavená faktúra sa nedá zmazať, opraviť sa dá dobropisom.
odosielaniePosielať doklady. Pošle faktúru cez Peppol alebo e-mailom. O každom odoslaní príde upozornenie.
platbyZapisovať platby. Zapíše úhradu k faktúre.
kontaktySpravovať kontakty. Založiť a upraviť odberateľa.
prijatePrijaté faktúry. Nahrať prijatý doklad na vyťaženie a prečítať prijaté faktúry. Pribudne s ďalšími operáciami.
bankaBanka. Čítať pohyby na bankových účtoch firmy. Pribudne s ďalšími operáciami.
webhookyWebhooky. Spravovať adresy, na ktoré SimFa posiela udalosti.
KONVENCIE

Sumy, stránky, idempotencia, limity

Sumy a dátumy

Sumy sú desatinné reťazce s dvoma miestami v mene dokladu, napríklad "65.25". Na vstupe aj číslo, najviac s dvoma desatinnými miestami; tri miesta sú chyba, nie zaokrúhlenie. Dátumy RRRR-MM-DD, časy ISO 8601 v UTC.

Stránkovanie

Zoznamy vracajú data, has_more a next_cursor, predvolene 25 a najviac 100 záznamov. Na dobiehanie zmien pošli updated_since a order=asc, nič sa nepreskočí.

Idempotencia

Zakladanie a zmeny stavu prijímajú Idempotency-Key. Rovnaký kľúč s rovnakým telom do 24 hodín vráti prvú odpoveď s hlavičkou Idempotent-Replayed: true. Súbežná požiadavka dostane 409, iné telo 422.

Limity

120 požiadaviek za minútu na kľúč, 600 na firmu spolu, PDF a odoslanie 20. Odpoveď nesie RateLimit-Policy a RateLimit, pri prekročení 429 s Retry-After.

CHYBY

Chyba, ktorú prečíta program aj človek

Chyby majú tvar application/problem+json podľa RFC 9457: code pre program, detail ako vetu po slovensky, ktorú môže integrácia ukázať človeku, a request_id pre podporu. Chyby vstupu prídu všetky naraz v errors.

KódStavVýznam
unauthorized401Chýba platný API kľúč
missing_scope403Kľúč nemá potrebnú oblasť
forbidden403Prístup zamietnutý
plan_required403Ostrý kľúč potrebuje Premium
test_key_live_company403Testovací kľúč patrí len skúšobnej firme
not_found404Záznam neexistuje
invalid_request400Neplatná požiadavka
conflict409Stav záznamu to nedovoľuje
duplicate_order409Objednávka už má doklad
idempotency_in_progress409Rovnaká požiadavka sa ešte spracúva
idempotency_mismatch422Kľúč idempotencie už patrí inej požiadavke
order_stopped422Z objednávky doklad nevznikne
not_sent422Doklad neodišiel žiadnou cestou
rate_limited429Priveľa požiadaviek
server_error500Chyba na strane SimFa
400
{
  "type": "https://simfa.sk/vyvojari/chyby#invalid_request",
  "title": "Neplatná požiadavka",
  "status": 400,
  "detail": "Požiadavka má 2 chyby v poliach, sú v errors.",
  "code": "invalid_request",
  "errors": [
    {
      "field": "lines[0].unit_price",
      "message": "Cena za jednotku je suma s najviac dvoma desatinnými miestami, napríklad \"9.99\"."
    },
    {
      "field": "customer",
      "message": "Doklad potrebuje odberateľa: contact_id alebo customer s menom."
    }
  ],
  "request_id": "req_7Hq2kL9xV1"
}
E-SHOP

Objednávka sama vyberie správny doklad

POST /v1/orders prijme objednávku s cenami s DPH a podľa platby vystaví doklad, ako by ho vystavil človek. Zákazník sa nájde alebo založí podľa external_id a source, objednávka sa nevystaví dvakrát.

ObjednávkaČo vznikneStav
card, paypal, online, zaplatenáfaktúra vystavená a uhradená201
card, paypal, online, nezaplatenázatiaľ nič, doklad vznikne po platbe202
bank_transferzálohová faktúra, po úhrade faktúra201
cash_on_deliverykoncept faktúry, vystavíš ho pri odoslaní (invoices.issue)201
cashzastaví sa: hotovosť pri odbere eviduje eKasa422
firma z EÚ s IČ DPHbez slovenskej DPH (oslobodenie alebo prenesenie), IČ DPH overí VIES201
občan z EÚ s DPH svojej krajinyzastaví sa (OSS)422
súčet nesedí s položkamizastaví sa s oboma sumami422
tá istá objednávka znovadruhý doklad nevznikne, príde id prvého409
WEBHOOKY

Udalosti prídu samy, podpísané podľa štandardu

Keď sa v SimFa niečo stane, pošleme POST na adresu, ktorú si firma pridá v Nastaveniach, Integrácie, alebo cez POST /v1/webhook_endpoints (tak sa prihlasujú spúšťače Make a Zapier). Podpis je podľa otvoreného štandardu Standard Webhooks: hlavičky webhook-id, webhook-timestamp a webhook-signature, overíš ich hotovou knižnicou.

# Takto vyzerá správa od SimFa; podpis sa počíta z webhook-id.webhook-timestamp.telo
curl https://tvoj-system.sk/simfa \
  -H 'content-type: application/json' \
  -H 'webhook-id: evt_mgu7k2x1aQ4tR9sLm2Xb7Kp0Z' \
  -H 'webhook-timestamp: 1792224752' \
  -H 'webhook-signature: v1,…' \
  -d '{"id":"evt_mgu7k2x1aQ4tR9sLm2Xb7Kp0Z","object":"event","type":"invoice.paid","timestamp":"2026-10-16T08:12:32.000Z","company_id":"cmf0firma00000000000000001","data":{"object":{"id":"cmf0doklad0000000000000001","object":"invoice","type":"invoice","number":"2026-0411","status":"paid","payment_status":"paid","issue_date":"2026-10-16","due_date":"2026-10-30","delivery_date":"2026-10-16","currency":"EUR","exchange_rate":null,"exchange_rate_date":null,"prices_include_vat":true,"vat_payer":true,"tax_regime":"standard","customer":{"contact_id":"cmf0kontakt000000000000001","name":"Jana Kováčová","ico":null,"dic":null,"ic_dph":null,"street":"Mierová 5","city":"Bratislava","zip":"821 05","country":"SK"},"document_discount":null,"totals":{"net":"55.03","vat":"10.22","gross":"65.25","paid":"65.25","due":"0.00"},"totals_eur":null,"variable_symbol":"20260411","payment_method":"card","iban":"SK3112000000198742637541","language":"SK","note":"Objednávka 1042.","buyer_reference":null,"related_invoice_id":null,"external_id":"1042","source":"woocommerce","sent_at":null,"created_at":"2026-10-16T08:12:31.000Z","updated_at":"2026-10-16T08:12:32.000Z","links":{"pdf":"https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001/pdf","ubl":"https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001/ubl"}},"url":"https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001","details":{"payment":{"id":"cmf0uhrada0000000000000001","amount":"65.25","amount_in_currency":null,"date":"2026-10-16","method":"card","source":"manual"}}}}'

Prijímač odpovie kódom 2xx do 15 sekúnd, presmerovanie nenasledujeme. Neúspešnú správu skúsime znova po 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h a 24 h, spolu takmer 3 dni. Adresu, ktorá za ten čas neprijme nič alebo odpovie 410, vypneme a majiteľ firmy dostane e-mail. Doručenie je aspoň raz a poradie nie je zaručené, rovnaké webhook-id spracuj len raz. Po rotácii platí predošlé tajomstvo ešte 24 hodín a správy nesú oba podpisy. Firma má najviac 10 adries a udalosti sú 30 dní aj v GET /v1/events, na dobehnutie zmeškaných.

POST na tvoju adresu
{
  "id": "evt_mgu7k2x1aQ4tR9sLm2Xb7Kp0Z",
  "object": "event",
  "type": "invoice.paid",
  "timestamp": "2026-10-16T08:12:32.000Z",
  "company_id": "cmf0firma00000000000000001",
  "data": {
    "object": {
      "id": "cmf0doklad0000000000000001",
      "object": "invoice",
      "type": "invoice",
      "number": "2026-0411",
      "status": "paid",
      "payment_status": "paid",
      "issue_date": "2026-10-16",
      "due_date": "2026-10-30",
      "delivery_date": "2026-10-16",
      "currency": "EUR",
      "exchange_rate": null,
      "exchange_rate_date": null,
      "prices_include_vat": true,
      "vat_payer": true,
      "tax_regime": "standard",
      "customer": {
        "contact_id": "cmf0kontakt000000000000001",
        "name": "Jana Kováčová",
        "ico": null,
        "dic": null,
        "ic_dph": null,
        "street": "Mierová 5",
        "city": "Bratislava",
        "zip": "821 05",
        "country": "SK"
      },
      "document_discount": null,
      "totals": {
        "net": "55.03",
        "vat": "10.22",
        "gross": "65.25",
        "paid": "65.25",
        "due": "0.00"
      },
      "totals_eur": null,
      "variable_symbol": "20260411",
      "payment_method": "card",
      "iban": "SK3112000000198742637541",
      "language": "SK",
      "note": "Objednávka 1042.",
      "buyer_reference": null,
      "related_invoice_id": null,
      "external_id": "1042",
      "source": "woocommerce",
      "sent_at": null,
      "created_at": "2026-10-16T08:12:31.000Z",
      "updated_at": "2026-10-16T08:12:32.000Z",
      "links": {
        "pdf": "https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001/pdf",
        "ubl": "https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001/ubl"
      }
    },
    "url": "https://api.simfa.sk/v1/invoices/cmf0doklad0000000000000001",
    "details": {
      "payment": {
        "id": "cmf0uhrada0000000000000001",
        "amount": "65.25",
        "amount_in_currency": null,
        "date": "2026-10-16",
        "method": "card",
        "source": "manual"
      }
    }
  }
}
UdalosťKedy príde
invoice.issuedFaktúra, zálohová faktúra alebo dobropis dostali číslo. Druh dokladu je v `data.object.type`.
invoice.sentDoklad odišiel klientovi e-mailom, cez Peppol alebo SMS, aj ako upomienka. Cestu nesie `data.details.channel`, upomienku `data.details.reminder`.
invoice.partially_paidK dokladu pribudla úhrada a ešte niečo ostáva zaplatiť. Úhradu nesie `data.details.payment`.
invoice.paidDoklad je celý uhradený, ručne, z banky aj cez API. Poslednú úhradu nesie `data.details.payment`.
invoice.overdueRáno po dni splatnosti, keď doklad ešte nie je celý uhradený. Raz pre každý dátum splatnosti.
contact.createdOdberateľ pribudol v appke, cez API alebo z e-shopu.
contact.updatedZmenili sa údaje odberateľa.
received_invoice.createdPrišiel doklad od dodávateľa e-mailom, cez Peppol alebo nahratím. Duplicitu nesie `data.object.duplicate`.
package.readyBalík dokladov za mesiac je hotový. Nesie adresu odberu bez tokenu, nie súbor: token má program, ktorý balíky odoberá.
REFERENCIA

Operácie API v1

25 operácií nad adresou https://api.simfa.sk/v1. Celý opis je aj ako OpenAPI 3.1 pre generátory klientov, Postman a AI asistentov.

Firma

Kontakty

Faktúry a dobropisy

Objednávky z e-shopu

Udalosti a webhooky

VERZIE

Integrácia sa nerozbije zo dňa na deň

Zmena, ktorá by rozbila integráciu, príde v novej verzii (/v2). Stará verzia potom platí ešte aspoň 12 mesiacov a jej odpovede nesú hlavičku Sunset. Nové polia a nové operácie pribúdajú bez novej verzie, neznáme polia v odpovedi má integrácia ignorovať.

  • 1.1.0Udalosti a webhooky: GET /v1/events, adresy webhookov (webhook_endpoints) a podpis podľa Standard Webhooks.
  • 1.0.0Prvá verzia: firma, kontakty, faktúry, zálohové faktúry, dobropisy, úhrady, PDF, e-faktúra UBL a objednávky z e-shopu.

Napoj svoj systém na SimFa.

Účet založíš za minútu, bez karty. Ostrý kľúč je súčasťou Premium.

Mám účet, založiť kľúč