Romania E-Invoice RO-eFactura

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://app-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

Docnova Romania is a cloud-based e-invoicing management portal developed by Melasoft, fully aligned with Romania's e-invoicing requirements and designed to support integration with the RO e-Factura (Sistemul Național de Facturare Electronică — National Electronic Invoicing System) framework, operated by the National Agency for Fiscal Administration (Agenția Națională de Administrare Fiscală — ANAF) under the Romanian Ministry of Finance (Ministerul Finanțelor).

This API documentation is intended to help your ERP systems integrate smoothly with Romania's e-invoicing process.

Our portal abstracts complex invoice data structures and RO e-Factura transmission workflows, providing developers with an easy-to-use, secure, and scalable interface. By using the Docnova Romania API, you can submit invoices asynchronously, track real-time processing statuses, manage incoming invoices, and automatically process technical responses and validation results, including official acceptance receipts (Index de Descarcare and the ANAF-signed XML response) back into your ERP system.

Our compliance-oriented architecture supports the legal validity of every document, ensures data integrity, and provides an end-to-end traceable audit trail.

Docnova Romania also manages the submission of invoices to RO e-Factura as part of the compliance flow. After validation checks are completed, invoices are transmitted asynchronously to ANAF and the acceptance or rejection result, along with the digitally signed invoice XML stamped by ANAF, is returned with detailed status information for automatic processing in your ERP.

2. Authentication POST

Purpose of Use: This endpoint enables programmatic login to the system using a pre-generated API key combined with an email address. Unlike the standard password-based login flow, this method is specifically designed for ERP integrations, automated workflows, and third-party service integrations.

The API key can be of two types: COMPANY-type keys are bound to a specific company and only allow users who are authorized members of that company to log in; USER-type keys belong directly to a user and are used to open a session under that user's identity. Upon successful login, a short-lived JWT access token and its expiration date are returned. This JWT must be used as a Bearer token in the Authorization header for all subsequent requests.

Endpoint Information

Property	Value
URL	/auth/login
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-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' \ 
--data-raw '{ 
  "apiKey": "{{your_api_key}}", 
  "email": "user@example.com" 
  }'

Request Parameters

Field Name	Type	Required	Description
apiKey	String	Required	A registered and active API key in the system. Can be either COMPANY type or USER type.
email	String	Required	The registered email address of the user to log in as. When using a COMPANY-type API key, this email must belong to a user who is an authorized member of the company the key is associated with.

The API key authentication flow is triggered when apiKey and email are sent together without a password field.
For COMPANY-type API keys, the provided email address must be a member of the company the key belongs to; otherwise a 400 error is returned.
For USER-type API keys, the provided email must match the user who owns the key.

Responses

200 - Successful Response

Response type: JwtBasicResponse

Login successful. Returns a short-lived JWT access token and its expiration date. The returned JWT must be used as Authorization: Bearer {{jwt_token}} in all subsequent API requests.

{
  "jwt": "{{jwt_token}}",
  "expirationDate": "2026-01-15T12:00:00.000Z"
}

Response Fields

Root Fields

Field Name	Type	Description
jwt	String	JWT access token. Used as a Bearer token in the `Authorization` header for subsequent API requests.
expirationDate	String(ISO 8601)	The expiration date and time of the JWT token. After this date, the token is invalid and a new login is required.

Parameter Values Reference

apiKey — Values

Value	Description
COMPANY	A company-scoped API key. The user logging in with this key must be a member of the company the key is associated with. The resulting JWT is created with permissions restricted to that company.
USER	A user-scoped API key. Only the user who owns the key can log in using it.

400 - Bad Request

Trigger: When the provided API key is not found in the database.

