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

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

Typical flow

  1. Save your settings with a NISS (POST /api/v3/accounts/social_security). Declarations answer 422 until they exist.
  2. Read the quarter to declare (quarterly_declaration), or the history (quarterly_declarations).
  3. Report the quarter in Segurança Social Direta, then record it with a self-report (POST /api/v3/accounts/social_security_reports).

How the numbers are calculated

  • What is counted. Invoice, SimplifiedInvoice and InvoiceReceipt documents (and legacy documents with no type) with status sent, settled or second_copy, dated in the month. Credit and debit notes, plain receipts, drafts, cancelled and deleted documents, estimates and guides are not counted.
  • Amount. The amount before VAT (total_before_taxes).
  • Services and goods. Each line goes into one bucket by its unit. unit, product and article are goods; any other unit is a service.
  • Estimated relevant income. Services x 70% plus goods x 20%.
  • Estimated monthly payment. One third of the quarter's relevant income (the monthly base), capped at 12 x IAS, multiplied by the rate: 21.4% for independente, 25.2% for eni. The result is never below EUR 20 per month, a flat amount. One declaration covers three equal monthly contributions, so the figure is per month, not per quarter.
  • IAS. The cap uses the IAS of the contribution year, which is the quarter's year, except Q4, which uses the next year (Q4 is declared in January). If that year is missing from the table (a future year, or before 2014), the latest known IAS is used (2026, EUR 537.13).
YearIAS (EUR)Cap, 12 x IAS (EUR)
2014 to 2016419.225 030.64
2017421.325 055.84
2018428.905 146.80
2019435.765 229.12
2020 and 2021438.815 265.72
2022443.205 318.40
2023480.435 765.16
2024509.266 111.12
2025522.506 270.00
2026537.136 445.56

Freshness

The current open month is always calculated live. A closed month with at least one counted document is calculated on first request and then cached; a closed month with none is calculated again on every request, unless a self-report stamped it with submitted_at, which stores it. It is recalculated in the background when a document dated in it is finalised, cancelled or deleted, so the previous total can be served meanwhile. Recalculation is queued at most once per month every 30 seconds: a change made inside that window is not queued, and the cached total can stay out of date until a later change in that month.

Limitations

  • Every estimated_* field is an estimate. total_amount is the figure to declare, but it is not yet authoritative: whether income is recognised on the issue or payment date, whether credit notes net against it, and whether invoices without a linked payment count are still open questions.
  • The services and goods split is a heuristic on the line unit, not a fiscal classification.
  • regime, exempt and special_profile are stored and returned, but no calculation uses them. There is no eligibility check: any account can save a NISS, including accounts that are exempt from this declaration.
  • A self-report has no DELETE of its own; DELETE /api/v3/accounts/social_security deletes all of them.
  • Error messages follow the language of the account, not the Accept-Language header.

Get Social Security Settings

Request

Returns the account's Social Security settings, wrapped in a social_security key. Always 200: when nothing is configured it returns the defaults with niss: null, which is how a client detects that the account is not set up yet. Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

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

Responses

SUCCESS

Bodyapplication/json
social_securityobject(V3SocialSecuritySettings)

The account's Social Security settings. Always returns all five fields.

Response
application/json
{ "social_security": { "niss": null, "worker_type": "independente", "regime": "services", "exempt": false, "special_profile": "none" } }

Create Social Security Settings

Request

Creates the account's Social Security settings. Send the fields wrapped in a social_security key. niss is required. It is normalised (spaces, -, . and / are stripped), must have 11 digits, start with 1 or 2 and have a valid check digit. If settings already exist the call answers 422; use PUT instead. Do not send null for worker_type, regime, exempt or special_profile (the API answers 500). regime, exempt and special_profile are stored and returned but no calculation uses them; only worker_type changes the contribution rate. Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
social_securityobjectrequired
social_security.​nissstringrequired

11 digits, first digit 1 or 2, valid check digit. Spaces, -, . and / are stripped before validation and storage, so 123-456-789-02 is stored as 12345678902. Letters make it invalid.

