Create quotes, proformas and fees notes and send them to your clients.
InvoiceXpress API (3.1.0)- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
Invoices- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients.
Guides- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Create shippings, transports & devolutions and send them to your clients.
Estimates- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Sequences- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
A Sequence is used to group invoices in a sequential order.
Clients- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
A Client is an entity you send invoices to.
Accounts- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Manage your InvoiceXpress account settings, users, AT communication, and billing.
Account Credentials- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Manage AT communication credentials for your account.
Collection Alerts- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Configure automated payment collection alerts sent to clients.
Batch Invoices- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
Batch Products- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Bulk import products from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard.
Batch Clients- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
Items- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
An Item is the product or service you invoice.
Schedules- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Create and manage recurring document schedules.
Taxes- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Manage tax rates for your account.
Current User- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Manage the currently authenticated user's own profile, API key, linked accounts, and password recovery.
Currencies- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
List supported currencies and look up exchange rates between them.
Dashboard- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Retrieve dashboard KPIs and analytics about your clients and invoicing activity.
Favorites- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Save and reuse custom filter presets for documents and other list views.
Payment Services- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Configure and manage the payment service integration used to collect payments for your invoices.
Phone Calling Codes- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
List all phone country calling codes.
Reports- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Reporting endpoints — currently covers the balance-per-client report, its summary, and XLSX export.
SAF-T- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Generate the SAF-T (Standard Audit File for Tax) export for your account.
Tax Countries- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
List all tax countries.
Digital signatures- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
Allows opt-in for available digital signature providers, manage its credentials, and sign invoices.
EDI- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
- Save your settings with a NISS (
POST /api/v3/accounts/social_security). Declarations answer422until they exist. - Read the quarter to declare (
quarterly_declaration), or the history (quarterly_declarations). - Report the quarter in Segurança Social Direta, then record it with a self-report (
POST /api/v3/accounts/social_security_reports).
- What is counted.
Invoice,SimplifiedInvoiceandInvoiceReceiptdocuments (and legacy documents with no type) with statussent,settledorsecond_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,productandarticleare 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% foreni. 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).
| Year | IAS (EUR) | Cap, 12 x IAS (EUR) |
|---|---|---|
| 2014 to 2016 | 419.22 | 5 030.64 |
| 2017 | 421.32 | 5 055.84 |
| 2018 | 428.90 | 5 146.80 |
| 2019 | 435.76 | 5 229.12 |
| 2020 and 2021 | 438.81 | 5 265.72 |
| 2022 | 443.20 | 5 318.40 |
| 2023 | 480.43 | 5 765.16 |
| 2024 | 509.26 | 6 111.12 |
| 2025 | 522.50 | 6 270.00 |
| 2026 | 537.13 | 6 445.56 |
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.
- Every
estimated_*field is an estimate.total_amountis 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,exemptandspecial_profileare 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
DELETEof its own;DELETE /api/v3/accounts/social_securitydeletes all of them. - Error messages follow the language of the account, not the
Accept-Languageheader.
Get Social Security Settings
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY"{ "social_security": { "niss": null, "worker_type": "independente", "regime": "services", "exempt": false, "special_profile": "none" } }
Create Social Security Settings
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
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.
Defaults to services. Stored only.
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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"}}'{ "social_security": { "niss": "12345678902", "worker_type": "eni", "regime": "services", "exempt": false, "special_profile": "none" } }
Update Social Security Settings
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
Same normalisation and rules as on create. Validated only when it changes.
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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"}}'{ "social_security": { "niss": "12345678902", "worker_type": "independente", "regime": "services", "exempt": false, "special_profile": "none" } }
Delete Social Security Settings
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -X DELETE "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY"{ "success": true }
Create Social Security Report
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
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.
Optional. Sets submitted_at of the quarter's declaration.
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").
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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}}'{ "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
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/{year}/{quarter}
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/2026/2?api_key=YOUR_API_KEY"{ "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
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
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.
A new value sets submitted_at of the quarter to it; null clears it. Omitted or unchanged leaves it untouched.
0 to 9999999999.99. null clears it.
- Production Serverhttps://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/{year}/{quarter}
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
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}}'{ "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
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
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.
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.
- Production Serverhttps://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declaration
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -X GET "https://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declaration?year=2026&quarter=2&api_key=YOUR_API_KEY"SUCCESS
Read live from the current settings, so a correction shows up at once, even on a past quarter.
Read live from the current settings. Selects the contribution rate.
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.
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.
Always exactly 3 entries, in month order.
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).
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.
Cap on the monthly contribution base, 12 times ias. Decimal string.
ESTIMATE. services_amount x 0.70 + goods_amount x 0.20, rounded to 2 decimals. JSON number.
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.
{ "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
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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.
- Production Serverhttps://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declarations
- cURL
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -X GET "https://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declarations?api_key=YOUR_API_KEY"[ { "year": 2026, "quarters": [ … ], "niss": "12345678902", "worker_type": "independente" }, { "year": 2025, "quarters": [ … ], "niss": "12345678902", "worker_type": "independente" } ]
Changelog- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
- Copy for LLMCopy page as Markdown for LLMs
- View as MarkdownOpen this page as Markdown
- Open in ChatGPTGet insights from ChatGPT
- Open in ClaudeGet insights from Claude
- Connect to CursorInstall MCP server on Cursor
- Connect to VS CodeInstall MCP server on VS Code
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 as4.0.0of this one.
Social SecurityCopy for LLM Copy page as Markdown for LLMs View as Markdown Open this page as Markdown Open in ChatGPT Get insights from ChatGPT Open in Claude Get insights from Claude Connect to Cursor Install MCP server on Cursor Connect to VS Code Install MCP server on VS Code
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_keyonly, 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.