Version: 1.0.0

Slovakia E-Invoice Peppol

How to get “API Key” from Portal ?

To obtain the API key to be used in the request body of the login endpoint,

navigate to Settings > ERP Management > API Management in the Portal and use the "Generate" button.

Technical Details

Property	Value
Endpoint	/auth/login
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	None (Initial access)

Request Body (JSON)

The following fields are used to define login criteria:

Field	Type	Description
apiKey	String	A unique key assigned specifically to the user for portal access, verifying the system identity. (it is explained in previous section “How to get API Key from portal”)
email	String	The registered email address in the system belonging to the authorized user performing the operation.

Response Details

Upon a successful request, a 200 OK code is returned with the following details:

Field	Type	Description
jwt	—	The secure session token that must be used as a 'R-Auth' API Key in all subsequent API calls.
expirationDate	DateTime	Indicates the exact time the session key will expire; the ERP system can use this data to manage automatic re-login processes.

The JWT token successfully obtained during the authentication step (auth/login) acts as a key to access the secure endpoints of the APIs. After the first successful login, the JWT token obtained from the response of a successful login is used as the R-Auth value in the authorization section of other queries. This configuration ensures that every data exchange between the ERP and the portal occurs over an authenticated and secure channel.

Technical Details

Property	Value
Key	Enter R-Auth in the Key field.
Value	`{{apiKey}}` or `{{jwt}}` (Copy the jwt string returned from the login endpoint.)
Header Setting	Navigate to the "Headers" tab of the request to be sent.

1. Introduction

This guide is structured to allow development teams to incorporate portal features into their business workflows with minimum effort and maximum compliance.

2. Authentication POST

Purpose of Use: This endpoint is utilized by ERP systems to obtain the session key (JWT Token) required to establish a secure connection and initiate data exchange with the docnova portal.

An enterprise ERP system must trigger this endpoint to receive a valid authentication token before performing actions such as transmitting invoices or querying compliance reports via the portal. The acquired token is then provided in the "Authorization" header for all subsequent API requests. This mechanism ensures that data traffic between the ERP and the portal is conducted via a secure, time-bound key rather than transmitting sensitive user credentials for every transaction.

Endpoint Information

Property	Value
URL	/auth/login
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Not required (public endpoint)

Example Request

curl --location 'https://api-stage.docnova.ai/auth/login' \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --data-raw '{
    "apiKey": "{{your_api_key}}",
    "email": "user@example.com"
  }'

Request Parameters

Field	Type	Required	Description
email	String	Optional	User's registered email address
apiKey	String	Yes	Obtained from the portal, via the settings > ERP Management > API Management menu.

Responses

Full Response (AccountInfo)

{  
 "id": "b32636cd-ec05-4c48-b102-...",  
 "superAdmin": true,  
 "companies": [  
 {  
 "id": "ba876f6b-e20d-48b4-9ce8-...",  
 "name": "Demo Slovakia s.r.o.",  
 "taxNumber": "2029999999",  
 "website": null,  
 "address": "Testovacia 123",  
 "city": "Bratislava",  
 "state": null,  
 "country": "SK",  
 "portalType": "DEFAULT",  
 "postalCode": "81101",  
 "phoneNumber": null,  
 "credit": 5,  
 "iconUrl": null,  
 "email": "test@demo-slovakia.example",  
 "userCount": 1,  
 "vatNumber": "SK2029999999",  
 "siretNumber": null,  
 "frVatRegime": null,  
 "faxNumber": null,  
 "mailLanguage": "EN",  
 "subscriptionType": "6rtHLfnEgfyT7US9XKxVP0s6V4bzDF/mGGe8S/fIatQ=",  
 "cif": null,  
 "sftp": false,  
 "isSubCompany": false,  
 "participants": [],  
 "featureAllowed": false,  
 "subCompanies": [],  
 "stripeObj": {  
 "stripeCustomerId": "cus_V4PXDBMLV4t6dV",  
 "type": "FREE",  
 "renewalDate": "2026-09-14T08:43:23",  
 "docnovaAiProductCredits": 0,  
 "docnovaAiFeatureCredits": 0,  
 "googleAiFeatureCredits": 0,  
 "renewal": true  
 },  
 "authorities": "WqvBsTh6Pd8fcwTOW93xQB7b6jCQyv/530wsgy5dBU4=",  
 "compAuthTypes": "Pv24DAWwUcFHwNEg2oKn8vtYU6DqlUpw4VGiJ1afT1M=",  
 "currencyCode": "EUR",  
 "remainingDocumentPercentage": 0.0,
 "remainingPromotionDays": null,  
 "trialUsed": false,  
 "defaultParticipantId": null  
 }  
 ],  
 "jwt": "eyJhbGciOiJIUzUxMiJ9...",  
 "expirationDate": "2026-08-15T08:48:38.587+00:00",  
 "user": {  
 "id": null,  
 "email": "ayse.arslan@melasoft.com",  
 "firstName": "Ayşe",  
 "lastName": "Arslan",  
 "phoneNumber": "905419717819",  
 "creationTime": null,  
 "photoUrl": "https://graph.microsoft.com/v1.0/me/photo/$value",  
 "mailLang": "MS",  
 "isSuperAdmin": null,  
 "lastLoginTime": null,  
 "authorities": null,  
 "adminAuthorities": "ah+hOi4mUW5o7WqqHQW+FZZBApX8Th/...",  
 "featureAllowed": false  
 },  
 "mfaEnabled": true,  
 "secretImageUri": null,  
 "lastCompanyId": "ba876f6b-e20d-48b4-9ce8-cd650ccb6182",  
 "requiresRecaptchaV2": null,  
 "message": null,  
 "active": true,  
 "isAppLogin": false,  
 "mfaType": "EMAIL",  
 "refreshToken": "qI8a9ize1vax_2Yj5EYG-RB8pTLEyM7oZGfo_AHctGspBSCCKgIJtjM-...",  
 "refreshTokenExpiration": "2026-09-13T08:48:38.592+00:00"  
}  

Basic Response (JwtBasicResponse)

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expirationDate": "2026-01-30T10:30:00.000Z"
}

Response Fields

Account Information Fields

Field	Type	Description
id	String	User unique identifier
superAdmin	Boolean	Whether user has super admin privileges
companies	Array<AuthorizedCompany>	List of companies user is authorized to access
jwt	String	JWT access token. Used in R-Auth header for API requests
expirationDate	DateTime	JWT token expiration date
refreshToken	String	Refresh token for obtaining new access tokens
refreshTokenExpiration	DateTime	Refresh token expiration date
user	Object	User detail information
mfaEnabled	Boolean	Whether multi factor authentication is enabled
mfaType	Enum	MFA type (GOOGLE, WHATSAPP)
secretImageUri	String	Google Authenticator QR code URI
lastCompanyId	String	Last selected company ID
requiresRecaptchaV2	Boolean	Whether reCAPTCHA v2 verification is required
message	String	Status message (e.g., "MFA required")
active	Boolean	Whether user account is active
isAppLogin	Boolean	Whether this is a mobile app login

Parameter Values Reference Table

currentCountry Values (Sample List)

Value	Description
DE	Germany
AT	Austria
RO	Romania
KZ	Kazakhstan
TR	Turkey
FI	Finland
FR	France
IT	Italy
NL	Netherlands
ES	Spain
SE	Sweden
PL	Poland
BE	Belgium
DK	Denmark
NO	Norway
MY	Malaysia
SG	Singapore
AU	Australia
NZ	New Zealand
JP	Japan
EG	Egypt
RS	Serbia
SK	Slovakia
GLOBAL	Global (default)

Company Information Fields

Field	Type	Description
id	String	Company unique identifier
name	String	Company name
taxNumber	String	Tax number
vatNumber	String	VAT number
email	String	Company email address
website	String	Company website
address	String	Address
city	String	City
state	String	State or Region
country	Enum	Country code
postalCode	String	Postal code
phoneNumber	String	Phone number
faxNumber	String	Fax number
credit	Integer	Available credit
userCount	Integer	Total user count
portalType	Enum	Portal type
mailLanguage	Enum	Email language
currencyCode	String	Currency code
sftp	Boolean	Whether SFTP integration is active
isSubCompany	Boolean	Whether it's a sub company
featureAllowed	Boolean	Whether feature access is granted
participants	Array	Peppol participant information

User Information Fields

Field	Type	Description
id	String	User unique identifier
email	String	User email address
firstName	String	User first name
lastName	String	User last name
phoneNumber	String	User phone number
photoUrl	String	User photo URL
mailLang	Enum	User email language
isSuperAdmin	Boolean	Whether user has super admin privileges
lastLoginTime	DateTime	Last login time
featureAllowed	Boolean	Whether feature access is granted

Enum Values Reference Table

mfaType Values

Value	Description
GOOGLE	Google Authenticator verification
WHATSAPP	WhatsApp verification

portalType Values

Value	Description
DEFAULT	Default portal
RECHNUNG	Germany main portal
KZ	Kazakhstan portal
RO	Romania portal
AU	Australia portal
AT	Austria portal
BE	Belgium portal
DK	Denmark portal
EG	Egypt portal
FI	Finland portal
FR	France portal
IT	Italy portal
MY	Malaysia portal
NL	Netherlands portal
NO	Norway portal
PL	Poland portal
RS	Serbia portal
SK	Slovakia portal
SE	Sweden portal
SG	Singapore portal

mailLanguage Values

Value	Description
DE	German
EN	English
TR	Turkish
RO	Romanian
PL	Polish
FR	French
IT	Italian
ES	Spanish
NL	Dutch

401 - Unauthorized

{
  "timestamp": "2026-01-29T10:30:00.000Z",
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid email or password"
}

403 - MFA Required

{
  "id": "user-uuid",
  "mfaEnabled": true,
  "mfaType": "GOOGLE",
  "message": "MFA verification required",
  "jwt": null
}

429 - Too Many Requests

{
  "timestamp": "2026-01-29T10:30:00.000Z",
  "status": 429,
  "error": "Too Many Requests",
  "message": "Too many failed login attempts. Please try again later.",
  "requiresRecaptchaV2": true
}

3. Search Processing History POST

Purpose of Use: The POST /invoice/document-process/search endpoint serves as the central monitoring and querying interface for all document processing activities within the system. Every document whether it is an invoice, credit note, or waybill that enters or leaves the platform passes through an asynchronous processing pipeline. This endpoint provides full visibility into that pipeline.

Endpoint Information

Property	Value
URL	/invoice/document-process/search
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	R-Auth header (JWT token)
Required Authority	ADMIN, INCOMING_INVOICE_DISPLAY, or OUTGOING_INVOICE_DISPLAY (at least one)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/document-process/search?page=0&size=20&sort=createdAt,desc' \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --header 'R-Auth: <JWT_TOKEN>' \
  --data '{
    "companyId": "<COMPANY_UUID>",
    "createdAt": {
      "from": "2024-01-01",
      "to": "2026-02-28"
    }
  }'

Request Parameters

Field	Type	Required	Description
companyId	UUID	Yes	Unique identifier of the company to search
direction	String (Enum)	No	Document direction filter (INCOMING or OUTGOING)
source	String (Enum)	No	Source system filter
filename	String	No	Exact match filter by filename
status	String (Enum)	No	Document processing status filter
createdAt	Object (DateRange)	No	Creation date range filter
createdAt.from	String (LocalDate)	No	Start date (inclusive). Format: yyyy-MM-dd. Must be past or present
createdAt.to	String (LocalDate)	No	End date (inclusive). Format: yyyy-MM-dd. Must be past or present

Query Parameters (Pagination)

Field	Type	Default	Description
page	Integer	0	Page number (0 indexed)
size	Integer	20	Number of records per page (max 100)
sort	String	createdAt,desc	Sort field and direction. Format: field,asc\|desc

Enum Value Reference

direction Values (Document Direction)

Value	Description
INCOMING	Incoming document
OUTGOING	Outgoing document

status Values (Processing Status)

Value	Description
PENDING	Queued and waiting for processing
PROCESSING	Currently being processed
COMPLETED	Successfully completed
FAILED	Processing failed (retriable)
SENDING_FAILED	Failed at the sending stage
PERMANENT_FAILED	Permanently failed (will not be retried)

source Values (Source and Target System)

Value	Description
ERP	ERP integration
PORTAL	Web portal
PORTAL_OCR	Portal upload via OCR
EMAIL_OCR	OCR via email
EMAIL	Email
PEPPOL	Peppol network
SFTP	SFTP connection
KSEF	Poland KSeF system
ANAF	Romania ANAF system
LHDNM	Malaysia LHDNM system
NEMHANDEL	Denmark NemHandel
RS_API	Serbia API
ETA	Egypt ETA system
ERACUN	eRacun system
HARVEST	Harvest integration
SHOPIFY	Shopify integration
AMAZON_SP	Amazon SP API
EBAY	eBay integration
HUBSPOT	HubSpot integration
LAZADA	Lazada integration
STRIPE	Stripe integration
SERVICE	Internal service

documentType Values (Document Format)

Value	Description
PEPPOL_BIS	Peppol BIS 3.0
XRECHNUNG	XRechnung (UBL)
XRECHNUNG_CII	XRechnung (CII)
ZUGFERD	ZUGFeRD
FACTUR_X	Factur X
CII	Cross Industry Invoice
CID	CID format
RO_EFACTURA	Romania e Factura
MY_INVOIS	Malaysia MyInvois
MY_PINT	Malaysia PINT
DK_OIOUBL	Denmark OIOUBL
EG_INVOICE	Egypt invoice
HR_INVOICE	Croatia invoice
UAE_PINT	UAE PINT
KZ_ESF_V2	Kazakhstan ESF v2
KSEF	Poland KSeF
KSEF_OFFLINE	Poland KSeF (offline)

waybillType Values (Waybill Type)

Value	Description
RS_WAYBILL_DESPATCH	Serbia despatch waybill
RS_WAYBILL_RECEIPT	Serbia receipt waybill
RS_APPLICATION_RESPONSE	Serbia application response
RO_ETRANSPORT	Romania e Transport

Responses

200 - Successful Response

