Developer's Guide - e-invoice (Peppol) via the API

An invoice created in Faktúry online (via the API or manually) can be sent through the API to the Peppol network as an electronic invoice. Sending happens in two steps:

1. Queueing by calling /api/peppol-send. The system immediately checks the invoice (supplier and customer data, permission, credit, VAT regimes) and validates the generated e-invoice (UBL format, EN 16931 and Peppol BIS rules). If anything is missing you get the error right in the response and nothing is sent. If the invoice only has warnings, it is not sent until you fix it or send it with the ignore_warnings=1 parameter. If everything is fine, the invoice is queued and the response status is queued.
2. Sending is done by the server in the background, usually within one to two minutes: it creates the PDF attachment (if the company has it enabled) and hands the e-invoice over to a certified access point provider. You get the result by calling /api/peppol-status.

Note on timing. Sending an e-invoice is not instant. A call to /api/peppol-send usually takes 1 to 5 seconds because the whole e-invoice is generated and validated synchronously. The hand-over to the access point provider runs in the background, usually within 1 to 2 minutes of queueing (status sent). Delivery confirmation to the buyer (status accepted) may take 10 to 20 minutes. Do not wait for the result within a single call and do not resend the invoice while its status is not final.

Sending states returned by /api/peppol-status:

peppol_status	Meaning
not_sent	The invoice has not been queued for sending yet.
queued	Waiting in the queue (processed continuously, in the order of queueing).
sent	The access point provider has accepted the e-invoice and is delivering it into the Peppol network.
accepted	The e-invoice was delivered to the customer's access point. Final successful state.
rejected	The provider or the network rejected the e-invoice. Details are in peppol_error.
not_valid	The e-invoice failed validation in the network. Correct the data and send a corrective document.
failed	Sending failed (technical error or attempts exhausted). Details are in peppol_error and error_code. If error_code is receiver_unregistered, the invoice was sent and reported to the Financial Administration, do not send it again.

The accepted state is updated continuously from the provider's information, usually 10 to 20 minutes after sending. The system does not push the result (no webhook); you request the state yourself via /api/peppol-status.

