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

Guides

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

Operations

List Guides (POST)

Request

Same as GET /api/v3/guides, with the filters and pagination options sent in a JSON body instead of the query string. Useful when the filters (for example long id or client_id lists) do not fit in a URL. Returns the same response.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/json
languagestring

Language of the response

Example: "pt"
items_per_pageinteger

Number of items per page

Example: 10
pageinteger

Page number

Example: 1
idArray of strings

Filter by one or more document ids

Example: ["541897"]
except_idArray of strings

Exclude these document ids

Example: ["541897"]
sortstring

Field to sort by

Example: "document_type"
sort_orderstring

Order of sorting (asc/desc)

Enum"asc""desc"
Example: "desc"
textstring

Text to search for

Example: "asdasdwqe"
non_archivedboolean

Filter for non-archived items

Example: true
archivedboolean

Filter for archived items

Example: false
referencestring

Reference identifier

Example: "123asd"
show_ivaboolean

Show IVA

Example: true
typeArray of strings

Document type filter

Example: ["invoice"]
statusArray of strings

Status filter

Example: ["draft"]
client_idArray of strings

Client id filter

Example: ["541897"]
pluginArray of strings

Plugin filter

Example: ["541897123-asdasdasd-zxcas123"]
serie_nameArray of strings

Serie name filter

Example: ["SerieA"]
date[from]string(date)

Document date range start

Example: "2026-04-27"
date[to]string(date)

Document date range end

Example: "2026-04-27"
loaded_at[from]string(date)

Loaded-at range start

Example: "2026-04-27"
loaded_at[to]string(date)

Loaded-at range end

Example: "2026-04-27"
total_before_taxes[from]number

Total before taxes range start

total_before_taxes[to]number

Total before taxes range end

total_with_taxes[from]number

Total with taxes range start

total_with_taxes[to]number

Total with taxes range end

curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/guides?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"page":1,"items_per_page":10,"status":["sent"]}'

Responses

SUCCESS

Bodyapplication/json
guidesArray of objects
totalsobject
Response
application/json
{ "guides": [ { … } ], "totals": { "count": 44, "pages": 4, "statuses": [ … ] } }

Get Guides Summary

Request

Returns the totals of the specific documents select

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
idArray of strings
Example: ["541897"]
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/guides/summary?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
totalsobject
Response
application/json
{ "totals": { "count": 44, "pages": 5, "statuses": [ … ] } }

Create Guide

Request

Creates a new guide of the specified type, as a draft. The request body wrapper key must match the path segment:

  • shipping for shippings
  • transport for transports
  • devolution for devolutions

loaded_at and at least one item are required. Portuguese accounts must also send address_from and address_to, each with detail, city, postal_code and country.

Security
apiKeyAuth
Path
guides-typestringrequired

The type of the guide document.

Enum"shippings""transports""devolutions"
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
proprietary_uidstring

Your own idempotency identifier for the document (create only). Accepted here at the top level or inside the wrapper; a repeated value returns the guide already created with it instead of creating a new one.

Example: "order-10045"
transportobjectrequired
transport.​datestring(date)
Example: "2026-07-13"
transport.​due_datestring(date)
Example: "2026-07-13"
transport.​loaded_atstringrequired

Load date and time. Required, and must not be in the past; otherwise the API returns 422 Load date must be on or after <current date and time>.

Example: "2026-07-13 13:07:00"
transport.​license_platestring<= 255 characters
Example: "00-AA-00"
transport.​load_sitestring

Loading place (foreign accounts).

Example: "Warehouse A"
transport.​delivery_sitestring

Delivery place (foreign accounts).

Example: "Client store"
transport.​address_fromobject(V3GuideAddress)

Structured address. Used only by Portuguese accounts, where it is required with all four fields filled in; foreign accounts ignore it and use load_site / delivery_site instead.

transport.​address_toobject(V3GuideAddress)

Structured address. Used only by Portuguese accounts, where it is required with all four fields filled in; foreign accounts ignore it and use load_site / delivery_site instead.

transport.​referencestring<= 255 characters
Example: "PO-1234"
transport.​observationsstring

No enforced length limit; stored as a text column.

Example: "Fragile goods"
transport.​sequence_idinteger

Id of the sequence (series) to issue the guide in. The account's default sequence is used when omitted.

Example: 5259467
transport.​manual_sequence_numberstring<= 255 characters
Example: "001"
transport.​tax_exemptionstring

AT tax exemption code (e.g. M01).

Example: "M01"
transport.​retentionnumber

Withholding tax rate (percentage). Only applied when it matches an active retention base.

Example: 0
transport.​global_discountobject or null

Document-level discount. Send null to remove an existing discount.

transport.​currency_codestring

Only applied when the account's plan includes multi-currency.

Example: "EUR"
transport.​ratenumber
Example: 1
transport.​client_idinteger

Id of an existing client. Alternative to client.id.

Example: 456
transport.​clientobject

Resolved by id first, then by name / code; a client that does not exist is created.

transport.​itemsArray of objectsnon-emptyrequired

At least one item is required.

transport.​items[].​namestring<= 60 characters
Example: "Product Name"
transport.​items[].​descriptionstring<= 200 characters
Example: "Product description"
transport.​items[].​unit_pricenumber
Example: 100
transport.​items[].​unitstring
Example: "unit"
transport.​items[].​quantitynumber
Example: 2
transport.​items[].​discountnumber
Example: 0
transport.​items[].​taxobject
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/transports?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"transport":{"date":"2026-07-13","loaded_at":"2026-07-13 13:07:00","address_from":{"detail":"123 Loading Street","city":"Lisbon","postal_code":"1000-001","country":"Portugal"},"address_to":{"detail":"456 Client Street","city":"Porto","postal_code":"4000-001","country":"Portugal"},"client":{"name":"John Doe"},"items":[{"name":"Product Name","unit_price":100,"quantity":1,"tax":{"name":"IVA23"}}]}}'

Responses

CREATED

Bodyapplication/json
transportobject

Wrapper key matches the singular of the requested guide type (transport, shipping, or devolution).

Response
application/json
{ "transport": { "id": 263315060, "status": "draft", "archived": false, "type": "Transport", "sequence_number": "draft", "inverted_sequence_number": "draft", "sequence_id": 5259467, "atcud": "N/A", "saft_hash": "vaDf", "tax_exemption": "M01", "date": "2026-07-13", "due_date": "2026-07-13", "reference": null, "observations": null, "token": "263315060c9d7840b5909668386f4a9c93d4b3c4b98ab064e", "permalink": "https://web.invoicexpress.com/documents/263315060c9d7840b5909668386f4a9c93d4b3c4b98ab064e?language=pt", "retention": 0, "global_discount": null, "loaded_at": "2026-07-13 13:07:00", "license_plate": null, "at_doc_code_id": null, "address_from": { … }, "address_to": { … }, "load_site": "123 Loading Street, Lisbon", "delivery_site": "456 Delivery Street, Porto", "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": { … } } }

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.