Example: "123-456-789-02"
social_security.​worker_typestring

Defaults to independente.

Enum"independente""eni"
Example: "eni"
social_security.​regimestring

Defaults to services. Stored only.

Enum"services""goods""mixed"
Example: "services"
social_security.​exemptboolean

Defaults to false. Stored only.

Example: false
social_security.​special_profilestring

Defaults to none. Stored only.

Enum"none""organized_accounting""accumulation""own_fund"
Example: "none"
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"social_security":{"niss":"123-456-789-02","worker_type":"eni"}}'

Responses

SUCCESS

Bodyapplication/json
social_securityobject(V3SocialSecuritySettings)

The account's Social Security settings. Always returns all five fields.

Response
application/json
{ "social_security": { "niss": "12345678902", "worker_type": "eni", "regime": "services", "exempt": false, "special_profile": "none" } }

Update Social Security Settings

Request

Updates the account's Social Security settings. PATCH is routed to the same action and behaves identically. Send only the fields to change, wrapped in a social_security key; the response always returns all five. Answers 404 when no settings exist yet; use POST first. niss is validated only when it changes, so a stored invalid NISS does not block updating other fields. Do not send null for worker_type, regime, exempt or special_profile (the API answers 500). Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
social_securityobjectrequired
social_security.​nissstring

Same normalisation and rules as on create. Validated only when it changes.

Example: "123-456-789-02"
social_security.​worker_typestring
Enum"independente""eni"
Example: "independente"
social_security.​regimestring
Enum"services""goods""mixed"
Example: "services"
social_security.​exemptboolean
Example: false
social_security.​special_profilestring
Enum"none""organized_accounting""accumulation""own_fund"
Example: "none"
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"social_security":{"worker_type":"independente"}}'

Responses

SUCCESS

Bodyapplication/json
social_securityobject(V3SocialSecuritySettings)

The account's Social Security settings. Always returns all five fields.

Response
application/json
{ "social_security": { "niss": "12345678902", "worker_type": "independente", "regime": "services", "exempt": false, "special_profile": "none" } }

Delete Social Security Settings

Request

Deletes the account's Social Security settings and also deletes every quarterly self-report recorded for the account. Idempotent: always 200 with {"success": true}, whether or not anything existed. The quarterly declaration endpoints answer 422 again afterwards. Cached quarters keep their submitted_at; it shows again if settings are re-created. Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

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

Responses

SUCCESS

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

Create Social Security Report

Request

Records that the account declared a quarter in Segurança Social Direta, and what it was charged. It is a personal tracking record; nothing is sent anywhere. Send the fields wrapped in a social_security_report key; year (1583 to 9999, except year 9999 with quarter 4 and reported_at set, which answers 500 and saves nothing; the API does not validate it and a value outside the range may answer 500) and quarter (1 to 4) are required and identify the report (there is no id): at most one per account, year and quarter. estimated_monthly_payment and monthly_payment accept 0 to 9999999999.99 and are returned as decimal strings rounded to 2 places, in the shortest form but always with at least one decimal digit ("70.0", "55.1", "53.52"). Setting reported_at also sets submitted_at of that quarter on the quarterly declaration endpoints. The account must already have a NISS (POST /api/v3/accounts/social_security), otherwise the call answers 422. A report cannot be deleted on its own: there is no DELETE; reports are removed only by DELETE /api/v3/accounts/social_security, which deletes all of them. Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
social_security_reportobjectrequired
social_security_report.​yearintegerrequired

Required. Supported range 1583 to 9999, except year 9999 with quarter 4 when reported_at is set (500, nothing is saved); a value outside the range may answer 500.

Example: 2026
social_security_report.​quarterinteger[ 1 .. 4 ]required

Required, 1 to 4.

Example: 2
social_security_report.​reported_atstring or null(date-time)

Optional. Sets submitted_at of the quarter's declaration.

Example: "2026-07-15T19:08:03Z"
social_security_report.​estimated_monthly_paymentnumber or string or null