{
  "errorMessage": "API key not found!",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: If the apiKey value sent does not match any record in the system, an IllegalStateException is thrown and a 400 Bad Request is returned. The errorType field is absent from the response for this error.

400 - Bad Request — API Key Out of Use

Trigger: When the API key has been deactivated or deleted.

{
  "errorMessage": "Provided api key is out of use! Please login with your credentials and try again.",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: If the API key has active=false or deleted=true, an IllegalStateException is thrown and a 400 Bad Request is returned.

400 - Bad Request — API Key Expired

Trigger: When the API key's expiration date has passed.

{
  "errorMessage": "Provided api key has expired! Please login with your credentials and try again.",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: If the expireDate of the API key is before the current time, an IllegalStateException is thrown and a 400 Bad Request is returned.

400 - Bad Request — User Not Authorized for Company

Trigger: When using a COMPANY-type API key but the specified email has no authorization in that company.

{
  "errorMessage": "Specified user email is not authorized to login with your credentials!",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: When logging in with a COMPANY-type API key, if the user associated with the provided email does not have a defined role in that company, an IllegalStateException is thrown and a 400 Bad Request is returned.

401 - Unauthorized

Trigger: When a USER-type API key is sent but the key owner does not match the provided email address.

{
  "errorMessage": "Invalid login attempt!",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: When a USER-type API key is used and the provided email does not match the owner of that key, an AuthorizationServiceException is thrown and a 401 Unauthorized is returned.

404 - Not Found

Trigger: When no active registered user is found with the provided email address.

{
  "errorMessage": "User not found!",
  "errorType": "NOT_FOUND_USER",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: If no non-deleted (deletedAt=null) user matching the provided email address is found, a NotFoundException is thrown and a 404 Not Found is returned.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/auth/login"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs.

3. Send Document Async POST

Purpose of Use: This endpoint is used to submit Base64-encoded invoice or waybill documents (XML or PDF) for asynchronous processing. When the request is received, the system queues the document and immediately returns a tracking ID — ensuring that lengthy document processing does not block the client.

Either apiKey or compId is required for identification. The authenticated user's access to the target company is verified via the JWT token. The document type must be specified using the invoiceType (invoice) or waybillType (waybill) field. After submission, the processing status can be polled via GET /invoice/document-status/{trackingId}.

Endpoint Information

Property	Value
URL	/invoice/send-document-async
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Required — r-Auth header (JWT token)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/send-document-async' \ 
--header 'Content-Type: application/json' \ 
--header 'r-Auth: {{jwt_token}}' \ 
--data-raw '{ 
  "apiKey": "{{your_api_key}}", 
  "base64Document": "{{base64_xml_document}}", 
  "businessType": "B2C", 
  "invoiceSource": "ERP", 
  "invoiceType": "RO_EFACTURA", 
  "receiverEmails": [ 
    "user@example.com" 
  ] 
}'

Request Parameters

Field Name	Type	Required	Description
apiKey	String	Conditional*	Integration API key. Required if `compId` is not provided; the company ID is resolved from this key.
compId	String(UUID)	Conditional*	Unique identifier of the target company. Required if `apiKey` is not provided.
base64Document	String	Conditional*	Base64-encoded XML invoice document. Required if `base64Pdf` is not provided.
base64Pdf	String	Conditional*	Base64-encoded PDF document (for ZUGFeRD/Factur-X format). Required if `base64Document` is not provided.
invoiceType	String(enum)	Conditional*	Format type of the invoice document. Required if `waybillType` is not provided. See the Parameter Values Reference table for supported values.
waybillType	String(enum)	Conditional*	Format type of the waybill document. Required if `invoiceType` is not provided. See the Parameter Values Reference table for supported values.
invoiceSource	String(enum)	Optional	Indicates the origin of the document (e.g. ERP, PORTAL, EMAIL). Used for system integration tracking.
receiverEmails	Array<String>	Optional	List of recipient email addresses to which the invoice will be delivered via email.
mailTemplateId	String	Optional	Identifier of the custom email template to use for email delivery.
businessType	String(enum)	Optional	Business model type: B2B (Business to Business), B2C (Business to Consumer), or B2G (Business to Government).

At least one of apiKey or compId is required. When both are provided, compId takes precedence.
Exactly one of invoiceType or waybillType must be provided; they cannot be used simultaneously.
At least one of base64Document or base64Pdf is required. base64Pdf is used exclusively for ZUGFeRD/Factur-X PDF documents.

Parameter Values Reference

invoiceType — Values

Value	Description
PEPPOL_BIS	Standard Peppol BIS Billing 3.0 UBL format (recommended)
RO_EFACTURA	Romania e-Invoice (CIUS-RO) format
XRECHNUNG	Germany XRechnung UBL format
UBL_NL	Netherlands UBL NLCIUS format
MY_INVOIS	Malaysia e-Invoice (MyInvois) format
MY_PINT	Malaysia Peppol PINT format
DK_OIOUBL	Denmark OIOUBL format
EG_INVOICE	Egypt e-Invoice format
HR_INVOICE	Croatia eRačun format
UAE_PINT	United Arab Emirates Peppol PINT format
FR_UBL_CIUS	France UBL CIUS format
FR_CII_CIUS	France CII CIUS format
FR_CDAR	France CDAR format
ZUGFERD	ZUGFeRD PDF/A-3 format (XML embedded in PDF)
FACTUR_X	Factur-X format (equivalent to ZUGFeRD)
XRECHNUNG_CII	XRechnung CII (UN/CEFACT) format
CII	UN/CEFACT CII format
CID	CID format
PDF	Unstructured invoice document (paper invoice image, etc.)
KZ_ESF_V2	Kazakhstan ESF v2 format
KSEF	Poland KSeF e-Invoice format
KSEF_OFFLINE	Poland KSeF offline mode format

waybillType — Values

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

invoiceSource — Values

Value	Description
ERP	ERP system integration
PORTAL	Manual upload via web portal
PORTAL_UPLOAD	File upload via web portal
EMAIL	Email integration
SFTP	SFTP transfer
PEPPOL	Document received via Peppol network
KSEF	Poland KSeF integration
SHOPIFY	Shopify integration
AMAZON_SP	Amazon Seller Partner integration
HUBSPOT	HubSpot integration
HARVEST	Harvest integration
STRIPE	Stripe integration

businessType — Values

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

Responses

200 - Successful Response

Response type: AsyncERPResponse

Document successfully accepted into the queue. Use the returned trackingId to monitor processing status via GET /invoice/document-status/{trackingId}.

{
  "trackingId": "{{tracking_uuid}}",
  "status": "PENDING",
  "message": null
}

Response Fields

Root Fields

Field Name	Type	Description
trackingId	String(UUID)	Unique identifier used to track document processing. Passed as a path variable to GET /invoice/document-status/{trackingId}.
status	String(enum)	Current status of the document processing. Returns `PENDING` on successful queue acceptance. See the Parameter Values Reference table for all possible values.
message	String	Optional informational message about the processing. Typically `null` on initial submission.

status — Values

Value	Description
PENDING	Document queued, processing not yet started
PROCESSING	Document is actively being processed
COMPLETED	Document successfully processed and delivered
FAILED	Processing failed
SENDING_FAILED	Document was processed but delivery failed
PERMANENT_FAILED	Permanently failed; no further retry attempts will be made

400 - Bad Request

Trigger: When both apiKey and compId are missing from the request.

{
  "errorMessage": "Document process required fields: apiKey or companyId",
  "errorType": "DOCUMENT_PROCESS_REQUIRED_FIELDS",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/send-document-async"
}

Description: At least one of apiKey or compId must be provided. When both are absent, an IllegalArgumentException (ErrorType: DOCUMENT_PROCESS_REQUIRED_FIELDS) is thrown returning 400 Bad Request.

400 - Bad Request — Missing Document Type

Trigger: When both invoiceType and waybillType are null.

{
  "errorMessage": "Document process required fields: invoiceType or waybillType",
  "errorType": "DOCUMENT_PROCESS_REQUIRED_FIELDS",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/send-document-async"
}

Description: Exactly one of invoiceType or waybillType must be specified. When both are null, an IllegalArgumentException (ErrorType: DOCUMENT_PROCESS_REQUIRED_FIELDS) is thrown.

400 - Bad Request — Missing Document Content

Trigger: When both base64Document and base64Pdf are null.

{
  "errorMessage": "Document process required fields: base64Document or base64Pdf",
  "errorType": "DOCUMENT_PROCESS_REQUIRED_FIELDS",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/send-document-async"
}

Description: At least one of base64Document or base64Pdf must be provided for the document content. When both are null, an IllegalArgumentException (ErrorType: DOCUMENT_PROCESS_REQUIRED_FIELDS) is thrown.

400 - Bad Request — Invalid API Key

Trigger: When an invalid or unrecognized apiKey is submitted.

{
  "errorMessage": "Invalid or unrecognized API key.",
  "errorType": "API_KEY_NOT_FOUND",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/send-document-async"
}

Description: If the provided apiKey does not match any active API key in the system, an IllegalArgumentException (ErrorType: API_KEY_NOT_FOUND) is thrown returning 400 Bad Request.

400 - Bad Request — API Key Company Not Found

Trigger: When the API key is valid but its associated company is deleted or not found.

{
  "errorMessage": "The provided API key is not associated with any company.",
  "errorType": "API_KEY_COMPANY_NOT_FOUND",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/send-document-async"
}

Description: Even if the API key is valid, if the associated company has been deleted (isDeleted=true) or cannot be found, an IllegalArgumentException (ErrorType: API_KEY_COMPANY_NOT_FOUND) is thrown.

401 - Unauthorized

Trigger: When the JWT token in the r-Auth header is missing, invalid, or expired.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/send-document-async"
}

Description: A valid JWT token must be provided in the r-Auth header. If the token is missing or invalid, an AuthorizationServiceException is thrown returning 401 Unauthorized.

401 - Unauthorized — Company Access

Trigger: When the authenticated user does not have access to the target company.

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

Description: Even with a valid JWT token, if the authenticated user is not associated with the target company, an AuthorizationServiceException (ErrorType: AUTHORIZATION_FAILED) is thrown returning 401 Unauthorized.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "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/send-document-async"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs.

4. Document Status GET

Purpose of Use: This endpoint is used to query the current processing status of an asynchronously submitted document (invoice, waybill, etc.). It allows tracking documents submitted via ERP integration, portal upload, or any other channel using the trackingId returned at submission time.

Asynchronous submission endpoints (e.g. /invoice/send-document-async, /invoice/send-by-file-async) enqueue documents for background processing and immediately return a trackingId. Developers are expected to poll this endpoint periodically until the document reaches a terminal state — COMPLETED (success) or FAILED / PERMANENT_FAILED (failure). Once COMPLETED, the documentId field contains the UUID of the created invoice or document record.

Endpoint Information

Property	Value
URL	/invoice/document-status/{trackingId}
Method	GET
Content-Type	None (GET request)
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header (JWT)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/document-status/{{tracking_uuid}}' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' 

Request Parameters

Path parameters

Field Name	Type	Required	Description
trackingId	String(UUID)	Required	The unique tracking identifier returned upon asynchronous document submission. Provided as a path parameter in the URL.

Responses

200 - Successful Response

Response type: DocumentProcessDto

Processing status retrieved successfully. The status field reflects the document's current state; poll this endpoint periodically until COMPLETED or a terminal failure state is reached. When COMPLETED, the documentId field contains the UUID of the created invoice or document record.

{
  "trackingId": "{{tracking_uuid}}",
  "companyId": "{{company_uuid}}",
  "direction": "OUTGOING",
  "documentType": "RO_EFACTURA",
  "waybillType": null,
  "source": "ERP",
  "target": "ANAF",
  "status": "COMPLETED",
  "filename": "invoice_2026_001.pdf",
  "invoiceNumber": "INV-2026-001",
  "documentId": "{{document_uuid}}",
  "sendingResult": "Document sent successfully",
  "errorType": null,
  "createdAt": "2026-04-28T09:00:00",
  "statusUpdatedAt": "2026-04-28T09:01:30",
  "completedAt": "2026-04-28T09:01:30",
  "errors": null,
  "additionalData": null
}

Response Fields

Root Fields

Field Name	Type	Description
trackingId	String(UUID)	The unique tracking identifier generated during async submission and tied to this processing record.
companyId	String(UUID)	Unique identifier of the company that submitted the document.
direction	String(enum: DocumentType)	Document direction. Either INCOMING (received from a supplier) or OUTGOING (sent to a customer or target system).
documentType	String(enum: DataType)	Data format of the processed document. E.g. PEPPOL_BIS, XRECHNUNG, ZUGFERD, KSEF.
waybillType	String(enum: WaybillDataType)	Waybill type. Populated only for waybill processing; `null` for invoice processing.
source	String(enum: InvoiceSource)	Source channel through which the document entered the system (ERP, PORTAL, PEPPOL, etc.).
target	String(enum: InvoiceSource)	Target system to which the document will be delivered (PEPPOL, ANAF, KSEF, etc.).
status	String(enum: DocumentProcessStatus)	Current processing status. Follows the flow: PENDING → PROCESSING → COMPLETED or FAILED.
filename	String	Name of the original uploaded file.
invoiceNumber	String	Invoice number extracted from the processed document. Populated after processing completes.
documentId	String(UUID)	UUID of the invoice or document record created upon successful completion. May be `null` before processing finishes.
sendingResult	String	Result of delivering the document to the target system. May contain a success confirmation or an error detail from the external system.
errorType	String(enum: ErrorType)	Error type when processing fails. `null` on successful processing.
errors	Object	Error details. If `errorType` is VALIDATION_FAILED, returns `List<ValidationError>`; otherwise `List<String>` or `String`. `null` on success.
additionalData	Object	Country- or document-type-specific additional metadata. Structure varies by processing type.
createdAt	String(ISO 8601)	Timestamp when the processing record was created.
statusUpdatedAt	String(ISO 8601)	Timestamp of the most recent status update.
completedAt	String(ISO 8601)	Timestamp when processing completed (successfully or with failure).

Parameter Values Reference

status — Values

Value	Description
PENDING	Processing is queued; not yet started. Continue polling.
PROCESSING	Processing is in progress; document is being converted or transmitted.
COMPLETED	Processing completed successfully. The `documentId` field is populated.
FAILED	Processing failed. The system may retry automatically.
SENDING_FAILED	Document was converted but delivery to the target system failed.
PERMANENT_FAILED	Processing permanently failed. No automatic retry will be attempted; manual intervention may be required.

direction — Values

Value	Description
INCOMING	Incoming document (invoice or waybill received from a supplier).
OUTGOING	Outgoing document (invoice or waybill sent to a customer or target system).

documentType — Values

Value	Description
PEPPOL_BIS	Peppol BIS Billing 3.0 format (UBL-based).
RO_EFACTURA	Romania e-Invoice format (UBL-based).
XRECHNUNG	Germany XRechnung UBL format.
XRECHNUNG_CII	Germany XRechnung CII format.
ZUGFERD	ZUGFeRD hybrid PDF/XML format.
FACTUR_X	France Factur-X / ZUGFeRD compatible format.
CII	UN/CEFACT CII (Cross Industry Invoice) format.
CID	CII-based Cross Industry Document format.
PDF	Unstructured PDF document (paper invoice, scanned image, etc.).
UBL_NL	Netherlands UBL format.
MY_INVOIS	Malaysia MyInvois e-Invoice format.
MY_PINT	Malaysia PINT (Peppol International) format.
DK_OIOUBL	Denmark OIOUBL format.
EG_INVOICE	Egypt e-Invoice format.
HR_INVOICE	Croatia eRačun format.
UAE_PINT	UAE Peppol PINT format.
FR_UBL_CIUS	France UBL CIUS format (Chorus Pro).
FR_CII_CIUS	France CII CIUS format (Chorus Pro).
FR_CDAR	France CDAR format.
KZ_ESF_V2	Kazakhstan ESF V2 electronic invoice format.
KSEF	Poland KSeF online e-Invoice format.
KSEF_OFFLINE	Poland KSeF offline mode e-Invoice format.

waybillType — Values

Value	Description
RS_WAYBILL_DESPATCH	Serbia waybill — Despatch Advice.
RS_WAYBILL_RECEIPT	Serbia waybill — Receipt Advice.
RS_APPLICATION_RESPONSE	Serbia waybill — Application Response.
RO_ETRANSPORT	Romania e-Transport waybill format.

source — Values

Value	Description
ERP	Submitted via ERP integration.
PORTAL	Manually created via the Docnova web portal.
PORTAL_UPLOAD	File uploaded through the portal.
PORTAL_OCR	Auto-extracted from PDF via portal OCR service.
MOBILE	Submitted via mobile application.
MOBILE_OCR	Auto-extracted from PDF via mobile OCR.
EMAIL	Received via email integration.
EMAIL_OCR	Auto-extracted from email attachment via OCR.
PEPPOL	Document received from or delivered to the Peppol network.
ANAF	Romania ANAF e-Invoice system.
KSEF	Poland KSeF system.
NEMHANDEL	Denmark NemHandel network.
LHDNM	Malaysia LHDN MyInvois system.
SFTP	SFTP file transfer.
HARVEST	Harvest accounting software integration.
SHOPIFY	Shopify e-commerce integration.
AMAZON_SP	Amazon Selling Partner integration.
EBAY	eBay integration.
HUBSPOT	HubSpot CRM integration.
LAZADA	Lazada e-commerce integration.
TEMU	Temu e-commerce integration.
RS_API	Serbia official API integration.
ETA	Egypt ETA e-Invoice system.
ERACUN	Croatia eRačun system.
STRIPE	Stripe payment platform integration.
PPF	France Portail Public de Facturation (Chorus Pro).
PA_SFTP	Public authority SFTP transfer.
SERVICE	Document created by an internal service.

404 - Not Found

Trigger: When the provided trackingId does not exist in the database.

Response body: null (empty body). The standard ExceptionResponse format is not applied on this endpoint.

Description: When no processing record matches the given trackingId, the service layer throws ApiError(INVOICE_PROCESS_NOT_FOUND). The controller catches this exception and returns 404 Not Found with an empty (null) body. Underlying error message: Tracking ID not found.

500 - Internal Server Error

Trigger: When an unexpected server-side error occurs.

Response body: null (empty body). The standard ExceptionResponse format is not applied on this endpoint.

Description: If an unexpected error occurs in the service layer, the controller catches the general Exception and returns 500 Internal Server Error with an empty (null) body.

5. Search Processing History POST

Purpose of Use: This endpoint is used to query a company's document processing records (DocumentProcess) in a paginated manner using multi-criteria filters. Records for documents sent or received in various formats such as Peppol, e-Invoice, XRechnung, and KSeF can be filtered by processing status (PENDING, PROCESSING, COMPLETED, FAILED, etc.), direction (INCOMING/OUTGOING), source system (ERP, PORTAL, PEPPOL, etc.), document type (RO_EFACTURA, XRECHNUNG, PEPPOL_BIS, etc.), and date ranges for creation and status update timestamps.

This endpoint is particularly useful for identifying failed (FAILED / SENDING_FAILED / PERMANENT_FAILED) submission records, monitoring batch processing pipelines, and troubleshooting integration issues. The response is a Spring Page structure containing a list of DocumentProcessDto objects along with total record count and pagination metadata. Each record may include error type, error details, and country-specific additional data (additionalData).

Endpoint Information

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

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/document-process/search?paged=true&pageNumber=0&pageSize=20' \ 
--header 'Content-Type: application/json' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "companyId": "{{company_uuid}}", 
  "createdAt": { 
    "from": "2025-01-01", 
    "to": "2026-04-28" 
  }, 
  "direction": "OUTGOING", 
  "documentType": "RO_EFACTURA", 
  "source": "ERP", 
  "status": "FAILED", 
  "statusUpdatedAt": { 
    "from": "2025-01-01", 
    "to": "2026-04-28" 
  }, 
  "waybillType": null 
}'

Request Parameters

Query parameters

Field Name	Type	Required	Description
paged	Boolean	Optional	Whether to return paginated results. Default: `true`
pageNumber	Number	Optional	Zero-based page number. Default: `0`
pageSize	Number	Optional	Number of records per page. Default: `20`

Request body

Field Name	Type	Required	Description
companyId	String(UUID)	Required	Unique identifier of the company whose document processing records will be queried
direction	String(enum)	Optional	Document direction: OUTGOING (sent by the company) or INCOMING (received by the company)
source	String(enum)	Optional	Source channel that submitted the document to the system (ERP, PORTAL, PEPPOL, etc.)
documentType	String(enum)	Optional	Document format or type (RO_EFACTURA, XRECHNUNG, PEPPOL_BIS, etc.)
waybillType	String(enum)	Optional	Waybill data type. Pass `null` for invoice record searches.
filename	String	Optional	Text filter applied to the original uploaded filename
invoiceNumber	String	Optional	Text filter applied to the invoice number within the document
status	String(enum)	Optional	Filter by document processing status (PENDING, COMPLETED, FAILED, etc.)
createdAt	Object	Optional	Date range filter applied to the record creation timestamp
createdAt.from	String(ISO 8601 — YYYY-MM-DD)	Optional	Start date of the creation date range (must be past or present)
createdAt.to	String(ISO 8601 — YYYY-MM-DD)	Optional	End date of the creation date range (must be past or present)
statusUpdatedAt	Object	Optional	Date range filter applied to the status update timestamp
statusUpdatedAt.from	String(ISO 8601 — YYYY-MM-DD)	Optional	Start date of the status update date range
statusUpdatedAt.to	String(ISO 8601 — YYYY-MM-DD)	Optional	End date of the status update date range

Responses

200 - Successful Response

Response type: Page<DocumentProcessDto>

Search successful. Document processing records matching the specified filter criteria are returned along with pagination metadata. If no sort order is specified, records are returned in descending order by createdAt by default.

{
  "content": [
    {
      "trackingId": "{{entity_uuid}}",
      "companyId": "{{company_uuid}}",
      "direction": "OUTGOING",
      "documentType": "RO_EFACTURA",
      "waybillType": null,
      "source": "ERP",
      "target": "ANAF",
      "status": "FAILED",
      "filename": "invoice-2025-001.xml",
      "invoiceNumber": "INV-2025-001",
      "documentId": "{{invoice_uuid}}",
      "sendingResult": null,
      "errorType": "VALIDATION_FAILED",
      "createdAt": "2025-06-15T10:30:00",
      "statusUpdatedAt": "2025-06-15T10:31:05",
      "completedAt": null,
      "errors": ["Field 'taxNumber' is required"],
      "additionalData": null
    }
  ],
  "totalElements": 42,
  "totalPages": 3,
  "size": 20,
  "number": 0,
  "numberOfElements": 20,
  "first": true,
  "last": false,
  "empty": false
}

Response Fields

Pagination Metadata (Page)

Field Name	Type	Description
content	Array<DocumentProcessDto>	List of document processing records matching the search criteria
totalElements	Number	Total number of records matching the filter criteria across all pages
totalPages	Number	Total number of pages
size	Number	Maximum number of records per page (`pageSize` parameter)
number	Number	Current page number (zero-based)
numberOfElements	Number	Actual number of records returned on this page
first	Boolean	Whether the current page is the first page
last	Boolean	Whether the current page is the last page
empty	Boolean	Whether the page is empty (`true` when the content list has no elements)

Document Processing Record Fields (content[])

Field Name	Type	Description
content[].trackingId	String(UUID)	Unique tracking identifier for the processing record. Used for error diagnosis and status queries.
content[].companyId	String(UUID)	Unique identifier of the company that owns the document
content[].direction	String(enum)	Direction of the document: INCOMING (received) or OUTGOING (sent)
content[].documentType	String(enum)	Document format (RO_EFACTURA, XRECHNUNG, PEPPOL_BIS, etc.)
content[].waybillType	String(enum) \| null	Waybill document type. Returns `null` for invoice records.
content[].source	String(enum)	Source channel that submitted the document (ERP, PORTAL, PEPPOL, etc.)
content[].target	String(enum)	Target system the document was sent to (ANAF, KSEF, NEMHANDEL, etc.)
content[].status	String(enum)	Current processing status (PENDING, PROCESSING, COMPLETED, FAILED, etc.)
content[].filename	String \| null	Original filename of the uploaded document
content[].invoiceNumber	String \| null	Invoice number extracted from the document
content[].documentId	String(UUID) \| null	Unique identifier of the successfully created document (InvoiceEntity). May be `null` if processing has not yet completed.
content[].sendingResult	String \| null	Result of transmission to the external system (external system response on success, error message on failure)
content[].errorType	String(enum) \| null	Error type classification. Only populated for FAILED or SENDING_FAILED statuses.
content[].createdAt	String(ISO 8601)	Timestamp when the processing record was created
content[].statusUpdatedAt	String(ISO 8601)	Timestamp of the most recent status update
content[].completedAt	String(ISO 8601) \| null	Timestamp when the processing completed. Returns `null` for incomplete records.
content[].errors	Object \| null	Error detail payload. When `errorType` is VALIDATION_FAILED: `List<ValidationError>`; otherwise: `List<String>` or `String`.
content[].additionalData	Object \| null	Country-specific or document-type-specific additional metadata (structure varies by `documentType`)

Parameter Values Reference

direction — Values

Value	Description
INCOMING	Incoming document (invoice or waybill received by the company)
OUTGOING	Outgoing document (invoice or waybill sent by the company)

status — Values

Value	Description
PENDING	Processing has been queued and has not yet started
PROCESSING	Processing is currently in progress
COMPLETED	Processing completed successfully
FAILED	Processing failed (may be retried)
SENDING_FAILED	Document was created but transmission to the external system failed
PERMANENT_FAILED	Processing permanently failed; no further retries will be attempted

documentType — Values

Value	Description
PEPPOL_BIS	Peppol BIS UBL format (international standard)
RO_EFACTURA	Romanian e-Invoice (ANAF) format
XRECHNUNG	German XRechnung UBL format
XRECHNUNG_CII	German XRechnung CII format
ZUGFERD	ZUGFeRD PDF/XML hybrid format
FACTUR_X	Factur-X PDF/XML hybrid format (FR/DE)
CII	UN/CEFACT Cross Industry Invoice format
CID	CID format
UBL_NL	Dutch UBL format
MY_INVOIS	Malaysian InvoIS format (LHDNM)
MY_PINT	Malaysian Peppol PINT format
DK_OIOUBL	Danish OIOUBL format
EG_INVOICE	Egyptian e-Invoice (ETA) format
HR_INVOICE	Croatian eRačun format
UAE_PINT	UAE Peppol PINT format
FR_UBL_CIUS	French UBL CIUS format
FR_CII_CIUS	French CII CIUS format
FR_CDAR	French CDAR format
PDF	Unstructured PDF (paper invoice, image, etc.)
KZ_ESF_V2	Kazakhstan e-SF v2 format
KSEF	Polish KSeF online invoice format
KSEF_OFFLINE	Polish KSeF offline invoice format

source — Values

Value	Description
ERP	Submitted via ERP integration
PORTAL	Uploaded through the web portal
PORTAL_UPLOAD	Submitted via portal file upload
PORTAL_OCR	Scanned via portal OCR processing
MOBILE	Submitted via mobile application
MOBILE_OCR	Scanned via mobile OCR processing
EMAIL	Received as an email attachment
EMAIL_OCR	Email attachment scanned via OCR
PEPPOL	Transmitted via the Peppol network
SFTP	Transferred via SFTP integration
ANAF	Romanian ANAF system (source/target)
KSEF	Polish KSeF system
NEMHANDEL	Danish NemHandel system
LHDNM	Malaysian LHDNM system
SERVICE	Internal service processing
HARVEST	Harvest integration
SHOPIFY	Shopify integration
AMAZON_SP	Amazon Seller Partner integration
EBAY	eBay integration
HUBSPOT	HubSpot integration
LAZADA	Lazada integration
TEMU	Temu integration
RS_API	Serbian RS API system
ETA	Egyptian ETA system
ERACUN	Croatian eRačun system
STRIPE	Stripe payment system
PPF	PPF integration
PA_SFTP	PA SFTP integration

waybillType — Values

Value	Description
RS_WAYBILL_DESPATCH	Serbian waybill despatch document
RS_WAYBILL_RECEIPT	Serbian waybill receipt document
RS_APPLICATION_RESPONSE	Serbian waybill application response
RO_ETRANSPORT	Romanian e-Transport waybill document

401 - Unauthorized

Trigger: When the r-auth header JWT token is missing, expired, or has an invalid signature.

{
  "errorMessage": "Full authentication is required to access this resource",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/document-process/search"
}

Description: The Spring Security filter returns a 401 Unauthorized response before the request reaches the controller when it cannot validate the JWT in the r-auth header. The token may be expired, have an invalid signature, or the header may be entirely absent.

401 - Unauthorized — Insufficient Company Authority

Trigger: When the authenticated user does not hold ADMIN, INCOMING_INVOICE_DISPLAY, or OUTGOING_INVOICE_DISPLAY authority for the specified company.

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

Description: AuthorizationService.checkAnyAuthorityByCompanyAndUser() verifies that the user identified by the JWT holds at least one of the required authorities (ADMIN, INCOMING_INVOICE_DISPLAY, or OUTGOING_INVOICE_DISPLAY) for the company specified in the request body. If none of these authorities are present, an AuthorizationServiceException is thrown and a 401 response is returned.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "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/document-process/search"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs (e.g. database connection loss, null pointer, or other runtime exceptions).

6. Search Document with Filter POST

Purpose of Use: This endpoint is used to search incoming and outgoing invoices/documents belonging to a company using various filter criteria with paginated results. Filters such as date range, document direction (incoming/outgoing), invoice status, document format type, and reference document number are supported.

The response includes the total record count, currency-based financial totals (net amount, tax amount, payable amount), and the invoice list. Each invoice record contains supplier/customer details, status history, payment details, and country-specific data. This endpoint is primarily used by ERP integrations, portal clients, and external systems.

Endpoint Information

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

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/search-documents' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "companyId": "{{company_uuid}}", 
  "documentType": "OUTGOING", 
  "endDate": "2026-04-27", 
  "invoiceSearchType": "CREATE_DATE", 
  "page": 0, 
  "referenceDocument": "INV-2024-001", 
  "size": 20, 
  "startDate": "2024-01-01", 
  "status": "PORTAL_ERROR", 
  "type": null, 
  "uit": "{{uit_code}}" 
}'

Request Parameters

Field Name	Type	Required	Description
companyId	String(UUID)	Optional	Unique identifier of the company whose documents are to be searched
documentType	String(enum)	Optional	Document direction filter: INCOMING or OUTGOING
status	String(enum)	Optional	Invoice status filter. See Parameter Values Reference table for allowed values
type	String(enum)	Optional	Document format type filter (e.g. PEPPOL_BIS, XRECHNUNG, ZUGFERD). If omitted, all formats are returned
invoiceSearchType	String(enum)	Optional	Date field used for the date range search. Default: CREATE_DATE
startDate	String(ISO 8601)	Optional	Search start date (inclusive). Format: `yyyy-MM-dd`
endDate	String(ISO 8601)	Optional	Search end date (inclusive). Format: `yyyy-MM-dd`
referenceDocument	String	Optional	Free-text search against invoice number, supplier name, or customer name. At least 3 characters recommended. Returns 400 if the matching candidate set exceeds 10,000 records
tin	String	Optional	Tax Identification Number filter
uit	String	Optional	Unique Invoice Token — country-specific invoice identifier (e.g. Malaysia)
page	Number	Optional	Zero-based page number. Default: `0`
size	Number	Optional	Number of records per page. Maximum: 200. Default: 200

referenceDocument full-text search is activated when the value is at least 3 characters; shorter inputs are not filtered.
When referenceDocument is used and the candidate result set exceeds 10,000 records, a 400 Bad Request is returned — narrow the search criteria.
The size field must not exceed 200; exceeding this triggers a validation error.
If invoiceSearchType is not specified, CREATE_DATE is used as the default.

Parameter Values Reference

documentType — Values

Value	Description
INCOMING	Incoming invoice / document
OUTGOING	Outgoing invoice / document

invoiceSearchType — Values

Value	Description
CREATE_DATE	Search by system creation date (default)
ISSUE_DATE	Search by invoice issue date
DUE_DATE	Search by payment due date

type — Values

Value	Description
PEPPOL_BIS	Peppol BIS 3.0 format (European Peppol network invoice)
RO_EFACTURA	Romanian e-Invoice format (ANAF portal)
XRECHNUNG	German XRechnung format (UBL-based)
UBL_NL	Dutch UBL format
MY_INVOIS	Malaysian MyInvois format (LHDNM)
MY_PINT	Malaysian Peppol PINT format
DK_OIOUBL	Danish OIOUBL format
EG_INVOICE	Egyptian ETA e-invoice format
HR_INVOICE	Croatian eRacun format
UAE_PINT	UAE Peppol PINT format
FR_UBL_CIUS	French UBL CIUS format (CTC/PPF)
FR_CII_CIUS	French CII CIUS format (CTC/PPF)
FR_CDAR	French CDAR format
ZUGFERD	ZUGFeRD hybrid PDF/XML format
FACTUR_X	Factur-X hybrid PDF/XML format (France/Germany)
XRECHNUNG_CII	XRechnung CII XML format
CII	UN/CEFACT Cross Industry Invoice (CII) format
CID	Cross Industry Document (CID) format
PDF	Unstructured PDF invoice (processed by OCR)
KSEF	Polish KSeF format (online)
KSEF_OFFLINE	Polish KSeF format (offline)
KZ_ESF_V2	Kazakhstan ESF v2 format

Responses

200 - Successful Response

Response type: DocumentSearchResponse

Search successful. Returns total record count, currency-based financial totals, and the invoice list.

{
  "totalCount": 42,
  "currencyTotals": [
    {
      "currency": "EUR",
      "totalAmount": 12450.00,
      "netAmount": 10500.00,
      "taxAmount": 1950.00,
      "payableAmount": 8750.00
    }
  ],
  "invoiceList": [
    {
      "id": "{{invoice_uuid}}",
      "companyId": "{{company_uuid}}",
      "userId": "{{user_uuid}}",
      "customerName": "Example Customer GmbH",
      "supplierName": "Example Supplier Ltd.",
      "supplierId": "{{entity_uuid}}",
      "supplierVat": "RO123456789",
      "status": "PORTAL_ERROR",
      "invoiceNumber": "INV-2024-001",
      "taxExclusiveAmount": 1000.00,
      "taxInclusiveAmount": 1190.00,
      "lineExtensionAmount": 1000.00,
      "payableAmount": 1190.00,
      "allowanceTotalAmount": 0.00,
      "currency": "EUR",
      "createdTime": "2024-03-15T10:30:00",
      "localCreatedTime": "2024-03-15T11:30:00",
      "issueDate": "2024-03-15",
      "deliveryDate": "2024-03-20",
      "dueDate": "2024-04-15",
      "supplierCountryCode": "RO",
      "supplierEndpoint": "0088:1234567890123",
      "customerId": "{{entity_uuid}}",
      "customerVat": "RO987654321",
      "customerEndpoint": "0088:9876543210987",
      "customerCountryCode": "RO",
      "typeCode": "380",
      "documentType": "OUTGOING",
      "errorMessage": "Portal returned error: Invalid tax number",
      "lastUpdatedTime": "2024-03-15T12:00:00",
      "localLastUpdatedTime": "2024-03-15T13:00:00",
      "type": "RO_EFACTURA",
      "idIncarcare": null,
      "idDescarcare": null,
      "source": "ERP",
      "sendViaPeppol": false,
      "statusTime": "2024-03-15T11:45:00",
      "localStatusTime": "2024-03-15T12:45:00",
      "fileName": "invoice_2024_001.xml",
      "ocrParser": null,
      "paymentDetails": {
        "paymentStatus": "SENT",
        "paidAmount": 0.00,
        "totalAmount": 1190.00,
        "remainingAmount": 1190.00,
        "paymentDate": null
      },
      "profileType": "EN16931",
      "isActive": true,
      "countrySpecificData": null,
      "isRead": false,
      "governmentStatus": null,
      "orderReference": "PO-2024-001",
      "purchaseOrder": "PO-2024-001"
    }
  ]
}

Response Fields

Root Fields

Field Name	Type	Description
totalCount	Number	Total number of invoices/documents matching the filter criteria
currencyTotals	Array<Object>	List of financial summary objects grouped by currency
invoiceList	Array<Object>	List of invoice/document objects returned for the current page

Currency Totals (currencyTotals[])

Field Name	Type	Description
currencyTotals[].currency	String	Currency code (ISO 4217, e.g. EUR, USD, RON)
currencyTotals[].totalAmount	Number	Total amount including VAT
currencyTotals[].netAmount	Number	Net amount excluding VAT (sum of taxExclusiveAmount)
currencyTotals[].taxAmount	Number	Total tax amount (totalAmount - netAmount)
currencyTotals[].payableAmount	Number	Remaining payable amount (after deducting payments)

Invoice List (invoiceList[])

Field Name	Type	Description
invoiceList[].id	String(UUID)	Unique system identifier of the invoice
invoiceList[].companyId	String(UUID)	Identifier of the company that owns the invoice
invoiceList[].userId	String(UUID)	Identifier of the user who uploaded the invoice
invoiceList[].customerName	String	Customer / buyer name
invoiceList[].supplierName	String	Supplier / seller name
invoiceList[].supplierId	String(UUID)	System identifier of the supplier company
invoiceList[].supplierVat	String	Supplier VAT number
invoiceList[].status	String(enum)	Current status code of the invoice. See Parameter Values Reference table for allowed values
invoiceList[].invoiceNumber	String	Invoice number
invoiceList[].taxExclusiveAmount	Number	Amount excluding VAT
invoiceList[].taxInclusiveAmount	Number	Total amount including VAT
invoiceList[].lineExtensionAmount	Number	Line extension amount (before discounts)
invoiceList[].payableAmount	Number	Amount payable
invoiceList[].allowanceTotalAmount	Number	Total allowance / discount amount
invoiceList[].currency	String	Invoice currency code (ISO 4217)
invoiceList[].createdTime	String(ISO 8601)	Timestamp when the invoice was saved in the system (UTC)
invoiceList[].localCreatedTime	String(ISO 8601)	Invoice creation time in the company's local timezone
invoiceList[].issueDate	String(ISO 8601)	Invoice issue date
invoiceList[].deliveryDate	String(ISO 8601)	Delivery date
invoiceList[].dueDate	String(ISO 8601)	Payment due date
invoiceList[].supplierCountryCode	String	Supplier country code (ISO 3166-1 alpha-2)
invoiceList[].supplierEndpoint	String	Supplier Peppol endpoint address
invoiceList[].customerId	String(UUID)	System identifier of the customer company
invoiceList[].customerVat	String	Customer VAT number
invoiceList[].customerEndpoint	String	Customer Peppol endpoint address
invoiceList[].customerCountryCode	String	Customer country code (ISO 3166-1 alpha-2)
invoiceList[].typeCode	String	UBL document type code (e.g. 380: Commercial Invoice, 381: Credit Note)
invoiceList[].documentType	String(enum)	Document direction: INCOMING or OUTGOING
invoiceList[].errorMessage	String	Error description from the portal or processing pipeline in case of failure
invoiceList[].lastUpdatedTime	String(ISO 8601)	Last update timestamp (UTC)
invoiceList[].localLastUpdatedTime	String(ISO 8601)	Last update timestamp (local timezone)
invoiceList[].type	String(enum)	Document format type (PEPPOL_BIS, XRECHNUNG, ZUGFERD, etc.)
invoiceList[].idIncarcare	String	Upload ID assigned by the Romanian ANAF portal (Romania-specific)
invoiceList[].idDescarcare	String	Download ID assigned by the Romanian ANAF portal (Romania-specific)
invoiceList[].source	String(enum)	Channel through which the invoice entered the system (portal, ERP, Peppol, OCR, etc.)
invoiceList[].sendViaPeppol	Boolean	Indicates whether the invoice was sent via the Peppol network
invoiceList[].statusTime	String(ISO 8601)	Timestamp of the most recent status change (UTC)
invoiceList[].localStatusTime	String(ISO 8601)	Status change timestamp (local timezone)
invoiceList[].fileName	String	Original name of the uploaded file
invoiceList[].ocrParser	String(enum)	OCR engine used to process the document
invoiceList[].profileType	String(enum)	ZUGFeRD / Factur-X profile type (MINIMUM, BASIC, EN16931, EXTENDED, etc.)
invoiceList[].isActive	Boolean	Whether the invoice is active
invoiceList[].countrySpecificData	Object	Country-specific additional data field (structure varies by country)
invoiceList[].isRead	Boolean	Whether the invoice has been read by the user
invoiceList[].governmentStatus	String(enum)	Government portal status code (e.g. TDD_APPROVED, WITHDRAW_SEND)
invoiceList[].orderReference	String	Order reference number
invoiceList[].purchaseOrder	String	Purchase order number (PO number)

Payment Details (invoiceList[].paymentDetails)

Field Name	Type	Description
invoiceList[].paymentDetails.paymentStatus	String(enum)	Payment status: SENT, PAID, PARTIAL_PAID, or LATE
invoiceList[].paymentDetails.paidAmount	Number	Total amount paid to date
invoiceList[].paymentDetails.totalAmount	Number	Total invoice amount
invoiceList[].paymentDetails.remainingAmount	Number	Remaining unpaid amount
invoiceList[].paymentDetails.paymentDate	String(ISO 8601)	Payment date

Parameter Values Reference

status / invoiceList[].status — Values

Value	Description
CREATED	Invoice created
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_PDF	Saved as PDF
PENDING	Awaiting processing
CANCELED	Canceled
DELETED	Deleted
SENT_VIA_EMAIL	Sent via email
READY_FOR_KSEF	Ready for KSeF submission
SENT_TO_ACCESS_POINT	Sent to access point
COMPLETED_BY_MELA_AI	Completed by Mela AI
CREDIT_BLOCKED	Blocked due to credit limit
OCR_WAITING	Waiting for OCR processing
OCR_PARSED	OCR processing completed
OCR_FAILED	OCR processing failed
OCR_PARSED_PENDING_PAYMENT	OCR completed, awaiting payment
OCR_WAITING_TOKEN	Waiting for OCR token
SENT_TO_ANAF	[Romania] Sent to ANAF portal
PORTAL_OKAY	[Romania] Portal approved
PORTAL_ERROR	[Romania] Portal returned an error
PORTAL_ERRORS	[Romania] Portal returned multiple errors
PORTAL_SYSTEM_ERROR	[Romania] Portal system error
PORTAL_IN_PROCESS	[Romania] Portal is processing
LHDNM_SUBMITTED	[Malaysia] Submitted to LHDNM portal
LHDNM_VALID	[Malaysia] LHDNM valid
LHDNM_INVALID	[Malaysia] LHDNM invalid
LHDNM_CANCELLED	[Malaysia] LHDNM cancelled
LHDNM_REJECT_REQUESTED	[Malaysia] Rejection requested
LHDNM_REJECTED	[Malaysia] Rejected
LHDNM_ERROR	[Malaysia] LHDNM error
KSEF_PENDING	[Poland] KSeF pending
KSEF_ACCEPTED	[Poland] KSeF accepted
KSEF_REJECTED	[Poland] KSeF rejected
KSEF_DUPLICATE	[Poland] KSeF duplicate
ERACUN_ERROR	[Croatia] eRacun error
ERACUN_PENDING	[Croatia] eRacun pending
ERACUN_SENT	[Croatia] eRacun sent
ERACUN_RECEIVED	[Croatia] eRacun received
ERACUN_APPROVED	[Croatia] eRacun approved
ERACUN_REJECTED	[Croatia] eRacun rejected
ERACUN_FULLY_PAID	[Croatia] Fully paid
ERACUN_PARTIALLY_PAID	[Croatia] Partially paid
ERACUN_DELIVERY_FAILED	[Croatia] Delivery failed
ETA_SUBMITTED	[Egypt] Submitted to ETA portal
SENT_TO_NEMHANDEL	[Denmark] Sent to Nemhandel network
SENT_TO_PEPPOL	[Peppol] Sent to Peppol network
SUCCESS	[Peppol] Successfully delivered
INVALID_PARAMETERS	[Peppol] Invalid parameters
TRANSPORT_ERROR	[Peppol] Transport error
TRANSPORT_ERROR_NO_RETRY	[Peppol] Permanent transport error (no retry)
SMP_LOOKUP_FAILED	[Peppol] SMP lookup failed
INCOMING_RESPONSE_ACKNOWLEDGED	[Peppol] Incoming response acknowledged (MLR/MLS)
INCOMING_RESPONSE_REJECTED	[Peppol] Incoming response rejected
INCOMING_RESPONSE_ACCEPTED	[Peppol] Incoming response accepted
OUTGOING_RESPONSE_ACKNOWLEDGED	[Peppol] Outgoing response acknowledged
OUTGOING_RESPONSE_REJECTED	[Peppol] Outgoing response rejected
OUTGOING_RESPONSE_ACCEPTED	[Peppol] Outgoing response accepted
FR_DEPOSITED	[France] Deposited to portal
FR_REJECTED	[France] Rejected
FR_RECEIVED	[France] Received
FR_AVAILABLE	[France] Available
FR_PROCESSING	[France] Processing
FR_APPROVED	[France] Approved
FR_PARTIALLY_APPROVED	[France] Partially approved
FR_DISPUTED	[France] Disputed
FR_SUSPENDED	[France] Suspended
FR_PLATFORM_ISSUED	[France] Issued by platform
FR_REFUSED	[France] Refused (platform)
FR_PAYMENT_SENT	[France] Payment sent
FR_COLLECTED	[France] Collected
FR_COMPLETED	[France] Completed
FR_CANCELLED	[France] Cancelled

invoiceList[].source — Values

Value	Description
PORTAL	Uploaded via web portal interface
PORTAL_UPLOAD	Portal file upload
PORTAL_OCR	From portal OCR processing
MOBILE	Uploaded from mobile app
MOBILE_OCR	From mobile OCR processing
EMAIL	Received via email
EMAIL_OCR	From email OCR processing
ERP	Submitted via ERP integration
PEPPOL	Received via Peppol network
LHDNM	Malaysia LHDNM portal
NEMHANDEL	Denmark Nemhandel network
ANAF	Romania ANAF portal
KSEF	Poland KSeF system
SFTP	SFTP integration
SHOPIFY	Shopify integration
AMAZON_SP	Amazon Seller Partner integration
EBAY	eBay integration
HUBSPOT	HubSpot integration
STRIPE	Stripe payment integration
SERVICE	Created by internal service
HARVEST	Harvest integration
ERACUN	Croatian eRacun system
ETA	Egyptian ETA portal
RS_API	Serbia API integration
PPF	France PPF (Portail Public de Facturation)
PA_SFTP	Partner SFTP integration
TEMU	Temu e-commerce integration
LAZADA	Lazada e-commerce integration

invoiceList[].ocrParser — Values

Value	Description
DOCNOVA_AI	Docnova AI OCR engine
GOOGLE_DOCUMENT_AI	Google Document AI OCR engine

invoiceList[].profileType — Values

Value	Description
MINIMUM	Minimum profile (mandatory fields only)
BASICWL	Basic WL profile (without line items)
BASIC	Basic profile
EN16931	EN 16931 compliant profile (default)
EXTENDED	Extended profile
XRECHNUNG	XRechnung profile
KSEF_FA2	[Poland] FA (2) KSeF profile
KSEF_FA3	[Poland] FA (3) KSeF profile

invoiceList[].governmentStatus — Values

Value	Description
TDD_SEND	TDD submission sent
TDD_FAILED	TDD submission failed
TDD_APPROVED	Approved by TDD
TDD_ACKNOWLEDGED	Acknowledged by TDD
TDD_REJECTED	Rejected by TDD
WITHDRAW_SEND	Withdrawal request sent
WITHDRAW_FAILED	Withdrawal request failed

invoiceList[].paymentDetails.paymentStatus — Values

Value	Description
SENT	Invoice sent, awaiting payment
PAID	Fully paid
PARTIAL_PAID	Partially paid
LATE	Late, payment is overdue

400 - Bad Request

Trigger: When referenceDocument search candidate set exceeds 10,000 records.

{
  "errorMessage": "Search result set is too large for in-memory filtering. Please narrow your search criteria.",
  "errorType": "SEARCH_RESULT_TOO_LARGE",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/search-documents"
}

Description: When the referenceDocument filter is active, all candidate records are loaded into memory for sorting. If the candidate set exceeds 10,000 records, an IllegalArgumentException is thrown and returned as 400 Bad Request. Narrow the date range or apply additional filters (status, documentType, type) to reduce the result set.

400 - Bad Request — Page Size Validation

Trigger: When size field exceeds 200 (validation error).

{
  "errorMessage": "size: must be less than or equal to 200",
  "errorType": "VALIDATION_ERROR",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": [
    { "field": "size", "message": "must be less than or equal to 200" }
  ],
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/search-documents"
}

Description: The size field in DocumentSearchBody is subject to a @Max(200) constraint. Sending a value greater than 200 causes Spring @Valid validation to fail, returning 400 Bad Request.

401 - Unauthorized

Trigger: When r-auth header is missing, expired, or contains an invalid JWT token.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/search-documents"
}

