====== REST API ======

===== Test Access Point URL =====

[[https://peppol.eso9.cz/accesspoint|https://peppol.eso9.cz/accesspoint]]

===== Production Access Point URL =====

[[https://eso9peppol.eu/accesspoint|https://eso9peppol.eu/accesspoint]]

===== Basic communication verification =====

  * //URL:// [[{{URL}}/api/auth/whoami|{{URL}}/api/auth/whoami]]
  * //HTTP method:// GET
  * //Authentication:// no
  * //Headers://
    * Accept: ''*/*''
  * //Body:// empty
  * //Returns:// caller IP address

===== Authentication =====

  * //URL:// [[{{URL}}/api/auth|{{URL}}/api/auth]]
  * //HTTP method:// POST
  * //Authentication:// no
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/json
  * //Body:// JSON with user name (VAT NO) and password in structure:

<code json>
{
    "username":"CZ27624609",
    "password":"xxxxxxxxxxxxxx"
}
</code>

  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": "89puKGciOiJIUzI1NiJ9.eyJzdWIiOiJDWjI3NjI0NjA5IiwiaWF0IjoxNzYzNjrUijc2987leHAiOjE3NjM2MzY2NzZ9.Gwz0M1N_gycoar_Ir3UbDRC0_nbBucqc_943l-bkeiE",
    "timestamp": "2025-11-20 09:24:36"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK).
  * //message:// Bearer token used for authentication of SEND / RECEIVE methods. Token is valid for 24 hours. Error description if authentication fails.
  * //errorCode:// Error Code if authentication fails.

==== Example ====

<code bash>
curl --location '{URL}/api/auth' \
--header 'Content-Type: application/json' \
--data '{
    "username":"CZ27624609",
    "password":"xxxxxxxxxxxxxx"
}'
</code>

===== Sending document in BIS3.0 format =====

Validates and sends one document.

  * //URL:// [[{{URL}}/api/peppol/send|{{URL}}/api/peppol/send]]
  * //HTTP method:// POST
  * //Authentication:// Bearer token obtained by calling the ''AUTH'' method
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/xml
    * Authorization: Bearer 89puKGci...
    * X-PEPPOL-RECEIVER: PEPPOL recipient's ID (aka ParticipantID), e.g.''9929:CZ27624609''
    * X-PEPPOL-DOC-TYPE: type of document being sent, e.g.''Generic.Invoice'' or ''Generic.CreditNote''
  * //Body:// document in PEPPOL BIS 3.0 format
  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": 70,
    "timestamp": "2025-11-20 09:53:28"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK)
  * //message:// created document ID on Access Point. Error description if sending fails.
  * //errorCode:// Error Code if sending fails.

==== Example ====

<code bash>
curl --location '{URL}/api/peppol/send' \
--header 'X-PEPPOL-RECEIVER: 9929:CZ27624609' \
--header 'X-PEPPOL-DOC-TYPE: Generic.Invoice' \
--header 'Content-Type: application/xml' \
--header 'Authorization: Bearer ••••••' \
--data-raw '<ns4:Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" .... '
</code>

===== Sending document in flat structure =====

Validates and sends one document in flat structure. The flat structure XML is described in detail [[Vstupní-FlatXML|here]].

  * //URL:// [[{{URL}}/api/peppol/sendFlat|{{URL}}/api/peppol/sendFlat]]
  * //HTTP method:// POST
  * //Authentication:// Bearer token obtained by calling the ''AUTH'' method
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/xml
    * Authorization: Bearer 89puKGci...
    * X-PEPPOL-RECEIVER: PEPPOL recipient's ID (aka ParticipantID), e.g.''9929:CZ27624609''
    * X-PEPPOL-DOC-TYPE: type of document being sent, e.g.''Generic.Invoice'' or ''Generic.CreditNote''
  * //Body:// document in [[Vstupní-FlatXML|flat format]]
  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": 71,
    "timestamp": "2026-04-08 12:59:28"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK)
  * //message:// created document ID on Access Point. Error description if sending fails.
  * //errorCode:// Error Code if sending fails.

==== Example ====

===== Receiving document in BIS3.0 format =====

Receipt of a single document in PEPPOL BIS3.0 format.

  * //URL:// [[{{URL}}/api/peppol/receive|{{URL}}/api/peppol/receive]]
  * //HTTP method:// GET
  * //Authentication:// Bearer token obtained by calling the ''AUTH'' method
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/xml
    * Authorization: Bearer 89puKGci...
    * X-PEPPOL-DOCUMENT-ID: document ID retrieved from webhook (''IDPEPPOLDOC'' in ESO9 table ''PEPPOL_DOC_QUEUE'')
  * //Body:// none
  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": "",
    "timestamp": "2025-11-28 13:00:45",
    "document": "<as4:Invoice> ... </as4:Invoice>\n",
    "documentType": "Generic.Invoice"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK)
  * //document:// document in PEPPOL BIS 3.0 format
  * //errorCode:// Error Code if sending fails.

==== Example ====

<code bash>
curl --location '{URL}/peppol/receive' \
--header 'X-PEPPOL-DOCUMENT-ID: 9999' \
--header 'Authorization: Bearer ••••••'
</code>

===== Receiving document in flat structure =====

Receipt of a single document in flat structure. The flat structure XML is described in detail [[Vstupní-FlatXML|here]].

  * //URL:// [[{{URL}}/api/peppol/receiveFlat|{{URL}}/api/peppol/receiveFlat]]
  * //HTTP method:// GET
  * //Authentication:// Bearer token obtained by calling the ''AUTH'' method
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/xml
    * Authorization: Bearer 89puKGci...
    * X-PEPPOL-DOCUMENT-ID: document ID retrieved from webhook (''IDPEPPOLDOC'' in ESO9 table ''PEPPOL_DOC_QUEUE'')
  * //Body:// none
  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": "",
    "timestamp": "2025-11-28 13:00:45",
    "document": "<?xml version="1.0" encoding="utf-8"?><Invoice> ... </Invoice>\n",
    "documentType": "Generic.InvoiceFlat"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK)
  * //document:// document in [[Vstupní-FlatXML|flat format]]
  * //errorCode:// Error Code if sending fails.

==== Example ====

===== Retrieval of all documents =====

Retrieves a list of all documents (sent and received) without including their payload.

  * //URL:// [[{{URL}}/api/peppol/documents?from=2026-01-01T15:00:00&to=2026-02-15T00:00:00|{{URL}}/api/peppol/documents?from=2026-01-01T15:00:00&to=2026-02-15T00:00:00]]
  * //HTTP method:// GET
  * //Parameters:// from / to - document creation date and time (from / to)
  * //Authentication:// Bearer token obtained by calling the ''AUTH'' method
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/xml
    * Authorization: Bearer 89puKGci...
  * //Body:// none
  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": [
        {
            "id": 1,
            "documentType": "busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
            "processType": "cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
            "instanceUuid": "b8702472-9949-48d0-aeb3-b7aee49b37c8",
            "transmissionMessageUUID": "86b9c5c9-41dc-48e1-a9a5-3a9fbf098b10@ca65f6a4ac26",
            "senderId": "9950:sk2022706521",
            "receiverId": "9929:cz27624609",
            "c1CountryCode": "SK",
            "c4CountryCode": "CZ",
            "status": 1,
            "dtCreated": "2026-02-11T11:37:50",
            "dtUpdated": "2026-02-11T11:37:50",
            "direction": 1,
            "c2seatid": "POP000845",
            "c3seatid": "POP000845",
            "subjectId": 1
        },
        ....
 ],
    "timestamp": "2026-02-16 11:46:38"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK)
  * //message:// list of all documents associated with the specified entity
  * //errorCode:// Error Code if sending fails.

==== Example ====

<code bash>
curl --location 'https://peppol.eso9.cz/accesspoint/api/peppol/documents?from=2026-01-01T15%3A00%3A00&to=2026-02-15T00%3A00%3A00' \
--header 'Authorization: Bearer ••••••'
</code>

===== Retrieval of previously undownloaded documents =====

Retrieves a list of documents with the status “not yet downloaded” in the Access Point.

  * //URL:// [[{{URL}}/api/peppol/undownloaded|{{URL}}/api/peppol/undownloaded]]
  * //HTTP method:// GET
  * //Authentication:// Bearer token obtained by calling the ''AUTH'' method
  * //Headers://
    * Accept: ''*/*''
    * Content-Type: application/xml
    * Authorization: Bearer 89puKGci...
  * //Body:// none
  * //Returns:// JSON in structure:

<code json>
{
    "statusCode": 200,
    "message": [
        {
            "id": 1,
            "sender": "9950:sk2022706521",
            "resolvedDocumentFileType": "Generic.Invoice",
            "documentTypeIdentifier": "busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
            "processTypeIdentifier": "cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
        },
        ....
    ],
    "timestamp": "2026-02-16 11:54:40"
}
</code>

  * //statusCode:// HTTP status, e.g. 200 (OK)
  * //message:// list of undownloaded documents associated with the specified entity
  * //errorCode:// Error Code if sending fails.

==== Example ====

<code bash>
curl --location 'https://peppol.eso9.cz/accesspoint/api/peppol/undownloaded' \
--header 'Authorization: Bearer ••••••'
</code>