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

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

List Digital Signature Providers

Request

Gets the list of all available digital signature providers.

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/digital_signatures/providers?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
providersArray of objects(V3DigitalSignatureProviderObject)
Response
application/json
{ "providers": [ { … } ] }

Get Account Digital Signature Provider

Request

Gets the customer's active digital signature provider. The body is the account provider object at the top level (no wrapper).

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/digital_signatures/accounts/providers?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
idinteger
Example: 1
consent_agreementboolean
Example: true
providerobject or null

The linked provider. Same fields as the providers list except in_use, which is not returned here.

Response
application/json
{ "id": 1, "consent_agreement": true, "provider": { "id": 1, "name": "Multicert", "identifier": "multicert", "description": "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE).", "grant_type": "client_credentials", "url_image": "/digital_signatures/providers/multicert-logo.png", "url_guide": "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao", "url_auth": null, "expired": false, "expiration_date": null } }

Set Account Digital Signature Provider

Request

Sets the customer's digital signature provider.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
provider_idintegerrequired

Id of a provider (see the providers list). Missing or unknown → 404.

Example: 1
client_idstringrequired
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstringrequired
Example: "ChvH5AUVhLNU"
consent_agreementbooleanrequired

Must be true; false or missing → 422 (consent_agreement: ["can't be blank"]).

Valuetrue
Example: true
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"provider_id":1,"client_id":"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85","client_secret":"ChvH5AUVhLNU","consent_agreement":true}'

Responses

SUCCESS — provider was added successfully to the account. The body is the linked provider itself, flat (no wrapper).

Bodyapplication/json
idinteger
Example: 1
namestring
Example: "Multicert"
descriptionstring

Localized text in the account language. May contain HTML (e.g. an <a href> link for Multicert); render or strip it accordingly. Empty string when there is no text for the provider.

Example: "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE)."
identifierstring
Example: "multicert"
grant_typestring

OAuth grant type used by this provider

Example: "client_credentials"
url_imagestring
Example: "/digital_signatures/providers/multicert-logo.png"
url_guidestring
Example: "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao"
url_authstring

OAuth authorization URL to opt into this provider

Example: "https://preprod.autenticacao.gov.pt/oauth/askauthorization"
in_useboolean

Whether this provider is the one currently active for the account

Example: false
expiredboolean or null
Example: false
expiration_datestring or null(date-time)
Example: null
Response
application/json
{ "id": 1, "name": "Multicert", "description": "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE).", "identifier": "multicert", "grant_type": "client_credentials", "url_image": "/digital_signatures/providers/multicert-logo.png", "url_guide": "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao", "url_auth": "https://preprod.autenticacao.gov.pt/oauth/askauthorization", "in_use": false, "expired": false, "expiration_date": null }

Update Account Digital Signature Provider

Request

Updates the active customer's digital signature provider.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
provider_idintegerrequired

Id of a provider (see the providers list). Missing or unknown → 404.

Example: 1
client_idstringrequired
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstringrequired
Example: "ChvH5AUVhLNU"
consent_agreementbooleanrequired

Must be true; false or missing → 422 (consent_agreement: ["can't be blank"]).

Valuetrue
Example: true
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"provider_id":1,"client_id":"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85","client_secret":"ChvH5AUVhLNU","consent_agreement":true}'

Responses

SUCCESS — the body is the linked provider itself, flat (no wrapper).

Bodyapplication/json
idinteger
Example: 1
namestring
Example: "Multicert"
descriptionstring

Localized text in the account language. May contain HTML (e.g. an <a href> link for Multicert); render or strip it accordingly. Empty string when there is no text for the provider.

Example: "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE)."
identifierstring
Example: "multicert"
grant_typestring

OAuth grant type used by this provider

Example: "client_credentials"
url_imagestring
Example: "/digital_signatures/providers/multicert-logo.png"
url_guidestring
Example: "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao"
url_authstring

OAuth authorization URL to opt into this provider

Example: "https://preprod.autenticacao.gov.pt/oauth/askauthorization"
in_useboolean

Whether this provider is the one currently active for the account

Example: false
expiredboolean or null
Example: false
expiration_datestring or null(date-time)
Example: null
Response
application/json
{ "id": 1, "name": "Multicert", "description": "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE).", "identifier": "multicert", "grant_type": "client_credentials", "url_image": "/digital_signatures/providers/multicert-logo.png", "url_guide": "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao", "url_auth": "https://preprod.autenticacao.gov.pt/oauth/askauthorization", "in_use": false, "expired": false, "expiration_date": null }

Remove Account Digital Signature Provider

Request