Description: Requests without a valid JWT token or without sufficient access rights to this endpoint are rejected via AuthorizationServiceException. Ensure the r-auth header contains a valid, non-expired JWT token.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/search-documents"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs (e.g. database connection failure, internal service outage).

7. Create New Waybill POST

Purpose of Use: This endpoint receives DESADV01-format IDoc data from SAP systems, converts it to the Romanian ANAF e-Transport V2 schema, and submits it as a new waybill. It is the recommended primary endpoint for new ERP integrations; the legacy V1 format is available at /waybill/RO/new/v1.

The processing flow is as follows: the submitted Base64-encoded IDoc XML is decoded and unmarshalled into a DESADV01 object, then transformed into the ANAF ETransportType V2 schema and validated against the XSD. Upon successful validation, the document is uploaded to ANAF servers. The response contains the ANAF-assigned UIT (Unique Identification Token) and Index Incarcare (loading index), along with the persisted waybill record. One document credit is deducted from the company's balance on each successful submission; in case of failure, the credit is automatically refunded.

Endpoint Information

Property	Value
URL	/waybill/RO/new
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/new?taxNumber={{tax_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "idocXml": "{{base64_encoded_idoc_xml}}" 
}'

Request Parameters

Query parameters

Field Name	Type	Required	Description
taxNumber	String	Required	The Romanian tax identification number (CUI/CIF) of the company. Used to identify the company registered in the system that the authenticated user is authorized for. Sent as a URL query parameter.

Request body

Field Name	Type	Required	Description
idocXml	String(Base64)	Required	Base64 Standard Encoding of the IDoc XML content in SAP DESADV01 (Dispatch Advice) format. The system automatically converts this into the ANAF e-Transport V2 (ETransportType) format.

taxNumber is sent as a query parameter appended to the URL: POST /waybill/RO/new?taxNumber=26054330
The idocXml value must be a valid SAP DESADV01 IDoc XML structure encoded with Java Base64.getEncoder() (RFC 4648 Standard Alphabet).
The r-auth header is mandatory. Requests with a missing, invalid, or expired token will return 401 Unauthorized.

Responses

200 - Successful Response

Response type: RomaniaWaybillDto

Waybill successfully created and submitted to the ANAF e-Transport system. The response contains the ANAF-assigned UIT and Index Incarcare values, with waybillStatus set to SENT.

{
  "waybillId": "{{waybill_uuid}}",
  "deliveryNo": "RIM2025000591750",
  "referenceDocument": "CJ70PZB",
  "uit": "{{uit_code}}",
  "indexIncarcare": "100000001",
  "goodsIssueDt": "2026-04-26",
  "transportDate": "2026-04-26",
  "receipent": "{{Receipent_Name}}",
  "waybillStatus": "SENT",
  "companyCode": "26054330",
  "createdTime": "2026-04-26T10:30:00",
  "documentType": "OUTGOING",
  "waybillType": null,
  "comment": null,
  "waybillResponseType": null,
  "lastUpdateTime": null,
  "errMsg": null,
  "countryCode": "RO"
}

Response Fields

Root Fields

Field Name	Type	Description
waybillId	String(UUID)	Unique identifier of the waybill record created in the Docnova system
deliveryNo	String	Delivery number extracted from the IDoc (derived from the DESADV01 VBELN field)
referenceDocument	String	Reference document number (derived from IDoc TRAID or related identifier field)
uit	String	ANAF-assigned Unique Identification Token — the waybill's unique identifier within the ANAF e-Transport system
indexIncarcare	String	ANAF loading index number — assigned by ANAF, used for status queries
goodsIssueDt	String	Goods issue date derived from the IDoc DATUM field (YYYY-MM-DD format)
transportDate	String	Planned transport / delivery date (YYYY-MM-DD format)
receipent	String	Recipient party name (taken from the TU (Ship-To) partner NAME1 field in the IDoc)
waybillStatus	String(enum)	Current status of the waybill. Set to SENT immediately after a successful ANAF submission.
companyCode	String	Tax number (CUI/CIF) of the company that created the waybill
createdTime	String(ISO 8601)	Timestamp when the waybill was created in the Docnova system
documentType	String(enum)	Document direction: waybills created via ERP integration are always marked as OUTGOING
waybillType	String	Waybill type (optional, may be populated based on IDoc content)
comment	String	Additional comment on the waybill (optional)
waybillResponseType	String(enum)	Response type provided by the counterparty. `null` at creation time; populated when a response is received.
lastUpdateTime	String	Timestamp of the last update to the waybill
errMsg	String	Error message — `null` on successful operations; contains ANAF error detail if an error is returned
countryCode	String	Country code (ISO 3166-1 alpha-2). Always `RO` for Romania.

Parameter Values Reference

waybillStatus — Values

Value	Description
CREATED	Waybill created in the system, not yet submitted to ANAF
CREDIT_BLOCKED	Operation blocked due to insufficient credit
SENT	Waybill successfully submitted to the ANAF e-Transport system
RESPONDED	Counterparty has responded to the waybill
CANCELLED	Waybill has been cancelled
EDITED	Waybill has been edited and resubmitted
RECEIVED	Waybill has been received
ERROR	An error occurred during ANAF processing
SUCCESS	Processing completed successfully
IN_PROGRESS	Waybill processing is in progress
DELIVERY_CONFIRMED	Delivery has been confirmed
DELIVERED	Delivery has been completed
SEIZED	Waybill has been seized
FULFILLED	Waybill has been fulfilled
ACCEPTED	Waybill has been accepted
REJECTED	Waybill has been rejected
NOT_FOUND_AT_ANAF	Waybill could not be found in the ANAF system

documentType — Values

Value	Description
OUTGOING	Outgoing document — waybill sent to ANAF by the company (always this value for ERP-generated waybills)
INCOMING	Incoming document — waybill received from another party

waybillResponseType — Values

Value	Description
APPROVE	Full approval — ANAF service code: 10
PARTIAL_APPROVE	Partial approval — ANAF service code: 20
REJECT	Rejection — ANAF service code: 30

400 - Bad Request

Trigger: When the e-Transport V2 XML produced from the IDoc fails ANAF XSD schema validation.

{
  "errorMessage": "Validation failed for e-Transport XML",
  "errorType": "VALIDATION_FAILED",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": [
    "cvc-minLength-valid: Value '' with length = '0' is not facet-valid with respect to minLength '1' for type 'String50'",
    "Element 'CodDeclarant' is missing or invalid"
  ],
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new"
}

