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

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

List Sequences

Request

Returns a paginated list of the sequences (séries) of the current account, 10 per page by default, newest first. Archived séries are included unless archived=false is sent.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
pageinteger>= 1

Page number, starting at 1.

Default 1
Example: page=1
per_pageinteger

Number of series per page. items_per_page and page_items are accepted as aliases.

Default 10
Example: per_page=10
sortstring

Sort field. Any other value sorts by created_at.

Default "created_at"
Enum"created_at""serie_name"
Example: sort=serie_name
sort_orderstring

Sort direction.

Default "DESC"
Enum"ASC""DESC"
Example: sort_order=ASC
textstring

Free-text search on the série name. Ignored when its first word has fewer than 3 characters.

Example: text=SERIE
archivedstring

true returns only archived séries, false only séries that are not archived. Absent, or any other value, returns both.

Enum"true""false"
Example: archived=false
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/sequences?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
sequencesArray of objects
totalsobject
offer_demo_cleanupboolean

true only when the account has the demo série (INVOICEXPRESSDEMO) and no other série yet, i.e. when creating the first real série can also delete the demo one (delete_demo_series).

Example: false
Response
application/json
{ "sequences": [ { … } ], "totals": { "pages": 1, "total": 1 }, "offer_demo_cleanup": false }

Create Sequence

Request

Creates a new sequence for the current account. The operation is asynchronous — poll GET /api/v3/sequences/create_status with the returned status_endpoint params to check completion.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
sequenceobjectrequired
sequence.​serie_namestring[ 1 .. 35 ] charactersrequired
Example: "SERIE2026"
sequence.​set_as_defaultboolean

When true (or the string "true"), the new série becomes the account's default série.

Default false
Example: false
sequence.​create_and_registryboolean

When true (or the string "true"), the série is also registered with the tax authority (AT) right after it is created. The response is then 202 instead of 201.

Default false
Example: false
sequence.​delete_demo_seriesboolean

When true, the demo série is deleted as part of the operation. Only a real true (or the string "true") opts in; any other value means false.

Default false
Example: false
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/sequences?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"sequence":{"serie_name":"SERIE2026","set_as_default":false,"create_and_registry":false}}'

Responses

CREATED — the série was created (create_and_registry not set)

Bodyapplication/json
successboolean
Example: true
status_endpointstring

Relative path and query string to poll with GET /api/v3/sequences/create_status. Its account_id is an encrypted account token, not the numeric account id — pass it back unchanged.

Example: "/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false"
Response
application/json
{ "success": true, "status_endpoint": "/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false" }

Get Sequences By Name

Request

Returns a list of all sequence names for the account.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/sequences/by_name?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
seriesArray of strings
Example: ["INVOICEXPRESSDEMO","SERIE2026"]
Response
application/json
{ "series": [ "INVOICEXPRESSDEMO", "SERIE2026" ] }

Get Sequence Collection

Request

Returns the registration collection for a given sequence, showing the registration status per document category.

Security
apiKeyAuth
Query
namestringrequired

The serie name to retrieve the collection for.

Example: name=INVOICEXPRESSDEMO
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/sequences/collection?api_key=YOUR_API_KEY&name=INVOICEXPRESSDEMO"

Responses

SUCCESS

Bodyapplication/json
sequencesArray of objects
register_statusstring
Example: ""
sequence_statusstring
Example: "active"
Response
application/json
{ "sequences": [ { … } ], "register_status": "", "sequence_status": "active" }

Check Sequence Creation Status

Request

Checks the creation status of a sequence. Called with the query string returned in status_endpoint from the create and register operations. No API key is needed — the encrypted account_id token identifies the account. Returns 202 while the operation is still running and 200 once it has finished; a failed operation is also answered with 200 and success set to false.

Query
account_idstringrequired

Encrypted account token, exactly as returned in status_endpoint. It is not the numeric account id.

Example: account_id=7117e09c4cd4ba7b05b2cc10e34d8684
serie_namestringrequired

The serie name being created/registered.

Example: serie_name=SERIE2026
create_and_registryboolean

Whether the operation also registers the serie with the tax authority.

Example: create_and_registry=false
sequence_already_existsboolean

Whether the serie already existed before this operation.

Example: sequence_already_exists=false
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/sequences/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false"

Responses

SUCCESS

Bodyapplication/json
operation_statusstring
Enum"processing""finished"
Example: "finished"
successboolean
Example: true
dataProgress (object) or Registration result (object) or Timed out (object)
Example: {}
Any of:
Response
application/json
{ "operation_status": "finished", "success": true, "data": {} }

Set Default Sequence

Request

Sets the default sequence for the current account.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
sequenceobject
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/sequences/default?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
successboolean
Example: true
Response
application/json
{ "success": true }

Archive Sequence

Request

Archives a série, for every document type at once. An archived série is no longer offered when a new document is prepared, and cannot be made the default. It does not block anything else: existing documents are unaffected, and a document can still be created with it through the API. The default série cannot be archived.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
sequenceobjectrequired
sequence.​serie_namestringrequired

Name of the série. A série that does not exist answers 404.

Example: "SERIE2026"
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/sequences/archive?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"sequence":{"serie_name":"SERIE2026"}}'

Responses

SUCCESS

Bodyapplication/json
successboolean
Example: true
Response
application/json
{ "success": true }

Unarchive Sequence

Request

Unarchives a série, for every document type at once, so it is offered again when a new document is prepared.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
sequenceobjectrequired
sequence.​serie_namestringrequired

Name of the série. A série that does not exist answers 404.

Example: "SERIE2026"
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/sequences/unarchive?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"sequence":{"serie_name":"SERIE2026"}}'

Responses

SUCCESS

Bodyapplication/json
successboolean
Example: true
Response
application/json
{ "success": true }

Register Sequence

Request

Registers a sequence with the tax authority (AT). The operation is asynchronous — poll GET /api/v3/sequences/create_status with the returned status_endpoint params to check completion.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
sequenceobjectrequired

The série is identified by its name, not by a sequence id. All the sequences of that série that still need registering are sent to the AT.

sequence.​serie_namestringrequired

Name of the série to register.

Example: "INVOICEXPRESSDEMO"
sequence.​delete_demo_seriesboolean

When true, the demo série is deleted as part of the registration. Only a real true (or the string "true") opts in; any other value means false.

Default false
Example: false
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/sequences/register?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"sequence":{"serie_name":"INVOICEXPRESSDEMO"}}'

Responses

ACCEPTED — registration started

Bodyapplication/json
successboolean
Example: true
status_endpointstring

Relative path and query string to poll with GET /api/v3/sequences/create_status. Its account_id is an encrypted account token, not the numeric account id — pass it back unchanged.

Example: "/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false"
Response
application/json
{ "success": true, "status_endpoint": "/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false" }

Get Registered Series

Request

Returns a list of registered series names for the account.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/sequences/registered_series?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/jsonArray [
string
]
Response
application/json
[ "2023", "2024" ]

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.