{
  "content": [
    {
      "trackingId": "a1b2c3d4-...",
      "companyId": "60ccd1a7-...",
      "direction": "INCOMING",
      "documentType": "PEPPOL_BIS",
      "waybillType": null,
      "source": "ERP",
      "target": "PEPPOL",
      "status": "COMPLETED",
      "filename": "invoice_2024_001.xml",
      "invoiceNumber": "INV-2024-001",
      "documentId": "f5e6d7c8-...",
      "sendingResult": "OK",
      "errorType": null,
      "errors": null,
      "additionalData": null,
      "createdAt": "2024-06-15T10:30:00",
      "statusUpdatedAt": "2024-06-15T10:30:45",
      "completedAt": "2024-06-15T10:31:00"
    }
  ],
  "totalElements": 150,
  "totalPages": 8,
  "number": 0,
  "size": 20
}

Response Fields

Field	Type	Description
content	Array<Object>	Page content (document processing records)
content[].trackingId	UUID	Processing tracking identifier
content[].companyId	UUID	Company identifier
content[].direction	String (Enum)	Document direction (INCOMING / OUTGOING)
content[].documentType	String (Enum)	Document format (see documentType enum table)
content[].waybillType	String (Enum) \| null	Waybill type (only for waybill documents)
content[].source	String (Enum)	Source system of the document
content[].target	String (Enum) \| null	Target system for the document
content[].status	String (Enum)	Current processing status
content[].filename	String	Original filename
content[].invoiceNumber	String \| null	Invoice number
content[].documentId	UUID \| null	Associated document identifier
content[].sendingResult	String \| null	Sending result message
content[].errorType	String (Enum) \| null	Error type code (on failed processes)
content[].errors	Object \| null	Error details (validation errors, message list, or text)
content[].additionalData	Object \| null	Country or document type specific metadata
content[].createdAt	String (DateTime)	Creation timestamp. Format: yyyy-MM-ddTHH:mm:ss
content[].statusUpdatedAt	String (DateTime)	Last status update timestamp
content[].completedAt	String (DateTime) \| null	Completion timestamp (only when COMPLETED)
totalElements	Long	Total number of matching records
totalPages	Integer	Total number of pages
number	Integer	Current page number (0-indexed)
size	Integer	Number of records per page

400 - Bad Request

Trigger: When the companyId field is sent as null in the request body (@NotNull validation) or when required fields are missing.
Scenario: Sending a request without providing companyId.

{
  "errorMessage": "Document process required fields: companyId",
  "errorType": "DOCUMENT_PROCESS_REQUIRED_FIELDS",
  "errorTitle": "BAD_REQUEST",
  "errorId": "corr-8f2a1b3c",
  "status": 400,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/document-process/search"
}

400 - Bad Request

Trigger: When the request body JSON format is malformed, an invalid enum value is sent, or the date format is incorrect.

Scenario: Sending a value like "UNKNOWN_STATUS" that is not defined in the enum for the status field, or sending an invalid date like "2024-13-45" for the createdAt.from field.

{
  "errorMessage": "Invalid request. Cannot deserialize value of type `DocumentProcessStatus` from String \"UNKNOWN_STATUS\"",
  "errorType": "INVALID_REQUEST",
  "errorTitle": "BAD_REQUEST",
  "errorId": "corr-4d5e6f7a",
  "status": 400,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/document-process/search"
}

401 - Unauthorized

Trigger: When the R-Auth header is not provided or the JWT token signature is invalid. This error is caught at the Spring Security filter chain and does not reach the RestExceptionHandler.

Scenario: Sending a request without the header or with a corrupted/tampered token.

{
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource",
  "status": 401
}

401 - Unauthorized

Trigger: When the JWT token is valid but the user does not have any of the ADMIN, INCOMING_INVOICE_DISPLAY, or OUTGOING_INVOICE_DISPLAY authorities on the specified companyId. Thrown by AuthorizationService.checkAnyAuthorityByCompanyAndUser().

Scenario: Performing a search with a companyId for which the user has no access permissions.

{ 

  "errorMessage": "User is not authorized for this operation", 
  "errorType": "AUTHORIZATION_FAILED", 
  "errorTitle": "UNAUTHORIZED", 
  "errorId": "corr-9a8b7c6d", 
  "status": 401, 
  "timestamp": "2026-02-11T14:30:00", 
  "path": "/invoice/document-process/search" 
} 

404 - Not Found

Trigger: When the provided companyId value is not found in the database. A NotFoundException is thrown by CompanyService.

Scenario: Sending a UUID as companyId that has been deleted or never existed.

{
  "errorMessage": "Company not found!",
  "errorType": "COMPANY_NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "errorId": "corr-1b2c3d4e",
  "status": 404,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/document-process/search"
}

498 - Token Expired

Trigger: When the JWT token has expired. Returned by CustomAuthenticationEntryPoint at the Spring Security filter level.

Scenario: Sending a request with an expired JWT token.

{
  "errorMessage": "Your session has expired. Please login again.",
  "errorType": "TOKEN_EXPIRED",
  "errorTitle": "UNAUTHORIZED",
  "status": null,
  "timestamp": null,
  "path": null
}

Note: Since this response is generated at the Security filter level, the timestamp, path, and status fields are not populated by enrichResponse and return null. A custom HTTP status code of 498 is used.

500 - Internal Server Error

Trigger: When an unexpected error occurs on the server side (database connection failure, NullPointerException, etc.). Caught by the RestExceptionHandler catch-all handler.

Scenario: Database access failure, unexpected runtime exception.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "SERVER_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "errorId": "corr-5e6f7a8b",
  "status": 500,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/document-process/search"
}

Response Structure Reference (ExceptionResponse)

Field	Type	Description	Inclusion Condition
errorMessage	String	Human readable error description	Always
errorType	String	Machine readable error code (ErrorType enum name)	Always
errorTitle	String (HttpStatus)	HTTP status description (BAD_REQUEST, UNAUTHORIZED, etc.)	Always
errorId	String	Correlation ID (for log tracing)	If present in ThreadContext
status	Integer	HTTP status code (numeric)	Always
timestamp	String (DateTime)	Timestamp when the error occurred	By RestExceptionHandler
path	String	URI of the request	By RestExceptionHandler
data	String	Additional data information	If present (@JsonInclude NON_NULL)
details	Map<String, Object>	Additional detail information	If present (@JsonInclude NON_NULL)
validationErrors	Array<ValidationError>	Field level validation errors	If present (@JsonInclude NON_NULL)

Note: The ExceptionResponse class uses @JsonInclude(JsonInclude.Include.NON_NULL). Therefore, fields with null values are excluded from the JSON response.

4. Send Document Async POST

Purpose of Use: This endpoint enables ERP systems to transmit e-invoice data to the docnova portal asynchronously. It is designed to enhance system responsiveness and efficiently manage the process queue during high-volume data transfers. After generating an invoice in compliance with Slovak legal standards (Peppol BIS Billing 3.0, UBL format, aligned with EN 16931), the ERP system converts the document into base64 format and transmits it to the portal. Since this method operates asynchronously, the ERP system receives a tracking ID (trackingId) without waiting for the full processing of the document. This prevents delays in ERP-side workflows, and the final status of the document can be queried later using the provided tracking ID.

Endpoint Information

Property	Value
URL	/invoice/send-document-async
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	JWT Token (R-Auth header) or API Key

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/send-document-async' \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --header 'R-Auth: {{jwt_token}}' \
  --data-raw '{
    "apiKey": "{{your_api_key}}",
    "base64Document": "{{base64_encoded_xml}}",
    "base64Pdf": "{{base64_encoded_pdf}}",
    "businessType": "B2B",
    "compId": "{{company_uuid}}",
    "invoiceType": "PEPPOL_BIS",
    "receiverEmails": [
      "recipient@example.com"
    ],
    "mailTemplateId": "{{template_id}}"
  }'

Request Parameters

Field	Type	Required	Description
compId	String (UUID)	Conditional*	Company unique identifier. Required if apiKey is not provided.
apiKey	String	Conditional*	API key. Required if compId is not provided.
base64Document	String	Conditional**	Base64-encoded XML document. Required if base64Pdf is not provided.
base64Pdf	String	Conditional**	Base64-encoded PDF document. Required if base64Document is not provided.
invoiceType	Enum	Conditional***	Invoice format type. Required if waybillType is not provided.
waybillType	Enum	Conditional***	Waybill format type. Required if invoiceType is not provided.
businessType	Enum	No	Business model type (B2B, B2C, B2G).
receiverEmails	Array<String>	No	List of recipient email addresses.
mailTemplateId	String	No	Email template identifier.

Note:

(*) At least one of compId or apiKey must be provided.
(**) At least one of base64Document or base64Pdf must be provided.
(***) At least one of invoiceType or waybillType must be provided.

businessType Values

Value	Description
B2B	Business to Business
B2C	Business to Consumer
B2G	Business to Government

invoiceType Values

Value	Group	Description
PEPPOL_BIS	XRECHNUNG	Peppol BIS 3.0 format
XRECHNUNG	XRECHNUNG	German XRechnung format
RO_EFACTURA	XRECHNUNG	Romania e-Factura format
ZUGFERD	ZUGFERD	ZUGFeRD format (PDF/A-3 with XML)
FACTUR_X	ZUGFERD	Factur-X format (France)
XRECHNUNG_CII	ZUGFERD	XRechnung CII profile
CII	ZUGFERD	Cross Industry Invoice format
CID	ZUGFERD	CID format
PDF	ZUGFERD	PDF format
MY_INVOIS	Country-Specific	Malaysia MyInvois format
MY_PINT	Country-Specific	Malaysia PINT format
DK_OIOUBL	Country-Specific	Denmark OIOUBL format
EG_INVOICE	Country-Specific	Egypt e-Invoice format
HR_INVOICE	Country-Specific	Croatia e-Invoice format
UAE_PINT	Country-Specific	UAE PINT format
KZ_ESF_V2	Kazakhstan	Kazakhstan ESF v2
KSEF	Poland	Poland KSeF format
KSEF_OFFLINE	Poland	Poland KSeF offline

waybillType Values

Value	Description
RS_WAYBILL_DESPATCH	Serbia despatch waybill
RS_WAYBILL_RECEIPT	Serbia receipt waybill
RS_APPLICATION_RESPONSE	Serbia application response
RO_ETRANSPORT	Romania e-Transport

Responses

200 - Successful Response

{
  "trackingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PENDING",
  "message": "Document queued for processing"
}

Response Fields

Field	Type	Description
trackingId	UUID	Unique process tracking identifier. This ID can be used to query the processing status.
status	Enum	Current status of the process.
message	String	Descriptive message about the status.

status Values

Value	Description
PENDING	Process queued, not yet started
PROCESSING	Process in progress
COMPLETED	Process completed successfully
FAILED	Process failed
SENDING_FAILED	Sending failed
PERMANENT_FAILED	Permanent failure, will not be retried

400 - Bad Request

{
  "trackingId": null,
  "status": "FAILED",
  "message": "Either invoiceType or waybillType must be provided"
}

401 - Unauthorized

{
  "timestamp": "2026-01-29T10:30:00.000Z",
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

500 - Internal Server Error

{
  "trackingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "FAILED",
  "message": "An unexpected error occurred"
}

5. Document Status GET

Purpose of Use: The GET /invoice/document-status/{trackingId} endpoint is used to query the processing status of documents (invoices, waybills, etc.) that were submitted asynchronously.

When a document is submitted through any of the send-document-async, send-document-async-json, send-by-file-async, or send-portal-new-async endpoints, the system immediately returns a trackingId and begins processing the document in the background.

Polling stops when the status becomes COMPLETED or FAILED.

Endpoint Information

Property	Value
URL	/invoice/document-status/{trackingId}
Method	GET
Authorization	R-Auth header (JWT token)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/document-status/{trackingId}' \ 

--header 'Accept: */*' \ 

--header 'R-Auth: {JWT_TOKEN}' 
  }'

Request Parameters

Path Parameters

Field	Type	Required	Description
trackingId	UUID	Yes	The tracking identifier returned from an asynchronous document submission. This is the trackingId value included in the response of send-document-async, send-document-async-json, send-by-file-async, or send-portal-new-async endpoints.

Header Parameters

Field	Type	Required	Description
R-Auth	String (JWT)	Yes	User authentication token. A JWT signed with the HS512 algorithm. The payload carries userId, companyId, authorities, and userType information.
Accept	String	No	Response media type. Default: /

Responses

200 - Successful Response

{
  "trackingId": "e20a112a-fcb2-4da2-9efd-...",
  "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
  "direction": "OUTGOING",
  "documentType": "PEPPOL_BIS",
  "waybillType": null,
  "source": "ERP",
  "target": null,
  "status": "COMPLETED",
  "filename": "invoice_2025.xml",
  "invoiceNumber": "INV-2025-001234",
  "documentId": "f47ac10b-58cc-4372-a567-...",
  "sendingResult": "SUCCESS",
  "errorType": null,
  "errors": null,
  "additionalData": null,
  "createdAt": "2025-06-15T10:30:00",
  "statusUpdatedAt": "2025-06-15T10:30:45",
  "completedAt": "2025-06-15T10:30:45"
}

Success Response Field Descriptions

Field	Type	Description
trackingId	UUID	Unique tracking identifier for the document processing
companyId	UUID	Unique identifier of the company the document belongs to
direction	String (Enum)	Document direction: INCOMING or OUTGOING
documentType	String (Enum)	Document format (e.g.,PEPPOL BIS)
waybillType	String (Enum)	Waybill type. Only populated for waybill operations
source	String (Enum)	Source platform the document was submitted from (e.g., ERP, PORTAL)
target	String (Enum) \| null	Target platform for the document
status	String (Enum)	Current processing status: PENDING, PROCESSING, COMPLETED, FAILED, SENDING_FAILED, PERMANENT_FAILED
filename	String	Name of the processed file
invoiceNumber	String \| null	Invoice number assigned to the document. Populated when processing completes
documentId	UUID \| null	Unique system identifier of the created document. Populated when processing completes
sendingResult	String \| null	Sending result (e.g., SUCCESS, SENT_TO_PEPPOL). Populated when processing completes
errorType	String (Enum) \| null	Error category when an error occurs. Null for successful operations
errors	Object \| null	Error details. Variable type: can be List<ValidationError>, List<String>, or String
additionalData	Object	Country specific additional metadata. Structure varies by country/document type (e.g., Poland KSeF: `ksefNumber`, Romania: `submissionId`)
createdAt	DateTime	Timestamp when the processing record was created (ISO 8601)
statusUpdatedAt	DateTime	Timestamp when the status was last updated (ISO 8601)
completedAt	DateTime \| null	Timestamp when processing completed. Null while processing is ongoing