Description: When the converted XML is validated against ANAF's e-Transport V2 XSD schema by WaybillValidationService and violations are detected, an ApiError(VALIDATION_FAILED) is thrown. The validationErrors array lists each schema constraint violation in detail. The IDoc source data must be corrected and the request resubmitted.

400 - Bad Request — Concurrent Operation

Trigger: When another document credit operation for the same company is already holding the Redis lock.

{
  "errorMessage": "Concurrent operation already in progress for this company",
  "errorType": "CONCURRENT_OPERATION_IN_PROGRESS",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new"
}

Description: Since the system runs as multiple server instances, if two document consumption operations for the same company are initiated simultaneously, the Redis distributed lock mechanism prevents a race condition and throws IllegalStateException(CONCURRENT_OPERATION_IN_PROGRESS). This is a transient error; retrying after a few seconds is sufficient.

401 - Unauthorized

Trigger: When the r-auth header is missing or invalid, or when the user has no role for the company matching the taxNumber.

{
  "errorMessage": "Authorization failed",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new"
}

Description: Triggered in two scenarios: (1) If the JWT token is missing or expired, the Spring Security layer returns 401 directly. (2) If the token is valid but the authenticated user has no role assigned to the company identified by the given taxNumber, an AuthorizationServiceException is thrown and 401 Unauthorized is returned.

422 - Unprocessable Entity

Trigger: When no active product plan is found for the company or when credits are exhausted for an outgoing document.

{
  "errorMessage": "Credit not found for company",
  "errorType": "CREDIT_NOT_FOUND",
  "errorTitle": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new"
}

Description: When the DocumentConsumptionService cannot resolve an active product plan for the company, a GeneralException(CREDIT_NOT_FOUND) is thrown and 422 Unprocessable Entity is returned. The same error is triggered when insufficient credits remain for an OUTGOING document. The company's subscription plan and credit balance must be reviewed and updated.

500 - Internal Server Error

Trigger: When the company is not found by taxNumber, when idocXml is not valid DESADV01 XML, when IDoc-to-V2 transformation fails, or when the ANAF upload service is unavailable.

{
  "errorMessage": "Company not found with tax number: 26054330",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new"
}

Description: Four scenarios trigger a 500 Internal Server Error: (1) No non-deleted company matching the taxNumber exists in the system — a RuntimeException is thrown; (2) The idocXml value does not contain valid DESADV01 XML — the JAXB Unmarshaller throws a JAXBException; (3) An unexpected error occurs in the IDoc-to-V2 transformer; (4) The ANAF upload service is unreachable or returns a 5xx error. In all failure scenarios, the document credit is automatically refunded to the company.

8. Create New Waybill from XML POST

Purpose of Use: This endpoint is used to create and submit a new waybill record to the Romanian ANAF e-Transport system. The client sends an ANAF e-Transport-compliant XML document (v1 or v2 schema) encoded in Base64 as a raw string in the request body.

The system decodes the Base64 payload, validates the XML against XSD and XSLT rules, verifies company authorization, decrements the subscription document quota, and uploads the XML directly to the ANAF e-Transport API. On success, the UIT (Unique Identifier Transport) number and loading index assigned by ANAF are returned. The result is also persisted as a waybill record in Docnova and archived to S3. This endpoint is particularly suited for ERP integrations (SAP, Oracle, etc.) where pre-generated eTransport XML documents need to be submitted to ANAF through Docnova.

Endpoint Information

Property	Value
URL	/waybill/RO/new/xml
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — R-Auth header — Required

Example Request

curl -X POST "https://api-stage.docnova.ai/waybill/RO/new/xml?taxNumber={{tax_number}}" \ 
-H "accept: */*" \ 
-H "R-Auth: {{jwt_token}}" \ 
-H "Content-Type: application/json" \ 
-d "{{base64_encoded_etransport_xml}}" 

Request Parameters

Field Name	Location	Type	Required	Description
R-Auth	Header	String(JWT)	Required	JWT token used for authentication. Passed via the `R-Auth` header.
taxNumber	Query Parameter	String	Required	The CUI/CIF tax number of the company registered in Romania. The company must already exist in Docnova.
body	Request Body	String(Base64)	Required	Base64-encoded ANAF e-Transport schema-compliant XML document (v1 or v2). The schema version is automatically extracted from the XML namespace.

The request body must be sent as a raw Base64 string, not wrapped in a JSON object.
The XML document must contain the mfp:anaf:dgti:eTransport:declaratie:v1 or v2 namespace; otherwise the version cannot be resolved and a 500 is returned.
The submitted XML is validated against ANAF XSD and XSLT business rules. A 400 is returned if validation fails, with error details in validationErrors.

Responses

200 - Successful Response

Response type: RomaniaWaybillDto

Waybill created and submitted to ANAF e-Transport successfully. The UIT number and loading index assigned by ANAF are returned. Waybill status is set to SENT.

{
  "waybillId": "{{waybill_uuid}}",
  "deliveryNo": "80012345",
  "referenceDocument": "80012345",
  "uit": "{{uit_code}}",
  "indexIncarcare": "987654321",
  "goodsIssueDt": "2026-04-26",
  "transportDate": "2026-04-26",
  "receipent": "{{Receipent_Name}}",
  "waybillStatus": "SENT",
  "companyCode": "ROMN",
  "createdTime": "2026-04-26T10:30:00",
  "documentType": "OUTGOING",
  "waybillType": "60",
  "comment": null,
  "waybillResponseType": null,
  "lastUpdateTime": null,
  "errMsg": null,
  "countryCode": "RO"
}

Response Fields

Root Fields

Field Name	Type	Description
waybillId	String(UUID)	Unique identifier of the waybill in the Docnova system
deliveryNo	String	Delivery / shipment number
referenceDocument	String	Reference document number (VBELN)
uit	String	Unique Transport Identifier assigned by ANAF (UIT). Used for tracking and status queries.
indexIncarcare	String	ANAF loading index. Required when querying status via `/get-status-anaf`.
goodsIssueDt	String(ISO 8601)	Goods issue date
transportDate	String(ISO 8601)	Planned transport date
receipent	String	Recipient commercial partner code (CIF / tax number)
waybillStatus	String(enum)	Current status of the waybill. Returns SENT after successful submission.
companyCode	String	Declaring company code (codDeclarant)
createdTime	String(ISO 8601)	Timestamp when the waybill was created in Docnova
documentType	String(enum)	Document direction. Always returns OUTGOING for new waybills.
waybillType	String	ANAF operation type code (codTipOperatiune). See Parameter Values Reference for allowed values.
comment	String	Optional comment note. Returns null if not provided.
waybillResponseType	String(enum)	Response type. Returns null for this endpoint; populated only after `/respond`.
lastUpdateTime	String(ISO 8601)	Last update timestamp. Returns null for newly created waybills.
errMsg	String	Error message from ANAF. Returns null on successful submission.
countryCode	String	Country code (ISO 3166-1 alpha-2). Always `RO` for Romania.

Parameter Values Reference

waybillStatus — Values

Value	Description
CREATED	Created, not yet sent to ANAF
SENT	Successfully submitted to ANAF
IN_PROGRESS	ANAF is processing the waybill
SUCCESS	Accepted by ANAF
ERROR	ANAF returned an error
EDITED	Waybill has been edited
CANCELLED	Waybill has been cancelled
RESPONDED	A response has been submitted to the waybill
RECEIVED	Marked as received
NOT_FOUND_AT_ANAF	Not found at ANAF (transient state)
CREDIT_BLOCKED	Blocked due to credit limit exceeded
DELIVERY_CONFIRMED	Delivery confirmed
DELIVERED	Delivered
SEIZED	Goods seized
FULFILLED	Fulfilled
ACCEPTED	Accepted
REJECTED	Rejected

documentType — Values

Value	Description
OUTGOING	Outgoing document (export / outbound sale)
INCOMING	Incoming document (import / inbound purchase)

waybillResponseType — Values

Value	Description
APPROVE	Approved (ANAF code: 10)
PARTIAL_APPROVE	Partially approved (ANAF code: 20)
REJECT	Rejected (ANAF code: 30)

waybillType — Values

