Skip to content

InvoiceXpress API (3.1.0)

The InvoiceXpress v3 API: invoicing documents (invoices, guides, estimates) and their series, clients, items, taxes, schedules and favorites; account, user, AT-communication and payment-service settings; batch CSV imports of invoices, products and clients; dashboard KPIs, reports, SAF-T export, digital signatures, EDI (CIUS-PT), Social Security declarations, and reference lists (currencies, tax countries, phone calling codes).

What changed between versions of this reference is listed under Changelog, at the end of the navigation.

Authentication

Send your api_key as a query parameter on JSON (or XML) requests. A request with no valid api_key answers 401. The Authorization: Bearer and X-Account headers authenticate the InvoiceXpress web app only; they are not meant for API clients. Endpoints marked as public need no key.

Download OpenAPI description
Overview
InvoiceXpress API Support
Languages
Servers
Production Server
https://api-v3.app.invoicexpress.com/

Invoices

Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients.

Operations

Get Document Details

Request

Retrieves detailed information about a specific document including client data, items, financial summary, and account information. Public endpoint — no API key needed; the document token itself grants access. The response language follows the client's (or the account's) language.

Path
tokenstringrequired

The unique identifier (token) of the document.

Example: abc123token
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/documents/abc123token"

Responses

SUCCESS

Bodyapplication/json
invoiceobject

Wrapper key matches the singular of the requested invoice type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, or receipt).

For the receipt wrapper (payment receipts) the shape differs: items are the payments the receipt covers, each {document_type, document_sequence_number, total, paid} (e.g. {"document_type": "Invoice", "document_sequence_number": "2026/12", "total": 123.0, "paid": 123.0}) instead of product lines; account.bank_data and auto_add_related_document are not returned.

Response
application/json
{ "invoice": { "id": 264663413, "status": "draft", "cancel_reason": "document was duplicated", "archived": false, "type": "Invoice", "sequence_number": "draft", "inverted_sequence_number": "draft", "sequence_id": 5259451, "atcud": "N/A", "saft_hash": "FoIq", "tax_exemption": "M01", "date": "2026-07-27", "due_date": "2026-08-27", "reference": null, "observations": null, "token": "2646634130360dcbca24d2d9509add7c92ccb1d7ab970ce6d", "permalink": "https://web.invoicexpress.com/documents/2646634130360dcbca24d2d9509add7c92ccb1d7ab970ce6d?language=pt", "retention": 0, "global_discount": null, "owner_invoice_id": null, "raw_owner_invoice": "FT 2026/253", "currency": null, "auto_add_related_document": false, "qr_code": "https://example.com/qr_codes/264663413.png", "digital_signed": false, "include_payment_reference": false, "account": { … }, "client": { … }, "items": [ … ], "summary": { … }, "mb_reference": { … } } }

Get Document PDF by Token

Request

Returns the PDF URL of the document identified by its public token, or indicates that PDF generation is in progress (poll again). Public endpoint — no API key needed; the document token itself grants access. Works for any document type.

Path
tokenstringrequired

The unique identifier (token) of the document.

Example: abc123token
Query
attachmentboolean

When true, the returned URL serves the PDF as a download instead of inline display. Ignored by the legacy PDF service.

Default false
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/documents/abc123token/pdf"

Responses

SUCCESS

Bodyapplication/json
pdfobject
Response
application/json
{ "pdf": { "url": "https://s3.amazonaws.com/bucket/document.pdf" } }

Create partial payment for document

Request

Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body.

Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice.

Security
apiKeyAuth
Path
document_idintegerrequired

The unique identifier of the document.

Example: 541674
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Headers
Idempotency-Keystring

Optional client-generated unique key (e.g. a UUID), scoped to the account and the document. Without it, every request registers a new payment.

Example: 6f1c2a4e-1b7d-4c55-9a0e-3f2b8d7c9e10
Bodyapplication/jsonrequired
partial_paymentobjectrequired
partial_payment.​amountnumberrequired
Example: 150.5
partial_payment.​payment_datestring

dd/mm/yyyy

Example: "15/01/2024"
partial_payment.​payment_mechanismstring<= 255 characters

Payment mechanism code (e.g. TB, MB, CC). 255-character limit is the database column default.

Example: "TB"
partial_payment.​notestring

Stored in full on the receipt (observations, a text column). The copy on the treasury movement is truncated to 255 characters. If a value still reaches a 255-character column, the API answers 422 The note is too long (maximum 255 characters). Please shorten it and try again.

Example: "Payment for invoice 123456"
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/documents/541674/partial_payments.json?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

Partial payment created successfully

Bodyapplication/json
receiptobjectrequired
Example: {"id":256124749,"status":"final","archived":false,"type":"Receipt","sequence_number":"14/INVOICEXPRESSDEMO","inverted_sequence_number":"INVOICEXPRESSDEMO/14","sequence_id":5259454,"date":"30/04/2026","due_date":"30/04/2026","reference":"","observations":"Payment for invoice 123456","retention":null,"permalink":"https://web.invoicexpress.com/documents/256124749625970261deda875ee3e3138ffed1a5437d8dc8b","saft_hash":"jd5I","sum":100,"discount":0,"before_taxes":100,"taxes":23,"total":123,"currency":"Euro","client":{"id":192905674,"name":"teste","email":"client@example.com","country":"Portugal"},"items":[],"atcud":"N/D"}
receipt.​idinteger
Example: 256124749
receipt.​statusstring
Example: "final"
receipt.​archivedboolean
Example: false
receipt.​typestring
Example: "Receipt"
receipt.​sequence_numberstring
Example: "14/INVOICEXPRESSDEMO"
receipt.​inverted_sequence_numberstring
Example: "INVOICEXPRESSDEMO/14"
receipt.​sequence_idinteger
Example: 5259454
receipt.​datestring