Parameter Value Reference

DocumentProcessStatus — Possible Status Values

Value	Description
PENDING	Document is queued, processing has not started yet
PROCESSING	Document is actively being processed (conversion, validation, sending, etc.)
COMPLETED	Document processing completed successfully
FAILED	An error occurred during document processing (may be retried)
SENDING_FAILED	Document was created but failed during the sending phase
PERMANENT_FAILED	Document processing permanently failed (will not be retried)

DocumentType — Document Direction

Value	Description
INCOMING	Incoming document
OUTGOING	Outgoing document

DataType — Document Format

Value	Description
PEPPOL_BIS	Peppol BIS 3.0 UBL format
XRECHNUNG	XRechnung (Germany) UBL format
RO_EFACTURA	Romania eFactura format
MY_INVOIS	Malaysia MyInvois format
MY_PINT	Malaysia PINT format
DK_OIOUBL	Denmark OIOUBL format
EG_INVOICE	Egypt e-Invoice format
HR_INVOICE	Croatia e-Invoice format
UAE_PINT	UAE PINT format
ZUGFERD	ZUGFeRD format
FACTUR_X	Factur-X (France) format
XRECHNUNG_CII	XRechnung CII format
CII	UN/CEFACT CII format
PDF	Unstructured PDF (paper invoices, images, etc.)
KSEF	Poland KSeF format
KSEF_OFFLINE	Poland KSeF Offline format
KZ_ESF_V2	Kazakhstan ESF v2 format

WaybillDataType — Waybill Type

Value	Description
RS_WAYBILL_DESPATCH	Serbia despatch waybill
RS_WAYBILL_RECEIPT	Serbia receipt waybill
RS_APPLICATION_RESPONSE	Serbia application response
RO_ETRANSPORT	Romania eTransport waybill

ErrorType — Error Types Specific to This Endpoint

Value	Message
INVOICE_PROCESS_NOT_FOUND	Tracking ID not found
VALIDATION_FAILED	Validation failed!
INVOICE_NULL_COULD_NOT_SAVE	Invoice is NULL and/or could not be saved!
ZUGFERD_VALIDATION_ERROR	ZUGFeRD validation error
INVOICE_CREATION_FAILED	Invoice creation failed!
INVOICE_SENDING_FAILED	Invoice sending failed: {details}

401 - Unauthorized

Returned when the R-Auth header is missing, contains an invalid JWT token, or the token has expired.

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource"
}

Detail	Description
HTTP Status	401 Unauthorized
Trigger	JWT token is missing, malformed, expired, or signature verification failed
Resolution	Send a valid, non-expired JWT token in the R-Auth header

404 - Not Found

Returned when the provided trackingId does not exist in the database.
Response Body: null (body is empty)

Detail	Description
HTTP Status	404 Not Found
Response Body	null (body is empty)
Trigger	No DocumentProcessEntity record matches the given trackingId in the database
Internal Error Type	INVOICE_PROCESS_NOT_FOUND — "Tracking ID not found"
Resolution	Verify the trackingId value is correct. Use the value returned in the response of the async submission endpoint

500 - Internal Server Error

Returned when an unexpected server error occurs during the status query.
Response Body: null (body is empty)

Detail	Description
HTTP Status	500 Internal Server Error
Response Body	null (body is empty)
Trigger	Database connection failure, entity conversion error, or other unexpected runtime exceptions
Resolution	Check server logs. Contact the support team if the issue persists

Status-Based Response Examples

PENDING — Queued for Processing

{ 
    "trackingId": "e20a112a-fcb2-4da2-9efd-...",
    "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
    "direction": null,
    "documentType": "PEPPOL_BIS",
    "status": "PENDING",
    "documentId": null,
    "invoiceNumber": null,
    "sendingResult": null,
    "errorType": null,
    "errors": null,
    "createdAt": "2025-06-15T10:30:00",
    "statusUpdatedAt": "2025-06-15T10:30:00",
    "completedAt": null  
}

PROCESSING — Currently Processing

{
    "trackingId": "e20a112a-fcb2-4da2-9efd-...",
    "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
    "direction": "OUTGOING",
    "documentType": "PEPPOL_BIS",
    "status": "PROCESSING",
    "documentId": "f47ac10b-58cc-4372-a567-...",
    "invoiceNumber": "INV-2025-001234",
    "sendingResult": null,
    "errorType": null,
    "errors": null,
    "createdAt": "2025-06-15T10:30:00",
    "statusUpdatedAt": "2025-06-15T10:30:20",
    "completedAt": null
}

FAILED — Processing Failed (Validation Error)

{  
    "trackingId": "e20a112a-fcb2-4da2-9efd-...",
    "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
    "direction": null,
    "documentType": "PEPPOL_BIS",
    "status": "FAILED",
    "documentId": null,
    "invoiceNumber": null,
    "sendingResult": null,
    "errorType": "VALIDATION_FAILED",
    "errors": [
      {
        "field": "invoiceNumber",
        "message": "Invoice number is required"
      },
      {
        "field": "issueDate",
        "message": "Issue date format is invalid"
      }
    ],
    "createdAt": "2025-06-15T10:30:00",
    "statusUpdatedAt": "2025-06-15T10:30:15",
    "completedAt": "2025-06-15T10:30:15"
  
}

FAILED — Processing Failed (General Error)

{
   "trackingId": "e20a112a-fcb2-4da2-9efd-...",
    "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
    "direction": "OUTGOING",
    "documentType": "PEPPOL_BIS",
    "status": "FAILED",
    "documentId": null,
    "invoiceNumber": null,
    "sendingResult": null,
    "errorType": "INVOICE_NULL_COULD_NOT_SAVE",
    "errors": [
      "Invoice is NULL and/or could not be saved! XML parsing error at line 42"
    ],
    "createdAt": "2025-06-15T10:30:00",
    "statusUpdatedAt": "2025-06-15T10:30:12",
    "completedAt": "2025-06-15T10:30:12"
}

SENDING_FAILED — Sending Failed

{
  "trackingId": "e20a112a-fcb2-4da2-9efd-...",
    "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
    "direction": "OUTGOING",
    "documentType": "PEPPOL_BIS",
    "status": "SENDING_FAILED",
    "documentId": "f47ac10b-58cc-4372-a567-...",
    "invoiceNumber": "INV-2025-001234",
    "sendingResult": null,
    "errorType": "INVOICE_SENDING_FAILED",
    "errors": [
      "Invoice sending failed: Peppol access point unreachable"
    ],
    "createdAt": "2025-06-15T10:30:00",
    "statusUpdatedAt": "2025-06-15T10:31:00",
    "completedAt": "2025-06-15T10:31:00"
}

COMPLETED — With Country-Specific Metadata (Poland KSeF)

{
    "trackingId": "e20a112a-fcb2-4da2-9efd-...",
    "companyId": "a1b2c3d4-e5f6-7890-abcd-...",
    "direction": "OUTGOING",
    "documentType": "KSEF",
    "status": "COMPLETED",
    "documentId": "f47ac10b-58cc-4372-a567-...",
    "invoiceNumber": "FA/2025/06/001",
    "sendingResult": "SUCCESS",
    "errorType": null,
    "errors": null,
    "additionalData": {
      "sessionReferenceNumber": "20250615-SE-ABC123",
      "invoiceReferenceNumber": "20250615-IR-DEF456",
      "ksefNumber": "1234567890-20250615-..."
    },
    "createdAt": "2025-06-15T10:30:00",
    "statusUpdatedAt": "2025-06-15T10:31:30",
    "completedAt": "2025-06-15T10:31:30"
  
}

6. Get Invoice/Document Status GET

Purpose of Use: This endpoint is used to query the real-time processing status of an invoice/document by using the trackingId returned from an asynchronous document submission request.

After an invoice or document is submitted through an async flow, the first response may only contain a trackingId. This endpoint allows the client to follow the internal processing lifecycle of that document, including whether it is queued, processing, failed, or completed.

Once a documentId has been assigned to the document, this endpoint also returns invoice-level status information such as invoiceStatus and invoiceStatusDate. If the document has not yet been assigned a final documentId, those fields may be null, and only the process-level status fields should be used.

The request requires that the authenticated user in the R-Auth JWT has authority over the queried companyId.

Endpoint Information

Property	Value
URL	/invoice/get-document-status-by-tracking
Method	GET
Content-Type	None — query parameters only, no request body
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	R-Auth: {{jwt_token}}

Example Request

curl -X GET 'https://api-stage.docnova.ai/invoice/get-document-status-by-tracking?companyId={{company_uuid}}&trackingId={{tracking_uuid}}' \
  -H 'accept: */*' \
  -H 'R-Auth: {{jwt_token}}'

Request Parameters

Field	Type	Required	Description
companyId	String(UUID)	Yes	Unique identifier of the company that the queried tracking record belongs to. The requesting user must hold a role in this company.
trackingId	String(UUID)	Yes	The tracking identifier returned in the response of the document's asynchronous submission request. The document status is looked up via this identifier.

Notes

The R-Auth header is mandatory.
The user in the JWT must have a role in the company matching companyId.
If trackingId is not associated with companyId, for example when trying to access a record belonging to another company, a 401 Unauthorized response is returned.
If the tracking process is found but no documentId has been assigned yet, only the process-level status fields are returned.

Responses

200 - Successful Response

{
  "trackingId": "{{tracking_uuid}}",
  "documentId": "{{document_uuid}}",
  "invoiceStatus": "SENT_TO_PEPPOL",
  "invoiceStatusDate": "2026-01-15T12:00:00",
  "processStatus": "COMPLETED",
  "processStatusUpdatedAt": "2026-01-15T12:00:00"
}

Description: Request succeeded. If the document has not yet been assigned a documentId, the documentId, invoiceStatus, and invoiceStatusDate fields are null, and only processStatus / processStatusUpdatedAt are meaningful.

Response Fields

Field	Type	Description
trackingId	String(UUID)	Echoes the `trackingId` sent in the request. Always populated.
documentId	String(UUID)	Populated once the document is assigned a final ID. `null` if the document has not yet been assigned.
invoiceStatus	String(Enum)	Populated once `documentId` is assigned. Contains the invoice's country/channel-specific final status. `null` if `documentId` is not yet assigned.
invoiceStatusDate	String(ISO8601)	Timestamp of the last update to `invoiceStatus`. `null` if `documentId` is not yet assigned.
processStatus	String(Enum)	Status of the document's own processing pipeline. Always populated, even before `documentId` is assigned.
processStatusUpdatedAt	String(ISO8601)	Timestamp of the last update to `processStatus`. Always populated.

Parameter Values Reference Table

processStatus Values

Value	Description
PENDING	Process has not started yet; queued.
PROCESSING	Document is currently being processed.
FAILED	Processing failed; may be retried.
SENDING_FAILED	An error occurred during the sending stage.
PERMANENT_FAILED	Permanent failure; will not be retried.
COMPLETED	Process completed successfully.

invoiceStatus Values

Value	Description
CREATED	Invoice/document has been created.
SAVED_AS_UBL	Saved in UBL format.
SAVED_AS_ZUGFERD	Saved in ZUGFeRD format.
SAVED_AS_FACTUR_X	Saved in Factur-X format.
SAVED_AS_CII	Saved in CII format.
SAVED_AS_CID	Saved in CID format.
READY_FOR_KSEF	Ready for submission to KSeF in Poland.
SENT_TO_ACCESS_POINT	Sent to the Access Point.
OCR_WAITING	Waiting for OCR processing.
OCR_PARSED	Successfully parsed by OCR.
OCR_FAILED	OCR processing failed.
OCR_PARSED_PENDING_PAYMENT	OCR completed, awaiting payment.
OCR_WAITING_TOKEN	Waiting for a token for OCR.
CANCELED	Canceled.
PENDING	Pending.
SAVED_AS_PDF	Saved as PDF.
DELETED	Deleted.
COMPLETED_BY_MELA_AI	Completed by Mela AI.
SENT_VIA_EMAIL	Sent via email.
SENT_VIA_SFTP	Sent via SFTP.
SENT_TO_PEPPOL	Sent to the Peppol network.
SUCCESS	Operation succeeded.
INVALID_PARAMETERS	Invalid parameters.
TRANSPORT_ERROR	Peppol transport error; no automatic retry.
TRANSPORT_ERROR_NO_RETRY	Peppol transport error; retry disabled.
NO_SIGNAL_MESSAGE_RECEIVED	No signal message received.
AS4_ERROR_MESSAGE_RECEIVED	AS4 error message received.
INVALID_SIGNAL_MESSAGE_RECEIVED	Invalid signal message received.
SMP_LOOKUP_FAILED	SMP lookup failed.
CREDIT_BLOCKED	Payment blocked due to credit limit.

All error responses share the following structure:

{
  "errorMessage": "<human-readable message>",
  "errorType": "<error type key>",
  "errorTitle": "<HTTP status name>",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/get-document-status-by-tracking"
}

400 - Bad Request

Tracking ID Not Found

{
  "errorMessage": "Tracking ID not found",
  "errorType": "INVOICE_PROCESS_NOT_FOUND",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/get-document-status-by-tracking"
}

Description: An ApiError(INVOICE_PROCESS_NOT_FOUND) is thrown when the trackingId is not found in the database.

Note: Although Swagger annotation documents this case as 404, the code currently calls withStatus() on this exception, so RestExceptionHandler returns the default 400 Bad Request.

401 - Unauthorized

{
  "errorMessage": "User is not authorized for this operation",
  "errorType": "AUTHORIZATION_FAILED",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/get-document-status-by-tracking"
}

Trigger: The user in the R-Auth JWT has no role or authority in the given companyId, or the trackingId belongs to a different company than the given companyId.