Value	Description
10	Export — locIncarcare (loading location) and codPtf (PTF code) required
20	Import — locIncarcare and codPtf required
30	Domestic sale — locIncarcare and locDescarcare (unloading location) required
40	Temporary import — locDescarcare and codBirouVamal (customs office code) required
50	Temporary export — locIncarcare and codBirouVamal required
60	Goods acquisition from abroad — locDescarcare and codPtf required
70	Goods return — locIncarcare and codPtf required

400 - Bad Request

Trigger: When the submitted XML fails ANAF XSD schema or XSLT business rule validation.

{
  "errorMessage": "XML validation failed",
  "errorType": "VALIDATION_FAILED",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new/xml",
  "validationErrors": [
    {
      "field": "/eTransport/notificare/bunuriTransportate[1]",
      "code": "BR-RO-001",
      "message": "Attribute 'codTarifar' must match the customs tariff code format."
    }
  ]
}

Description: ApiError(VALIDATION_FAILED) is thrown inside WaybillValidationService.validate(). The XML is validated first against the XSD schema and then against XSLT business rules. Validation failures are returned in the validationErrors array, where each entry contains field (XPath to the failing element), code (rule identifier), and message (human-readable description).

401 - Unauthorized

Trigger: When the JWT token is missing, invalid, or expired; or when the authenticated user does not belong to the specified company.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new/xml"
}

Description: AuthorizationServiceException is thrown. Triggered in two scenarios: (1) If the JWT token is invalid or expired — caught at the Spring Security filter layer. (2) If the authenticated user does not belong to the company matched by taxNumber — thrown inside authorizationService.checkIfCompanyUser(). The errorType is always NOT_AUTHORITY.

422 - Unprocessable Entity

Trigger: When the company's active subscription plan has no remaining document quota.

{
  "errorMessage": "Document quota exceeded. Please upgrade your subscription.",
  "errorType": "QUOTA_EXCEEDED",
  "errorTitle": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new/xml"
}

Description: GeneralException is thrown in documentConsumptionService.validateAndDecrementDocumentCount(). This error is returned when the company's subscription plan document allowance is exhausted or no active plan exists. The partially created waybill record is automatically rolled back via refundDocumentCount() on failure.

500 - Internal Server Error

Trigger: When company is not found by taxNumber; unsupported XML version is provided; JAXB unmarshalling fails; or the ANAF service is unreachable.

{
  "errorMessage": "Company not found with tax number: {{tax_number}}",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-04-26T10:30:00",
  "path": "/waybill/RO/new/xml"
}

Description: A 500 can be returned in multiple scenarios: (1) If no Romanian company matching the taxNumber is found in Docnova, RuntimeException('Company not found with tax number: ...') is thrown. (2) If the XML namespace version cannot be resolved to v1 or v2, RuntimeException('Unsupported waybill version: ...') is thrown. (3) If JAXB unmarshalling fails due to a malformed XML structure, JAXBException is propagated and caught by the global Exception handler, returning 500. (4) If the ANAF REST service is unreachable or returns an unexpected error, the exception is propagated as a RuntimeException or Exception. In all cases errorType returns RUNTIME_ERROR or SERVER_ERROR.

9. Check Waybill Status from ANAF GET

Purpose of Use: This endpoint is used to query the real-time status of a previously submitted waybill directly from the Romanian ANAF e-Transport system. After a waybill submission, it allows developers to check whether processing has been completed on the ANAF side, whether a validation error has occurred, or whether a UIT number has been assigned.

The endpoint uses the waybill's stored indexIncarcare (upload index) and the company's CIF number to call ANAF's stareMesaj service and forwards the raw JSON response as-is. This response contains the processing status (stare), an execution status code (ExecutionStatus), and any error messages (Errors) if applicable. The waybill must exist in the system and the requesting user must be a member of the associated company.

Endpoint Information

Property	Value
URL	/waybill/RO/get-status-anaf
Method	GET
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/get-status-anaf?waybillId={{waybill_uuid}}' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' 

Request Parameters

Query parameters

Field Name	Type	Required	Description
waybillId	String(UUID)	Required	The unique identifier (UUID) of the waybill whose status is to be queried

Responses

200 - Successful Response

Response type: String(ANAF JSON)

The raw JSON response from the ANAF stareMesaj service is returned as a string. The stare field indicates the processing status, ExecutionStatus provides a numeric execution code, and Errors.errorMessage contains the ANAF-side error message if any. The example below shows the typical structure when that string is parsed.

{
  "stare": "ok",
  "dateResponse": "202404291145",
  "ExecutionStatus": 0,
  "Errors": {
    "errorMessage": ""
  }
}

Response Fields

ANAF Status Response (stareMesaj)

Field Name	Type	Description
stare	String(enum)	The processing status of the waybill in the ANAF system. Possible values: `ok`, `in prelucrare`, `nok`
dateResponse	String	The date and time when ANAF generated the response (format: yyyyMMddHHmm)
ExecutionStatus	Number	Execution status code. `0` means successful processing; `1` or other values indicate an error or processing still in progress
Errors	Object	An object containing ANAF-side error information
Errors.errorMessage	String	Empty string if no error; otherwise the error description returned by ANAF

Parameter Values Reference

stare — Values

Value	Description
ok	Waybill was successfully processed and validated by ANAF
in prelucrare	Waybill is still being processed by ANAF; result is not yet available
nok	Waybill was rejected by ANAF or a validation error occurred

ExecutionStatus — Values

Value	Description
0	Processing successful — waybill was processed by ANAF
1	Processing failed or still in progress

401 - Unauthorized

Trigger: When the user is not a member of the company that owns the waybill, or when the JWT token is invalid or missing.

{
  "errorMessage": "Authorization failed",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-29T12:00:00",
  "path": "/waybill/RO/get-status-anaf"
}

Description: An AuthorizationServiceException is thrown when the user does not have access to the company that owns the requested waybill, returning a 401 Unauthorized response. This error also occurs when the r-auth header is missing or contains an invalid JWT token.

404 - Not Found

Trigger: When no waybill exists for the given waybillId, or when no ANAF OAuth token is registered for the associated company.

{
  "errorMessage": "No such waybill with id: {{waybill_uuid}}",
  "errorType": "NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-29T12:00:00",
  "path": "/waybill/RO/get-status-anaf"
}

Description: A NotFoundException is thrown in two cases: (1) when no waybill record is found in the database for the given UUID, or (2) when no ANAF OAuth token record exists in TokenRepository for the waybill's associated company. Both cases return a 404 Not Found response.

500 - Internal Server Error

Trigger: When an unexpected server error occurs or when the connection to the ANAF service fails.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-04-29T12:00:00",
  "path": "/waybill/RO/get-status-anaf"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs, or when a connection to the ANAF stareMesaj service cannot be established or a response cannot be received.

10. Search Waybills POST

Purpose of Use: This endpoint is used to search and list waybills created through the Romanian e-Transport system (ANAF) using various filter criteria. Results are returned in a paginated format.

Users can query by UIT number, waybill status, document type, reference document number, waybill type, and date range. The company is resolved from the taxNumber query parameter in the URL, not from the companyId field in the request body. Even if companyId is included in the request body, it is silently ignored by the server. Authorization is performed via JWT token; the token holder must have access rights to the specified company.

Endpoint Information

Property	Value
URL	/waybill/RO/search
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header (JWT) — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/search?taxNumber={{tax_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "documentType": "OUTGOING", 
  "fromDate": "2026-04-23", 
  "toDate": "2026-04-27", 
  "page": 0, 
  "size": 20, 
  "referenceDocument": "RIM2025000059175", 
  "uit": "{{uit_code}}", 
  "waybillStatus": "SUCCESS", 
  "waybillType": "60" 
}'

Request Parameters

Query parameters

Field Name	Type	Required	Description
taxNumber	String	Required	The company's tax identification number (CUI/CIF). Sent as a URL query parameter. The company is resolved from this value.

Request body

Field Name	Type	Required	Description
uit	String	Optional	UIT (Unic Identificator Transport) number assigned by ANAF. Filters by exact match.
waybillStatus	String(enum)	Optional	Status of the waybill. See the Parameter Values Reference table for allowed values.
documentType	String(enum)	Optional	Document direction: INCOMING (received) or OUTGOING (sent).
waybillType	String	Optional	ANAF e-Transport waybill type code. E.g.: `"60"` (combined transport).
referenceDocument	String	Optional	Reference document number from the ERP system. Filters by exact match.
fromDate	String(ISO 8601 Date)	Optional	Search start date (YYYY-MM-DD). Inclusive, filters from the start of the day (00:00:00).
toDate	String(ISO 8601 Date)	Optional	Search end date (YYYY-MM-DD). Inclusive, filters up to the end of the day (23:59:59).
page	Number	Optional	Page number (zero-based). Defaults to 0 if not specified.
size	Number	Optional	Number of records per page. Defaults to 50 if not specified.

The companyId field, even if included in the request body, is silently ignored by the server. The company is automatically resolved from the taxNumber query parameter.
All body parameters are optional; when any parameter is omitted, that filter is not applied and all records are returned (subject to pagination).
Results are sorted in descending order by plannedDeliveryDate (most recent first).

Responses

200 - Successful Response

Response type: Page<RomaniaWaybillDto>

Search completed successfully. Waybills matching the filters are returned as a paginated list. If no records match, the content array is empty.

{
  "content": [
    {
      "waybillId": "{{waybill_uuid}}",
      "deliveryNo": "DEL-2026-001",
      "referenceDocument": "RIM2025000059175",
      "uit": "{{uit_code}}",
      "indexIncarcare": "1234567890",
      "goodsIssueDt": "2026-04-23",
      "transportDate": "2026-04-24",
      "receipent": "{{Receipent_Name}}",
      "waybillStatus": "SUCCESS",
      "companyCode": "RO01",
      "createdTime": "2026-04-23T10:30:00",
      "documentType": "OUTGOING",
      "waybillType": "60",
      "comment": null,
      "waybillResponseType": null,
      "lastUpdateTime": "2026-04-24T08:15:00",
      "errMsg": null,
      "countryCode": "RO"
    }
  ],
  "pageable": {
    "sort": { "empty": false, "sorted": true, "unsorted": false },
    "offset": 0,
    "pageSize": 20,
    "pageNumber": 0,
    "paged": true,
    "unpaged": false
  },
  "totalPages": 1,
  "totalElements": 1,
  "last": true,
  "first": true,
  "size": 20,
  "number": 0,
  "numberOfElements": 1,
  "empty": false
}

Response Fields

Pagination Fields (Page wrapper)

Field Name	Type	Description
content	Array<RomaniaWaybillDto>	List of waybills matching the search filters
totalElements	Number	Total number of records matching the filter across all pages
totalPages	Number	Total number of pages
size	Number	Page size specified in the request
number	Number	Current page number (zero-based)
first	Boolean	Whether this is the first page
last	Boolean	Whether this is the last page
numberOfElements	Number	Number of records on the current page
empty	Boolean	Whether the current page is empty

Waybill fields (`content[]`)

Field Name	Type	Description
content[].waybillId	String(UUID)	Unique identifier of the waybill within the system
content[].deliveryNo	String	Delivery number
content[].referenceDocument	String	Reference document number from the ERP system
content[].uit	String	UIT (Unic Identificator Transport) number assigned by ANAF
content[].indexIncarcare	String	ANAF loading index number
content[].goodsIssueDt	String	Goods issue date
content[].transportDate	String	Transport date
content[].receipent	String	Recipient company name or identifier
content[].waybillStatus	String(enum)	Current status of the waybill. See the Parameter Values Reference table for allowed values.
content[].companyCode	String	Company code in the ERP system
content[].createdTime	String(ISO 8601)	Timestamp when the waybill was created in the system
content[].documentType	String(enum)	Document direction: INCOMING or OUTGOING
content[].waybillType	String	ANAF e-Transport waybill type code
content[].comment	String	Optional comment attached to the waybill
content[].waybillResponseType	String(enum)	Response type for incoming waybills: APPROVE, PARTIAL_APPROVE, or REJECT
content[].lastUpdateTime	String	Timestamp of the last update to the waybill
content[].errMsg	String	ANAF error message; `null` for successful operations
content[].countryCode	String	Country code, always RO (Romania)

Parameter Values Reference

waybillStatus — Values

Value	Description
CREATED	Waybill has been created, not yet submitted
CREDIT_BLOCKED	Submission blocked due to insufficient credit
SENT	Submitted to ANAF, awaiting response
RESPONDED	A response has been submitted for an incoming waybill
CANCELLED	Waybill has been cancelled
EDITED	Waybill was edited and resubmitted to ANAF
RECEIVED	Received by the recipient
ERROR	An error occurred during processing
SUCCESS	Successfully validated and approved by ANAF
IN_PROGRESS	Processing is in progress at ANAF
DELIVERY_CONFIRMED	Delivery has been confirmed
DELIVERED	Delivery completed
SEIZED	Waybill has been seized by authorities
FULFILLED	All waybill processes have been completed
ACCEPTED	Accepted by the recipient
REJECTED	Rejected by the recipient
NOT_FOUND_AT_ANAF	Not found in the ANAF system

documentType — Values

Value	Description
OUTGOING	Outgoing document — waybill created by the company
INCOMING	Incoming document — waybill sent to the company

waybillResponseType — Values

Value	Description
APPROVE	Full acceptance (ANAF code: 10)
PARTIAL_APPROVE	Partial acceptance (ANAF code: 20)
REJECT	Rejection (ANAF code: 30)

400 - Bad Request

Trigger: When an invalid enum value is sent for waybillStatus or documentType, or when the JSON body cannot be parsed.

{
  "errorMessage": "JSON parse error: Cannot deserialize value of type `WaybillStatus` from String ...",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/search"
}

Description: If a value not defined in the WaybillStatus or DocumentType enum classes is sent for the waybillStatus or documentType fields, Jackson throws a JSON parse error and Spring returns 400 Bad Request. This error also occurs if the JSON body has a syntax error.

401 - Unauthorized

Trigger: When the JWT token holder does not have access rights to the company identified by taxNumber.

{
  "errorMessage": "Authorization failed",
  "errorType": "AUTHORIZATION_FAILED",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/search"
}

Description: The authorizationService.checkIfCompanyUser() method throws AuthorizationServiceException if no role relationship exists between the JWT user and the company, returning a 401 Unauthorized response. This error also occurs when the r-auth header is missing or contains an invalid JWT token.

500 - Internal Server Error

Trigger: When no active (non-deleted) company is found for the provided taxNumber, or when an unexpected server error occurs.

{
  "errorMessage": "Company not found with tax number: {{tax_number}}",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/search"
}

Description: In the service layer, if companyRepository.findByTaxNumberAndCountryAndIsDeletedFalse() cannot find an active company with the given taxNumber and RO country code, a RuntimeException is thrown. This exception is caught by RestExceptionHandler and returned as 500 Internal Server Error. The same error may also occur due to database or other infrastructure issues.

11. Edit Waybill POST

Purpose of Use: This endpoint is used to update an existing Romania e-Transport waybill that was previously submitted to the ANAF system. The delivery document in SAP IDoc format (DESADV01) is sent Base64-encoded; the system automatically decodes this XML, converts it to the e-Transport V1 XML format, validates it against ANAF's XSD schema and Schematron rules, and then forwards it to ANAF as a correction request via the REST service.

The edit operation can only be performed on an existing waybill: the uit field in the request body must match the UIT (Unique Identification for Transport) code assigned by ANAF during the initial submission and must correspond to a waybill recorded in the system. Upon successful update, the waybill status is set to EDITED, and the new UIT and indexIncarcare values returned from ANAF are persisted to the database and included in the response.

Endpoint Information

Property	Value
URL	/waybill/RO/edit
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header (JWT) — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/edit?taxNumber={{tax_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "idocXml": "{{base64_encoded_idoc_xml}}", 
  "uit": "{{uit_code}}" 
}'

Request Parameters

Query parameters

Field Name	Type	Required	Description
taxNumber	String	Required	Tax identification number (CUI/CIF) of the company registered in ANAF. Used to locate the company in the database and verify that the authenticated user belongs to that company.

Request body

Field Name	Type	Required	Description
idocXml	String(Base64)	Required	Base64-encoded SAP IDoc XML content. Must be in DESADV01 (Despatch Advice) format. The system automatically decodes this value and transforms it into the e-Transport V1 XML format.
uit	String	Required	UIT (Unique Identification for Transport) code assigned by ANAF during the initial waybill submission. Used to locate the existing waybill record in the system; an incorrect or non-existent value results in a 404 error.

taxNumber is sent as a URL query parameter (not in the request body).
The idocXml field value must be Base64-encoded. Raw XML cannot be sent directly.
The uit field must be the UIT value returned from the initial waybill submission to ANAF.
The number of product line items in the IDoc XML (E1EDP07 segments) must not exceed 3000; otherwise the request will be rejected with a 500 error.

Responses

200 - Successful Response

Response type: RomaniaWaybillDto

Edit successful. Returns the updated waybill information. The waybillStatus field is set to EDITED, and the new UIT and indexIncarcare values returned from ANAF are included in the response.

{
  "waybillId": "{{waybill_uuid}}",
  "deliveryNo": "RIM20260001234",
  "referenceDocument": "RIM20260001234",
  "uit": "{{uit_code}}",
  "indexIncarcare": "5001234567",
  "goodsIssueDt": "2026-04-26",
  "transportDate": "2026-04-26",
  "receipent": "{{Receipent_Name}}",
  "waybillStatus": "EDITED",
  "companyCode": "ROMN",
  "createdTime": "2026-01-15T10:00:00",
  "documentType": "OUTGOING",
  "waybillType": "60",
  "comment": null,
  "waybillResponseType": null,
  "lastUpdateTime": "2026-04-26T14:30:00",
  "errMsg": null,
  "countryCode": "RO"
}

Response Fields

Root Fields

Field Name	Type	Description
waybillId	String(UUID)	Unique identifier of the waybill in the system
deliveryNo	String	Delivery number extracted from the IDoc (VBELN field)
referenceDocument	String	Reference document number
uit	String	Unique Identification for Transport code assigned by ANAF
indexIncarcare	String	ANAF upload index; used for status polling operations
goodsIssueDt	String	Goods loading date (from IDoc E1EDK07/DATUM field)
transportDate	String	Transport date (from IDoc E1EDK06/DATUM field)
receipent	String	Recipient commercial partner code (PARTN from IDoc PARVW=WE segment)
waybillStatus	String(enum)	Current status of the waybill. Set to EDITED after a successful edit.
companyCode	String	Company code (from IDoc BUKRS field)
createdTime	String(ISO 8601)	Initial creation timestamp of the waybill
documentType	String(enum)	Document direction: INCOMING or OUTGOING
waybillType	String	ANAF operation type code (from IDoc CODTO field; e.g. `'60'` = EU inbound)
comment	String	Optional comment field for the waybill
waybillResponseType	String(enum)	Approval response type from the recipient. Typically `null` after an edit operation.
lastUpdateTime	String(ISO 8601)	Timestamp of the last update
errMsg	String	Error message returned from ANAF. `null` on successful operations.
countryCode	String	Country code (ISO 3166-1 alpha-2). Always `RO` for Romania.

Parameter Values Reference

waybillStatus — Values

Value	Description
CREATED	Created
CREDIT_BLOCKED	Blocked due to insufficient credit
SENT	Submitted to ANAF
RESPONDED	Responded to by recipient
CANCELLED	Cancelled
EDITED	Edited and resubmitted to ANAF
RECEIVED	Received
ERROR	Error occurred
SUCCESS	Successfully approved by ANAF
IN_PROGRESS	Being processed by ANAF
DELIVERY_CONFIRMED	Delivery confirmed
DELIVERED	Delivered
SEIZED	Seized
FULFILLED	Fulfilled
ACCEPTED	Accepted
REJECTED	Rejected
NOT_FOUND_AT_ANAF	Not found in ANAF system

documentType — Values

Value	Description
INCOMING	Incoming document
OUTGOING	Outgoing document

waybillResponseType — Values

Value	Description
APPROVE	Approved (ANAF code: 10)
PARTIAL_APPROVE	Partially approved (ANAF code: 20)
REJECT	Rejected (ANAF code: 30)

400 - Bad Request

Trigger: When the e-Transport XML generated from the IDoc fails ANAF XSD schema or Schematron business rule validation.

{
  "errorMessage": "Validation failed",
  "errorType": "VALIDATION_FAILED",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "validationErrors": [
    {
      "location": "/eTransport/notificare/bunuriTransportate[1]",
      "id": "BR-RO-001",
      "message": "Campul denumireMarfa este obligatoriu"
    }
  ],
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/edit"
}

Description: WaybillValidationService.validate() checks the generated XML against ANAF's XSD schema and XSLT/Schematron rules. If any rule is violated, ApiError(VALIDATION_FAILED) is thrown and 400 Bad Request is returned. The validationErrors array contains the location, rule ID, and message for each failing field.

401 - Unauthorized

Trigger: When the JWT token is invalid or expired, or the authenticated user does not have a registered role in the company associated with the given taxNumber.

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/edit"
}

Description: An AuthorizationServiceException is thrown when an invalid or expired JWT token is provided in the r-auth header, or when the authenticated user does not have a registered role in the company identified by taxNumber. Even if the company lookup succeeds, authorizationService.checkIfCompanyUser() enforces this check and returns 401 Unauthorized.

404 - Not Found

Trigger: When no waybill exists in the system matching the uit value provided in the request body.

{
  "errorMessage": "No such waybill with uit: {{uit_code}}",
  "errorType": "NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/edit"
}

Description: A NotFoundException is thrown when WaybillRepository.findFirstByGovernmentReferenceId(uit) returns empty. Ensure the UIT code was obtained from a successful initial waybill submission and has not been deleted.

500 - Internal Server Error

Trigger: When company is not found, Base64 decoding or XML parsing fails, or IDoc item count exceeds 3000.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/waybill/RO/edit"
}

