Getting Started

Send your first invoice through the Peppol network in under 5 minutes.

Before you start

• Sign up at invostaq.com to get a tenant
• Generate an API key from Settings → API Keys in the dashboard
  • Sandbox keys start with sk_test_ — invoices route to the Peppol TEST network
  • Production keys start with sk_live_ — invoices route to the live Peppol network

Every request requires the key in an x-api-key header. No OAuth, no tokens.

---

Step 1: Look up the recipient

Before sending an invoice, verify the recipient is registered on the Peppol network.

curl "https://api.sandbox.invostaq.com/api/participants/lookup?participantId=0196:971501234567" \
  -H "x-api-key: sk_test_YOUR_KEY"

{
  "participantId": "0196:971501234567",
  "isRegistered": true,
  "accessPointRef": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "supportedDocTypes": [
    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
  ],
  "provider": "InvoStaq"
}

• isRegistered: true — the recipient can receive Peppol documents
• accessPointRef — copy this UUID; you need it in Step 2
• isRegistered: false — the recipient is not on the Peppol network yet; you cannot send to them via Peppol

---

Step 2: Send the invoice

curl -X POST https://api.sandbox.invostaq.com/api/invoices/send \
  -H "x-api-key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-2024-001-attempt-1" \
  -d '{
    "invoice": {
      "number": "INV-2024-001",
      "issueDate": "2024-06-15",
      "dueDate": "2024-07-15",
      "currency": "EUR",
      "supplier": {
        "name": "Acme Trading NV",
        "taxId": "BE0417497106",
        "address": {
          "line1": "Rue de la Loi 1",
          "city": "Brussels",
          "postalCode": "1000",
          "countryCode": "BE"
        }
      },
      "buyer": {
        "name": "Gulf Imports Co",
        "taxId": "971501234567",
        "address": {
          "line1": "Sheikh Zayed Road",
          "city": "Dubai",
          "countryCode": "AE"
        }
      },
      "lineItems": [
        {
          "description": "Consulting services — June 2024",
          "quantity": 1,
          "unitPrice": 1000.00,
          "taxRate": 21.0
        }
      ],
      "totals": {
        "subtotal": 1000.00,
        "taxAmount": 210.00,
        "grandTotal": 1210.00
      }
    },
    "routing": {
      "senderParticipantId": "0208:0417497106",
      "receiverParticipantId": "0196:971501234567",
      "accessPointRef": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

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

Save the invoiceId — you need it to check delivery status.

The networkStatus starts as Processing and updates to Delivered or Failed once the recipient's Access Point responds.

Idempotency

Include an Idempotency-Key header on every send request. If the request times out or you are unsure whether it succeeded, retry with the same key — the API returns the original result without sending a duplicate to Peppol. Any unique string works: an invoice number, a UUID, or a combination.

Tax rates

Tax rates are percentages. Use 21.0 for 21% VAT — not 0.21.

---

Step 3: Check delivery artefacts

After sending, poll for delivery receipts from the recipient's Access Point.

curl "https://api.sandbox.invostaq.com/api/invoices/f47ac10b-58cc-4372-a567-0e02b2c3d479/artefacts" \
  -H "x-api-key: sk_test_YOUR_KEY"

{
  "invoiceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "items": [
    {
      "artefactId": "receipt-001",
      "type": "RECEIPT",
      "name": "AS4 receipt",
      "contentType": "application/xml",
      "createdAt": "2024-06-15T10:32:00Z"
    }
  ],
  "provider": "InvoStaq"
}

Download the raw content of any artefact:

curl "https://api.sandbox.invostaq.com/api/invoices/f47ac10b-58cc-4372-a567-0e02b2c3d479/artefacts/receipt-001" \
  -H "x-api-key: sk_test_YOUR_KEY" \
  --output receipt.xml

---

Step 4: Receive delivery events via webhooks

Rather than polling, register a webhook to receive real-time delivery status updates.

Go to Settings → Webhooks in the dashboard and add your endpoint URL. Invostaq will POST a signed JSON payload when delivery status changes.

Invoice delivered:

{
  "eventType": "transaction.sent",
  "transactionId": "txn_abc123def456",
  "invoiceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "Delivered"
}

Delivery failed:

{
  "eventType": "transaction.failed",
  "transactionId": "txn_abc123def456",
  "invoiceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "Failed",
  "reason": "Recipient Access Point unreachable"
}

Always respond with 200 OK. See the Webhooks guide for signature verification and the full event reference.

---

Pricing

Invostaq is priced per invoice sent. Contact us for pricing and volume — we respond within one business day. There are no platform fees or monthly minimums.

---

Common errors

Error code	Cause	Fix
api-key-required	No x-api-key header	Add x-api-key: sk_test_... to every request
invalid-api-key	Key doesn't match any tenant	Check the key in Settings → API Keys
invalid-sender-id	Routing participant ID not in scheme:id format	Use 0208:0417497106, not 0417497106
missing-routing	routing object missing required fields	Include senderParticipantId, receiverParticipantId, accessPointRef
declared-totals-mismatch	Totals don't reconcile	grandTotal = subtotal + taxAmount; subtotal = sum of line extensions
self-invoicing	Sender and receiver are the same	senderParticipantId and receiverParticipantId must be different

---

What's next

Guide	When you need it
Authentication	Key management, sandbox vs. production, rate limits
Errors	Every error type with full JSON examples
Webhooks	Event types, signature verification, retry behavior
API overview	Full invoice lifecycle, all endpoints at a glance