500 - Internal Server Error

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/get-document-status-by-tracking"
}

Trigger: An unexpected server-side error occurs.

This may happen because of a database connectivity issue, an unhandled exception, or another server-side runtime error.

7. Retrieve Doc by ID and Type GET

Purpose of Use: The GET /invoice/get-document/{documentId}/{documentTypes} endpoint allows downloading a previously stored invoice or document in a specific format such as PDF, XML, or JSON.

The client provides the document UUID (documentId) and the desired output format (documentTypes). The API returns the document content as Base64 encoded data. This is mainly used in ERP integrations to programmatically fetch, view, archive, or store invoice documents.

When the requested format is pdf, the API returns the printable or viewable PDF file content as Base64 encoded data.

Endpoint Information

Property	Value
URL	/invoice/get-document//{documentTypes}
Method	GET
Authorization	R-Auth header (JWT token)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/get-document/{documentId}/pdf' \
  --header 'Accept: */*' \
  --header 'R-Auth: {auth-token}'
  }'

Request Parameters

Path Parameters

Field Name	Type	Required	Description
documentId	String (UUID)	Yes	Unique identifier of the document. Must be in UUID v4 format. Example: 550e8400-e29b-41d4-a716-...
documentTypes	String (Enum)	Yes	Requested document format type. Multiple types can be separated by hyphen -. Example: PDF, XML

Header Parameters

Field Name	Type	Required	Description
R-Auth	String (JWT)	Yes	Authentication token. JWT signed with HS512 algorithm.
Accept	String	No	Accepted response media type. Default: /

documentTypes Parameter Values

Value	Format Type	Description
PDF	FormatType.PDF	Returns Base64-encoded PDF representation of the invoice
XML	FormatType.XML	Returns Base64-encoded UBL XML content of the invoice
JSON	FormatType.JSON	Returns Base64-encoded UBL DTO JSON content of the invoice
PDF-XML	Multiple formats	Multiple formats can be requested simultaneously using hyphen separator
XML-PDF-JSON	Multiple formats	All three formats can be requested at once

Note: JSON format is only supported for invoices processed by OCR (OCR_PARSED) or completed by MelAI (COMPLETED_BY_MELAI_AI).

Responses

200 - Successful Response

{
  "documents": [
    {
      "file_type": "PDF",
      "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC..."
    }
  ]
}

Successful Response Field Descriptions

Field Name	Type	Description
documents	List<Document>	List of documents in requested formats. Contains one Document object per format.
documents[].file_type	String (Enum)	Document format type. Possible values: PDF, XML, JSON
documents[].data	String (Base64)	Base64-encoded content of the document. When decoded for PDF, produces a valid PDF file.

Multi-Format Response Example

{
  "documents": [
    {
      "file_type": "XML",
      "data": "PD94bWwgdmVy... (base64)"
    },
    {
      "file_type": "PDF",
      "data": "JVBERi0xLjQK... (base64)"
    }
  ]
}

400 - Bad Request

Returned when an invalid documentTypes value is provided.

{ 

  "errorMessage": "Unsupported document type: DOCX", 
  "errorType": "INVALID_ARGUMENT", 
  "errorTitle": "BAD_REQUEST", 
  "errorId": "corr-def456", 
  "status": 400, 
  "timestamp": "2026-02-11T14:31:00", 
  "path": "/invoice/get-document/af6e8982-b791-4704-bc06-.../docx" 
} 

Field	Description
errorMessage	Specifies the unsupported document type and which type was invalid.
errorType	INVALID_ARGUMENT An invalid parameter was provided.
status	400

400 - Bad Request

Returned when the document's OCR processing has not yet completed (waiting state).

{
  "errorMessage": "Invoice is waiting for MelaAIParser. Please try again later",
  "errorType": "INVALID_ARGUMENT",
  "errorTitle": "BAD_REQUEST",
  "errorId": "corr-ghi789",
  "status": 400,
  "timestamp": "2026-02-11T14:32:00",
  "path": "/invoice/get-document/af6e8982-b791-4704-bc06-.../json"
}

Field	Description
errorMessage	Indicates the invoice has not been processed by MelaAI yet and should be retried later.
errorType	INVALID_ARGUMENT The invoice is not in a processable state currently.
status	400

401 - Unauthorized

Returned when an invalid or missing R-Auth token is provided.

{
  "errorMessage": "Authentication is required. Please complete the authentication process.",
  "errorType": "AUTHENTICATION_REQUIRED",
  "errorTitle": "UNAUTHORIZED",
  "errorId": "corr-abc123",
  "status": 401,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/get-document/af6e8982-b791-4704-bc06-.../pdf"
}

Field	Description
errorMessage	Indicates that the authentication process must be completed.
errorType	AUTHENTICATION_REQUIRED Token is missing, expired, or invalid.
status	401

404 - Not Found

Returned when no document matches the provided UUID. Specifically occurs when JSON format is requested and the invoice is not found.

{
  "errorMessage": "af6e8982-b791-4704-bc06-d4655faa4b4c Invoice not found!", 
  "errorType": "NOT_FOUND_INVOICE", 
  "errorTitle": "NOT_FOUND", 
  "errorId": "corr-jkl012", 
  "status": 404, 
  "timestamp": "2026-02-11T14:33:00", 
  "path": "/invoice/get-document/af6e8982-b791-4704-bc06-.../json" 
}

Field	Description
errorMessage	Returns a not found message along with the document UUID.
errorType	NOT_FOUND_INVOICE No matching invoice record exists in the database.
status	404

500 - Internal Server Error

Returned when an unexpected error occurs (e.g., file cannot be retrieved from S3, PDF conversion fails).

{ 

  "errorMessage": "Internal server error", 
  "errorType": "SERVER_ERROR", 
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "errorId": "corr-mno345", 
  "status": 500, 
  "timestamp": "2026-02-11T14:34:00", 
  "path": "/invoice/get-document/af6e8982-b791-4704-bc06-.../pdf"
} 

Field	Description
errorMessage	Generic server error message.
errorType	SERVER_ERROR An unexpected error occurred.
status	500

Common Error Response Field Descriptions

Field Name	Type	Description
errorMessage	String	Human readable description of the error
errorType	String	Programmatic classification code of the error
errorTitle	String (HttpStatus)	Text representation of the HTTP status code
errorId	String	Request correlation ID (for log tracking)
status	Integer	HTTP status code (numeric)
timestamp	String (ISO 8601)	Timestamp when the error occurred
path	String	Endpoint path where the error occurred
details	`Map<String, Object>`	Additional error details (if available)
validationErrors	`List<ValidationError>`	List of validation errors (if available)

8. Search Document with Filter POST

Purpose of Use: The POST /invoice/search-documents endpoint is used to search for invoices and documents belonging to a specific company using various filtering criteria.

This API enables users to list documents associated with their company by applying filters such as date range, document direction (incoming or outgoing), invoice status, and document format (PEPPOL BIS, XRECHNUNG, etc.). Results are returned with pagination support, and each page includes the total document count, tax exclusive total amount, and tax inclusive total amount.

Endpoint Information

Property	Value
URL	/invoice/search-documents
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	R-Auth header (JWT token)

Example Request

curl --location 'api-stage.docnova.ai/invoice/search-documents' \  
--header 'Content-Type: application/json' \  
--header 'Accept: */*' \  
--header 'R-Auth: eyJhbGciOiJIUzUxMiJ9....' \  
--data '{  
 "companyId": "cfffb7b0-608d-49e3-8aa2-8a81109680e2",  
 "documentType": "OUTGOING",  
 "endDate": "2026-06-14",  
 "page": 1,  
 "status": "SAVED_AS_UBL",  
 "size": 20,  
 "startDate": "2026-01-25",  
 "type": "PEPPOL_BIS"  
}'   

Request Parameters

Field	Type	Required	Description
companyId	UUID	Yes	Unique identifier of the company to search documents for
documentType	String (Enum)	No	Document direction filter. Used to filter incoming or outgoing documents
status	String (Enum)	No	Invoice status filter. Returns invoices in a specific status
type	String (Enum)	No	Document format type filter. Filters by invoice format
startDate	String (ISO Date)	No	Search start date. Format: YYYY-MM-DD
endDate	String (ISO Date)	No	Search end date. Format: YYYY-MM-DD
tin	String	No	Tax Identification Number filter
uit	String	No	UIT identifier filter
referenceDocument	String	No	Search by reference document number
page	Integer	No	Page number (0-based). Default: 0
size	Integer	No	Number of records per page. Default: 50

Parameter Values

documentType Values

Value	Description
INCOMING	Incoming documents (invoices sent by suppliers)
OUTGOING	Outgoing documents (invoices sent to customers)

type Values

Value	Group	Description
XRECHNUNG	UBL	German XRechnung format (UBL-based)
PEPPOL_BIS	UBL	Peppol BIS 3.0 format
RO_EFACTURA	UBL	Romanian e-Invoice format
UBL	UBL	General UBL 2.1 format
MY_INVOIS	MY_INVOIS	Malaysian MyInvois format
MY_PINT	MY_PINT	Malaysian PINT format
DK_OIOUBL	DK_OIOUBL	Danish OIOUBL format
EG_INVOICE	EG_INVOICE	Egyptian e-Invoice format
HR_INVOICE	HR_INVOICE	Croatian eRacun format
UAE_PINT	UAE_PINT	UAE PINT format
ZUGFERD	ZUGFERD	ZUGFeRD format (PDF + embedded XML)
FACTUR_X	ZUGFERD	French Factur-X format
XRECHNUNG_CII	ZUGFERD	XRechnung CII format
CII	ZUGFERD	UN/CEFACT CII format
CID	ZUGFERD	CID format
PDF	ZUGFERD	Unstructured invoices (paper, images, etc.)
KSEF	KSEF	Polish KSeF format
KSEF_OFFLINE	KSEF_OFFLINE	Polish KSeF offline format
KZ_ESF_V2	KZ_ESF_V2	Kazakhstan e-Invoice v2 format

Note: When using the type filter on the search-documents endpoint, only XRECHNUNG, ZUGFERD, and FACTUR_X values actively filter results. Other values return an empty result set.

status Values

Category	Value	Description
General	CREATED	Invoice created
	PENDING	Awaiting processing
	CANCELED	Cancelled
	DELETED	Deleted
	SENT_VIA_EMAIL	Sent via email
Saved	SAVED_AS_UBL	Saved as UBL
	SAVED_AS_ZUGFERD	Saved as ZUGFeRD
	SAVED_AS_FACTUR_X	Saved as Factur-X
	SAVED_AS_CII	Saved as CII
	SAVED_AS_CID	Saved as CID
	SAVED_AS_KSEF	Saved as KSeF
	SAVED_AS_PDF	Saved as PDF
OCR	OCR_WAITING	OCR processing pending
	OCR_PARSED	OCR completed successfully
	OCR_FAILED	OCR processing failed
	OCR_PARSED_PENDING_PAYMENT	OCR completed, payment pending
	OCR_WAITING_TOKEN	OCR waiting for token
	COMPLETED_BY_MELA_AI	Completed by Mela AI
Peppol	SENT_TO_PEPPOL	Sent to Peppol network
	SENT_TO_ACCESS_POINT	Sent to Access Point
	SUCCESS	Successfully delivered
	TRANSPORT_ERROR	Transport error
	INVALID_PARAMETERS	Invalid parameters
	NO_SIGNAL_MESSAGE_RECEIVED	No signal message received
	AS4_ERROR_MESSAGE_RECEIVED	AS4 error message received
	INVALID_SIGNAL_MESSAGE_RECEIVED	Invalid signal message received
	INCOMING_RESPONSE_ACKNOWLEDGED	Incoming response acknowledged (MLR/MLS)
	INCOMING_RESPONSE_REJECTED	Incoming response rejected
	INCOMING_RESPONSE_ACCEPTED	Incoming response accepted
	OUTGOING_RESPONSE_ACKNOWLEDGED	Outgoing response acknowledged (MLR/MLS)
	OUTGOING_RESPONSE_REJECTED	Outgoing response rejected
	OUTGOING_RESPONSE_ACCEPTED	Outgoing response accepted
Romania (ANAF)	SENT_TO_ANAF	Sent to ANAF
	PORTAL_OKAY	Portal approved
	PORTAL_ERROR	Portal error
	PORTAL_ERRORS	Portal multiple errors
	PORTAL_SYSTEM_ERROR	Portal system error
	PORTAL_IN_PROCESS	Portal processing
Poland (KSeF)	KSEF_PENDING	KSeF processing
	KSEF_ACCEPTED	KSeF accepted
	KSEF_REJECTED	KSeF rejected
	KSEF_DUPLICATE	KSeF duplicate record
Malaysia (LHDNM)	LHDNM_SUBMITTED	Submitted to LHDNM
	LHDNM_VALID	LHDNM valid
	LHDNM_INVALID	LHDNM invalid
	LHDNM_CANCELLED	LHDNM cancelled
	LHDNM_REJECT_REQUESTED	LHDNM rejection requested
	LHDNM_REJECTED	LHDNM rejected
	LHDNM_ERROR	LHDNM error
Egypt (ETA)	ETA_SUBMITTED	Submitted to ETA
Croatia (eRacun)	ERACUN_ERROR	eRacun error
	ERACUN_PENDING	eRacun pending
	ERACUN_WAITING_TO_SEND	eRacun waiting to send
	ERACUN_SENT	eRacun sent
	ERACUN_RECEIVED	eRacun received
	ERACUN_APPROVED	eRacun approved
	ERACUN_REJECTED	eRacun rejected
	ERACUN_FULLY_PAID	eRacun fully paid
	ERACUN_PARTIALLY_PAID	eRacun partially paid
	ERACUN_DELIVERY_FAILED	eRacun delivery failed
Denmark	SENT_TO_NEMHANDEL	Sent to Nemhandel
Other	CREDIT_BLOCKED	Credit blocked (returns masked data)

Responses

200 - Successful Response