Optional, 0 to 9999999999.99. Rounded to 2 places and returned as a decimal string with at least one decimal digit (70 is returned as "70.0").

Example: 53.53
social_security_report.​monthly_paymentnumber or string or null

Optional, 0 to 9999999999.99. Rounded to 2 places and returned as a decimal string with at least one decimal digit (70 is returned as "70.0").

Example: 55.1
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"social_security_report":{"year":2026,"quarter":2,"reported_at":"2026-07-15T19:08:03Z","estimated_monthly_payment":53.53,"monthly_payment":55.10}}'

Responses

SUCCESS. Echoes all five fields.

Bodyapplication/json
social_security_reportobject(V3SocialSecurityReport)

A quarterly self-report, identified by year + quarter (there is no id). At most one per account, year and quarter. A personal tracking record; nothing is sent to Segurança Social.

Response
application/json
{ "social_security_report": { "year": 2026, "quarter": 2, "reported_at": "2026-07-15T20:08:03+01:00", "estimated_monthly_payment": "53.53", "monthly_payment": "55.1" } }

Get Social Security Report

Request

Returns the quarterly self-report for year and quarter, wrapped in a social_security_report key. 422 is checked before 404: without a NISS the answer is 422 even for a quarter that never had a report. With a NISS, 404 means no report exists for that quarter (the client can show a create form); it is also the answer when a URL segment is not purely digits (for example /2026abc/2). Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

Security
apiKeyAuth
Path
yearintegerrequired

Year of the quarterly self-report, digits only (for example 2026). A segment that is not purely digits (such as 2026abc) answers 404, as does a year with no report.

Example: 2026
quarterinteger[ 1 .. 4 ]required

Quarter of the self-report, 1 to 4, digits only. A segment that is not purely digits answers 404, as does a quarter with no report (including 0 and 5 or more).

Example: 2
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/2026/2?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
social_security_reportobject(V3SocialSecurityReport)

A quarterly self-report, identified by year + quarter (there is no id). At most one per account, year and quarter. A personal tracking record; nothing is sent to Segurança Social.

Response
application/json
{ "social_security_report": { "year": 2026, "quarter": 2, "reported_at": "2026-07-15T20:08:03+01:00", "estimated_monthly_payment": "53.53", "monthly_payment": "55.1" } }

Update Social Security Report

Request

Updates the quarterly self-report for year and quarter. PATCH is routed to the same action and behaves identically. Send only the fields to change, wrapped in a social_security_report key; the response always returns all five. year and quarter in the body are silently ignored, the URL identifies the report; there is no way to move a report to another quarter, and no DELETE (reports are removed only by DELETE /api/v3/accounts/social_security). reported_at and submitted_at of that quarter on the quarterly declaration endpoints are synced when a report is created or updated (deleting the settings does not clear submitted_at): setting or changing reported_at sets submitted_at to it, null clears submitted_at, and a change to only estimated_monthly_payment or monthly_payment leaves it untouched. Exception: for year 9999 with quarter 4, setting reported_at answers 500 and saves nothing. 422 (no NISS) is checked before 404 (no report for that quarter, or a URL segment that is not purely digits). Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

Security
apiKeyAuth
Path
yearintegerrequired

Year of the quarterly self-report, digits only (for example 2026). A segment that is not purely digits (such as 2026abc) answers 404, as does a year with no report.

Example: 2026
quarterinteger[ 1 .. 4 ]required

Quarter of the self-report, 1 to 4, digits only. A segment that is not purely digits answers 404, as does a quarter with no report (including 0 and 5 or more).

Example: 2
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
social_security_reportobjectrequired
social_security_report.​reported_atstring or null(date-time)

A new value sets submitted_at of the quarter to it; null clears it. Omitted or unchanged leaves it untouched.

Example: "2026-08-01T10:00:00Z"
social_security_report.​estimated_monthly_paymentnumber or string or null

0 to 9999999999.99. null clears it.

Example: 53.53
social_security_report.​monthly_paymentnumber or string or null

0 to 9999999999.99. null clears it.

