API Overview

The Invostaq API lets you send e-invoices through the Peppol network and receive real-time delivery status. This page covers the full lifecycle, endpoint reference, and conventions before you dive into individual guides.

Invoice lifecycle

Your system          Invostaq                   Peppol network
     │                   │                           │
     │  1. Lookup         │                           │
     │ ─────────────────► │                           │
     │  isRegistered: true│                           │
     │ ◄───────────────── │                           │
     │                    │                           │
     │  2. Send invoice   │                           │
     │ ─────────────────► │  Validate & build UBL     │
     │                    │ ──────────────────────────►│
     │                    │                           │  Deliver to recipient
     │  3. Response:       │                           │ ──────────────────────►
     │     Processing     │                           │
     │ ◄───────────────── │                           │
     │                    │                           │
     │  4. Webhook:        │  Delivery receipt         │
     │     Delivered      │ ◄──────────────────────── │
     │ ◄───────────────── │                           │

Look up the recipient — GET /api/participants/lookup confirms they are reachable on Peppol and returns the accessPointRef you need to route the invoice
Send the invoice — POST /api/invoices/send validates the data, builds a signed UBL 2.1 XML document, and submits it to the Peppol Access Point
Immediate response — you receive status: "success" and an invoiceId; the network status starts as Processing
Webhook delivery — when the recipient's Access Point acknowledges the invoice, Invostaq calls your webhook endpoint with Delivered or Failed

Base URLs

Environment	Base URL
Sandbox	`https://api.sandbox.invostaq.com/api`
Production	`https://api.invostaq.com/api`

Sandbox keys start with sk_test_ and route invoices to the Peppol TEST network. No real invoices are delivered to recipients.

Public API endpoints

All authenticated with x-api-key header.

Method	Path	Description
`GET`	`/participants/lookup`	Check if a recipient is registered on Peppol and get their routing reference
`POST`	`/invoices/send`	Send an invoice through the Peppol network
`GET`	`/invoices/{id}/artefacts`	List delivery artefacts (receipts, validation reports) for a sent invoice
`GET`	`/invoices/{id}/artefacts/{artefactId}`	Download the raw content of a delivery artefact

Authentication

Endpoint	Header
All public API endpoints	`x-api-key: sk_test_...`
Webhook callbacks	`X-Webhook-Secret: ...` (validated on your server)

Generate keys from Settings → API Keys in the Invostaq dashboard. See Authentication for key rotation, IP allowlisting, and rate limits.

Request format

Content-Type: application/json
Dates: YYYY-MM-DD (e.g. 2024-06-15)
Money: decimal numbers (1050.00, not "1050.00")
Participant IDs: ISO 6523 format — {scheme}:{identifier} (e.g. 0196:971501234567)
Tax rates: percentage values — 21.0 means 21%, not 0.21

Response format

Success:

{
  "invoiceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "transactionId": "txn_abc123def456",
  "status": "success",
  "networkStatus": "Processing",
  "idempotencyKeyEcho": "inv-2024-001-attempt-1",
  "provider": "InvoStaq"
}

Error — RFC 7807 Problem Details:

{
  "type": "https://invostaq.com/errors/declared-totals-mismatch",
  "title": "Declared totals do not reconcile",
  "detail": "grandTotal (1000.00) must equal subtotal (800.00) + taxAmount (210.00).",
  "status": 400
}

Match on type for programmatic error handling. See Errors for every error code.

Idempotency

Include an Idempotency-Key header on every send request:

curl -X POST https://api.sandbox.invostaq.com/api/invoices/send \
  -H "x-api-key: sk_test_..." \
  -H "Idempotency-Key: inv-2024-001-attempt-1" \
  ...

If the request times out or you are unsure whether it succeeded, retry with the same key. The API returns the original result without resubmitting to Peppol.

Response headers confirm whether the result is fresh or replayed:

Idempotency-Key: inv-2024-001-attempt-1
Idempotency-Replay: false   ← "true" if this is a replayed result

Keys can be any string up to 128 characters. Use invoice numbers, UUIDs, or any value unique to this submission attempt.

Peppol participant ID format

Peppol uses ISO 6523 identifiers in the form {scheme}:{identifier}:

Scheme	Country / Standard	Example
`0196`	UAE (TRN)	`0196:971501234567`
`0208`	Belgium (CBE/KBO)	`0208:0453054123`
`0106`	Netherlands (KVK)	`0106:12345678`
`0007`	Sweden (Org number)	`0007:5560000001`
`0088`	International (GLN)	`0088:1234567890123`
`0231`	Saudi Arabia (TIN)	`0231:300000000000003`
`0002`	France (SIREN)	`0002:123456789`

Use GET /api/participants/lookup?participantId={scheme}:{identifier} to verify a recipient is reachable before sending.

Rate limits

	Limit	Scope
All methods	60 requests/min	Per API key

Exceeding the limit returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

What's next

Guide
Getting Started	Send your first invoice end-to-end
Authentication	Key management, sandbox vs. production, rate limits
Errors	Every error type with full JSON examples
Webhooks	Event types, signature verification, retry behavior

Invoice lifecycle​

Base URLs​

Public API endpoints​

Authentication​

Request format​

Response format​

Idempotency​

Peppol participant ID format​

Rate limits​

What's next​