{  
 "totalCount": 1,  
 "currencyTotals": [  
 {  
 "currency": "EUR",  
 "totalAmount": 419283.43,  
 "netAmount": 354187.94,  
 "taxAmount": 65095.49,  
 "payableAmount": 416194.42  
 }  
 ],  
 "invoiceList": [  
 {
 "id": "c62739c4-ea6a-4aeb-86b0-...",  
 "companyId": "cfffb7b0-608d-49e3-8aa2-...",  
 "customerName": "partner",  
 "supplierName": "Demo Slovakia s.r.o.",  
 "supplierId": "5342382",  
 "supplierVat": "SK2029999999",  
 "status": "SAVED_AS_UBL",  
 "invoiceNumber": "2701-1509",  
 "taxExclusiveAmount": 1600.0,  
 "taxInclusiveAmount": 1760.0,  
 "lineExtensionAmount": 1600.0,  
 "payableAmount": 1760.0,  
 "currency": "EUR",  
 "issueDate": "2026-03-14",  
 "dueDate": "2026-05-02",  
 "supplierCountryCode": "SK",  
 "supplierEndpoint": "iso6523-actorid-upis::9930:de610083641",  
 "customerId": "5625652",  
 "customerVat": "DE5665661",  
 "customerEndpoint": "iso6523-actorid-upis::9930:DE456982314",  
 "customerCountryCode": "DE",  
 "typeCode": "380",  
 "documentType": "OUTGOING",  
 "type": "PEPPOL_BIS",  
 "source": "PORTAL",  
 "sendViaPeppol": true,  
 "paymentDetails": {  
 "paymentStatus": "LATE",  
 "paidAmount": 0.0,  
 "totalAmount": 1760.0,  
 "remainingAmount": 1760.0,  
 "paymentDate": null  
 },  
 "profileType": "EN16931",  
 "isActive": true,  
 "isRead": false  
 }  
 ]  
}  

Successful Response Field Descriptions

Top-Level Fields

Field	Type	Description
totalCount	Long	Total number of documents matching the filters
netTotal	Double	Tax-exclusive total amount (excludes CREDIT_BLOCKED)
total	Double	Tax-inclusive total amount (excludes CREDIT_BLOCKED)
invoiceList	Array<Invoice>	List of invoice objects

Invoice Object Fields

Field	Type	Description
id	String (UUID)	Unique identifier of the invoice
companyId	String (UUID)	Company ID the invoice belongs to
userId	String (UUID)	User ID who created the invoice
customerName	String	Customer (buyer) name
supplierName	String	Supplier (seller) name
supplierId	String	Supplier ID
supplierVat	String	Supplier VAT number
status	String (Enum)	Current invoice status
invoiceNumber	String	Invoice number
taxExclusiveAmount	Double	Tax-exclusive amount
taxInclusiveAmount	Double	Tax-inclusive amount
lineExtensionAmount	Double	Line items total amount
payableAmount	Double	Amount payable
allowanceTotalAmount	Double	Total allowance/discount amount
currency	String	Currency code (ISO 4217: EUR, USD, TRY, etc.)
createdTime	String (DateTime)	Creation timestamp (UTC)
localCreatedTime	String (DateTime)	Creation timestamp (local time)
issueDate	String (Date)	Invoice issue date
deliveryDate	String (Date)	Delivery date
dueDate	String (Date)	Due date
supplierCountryCode	String	Supplier country code (ISO 3166-1 alpha-2)
supplierEndpoint	String	Supplier Peppol endpoint
customerId	String	Customer ID
customerVat	String	Customer VAT number
customerEndpoint	String	Customer Peppol endpoint
customerCountryCode	String	Customer country code
typeCode	String	Invoice type code (e.g., 380=Invoice, 381=Credit Note)
documentType	String (Enum)	Document direction: INCOMING or OUTGOING
errorMessage	String	Error message (if any)
lastUpdatedTime	String (DateTime)	Last update timestamp (UTC)
localLastUpdatedTime	String (DateTime)	Last update timestamp (local time)
type	String (Enum)	Document format type (DataType)
source	String (Enum)	Invoice source (PORTAL, ERP, PEPPOL, EMAIL, etc.)
sendViaPeppol	Boolean	Whether sent via Peppol
statusTime	String (DateTime)	Status change timestamp (UTC)
localStatusTime	String (DateTime)	Status change timestamp (local time)
fileName	String	File name
ocrParser	String (Enum)	OCR parser type
paymentDetails	Object	Payment details (null for certain statuses)
profileType	String (Enum)	ZUGFeRD profile type: BASIC, EN16931, EXTENDED
isActive	Boolean	Whether the invoice is active
countrySpecificData	Object	Country-specific additional data

Note: Invoices with CREDIT_BLOCKED status are masked — only id, companyId, documentType, type,invoiceNumber ,supplierName,supplierVat , status and isActive fields are returned; all other fields are null.

400 - Bad Request

Returned when an invalid parameter value is provided (e.g., incorrect enum value, malformed UUID format).

{
  "errorMessage": "Invalid value 'INVALID_STATUS' for parameter 'status'", 
  "errorType": "ILLEGAL_ARGUMENT", 
  "errorTitle": "BAD_REQUEST", 
  "errorId": "corr-abc123-def456", 
  "status": 400, 
  "timestamp": "2026-01-15T10:30:00", 
  "path": "/invoice/search-documents" 
}

Error Response Fields

Field	Type	Description
errorMessage	String	Human-readable error description
errorType	String	Error type code
errorTitle	String	HTTP status name
errorId	String	Correlation ID (for log tracing)
status	Integer	HTTP status code
timestamp	String (DateTime)	Error occurrence time
path	String	Request path

401 - Unauthorized

Returned when an invalid, expired, or missing JWT token is provided.

{
  "errorMessage": "Not authorized for this action", 
  "errorType": "NOT_AUTHORITY", 
  "errorTitle": "UNAUTHORIZED", 
  "errorId": "corr-abc123-def456", 
  "status": 401, 
  "timestamp": "2026-01-15T10:30:00", 
  "path": "/invoice/search-documents" 
}

Unauthorized Error Response Fields

Field	Type	Description
errorMessage	String	Authorization error description
errorType	String	Fixed value: NOT_AUTHORITY
errorTitle	String	HTTP status name: UNAUTHORIZED
errorId	String	Correlation ID
status	Integer	401
timestamp	String (DateTime)	Error occurrence time
path	String	Request path

500 - Internal Server Error

Returned in case of database connection errors, unexpected runtime exceptions, or other server-side failures.

{
  "errorMessage": "An unexpected error occurred", 
  "errorType": "RUNTIME_ERROR", 
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "errorId": "corr-abc123-def456", 
  "status": 500, 
  "timestamp": "2026-01-15T10:30:00",
  "path": "/invoice/search-documents" 
}

Server Error Response Fields

Field	Type	Description
errorMessage	String	General error message
errorType	String	RUNTIME_ERROR, IO_ERROR, or SERVER_ERROR
errorTitle	String	HTTP status name: INTERNAL_SERVER_ERROR
errorId	String	Correlation ID (for log tracing)
status	Integer	500
timestamp	String (DateTime)	Error occurrence time
path	String	Request path

9. Get Invoice Details GET

Purpose of Use:
The GET /invoice/get-invoice/{invoiceId} endpoint allows retrieving the full structured details of a single invoice, including header data, party details, tax breakdown, and all invoice line items, in one consistent JSON structure regardless of the invoice's underlying document format, such as UBL, CII, Factur-X, etc.

Endpoint Information

Property	Value
URL	/invoice/get-invoice/{invoiceId}
Method	GET
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	R-Auth header, JWT token

Example Request

curl -X GET 'https://api-stage.docnova.ai/invoice/get-invoice/{invoiceId}' \
  --header 'R-Auth: {your JWT}'

Request Parameters

Field Name	Type	Required	Description
invoiceId	String (UUID)	Yes	Unique identifier of the invoice. Must be in UUID v4 format. Obtained from the id field in the search-documents response.
R-Auth	String (JWT)	Yes	Authentication token. JWT signed with HS512 algorithm.

Responses

200 - Successful Response

Returns an object with two top-level fields: invoice, the full invoice data, and paymentDetails, the payment status summary.

