Taxstar E-Invoice OAuth API
Integrate your software with the Taxstar E-Invoice platform. One API to register applications, manage users and companies, and dispatch legally compliant invoices to the UAE Peppol network — all secured with OAuth 2.0 client credentials.
Base URL
https://integration-einv.taxstar.app/apiAll endpoints are relative to this base. Every resource endpoint requires Authorization: Bearer <access_token>.
Quickstart
Four steps from zero to your first invoice on the Peppol network.
Register an application
Sign in as a developer and call POST /oauth/apps. You receive a client_id and a client_secret (shown once — store it securely). The app starts as PENDING; an admin approves it before tokens are issued.
Get an access token
Exchange your credentials at POST /oauth/token with grant_type=client_credentials. The response gives an access_token (short-lived) and a refresh_token. All resource endpoints need the Bearer access_token.
Create an entity
POST /oauth/entities with your company TRN, address, and contact details. The entity_id returned here is the seller identifier you pass on every invoice.
Send an invoice
POST /oauth/invoices with entity_id, buyer, and line items. Totals are computed automatically. The invoice is validated, converted to XML, and dispatched to the UAE Peppol network in the background.
API overview
All 33 endpoints across 7 resource groups. Click a card to go to the full reference.
Register OAuth apps, obtain client credentials, rotate secrets, and track per-app activity. New apps start as PENDING and require admin approval before tokens can be issued.
POST /oauth/apps — create an appGET /oauth/apps — list your appsPOST /oauth/apps/{id}/regenerate-secret — rotate secretPOST /oauth/apps/{id}/activate|deactivate
Exchange client credentials for a short-lived access token and a refresh token. Use the refresh token to get a new access token without re-supplying credentials.
POST /oauth/token grant_type=client_credentialsPOST /oauth/token grant_type=refresh_token
Inspect the application behind the current access token. Useful for debugging and validating that the right credentials are in use.
GET /oauth/me — return app identity
Create end-users scoped to your application. Users own their own entities and invoices. A user can even create further users, letting you build a hierarchy within one app.
POST /oauth/users — create a userGET /oauth/users — list usersGET /oauth/users/{id} — get a user
Register companies (entities) that will issue invoices on the UAE Peppol network. Each entity holds its TRN, address, and contact details and can be owned by any user of your app.
POST /oauth/entities — create an entityGET /oauth/entities — list entitiesPATCH /oauth/entities/{id} — updateDELETE /oauth/entities/{id} — delete
Create, validate, and dispatch invoices to the UAE Peppol network. Send one invoice or a batch of invoices in a single call. Also list and inspect sent and received invoices.
POST /oauth/invoices — push a single invoicePOST /oauth/invoices/bulk — push multiple at onceGET /oauth/invoices/sent — list sent invoicesGET /oauth/invoices/received — list received invoices
Register HTTPS endpoints and subscribe to invoice lifecycle events. Taxstar signs every payload so you can verify it came from us. Rotate secrets at any time without downtime.
POST /oauth/webhooks — create an endpointPATCH /oauth/webhooks/{id} — update subscriptionPOST /oauth/webhooks/{id}/rotate-secretDELETE /oauth/webhooks/{id} — remove
Key features
Capabilities beyond simple CRUD — built for production invoice automation.
Bulk invoice sending
POST /oauth/invoices/bulk accepts an array of invoice objects. Each is processed independently — one failure never blocks the rest. Returns HTTP 207 with per-item status codes.
Signed webhook events
Subscribe to invoice.sent, invoice.delivered, invoice.failed, invoice.received, and invoice.status_changed. Every payload carries an HMAC signature so you can verify authenticity.
UAE Peppol network
Invoices are dispatched via the UAE national Peppol framework. The API handles XML generation, schema validation (EN 16931 + BTUAE), and network delivery.
OAuth 2.0 client credentials
Standard grant_type=client_credentials flow. Tokens are short-lived; refresh tokens rotate on every use. Secret rotation is non-disruptive — the old secret stops working immediately.
Multi-user hierarchy
One application can own many users. Each user owns their own entities and invoices. Pass created_by_user_id on POST /oauth/users to build a tree of sub-accounts under one app.
Async processing pipeline
After POST /oauth/invoices returns 202, the invoice moves through a Temporal workflow: validate → generate XML → deliver. Track progress with GET /oauth/invoices/sent/{id}.
Ownership model
Every resource belongs to your application. Within it, users own entities, and entities own invoices. You can omit the user_id on most calls to attribute everything directly to the application owner — handy for simple single-tenant integrations.
Application
client_id + client_secret
owns all resources; must be approved
Users
optional sub-accounts
each user can own their own entities
Entities
companies / TRNs
the invoice sender; holds TRN & address
Invoices
sent & received
scoped to an entity; tracked per-app
Response codes
All errors return a JSON body with an error key. Validation errors return an array of field-level messages.
| Code | Status | Meaning |
|---|---|---|
| 200 | OK | Successful GET / PATCH / DELETE |
| 202 | Accepted | Invoice queued for async processing |
| 207 | Multi-Status | Bulk invoice results (per-item codes inside) |
| 400 | Bad Request | Validation failed — see error field |
| 401 | Unauthorized | Missing or expired access token |
| 404 | Not Found | Resource does not exist or does not belong to your app |
| 409 | Conflict | Duplicate invoice number for the same entity |
| 502 | Bad Gateway | Peppol network delivery failed |
Authentication
All resource endpoints (Users, Entities, Invoices, Webhooks) require an Authorization: Bearer <access_token> header. Application management endpoints (POST /oauth/apps and related) require a developer login token instead. The Token endpoint itself is public — no auth header needed to exchange credentials.