Example: 60.46
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/2026/2?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"social_security_report":{"reported_at":"2026-08-01T10:00:00Z","monthly_payment":60.46}}'

Responses

SUCCESS. Returns all five fields.

Bodyapplication/json
social_security_reportobject(V3SocialSecurityReport)

A quarterly self-report, identified by year + quarter (there is no id). At most one per account, year and quarter. A personal tracking record; nothing is sent to Segurança Social.

Response
application/json
{ "social_security_report": { "year": 2026, "quarter": 2, "reported_at": "2026-08-01T11:00:00+01:00", "estimated_monthly_payment": "53.53", "monthly_payment": "60.46" } }

Get Social Security Quarterly Declaration

Request

Returns the totals of one quarter, calculated from the account's invoices. Needs a NISS: answers 422 until the settings exist. Served under /services/v1/, not /api/v3/, on the same host. year and quarter are optional and never produce a 422. Year and quarter rules: year and quarter are read as integers like Ruby to_i: leading digits are used, and a single underscore between digits is accepted (2026abc and 2_026 are 2026; 2__026 is 2; abc is 0). If either is missing, if year is not positive, or if quarter is not 1 to 4, both fall back to the last completed quarter (the previous quarter; from January to March, quarter 4 of the previous year) and the answer is 200, so check year and quarter in the response. Supported range: year 1583 to 9999 with quarter 1 to 4, except year=9999&quarter=4, which answers 500. Outside the supported range, results are not guaranteed and may answer 500 (for example a year of 10000 or more with a valid quarter, or some years before 1583). A year or quarter sent as an array or hash (year[]=1, quarter[]=1) answers 500. Counts Invoice, SimplifiedInvoice and InvoiceReceipt documents with status sent, settled or second_copy dated inside the quarter, using the gross amount before VAT (total_before_taxes). Credit and debit notes, plain receipts, drafts, cancelled and deleted documents, estimates and guides are not counted. Money totals are decimal strings. Every estimated_* field is an estimate; total_amount is the figure to declare. niss and worker_type are read live from the current settings. Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social. The current open month is always calculated live; a closed month is cached and recalculated in the background when a document dated in it is finalised, cancelled or deleted, so the previous total can still be served for a short while. Recalculation is debounced to one run per month every 30 seconds: a change made within 30 seconds of an earlier one in the same month is not queued, and the cached total may stay out of date until a later change in that month. Documents with no type (legacy) are counted as well.

Security
apiKeyAuth
Query
yearinteger>= 1

Year of the quarter, read as an integer like Ruby to_i (2026abc and 2_026 are 2026; abc is 0). If it is missing or not positive, or quarter is missing or not 1 to 4, both parameters fall back to the last completed quarter (200). Supported range: 1583 to 9999, except year=9999&quarter=4 (500). Outside it, results are not guaranteed and may answer 500. An array or hash (year[]=1) answers 500.

Example: year=2026
quarterinteger[ 1 .. 4 ]

Quarter, 1 to 4, read as an integer like Ruby to_i (a single underscore between digits is accepted). If it is missing or any other value, both parameters fall back to the last completed quarter (200, no 422). An array or hash (quarter[]=1) answers 500.

Example: quarter=2
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declaration?year=2026&quarter=2&api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
yearinteger
Example: 2026
nissstring

Read live from the current settings, so a correction shows up at once, even on a past quarter.

Example: "12345678902"
worker_typestring

Read live from the current settings. Selects the contribution rate.

Enum"independente""eni"
Example: "independente"
quarterinteger[ 1 .. 4 ]
Example: 2
start_datestring(date)

First day of the quarter.

Example: "2026-04-01"
end_datestring(date)

Last day of the quarter.

Example: "2026-06-30"
total_amountstring

The figure to declare in Segurança Social Direta: the gross amount invoiced in the quarter, before VAT. Decimal string (for example "1250.5"), not a JSON number. Counts Invoice, SimplifiedInvoice and InvoiceReceipt documents (and legacy documents with no type) with status sent, settled or second_copy, dated inside the quarter.

