Best Practices for E-Invoice Archive API Integration

API Integration Overview

Integrating archiving into your workflow should be seamless. Our REST API provides everything you need to build robust, automated archiving pipelines.

Authentication

All API requests require authentication using Bearer tokens. Rotate these tokens periodically.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.peppol-archive.eu/v1/documents

Efficient Data Handling

When dealing with thousands of invoices, standard patterns fail.

#### 1. Pagination for Search Don't request 10,000 records at once. Use cursor-based pagination for reliable iteration.

GET /documents?limit=50&cursor=eyJid...

#### 2. Large File Uploads For documents >10MB (e.g., large PDF attachments), use our multipart upload endpoint or presigned URLs to upload directly to storage, bypassing the API gateway bottleneck.

---

Handling Errors Gracefully

Robust integrations expect failure.

Idempotency

To prevent duplicate archives during network timeouts, send an Idempotency-Key header. If you retry the request with the same key, we return the original successful response without creating a duplicate.

Idempotency-Key: 00000000-0000-0000-0000-000000000000

---

Webhook Architecture

Don't poll for status. Use webhooks to be notified when:

1 Archiving is complete: The eIDAS timestamp has been applied.

2 Validation failed: The document was rejected (malformed XML).

Security: Verify the X-Signature header in every webhook to ensure it comes from us.

const signature = req.headers['x-signature'];
const expected = hmac(secret, JSON.stringify(req.body));
if (signature !== expected) throw new Error('Invalid webhook signature');