eFaktúra Developers

Changelog

Dated log of changes to the Agent API and the partner portal. Newest first.

2026-10-13New
  • Foreign currency on invoices: POST /v1/agent/invoices accepts the optional fields currency (ISO 4217; the firm's currency when omitted) and exchange_rate (units of the currency per one unit of the firm's home currency, e.g. "1.0842"). Without a rate the server fills in the ECB rate (Slovak firm) or the CNB rate (Czech firm) for the tax point; if it cannot get one, the invoice is created with exchange_rate: null. Credit and debit notes must use the currency of the original invoice. The response and GET /v1/agent/invoices/{id} carry exchange_rate.
  • Documents from the API to the accounting program: POST /v1/agent/expenses/{id}/approve-for-accounting (receipt:approve scope) is the counterpart of the Zaúčtovať button in eDoklad — it marks a received document as approved for accounting and hands it to the Konektor (Omega, Pohoda, Money S3, MRP). Repeat calls are no-ops; a document in status processing, needs_review or rejected returns 409 EXPENSE_NOT_POSTABLE. In bulk via POST /v1/agent/expenses/bulk with action: approve_for_accounting.
  • Mutual set-off through the API: POST /v1/agent/offsets (invoice:update and receipt:update scopes, Idempotency-Key) offsets an issued invoice against a received invoice of the same counterparty — it writes an offset payment on both documents and pairs them. GET /v1/agent/offsets (invoice:read) lists the set-offs. For firms with Omega, eFaktúra creates an internal document once Omega's mirror shows both documents; the state is in accounting_program. Slovak firms only.
2026-10-10New
  • Partial payments and set-off through the API: POST /v1/agent/invoices/{id}/payments (invoice:update scope) records one payment of a document with an amount, date and method bank_transfer, cash, card or offset (mutual set-off). Record the remainder after a set-off with a second call; the meta of the response returns the new balance and status. Supports Idempotency-Key.