Example: "1250.5"
services_amountstring

Heuristic services share of total_amount, from the unit of each invoice line. Normally adds up to total_amount together with goods_amount, but the two come from different sources (total_amount from the document totals, the split from the line subtotals) and may differ by rounding. Decimal string.

Example: "1000.5"
goods_amountstring

Heuristic goods share of total_amount. Decimal string.

Example: "250.0"
document_countinteger

Number of documents counted.

Example: 4
monthly_breakdownArray of objects(V3SocialSecurityMonthlyBreakdown)= 3 items

Always exactly 3 entries, in month order.

contribution_yearinteger

Year whose IAS caps the contribution base. Equals year, except for quarter 4, which is declared in January and uses year + 1. If that year is not in the IAS table (a future year, or before 2014) the latest known IAS is used (537.13, the 2026 value).

Example: 2026
iasstring

IAS (Indexante dos Apoios Sociais) of contribution_year, as a decimal string without fixed decimals ("537.13", "522.5"). Returned so a client can explain the estimate.

Example: "537.13"
monthly_base_capstring

Cap on the monthly contribution base, 12 times ias. Decimal string.

Example: "6445.56"
estimated_relevant_incomenumber

ESTIMATE. services_amount x 0.70 + goods_amount x 0.20, rounded to 2 decimals. JSON number.

Example: 750.35
estimated_monthly_paymentnumber

ESTIMATE. Contribution for each of the 3 months this declaration bills, not for the quarter. max(round(min(estimated_relevant_income / 3, monthly_base_cap) x rate, 2), 20.00), with rate 0.214 for independente and 0.252 for eni. Never below the 20.00 monthly minimum, so a quarter with no invoicing still shows 20.0. JSON number.

Example: 53.52
submitted_atstring or null(date-time)

When the account recorded a self-report for this quarter, otherwise null. It can be set on a quarter that is still open.

Example: null
Response
application/json
{ "year": 2026, "quarter": 2, "start_date": "2026-04-01", "end_date": "2026-06-30", "total_amount": "1250.5", "services_amount": "1000.5", "goods_amount": "250.0", "document_count": 4, "monthly_breakdown": [ { … }, { … }, { … } ], "niss": "12345678902", "worker_type": "independente", "contribution_year": 2026, "ias": "537.13", "monthly_base_cap": "6445.56", "estimated_relevant_income": 750.35, "estimated_monthly_payment": 53.52, "submitted_at": "2026-07-15T19:08:03.000Z" }

List Social Security Quarterly Declarations

Request

Returns the declaration history, grouped by year, newest year first, with the quarters of each year newest first. Takes no query parameters other than api_key and ignores any that are sent. niss and worker_type are read live and appear once per year; each quarter object has the fields of the single declaration minus year, niss and worker_type. Needs a NISS: answers 422 until the settings exist. Served under /services/v1/, not /api/v3/, on the same host. Which quarters are listed, as a union: every quarter of the current year, including open and future ones (zeros when nothing is invoiced yet); every quarter the account invoiced in since 1 January two years before the current year (for example, since 1 January 2024 in 2026); every quarter that already has cached data, from any year, so history does not drop off. Each listed quarter is re-aggregated over its 3 months, so a total is never partial. A quarter with no invoicing still shows estimated_monthly_payment: 20.0, the monthly minimum. Money totals are decimal strings. Every estimated_* field is an estimate; total_amount is the figure to declare. Requires the administrator or contributor role. Error messages follow the language of the account (pt, en or es), not the Accept-Language header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declarations?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/jsonArray [
yearinteger
Example: 2026
quartersArray of objects(V3SocialSecurityQuarter)

Newest quarter first.

nissstring

Read live from the current settings.

Example: "12345678902"
worker_typestring

Read live from the current settings.

Enum"independente""eni"
Example: "independente"
]
Response
application/json
[ { "year": 2026, "quarters": [ … ], "niss": "12345678902", "worker_type": "independente" }, { "year": 2025, "quarters": [ … ], "niss": "12345678902", "worker_type": "independente" } ]

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.