Removes the account's digital signature provider and its credentials. Idempotent; answers 204 also when no provider is configured.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X DELETE "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY"

Responses

NO CONTENT — provider removed, or there was none.

Response
No content

Get Digital Signature Provider Credentials

Request

Gets the customer's digital signature provider credentials. The secret is never returned in clear.

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/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
client_idstring or null
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstring

Never returned in clear. "********" when a secret is stored, "" otherwise.

Enum"********"""
Example: "********"
Response
application/json
{ "client_id": "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85", "client_secret": "********" }

Set Digital Signature Provider Credentials

Request

Sets the customer's digital signature provider credentials. Requires an active digital signature provider to already be configured for the account (see the account providers endpoints).

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
client_idstringrequired
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstringrequired
Example: "ChvH5AUVhLNU"
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"client_id":"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85","client_secret":"ChvH5AUVhLNU"}'

Responses

NO CONTENT — credentials were checked with the provider and stored

Response
No content

Update Digital Signature Provider Credentials

Request

Updates the customer's digital signature provider credentials. Requires an active digital signature provider to already be configured for the account (see the account providers endpoints).

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
client_idstringrequired
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstringrequired
Example: "ChvH5AUVhLNU"
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"client_id":"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85","client_secret":"ChvH5AUVhLNU"}'

Responses

NO CONTENT — credentials were checked with the provider and updated

Response
No content

Patch Digital Signature Provider Credentials

Request

Updates the customer's digital signature provider credentials. Equivalent to PUT on this same path — the API accepts both verbs. Requires an active digital signature provider to already be configured for the account (see the account providers endpoints).

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
client_idstringrequired
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstringrequired
Example: "ChvH5AUVhLNU"
curl -X PATCH "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS — credentials were updated successfully

Bodyapplication/json
client_idstringrequired
Example: "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
client_secretstringrequired
Example: "ChvH5AUVhLNU"
Response
application/json
{ "client_id": "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85", "client_secret": "ChvH5AUVhLNU" }

Remove Digital Signature Provider Credentials

Request

Removes the customer's digital signature provider credentials.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X DELETE "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY"

Responses

NO CONTENT — credentials were removed successfully

Response
No content

Get Digital Signature Info

Request

Returns the digital signature configuration data for the current account, including provider details, credentials, and status information. If no digital signature is configured, returns "NOT_CONFIGURED".

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/digital_signature/info?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
digital_signature_itemV3DigitalSignatureInfoObject (object) or string

The account's digital signature configuration, or "NOT_CONFIGURED" if no digital signature has been set up.

One of:

The account's digital signature configuration, or "NOT_CONFIGURED" if no digital signature has been set up.

Response
application/json
{ "digital_signature_item": { "uid": "12345", "accessToken": "encrypted_access_token_here", "credentialId": "PRT.123456789-PRT.123 123 123-abc123-ab12-cd34-ef56-123456789abc", "clientSecret": "weWihPC67jwTdtAVx2UR@", "expiration_date": "2024-12-31", "provider": "multicert", "is_online_signature": true, "refreshToken": "encrypted_refresh_token_here", "fiscalId": "123456789", "status": "2", "is_status_communicated": true, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } }

Get Document Digital Signature Status

Request

Returns the digital signature status information for a specific document, including whether it is signed and whether it should be signed.

Security
apiKeyAuth
Path
document_idintegerrequired

The unique identifier of the document.

Example: 12345
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/document/12345/status?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
signedboolean

Indicates whether the document is digitally signed

Example: true
should_be_signedboolean

Indicates whether the document should be digitally signed

Example: true
signaturestring

PDF service v2 only. Signature state of the document's PDF.

Enum"signed""unsigned""pending""not_applicable""unknown"
Example: "signed"
signature_providerstring or null

PDF service v2 only. Provider that signed the PDF.

Example: "multicert"
signature_error_codestring or null

PDF service v2 only. Why the PDF was delivered unsigned (e.g. credentials_expired).

Example: null
signature_updated_atstring or null

PDF service v2 only. When the signature state last changed.

Example: null
Response
application/json
{ "signed": true, "should_be_signed": true, "signature": "signed", "signature_provider": "multicert", "signature_error_code": null, "signature_updated_at": null }

Sign Document

Request

Triggers the digital signature process for a specific document by its ID. This will generate a new PDF for the document including the digital signature.

Security
apiKeyAuth
Path
idintegerrequired

The unique identifier of the document.

Example: 12345
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/document/12345/sign?api_key=YOUR_API_KEY"

Responses

SUCCESS — PDF regeneration requested (legacy PDF service). Body is an empty object {}.

Bodyapplication/json
object
Response
application/json
{}

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.