Description: Returns 500 Internal Server Error in the following cases: (1) no active Romania company is found for the given taxNumber (Company not found with tax number: ...); (2) idocXml contains invalid Base64 or the decoded content is not a valid DESADV01 XML; (3) the number of E1EDP07 segments in the IDoc exceeds 3000 (Waybill data is too long. It must be 3000 or less!); (4) the ANAF REST service is unavailable or returns an unexpected error.

12. Respond to Waybill POST

Purpose of Use: This endpoint is used to send a response to a waybill registered in the Romanian ANAF e-Transport system. The recipient company can approve, partially approve, or reject a waybill identified by its UIT (Unique Identification Token).

The response is transmitted to the ANAF e-Transport system in real time, and the waybill's local status (waybillStatus) is automatically updated to RESPONDED. This endpoint requires JWT authentication and can only be called by users with access rights to the related company. Company verification is performed via the taxNumber query parameter, followed by a check that the user belongs to that company.

Endpoint Information

Property	Value
URL	/waybill/RO/respond
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/respond?taxNumber={{tax_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "cif": "{{tax_number}}", 
  "uit": "{{uit_code}}", 
  "waybillResponseType": "PARTIAL_APPROVE" 
}'

Request Parameters

Query parameters

Field Name	Type	Required	Description
taxNumber	String	Required	The Romanian tax identification number (CUI/CIF) of the company. Sent as a query string parameter. Used to identify the company in the system.

Request body

Field Name	Type	Required	Description
cif	String	Required	The company CIF number used when submitting the response to the ANAF e-Transport system. Sent in the request body.
uit	String	Required	The Unique Identification Token assigned by ANAF for the waybill being responded to. If no waybill with this UIT exists in the system, a 404 error is returned.
waybillResponseType	String(enum)	Required	The type of response to the waybill. Refer to the Parameter Values Reference table for allowed values.

Responses

200 - Successful Response

Response type: RomaniaWaybillDto

Response successfully submitted to the ANAF e-Transport system and the waybill status has been updated to RESPONDED. Returns the updated waybill record.

{
  "waybillId": "{{entity_uuid}}",
  "deliveryNo": "DEL-2026-00123",
  "referenceDocument": "PO-2026-00456",
  "uit": "{{uit_code}}",
  "indexIncarcare": "3001234567",
  "goodsIssueDt": "2026-05-01",
  "transportDate": "2026-05-03",
  "receipent": "{{Receipent_Name}}",
  "waybillStatus": "RESPONDED",
  "companyCode": "{{tax_number}}",
  "createdTime": "2026-05-01T09:00:00",
  "documentType": "OUTGOING",
  "waybillType": "10",
  "comment": null,
  "waybillResponseType": "PARTIAL_APPROVE",
  "lastUpdateTime": "2026-05-03T12:00:00",
  "errMsg": null,
  "countryCode": "RO"
}

Response Fields

Root Fields

Field Name	Type	Description
waybillId	String(UUID)	Unique identifier of the waybill in the system
deliveryNo	String	Delivery note number of the waybill
referenceDocument	String	Reference document number (e.g. purchase order number)
uit	String	Unique Identification Token assigned by the ANAF e-Transport system
indexIncarcare	String	Upload index number received from ANAF upon submission
goodsIssueDt	String	Goods issue date
transportDate	String	Transport date
receipent	String	Recipient company name
waybillStatus	String(enum)	Current status of the waybill. Set to RESPONDED after a successful response.
companyCode	String	CIF code of the company that created the waybill
createdTime	String(ISO 8601)	Timestamp when the waybill was created in the system
documentType	String(enum)	Document direction: OUTGOING (sent) or INCOMING (received)
waybillType	String	ANAF e-Transport operation type code
comment	String	Additional comment field (optional, may be null)
waybillResponseType	String(enum)	The response type submitted: APPROVE, PARTIAL_APPROVE, or REJECT
lastUpdateTime	String	Timestamp of the most recent update to the waybill
errMsg	String	Error message field; returns null on successful operations
countryCode	String	Country code the waybill belongs to (e.g. RO)

Parameter Values Reference

waybillResponseType — Values

Value	Description
APPROVE	Full approval — waybill contents accepted in full (ANAF code: 10)
PARTIAL_APPROVE	Partial approval — only part of the waybill contents accepted (ANAF code: 20)
REJECT	Rejection — waybill contents rejected (ANAF code: 30)

waybillStatus — Values

Value	Description
CREATED	Waybill created, not yet submitted
CREDIT_BLOCKED	On hold due to insufficient credit
SENT	Submitted to ANAF, awaiting result
RESPONDED	Recipient has submitted a response
CANCELLED	Waybill has been cancelled
EDITED	Waybill has been edited
RECEIVED	Received
ERROR	An error occurred during processing
SUCCESS	Successfully processed by ANAF
IN_PROGRESS	Processing is ongoing at ANAF
DELIVERY_CONFIRMED	Delivery has been confirmed
DELIVERED	Goods have been delivered
SEIZED	Goods have been seized
FULFILLED	Waybill has been fulfilled
ACCEPTED	Accepted
REJECTED	Rejected by ANAF
NOT_FOUND_AT_ANAF	Could not be found in the ANAF system

documentType — Values

Value	Description
OUTGOING	Outgoing document — waybill created by the company
INCOMING	Incoming document — waybill received from another company

401 - Unauthorized

Trigger: When the JWT token is missing or invalid, or when the user does not belong to the specified company.

{
  "errorMessage": "Authorization failed for this company",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T12:00:00",
  "path": "/waybill/RO/respond"
}

Description: An AuthorizationServiceException is thrown when JWT validation fails or when the user does not have a role assigned to the company matched by the taxNumber parameter. This error also occurs if the r-auth header is missing or the token has expired.

404 - Not Found

Trigger: When no waybill matching the provided uit value exists in the system.

{
  "errorMessage": "No such waybill with uit: {{uit_code}}",
  "errorType": "NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T12:00:00",
  "path": "/waybill/RO/respond"
}

Description: A NotFoundException is thrown when no waybill record is found for the uit value provided in the request body, returning a 404 Not Found response.

500 - Internal Server Error

Trigger: When no active Romanian company is found for the provided taxNumber, or when an unexpected error occurs during ANAF communication.

{
  "errorMessage": "Company not found with tax number: {{tax_number}}",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T12:00:00",
  "path": "/waybill/RO/respond"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs. If no active Romanian company (country=RO, isDeleted=false) is found for the given taxNumber query parameter, a RuntimeException is thrown which also maps to 500.

13. Get Waybill XML Content GET

Purpose of Use: This endpoint returns the original XML content of a waybill that was previously submitted to the Romanian ANAF e-Transport system. The unique identifier (UUID) of the waybill is provided as a path parameter; the system looks up the record in the database, downloads the XML file from AWS S3, and returns the raw content as the response.

The returned XML conforms to the ANAF e-Transport schema (v1 or v2) and is identical to the document submitted to the Romanian tax authority. This endpoint is typically used for archiving, compliance auditing, debugging, and integration with third-party systems. The requesting user must have access rights to the company that owns the waybill; otherwise an authorization error is returned.

Endpoint Information

Property	Value
URL	/waybill/RO/xml/{waybillId}
Method	GET
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — r-auth header (JWT) — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/xml/{{waybill_uuid}}' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' 

Request Parameters

Path parameters

Field Name	Type	Required	Description
waybillId	String(UUID)	Required	The unique identifier of the waybill whose XML content is to be retrieved (UUID format). Sent as a URL path parameter.

Responses

200 - Successful Response

Response type: String(XML)

Successful response. Returns the ANAF e-Transport XML content of the waybill as a raw string. The content is extracted from the compressed XML file stored in AWS S3. The response is identical to the original XML document submitted to ANAF.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<eTransport xmlns="mfp:anaf:dgti:eTransport:declaratie:v1" codDeclarant="{{tax_number}}">
 <notificare codTipOperatiune="10">
  <bunuriTransportate nrCrt="1" denumireMarfa="ProductName" cantitate="100.00" codUnitateMasura="BUC" greutateNeta="50.00" greutateBruta="55.00" valoareLeiFaraTva="1200.00" codTarifar="84713000" codScopOperatiune="301"/>
  <partenerComercial cod="RO12345678" denumire="Example Partner SRL" codTara="RO"/>
  <dateTransport dataTransport="2026-05-03" codTransportator="RO87654321" denumireTransportator="Transport SRL" codTaraTransportator="RO" nrVehicul="B123ABC" codPtf="4010"/>
  <documenteTransport tipDocument="10" dataDocument="2026-05-01"/>
 </notificare>
</eTransport>

401 - Unauthorized

Trigger: When an invalid or expired JWT token is provided, or when the user does not have access rights to the company that owns the waybill.

{
  "errorMessage": "Authorization failed",
  "errorType": "AUTHORIZATION_FAILED",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-03T12:00:00",
  "path": "/waybill/RO/xml/{{waybill_uuid}}"
}

Description: An AuthorizationServiceException is thrown when authentication fails or when the user associated with the JWT token does not have a role in the company that owns the waybill, returning a 401 Unauthorized response. Triggered when the roleService.existsRoleByCompanyIdAndUserId() check inside AuthorizationService.checkIfCompanyUser() fails.

404 - Not Found

Trigger: When no waybill with the given waybillId exists in the database, or when the S3 storage record for that waybill is missing.

{
  "errorMessage": "No such waybill with id: {{waybill_uuid}}",
  "errorType": "NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-03T12:00:00",
  "path": "/waybill/RO/xml/{{waybill_uuid}}"
}

Description: A NotFoundException is thrown in two distinct situations, both returning 404 Not Found: (1) No WaybillEntity matching the given UUID exists in the database — error message: No such waybill with id: {id}. (2) The waybill record exists but the corresponding S3 XML storage record (StorageS3Entity) is missing — error message: No such waybill with id: {id} in S3 storage.

500 - Internal Server Error

Trigger: When an unexpected server-side error occurs (e.g. failed S3 file download, database connection failure).

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-03T12:00:00",
  "path": "/waybill/RO/xml/{{waybill_uuid}}"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs. In particular, a RuntimeException is thrown when a network or access error occurs while downloading the XML file from AWS S3, and this handler catches it.

14. Cancel Waybill POST

Purpose of Use: This endpoint is used to cancel a waybill that was previously submitted to the Romanian ANAF e-Transport system and is recorded in the platform. The cancellation is performed using the waybill's UIT (Unique Identification Token) number and the company's CIF (Cod de Identificare Fiscală) number.

The cancellation request is forwarded to the ANAF e-Transport API in XML format. Upon a successful operation, the waybill's status in the system is automatically updated to CANCELLED. Only waybills that have not yet been finalized can be cancelled. The request requires a valid JWT token for authentication, and the user must be associated with the specified company.

Endpoint Information

Property	Value
URL	/waybill/RO/cancel
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — R-Auth header (JWT) — Required

Example Request

curl --location 'https://api-stage.docnova.ai/waybill/RO/cancel?taxNumber={{tax_number}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: */*' \ 
--header 'r-auth: {{jwt_token}}' \ 
--data '{ 
  "cif": "{{tax_number}}", 
  "uit": "{{uit_code}}" 
}'

Request Parameters

Query parameters

Field Name	Type	Required	Description
taxNumber	String	Required	The Romanian tax identification number (CUI/CIF) of the company. Sent as a query parameter. Used to locate the registered company in the system.

Request body

Field Name	Type	Required	Description
cif	String	Required	The Cod de Identificare Fiscală (CIF) of the company to which the waybill being cancelled belongs. Sent in the request body; used in the cancellation XML forwarded to ANAF.
uit	String	Required	The Unique Identification Token assigned by ANAF for the waybill to be cancelled. Used to locate the registered waybill record in the system.

Responses

200 - Successful Response

Response type: RomaniaWaybillDto

Cancellation is successful. Returns the RomaniaWaybillDto object with the current waybill information and CANCELLED status.

{
  "waybillId": "{{waybill_uuid}}",
  "deliveryNo": "DEL-2026-00123",
  "referenceDocument": "REF-2026-00456",
  "uit": "{{uit_code}}",
  "indexIncarcare": "5002567891",
  "goodsIssueDt": "2026-05-01",
  "transportDate": "2026-05-03",
  "receipent": "{{Receipent_Name}}",
  "waybillStatus": "CANCELLED",
  "companyCode": "RO26054330",
  "createdTime": "2026-05-01T10:30:00",
  "documentType": "OUTGOING",
  "waybillType": "10",
  "comment": null,
  "waybillResponseType": null,
  "lastUpdateTime": "2026-05-03T14:00:00",
  "errMsg": null,
  "countryCode": "RO"
}

Response Fields

Root Fields

Field Name	Type	Description
waybillId	String(UUID)	Unique identifier of the waybill in the system
deliveryNo	String	Delivery document number
referenceDocument	String	Reference document number
uit	String	Unique Identification Token assigned by ANAF for the waybill
indexIncarcare	String	Upload index number in the ANAF e-Transport system
goodsIssueDt	String	Goods issue date
transportDate	String	Transport date
receipent	String	Name or title of the recipient party
waybillStatus	String(enum)	Current status of the waybill. Updated to CANCELLED after the cancellation operation.
companyCode	String	Code of the company that created the waybill
createdTime	String(ISO 8601)	Timestamp when the waybill was created
documentType	String(enum)	Document direction: incoming (INCOMING) or outgoing (OUTGOING)
waybillType	String	ANAF e-Transport waybill type code
comment	String	Comment or note associated with the waybill (optional)
waybillResponseType	String(enum)	Response type given to the waybill. Returns null for cancellation operations.
lastUpdateTime	String	Timestamp of the last update to the waybill
errMsg	String	Error message returned by ANAF. Returns null for successful operations.
countryCode	String	Country code of the waybill (ISO 3166-1 alpha-2). `RO` for Romania.

Parameter Values Reference

waybillStatus — Values

Value	Description
CREATED	Created — Waybill saved to the system, not yet submitted to ANAF
CREDIT_BLOCKED	Credit Blocked — Process halted due to insufficient credit
SENT	Sent — Successfully forwarded to ANAF
RESPONDED	Responded — A response has been submitted to the waybill
CANCELLED	Cancelled — Waybill has been cancelled in the ANAF system
EDITED	Edited — Waybill has been updated and resubmitted
RECEIVED	Received — Received by the counterparty
ERROR	Error — An error occurred during processing
SUCCESS	Success — Operation approved by ANAF
IN_PROGRESS	In Progress — Still being processed by ANAF
DELIVERY_CONFIRMED	Delivery Confirmed — Delivery has been confirmed
DELIVERED	Delivered — Goods have been delivered
SEIZED	Seized — Goods have been seized
FULFILLED	Fulfilled — Process completed
ACCEPTED	Accepted — Accepted by ANAF
REJECTED	Rejected — Rejected by ANAF
NOT_FOUND_AT_ANAF	Not Found at ANAF — No record found in the ANAF system

documentType — Values

Value	Description
INCOMING	Incoming — A waybill received from another company
OUTGOING	Outgoing — A waybill issued by your own company

waybillResponseType — Values

Value	Description
APPROVE	Approve (code: 10) — Waybill fully approved
PARTIAL_APPROVE	Partial Approve (code: 20) — Waybill partially approved
REJECT	Reject (code: 30) — Waybill rejected

401 - Unauthorized

Trigger: When the JWT token is missing or invalid, or when the user does not have access rights to the specified company.

{
  "errorMessage": "Authorization failed",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T14:00:00",
  "path": "/waybill/RO/cancel"
}

Description: Thrown in two scenarios: (1) If no valid JWT token is present in the request header, the Spring Security filter returns 401. (2) Even with a valid token, if the user does not have a role associated with the company identified by taxNumber, AuthorizationService.checkIfCompanyUser() throws AuthorizationServiceException, which the RestExceptionHandler maps to 401 UNAUTHORIZED.

404 - Not Found

Trigger: When no waybill matching the uit value sent in the request body is found in the system.

{
  "errorMessage": "No such waybill with uit: {{uit_code}}",
  "errorType": "NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T14:00:00",
  "path": "/waybill/RO/cancel"
}

Description: The getByUit() method, called from within uploadWaybillStatus(), throws a NotFoundException if no WaybillEntity with the given UIT number exists. The RestExceptionHandler maps this exception to 404 NOT_FOUND.

500 - Internal Server Error

Trigger: When no active, non-deleted, Romania-registered company matching the taxNumber query parameter is found in the system.

{
  "errorMessage": "Company not found with tax number: {{tax_number}}",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T14:00:00",
  "path": "/waybill/RO/cancel"
}

Description: A RuntimeException is thrown when the companyRepository.findByTaxNumberAndCountryAndIsDeletedFalse(taxNumber, Country.RO) query returns no result. The RestExceptionHandler maps this exception to 500 INTERNAL_SERVER_ERROR.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "details": null,
  "validationErrors": null,
  "timestamp": "2026-05-03T14:00:00",
  "path": "/waybill/RO/cancel"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs.

15. Download descarcare POST

Purpose of Use: This endpoint is used to download invoices registered in the Romanian e-invoicing system (ANAF e-Factura) as a ZIP archive. The id field in the request body represents the unique download identifier (id_descarcare) of the invoice in the ANAF system. The cif parameter specifies which company's authorization is used for the download.

The endpoint follows two different download paths based on the value of the fromPortal field: (1) When fromPortal is sent as "X", the system first searches for the invoice record in the Docnova database using the cif and id combination, then returns the corresponding ZIP file from the internal S3 storage if found. This path is primarily used by Docnova Portal users. (2) When fromPortal carries any value other than "X" or is null, the system directly calls ANAF's descarcare endpoint using the company's Romania OAuth access token and retrieves the ZIP file in real time from ANAF. This path is used by ERP systems and external integrations.

Endpoint Information

Property	Value
URL	/invoice/RO/download-descarcare
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	JWT token via R-Auth header — Required
Response Type	application/octet-stream (Binary ZIP File)

Example Request

curl -X POST "https://api-stage.docnova.ai/invoice/RO/download-descarcare" \ 
-H "accept: */*" \ 
-H "R-Auth: {{jwt_token}}" \ 
-H "Content-Type: application/json" \ 
-d '{ 
  "cif": "{{tax_number}}", 
  "fromPortal": "true", 
  "id": "{{anaf_invoice_id}}" 
}' 

