Oxapher External API docs

A detailed guide for trusted systems that need to create customers, create paid invoices, read invoice responses, and send invoice messages in Oxapher.

Quick start

1. Open Document Settings and create an External API credential.
2. Copy the one-time API key and store it in your integration vault.
3. Send the key as `Authorization: Bearer oxa_live_...`.
4. Include an `Idempotency-Key` on every create or send request.
5. Use HTTPS only in production.

What this API is for

Use the external API when another system already knows a customer or payment has happened and Oxapher should create the matching customer record, issue the invoice, post the payment, and return the number and print link.

This is the same business workflow the app uses internally. That means numbering, accounts posting, payment status, print/share generation, and delivery rules stay consistent.

What you can do

Important rules

• Keys are scope-limited and can be rotated or revoked.
• Requests are rate limited.
• Duplicate create requests return the same result when the idempotency key matches.
• Production requests must use HTTPS.
• The API is live-only today; for a trial call, use a low-value test customer and a single invoice line, then verify the returned `invoice_number` and `print_url`.

Authentication

Send the credential exactly as a bearer token in the request header:

• `Authorization: Bearer oxa_live_...`
• `Content-Type: application/json`
• `Idempotency-Key: your-unique-key`

If the credential does not include the required scope, Oxapher returns `403`.

Customer create: how to call it

`POST /api/external/v1/customers`

Use this when the upstream system already has the customer identity and you want Oxapher to create the matching customer, or return the existing one if `external_reference` is reused.

Important fields:

If you send the same `external_reference` again, Oxapher resolves the same customer instead of creating a duplicate.

Customer response

Invoice create: how to call it

`POST /api/external/v1/invoices`

The invoice payload can either embed a `customer` object or send `customer_id` if the customer already exists.

You can create these invoice types:

• `tax_invoice`
• `retail_invoice`
• `bill_of_supply`
• `cash_memo`
• `pos`

Important invoice fields:

The create call does more than save a draft. It posts the invoice, records the payment when `paid` is true, and returns the print link the same way the app would.

Invoice response

Read invoice details

`GET /api/external/v1/invoices/{sales_document_id}`

Use this when a caller already has the Oxapher invoice id and wants the current document data, status, totals, party details, and approval context.

The response is the standard Oxapher sales-document payload for that invoice. It includes the invoice identity, party details, line items, amounts, status, and any linked approval or accounting context.

Send invoice

`POST /api/external/v1/invoices/{sales_document_id}/send`

Use this when the invoice already exists and you want to trigger delivery after the fact.

You can also send delivery instructions inside the invoice create call through `send`.

Trial call

There is no separate sandbox endpoint in the current API. The safest first test is a live call with a test customer and one invoice line.

Recommended trial flow:

1. Create or resolve a customer with `external_reference` like `checkout-customer-42`.
2. Create a single-line `retail_invoice` or `tax_invoice`.
3. Keep `paid: true`.
4. Set a unique `Idempotency-Key`.
5. Save the returned `invoice_number`, `invoice_id`, and `print_url`.

If the same request runs again with the same idempotency key, Oxapher returns the same result instead of creating a duplicate.

Trial request and expected response

Use these tables as a copy checklist before wiring code:

Error handling

Example customer payload

Use this shape when a checkout or ERP companion app creates a customer first:

Example invoice payload

This is the simple billing pattern:

Related pages

• CRM ERP software
• Quotation software
• Demo request