# InvoRoute

> REST API for sending PEPPOL e-invoices. Abstracts PEPPOL complexity (UBL, AS4, SMP lookups) into simple endpoints—send invoices with customer_id, amount, and currency. We handle BIS 3.0 compliance, format conversion, and network delivery.

InvoRoute is a developer-first API for electronic invoicing via the PEPPOL network. You call simple JSON endpoints; we handle PEPPOL BIS Billing 3.0 compliance, UBL 2.1 format conversion, EN 16931 validation, digital signatures, and secure AS4 transport.

Base URLs: Production `https://api.invoroute.com`, Sandbox `https://api-sandbox.invoroute.com`. Rate limits: 100 req/min (sandbox), 1,000 req/min (production). Use `Idempotency-Key` header for safe retries.

## Docs

- [OpenAPI Specification](https://invoroute.com/openapi.json): Complete API schema with all endpoints, request/response models, and examples
- [Interactive Documentation](https://invoroute.com/docs): Scalar UI with code samples in multiple languages and try-it functionality
- [Full Context (llms-ctx.txt)](https://invoroute.com/llms-ctx.txt): Complete inline documentation for LLMs that cannot fetch external URLs

## Authentication

- API keys use Bearer token format: `Authorization: Bearer sk_test_xxx`
- Sandbox keys start with `sk_test_` - use with test participants
- Production keys start with `sk_live_` - sends real invoices on PEPPOL network

## API Reference

- [POST /v1/invoices](https://invoroute.com/docs#tag/Invoices/operation/CreateInvoice): Send an invoice - requires customer_id (PEPPOL identifier), amount (cents), currency (ISO 4217)
- [GET /v1/invoices/{id}/status](https://invoroute.com/docs#tag/Invoices/operation/GetInvoiceStatus): Check delivery status - returns pending, sent, delivered, or failed
- [GET /v1/participants/lookup](https://invoroute.com/docs#tag/Participants/operation/LookupParticipant): Verify customer exists in PEPPOL directory before sending
- [POST /v1/invoices/validate](https://invoroute.com/docs#tag/Invoices/operation/ValidateInvoice): Pre-validate invoice without sending
- [POST /v1/webhooks](https://invoroute.com/docs#tag/Webhooks/operation/RegisterWebhook): Subscribe to delivery events (invoice.delivered, invoice.failed)

## Testing

- [GET /v1/sandbox/participants](https://invoroute.com/docs#tag/Sandbox-Tools/operation/GetSandboxParticipants): List available test participants
- Test participant `9999:test-success` always delivers successfully
- Test participant `9999:test-failure` always fails with participant_not_found
- Test participant `9999:test-slow` delivers after 60 second delay

## PEPPOL Identifiers

- Format: `{scheme}:{identifier}` using ISO 6523 ICD codes
- Sweden: `0007:5567125082` (organization number)
- Norway: `0192:123456789` (organization number)
- Australia: `0151:51824753556` (ABN)
- GLN: `0088:1234567890123` (Global Location Number)
- Full ICD list: https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/

## Standards

- PEPPOL BIS Billing 3.0 (latest)
- UBL 2.1 document format
- EN 16931 European e-invoicing standard
- AS4 transport protocol
- Reference: https://docs.peppol.eu/poacc/billing/3.0/

## Optional

- [GET /v1/invoices](https://invoroute.com/docs#tag/Invoices/operation/ListInvoices): List all invoices with pagination and filtering
- [GET /v1/invoices/{id}](https://invoroute.com/docs#tag/Invoices/operation/GetInvoice): Get full invoice details including line items
- [PATCH /v1/invoices/{id}](https://invoroute.com/docs#tag/Invoices/operation/UpdateInvoice): Update pending invoice before sending
- [DELETE /v1/invoices/{id}](https://invoroute.com/docs#tag/Invoices/operation/CancelInvoice): Cancel pending invoice
- [GET /v1/invoices/{id}/events](https://invoroute.com/docs#tag/Invoices/operation/GetInvoiceEvents): Get invoice event timeline for debugging
- [GET /v1/participants/document-types](https://invoroute.com/docs#tag/Participants/operation/GetDocumentTypes): List supported PEPPOL document types
- [GET /v1/webhooks](https://invoroute.com/docs#tag/Webhooks/operation/ListWebhooks): List registered webhooks
- [GET /v1/webhooks/{id}](https://invoroute.com/docs#tag/Webhooks/operation/GetWebhook): Get webhook details and delivery history
- [DELETE /v1/webhooks/{id}](https://invoroute.com/docs#tag/Webhooks/operation/DeleteWebhook): Remove webhook subscription
- [POST /v1/sandbox/reset](https://invoroute.com/docs#tag/Sandbox-Tools/operation/ResetSandbox): Clear all sandbox test data
- [GET /v1/health](https://invoroute.com/docs#tag/Health/operation/GetHealth): API health check (no auth required)
- [GitHub](https://github.com/invoroute): Open source projects and SDKs