Request Parameters

Request body

Field Name	Type	Required	Description
id	String	Required	The unique download identifier (`id_descarcare`) of the invoice in the ANAF e-Factura system. This is the numeric identifier returned by ANAF after a successful invoice submission.
cif	String	Required	The tax identification number (CUI/CIF) of the Romanian company authorized to perform the download. The system uses this value to locate the company's Romania OAuth token or its database record.
fromPortal	String	Optional	Routing flag that determines the download path. When `"X"` is sent, the invoice is retrieved from Docnova's internal S3 storage. For all other values (including null), the invoice is fetched directly from the ANAF API.

fromPortal = "X": Portal path (S3) — Invoice is searched in the Docnova database by cif + id combination.
fromPortal = any other value or null: Direct ANAF API download path — The company's Romania OAuth token is automatically resolved by cif. Examples: "true", "false", "1", empty string.

Parameter Values Reference

fromPortal — Values

Value	Description
X	Docnova Portal path: The invoice is searched in the Docnova database by the company's `cif` and `id`. If a matching record is found, the ZIP file is returned from the internal S3 storage.
null or any other value	ANAF Direct Download path: The company's Romania OAuth access token is resolved by `cif` and ANAF's `descarcare` endpoint is called to retrieve the ZIP file in real time. Examples: `"true"`, `"false"`, `"1"`, empty string.

Responses

200 - Successful Response

Response type: byte[] (Binary ZIP Archive)

On successful completion, a ZIP file containing the invoice's XML documents (and in some cases the digital signature) is returned as a binary stream. Content-Type: application/octet-stream. Invoice files inside the ZIP are in UBL XML format compliant with ANAF's e-Factura standard.

Body: [Binary ZIP archive — application/octet-stream]

Response Fields

Binary Response

Field Name	Type	Description
(binary stream)	byte[]	Binary content returned as a ZIP archive. Contains XML invoice files compliant with ANAF e-Factura standards. The response body can be saved directly as a file or extracted as a ZIP archive.

400 - Bad Request

Trigger: When the ANAF API call fails (on the direct ANAF download path, when the ANAF service returns an error or the connection cannot be established).

{
  "errorMessage": "43042158---404 Not Found: [ANAF descarcare error response]",
  "errorType": null,
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/download-descarcare"
}

Description: On the ANAF direct download path (fromPortal ≠ "X"), when ANAF's descarcare endpoint is unreachable or returns an error, an IllegalStateException is thrown and a 400 Bad Request response is returned. The errorMessage field will be in the format {cif}---{ANAF error message}.

404 - Not Found

Trigger: When no Romania invoice token or invoice record matching the given CIF and ANAF ID combination is found in the system.

{
  "errorMessage": "Token not found for cif: {{tax_number}}",
  "errorType": "TOKEN_NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/download-descarcare"
}

Description: This error is triggered in two different scenarios: (1) ANAF direct download path (fromPortal ≠ "X"): If no Romania OAuth token registered for the given cif value is found in the system, a NotFoundException is thrown and errorType: "TOKEN_NOT_FOUND" is returned. (2) Portal download path (fromPortal = "X"): If no invoice record matching the given cif + id combination is found in the Docnova database, a NotFoundException is thrown.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "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/RO/download-descarcare"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs. S3 storage access errors may also fall into this category.

16. Get Factura Message List Zile POST

Purpose of Use: This endpoint retrieves e-invoice messages (sent and/or received invoices) for a specific time range from the Romanian Tax Authority (ANAF) system, automatically handling pagination and returning all results as a single merged response.

The call is authenticated using the company's ANAF token and API key. The zile parameter controls how many days back to retrieve messages, while the filtru parameter specifies whether to list only sent invoices (E), only received invoices (P), or all messages (null). When multiple pages exist, the service automatically collects all pages and returns them as a single merged mesaje array. This endpoint is specifically designed for ERP systems to periodically synchronize invoice statuses with ANAF.

Endpoint Information

Property	Value
URL	/invoice/RO/factura-message-list
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	R-Auth header (JWT Bearer Token) + query param: apiKey

Example Request

curl -X POST 'https://api-stage.docnova.ai/invoice/RO/factura-message-list?apiKey={{your_api_key}}' \ 
-H 'accept: */*' \ 
-H 'R-Auth: {{jwt_token}}' \ 
-H 'Content-Type: application/json' \ 
-d '{ 
  "filtru": null, 
  "zile": "30" 
}' 

Request Parameters

Query parameters

Field Name	Type	Required	Description
apiKey	String	Required	The company's Docnova API key. Only COMPANY type keys are accepted. Sent as a query parameter.

Request body

Field Name	Type	Required	Description
zile	String	Optional	Specifies how many days back to retrieve ANAF messages. If not provided or left empty, defaults to `'1'`. Example: `'30'` fetches messages from the last 30 days.
filtru	String(enum)	Optional	Message type filter for ANAF retrieval. E returns only sent invoices, P returns only received invoices, `null` returns all messages.

The apiKey query parameter must be of COMPANY type; USER or other types return a 400 error.
When zile is not provided or is an empty string, the service automatically uses '1' day.
If filtru is sent as null, ANAF returns all message types (sent + received).

Parameter Values Reference

filtru — Values

Value	Description
E	Lists only sent (emise) invoices
P	Lists only received (primite) invoices
null	Lists all messages (sent + received)

Responses

200 - Successful Response

Response type: String(JSON)

Successful response. All ANAF pages are merged and returned as a single mesaje array. If ANAF reports an error, the eroare field will be populated but the HTTP status code remains 200.

{
  "mesaje": [
    {
      "id": 123456789,
      "detalii": "Factura cu id_incarcare=123456789 emisa de cif_emitent={{tax_number}} pentru cif_beneficiar={{tax_number}}",
      "tip": "FACTURA TRIMISA",
      "data_creare": "202501151200"
    },
    {
      "id": 987654321,
      "detalii": "Factura cu id_incarcare=987654321 emisa de cif_emitent={{tax_number}} pentru cif_beneficiar={{tax_number}}",
      "tip": "FACTURA PRIMITA",
      "data_creare": "202501141030"
    }
  ],
  "numar_total_inregistrari": 2,
  "numar_total_pagini": 1,
  "titlu": "Lista mesaje din ultimele 30 de zile"
}

Response Fields

Root Fields

Field Name	Type	Description
mesaje	Array<Object>	Merged list of invoice messages collected from all ANAF pages
numar_total_inregistrari	Number	Total number of message records for the specified filter and time range
numar_total_pagini	Number	Total number of pages available on ANAF (all are automatically fetched by the service)
titlu	String	Descriptive title text returned by ANAF
eroare	String	Error message originating from ANAF. If this field is populated, no invoice data was returned; however the HTTP status code may still be 200.

Message Object Fields (`mesaje[]`)

Field Name	Type	Description
mesaje[].id	Number	Unique identifier of the invoice in the ANAF system (used for download operations)
mesaje[].detalii	String	Description text for the invoice; contains the tax numbers of the sender and recipient
mesaje[].tip	String(enum)	Message type: FACTURA TRIMISA (sent), FACTURA PRIMITA (received), EROARE FACTURA (errored invoice)
mesaje[].data_creare	String	Date and time the message was created in the ANAF system (format: yyyyMMddHHmm)

mesaje[].tip — Values

Value	Description
FACTURA TRIMISA	Invoice successfully sent by the company
FACTURA PRIMITA	Invoice received by the company
EROARE FACTURA	Invoice rejected or containing an error reported by ANAF
MESAJ	General informational message from the ANAF system

400 - Bad Request

Trigger: When the apiKey query parameter cannot be found, the API key is inactive/deleted/expired, a non-COMPANY type key is used, or an unexpected exception occurs during the ANAF service call.

{
  "errorMessage": "API key not found!",
  "errorType": "BAD_REQUEST",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/factura-message-list"
}

Description: The validateApiKey() method throws IllegalStateException in three cases: (1) No record matching the apiKey parameter is found in the database or cache → API key not found!; (2) The key is inactive, deleted, or its expiry date has passed → Provided API key is out of use!; (3) The key type is not COMPANY → Only company type api keys are allowed!. Any exception occurring during the HTTP call to ANAF is also caught and re-thrown as IllegalStateException, resulting in the same 400 response. All these cases are handled by RestExceptionHandler as 400 BAD_REQUEST.

401 - Unauthorized

Trigger: When the R-Auth header is missing, expired, or contains an invalid JWT token; or when the token owner is not a member of the company associated with the API key.

{
  "errorMessage": "Authorization failed",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/factura-message-list"
}

Description: Thrown in two distinct scenarios: (1) Spring Security cannot validate the JWT token in the R-Auth header, returning 401. (2) AuthorizationService.checkIfCompanyUser() verifies that the user ID from the JWT is registered under the company linked to the API key; if not, an AuthorizationServiceException is thrown and 401 is returned.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "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/RO/factura-message-list"
}

Description: Returns a 500 Internal Server Error when an uncaught unexpected error occurs on the server side.

17. Invoice File Status Query GET

Purpose of Use: This endpoint is designed for use by ERP systems to query the current processing status of an e-invoice file previously submitted to the Romanian Tax Authority, ANAF (Agenția Națională de Administrare Fiscală). The invoice submitted via the /invoice/RO/upload endpoint is tracked using the incarcareId (upload tracking identifier) returned at submission time.

ANAF processes invoices asynchronously rather than in real time. Therefore, after uploading an invoice, this endpoint should be polled periodically to track its result. The returned ANAF XML response indicates one of four states: ok (accepted), in prelucrare (being processed), nok (contains errors), or XML cu erori nepreluat de sistem (XML not received by the system). In error cases, the response body contains the XML with detailed error information extracted from ANAF's ZIP archive.

Endpoint Information

Property	Value
URL	/invoice/RO/file-status
Method	GET
Content-Type	Not Required
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — R-Auth header + API key (query parameter)

Example Request

curl -X GET 'https://api-stage.docnova.ai/invoice/RO/file-status?apiKey={{your_api_key}}&incarcareId=1234567890' \ 
-H 'accept: */*' \ 
-H 'R-Auth: {{jwt_token}}' 

Request Parameters

Query parameters

Field Name	Type	Required	Description
apiKey	String	Required	Company-specific API key. Only active, non-expired API keys of type COMPANY are accepted.
incarcareId	String	Required	The upload tracking ID returned by ANAF when the invoice was submitted via the `/invoice/RO/upload` endpoint. Romanian: încărcare means upload.

Responses

200 - Successful Response

Response type: FileStatusResponse

Returns the raw XML response received from ANAF as a string. The XML structure varies depending on the invoice status. For ok or in prelucrare statuses, the raw ANAF XML is returned as-is. For nok or XML cu erori nepreluat de sistem statuses, the error detail XML extracted from ANAF's ZIP archive is returned.