• You need an API key and an initialised session via /api/init, just like for the other API calls (see the basic API manual).
• The company (the supplier's Tax ID on the invoice) must have completed the e-invoice activation in Faktúry online and must have an active package or transaction credit. Activation is done in the application in the E-invoice section; it cannot be done via the API.
• The account calling the API must be the owner of the activation or must have sending permission granted by the owner (delegation).
• You can send a regular invoice, a credit note, a debit note and a tax document for a received payment. Proforma invoices are not sent to the Peppol network.
• Each invoice can be sent only once. Corrections are made with a corrective document (credit note and a new invoice).

Before this call the session must be initialised (/api/init). API call for sending an invoice:

https://www.faktury-online.com/api/peppol-send?data={JSON}

Parameters:

Parameter	Attribute	Description
key	required	API key.
email	required	Email (or username) you use to log in to Faktúry online.
code	required	Invoice code (returned by the API when the invoice was created).
validate_only	optional	Value 1 only checks and validates the invoice, nothing is sent and no credit is used. Useful to verify the data before the real sending. Default value: 0
ignore_warnings	optional	Value 1 sends the invoice even if it has warnings (the warnings field). With value 0, an invoice with warnings is not sent and status 1622 is returned. Errors always block sending. Default value: 0

Request example:

Array
(
    [key] => vJyMc*4@2754*wGhofIWi!QDcEEQUdmj
    [email] => name@example.com
    [code] => 26915945a67c8b7ba74dac59c5badfbf
    [validate_only] => 0
    [ignore_warnings] => 0
)

Response when queued successfully:

Array
(
    [status] => 1
    [type] => OK
    [invoice_code] => 26915945a67c8b7ba74dac59c5badfbf
    [receiver_registered] => 1
    [warnings] => Array
        (
        )

    [test_mode] => 0
    [peppol_status] => queued
    [queue_id] => 1024
    [message] => Queued for sending. Poll /api/peppol-status for the result.
)

Field	Description
peppol_status	queued = queued for sending; with validate_only it is not_sent and the field validated is 1.
queue_id	Queue record number (a repeated call for the same invoice returns the same one).
receiver_registered	true = the customer is registered in the Peppol network, false = it is not, null = the registration could not be verified. The invoice is sent in all cases, the result is shown by /api/peppol-status.
warnings	List of warnings (code, message). The Peppol network accepts such an e-invoice, but the details may be wrong. The list of codes is below.
test_mode	1 = the company sends through a test provider (the e-invoice does not enter the live network).

Response on error:

Array
(
    [status] => 1618
    [type] => Error
    [error_code] => rezim_k_bez_icdph
    [message] => The e-invoice cannot be sent: the regime Intra-EU supply of goods requires the customer's VAT ID.
)

Response with warnings (status 1622):

Array
(
    [status] => 1622
    [type] => Error
    [error_code] => warnings
    [message] => The invoice has warnings. Check and fix the invoice, or send it again with ignore_warnings=1.
    [invoice_code] => 26915945a67c8b7ba74dac59c5badfbf
    [receiver_registered] => 1
    [warnings] => Array
        (
            [0] => Array
                (
                    [code] => issue_date_not_today
                    [message] => The issue date of an e-invoice should be the same as the day it is sent to the Peppol network. This invoice has the issue date 17.10.2026. We recommend changing the date.
                )

            [1] => Array
                (
                    [code] => buyer_vat_id_missing
                    [message] => The customer is a VAT payer (VAT ID SK2020123456), but the VAT ID is missing on the invoice.
                )

        )

)

The field error_code is a machine-readable error code (see the list below), message is an English description. On e-invoice validation errors the field errors lists the violated rules. With code 1615 (invoice already sent) the response also contains peppol_document_id of the original sending.

Return codes:

Status ID	Meaning	Description
1	OK	The invoice was queued (or, with validate_only, passed the checks).
1602	Error	The data parameter was not sent using GET.
1603	Error	The API key is missing or has an invalid length.
1604	Error	The API key is not entered correctly.
1605	Error	Email or username is missing.
1606	Error	The session is not initialised (call /api/init first).
1607	Error	The session is invalid.
1608	Error	Wrong combination of API key and email.
1609	Error	The account is not active or does not match the session.
1610	Error	The parameter code is missing.
1611	Error	No invoice exists with the given code.
1612	Error	This document type is not sent to the Peppol network (for example a proforma invoice).
1613	Error	Incorrect supplier VAT data (VAT payer without VAT ID, identical VAT ID of supplier and customer, missing or invalid Tax ID).
1614	Error	The company has not completed the e-invoice activation, the account has no sending permission or the provider is not active.
1615	Error	The invoice has already been sent; repeated sending is not possible.
1616	Error	The company has no active package or its transaction credit is used up.
1617	Error	The customer's country could not be recognised.
1618	Error	The VAT regime on the invoice is not allowed for an e-invoice (for example intra-EU supply without the customer's VAT ID, or intra-EU supply combined with export).
1619	Error	The e-invoice failed validation (the errors field lists the violated rules).
1620	Error	Unexpected error.
1621	Error	Too many requests, maximum 60 per minute.
1622	Error	The invoice has warnings and was not sent (the warnings field). Fix it or send it with ignore_warnings=1.

Before this call the session must be initialised (/api/init). API call for the sending status:

https://www.faktury-online.com/api/peppol-status?data={JSON}

Parameters:

Parameter	Attribute	Description
key	required	API key.
email	required	Email (or username) you use to log in to Faktúry online.
code	required	Invoice code.

Request example:

Array
(
    [key] => vJyMc*4@2754*wGhofIWi!QDcEEQUdmj
    [email] => name@example.com
    [code] => 26915945a67c8b7ba74dac59c5badfbf
)

Response:

Array
(
    [status] => 1
    [type] => OK
    [invoice_code] => 26915945a67c8b7ba74dac59c5badfbf
    [invoice_number] => 2026099
    [peppol_status] => accepted
    [peppol_document_id] => doc_5b1c9a2e-7f40-4c8a-9d21-3e8f0a6b7c1d
    [peppol_error] => 
    [error_code] => 
    [queue_attempts] => 1
    [peppol_queued_at] => 2026-10-01 10:12:05
    [peppol_sent_at] => 2026-10-01 10:13:02
    [peppol_status_checked_at] => 2026-10-01 10:28:00
)

Field	Description
peppol_status	Sending state (see the table of states in the first section).
peppol_document_id	Document identifier assigned by the access point provider on acceptance.
peppol_error	English error description for the states rejected, not_valid and failed, otherwise null.
error_code	Machine-readable code of the last error (see the list below), otherwise null.
queue_attempts	Number of sending attempts (a temporary error is retried up to three times).
peppol_queued_at	Time of queueing.
peppol_sent_at	Time of hand-over to the provider.
peppol_status_checked_at	Time of the last delivery check.

Recommended polling: send the first query about 2 minutes after queueing, then at most once every 10 minutes until the state is accepted, rejected, not_valid or failed. Delivery confirmation may take 10 to 20 minutes, more frequent queries bring no new state.

Return codes:

Status ID	Meaning	Description
1	OK	Everything went fine.
1702	Error	The data parameter was not sent using GET.
1703	Error	The API key is missing or has an invalid length.
1704	Error	The API key is not entered correctly.
1705	Error	Email or username is missing.
1706	Error	The session is not initialised (call /api/init first).
1707	Error	The session is invalid.
1708	Error	Wrong combination of API key and email.
1709	Error	The account is not active or does not match the session.
1710	Error	The parameter code is missing.
1711	Error	No invoice exists with the given code.
1712	Error	Too many requests, maximum 60 per minute.

• Each endpoint accepts at most 60 calls per minute per account; further calls get code 1621 or 1712.
• The queue is processed every minute in the order of queueing. One run sends at most 20 invoices and at most 5 invoices of one account, so that a batch from one integrator does not delay the others. With a larger batch expect the last invoices to leave a few minutes later; follow the state via /api/peppol-status.
• Invoices in the Designer PRO style take longer to render (a few seconds per invoice), so their sending may take a little longer.
• On a temporary error (provider unavailable, PDF creation failed) sending is retried automatically, up to three times. Then the invoice ends in the failed state and you can queue it again.
• The checks and validation in /api/peppol-send take 2 to 4 seconds; allow for that in your connection timeout.

The field error_code in the responses lets you handle errors programmatically. The most common values:

error_code	Meaning
fa_not_found	No invoice exists with the given code.
unsupported_type	The document type is not sent (proforma invoice).
vat_mismatch_platca_bez_icdph	The supplier is a VAT payer but has no VAT ID.
rovnake_icdph	Supplier and customer have the same VAT ID.
missing_dic, invalid_sk_dic	Missing or invalid supplier Tax ID.
no_postar	The company has not completed the e-invoice activation.
no_permission	The account has no permission to send for this company.
resend_blocked	The invoice has already been sent.
no_credit, no_credit_delegate	Credit used up or no package.
err_country_buyer	Unrecognised customer country.
receiver_unregistered	The customer is not registered in the Peppol network and the e-invoice could not be delivered. The sending was recorded, the invoice was reported to the Financial Administration and charged as sent. Do not send it again, you can email it to the customer.
warnings	The invoice has warnings and was not sent (the warnings field). Fix it or send it with ignore_warnings=1.
rezim_k_bez_icdph, rezim_k_bez_datumu, rezim_k_krajina, rezim_k_kombinacia, rezim_mimo_eu_krajina, rezim_ae_krajina	Not allowed combination of VAT regime and customer data.
validation_failed	The e-invoice failed validation before sending (errors field).
dp_rejected	The provider rejected the e-invoice (state rejected).
pdf_render_failed	The PDF attachment could not be created.
api_error, api_error_with_detail, api_error_with_rules	Error on the provider or network side; details in message or errors.
too_many_requests	Per-minute call limit exceeded.

Warning codes (warnings field):

code	Meaning
missing_supplier_street, missing_supplier_city, missing_supplier_zip	The supplier address is missing (street, city, postcode).
missing_buyer_street, missing_buyer_city, missing_buyer_zip	The customer address is missing.
missing_delivery_date	The date of supply is missing.
issue_date_not_today	The issue date is not today.
buyer_tax_id_not_found	The customer's Tax ID is not in the Financial Administration register.
buyer_tax_id_other_company	The customer's Tax ID belongs to a company with a different Company ID. The e-invoice is delivered according to the Tax ID.
buyer_vat_id_not_registered	The customer's VAT ID is not in the list of VAT payers.
buyer_vat_id_other_company	The customer's VAT ID belongs to a company with a different Company ID.
buyer_vat_id_tax_id_mismatch	The VAT ID does not match the Tax ID.
buyer_vat_id_missing	The customer is a VAT payer, but the VAT ID is missing on the invoice.

Tax ID and VAT ID checks apply only to customers from Slovakia.

Session initialisation, queueing an invoice for sending and reading the status:

<?php

// Príprava základných dát:
$data = [];

// Váš API kľúč:
$data['key'] = "dJyMc*53@687*wGhofIWi!WDcEEQUdmj";

// Váš email (príp. používateľské meno):
$data['email'] = "name@example.com";

// Inicializácia sedenia (cookie.txt musí byť zapisovateľný):
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.faktury-online.com/api/init?data=' . urlencode(json_encode($data)));
curl_setopt($ch, CURLOPT_COOKIESESSION, true);
curl_setopt($ch, CURLOPT_COOKIEJAR, 'cookie.txt');
curl_setopt($ch, CURLOPT_COOKIEFILE, 'cookie.txt');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
$result = json_decode(curl_exec($ch), true);
if ($result['status'] != 1) {
    throw new Exception("Vyskytla sa chyba č. " . $result['status']);
}

// Kód faktúry (z odpovede API pri jej vytvorení):
$data['code'] = "14915945a66c8b7be74dac59c5badfbf";
// Faktúru s upozorneniami (pole warnings) odoslať aj tak? 0 = nie (predvolené), 1 = áno:
$data['ignore_warnings'] = "0";

// Zaradenie na odoslanie do siete Peppol (kontroly a validácia prebehnú hneď):
curl_setopt($ch, CURLOPT_URL, 'https://www.faktury-online.com/api/peppol-send?data=' . urlencode(json_encode($data)));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$result = json_decode(curl_exec($ch), true);
if ($result['status'] != 1) {
    // error_code = strojový kód chyby, message = popis
    // Pri stave 1622 obsahuje $result['warnings'] zoznam upozornení (code, message)
    throw new Exception("Odoslanie zamietnuté: " . $result['status'] . " " . $result['error_code'] . " (" . $result['message'] . ")");
}
// $result['peppol_status'] == 'queued'

// Stav odoslania (prvý dotaz asi po 2 minútach, potom najviac raz za 15 minút):
sleep(120);
curl_setopt($ch, CURLOPT_URL, 'https://www.faktury-online.com/api/peppol-status?data=' . urlencode(json_encode($data)));
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

// $result['peppol_status']: queued | sent | accepted | rejected | not_valid | failed
echo $result['peppol_status'], " ", $result['peppol_document_id'] ?? '', " ", $result['peppol_error'] ?? '';