​{
    "invoice": {
        "Type": "PEPPOL_BIS",
        "StandardBusinessDocumentHeader": null,
        "LeitwegId": null,
        "IsPeppolParticipant": false,
        "CompanyId": null,
        "DraftUuid": null,
        "OcrUuid": null,
        "InvoiceUuid": null,
        "PartnerUuid": null,
        "ExternalInvoiceId": null,
        "Format": null,
        "ProfileType": "EN16931",
        "BusinessModelType": null,
        "UBLExtensions": null,
        "UBLVersionID": {
            "schemeID": null,
            "schemeName": null,
            "schemeAgencyID": null,
            "schemeAgencyName": null,
            "schemeVersionID": null,
            "Value": "2.1"
        },
        "CustomizationID": {
            "schemeID": null,
            "schemeName": null,
            "schemeAgencyID": null,
            "schemeAgencyName": null,
            "schemeVersionID": null,
            "Value": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0"
        },
        "ProfileID": {
            "schemeID": null,
            "schemeName": null,
            "schemeAgencyID": null,
            "schemeAgencyName": null,
            "schemeVersionID": null,
            "Value": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
        },
        "ProfileExecutionID": null,
        "ID": {
            "schemeID": null,
            "schemeName": null,
            "schemeAgencyID": null,
            "schemeAgencyName": null,
            "schemeVersionID": null,
            "Value": "2701-15893"
        },
        "CopyIndicator": null,
        "UUID": null,
        "IssueDate": {
            "Value": "2026-08-14"
        },
        "IssueTime": null,
        "DueDate": {
            "Value": "2026-08-20"
        },
        "InvoiceTypeCode": {
            "listID": null,
            "listAgencyID": null,
            "listAgencyName": null,
            "listName": null,
            "listVersionID": null,
            "name": null,
            "Value": "380"
        },
        "Note": [
            {
                "languageID": null,
                "Value": "Thank you for your order."
            }
        ],
        "TaxPointDate": {
            "Value": "2026-08-14"
        },
        "DocumentCurrencyCode": {
            "listID": null,
            "listAgencyID": null,
            "listAgencyName": null,
            "listName": null,
            "listVersionID": null,
            "name": null,
            "Value": "EUR"
        },
        "TaxCurrencyCode": null,
        "PricingCurrencyCode": null,
        "PaymentCurrencyCode": null,
        "PaymentAlternativeCurrencyCode": null,
        "AccountingCostCode": null,
        "AccountingCost": {
            "languageID": null,
            "Value": "68"
        },
        "LineCountNumeric": null,
        "BuyerReference": {
            "languageID": null,
            "Value": "buyer reference"
        },
        "InvoicePeriod": null,
        "DiscrepancyResponse": null,
        "OrderReference": {
            "ID": {
                "schemeID": null,
                "schemeName": null,
                "schemeAgencyID": null,
                "schemeAgencyName": null,
                "schemeVersionID": null,
                "Value": "purchase order"
            },
            "SalesOrderID": {
                "schemeID": null,
                "schemeName": null,
                "schemeAgencyID": null,
                "schemeAgencyName": null,
                "schemeVersionID": null,
                "Value": "sales order reference"
            },
            "CopyIndicator": null,
            "UUID": null,
            "IssueDate": null,
            "IssueTime": null,
            "CustomerReference": null,
            "DocumentReference": null
        },
        "BillingReference": null,
        "DespatchDocumentReference": null,
        "ReceiptDocumentReference": null,
        "StatementDocumentReference": null,
        "OriginatorDocumentReference": null,
        "ContractDocumentReference": null,
        "AdditionalDocumentReference": [
            {
                "ID": {
                    "schemeID": null,
                    "schemeName": null,
                    "schemeAgencyID": null,
                    "schemeAgencyName": null,
                    "schemeVersionID": null,
                    "Value": "docnova-document.pdf"
                },
                "CopyIndicator": null,
                "UUID": null,
                "IssueDate": null,
                "DocumentTypeCode": null,
                "DocumentType": null,
                "XPath": null,
                "DocumentStatusCode": null,
                "DocumentDescription": null,
                "Attachment": {
                    "EmbeddedDocumentBinaryObject": {
                        "mimeCode": "application/pdf",
                        "encodingCode": null,
                        "characterSetCode": null,
                        "filename": "docnova-document.pdf",
                        "Value": "JVBERi0xLjcKJeLjz9MKOCAwIG9iago8PC9..."
                        },
                    "ExternalReference": null
                },
                "ResultOfVerification": null
            }
        ],
        "ProjectReference": null,
        "Signature": null,
        "AccountingSupplierParty": {
            "CustomerAssignedAccountID": null,
            "AdditionalAccountID": null,
            "Party": {
                "WebsiteURI": null,
                "LogoReferenceID": null,
                "EndpointID": {
                    "schemeID": "0245",
                    "schemeName": null,
                    "schemeAgencyID": null,
                    "schemeAgencyName": null,
                    "schemeVersionID": null,
                    "Value": "2029999999"
                },
                "IndustryClassificationCode": null,
                "PartyIdentification": [
                    {
                        "ID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "5342382"
                        }
                    }
                ],
                "PartyName": [
                    {
                        "Name": {
                            "languageID": null,
                            "Value": "Demo Slovakia s.r.o."
                        }
                    }
                ],
                "Language": null,
                "PostalAddress": {
                    "ID": null,
                    "AddressTypeCode": null,
                    "AddressFormatCode": null,
                    "Postbox": null,
                    "Floor": null,
                    "Room": null,
                    "StreetName": {
                        "languageID": null,
                        "Value": "Testovacia 123, Bratislava, Slovakia"
                    },
                    "AdditionalStreetName": null,
                    "BuildingName": null,
                    "BuildingNumber": null,
                    "InhouseMail": null,
                    "Department": null,
                    "MarkAttention": null,
                    "MarkCare": null,
                    "PlotIdentification": null,
                    "CitySubdivisionName": null,
                    "CityName": {
                        "languageID": null,
                        "Value": "Bratislava"
                    },
                    "PostalZone": {
                        "languageID": null,
                        "Value": "10115"
                    },
                    "CountrySubentity": null,
                    "CountrySubentityCode": null,
                    "Region": null,
                    "District": null,
                    "AddressLine": [
                        {
                            "Line": {
                                "languageID": null,
                                "Value": "Testovacia 123, Bratislava, Slovakia"
                            }
                        }
                    ],
                    "Country": {
                        "Name": null,
                        "IdentificationCode": {
                            "listID": null,
                            "listAgencyID": null,
                            "listAgencyName": null,
                            "listName": null,
                            "listVersionID": null,
                            "Value": "SK"
                        }
                    }
                },
                "PhysicalLocation": null,
                "PartyTaxScheme": [
                    {
                        "RegistrationName": null,
                        "CompanyID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "SK2029999999"
                        },
                        "ExemptionReasonCode": null,
                        "ExemptionReason": null,
                        "RegistrationAddress": null,
                        "TaxScheme": {
                            "ID": {
                                "schemeID": null,
                                "schemeName": null,
                                "schemeAgencyID": null,
                                "schemeAgencyName": null,
                                "schemeVersionID": null,
                                "Value": "VAT"
                            },
                            "Name": null,
                            "TaxTypeCode": null,
                            "CurrencyCode": null,
                            "JurisdictionRegionAddress": null
                        }
                    }
                ],
                "PartyLegalEntity": [
                    {
                        "RegistrationName": {
                            "languageID": null,
                            "Value": "Demo Slovakia s.r.o."
                        },
                        "CompanyID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "SK2029999999"
                        },
                        "CompanyLegalForm": null,
                        "RegistrationAddress": null
                    }
                ],
                "Contact": {
                    "ID": null,
                    "Name": {
                        "languageID": null,
                        "Value": "Demo Slovakia s.r.o."
                    },
                    "Telephone": {
                        "languageID": null,
                        "Value": "+49301234567"
                    },
                    "Telefax": null,
                    "ElectronicMail": {
                        "languageID": null,
                        "Value": "demo@yopmail.com"
                    },
                    "Note": null,
                    "OtherCommunication": null
                },
                "Person": null
            },
            "DespatchContact": null,
            "AccountingContact": null,
            "SellerContact": null
        },
        "AccountingCustomerParty": {
            "CustomerAssignedAccountID": null,
            "SupplierAssignedAccountID": null,
            "AdditionalAccountID": null,
            "Party": {
                "WebsiteURI": null,
                "LogoReferenceID": null,
                "EndpointID": {
                    "schemeID": "9930",
                    "schemeName": null,
                    "schemeAgencyID": null,
                    "schemeAgencyName": null,
                    "schemeVersionID": null,
                    "Value": "DE610083641"
                },
                "IndustryClassificationCode": null,
                "PartyIdentification": [
                    {
                        "ID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "DE123658956"
                        }
                    }
                ],
                "PartyName": [
                    {
                        "Name": {
                            "languageID": null,
                            "Value": "ABC Innovations GmBH"
                        }
                    }
                ],
                "Language": null,
                "PostalAddress": {
                    "ID": null,
                    "AddressTypeCode": null,
                    "AddressFormatCode": null,
                    "Postbox": null,
                    "Floor": null,
                    "Room": null,
                    "StreetName": {
                        "languageID": null,
                        "Value": "address"
                    },
                    "AdditionalStreetName": null,
                    "BuildingName": null,
                    "BuildingNumber": null,
                    "InhouseMail": null,
                    "Department": null,
                    "MarkAttention": null,
                    "MarkCare": null,
                    "PlotIdentification": null,
                    "CitySubdivisionName": null,
                    "CityName": {
                        "languageID": null,
                        "Value": "Berlin"
                    },
                    "PostalZone": {
                        "languageID": null,
                        "Value": "1093"
                    },
                    "CountrySubentity": null,
                    "CountrySubentityCode": null,
                    "Region": null,
                    "District": null,
                    "AddressLine": [
                        {
                            "Line": {
                                "languageID": null,
                                "Value": "address"
                            }
                        }
                    ],
                    "Country": {
                        "Name": null,
                        "IdentificationCode": {
                            "listID": null,
                            "listAgencyID": null,
                            "listAgencyName": null,
                            "listName": null,
                            "listVersionID": null,
                            "Value": "DE"
                        }
                    }
                },
                "PhysicalLocation": null,
                "PartyTaxScheme": [
                    {
                        "RegistrationName": null,
                        "CompanyID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "DE123658956"
                        },
                        "ExemptionReasonCode": null,
                        "ExemptionReason": null,
                        "RegistrationAddress": null,
                        "TaxScheme": {
                            "ID": {
                                "schemeID": null,
                                "schemeName": null,
                                "schemeAgencyID": null,
                                "schemeAgencyName": null,
                                "schemeVersionID": null,
                                "Value": "VAT"
                            },
                            "Name": null,
                            "TaxTypeCode": null,
                            "CurrencyCode": null,
                            "JurisdictionRegionAddress": null
                        }
                    }
                ],
                "PartyLegalEntity": [
                    {
                        "RegistrationName": {
                            "languageID": null,
                            "Value": "DataCore Innovations AG-ebru"
                        },
                        "CompanyID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "DE123658956"
                        },
                        "CompanyLegalForm": null,
                        "RegistrationAddress": null
                    }
                ],
                "Contact": {
                    "ID": null,
                    "Name": {
                        "languageID": null,
                        "Value": "partner name"
                    },
                    "Telephone": {
                        "languageID": null,
                        "Value": "5544332"
                    },
                    "Telefax": null,
                    "ElectronicMail": {
                        "languageID": null,
                        "Value": "partner@yopmail.com"
                    },
                    "Note": null,
                    "OtherCommunication": null
                },
                "Person": null
            },
            "DeliveryContact": null,
            "AccountingContact": null,
            "BuyerContact": null
        },
        "PayeeParty": null,
        "BuyerCustomerParty": null,
        "SellerSupplierParty": null,
        "TaxRepresentativeParty": null,
        "Delivery": [
            {
                "ID": null,
                "Quantity": null,
                "MinimumQuantity": null,
                "MaximumQuantity": null,
                "ActualDeliveryDate": {
                    "Value": "2026-01-30"
                },
                "LatestDeliveryDate": null,
                "LatestDeliveryTime": null,
                "TrackingID": null,
                "DeliveryLocation": {
                    "ID": null,
                    "Description": null,
                    "Conditions": null,
                    "CountrySubentity": null,
                    "CountrySubentityCode": null,
                    "ValidityPeriod": null,
                    "Address": {
                        "ID": null,
                        "AddressTypeCode": null,
                        "AddressFormatCode": null,
                        "Postbox": null,
                        "Floor": null,
                        "Room": null,
                        "StreetName": {
                            "languageID": null,
                            "Value": "address"
                        },
                        "AdditionalStreetName": null,
                        "BuildingName": null,
                        "BuildingNumber": null,
                        "InhouseMail": null,
                        "Department": null,
                        "MarkAttention": null,
                        "MarkCare": null,
                        "PlotIdentification": null,
                        "CitySubdivisionName": null,
                        "CityName": {
                            "languageID": null,
                            "Value": "berlin"
                        },
                        "PostalZone": {
                            "languageID": null,
                            "Value": "10309"
                        },
                        "CountrySubentity": null,
                        "CountrySubentityCode": null,
                        "Region": null,
                        "District": null,
                        "AddressLine": [
                            {
                                "Line": {
                                    "languageID": null,
                                    "Value": "address"
                                }
                            }
                        ],
                        "Country": {
                            "Name": null,
                            "IdentificationCode": {
                                "listID": null,
                                "listAgencyID": null,
                                "listAgencyName": null,
                                "listName": null,
                                "listVersionID": null,
                                "Value": "DE"
                            }
                        }
                    }
                },
                "RequestedDeliveryPeriod": null,
                "PromisedDeliveryPeriod": null,
                "EstimatedDeliveryPeriod": null,
                "DeliveryParty": {
                    "WebsiteURI": null,
                    "LogoReferenceID": null,
                    "EndpointID": null,
                    "IndustryClassificationCode": null,
                    "PartyIdentification": null,
                    "PartyName": [
                        {
                            "Name": {
                                "languageID": null,
                                "Value": "Delivery Recipient Name"
                            }
                        }
                    ],
                    "Language": null,
                    "PostalAddress": null,
                    "PhysicalLocation": null,
                    "PartyTaxScheme": null,
                    "PartyLegalEntity": null,
                    "Contact": null,
                    "Person": null
                },
                "Despatch": null,
                "DeliveryTerms": null,
                "Shipment": null
            }
        ],
        "DeliveryTerms": null,
        "PaymentMeans": [
            {
                "ID": null,
                "PaymentMeansCode": {
                    "listID": null,
                    "listAgencyID": null,
                    "listAgencyName": null,
                    "listName": null,
                    "listVersionID": null,
                    "name": null,
                    "Value": "30"
                },
                "PaymentDueDate": null,
                "PaymentChannelCode": null,
                "InstructionID": null,
                "InstructionNote": null,
                "PaymentID": null,
                "CardAccount": null,
                "PayerFinancialAccount": null,
                "PayeeFinancialAccount": {
                    "ID": {
                        "schemeID": null,
                        "schemeName": null,
                        "schemeAgencyID": null,
                        "schemeAgencyName": null,
                        "schemeVersionID": null,
                        "Value": "SK8975000000000012345671"
                    },
                    "Name": {
                        "languageID": null,
                        "Value": "Account holder name"
                    },
                    "AccountTypeCode": null,
                    "CurrencyCode": null,
                    "PaymentNote": null,
                    "FinancialInstitutionBranch": {
                        "ID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "BICnumber"
                        },
                        "Name": null,
                        "FinancialInstitution": null,
                        "Address": null
                    }
                },
                "CreditAccount": null,
                "PaymentMandate": null
            }
        ],
        "PaymentTerms": null,
        "PrepaidPayment": null,
        "AllowanceCharge": null,
        "TaxExchangeRate": null,
        "PricingExchangeRate": null,
        "PaymentExchangeRate": null,
        "PaymentAlternativeExchangeRate": null,
        "TaxTotal": [
            {
                "TaxAmount": {
                    "currencyID": "EUR",
                    "Value": 12.92
                },
                "RoundingAmount": null,
                "TaxEvidenceIndicator": null,
                "TaxIncludedIndicator": null,
                "TaxSubtotal": [
                    {
                        "TaxableAmount": {
                            "currencyID": "EUR",
                            "Value": 68.00
                        },
                        "TaxAmount": {
                            "currencyID": "EUR",
                            "Value": 12.92
                        },
                        "CalculationSequenceNumeric": null,
                        "TransactionCurrencyTaxAmount": null,
                        "Percent": null,
                        "BaseUnitMeasure": null,
                        "PerUnitAmount": null,
                        "TaxCategory": {
                            "ID": {
                                "schemeID": null,
                                "schemeName": null,
                                "schemeAgencyID": null,
                                "schemeAgencyName": null,
                                "schemeVersionID": null,
                                "Value": "S"
                            },
                            "Name": null,
                            "Percent": {
                                "format": null,
                                "Value": 19
                            },
                            "BaseUnitMeasure": null,
                            "PerUnitAmount": null,
                            "TaxExemptionReasonCode": null,
                            "TaxExemptionReason": null,
                            "TaxScheme": {
                                "ID": {
                                    "schemeID": null,
                                    "schemeName": null,
                                    "schemeAgencyID": null,
                                    "schemeAgencyName": null,
                                    "schemeVersionID": null,
                                    "Value": "VAT"
                                },
                                "Name": null,
                                "TaxTypeCode": null,
                                "CurrencyCode": null,
                                "JurisdictionRegionAddress": null
                            }
                        }
                    }
                ]
            }
        ],
        "LegalMonetaryTotal": {
            "LineExtensionAmount": {
                "currencyID": "EUR",
                "Value": 68
            },
            "TaxExclusiveAmount": {
                "currencyID": "EUR",
                "Value": 68
            },
            "TaxInclusiveAmount": {
                "currencyID": "EUR",
                "Value": 80.92
            },
            "AllowanceTotalAmount": null,
            "ChargeTotalAmount": null,
            "PrepaidAmount": null,
            "PayableRoundingAmount": null,
            "PayableAmount": {
                "currencyID": "EUR",
                "Value": 80.92
            }
        },
        "InvoiceLine": [
            {
                "ID": {
                    "schemeID": null,
                    "schemeName": null,
                    "schemeAgencyID": null,
                    "schemeAgencyName": null,
                    "schemeVersionID": null,
                    "Value": "1"
                },
                "UUID": null,
                "Note": null,
                "InvoicedQuantity": {
                    "unitCode": "XBA",
                    "Value": 2
                },
                "LineExtensionAmount": {
                    "currencyID": "EUR",
                    "Value": 68
                },
                "TaxPointDate": null,
                "AccountingCostCode": null,
                "AccountingCost": null,
                "FreeOfChargeIndicator": null,
                "InvoicePeriod": null,
                "OrderLineReference": null,
                "DespatchLineReference": null,
                "ReceiptLineReference": null,
                "BillingReference": null,
                "PricingReference": null,
                "DocumentReference": [
                    {
                        "ID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "1"
                        },
                        "CopyIndicator": null,
                        "UUID": null,
                        "IssueDate": null,
                        "DocumentTypeCode": {
                            "listID": null,
                            "listAgencyID": null,
                            "listAgencyName": null,
                            "listName": null,
                            "listVersionID": null,
                            "name": null,
                            "Value": "130"
                        },
                        "DocumentType": null,
                        "XPath": null,
                        "DocumentStatusCode": null,
                        "DocumentDescription": null,
                        "Attachment": null,
                        "ResultOfVerification": null
                    }
                ],
                "OriginatorParty": null,
                "Delivery": null,
                "AllowanceCharge": null,
                "TaxTotal": null,
                "Item": {
                    "Description": null,
                    "PackQuantity": null,
                    "PackSizeNumeric": null,
                    "CatalogueIndicator": null,
                    "Name": {
                        "languageID": null,
                        "Value": "product"
                    },
                    "HazardousRiskIndicator": null,
                    "AdditionalInformation": null,
                    "Keyword": null,
                    "BrandName": null,
                    "ModelName": null,
                    "BuyersItemIdentification": null,
                    "SellersItemIdentification": {
                        "ID": {
                            "schemeID": null,
                            "schemeName": null,
                            "schemeAgencyID": null,
                            "schemeAgencyName": null,
                            "schemeVersionID": null,
                            "Value": "1"
                        }
                    },
                    "ManufacturersItemIdentification": null,
                    "StandardItemIdentification": null,
                    "CatalogueItemIdentification": null,
                    "AdditionalItemIdentification": null,
                    "CatalogueDocumentReference": null,
                    "ItemSpecificationDocumentReference": null,
                    "OriginCountry": null,
                    "CommodityClassification": null,
                    "TransactionConditions": null,
                    "HazardousItem": null,
                    "ClassifiedTaxCategory": [
                        {
                            "ID": {
                                "schemeID": null,
                                "schemeName": null,
                                "schemeAgencyID": null,
                                "schemeAgencyName": null,
                                "schemeVersionID": null,
                                "Value": "S"
                            },
                            "Name": null,
                            "Percent": {
                                "format": null,
                                "Value": 19
                            },
                            "BaseUnitMeasure": null,
                            "PerUnitAmount": null,
                            "TaxExemptionReasonCode": null,
                            "TaxExemptionReason": null,
                            "TaxScheme": {
                                "ID": {
                                    "schemeID": null,
                                    "schemeName": null,
                                    "schemeAgencyID": null,
                                    "schemeAgencyName": null,
                                    "schemeVersionID": null,
                                    "Value": "VAT"
                                },
                                "Name": null,
                                "TaxTypeCode": null,
                                "CurrencyCode": null,
                                "JurisdictionRegionAddress": null
                            }
                        }
                    ],
                    "AdditionalItemProperty": null,
                    "ManufacturerParty": null,
                    "InformationContentProviderParty": null,
                    "OriginAddress": null,
                    "ItemInstance": null
                },
                "Price": {
                    "PriceAmount": {
                        "currencyID": "EUR",
                        "Value": 34
                    },
                    "BaseQuantity": null,
                    "PriceChangeReason": null,
                    "PriceTypeCode": null,
                    "PriceType": null,
                    "OrderableUnitFactorRate": null,
                    "ValidityPeriod": null,
                    "PriceList": null,
                    "AllowanceCharge": null
                },
                "ItemPriceExtension": null,
                "CatalogItemId": null
            }
        ]
    },
    "paymentDetails": {
        "paymentStatus": "SENT",
        "paidAmount": 0.0,
        "totalAmount": 80.92,
        "remainingAmount": 80.92,
        "paymentDate": null
    }
}