{
  "anafResponse": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><header dateResponse=\"20260506120000\" ExecutionStatus=\"0\" index_incarcare=\"1234567890\"><stare>ok</stare><index_incarcare>1234567890</index_incarcare></header>"
}

Response Fields

Root Fields

Field Name	Type	Description
anafResponse	String(XML)	Raw XML response text received from the ANAF system. Contains a `header` element with `stare` (status) and `index_incarcare` (upload ID) fields.

ANAF XML Structure Inside `anafResponse`

Field Name	Type	Description
header.stare	String(enum)	Invoice processing status. Possible values: `ok`, `in prelucrare`, `nok`, `XML cu erori nepreluat de sistem`.
header.index_incarcare	String	ANAF upload identifier assigned at submission time. Matches the `incarcareId` query parameter.
header.dateResponse	String	ANAF response date and time. Format: yyyyMMddHHmmss.
header.ExecutionStatus	String	ANAF execution status code. `0` indicates successful processing.
header.id_descarcare	String	Present only when `stare` is `nok`. Download identifier used internally to retrieve the ANAF error ZIP archive.

Parameter Values Reference

header.stare — Values

Value	Description
ok	Invoice was successfully processed and accepted by ANAF
in prelucrare	Invoice is queued for processing and not yet finalized
nok	Invoice was processed but contains validation errors; error detail XML is returned
XML cu erori nepreluat de sistem	The submitted XML was not received by the ANAF system; detailed error XML is appended to the response

400 - Bad Request

Trigger: When an invalid, inactive, expired, or non-COMPANY type API key is provided.

{
  "errorMessage": "API key not found!",
  "errorType": null,
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-06T12:00:00",
  "path": "/invoice/RO/file-status"
}

Description: An IllegalStateException is thrown when API key validation fails, returning a 400 Bad Request. The errorType field is null in this case. Three possible messages: (1) API key not found! — the apiKey value does not match any registered key; (2) Provided API key is out of use! — the key is inactive, deleted, or expired; (3) Only company type api keys are allowed! — the key is not of type COMPANY.

401 - Unauthorized

Trigger: When the user identified by the R-Auth token is not associated with the company that owns the API key.

{
  "errorMessage": "User is not authorized for this operation",
  "errorType": "AUTHORIZATION_FAILED",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-06T12:00:00",
  "path": "/invoice/RO/file-status"
}

Description: An AuthorizationServiceException is thrown when the user identity in the JWT token is not associated with the company that owns the provided API key. Returns a 401 Unauthorized response. Ensure that the API key and the R-Auth token both belong to the same company.

404 - Not Found

Trigger: When the Romania ANAF OAuth access token has not been configured for the company associated with the API key.

{
  "errorMessage": "Token not found for this company id: {{company_uuid}}",
  "errorType": "TOKEN_NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-06T12:00:00",
  "path": "/invoice/RO/file-status"
}

Description: A NotFoundException is thrown when no ANAF API access token (Romania OAuth integration) has been configured for the company. Returns a 404 Not Found response. To resolve this error, the company must complete its Romania e-invoice integration setup through the portal.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "errorMessage": "An unexpected error occurred",
  "errorType": "RUNTIME_ERROR",
  "errorTitle": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-05-06T12:00:00",
  "path": "/invoice/RO/file-status"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs.

18. Invoice Validation POST

Purpose of Use: This endpoint validates UBL XML invoice or credit note documents against the ANAF (Agentia Nationala de Administrare Fiscala) system in compliance with Romanian e-invoice standards. The request body contains a Base64-encoded XML document which the system automatically decodes and forwards to the ANAF validare service.

The company identity can be provided in two ways: via a direct companyId UUID value or through a portal-defined apiKey. The system uses either value to resolve the company's ANAF access token and route the validation request accordingly. The invoice standard (FACT1 for invoices, FCN for credit notes) is automatically detected from the XML content. The ANAF response includes the validation state (stare), a processing trace identifier (trace_id), and any validation error messages (Messages) when applicable.

Endpoint Information

Property	Value
URL	/invoice/RO/validare
Method	POST
Content-Type	application/json
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Required — R-Auth header (JWT Token)

Example Request

curl --location 'https://api-stage.docnova.ai/invoice/RO/validare' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: */*' \ 
--header 'R-Auth: {{jwt_token}}' \ 
--data '{ 
  "apiKey": "{{your_api_key}}", 
  "xmlData": "{{base64_encoded_xml}}" 
}' 

Request Parameters

Request body

Field Name	Type	Required	Description
xmlData	String	Required	Base64-encoded UBL XML invoice or credit note content. The system automatically decodes this value before forwarding it to ANAF.
apiKey	String	Conditional*	Portal-registered API key used to resolve the company's ANAF access token. Required if `companyId` is not provided.
companyId	String(UUID)	Conditional*	Unique company identifier (UUID) used to resolve the company's ANAF access token. Required if `apiKey` is not provided.

At least one of apiKey or companyId must be provided. Both can be sent simultaneously; in that case, companyId takes precedence.
If xmlData is null or blank, the Base64 decode step is skipped and the empty content is forwarded to ANAF, which may result in a validation failure.

Responses

200 - Successful Response

Response type: ValidareResponse

ANAF validation completed. The stare field indicates the validation outcome. When validation fails, stare is NOK and the Messages array contains the error details.

{
  "stare": "ok",
  "trace_id": "3004565203",
  "Messages": null
}

Response Fields

Root Fields

Field Name	Type	Description
stare	String	The ANAF validation result status. Returns `ok` when validation passes, `NOK` when it fails.
trace_id	String	The ANAF system processing trace identifier. Used when contacting support for error analysis.
Messages	Array<MessageObj>	List of validation error or warning messages detected by ANAF. Returns `null` when validation is successful.

Message Object (`Messages[]`)

Field Name	Type	Description
Messages[].message	String	The text of the validation error or warning message generated by ANAF.

Parameter Values Reference

stare — Values

Value	Description
ok	The XML document passed all ANAF validation rules; the invoice is valid.
NOK	The XML document failed one or more validation rules. Error details are included in the `Messages` array.

400 - Bad Request

Trigger: When communication with the ANAF external service fails or the XML format is rejected by ANAF.

{
  "errorMessage": "ANAF service error: <ANAF error description>",
  "errorType": "BAD_REQUEST",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/validare"
}

Description: An IllegalStateException is thrown by RomaniaInvoiceRestService when an error occurs during the HTTP call to the ANAF validare service. The errorMessage field in the response body contains the original error message returned by ANAF.

401 - Unauthorized

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

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/validare"
}

Description: The Spring Security JWT filter throws an AuthorizationServiceException when the token in the R-Auth header is found to be invalid or expired, returning a 401 Unauthorized response.

404 - Not Found

Trigger: When no registered ANAF access token is found in the system for the provided apiKey or companyId.

{
  "errorMessage": "Token not found for companyId: {{company_uuid}}",
  "errorType": "TOKEN_NOT_FOUND",
  "errorTitle": "NOT_FOUND",
  "status": 404,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/validare"
}

Description: A NotFoundException is thrown by TokenService when no active Romania ANAF access token can be matched for the given companyId or apiKey. The company must have completed its ANAF OAuth connection beforehand.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "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/RO/validare"
}

Description: Returns a 500 Internal Server Error when an unexpected RuntimeException or system-level error occurs on the server side.

19. XML to PDF Conversion POST

Purpose of Use: This endpoint accepts a Base64-encoded UBL XML invoice or credit note compliant with the Romanian e-Invoice standard (CIUS-RO) and converts it to PDF format via ANAF's e-Factura API, returning the result as binary data. It is designed for ERP systems and integration applications that need to render invoice documents in a human-readable PDF format.

Authentication works in two layers: first, the user identity is verified via the JWT token in the R-Auth header, then company authorization is performed using the apiKey query parameter. The XML content must be Base64-encoded; the service automatically detects the processing standard — XMLs containing CreditNote are handled using the FCN standard, while all others use FACT1. The successful response is not JSON but raw binary PDF data.

Endpoint Information

Property	Value
URL	/invoice/RO/xml-to-pdf
Method	POST
Content-Type	application/json
Response Type	application/pdf (Binary)
Base URL	Stage Environment URLhttps://app-stage.docnova.ai/ Production Environment URLhttps://api.docnova.ai/
Authorization	Bearer token — R-Auth header + API key (query param)

Example Request

curl --location --request POST 'https://api-stage.docnova.ai/invoice/RO/xml-to-pdf?apiKey={{your_api_key}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Accept: */*' \ 
--header 'R-Auth: {{jwt_token}}' \ 
--data '{ 
  "businessType": "B2B", 
  "xmlData": "{{base64_encoded_ubl_xml}}" 
}' 

Request Parameters

Query parameters

Field Name	Type	Required	Description
apiKey	String	Required	Company-scoped API key. Passed as a URL query parameter. Used to identify the company and verify user-to-company authorization.

Request body

Field Name	Type	Required	Description
xmlData	String	Required	Base64-encoded UBL XML invoice data. Must conform to the Romanian CIUS-RO standard. If the decoded XML contains `CreditNote`, the FCN standard is applied; otherwise FACT1 is used.
businessType	String(enum)	Optional	Business model type (B2B, B2C, B2G). Not actively used in PDF conversion logic for this endpoint; may be included in the request body but has no functional effect here.

The apiKey must be registered in the system, active, not deleted, not expired, and of type COMPANY.
The xmlData field must be Base64-encoded; sending raw XML will cause a decode error.
XML containing CreditNote is processed under the FCN standard (credit note cancellation); all others use FACT1 (standard invoice).
The businessType field is not processed by this endpoint; it is reserved for future use.

Parameter Values Reference

businessType — Values

Value	Description
B2B	Business to Business — commercial transaction between companies
B2C	Business to Consumer — transaction between a company and an individual customer
B2G	Business to Government — transaction between a company and a public institution

Responses

200 - Successful Response

Response type: byte[] (PDF Binary)

Conversion successful. The response body contains raw binary PDF data — no JSON is returned. The client should treat the response as Content-Type: application/pdf; the data can be written to a file or rendered directly in a browser.

Body: {{binary_pdf_content}}

Response Fields

Binary PDF Response

Field Name	Type	Description
(response body)	byte[]	Raw binary PDF data. Not a JSON object — the entire response body is the byte array of the PDF file. In Java, receive as `byte[]`; in JavaScript, receive as Blob or ArrayBuffer.

400 - Bad Request

Trigger: When the apiKey query parameter is absent from the request.

{
  "errorMessage": "Required request parameter 'apiKey' for method parameter type String is not present",
  "errorType": "BAD_REQUEST",
  "errorTitle": "BAD_REQUEST",
  "status": 400,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/xml-to-pdf"
}

Description: If the apiKey query parameter is not present in the URL, Spring MVC returns 400 Bad Request before reaching the service layer.

401 - Unauthorized

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

{
  "errorMessage": "Not authorized for this action",
  "errorType": "NOT_AUTHORITY",
  "errorTitle": "UNAUTHORIZED",
  "status": 401,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/xml-to-pdf"
}

Description: If the JWT token in the R-Auth header is invalid, expired, or missing, Spring Security returns 401 Unauthorized before the controller method is entered. This error occurs at the security filter layer, not in the service code.

422 - Unprocessable Entity

Trigger: When the API key is not found in the database.

{
  "errorMessage": "PDF convert error: API key not found!",
  "errorType": "PDF_CONVERT_ERROR",
  "errorTitle": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/xml-to-pdf"
}

Description: If the provided apiKey value does not exist in the system, a GeneralException is thrown and a 422 Unprocessable Entity is returned. The errorMessage always begins with the PDF convert error: prefix.

422 - Unprocessable Entity — API Key State

Trigger: When the API key is inactive, deleted, expired, or not of COMPANY type.

{
  "errorMessage": "PDF convert error: Provided API key is out of use!",
  "errorType": "PDF_CONVERT_ERROR",
  "errorTitle": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/xml-to-pdf"
}

Description: If the API key exists in the system but is inactive (active=false), deleted (deleted=true), past its expiration date, or is not of COMPANY type (only COMPANY type is permitted), a 422 is returned. Possible errorMessage values: PDF convert error: Provided API key is out of use! or PDF convert error: Only company type api keys are allowed!

422 - Unprocessable Entity — Company Access

Trigger: When the authenticated user does not belong to the company associated with the API key.

{
  "errorMessage": "PDF convert error: Not authorized for this action",
  "errorType": "PDF_CONVERT_ERROR",
  "errorTitle": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/xml-to-pdf"
}

Description: If the user identified by the JWT token is not a member of the company associated with the apiKey, an AuthorizationServiceException is thrown. This exception is caught inside the service-level try-catch and re-thrown as GeneralException(PDF_CONVERT_ERROR + message), resulting in a 422 response.

422 - Unprocessable Entity — XML or Conversion

Trigger: When xmlData has invalid Base64 encoding, the XML structure is malformed, or the ANAF PDF conversion service fails.

{
  "errorMessage": "PDF convert error: Invalid Base64 encoding",
  "errorType": "PDF_CONVERT_ERROR",
  "errorTitle": "UNPROCESSABLE_ENTITY",
  "status": 422,
  "errorId": "{{correlation_id}}",
  "timestamp": "2026-01-15T12:00:00",
  "path": "/invoice/RO/xml-to-pdf"
}

Description: If the xmlData field is not valid Base64, the decoded XML does not conform to CIUS-RO, or ANAF's XML-to-PDF conversion API returns an error, this 422 response is produced. The errorMessage contains the PDF convert error: prefix followed by the original error description from the underlying failure.

500 - Internal Server Error

Trigger: When an unexpected server error occurs.

{
  "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/RO/xml-to-pdf"
}

Description: Returns a 500 Internal Server Error when an unexpected server-side error occurs.

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 - Successful Response​

Response Fields​

Root Fields​

Parameter Values Reference​

apiKey — Values​

400 - Bad Request​

400 - Bad Request — API Key Out of Use​

400 - Bad Request — API Key Expired​

400 - Bad Request — User Not Authorized for Company​

401 - Unauthorized​

404 - Not Found​

500 - Internal Server Error​

3. Send Document Async POST​

Endpoint Information​

Example Request​

Request Parameters​

Parameter Values Reference​

invoiceType — Values​

waybillType — Values​

invoiceSource — Values​

businessType — Values​

Responses​

200 - Successful Response​

Response Fields​

Root Fields​

status — Values​

400 - Bad Request​

400 - Bad Request — Missing Document Type​

400 - Bad Request — Missing Document Content​

400 - Bad Request — Invalid API Key​

400 - Bad Request — API Key Company Not Found​

401 - Unauthorized​

401 - Unauthorized — Company Access​

500 - Internal Server Error​

4. Document Status GET​

Endpoint Information​

Example Request​

Request Parameters​

Path parameters​

Responses​

200 - Successful Response​

Response Fields​

Root Fields​

Parameter Values Reference​

status — Values​

direction — Values​

documentType — Values​

waybillType — Values​

source — Values​

404 - Not Found​

500 - Internal Server Error​

5. Search Processing History POST​

Endpoint Information​

Example Request​

Request Parameters​

Query parameters​

Request body​

Responses​

200 - Successful Response​

Response Fields​

Pagination Metadata (Page)​

Document Processing Record Fields (content[])​

Parameter Values Reference​

direction — Values​

status — Values​

documentType — Values​

source — Values​

waybillType — Values​

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 - Successful Response

Response Fields

Root Fields

Parameter Values Reference

apiKey — Values

400 - Bad Request

400 - Bad Request — API Key Out of Use

400 - Bad Request — API Key Expired

400 - Bad Request — User Not Authorized for Company

401 - Unauthorized

404 - Not Found

500 - Internal Server Error

3. Send Document Async POST

Endpoint Information

Example Request

Request Parameters

Parameter Values Reference

invoiceType — Values

waybillType — Values

invoiceSource — Values

businessType — Values

Responses

200 - Successful Response

Response Fields

Root Fields

status — Values

400 - Bad Request

400 - Bad Request — Missing Document Type

400 - Bad Request — Missing Document Content

400 - Bad Request — Invalid API Key

400 - Bad Request — API Key Company Not Found

401 - Unauthorized

401 - Unauthorized — Company Access

500 - Internal Server Error

4. Document Status GET

Endpoint Information

Example Request

Request Parameters

Path parameters

Responses

200 - Successful Response

Response Fields

Root Fields

Parameter Values Reference

status — Values

direction — Values

documentType — Values

waybillType — Values

source — Values

404 - Not Found

500 - Internal Server Error

5. Search Processing History POST

Endpoint Information

Example Request

Request Parameters

Query parameters

Request body

Responses

200 - Successful Response

Response Fields

Pagination Metadata (Page)

Document Processing Record Fields (content[])

Parameter Values Reference

direction — Values

status — Values

documentType — Values

source — Values

waybillType — Values