Poštár

API Documentation

Document Responses

PEPPOL supports multiple levels of document responses. This page explains each level and how to use the API to send them.

Key things to understand before you start

  • There is no strict obligation to explicitly confirm a document. In PEPPOL it is generally accepted that if no rejection is sent within a reasonable time, the document is considered accepted.
  • The lowest-level transmission acknowledgement (AS4) is confirmed automatically by the network infrastructure — no action required.
  • The Message Level Response can be sent either as MLR (BIS 36) or MLS (eDEC MLS 1.0). It is sent automatically when the "autoAcknowledge" option is enabled for a participant and only confirms technical receipt/processing (no business meaning). If the receiver supports both MLR and MLS, MLS is preferred.
  • Invoice Response (IMR) and Order Response are the only response types that carry actual business meaning. Use these when you want to explicitly accept or reject an invoice or order on behalf of the buyer.

1. Transmission Level Response (AS4)

At the lowest level, the PEPPOL AS4 transport protocol sends a synchronous acknowledgement for every message it receives. This is handled automatically by the access point and requires no action from you. It confirms that the bytes were received, not that the document was understood or accepted by the business.

2. Message Level Response – MLR (BIS 36)

MLR (BIS 36) is a PEPPOL ApplicationResponse document (urn:fdc:peppol.eu:poacc:trns:mlr:3). It signals whether the received document was technically valid and could be processed by the receiving system. It does not represent a business decision such as acceptance or rejection of an invoice. Use MLR to confirm or reject a received document at the message/system level.

This API also supports MLS (Message Level Status, urn:peppol:edec:mls:1.0). The same endpoints are used. The system negotiates based on receiver capabilities: if MLS is supported it is sent (preferred), otherwise MLR is sent; if neither is supported, no message-level response is sent.

Endpoints
  • POST /api/documents/{documentId}/mlr/confirm — Sends MLR with code AP (Acknowledged). Marks document as confirmed.
  • POST /api/documents/{documentId}/mlr/reject — Sends MLR with code RE (Rejected). Marks document as rejected.
curl -X POST "https://api.pepposh.eu/api/documents/{documentId}/mlr/confirm" \
  -H "Authorization: Bearer <your-token>"

3. Invoice Message Response – IMR (BIS 63)

IMR (BIS 63) is a PEPPOL ApplicationResponse document (urn:fdc:peppol.eu:poacc:trns:invoice_response:3). It represents a business-level response to an invoice or credit note. Unlike MLR, IMR carries business meaning – it tells the invoice sender whether their invoice is accepted, in review, under query, or rejected. PEPPOL BIS 63 specification ↗

Response Codes
CodeMeaning
ABMessage acknowledgement – received but not yet processed
IPIn process – being processed
UQUnder query – clarification needed
CAAccepted with changes
RERejected
APAccepted
PDPaid
Endpoints
  • POST /api/documents/{documentId}/accept — Convenience: sends IMR with code AP.
  • POST /api/documents/{documentId}/reject — Convenience: sends IMR with code RE.
  • POST /api/documents/{documentId}/send-response — Generic: specify any valid response code.
# Accept an invoice
curl -X POST "https://api.pepposh.eu/api/documents/{documentId}/accept" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"note": "Invoice accepted", "effectiveDate": "2025-01-15"}'

# Reject an invoice
curl -X POST "https://api.pepposh.eu/api/documents/{documentId}/reject" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"note": "Incorrect amount on line 3"}'

# Send a custom response code (e.g. Under Query)
curl -X POST "https://api.pepposh.eu/api/documents/{documentId}/send-response" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"responseCode": "UQ", "note": "Please confirm delivery address"}'

4. Order Response (BIS 28)

OrderResponse (BIS 28, T76) is a PEPPOL OrderResponse document (urn:fdc:peppol.eu:poacc:trns:order_response:3). It is the business-level response to a received order. The same API endpoints are used – the system automatically selects between IMR and OrderResponse based on the document type.

Response Codes
CodeMeaning
APOrder accepted
REOrder rejected
# Accept an order
curl -X POST "https://api.pepposh.eu/api/documents/{documentId}/accept" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"note": "Order confirmed"}'

Receiving responses for documents you sent

When the recipient of a document you sent responds with MLR/MLS, IMR or OrderResponse, the status of your original document is automatically updated. Accepted responses set the status to mlr-accepted; rejections set it to mlr-rejected. You can subscribe to the invoice.response and order.response webhook events to be notified.

  • invoice.response — Fired when an Invoice Message Response (IMR) is received.
  • order.response — Fired when an Order Response is received.