2026-10-02Improvement
  • The sandbox behaves like production: POST /v1/agent/organizations does not register the organization on the Peppol TEST network, POST /v1/agent/peppol/enroll requires a verification token (any hex is enough in the sandbox) and sending without an active Peppol account is rejected. This applies right away to accounts registered from 02.10.2026 and to older accounts that switch on “Sandbox like production” in the portal (Team & permissions), and to everyone else from 01.11.2026; until then their responses carry a warnings field and the Deprecation, Sunset and Link headers. The test tokens and the differences are on the Sandbox vs. production page.
  • Invoice preflight: POST /v1/agent/invoices/{id}/preflight (invoice:read scope) validates the exact document that will be sent (attachments and Peppol IDs included) and checks the recipient from the buyer DIČ in one call; it never writes or charges. Before sending, GET /v1/agent/invoices/{id}/xml returns the same document (header X-Efaktura-Ubl-Source: preview). Every /v1/agent/* response carries a Server-Timing header. See Recommended flow.
2026-10-01New
  • Webhooks for companies with their own API key: POST /v1/agent/webhooks (settings:update scope, Pro plan and higher) registers an HTTPS endpoint for invoice events (invoice.created/updated/deleted/sent/viewed/paid/overdue — from any channel incl. imports and recurring invoices), payments, reminders, inventory and Peppol documents (peppol.document.sent/delivered/failed/received). Delivery uses the same signature and retries as partner webhooks (11 attempts over ~2.7 days), with history and redelivery via /v1/agent/webhooks/{id}/deliveries. Make and n8n instant triggers attach to these endpoints. See Webhooks → Webhooks for companies.
  • OAuth “Connect with eFaktúra”: third-party apps (e-shop, CRM, ERP) register via Dynamic Client Registration with resources ["https://api.efaktura.sk/v1/agent"], the user signs in, picks a company and approves scopes, and the app calls the Agent API with Authorization: Bearer. The token is bound to one company (no X-Organization-Id needed), its scopes are the intersection of the consent and the user's role, and the user can revoke it any time in Settings → Integrations. MCP and Agent API tokens are kept apart. See OAuth — Connect with eFaktúra.
  • Event feed: GET /v1/agent/events (partner key, invoice:read scope) returns every partner event oldest first, paged with the after/next_after cursor, with the same body as the webhook. Events are logged even without a registered webhook endpoint and kept for 90 days, so you can fetch missed events behind a firewall or after a longer outage. See Webhooks → Event feed.
2026-09-30Improvement
  • Partner webhooks now retry for longer on failure: 11 attempts over about 2.7 days (5 s, 1 min, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, 14 h, 24 h) instead of 6 attempts within 2.5 minutes, so a temporarily unreachable endpoint receives every event without a manual replay. Keep deduplicating by X-Webhook-Id.
2026-09-28Improvement
  • Until 31.12.2026, a live Peppol send of an invoice (agent, batch, the raw-UBL connector, SAPI-SK, and SFTP) fails with INVOICE_ISSUE_DATE_TOO_OLD when the invoice was issued more than 10 days ago. This is an eFaktura internal safety limit, not a statutory deadline; test sends are exempt. From 1.1.2027 the INVOICE_ISSUE_DATE_NOT_SEND_DATE rule replaces it.
2026-09-23New
  • Scheduled and bulk Peppol sending: GET/PUT /v1/agent/peppol/send-settings pick the send mode (immediate/scheduled/manual), POST /v1/agent/peppol/batches/send releases held sends on demand, and GET /v1/agent/peppol/queue reports the organization's queue and platform-wide completion estimates. Held sends are also force-released by an automatic safety cutoff so they always leave by 21:00. See Scheduled and bulk Peppol sending.
  • From 1.1.2027, sending an invoice via Peppol (agent, batch, the raw-UBL connector, SAPI-SK, and SFTP) fails with INVOICE_ISSUE_DATE_NOT_SEND_DATE when the issue date (BT-2) doesn't match today — per the Slovak Financial Administration's e-Faktúra FAQ and § 85o of the VAT act.
2026-09-19New
  • GET /v1/agent/dashboard/onboarding (scope report:read): an organization's onboarding status in one call — Peppol account (participant_id, status, claim_status, pending_mandate), plan and subscription (status including past_due, current_period_end, edoklady_active), bank connections with their consent validity consent_expires_at, and the accounting-software link through the Connector (paired, version, last successful write, pending / failed / needs_review counts). Meant for accounting offices tracking the rollout of many organizations; the organization is selected by X-Organization-Id. The call writes nothing. The payment state is returned only to the organization's founder or a partner key, the bank block additionally needs the bank:read scope, and pending_mandate is evaluated for partner keys only — otherwise these values are null.
2026-09-18New
  • POST /v1/agent/invoices: new due_date field (YYYY-MM-DD) as a direct alternative to due_days (sending both returns 400; due_date must not precede issue_date). New payment_method value "online" (online payment service, e.g. PayPal). The payment method is now carried into the Peppol UBL as PaymentMeansCode per UNCL4461 (bank_transfer 30, cash 10, card 48, online 68, offset 97) — previously code 30 was always emitted. The payee account (IBAN/BIC) stays in PaymentMeans for every code whenever the document carries one.
  • Invoice attachments (attachments on POST /v1/agent/invoices, POST /v1/agent/invoices/:id/attachments and in-app upload): CSV, XLSX and ODS are now accepted alongside PDF/JPG/PNG — exactly the MIME types Peppol BIS 3.0 allows to be embedded in an e-invoice. DOC/DOCX/XLS/GIF cannot be delivered over Peppol; convert them to PDF.
2026-09-17Improvement
  • GET /v1/agent/peppol/events: native documents (app, POST /send) that failed before any Peppol dispatch (schematron, eligibility, credit, recipient) now appear in the audit trail as sent.failed with the failure time and the document number in the detail. Every data export (this audit trail, invoice, receipt, Peppol XML and account exports and the organization audit-log CSV) is itself written to the organization's audit log as data.export; the organization audit log in eDoklad gained a CSV export.
2026-09-13Improvement
  • GET /v1/agent/dashboard/summary: the period parameter now also accepts a period type week | month | quarter | year (ISO weeks from Monday) besides a YYYY-MM month, plus anchor (YYYY-MM-DD, defaults to today in Europe/Bratislava); without period the current month applies. The response adds period_range { type, start, end, label } and the net amounts revenue_total_net, revenue_outstanding_net and outstanding_amount_net (per-document net, credit notes signed). Existing fields are unchanged.
2026-09-08New
  • Received documents in the Agent API: GET /v1/agent/peppol/received/:id (metadata incl. SBDH identifiers, UBL SHA-256, attachment list, links), POST …/acknowledge (idempotent pickup acknowledgement, ?acknowledged=false filter against double processing) and GET …/evidence (receipt evidence with the dispatched MLS and its AS4 message id). GET /received now also returns acknowledged_at, sbdh_instance_id, attachments_count and is_test.
  • GET /v1/agent/peppol/events: exportable audit trail for sent and received documents (queued, AS4 receipt, deferred, failed, MLS delivered/rejected, received, MLS sent, pickup acknowledged) with time, result, AS4 message id, SBDH InstanceIdentifier and UBL SHA-256; JSON or CSV, from/to window.
2026-08-20New
  • Contracts module in the Agent API (/v1/agent/contracts): list, detail, create, update, delete, payment schedule (incl. marking a payment as paid), linked invoices and recurring invoices, stats, AI extraction from PDF, and attachments. Scopes contract:read/create/update/delete; new partner keys get read/create/update by default, older keys need to be regenerated.
  • PATCH /v1/agent/invoices/:id: edit an invoice's content (items, dates, notes, bank account, contract linking…). Same rules as the app: cancelled/archived/locked documents can't be edited, Peppol-sent ones only accounting metadata. The payload is camelCase (session shape) with an optional optimistic version lock. Requires the invoice:update scope.
  • Tightening: USER-scoped API keys (efk_live_/efk_test_) are now authorized by the intersection of the key's scopes and the user's permissions. A key with restricted scopes (e.g. invoice:read only) can no longer perform write operations through its owner's permissions; least-privilege keys are now enforced.
  • Projects (zákazky) in the Agent API: /v1/agent/projects (list, create with a color, detail, update) plus new case_id fields on expenses (create, upload, update, list filter) and caseId on contracts. Documents and contracts can be tagged with a project the moment they are created. Expenses also gained branch_id (previously only branch_code on upload).
2026-08-01New
  • Idempotency for document creation: POST /v1/agent/invoices and POST /v1/agent/expenses now accept an optional Idempotency-Key header. Retrying with the same key and body returns the stored response (the document isn't created twice, and the number series isn't consumed); the same key with a different body returns 409. Strongly recommended for all retry mechanisms.
  • POST /v1/agent/invoices/:id/send-reminder: calling it again within 10 minutes no longer resends the reminder, it returns 200 with sent:false instead of a duplicate email to the customer.
  • E-invoice validation fixes: a corrective document (§25, UNTDID 384) now keeps the actual sign of its amounts (previously it behaved like a credit note by taking the absolute value); a credit note without a VAT category on a line now correctly fails on SK-BT-148; deduplication of received documents now includes the document type (a credit note with the same number as an invoice is no longer dropped as a duplicate).
2026-07-27Fix
  • POST /v1/agent/expenses/scan-qr: parsing of eKasa receipts now applies only to organizations with SK (eKasa) fiscalization. Organizations from other countries (e.g. CZ) get a generic result { type: "text", raw } even for an eKasa QR code.
2026-07-23Fix
  • GET /v1/agent/expenses/:id/qr: the generated Pay by Square QR code no longer includes the due date (banking apps were pre-filling it or rejecting the payment).
2026-07-22Improvement
  • The phone number in the inline customer object (POST /v1/agent/invoices) is now validated as E.164: separators and the 00 prefix are normalized, and an invalid number returns a clear 400 VALIDATION_ERROR (previously an opaque 500 from a DB constraint).
2026-07-21New
  • New payment_method value: "offset" (mutual set-off) when creating an invoice, marking an expense as paid, or recording a payment. Credit notes can now be settled with a negative amount due (previously it was clamped to zero).
  • POST /v1/agent/invoices/:id/send-reminder: added "cs" (Czech) as a supported reminder language, alongside sk/en/de/hu.
2026-07-18Improvement
  • Invoices in the pending_approval state (awaiting approval) are now blocked the same way as drafts: you can't send a reminder for them or mark them as paid/cancelled; the API returns 400 instructing you to issue the invoice first.
2026-07-14Improvement
  • Issuing and editing an invoice (POST/PATCH /v1/invoices): new field numberSeriesAction (optional, "exception" | "advance") controls the series counter when customNumber (on issue) or number (on edit) jumps ahead of the series. Non-interactive requests without numberSeriesAction are handled by the API as "exception" by default: the document keeps the number you sent, but the series counter is no longer advanced automatically (behavior change, 2026-07). The Agent API doesn't yet support custom document numbers. Send "advance" to restore the previous behavior (continuing from the given number). Interactive (session) clients get a 409 NUMBER_OUT_OF_SERIES instead of the default, with details { typedNumber, expectedNext, nextIfException, nextIfAdvance, sequenceId, sequenceName, prefix }.
  • Documents saved with "exception" behavior are not tied to any number series and don't create a sequence_log entry: in series diagnostics they appear as "numbers outside series" and can later be adopted into a series retroactively.
2026-06-26New
  • Production onboarding (FS webhook → email confirmation): a company chooses eFaktúra as its delivery service provider (PDS) on the Slovak Financial Administration portal, the FS sends the mandate via webhook, and eFaktúra automatically sends the company a confirmation email. The company confirms receipt of e-invoices by clicking a public page (no login), this links it to your child org on live Peppol.
  • POST /agent/organizations/:id/peppol-claim: (re)sends the FS confirmation email for an org already owned by the key (scope invoice:send, NOT org:provision).
  • Public confirmation page for partner-claim: token-only, no company login required (anti-misrouting: the company's mailbox confirms via its FS company_email).
  • New documentation: Production onboarding and API keys and scopes.
2026-06-20New
  • Bulk sending via Peppol: POST /agent/peppol/send/batch with body { invoiceIds: [...] } (1–200 IDs per call).
  • Invoice attachments via the API: add, list, and remove attachments (scope invoice:update).
  • Received documents via the API: download the original PDF as well as the invoice's UBL XML (scope invoice:download).
2026-06-15New
  • Self-billing: support for the poacc:selfbilling:3.0 profile for both invoices and credit notes.
2026-06-10Improvement
  • The sandbox now runs on a real phoss-ap-TEST on the OpenPeppol TEST network: efk_pk_test_ sends go through the real Peppol TEST network (replacing the original in-process simulated Access Point). Still no credits and no FS.
2026-05-31New
  • Partner portal: document overview (Documents), invoices sent and received via Peppol with both document and transport statuses, filters, and a summary.
  • Partner portal: self-service sandbox API keys, an API call overview (logs), a list of client organizations.
  • Partner portal: partner login (email + password) via an administrator invitation.
  • Developer portal launched at developers.efaktura.sk, including the API reference (Scalar) and documentation.
2026-05-30New
  • Sandbox: efk_pk_test_ sends work immediately with no configuration on the Peppol TEST environment, no credits or FS.
  • Sandbox routing by key tier (test/live) on the same base URL (Stripe model).