Response Fields

Field	Type	Description
invoice	object	Full structured invoice data.
invoice.Type	string	Underlying invoice document type, e.g. FACTUR_X.
invoice.ProfileType	string	Invoice profile type, e.g. EN16931.
invoice.ID.Value	string	Business invoice number.
invoice.IssueDate.Value	date	Invoice issue date.
invoice.DueDate.Value	date	Invoice due date.
invoice.InvoiceTypeCode.Value	string	Invoice type code, e.g. 380.
invoice.DocumentCurrencyCode.Value	string	Invoice currency, e.g. EUR.
invoice.AccountingSupplierParty	object	Supplier party details.
invoice.AccountingCustomerParty	object	Customer party details.
invoice.TaxTotal	array	Tax total and tax breakdown information.
invoice.LegalMonetaryTotal	object	Invoice monetary totals.
invoice.InvoiceLine	array	Invoice line items.
paymentDetails	object	Payment status summary.
paymentDetails.paymentStatus	string	Current payment status.
paymentDetails.paidAmount	number	Amount already paid.
paymentDetails.totalAmount	number	Total invoice amount.
paymentDetails.remainingAmount	number	Remaining unpaid amount.
paymentDetails.paymentDate	datetime	Payment date, if available.

401 - Unauthorized

{
  "errorMessage": "User is not authorized for this operation",
  "errorType": "NOT_AUTHORITY",
  "status": 401,
  "timestamp": "2026-07-29T12:00:00",
  "path": "/invoice/get-invoice/{invoiceId}"
}

404 - Not Found

Returned when no invoice exists with the given invoiceId.

{
  "errorMessage": "{invoiceId} Invoice not found!",
  "errorType": "NOT_FOUND_INVOICE",
  "status": 404,
  "timestamp": "2026-07-29T12:00:00",
  "path": "/invoice/get-invoice/{invoiceId}"
}

500 - Internal Server Error

Returned when invoiceId is not a valid UUID.

{
  "errorMessage": "Invalid UUID string: {invoiceId}",
  "errorType": "RUNTIME_ERROR",
  "status": 500,
  "timestamp": "2026-07-29T12:00:00",
  "path": "/invoice/get-invoice/{invoiceId}"
}

10. Generate PDF POST

Purpose of Use: This endpoint accepts a base64-encoded UBL/XML invoice and converts it to PDF format, returning the raw PDF byte array. Supported format types include PEPPOL BIS, XRECHNUNG, UAE PINT, ZUGFeRD, KSEF, and other country-specific e-invoice standards. The optional country code and VAT number fields are used in SAP-ERP integrations for country-specific or company-specific XSLT template selection.

Endpoint Information

Property	Value
URL	/invoice/generate/pdf
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authentication	R-Auth header (JWT Bearer Token)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/generate/pdf' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'R-Auth: eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJNTU0iLCJzdWIiOiJwNjR9.IpGPX...' \
--data '{
  "base64XML": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KC...",
  "country": "SK",
  "type": "PEPPOL_BIS",
  "vatNumber": "SK2029999999"
}

Request Parameters

Field Name	Type	Required	Description
base64XML	String	Yes	Base64-encoded invoice XML data. Must be a valid XML in UBL 2.1, CrossIndustryInvoice (CII), or the relevant country-specific format.
type	Enum (DataType)	Yes	Invoice format type. Specifies the standard of the provided XML. Valid values are listed in the table below.
country	Enum (Country)	No	Country code of the invoice (ISO 3166-1 alpha-2). When used together with vatNumber, company matching is performed to add logo and language settings to the PDF.
vatNumber	String	No	VAT number of the invoicing company. When used together with country, it matches against the company record in the system.

Valid Values for type Parameter

UBL-Based Formats

Value	Description	XSLT Group
XRECHNUNG	German XRechnung standard (EN 16931 compliant)	XRECHNUNG
PEPPOL_BIS	PEPPOL BIS 3.0 standard	XRECHNUNG
RO_EFACTURA	Romania e-Factura format	XRECHNUNG
MY_INVOIS	Malaysia MyInvois format	MY_INVOIS
MY_PINT	Malaysia PINT format	MY_PINT
DK_OIOUBL	Denmark OIOUBL format	DK_OIOUBL
EG_INVOICE	Egypt invoice format	EG_INVOICE
HR_INVOICE	Croatia invoice format	HR_INVOICE
UAE_PINT	UAE PINT format	UAE_PINT

CII / ZUGFeRD-Based Formats

Value	Description	XSLT Group
ZUGFERD	ZUGFeRD 2.x format (XML-embedded PDF)	ZUGFERD
FACTUR_X	French Factur-X format	ZUGFERD
XRECHNUNG_CII	XRechnung CII format	ZUGFERD
CII	UN/CEFACT CrossIndustryInvoice	ZUGFERD
CID	CrossIndustryDocument format	ZUGFERD
PDF	Unstructured invoice (paper invoices, images, etc.)	ZUGFERD

Other Formats

Value	Description	XSLT Group
KZ_ESF_V2	Kazakhstan ESF v2 format	KZ_ESF_V2
KSEF	Poland KSeF format	KSEF
KSEF_OFFLINE	Poland KSeF offline format	KSEF_OFFLINE

country Parameter

Country Code	Country	PDF Language
DE	Germany	German (DE)
AT	Austria	German (DE)
FR	France	French (FR)
IT	Italy	Italian (IT)
NL	Netherlands	Dutch (NL)
RO	Romania	Romanian (RO)
ES	Spain	Spanish (ES)
TR	Turkey	Turkish (TR)
KZ	Kazakhstan	Kazakh (KK)
MY	Malaysia	Malay (MS)
BN	Brunei	Malay (MS)
SK	Slovakia	Slovak (SK)
All others	—	English (EN)

Responses

200 - Successful Response

Property	Value
HTTP Status	200
Content-Type	application/octet-stream
Body	Binary PDF data (byte array)

%PDF-1.7
%����
1 0 obj
<<
/Pages 2 0 R
/Type /Catalog
/Names 21 0 R
/Metadata 27 0 R
>>
endobj
5 0 obj
<<

400 - Bad Request

Trigger Condition: When the XML data is invalid, Base64 cannot be decoded, XSLT transformation fails, or any error occurs during iText PDF generation.

{
  "errorMessage": "PDF convert error: [detail message]",
  "errorType": "PDF_CONVERT_ERROR",
  "errorTitle": "BAD_REQUEST",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-...",
  "status": 400,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/generate/pdf"
}

Possible Detail Messages:

PDF convert error: PDF conversion failed due to an unexpected error — XSLT template not found or unexpected error during HTML-to-PDF conversion
PDF convert error: Illegal base64 character — The base64XML field is not in valid Base64 format
PDF convert error: [XSLT transformation error]` — XML structure does not match the expected format

400 - Bad Request — Invalid Parameter

Trigger Condition: When an invalid enum value is sent for the type field or required fields are missing.

{
  "errorMessage": "Invalid argument! Argument: type",
  "errorType": "INVALID_ARGUMENT",
  "errorTitle": "BAD_REQUEST",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-...",
  "status": 400,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/generate/pdf"
}

400 - Bad Request — Invalid PDF Type

Trigger Condition: When the submitted type value is an unsupported format for PDF conversion.

{
  "errorMessage": "Invalid PDF type",
  "errorType": "INVALID_PDF_TYPE",
  "errorTitle": "BAD_REQUEST",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-...",
  "status": 400,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/generate/pdf"
}

400 - Bad Request — Empty XML Data

Trigger Condition: When the base64XML field is sent as null or empty.

{
  "errorMessage": "Data XML cannot be NULL!",
  "errorType": "NULL_DATA_XML",
  "errorTitle": "BAD_REQUEST",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-...",
  "status": 400,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/generate/pdf"
}

401 - Unauthorized

Trigger Condition: When the R-Auth header is missing, the JWT token has expired, or an invalid token is provided.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-...",
  "status": 401,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/generate/pdf"
}

500 - Internal Server Error

Trigger Condition: When an unexpected server error occurs (XSLT file cannot be loaded, insufficient memory, etc.).

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-...",
  "status": 500,
  "timestamp": "2026-02-11T14:30:00",
  "path": "/invoice/generate/pdf"
}

Error Codes and Response Details

The following errors are specific to this endpoint. All error responses follow the ExceptionResponse format:

Error Response Structure

Field Name	Type	Description
errorMessage	String	Detailed description of the error
errorType	String	Error type identifier
errorTitle	String	HTTP status name (BAD_REQUEST, INTERNAL_SERVER_ERROR, etc.)
errorId	String	Correlation ID (for log tracing)
status	Integer	HTTP status code (400, 500, etc.)
timestamp	String (ISO 8601)	Time when the error occurred
path	String	Requested URL path

11. Peppol - Get MLR GET

Purpose of Use This endpoint is used to query Message Level Response (MLR) records for invoices sent or received through the Peppol network.
MLR is a message level response mechanism in the Peppol infrastructure that indicates whether a document was successfully delivered, accepted, or rejected by the receiving party.

With this API you can:

List all MLR responses belonging to a specific company
Query MLR status for a specific invoice (invoiceId) or document (documentId)
Filter by the counterpart’s Peppol participant identifier (counterpartParticipantId)
Perform time based searches by specifying a date range (fromDate, toDate)
Returned responses include detail lines for each MLR record (error field, status reason, description)

This enables developers to programmatically track the final status of the invoice delivery process and take necessary actions in case of errors.

Endpoint Information

Property	Value
URL	/peppol/search-mlr
Method	GET
Authentication	R-Auth header (JWT token)

Example Request

{
curl --location 'https://api-stage.docnova.ai/peppol/search-mlr?companyId={companyId}&counterpartParticipantId={counterpartParticipantId}&documentId={documentId}&fromDate={fromDate}&invoiceId={invoiceId}&toDate={toDate}' \
--header 'Accept: */*' \
--header 'R-Auth: {jwt_token}'
}

Request Parameters

Field	Type	Required	Format	Description
companyId	String (UUID)	Yes	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Unique identifier of the company to query
documentId	String (UUID)	No	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Peppol document identifier (instance identifier)
counterpartParticipantId	String	No	`{scheme}:{identifier}` (e.g., `9930:de111222777`)	Counterpart’s Peppol participant identifier
invoiceId	String	No	Free text	Invoice number or identifier
fromDate	String (ISO Date)	No	`yyyy-MM-dd` (e.g., `2025-09-09`)	Search start date (inclusive)
toDate	String (ISO Date)	No	`yyyy-MM-dd` (e.g., `2026-09-09`)	Search end date (inclusive)

Request Headers

Header	Type	Required	Description
R-Auth	String (JWT)	Yes	User authentication token. JWT signed with HS512 algorithm
Accept	String	No	Default /. Response is returned as application/json

Parameter Values

counterpartParticipantId Format

Scheme	Description	Example
9930	Germany VAT number	9930:de111222777
0204	Leitweg-ID	0204:1234567890123
0088	EAN location code	0088:1234567890123

responseType Response Type Enum Values

Value	Description
ACCEPTANCE	Document was accepted by the counterpart
ACKNOWLEDGING	Document was acknowledged (received) by the counterpart
REJECTION	Document was rejected by the counterpart

statusReasonCode Status Reason Code Enum Values

Value	Description
BUSINESS_RULE_VIOLATION_FATAL	Business rule violation. Critical error. Document was not processed
BUSINESS_RULE_VIOLATION_WARNING	Business rule violation. Warning. Document can still be processed
SYNTAX_VIOLATION	Syntax error. Document format is invalid

Responses

200 - Successful Response

Type: List<SearchMLRResponse>

{
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-...",
    "companyId": "60ccd1a7-5348-47b2-9ef6-...",
    "documentId": "8fa4606f-94f2-45e1-a8cb-...",
    "responseType": "ACCEPTANCE",
    "receivedTime": "2026-01-15T14:30:00",
    "counterpartParticipantId": "9930:de111222777",
    "invoiceId": "2026_007_peppol",
    "responseLines": [
      {
        "id": "f1e2d3c4-b5a6-7890-abcd-...",
        "errorField": null,
        "responseCode": "ACCEPTANCE",
        "description": "Document successfully processed",
        "statusReasonCode": null
      }
    ]
  }
]
}

Response Fields

Field	Type	Description
id	UUID	Unique identifier of the MLR record
companyId	String	Identifier of the related company
documentId	String	Peppol document identifier
responseType	Enum (MessageLevelResponseType)	Overall response type: ACCEPTANCE, ACKNOWLEDGING, REJECTION
receivedTime	DateTime (ISO 8601)	Date and time the MLR response was received
counterpartParticipantId	String	Counterpart’s Peppol participant identifier
invoiceId	String	Related invoice number
responseLines	List<SearchMLRLineResponse>	MLR detail lines

Response Detail Lines

Field	Type	Description
id	UUID	Unique identifier of the detail line
errorField	String (nullable)	The field / XPath expression where the error occurred
responseCode	Enum (MessageLevelResponseType)	Line level response code: ACCEPTANCE, ACKNOWLEDGING, REJECTION
description	String (nullable)	Error or status description
statusReasonCode	Enum (MLRStatusReasonCode) (nullable)	Status reason code: BUSINESS_RULE_VIOLATION_FATAL, BUSINESS_RULE_VIOLATION_WARNING, SYNTAX_VIOLATION

400 - Bad Request

Occurs when the required companyId parameter is missing or when the date format is invalid.

{
  "errorMessage": "Required request parameter 'companyId' for method parameter type String is not present",
  "errorType": "BAD_REQUEST",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "corr-xxx-xxx",
  "timestamp": "2026-01-15T14:30:00",
  "path": "/peppol/search-mlr"
}

Description: The companyId parameter is mandatory and Spring framework automatically returns this error when it is missing. Additionally, if fromDate or toDate parameters do not conform to the yyyy-MM-dd ISO format, the same error code is returned.

401 - Unauthorized

Occurs when the JWT token is invalid, expired, or the R-Auth header is missing. Also returned when the user is not associated with the specified companyId.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "corr-xxx-xxx",
  "timestamp": "2026-01-15T14:30:00",
  "path": "/peppol/search-mlr"
}

Description: The authorizationService.checkIfCompanyUser(companyId, userId) method verifies that the user identity in the JWT token matches the specified companyId. If they do not match, an AuthorizationServiceException is thrown. This error is also returned when the token is expired or its signature is invalid.

500 - Internal Server Error

Returned in case of database access errors, unexpected runtime exceptions, or other server-side failures.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "corr-xxx-xxx",
  "timestamp": "2026-01-15T14:30:00",
  "path": "/peppol/search-mlr"
}

Description: Returned in case of database connection errors, JPA/Hibernate query failures, or unexpected internal server errors. The errorId (correlation id) field can be used to trace detailed error information from log records.

Error Response General Format

Field	Type	Description
errorMessage	String	Human readable description of the error
errorType	String	Error classification code (e.g., NOT_AUTHORITY, RUNTIME_ERROR)
errorTitle	String (HttpStatus)	HTTP status code name (e.g., BAD_REQUEST, UNAUTHORIZED, INTERNAL_SERVER_ERROR)
status	Integer	HTTP status code numeric value (e.g., 400, 401, 500)
errorId	String (nullable)	Correlation ID used for log tracing
data	String (nullable)	Additional data (if available)
details	Map<String, Object> (nullable)	Detailed error information (if available)
validationErrors	List<ValidationError> (nullable)	Field level validation errors (if available)
timestamp	DateTime (ISO 8601)	Time when the error occurred
path	String	Endpoint path where the error occurred

12. Peppol - Send MLR POST

Purpose of Use The POST /peppol/send-mlr endpoint is used to send a Message Level Response (MLR) within the Peppol infrastructure.

An MLR is the official response given by the receiving party to an e-invoice received through Peppol. This response communicates to the sender whether the invoice was successfully received and accepted, is being processed (acknowledged), or has been rejected. The receiver can inform the sender in detail by specifying errors in the invoice (IBAN error, syntax error, business rule violation, etc.).

After the MLR is sent, the related invoice status is automatically updated.

Endpoint Information

Property	Value
URL	/peppol/send-mlr
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://api-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authentication	R-Auth header (JWT token)

Example Request

curl --location 'https://api-stage.docnova.ai/peppol/send-mlr' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'R-Auth: <JWT_TOKEN>' \
--data '{
  "errorLines": [
    {
      "description": "The IBAN number provided in the payment instructions is invalid or missing",
      "errorField": "PaymentMeans/PayeeFinancialAccount/ID",
      "responseCode": "ACKNOWLEDGING",
      "statusReasonCode": "BUSINESS_RULE_VIOLATION_WARNING"
    }
  ],
  "invoiceId": "<INVOICE_UUID>",
  "responseCode": "ACCEPTANCE"
}'

Request Parameters

Root Level Parameters

Field Name	Type	Required	Description
invoiceId	String (UUID)	Yes	Unique identifier of the invoice to send the MLR for (UUID format)
responseCode	Enum (MessageLevelResponseType)	Yes	Overall response code for the invoice
errorLines	Array<MLRErrorLine>	No	List of error details in the invoice. Can be left empty

errorLines Array Element

Field Name	Type	Required	Description
description	String	No	Human readable description of the error
errorField	String	No	UBL/XML field path where the error was detected (XPath-like)
responseCode	Enum (MessageLevelResponseType)	No	Response code specific to this error line
statusReasonCode	Enum (MLRStatusReasonCode)	No	Classification code of the error

Allowed Parameter Values

MessageLevelResponseType (responseCode)

Value	Description
ACCEPTANCE	Invoice accepted. It has been processed and approved
ACKNOWLEDGING	Invoice received. Receipt is confirmed but not yet fully processed
REJECTION	Invoice rejected. Not processed due to errors

MLRStatusReasonCode (statusReasonCode)

Value	Description
BUSINESS_RULE_VIOLATION_FATAL	Fatal business rule violation. A critical error that prevents the invoice from being processed
BUSINESS_RULE_VIOLATION_WARNING	Warning level business rule violation. The invoice can be processed but correction is recommended
SYNTAX_VIOLATION	Syntax error. Format or schema incompatibility in the XML/UBL structure

Responses

200 - Successful Response

Field	Type	Value	Description
HTTP Status	Integer	200	Operation successful
Body	String	"MLR sent successfully"	Response text returned from the Access Point service

"MLR sent successfully"

400 - Bad Request

Trigger Condition: When an error occurs while forwarding the MLR to the Access Point service (connection error, timeout, Access Point rejection).

{
  "errorMessage": "Failed to send MLR: <detailed error message>",
  "errorType": "API_ERROR",
  "errorTitle": "BAD_REQUEST",
  "errorId": "<correlation-id>",
  "status": 400,
  "timestamp": "2026-02-12T14:30:00",
  "path": "/peppol/send-mlr"
}

Description: The MLR was saved to the database but could not be forwarded to the Access Point. The error message contains the detail returned from the Access Point. Check your network connectivity and Access Point service availability.

400 - Bad Request — Invalid responseCode

Trigger Condition: When the responseCode field contains an invalid enum value (i.e., a value other than ACCEPTANCE, ACKNOWLEDGING, REJECTION).

{
  "errorMessage": "Unknown response code: <invalid_value>",
  "errorType": "API_ERROR",
  "errorTitle": "BAD_REQUEST",
  "errorId": "<correlation-id>",
  "status": 400,
  "timestamp": "2026-02-12T14:30:00",
  "path": "/peppol/send-mlr"
}

Description: The responseCode field only accepts ACCEPTANCE, ACKNOWLEDGING, or REJECTION values. Verify the value you are sending.

400 - Bad Request — Invalid UUID Format

Trigger Condition: When the invoiceId field is not in a valid UUID format.

{
  "errorMessage": "Invalid UUID string: <invalid_value>",
  "errorType": "API_ERROR",
  "errorTitle": "BAD_REQUEST",
  "errorId": "<correlation-id>",
  "status": 400,
  "timestamp": "2026-02-12T14:30:00",
  "path": "/peppol/send-mlr"
}

Description: : The invoiceId value must be a valid UUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

401 - Unauthorized

Trigger Condition: When the R-Auth header is missing, invalid, or contains an expired JWT token.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "errorId": "<correlation-id>",
  "status": 401,
  "timestamp": "2026-02-12T14:30:00",
  "path": "/peppol/send-mlr"
}

Description:  The JWT token has expired or is malformed. Obtain a new token and retry.

404 - Not Found

Trigger Condition: When no invoice matching the provided invoiceId is found in the database.

{
  "errorMessage": "<invoiceId> Invoice not found",
  "errorType": "NOT_FOUND_INVOICE",
  "errorTitle": "NOT_FOUND",
  "errorId": "<correlation-id>",
  "status": 404,
  "timestamp": "2026-02-12T14:30:00",
  "path": "/peppol/send-mlr"
}

Description: The invoiceId parameter contains an invalid or unregistered UUID in the database. Ensure the invoice ID is correct.

500 - Internal Server Error

Trigger Condition: When a database error, network error, or unexpected exception occurs.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "errorId": "<correlation-id>",
  "status": 500,
  "timestamp": "2026-02-12T14:30:00",
  "path": "/peppol/send-mlr"
}

Description: An unexpected error occurred on the server side. Forward the errorId (correlation ID) value to the support team for detailed investigation.

Error Response Model (ExceptionResponse)

Field Name	Type	Description
errorMessage	String	Detailed description of the error
errorType	String	Error classification code (e.g., NOT_FOUND_INVOICE, API_ERROR)
errorTitle	String (HttpStatus)	HTTP status name (e.g., NOT_FOUND, BAD_REQUEST)
errorId	String	Correlation identifier (for log tracing)
status	Integer	HTTP status code (e.g., 400, 404, 500)
data	String	Additional data (if available)
details	Map<String, Object>	Additional detail information (if available)
validationErrors	Array<ValidationError>	Validation error list (if available)
timestamp	String (ISO 8601)	Timestamp of when the error occurred
path	String	Endpoint path of the request

How to get “API Key” from Portal ?​

Login and Authorization Configuration​

Technical Details​

Request Body (JSON)​

Response Details​

Technical Details​

1. Introduction​

2. Authentication POST​

Endpoint Information​

Example Request​

Request Parameters​

Responses​

200 - Login Successful​

Basic Response (JwtBasicResponse)​

Response Fields​

Account Information Fields​

Parameter Values Reference Table​

currentCountry Values (Sample List)​

Company Information Fields​

User Information Fields​

Enum Values Reference Table​

mfaType Values​

portalType Values​

mailLanguage Values​

401 - Unauthorized​

403 - MFA Required​

429 - Too Many Requests​

3. Search Processing History POST​

Endpoint Information​

Example Request​

Request Parameters​

Query Parameters (Pagination)​

Enum Value Reference​

direction Values (Document Direction)​

status Values (Processing Status)​

source Values (Source and Target System)​

documentType Values (Document Format)​

waybillType Values (Waybill Type)​

Responses​

200 - Successful Response​

Response Fields​

400 - Bad Request​

400 - Bad Request ​

401 - Unauthorized​

401 - Unauthorized​

404 - Not Found​

498 - Token Expired​

500 - Internal Server Error​

Response Structure Reference (ExceptionResponse)​

4. Send Document Async POST​

Endpoint Information​

Example Request​

Request Parameters​

businessType Values​

invoiceType Values​

waybillType Values​

Responses​

200 - Successful Response​

Response Fields​

status Values​

400 - Bad Request​

401 - Unauthorized​

500 - Internal Server Error​

5. Document Status GET​

Endpoint Information​

Example Request​

Request Parameters​

Path Parameters​

Header Parameters​

Responses​

200 - Successful Response​

Success Response Field Descriptions​

Parameter Value Reference​

DocumentProcessStatus — Possible Status Values​

DocumentType — Document Direction​

DataType — Document Format​

WaybillDataType — Waybill Type​

ErrorType — Error Types Specific to This Endpoint​

401 - Unauthorized ​

404 - Not Found​

How to get “API Key” from Portal ?

Login and Authorization Configuration

Technical Details

Request Body (JSON)

Response Details

Technical Details

1. Introduction

2. Authentication POST

Endpoint Information

Example Request

Request Parameters

Responses

200 - Login Successful

Basic Response (JwtBasicResponse)

Response Fields

Account Information Fields

Parameter Values Reference Table

currentCountry Values (Sample List)

Company Information Fields

User Information Fields

Enum Values Reference Table

mfaType Values

portalType Values

mailLanguage Values

401 - Unauthorized

403 - MFA Required

429 - Too Many Requests

3. Search Processing History POST

Endpoint Information

Example Request

Request Parameters

Query Parameters (Pagination)

Enum Value Reference

direction Values (Document Direction)

status Values (Processing Status)

source Values (Source and Target System)

documentType Values (Document Format)

waybillType Values (Waybill Type)

Responses

200 - Successful Response

Response Fields

400 - Bad Request

400 - Bad Request

401 - Unauthorized

401 - Unauthorized

404 - Not Found

498 - Token Expired

500 - Internal Server Error

Response Structure Reference (ExceptionResponse)

4. Send Document Async POST

Endpoint Information

Example Request

Request Parameters

businessType Values

invoiceType Values

waybillType Values

Responses

200 - Successful Response

Response Fields

status Values

400 - Bad Request

401 - Unauthorized

500 - Internal Server Error

5. Document Status GET

Endpoint Information

Example Request

Request Parameters

Path Parameters

Header Parameters

Responses

200 - Successful Response

Success Response Field Descriptions

Parameter Value Reference

DocumentProcessStatus — Possible Status Values

DocumentType — Document Direction

DataType — Document Format

WaybillDataType — Waybill Type

ErrorType — Error Types Specific to This Endpoint

401 - Unauthorized

404 - Not Found