dd/mm/yyyy

Example: "30/04/2026"
receipt.​due_datestring

dd/mm/yyyy

Example: "30/04/2026"
receipt.​referencestring<= 255 characters
Example: ""
receipt.​observationsstring

No enforced length limit; stored as a text column.

Example: "Payment for invoice 123456"
receipt.​retentionnumber or null
Example: null
receipt.​permalinkstring(uri)
Example: "https://web.invoicexpress.com/documents/256124749625970261deda875ee3e3138ffed1a5437d8dc8b"
receipt.​saft_hashstring

No enforced character limit (text column).

Example: "jd5I"
receipt.​sumnumber
Example: 100
receipt.​discountnumber
Example: 0
receipt.​before_taxesnumber
Example: 100
receipt.​taxesnumber
Example: 23
receipt.​totalnumber
Example: 123
receipt.​currencystring
Example: "Euro"
receipt.​clientobject

The receipt's client. id and name are always present; every other field is omitted when blank on the client.

Example: {"id":192905674,"name":"teste","email":"client@example.com","country":"Portugal"}
receipt.​itemsArray of objects
Example: []
receipt.​atcudstring
Example: "N/D"
Response
application/json
{ "receipt": { "id": 256124749, "status": "final", "archived": false, "type": "Receipt", "sequence_number": "14/INVOICEXPRESSDEMO", "inverted_sequence_number": "INVOICEXPRESSDEMO/14", "sequence_id": 5259454, "date": "30/04/2026", "due_date": "30/04/2026", "reference": "", "observations": "Payment for invoice 123456", "retention": null, "permalink": "https://web.invoicexpress.com/documents/256124749625970261deda875ee3e3138ffed1a5437d8dc8b", "saft_hash": "jd5I", "sum": 100, "discount": 0, "before_taxes": 100, "taxes": 23, "total": 123, "currency": "Euro", "client": { … }, "items": [], "atcud": "N/D" } }

Guides

Create shippings, transports & devolutions and send them to your clients.

Operations

Estimates

Create quotes, proformas and fees notes and send them to your clients.

Operations

Sequences

A Sequence is used to group invoices in a sequential order.

Operations

Clients

A Client is an entity you send invoices to.

Operations

Accounts

Manage your InvoiceXpress account settings, users, AT communication, and billing.

Operations

Account Credentials

Manage AT communication credentials for your account.

Operations

Collection Alerts

Configure automated payment collection alerts sent to clients.

Operations

Batch Invoices

Bulk-create invoices from a CSV file. Flow — GET batch → upload → process → mapping → configure_options → configure → validate → validation → available_docs → POST create → status. DELETE to discard.

Operations

Batch Products

Bulk import products from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard.

Operations

Batch Clients

Bulk import clients from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard. No configure step.

Operations

Items

An Item is the product or service you invoice.

Operations

Schedules

Create and manage recurring document schedules.

Operations

Taxes

Manage tax rates for your account.

Operations

Current User

Manage the currently authenticated user's own profile, API key, linked accounts, and password recovery.

Operations

Currencies

List supported currencies and look up exchange rates between them.

Operations

Dashboard

Retrieve dashboard KPIs and analytics about your clients and invoicing activity.

Operations

Favorites

Save and reuse custom filter presets for documents and other list views.

Operations

Payment Services

Configure and manage the payment service integration used to collect payments for your invoices.

Operations

Phone Calling Codes

List all phone country calling codes.

Operations

Reports

Reporting endpoints — currently covers the balance-per-client report, its summary, and XLSX export.

Operations

SAF-T

Generate the SAF-T (Standard Audit File for Tax) export for your account.

Operations

Tax Countries

List all tax countries.

Operations

Digital signatures

Allows opt-in for available digital signature providers, manage its credentials, and sign invoices.

Operations

EDI

Manage electronic invoice (CIUS-PT) generation and its additional customs/delivery fields. Note these endpoints are served under /api/v1/edi/ on the v3 host, and address documents by a bare id with no document-type segment.

Operations

Social Security

Helps self-employed accounts (trabalhadores independentes and ENI) fill in the quarterly income declaration for Segurança Social. InvoiceXpress calculates the quarter's totals from your invoices and an estimate of the monthly contribution; you record what you reported.

This feature submits nothing to Segurança Social. You type the figures into Segurança Social Direta yourself. It only calculates and records.

Authentication is api_key only, and every endpoint is JSON only. The declaration endpoints are served under /services/v1/social_security/... and the settings and report endpoints under /api/v3/accounts/..., all on the v3 host.

Operations

Changelog

Changes to the documented contract of the InvoiceXpress API v3: endpoints, fields, enum values, status codes and behaviour you can observe as an integrator. The newest version is at the top.

The version number is the one shown at the top of this reference, and it follows these rules:

  • Minor (3.1.0): something was added, such as a new endpoint, field or enum value. Existing integrations keep working.
  • Patch (3.0.1): the documentation was corrected and now describes what the API already did. No behaviour changed.
  • The major version stays at 3. A change that would break existing integrations is released as a new API version, not as 4.0.0 of this one.