# InvoiceXpress API 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. Version: 3.1.0 ## Servers Production Server ``` https://api-v3.app.invoicexpress.com ``` ## Security ### apiKeyAuth Type: apiKey In: query Name: api_key ## Download OpenAPI description [InvoiceXpress API](https://docs.invoicexpress.com/_bundle/@v3/v3.yaml) ## Invoices Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients. ### Get Document Details - [GET /api/v3/documents/{token}](https://docs.invoicexpress.com/v3/invoices/getv3document.md): Retrieves detailed information about a specific document including client data, items, financial summary, and account information. Public endpoint — no API key needed; the document token itself grants access. The response language follows the client's (or the account's) language. ### Get Document PDF by Token - [GET /api/v3/documents/{token}/pdf](https://docs.invoicexpress.com/v3/invoices/getv3documentpdfbytoken.md): Returns the PDF URL of the document identified by its public token, or indicates that PDF generation is in progress (poll again). Public endpoint — no API key needed; the document token itself grants access. Works for any document type. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/invoices/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### List Invoices - [GET /api/v3/invoices](https://docs.invoicexpress.com/v3/invoices/listv3invoices.md): Returns a list of all your invoices. ### Create Invoice-type Document - [POST /api/v3/{invoices-type}](https://docs.invoicexpress.com/v3/invoices/createv3invoice.md): Creates a new document of the specified invoice type, as a draft unless finalized later through change-state. The request body wrapper key must be the singular of the path segment: - invoice for invoices - invoice_receipt for invoice_receipts - simplified_invoice for simplified_invoices - credit_note for credit_notes - debit_note for debit_notes Any other key returns 422 No element provided. The response wrapper key follows the same rule. ### List document batches for the account - [GET /api/v3/invoices/batches](https://docs.invoicexpress.com/v3/invoices/getv3invoicebatches.md): Returns all document batches belonging to the authenticated account. Each item includes the stored number_of_documents value as count (set when the import batch is finalized). Use each batch id as the batch_id query parameter on GET /api/v3/invoices to list only invoices from that batch. ### Check Finalize Conditions - [GET /api/v3/invoices/{id}/check_finalize](https://docs.invoicexpress.com/v3/invoices/checkfinalizeinvoice.md): Checks if there are conditions to finalize an invoice (e.g., future dates or earlier drafts). ### Update Invoice Summary - [POST /api/v3/{invoices-type}/update_summary](https://docs.invoicexpress.com/v3/invoices/updatev3invoicesummary.md): Calculates and returns the financial summary (totals, taxes, discounts, retention) for an invoice based on the provided invoice data without saving the invoice. The request body wrapper key must be the singular of the path type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, receipt); any other key returns 422 "No invoice element provided" (with the expected key name). ### Calculate Invoice Summary - [POST /api/v3/{invoices-type}/calculate_summary](https://docs.invoicexpress.com/v3/invoices/calculatev3invoicesummary.md): Unvalidated counterpart of update_summary: calculates the totals from the items, retention, global_discount, currency_code, rate and tax exemption in the body, without saving anything. Nothing else (client, dates, series) is read, and invalid input is coerced rather than rejected, so a missing or wrong wrapper key returns a summary of zeros instead of an error. At most 1000 items are taken into account. The wrapper key is the singular of the path segment (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, receipt). ### Get Invoices Summary - [POST /api/v3/invoices/summary](https://docs.invoicexpress.com/v3/invoices/getv3invoicessummary.md): Returns the totals of the documents matching the filters. Accepts the same filters as GET /api/v3/invoices (see V3InvoicesQueryParams: id[], except_id[], type[], status[], client_id[], serie_name[], date, due_date, total_before_taxes, total_with_taxes, text, archived, non_archived, reference, ...), sent either in the query string or in the JSON body. Pagination does not apply: totals.pages is always 1. ### Transform Document - [GET /api/v3/invoices/{id}/transform_document](https://docs.invoicexpress.com/v3/invoices/transformv3document.md): Returns a transformed version of the specified invoice document. This is typically used to prepare the document to be converted into another invoice-type document (e.g., credit note or other variations), mirroring the data structure of a cloned document ready for further edits. ### Get Document by ID - [GET /api/v3/{invoices-type}/{id}](https://docs.invoicexpress.com/v3/invoices/getv3documentbyid.md): Retrieves detailed information about a specific document including client data, items, financial summary, and account information. ### Update Invoice-type Document - [PUT /api/v3/{invoices-type}/{id}](https://docs.invoicexpress.com/v3/invoices/updatev3invoice.md): Updates a document of the specified invoice type and returns it. The id must belong to a document of that type. The request body wrapper key must be the singular of the path segment (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note). The body accepts the same fields as create, and items must again contain at least one item: the item list sent replaces the stored one. Documents in status sent, settled, deleted, canceled, accepted, refused or second_copy cannot be changed (422 "Document has been finalized so can't be changed anymore"). ### Get New Document Defaults - [GET /api/v3/{invoices-type}/new](https://docs.invoicexpress.com/v3/invoices/newv3invoice.md): Returns the defaults and choice lists used to build a new document of the specified invoice type (payment terms, exemption reasons, series of that type, currencies, retention options, taxes and default remarks). Nothing is created. ### Clone Document - [GET /api/v3/{invoices-type}/{id}/clone](https://docs.invoicexpress.com/v3/invoices/clonev3invoice.md): Returns an unsaved copy of the document, ready to be edited and sent to create. Nothing is created: id and token are null. The copy is a draft of the path type, dated today, with the due date moved by the client's (or account's) payment days, the exchange rate refreshed for foreign-currency documents, and the account's default series of that type. The source id can be any document of the account; it is not checked against the path type. ### Sync Invoice with an Integration - [POST /api/v3/invoices/{id}/handle_integration](https://docs.invoicexpress.com/v3/invoices/handlev3invoiceintegration.md): Queues a background job that associates the document with an integration (plugin). Answers {} immediately; the result is not reported back. ### Archive a document - [PUT /api/v3/{invoices-type}/{id}/archive](https://docs.invoicexpress.com/v3/invoices/archivev3document.md): Archives the specified document by setting its archived flag to true and returns the updated document. ### Archive a document - [PATCH /api/v3/{invoices-type}/{id}/archive](https://docs.invoicexpress.com/v3/invoices/archivev3documentpatch.md): Archives the specified document by setting its archived flag to true and returns the updated document. ### Creates a comment for a document - [POST /api/v3/{invoices-type}/{id}/comments](https://docs.invoicexpress.com/v3/invoices/createv3documentcomment.md): Creates a new comment for the specified document. Comments can only be deleted within 15 minutes of creation. ### Deletes a comment from a document - [DELETE /api/v3/{invoices-type}/{id}/comments/{comment_id}](https://docs.invoicexpress.com/v3/invoices/deletev3documentcomment.md): Deletes a comment from the specified document. Comments can only be deleted within 15 minutes of creation and only by the author. ### List document movements - [GET /api/v3/{invoices-type}/{id}/movements](https://docs.invoicexpress.com/v3/invoices/listv3documentmovements.md): Returns the list of movements related to the specified document. ### Change document state - [PUT /api/v3/{invoices-type}/{id}/change-state.json](https://docs.invoicexpress.com/v3/invoices/changev3invoicedocumentstate.md): Changes the state of an invoice-type document (invoices-type path segment). | From | To | Value in request body | Notes | | :--- | :--- | :--- | :--- | | draft | final | finalized | All types. | | draft | settled | finalized | Only invoice_receipts. | | draft | deleted | deleted | All types. | | final | canceled | canceled | All types. | | settled | canceled | canceled | Only invoice_receipts. | | final | settled | settled | All types except invoice_receipts and receipts. | | settled | final | unsettled | Only credit_notes and debit_notes. | On receipts (payment receipts) the only transition is canceled; canceling a receipt that is already canceled succeeds without change. The request body wrapper key must be the singular of the path type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, receipt); any other key returns 422 "Invalid root element, expected invoice" (with the expected key name). To cancel, send the reason in message inside the wrapper, e.g. {"invoice": {"state": "canceled", "message": "Document issued by mistake"}}. Without it the API returns 422 "The cancellation reason is a required field". ### Download document PDF - [GET /api/v3/{invoices-type}/{id}/pdf](https://docs.invoicexpress.com/v3/invoices/getv3documentpdf.md): Returns the PDF URL for the specified document or indicates if PDF generation is in progress. ### Get QR Code - [GET /api/v3/{invoices-type}/{id}/qr_code](https://docs.invoicexpress.com/v3/invoices/getv3documentqrcode.md): Returns the QR Code URL for the specified document or indicates if QR Code generation is in progress. ### Get send document configuration - [GET /api/v3/{invoices-type}/{id}/send](https://docs.invoicexpress.com/v3/invoices/getv3documentsendconfig.md): Returns the pre-filled email data for sending a document to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context. ### Send document by email - [POST /api/v3/{invoices-type}/{id}/send](https://docs.invoicexpress.com/v3/invoices/sendv3document.md): Sends the specified document by email to the client. ### List related documents - [GET /api/v3/{invoices-type}/{id}/related_documents](https://docs.invoicexpress.com/v3/invoices/listv3relateddocuments.md): Returns the list of documents related to the specified document. ### Returns timeline activities for a specific document - [GET /api/v3/{invoices-type}/{id}/timeline](https://docs.invoicexpress.com/v3/invoices/getv3documenttimeline.md): Retrieves timeline activities for a specific document including status changes, comments, and other events. ### Unarchive a document - [PUT /api/v3/{invoices-type}/{id}/unarchive](https://docs.invoicexpress.com/v3/invoices/unarchivev3document.md): Unarchives the specified document by setting its archived flag to false and returns the updated document. ### Unarchive a document - [PATCH /api/v3/{invoices-type}/{id}/unarchive](https://docs.invoicexpress.com/v3/invoices/unarchivev3documentpatch.md): Unarchives the specified document by setting its archived flag to false and returns the updated document. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/guides/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/estimates/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ## Guides Create shippings, transports & devolutions and send them to your clients. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/invoices/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/guides/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### List Guides - [GET /api/v3/guides](https://docs.invoicexpress.com/v3/guides/listv3guides.md): Returns a list of all your guides. ### List Guides (POST) - [POST /api/v3/guides](https://docs.invoicexpress.com/v3/guides/listv3guidespost.md): Same as GET /api/v3/guides, with the filters and pagination options sent in a JSON body instead of the query string. Useful when the filters (for example long id or client_id lists) do not fit in a URL. Returns the same response. ### Get Guides Summary - [POST /api/v3/guides/summary](https://docs.invoicexpress.com/v3/guides/getv3guidessummary.md): Returns the totals of the specific documents select ### Create Guide - [POST /api/v3/{guides-type}](https://docs.invoicexpress.com/v3/guides/createv3guide.md): Creates a new guide of the specified type, as a draft. The request body wrapper key must match the path segment: - shipping for shippings - transport for transports - devolution for devolutions loaded_at and at least one item are required. Portuguese accounts must also send address_from and address_to, each with detail, city, postal_code and country. ### Get New Guide Defaults - [GET /api/v3/{guides-type}/new](https://docs.invoicexpress.com/v3/guides/getv3newguide.md): Returns the defaults and choices used to fill in a new guide of the specified type (sequences, currencies, taxes, exemption reasons, due date and retention choices, address countries). Nothing is created. ### Calculate Guide Summary - [POST /api/v3/{guides-type}/calculate_summary](https://docs.invoicexpress.com/v3/guides/calculatev3guidesummary.md): Calculates the financial summary of a guide from its items, retention, global discount, currency and tax exemption, without saving anything. Unlike update_summary, the input is not validated — invalid values are coerced and a missing wrapper gives an all-zero summary — so it always answers 200 unless an unexpected error occurs. ### Update Guide Summary - [POST /api/v3/{guides-type}/update_summary](https://docs.invoicexpress.com/v3/guides/updatev3guidesummary.md): Calculates and returns the financial summary (totals, taxes, discounts, retention) for an guide based on the provided guide data without saving the guide. This endpoint is useful for previewing calculations before creating or updating an guide. ### Get Guide by ID - [GET /api/v3/{guides-type}/{id}](https://docs.invoicexpress.com/v3/guides/getv3guidebyid.md): Retrieves detailed information about a specific document including client data, items, financial summary, and account information ### Update Guide - [PUT /api/v3/{guides-type}/{id}](https://docs.invoicexpress.com/v3/guides/updatev3guide.md): Updates a guide of the specified type. The wrapper key must match the path segment (shipping, transport or devolution). The same rules as on create apply: loaded_at (not in the past) and at least one item are required, and Portuguese accounts must send complete address_from and address_to. The item list replaces the existing items. Guides that are sent, settled, deleted, canceled or second copies can no longer be edited. ### Clone Guide - [GET /api/v3/{guides-type}/{id}/clone](https://docs.invoicexpress.com/v3/guides/clonev3guide.md): Returns a new, unsaved draft guide of the specified type pre-filled from an existing document — nothing is created. The clone gets today's date, loaded_at 5 minutes from now, the account's default sequence for the type and, for Portuguese accounts, copies of the source addresses. Submit it with POST /api/v3/{guides-type} to create it. Unsaved fields such as id are null. ### List guide movements - [GET /api/v3/{guides-type}/{id}/movements](https://docs.invoicexpress.com/v3/guides/listv3guidemovements.md): Returns the payment and reimbursement movements of the specified guide and its related documents. Usually empty for guides. ### Archive a guide document - [PUT /api/v3/{guides-type}/{id}/archive](https://docs.invoicexpress.com/v3/guides/archivev3guidedocument.md): Archives the specified guide document by setting its archived flag to true and returns the updated document. ### Archive a guide document - [PATCH /api/v3/{guides-type}/{id}/archive](https://docs.invoicexpress.com/v3/guides/archivev3guidedocumentpatch.md): Archives the specified guide document by setting its archived flag to true and returns the updated document. ### Creates a comment for a document - [POST /api/v3/{guides-type}/{id}/comments](https://docs.invoicexpress.com/v3/guides/createv3guidedocumentcomment.md): Creates a new comment for the specified document. Comments can only be deleted within 15 minutes of creation. ### Deletes a comment from a document - [DELETE /api/v3/{guides-type}/{id}/comments/{comment_id}](https://docs.invoicexpress.com/v3/guides/deletev3guidedocumentcomment.md): Deletes a comment from the specified document. Comments can only be deleted within 15 minutes of creation and only by the author. ### Change document state - [PUT /api/v3/{guides-type}/{id}/change-state.json](https://docs.invoicexpress.com/v3/guides/changev3guidedocumentstate.md): Changes the state of a guide-type document (guides-type path segment: shippings, transports, or devolutions). | From | To | Value in request body | | :--- | :--- | :--- | | draft | final | finalized | | draft | deleted | deleted | | final | canceled | canceled | To cancel, send the reason in message inside the wrapper, e.g. {"transport": {"state": "canceled", "message": "Goods were not shipped"}}. Without it the API returns 422 "The cancellation reason is a required field". ### Download guide PDF - [GET /api/v3/{guides-type}/{id}/pdf](https://docs.invoicexpress.com/v3/guides/getv3guidepdf.md): Returns the PDF URL for the specified guide or indicates if PDF generation is in progress. ### Get QR Code - [GET /api/v3/{guides-type}/{id}/qr_code](https://docs.invoicexpress.com/v3/guides/getv3guideqrcode.md): Returns the QR Code URL for the specified document. ### Get send document configuration - [GET /api/v3/{guides-type}/{id}/send](https://docs.invoicexpress.com/v3/guides/getv3guidesendconfig.md): Returns the pre-filled email data for sending a guide document to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context. ### Send document by email - [POST /api/v3/{guides-type}/{id}/send](https://docs.invoicexpress.com/v3/guides/sendv3guidedocument.md): Sends the specified guide document by email to the client. ### List related documents - [GET /api/v3/{guides-type}/{id}/related_documents](https://docs.invoicexpress.com/v3/guides/listv3guiderelateddocuments.md): Returns the list of documents related to the specified guide document. ### Returns timeline activities for a specific document - [GET /api/v3/{guides-type}/{id}/timeline](https://docs.invoicexpress.com/v3/guides/getv3guidetimeline.md): Retrieves timeline activities for a specific document including status changes, comments, and other events ### Unarchive a guide document - [PUT /api/v3/{guides-type}/{id}/unarchive](https://docs.invoicexpress.com/v3/guides/unarchivev3guidedocument.md): Unarchives the specified guide document by setting its archived flag to false and returns the updated document. ### Unarchive a guide document - [PATCH /api/v3/{guides-type}/{id}/unarchive](https://docs.invoicexpress.com/v3/guides/unarchivev3guidedocumentpatch.md): Unarchives the specified guide document by setting its archived flag to false and returns the updated document. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/estimates/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ## Estimates Create quotes, proformas and fees notes and send them to your clients. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/invoices/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/guides/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### Create partial payment for document - [POST /api/v3/documents/{document_id}/partial_payments.json](https://docs.invoicexpress.com/v3/estimates/createv3documentpartialpayment.md): Creates a partial payment for a document. This generates a treasury movement and client current account entry. Use the document numeric id (the same id returned for invoice-type and guide-type resources). The .json suffix requests a JSON response body. Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer (kept for 24 hours) instead of registering the payment twice. ### List Estimates - [GET /api/v3/estimates](https://docs.invoicexpress.com/v3/estimates/listv3estimates.md): Returns a list of all your estimates (quotes, proformas and fees notes). ### List Estimates (POST) - [POST /api/v3/estimates](https://docs.invoicexpress.com/v3/estimates/listv3estimatespost.md): Same as GET /api/v3/estimates, with the filters sent as a JSON body instead of the query string (useful for long id / client_id lists). The response is identical. Page size defaults to 10. ### Get Estimates Summary - [POST /api/v3/estimates/summary](https://docs.invoicexpress.com/v3/estimates/getv3estimatessummary.md): Returns the totals of the specific documents selected. ### Create Estimate - [POST /api/v3/{estimate_type}](https://docs.invoicexpress.com/v3/estimates/createv3estimate.md): Creates a new estimate of the specified type. The request body wrapper key must match the path segment: - quote for quotes - proforma for proformas - fees_note for fees_notes ### Update Estimate Summary - [POST /api/v3/{estimate_type}/update_summary](https://docs.invoicexpress.com/v3/estimates/updatev3estimatesummary.md): Calculates and returns the financial summary (totals, taxes, discounts, retention) for an estimate based on the provided data without saving it. The request body wrapper key must be the singular of the path type (quote, proforma, fees_note); any other key returns 422 "No quote element provided" (with the expected key name). ### Calculate Estimate Summary - [POST /api/v3/{estimate_type}/calculate_summary](https://docs.invoicexpress.com/v3/estimates/calculatev3estimatesummary.md): Calculates the totals (sum, discount, taxes, retention, total) for the items sent, without validating or saving anything. Unlike update_summary, invalid input is coerced instead of rejected: a missing or wrongly named wrapper key, or no items, returns an all-zero summary with 200. Only items, retention, global_discount, currency_code, rate and tax_exemption are read; at most 1000 items are processed. The wrapper key is the singular of the path type (quote, proforma, fees_note). ### New Estimate Defaults - [GET /api/v3/{estimate_type}/new](https://docs.invoicexpress.com/v3/estimates/newv3estimate.md): Returns the defaults and choices needed to build a new estimate of the given type (due-date options, exemption reasons, issuable sequences, currencies, retention options, default remarks, taxes). Nothing is created. When client_id is sent, the client's payment days, exemption code, currency and observations take priority over the account's. ### Get Estimate by ID - [GET /api/v3/{estimate_type}/{id}](https://docs.invoicexpress.com/v3/estimates/getv3estimatebyid.md): Retrieves detailed information about a specific estimate document including client data, items, financial summary, and account information. ### Update Estimate - [PUT /api/v3/{estimate_type}/{id}](https://docs.invoicexpress.com/v3/estimates/updatev3estimate.md): Updates an estimate of the given type. The wrapper key must be the singular of the path type (quote, proforma, fees_note). items is required and replaces the whole item set. Documents in state sent, settled, deleted, canceled, accepted, refused or second_copy cannot be edited. ### Clone Estimate - [GET /api/v3/{estimate_type}/{id}/clone](https://docs.invoicexpress.com/v3/estimates/clonev3estimate.md): Returns an unsaved draft copy of the document, as an estimate of the path type, ready to be edited and submitted with the create operation. Nothing is persisted: the returned document has no id. Date is today, due date is today plus the client's (else the account's) payment days, and the exchange rate is refreshed for foreign-currency documents. The sequence is the account's default for the type unless keep_owner_sequence=true. The source id may be any document of the account (not only one of the path type); the copy always takes the path type. ### List estimate movements - [GET /api/v3/{estimate_type}/{id}/movements](https://docs.invoicexpress.com/v3/estimates/listv3estimatemovements.md): Returns the payments and reimbursements recorded against the estimate, its related documents and their receipts (non-canceled treasury movements of the document's client). ### Archive a document - [PUT /api/v3/{estimate_type}/{id}/archive](https://docs.invoicexpress.com/v3/estimates/archivev3estimatedocument.md): Archives the specified estimate document by setting its archived flag to true and returns the updated document. ### Archive a document - [PATCH /api/v3/{estimate_type}/{id}/archive](https://docs.invoicexpress.com/v3/estimates/archivev3estimatedocumentpatch.md): Archives the specified estimate document by setting its archived flag to true and returns the updated document. ### Creates a comment for a document - [POST /api/v3/{estimate_type}/{id}/comments](https://docs.invoicexpress.com/v3/estimates/createv3estimatecomment.md): Creates a new comment for the specified estimate document. Comments can only be deleted within 15 minutes of creation. ### Deletes a comment from a document - [DELETE /api/v3/{estimate_type}/{id}/comments/{comment_id}](https://docs.invoicexpress.com/v3/estimates/deletev3estimatecomment.md): Deletes a comment from the specified estimate document. Comments can only be deleted within 15 minutes of creation and only by the author. ### Download estimate PDF - [GET /api/v3/{estimate_type}/{id}/pdf](https://docs.invoicexpress.com/v3/estimates/getv3estimatepdf.md): Returns the PDF URL for the specified estimate or indicates if PDF generation is in progress. ### Get QR Code - [GET /api/v3/{estimate_type}/{id}/qr_code](https://docs.invoicexpress.com/v3/estimates/getv3estimateqrcode.md): Returns the QR Code URL for the specified estimate or indicates if QR Code generation is in progress. ### Get send document configuration - [GET /api/v3/{estimate_type}/{id}/send](https://docs.invoicexpress.com/v3/estimates/getv3estimatesendconfig.md): Returns the pre-filled email data for sending an estimate to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context. ### Send document by email - [POST /api/v3/{estimate_type}/{id}/send](https://docs.invoicexpress.com/v3/estimates/sendv3estimatedocument.md): Sends the specified estimate by email to the client. ### List related documents - [GET /api/v3/{estimate_type}/{id}/related_documents](https://docs.invoicexpress.com/v3/estimates/listv3estimaterelateddocuments.md): Returns the list of documents related to the specified estimate document. ### Returns timeline activities for a specific document - [GET /api/v3/{estimate_type}/{id}/timeline](https://docs.invoicexpress.com/v3/estimates/getv3estimatetimeline.md): Retrieves timeline activities for a specific estimate document including status changes, comments, and other events. ### Unarchive a document - [PUT /api/v3/{estimate_type}/{id}/unarchive](https://docs.invoicexpress.com/v3/estimates/unarchivev3estimatedocument.md): Unarchives the specified document by setting its archived flag to false and returns the updated document. ### Unarchive a document - [PATCH /api/v3/{estimate_type}/{id}/unarchive](https://docs.invoicexpress.com/v3/estimates/unarchivev3estimatedocumentpatch.md): Unarchives the specified document by setting its archived flag to false and returns the updated document. ### Change estimate state - [PUT /api/v3/{estimate_type}/{id}/change-state.json](https://docs.invoicexpress.com/v3/estimates/changev3estimatedocumentstate.md): Changes the state of an estimate document (estimate_type path segment: quotes, proformas, fees_notes). | From | To | Value in request body | | :--- | :--- | :--- | | draft | sent | finalized | | draft | deleted | deleted | | sent, refused | accepted | accept | | sent, accepted | refused | refuse | | sent, accepted, refused | canceled | canceled | The request body wrapper key must be the singular of the path type (quote, proforma, fees_note); any other key returns 422 "Invalid root element, expected quote" (with the expected key name). To cancel, send the reason in message inside the wrapper, e.g. {"quote": {"state": "canceled", "message": "Client withdrew the request"}}. Without it the API returns 422 "The cancellation reason is a required field". ## Sequences A Sequence is used to group invoices in a sequential order. ### List Sequences - [GET /api/v3/sequences](https://docs.invoicexpress.com/v3/sequences/listv3sequences.md): Returns a paginated list of the sequences (séries) of the current account, 10 per page by default, newest first. Archived séries are included unless archived=false is sent. ### Create Sequence - [POST /api/v3/sequences](https://docs.invoicexpress.com/v3/sequences/createv3sequence.md): Creates a new sequence for the current account. The operation is asynchronous — poll GET /api/v3/sequences/create_status with the returned status_endpoint params to check completion. ### Get Sequences By Name - [GET /api/v3/sequences/by_name](https://docs.invoicexpress.com/v3/sequences/getv3sequencesbyname.md): Returns a list of all sequence names for the account. ### Get Sequence Collection - [GET /api/v3/sequences/collection](https://docs.invoicexpress.com/v3/sequences/getv3sequencecollection.md): Returns the registration collection for a given sequence, showing the registration status per document category. ### Check Sequence Creation Status - [GET /api/v3/sequences/create_status](https://docs.invoicexpress.com/v3/sequences/getv3sequencecreatestatus.md): Checks the creation status of a sequence. Called with the query string returned in status_endpoint from the create and register operations. No API key is needed — the encrypted account_id token identifies the account. Returns 202 while the operation is still running and 200 once it has finished; a failed operation is also answered with 200 and success set to false. ### Set Default Sequence - [PUT /api/v3/sequences/default](https://docs.invoicexpress.com/v3/sequences/setv3defaultsequence.md): Sets the default sequence for the current account. ### Archive Sequence - [PUT /api/v3/sequences/archive](https://docs.invoicexpress.com/v3/sequences/archivev3sequence.md): Archives a série, for every document type at once. An archived série is no longer offered when a new document is prepared, and cannot be made the default. It does not block anything else: existing documents are unaffected, and a document can still be created with it through the API. The default série cannot be archived. ### Unarchive Sequence - [PUT /api/v3/sequences/unarchive](https://docs.invoicexpress.com/v3/sequences/unarchivev3sequence.md): Unarchives a série, for every document type at once, so it is offered again when a new document is prepared. ### Register Sequence - [PUT /api/v3/sequences/register](https://docs.invoicexpress.com/v3/sequences/registerv3sequence.md): Registers a sequence with the tax authority (AT). The operation is asynchronous — poll GET /api/v3/sequences/create_status with the returned status_endpoint params to check completion. ### Get Registered Series - [GET /api/v3/sequences/registered_series](https://docs.invoicexpress.com/v3/sequences/getv3registeredseries.md): Returns a list of registered series names for the account. ## Clients A Client is an entity you send invoices to. ### List Clients - [GET /api/v3/clients](https://docs.invoicexpress.com/v3/clients/listv3clients.md): Returns a paginated list of the clients in the account. Archived clients are included unless status says otherwise. ### Create Client - [POST /api/v3/clients](https://docs.invoicexpress.com/v3/clients/createv3client.md): Creates a new client. ### Get Client Suggestions - [GET /api/v3/clients/suggestions](https://docs.invoicexpress.com/v3/clients/getv3clientsuggestions.md): Returns client suggestions. With client_text, searches the account's clients by that text. Without it, returns the last clients used on documents of the document_tab family (at most 10, most recent first); an empty list when none were recorded. ### Get Client - [GET /api/v3/clients/{id}](https://docs.invoicexpress.com/v3/clients/getv3client.md): Returns a specific client by ID. ### Update Client - [PUT /api/v3/clients/{id}](https://docs.invoicexpress.com/v3/clients/updatev3client.md): Updates an existing client. Partial update — only the keys sent inside client are changed. ### Delete Client - [DELETE /api/v3/clients/{id}](https://docs.invoicexpress.com/v3/clients/deletev3client.md): Deletes a client. ### Archive Client - [PUT /api/v3/clients/{id}/archive](https://docs.invoicexpress.com/v3/clients/archivev3client.md): Archives a client. Archiving hides the client from GET /api/v3/clients?status=active and nothing else: the client can still be read and updated, documents created through the API can still use it, and it still counts when another client is created with the same name or code. Use it for clients that cannot be deleted (can_be_deleted is false), but any client can be archived. No request body. Archiving an archived client succeeds and keeps the original archived_at. ### Unarchive Client - [PUT /api/v3/clients/{id}/unarchive](https://docs.invoicexpress.com/v3/clients/unarchivev3client.md): Unarchives a client, so it is listed again with status=active. No request body. Unarchiving a client that is not archived succeeds and changes nothing. ### Get Client Balance - [GET /api/v3/clients/{id}/balance](https://docs.invoicexpress.com/v3/clients/getv3clientbalance.md): Returns the current account balance for a client. ### Update Client Initial Balance - [PUT /api/v3/clients/{id}/initial_balance](https://docs.invoicexpress.com/v3/clients/updatev3clientinitialbalance.md): Updates the initial balance for a client. ### List Client Regularizations - [GET /api/v3/clients/{client_id}/regularization](https://docs.invoicexpress.com/v3/clients/listv3clientregularizations.md): Returns the client's regularizations, paginated. ### Create Client Regularization - [POST /api/v3/clients/{client_id}/regularization](https://docs.invoicexpress.com/v3/clients/createv3clientregularization.md): Creates a new regularization for a client. ### Delete Client Regularization - [DELETE /api/v3/clients/{client_id}/regularization/{id}](https://docs.invoicexpress.com/v3/clients/deletev3clientregularization.md): Cancels one or more of the client's regularizations. This is a soft cancel (the movements are marked as canceled, not removed). Ids that are not regularizations of this client are skipped. ### Send Open Account Link Mail - [POST /api/v3/clients/{id}/send_open_account_link_mail](https://docs.invoicexpress.com/v3/clients/sendv3clientopenaccountlinkmail.md): Sends an open account link email to a chosen client. ### Create Treasury Movement - [POST /api/v3/clients/{client_id}/treasury_movements](https://docs.invoicexpress.com/v3/clients/createv3clienttreasurymovement.md): Creates a new treasury movement for a client. A Payment settles the client's open documents up to value and issues a receipt for each. A Reimbursement is spread over the client's settled documents (or only document_id when sent). Send an Idempotency-Key header to make retries safe: a repeated request with the same key and payload replays the first answer instead of creating a second movement. ### Delete Treasury Movement - [DELETE /api/v3/clients/{client_id}/treasury_movements/{id}](https://docs.invoicexpress.com/v3/clients/deletev3clienttreasurymovement.md): Cancels a treasury movement of the client (soft cancel; the movement is marked as canceled, not removed). When the movement has child movements, every child is canceled too. ## Accounts Manage your InvoiceXpress account settings, users, AT communication, and billing. ### Get Account - [GET /api/v3/accounts](https://docs.invoicexpress.com/v3/accounts/getv3account.md): Returns the current account details. ### Create Account - [POST /api/v3/accounts](https://docs.invoicexpress.com/v3/accounts/createv3account.md): Creates a new InvoiceXpress account. The response shape depends on whether it is an API or a web request (see the response schema). ### Update Account - [PUT /api/v3/accounts](https://docs.invoicexpress.com/v3/accounts/updatev3account.md): Updates the current account details. Only the fields sent inside account are changed. ### Get Years with Documents - [GET /api/v3/accounts/years_documents](https://docs.invoicexpress.com/v3/accounts/getv3accountyearsdocuments.md): Returns an array of years that have documents. ### Export Account Data - [POST /api/v3/accounts/export](https://docs.invoicexpress.com/v3/accounts/exportv3accountdata.md): Exports account data in XLS, CSV, or XML format. An email will be sent when the export is ready. Both data_type and data_format are required; account can only be exported as xml. ### Get Billing History - [GET /api/v3/accounts/billing_history](https://docs.invoicexpress.com/v3/accounts/getv3accountbillinghistory.md): Returns InvoiceXpress billing history for the account. ### Create Account for Existing User - [POST /api/v3/accounts/create_already_user](https://docs.invoicexpress.com/v3/accounts/createv3accountalreadyuser.md): Creates a new account for an existing InvoiceXpress user, authenticated by the email and password in the body. The response shape depends on whether it is an API or a web request (see the response schema). ### Get Account Settings - [GET /api/v3/accounts/settings](https://docs.invoicexpress.com/v3/accounts/getv3accountsettings.md): Returns the account configuration settings for one documents tab, chosen with the required documents_tab query parameter. ### List Account Users - [GET /api/v3/accounts/users](https://docs.invoicexpress.com/v3/accounts/listv3accountusers.md): Returns the account's users, paginated. ### Create or Add Account User - [POST /api/v3/accounts/users](https://docs.invoicexpress.com/v3/accounts/createv3accountuser.md): Creates a new user or adds an existing user to the account. user.role is optional; a missing or unknown role gives the user the contributor role. ### Update Account User - [PUT /api/v3/accounts/users/{id}](https://docs.invoicexpress.com/v3/accounts/updatev3accountuser.md): Updates a user's role on the account. ### Remove Account User - [DELETE /api/v3/accounts/users/{id}](https://docs.invoicexpress.com/v3/accounts/deletev3accountuser.md): Removes one or more users from the account. Ids that are not users of this account are skipped. ### Get Document Customization - [GET /api/v3/accounts/document_customization](https://docs.invoicexpress.com/v3/accounts/getv3documentcustomization.md): Returns the document customization of the account, or of one série with serie_name. ### Update Document Customization - [PUT /api/v3/accounts/document_customization](https://docs.invoicexpress.com/v3/accounts/updatev3documentcustomization.md): Replaces the document customization of the account (or of one série, with serie_name). This is a full replace: every customization field that is not sent (or is sent blank) is set to null. Send all the values you want to keep, not only the ones you change. See the request body for the list of fields. ### Remove Logo - [DELETE /api/v3/accounts/document_customization](https://docs.invoicexpress.com/v3/accounts/deletev3accountlogo.md): Removes the account logo, or, with serie_name, the logo of that série only. Always answers 200: {"success": true}, also when there was no logo to remove. After an internal failure it still answers 200, but the body is not {"success": true}. ## Account Credentials Manage AT communication credentials for your account. ### Get AT Active Communication - [GET /api/v3/accounts/at_active_communication](https://docs.invoicexpress.com/v3/account-credentials/getv3accountatactivecommunication.md): Retrieves whether the account has AT communication enabled and the current credentials status. ### Save AT Communication Settings - [POST /api/v3/accounts/at_communication](https://docs.invoicexpress.com/v3/account-credentials/savev3accountatcommunication.md): Saves the AT subuser, AT password, and communication type for an account. ### Get AT Communication History - [GET /api/v3/accounts/at_communication_history](https://docs.invoicexpress.com/v3/account-credentials/getv3accountatcommunicationhistory.md): Returns the AT communication history for the account. ### Create AT Communication Details - [POST /api/v3/account_credentials](https://docs.invoicexpress.com/v3/account-credentials/createv3accountcredentials.md): Creates AT communication details for an account. The credentials are checked against the AT before they are stored. ### Update AT Communication Details - [PUT /api/v3/account_credentials](https://docs.invoicexpress.com/v3/account-credentials/updatev3accountcredentials.md): Updates the AT communication details stored for the given context and type. username and password are always required here, and are checked against the AT before they are stored. ## Collection Alerts Configure automated payment collection alerts sent to clients. ### Create Collection Alert - [POST /api/v3/collection_alerts](https://docs.invoicexpress.com/v3/collection-alerts/createv3collectionalert.md): Creates the collection alert configuration of the account, or of a client when client_id is sent. At account level, replicate=true deletes every client-level configuration. ### Update Collection Alert - [PUT /api/v3/collection_alerts](https://docs.invoicexpress.com/v3/collection-alerts/updatev3collectionalert.md): Updates the existing collection alert configuration of the account, or of a client when client_id is sent. - Account level, replicate=true: every client-level configuration is deleted, so all clients follow the account configuration. - Client level, replicate=true: the client's own configuration is deleted (the client falls back to the account configuration), the other fields are ignored, and the response is {"collection_alert": {"client_has_email": true|false}}. ### Get Collection Alert - [GET /api/v3/collection_alerts](https://docs.invoicexpress.com/v3/collection-alerts/getv3collectionalert.md): Returns the collection alert configuration for an account or client. ## 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. ### Get Current Batch Invoice Job - [GET /api/v3/imports/invoices](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoicejob.md): Returns the most recent non-expired batch invoice metadata. Returns 204 if no active batch exists. ### Start Batch Invoice Creation - [POST /api/v3/imports/invoices](https://docs.invoicexpress.com/v3/batch-invoices/createv3batchinvoices.md): Enqueues a background job to create invoices from validated batch previews. Requires an active batch in "validated" status. ### Delete Active Batch Invoice Job - [DELETE /api/v3/imports/invoices](https://docs.invoicexpress.com/v3/batch-invoices/deletev3batchinvoicejob.md): Destroys the currently active batch invoice job and associated S3 files. ### Get Batch Invoice CSV Template - [GET /api/v3/imports/invoices/template](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoicetemplate.md): Returns a presigned S3 URL to download the batch invoice CSV template. Language matches the account language (en, es, pt). ### Get Batch Invoice Configuration Options - [GET /api/v3/imports/invoices/configure_options](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoiceconfigureoptions.md): Returns data for populating the configure step dropdowns (sequences, exemption reasons). Only series registered with the AT are listed. ### Upload CSV for Batch Invoice Import - [POST /api/v3/imports/invoices/upload](https://docs.invoicexpress.com/v3/batch-invoices/uploadv3batchinvoicecsv.md): Validates the CSV file and uploads it to S3. Creates a new batch metadata record. ### Process Uploaded CSV (Batch Invoice Mapping) - [POST /api/v3/imports/invoices/process](https://docs.invoicexpress.com/v3/batch-invoices/processv3batchinvoicecsv.md): After uploading, call this with separator and header info to build the column mapping. ### Get CSV Column Mapping - [GET /api/v3/imports/invoices/mapping](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoicemapping.md): Returns the CSV column-to-field mapping for the active batch invoice job. ### Save CSV Column Mapping - [PUT /api/v3/imports/invoices/mapping](https://docs.invoicexpress.com/v3/batch-invoices/savev3batchinvoicemapping.md): Saves the user-selected column-to-field mapping for the active batch invoice job. ### Configure Batch Invoice Job - [PUT /api/v3/imports/invoices/configure](https://docs.invoicexpress.com/v3/batch-invoices/configurev3batchinvoicejob.md): Updates the active batch invoice job with configuration options (name, document type, sequence, etc.) and transitions status to "configured". ### Start Batch Invoice CSV Validation - [POST /api/v3/imports/invoices/validate](https://docs.invoicexpress.com/v3/batch-invoices/validatev3batchinvoices.md): Enqueues a background job to validate the CSV rows. Requires batch in "configured" status. Poll GET /api/v3/imports/invoices/validation for results. ### Get Batch Invoice Validation Status - [GET /api/v3/imports/invoices/validation](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoicevalidation.md): Poll this after POST /api/v3/imports/invoices/validate to get validation status and result. ### Check Document Quota - [GET /api/v3/imports/invoices/available_docs](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoiceavailabledocs.md): Returns whether the account has enough document quota to create invoices from validated previews. Use before POST /api/v3/imports/invoices. ### Get Batch Invoice Creation Status - [GET /api/v3/imports/invoices/status](https://docs.invoicexpress.com/v3/batch-invoices/getv3batchinvoicestatus.md): Poll after POST /api/v3/imports/invoices to check invoice creation progress. Status values — processing (202), sending_email (202), completed (200), failed / exception_occurred / interrupted (422), stuck/unknown (500). Every body carries a success boolean. ## 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. ### Get Current Batch Product Import Job - [GET /api/v3/imports/products](https://docs.invoicexpress.com/v3/batch-products/getv3batchproductjob.md): Returns the most recent non-expired batch product import metadata. Returns 204 if no active batch exists. ### Start Batch Product Import - [POST /api/v3/imports/products](https://docs.invoicexpress.com/v3/batch-products/createv3batchproducts.md): Enqueues a background job to create products from validated batch previews. Poll GET /api/v3/imports/products/status for completion. ### Delete Active Batch Product Import Job - [DELETE /api/v3/imports/products](https://docs.invoicexpress.com/v3/batch-products/deletev3batchproductjob.md): Destroys the currently active batch product import and associated S3 files. ### Get Batch Product CSV Template - [GET /api/v3/imports/products/template](https://docs.invoicexpress.com/v3/batch-products/getv3batchproducttemplate.md): Returns a presigned S3 URL to download the batch product CSV template. ### Get Batch Product Import Status - [GET /api/v3/imports/products/status](https://docs.invoicexpress.com/v3/batch-products/getv3batchproductstatus.md): Returns the current status of the batch product import job. Poll after POST /api/v3/imports/products. ### Upload CSV for Batch Product Import - [POST /api/v3/imports/products/upload](https://docs.invoicexpress.com/v3/batch-products/uploadv3batchproductcsv.md): Validates the CSV file and uploads it to S3. Creates a new batch metadata record with import type products. ### Process Uploaded CSV (Batch Product Mapping) - [POST /api/v3/imports/products/process](https://docs.invoicexpress.com/v3/batch-products/processv3batchproductcsv.md): After uploading, call this with separator and header info to build the product field mapping. ### Get CSV Column Mapping for Product Import - [GET /api/v3/imports/products/mapping](https://docs.invoicexpress.com/v3/batch-products/getv3batchproductmapping.md): Returns the CSV column-to-field mapping for the active batch product import. ### Save CSV Column Mapping for Product Import - [PUT /api/v3/imports/products/mapping](https://docs.invoicexpress.com/v3/batch-products/savev3batchproductmapping.md): Saves the user-selected column-to-field mapping for the active batch product import. ### Start Batch Product CSV Validation - [POST /api/v3/imports/products/validate](https://docs.invoicexpress.com/v3/batch-products/validatev3batchproducts.md): Enqueues a background job to validate the CSV rows. Requires batch in "mapping" status. Poll GET /api/v3/imports/products/validation for results. ### Get Batch Product Validation Status - [GET /api/v3/imports/products/validation](https://docs.invoicexpress.com/v3/batch-products/getv3batchproductvalidation.md): Poll after POST /api/v3/imports/products/validate to get validation status and result. ## 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. ### Get Current Batch Client Import Job - [GET /api/v3/imports/clients](https://docs.invoicexpress.com/v3/batch-clients/getv3batchclientjob.md): Returns the most recent non-expired batch client import metadata. Returns 204 if no active batch exists. ### Start Batch Client Import - [POST /api/v3/imports/clients](https://docs.invoicexpress.com/v3/batch-clients/createv3batchclients.md): Enqueues a background job to create clients from validated batch previews. Poll GET /api/v3/imports/clients/status for completion. ### Delete Active Batch Client Import Job - [DELETE /api/v3/imports/clients](https://docs.invoicexpress.com/v3/batch-clients/deletev3batchclientjob.md): Destroys the currently active batch client import and associated S3 files. ### Get Batch Client Import Status - [GET /api/v3/imports/clients/status](https://docs.invoicexpress.com/v3/batch-clients/getv3batchclientstatus.md): Returns the current status of the batch client import job. Poll after POST /api/v3/imports/clients. ### Get Batch Client CSV Template - [GET /api/v3/imports/clients/template](https://docs.invoicexpress.com/v3/batch-clients/getv3batchclienttemplate.md): Returns a presigned S3 URL to download the batch client CSV template. Required column: name. All other columns (including fiscal_id) are optional. ### Upload CSV for Batch Client Import - [POST /api/v3/imports/clients/upload](https://docs.invoicexpress.com/v3/batch-clients/uploadv3batchclientcsv.md): Validates the CSV file and uploads it to S3. Creates a new batch metadata record with import type clients. ### Process Uploaded CSV (Batch Client Mapping) - [POST /api/v3/imports/clients/process](https://docs.invoicexpress.com/v3/batch-clients/processv3batchclientcsv.md): After uploading, call this with separator and header info to build the client field mapping. ### Get CSV Column Mapping for Client Import - [GET /api/v3/imports/clients/mapping](https://docs.invoicexpress.com/v3/batch-clients/getv3batchclientmapping.md): Returns the CSV column-to-field mapping for the active batch client import. ### Save CSV Column Mapping for Client Import - [PUT /api/v3/imports/clients/mapping](https://docs.invoicexpress.com/v3/batch-clients/savev3batchclientmapping.md): Saves the user-selected column-to-field mapping for the active batch client import. ### Start Batch Client CSV Validation - [POST /api/v3/imports/clients/validate](https://docs.invoicexpress.com/v3/batch-clients/validatev3batchclients.md): Enqueues a background job to validate the CSV rows. Requires batch in "mapping" status. Poll GET /api/v3/imports/clients/validation for results. ### Get Batch Client Validation Status - [GET /api/v3/imports/clients/validation](https://docs.invoicexpress.com/v3/batch-clients/getv3batchclientvalidation.md): Poll after POST /api/v3/imports/clients/validate to get validation status and result. ## Items An Item is the product or service you invoice. ### List Items - [GET /api/v3/items](https://docs.invoicexpress.com/v3/items/listv3items.md): Returns a paginated list of all items (products/services) in the account. ### Create Item - [POST /api/v3/items](https://docs.invoicexpress.com/v3/items/createv3item.md): Creates a new item (product or service). When omitted, unit defaults to service, the tax defaults to the account's default tax and rrp is computed from unit_price and the tax. ### Get Item - [GET /api/v3/items/{id}](https://docs.invoicexpress.com/v3/items/getv3item.md): Returns a specific item with detailed sales statistics. ### Update Item - [PUT /api/v3/items/{id}](https://docs.invoicexpress.com/v3/items/updatev3item.md): Updates an existing item. Partial update — only the keys sent inside item are changed, except retention, which is reset to 0 when omitted. An unknown tax.name is ignored (the current tax is kept). ### Delete Item - [DELETE /api/v3/items/{id}](https://docs.invoicexpress.com/v3/items/deletev3item.md): Deletes one or more items. This is a soft delete (the items are marked as deleted, not removed). Ids that are not undeleted items of the account are skipped. ## Schedules Create and manage recurring document schedules. ### List Schedules - [GET /api/v3/schedules](https://docs.invoicexpress.com/v3/schedules/listv3schedules.md): Returns a paginated list of all recurring document schedules for the account. ### Create Schedule - [POST /api/v3/schedules](https://docs.invoicexpress.com/v3/schedules/createv3schedule.md): Creates a new recurring document schedule. start_date must be tomorrow or later, so no back invoices are produced on create. ### Get Schedule - [GET /api/v3/schedules/{id}](https://docs.invoicexpress.com/v3/schedules/getv3schedule.md): Returns a specific schedule with its template. ### Update Schedule - [PUT /api/v3/schedules/{id}](https://docs.invoicexpress.com/v3/schedules/updatev3schedule.md): Updates an existing schedule. This is not a partial update; resend the full schedule, including template with its client and items. A missing template or items answers 422 (No template element provided, No items element provided). No client element provided (422) is returned only when client is sent without an id, name or code, not when it is missing. ### Archive Schedule - [DELETE /api/v3/schedules/{id}](https://docs.invoicexpress.com/v3/schedules/archivev3schedule.md): Archives (soft-deletes) a schedule in the account. ### Get Schedule Timeline - [GET /api/v3/schedules/{id}/timeline](https://docs.invoicexpress.com/v3/schedules/getv3scheduletimeline.md): Retrieves the timeline activities of a specific schedule (creation, updates, status changes). Schedules have no comments, so none are included. ### Toggle Schedule Active State - [PUT /api/v3/schedules/{id}/toggle](https://docs.invoicexpress.com/v3/schedules/togglev3schedule.md): Activates or deactivates a schedule. ## Taxes Manage tax rates for your account. ### List Taxes - [GET /api/v3/taxes](https://docs.invoicexpress.com/v3/taxes/listv3taxes.md): Returns a list of all tax rates for the account. ### Create Tax - [POST /api/v3/taxes](https://docs.invoicexpress.com/v3/taxes/createv3tax.md): Creates a new tax rate. ### Update Tax - [PUT /api/v3/taxes/{id}](https://docs.invoicexpress.com/v3/taxes/updatev3tax.md): Updates an existing tax rate. ### Delete Tax - [DELETE /api/v3/taxes/{id}](https://docs.invoicexpress.com/v3/taxes/deletev3tax.md): Soft delete. The tax stops being listed and can no longer be used on new documents, but the row is kept so documents already issued with it still resolve its region and code (SAF-T). From then on the tax answers 404, and its name can be reused for a new tax. If it was the account's default tax, another tax becomes the default. ## Current User Manage the currently authenticated user's own profile, API key, linked accounts, and password recovery. ### Get User - [GET /api/v3/users/{id}](https://docs.invoicexpress.com/v3/current-user/getv3user.md): Returns the current user. id must be the id of the caller. ### Update User - [PUT /api/v3/users/{id}](https://docs.invoicexpress.com/v3/current-user/updatev3user.md): Updates the current account user's profile. The email (and login) cannot be changed here. user.email / user.login may be sent only with the current value; a different value rejects the whole request with 422. Email changes go through POST /api/v3/users/{id}/email_change. user.name is saved as first_name. To change the password, send actual_password (current password), password and password_confirmation. ### Get User Api Key - [GET /api/v3/users/{id}/api_key](https://docs.invoicexpress.com/v3/current-user/getv3userapikey.md): Returns the caller's API key for the current account. id must be the id of the caller. ### Create User Api Key - [POST /api/v3/users/{id}/api_key](https://docs.invoicexpress.com/v3/current-user/createv3userapikey.md): Generates a new API key for the caller on the current account. Warning: this regenerates the key. If the caller already has an API key, it is replaced and the old one stops working immediately, including the key used to make this request. The id path parameter is ignored: the call always acts on the caller. ### Delete User Api Key - [DELETE /api/v3/users/{id}/api_key](https://docs.invoicexpress.com/v3/current-user/deletev3userapikey.md): Removes the caller's API key on the current account, which disables API access for the caller on that account (including the key used to make this request) until a new key is created. The id path parameter is ignored: the call always acts on the caller. ### Get User Accounts - [GET /api/v3/users/{id}/accounts](https://docs.invoicexpress.com/v3/current-user/listv3useraccounts.md): Returns the list of accounts the caller has access to. The id path parameter is ignored; the call always acts on the caller. ### Recover Password - [POST /api/v3/users/recover_password](https://docs.invoicexpress.com/v3/current-user/recoverv3userpassword.md): Sends a password reset link to the given user's email address. No authentication. Messages are in the language given by language (pt, en or es), Portuguese by default; the examples below are in English. ### Reset Password - [POST /api/v3/users/reset_password](https://docs.invoicexpress.com/v3/current-user/resetv3userpassword.md): Resets a user's password using the reset code sent by the recover password endpoint. No authentication. Messages are in the language given by language (pt, en or es); otherwise in the language of the user's account, or Portuguese. The examples below are in English. ## Currencies List supported currencies and look up exchange rates between them. ### List Currencies - [GET /api/v3/currencies](https://docs.invoicexpress.com/v3/currencies/listv3currencies.md): Returns a list of all currencies. ### Get Exchange Rate - [GET /api/v3/currencies/rate/{from}/{to}](https://docs.invoicexpress.com/v3/currencies/getv3currencyrate.md): Retrieves the current exchange rate between two currencies, including provider information. If the exchange rate cannot be fetched (unknown code, or a code not in upper case), the response is still HTTP 200, with success set to false and no other field. ## Dashboard Retrieve dashboard KPIs and analytics about your clients and invoicing activity. ### Get Active Clients - [GET /api/v3/dashboard/active_clients](https://docs.invoicexpress.com/v3/dashboard/getv3dashboardactiveclients.md): Returns recurring and new clients per month for the last 12 months. ### Get Clients KPI - [GET /api/v3/dashboard/clients_kpi](https://docs.invoicexpress.com/v3/dashboard/getv3dashboardclientskpi.md): Returns KPI metrics for clients over the last 12 months. ### Get Clients Dependency - [GET /api/v3/dashboard/clients_dependency](https://docs.invoicexpress.com/v3/dashboard/getv3dashboardclientsdependency.md): Returns the revenue share segments per client for the account. ### Get Daily Invoicing - [GET /api/v3/dashboard/daily_invoicing](https://docs.invoicexpress.com/v3/dashboard/getv3dashboarddailyinvoicing.md): Returns the daily invoicing totals for the account within an optional date range. Both dates default to the current month. A date that cannot be parsed is not an error; it silently falls back to its default. ## Favorites Save and reuse custom filter presets for documents and other list views. ### Create Favorite - [POST /api/v3/favorites](https://docs.invoicexpress.com/v3/favorites/createv3favorite.md): Creates a new favorite filter set for a user on a given tab. ### Get Favorite - [GET /api/v3/favorites/{uid}](https://docs.invoicexpress.com/v3/favorites/getv3favorite.md): Returns the filters of a specific favorite by uid. ### Rename Favorite - [PUT /api/v3/favorites/{uid}](https://docs.invoicexpress.com/v3/favorites/updatev3favorite.md): Renames an existing custom favorite and/or replaces its filters (favorite.filters). ### Delete Favorite - [DELETE /api/v3/favorites/{uid}](https://docs.invoicexpress.com/v3/favorites/deletev3favorite.md): Deletes a custom favorite. ### List All Favorites - [GET /api/v3/favorites/all](https://docs.invoicexpress.com/v3/favorites/listv3allfavorites.md): Returns a list of all user-created favorites for a given tab. ### List Default Favorites - [GET /api/v3/favorites/default](https://docs.invoicexpress.com/v3/favorites/listv3defaultfavorites.md): Returns a list of all default (system) favorites for a given tab. ## Payment Services Configure and manage the payment service integration used to collect payments for your invoices. ### List Payment Services - [GET /api/v3/payment_services](https://docs.invoicexpress.com/v3/payment-services/listv3paymentservices.md): Returns all available payment services along with the one currently configured for the account, if any. ### Create Payment Service - [POST /api/v3/payment_services](https://docs.invoicexpress.com/v3/payment-services/createv3paymentservice.md): Registers a payment service for the account. ### Update Payment Service - [PUT /api/v3/payment_services/{id}](https://docs.invoicexpress.com/v3/payment-services/updatev3paymentservice.md): Updates the configuration of an existing payment service. ### Delete Payment Service - [DELETE /api/v3/payment_services/{id}](https://docs.invoicexpress.com/v3/payment-services/deletev3paymentservice.md): Removes the payment service configuration from the account. ### List Payment Service References - [GET /api/v3/payment_services/references](https://docs.invoicexpress.com/v3/payment-services/listv3paymentservicereferences.md): Returns a paginated list of payment references (e.g. Multibanco) generated through the account's configured payment service. ## Phone Calling Codes List all phone country calling codes. ### List Phone Calling Codes - [GET /api/v3/phone_calling_codes](https://docs.invoicexpress.com/v3/phone-calling-codes/listv3phonecallingcodes.md): Returns a list of all phone country calling codes. This endpoint is public — no API key is needed. When an api_key is sent, the account language is used as the default response language. ## Reports Reporting endpoints — currently covers the balance-per-client report, its summary, and XLSX export. ### Get Balance Per Client Report - [GET /api/v3/reports/balance_per_client](https://docs.invoicexpress.com/v3/reports/getv3reportbalanceperclient.md): Returns a paginated list of balances per client, with optional date-range, client, and tax filtering. ### Export Balance Per Client Report - [GET /api/v3/reports/balance_per_client/export](https://docs.invoicexpress.com/v3/reports/exportv3reportbalanceperclient.md): Exports the full balance per client report as an XLSX file, using the same filters as the report endpoint. Results are not paginated — all matching rows are included. Generates the file, uploads it to S3, and returns a presigned download URL valid for about 7 days (X-Amz-Expires=597600). ### Get Balance Per Client Report Summary - [GET /api/v3/reports/balance_per_client/summary](https://docs.invoicexpress.com/v3/reports/getv3reportbalanceperclientsummary.md): Returns the aggregate summary of balances per client, using the same filters as the report endpoint. ## SAF-T Generate the SAF-T (Standard Audit File for Tax) export for your account. ### Generate SAF-T File - [GET /api/v3/saft/export.json](https://docs.invoicexpress.com/v3/saf-t/getv3saftexport.md): Generates the SAF-T file for a specific period. The operation is asynchronous — the first response returns 202 while the file is being generated; keep requesting until you receive 200 with the download URL. If there are no documents to export in the selected period, returns 200 with a message instead of a url. ## Tax Countries List all tax countries. ### List Tax Countries - [GET /api/v3/tax_countries](https://docs.invoicexpress.com/v3/tax-countries/listv3taxcountries.md): Returns a list of all tax countries. ## Digital signatures Allows opt-in for available digital signature providers, manage its credentials, and sign invoices. ### List Digital Signature Providers - [GET /api/v3/digital_signatures/providers](https://docs.invoicexpress.com/v3/digital-signatures/getv3digitalsignatureproviders.md): Gets the list of all available digital signature providers. ### Get Account Digital Signature Provider - [GET /api/v3/digital_signatures/accounts/providers](https://docs.invoicexpress.com/v3/digital-signatures/getv3digitalsignatureaccountprovider.md): Gets the customer's active digital signature provider. The body is the account provider object at the top level (no wrapper). ### Set Account Digital Signature Provider - [POST /api/v3/digital_signatures/accounts/providers](https://docs.invoicexpress.com/v3/digital-signatures/createv3digitalsignatureaccountprovider.md): Sets the customer's digital signature provider. ### Update Account Digital Signature Provider - [PUT /api/v3/digital_signatures/accounts/providers](https://docs.invoicexpress.com/v3/digital-signatures/updatev3digitalsignatureaccountprovider.md): Updates the active customer's digital signature provider. ### Remove Account Digital Signature Provider - [DELETE /api/v3/digital_signatures/accounts/providers](https://docs.invoicexpress.com/v3/digital-signatures/deletev3digitalsignatureaccountprovider.md): Removes the account's digital signature provider and its credentials. Idempotent; answers 204 also when no provider is configured. ### Get Digital Signature Provider Credentials - [GET /api/v3/digital_signatures/accounts/credentials](https://docs.invoicexpress.com/v3/digital-signatures/getv3digitalsignaturecredentials.md): Gets the customer's digital signature provider credentials. The secret is never returned in clear. ### Set Digital Signature Provider Credentials - [POST /api/v3/digital_signatures/accounts/credentials](https://docs.invoicexpress.com/v3/digital-signatures/createv3digitalsignaturecredentials.md): 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). ### Update Digital Signature Provider Credentials - [PUT /api/v3/digital_signatures/accounts/credentials](https://docs.invoicexpress.com/v3/digital-signatures/updatev3digitalsignaturecredentials.md): 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). ### Patch Digital Signature Provider Credentials - [PATCH /api/v3/digital_signatures/accounts/credentials](https://docs.invoicexpress.com/v3/digital-signatures/patchv3digitalsignaturecredentials.md): 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). ### Remove Digital Signature Provider Credentials - [DELETE /api/v3/digital_signatures/accounts/credentials](https://docs.invoicexpress.com/v3/digital-signatures/deletev3digitalsignaturecredentials.md): Removes the customer's digital signature provider credentials. ### Get Digital Signature Info - [GET /api/v3/digital_signature/info](https://docs.invoicexpress.com/v3/digital-signatures/getv3digitalsignatureinfo.md): 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". ### Get Document Digital Signature Status - [GET /api/v3/digital_signatures/document/{document_id}/status](https://docs.invoicexpress.com/v3/digital-signatures/getv3digitalsignaturedocumentstatus.md): Returns the digital signature status information for a specific document, including whether it is signed and whether it should be signed. ### Sign Document - [PUT /api/v3/digital_signatures/document/{id}/sign](https://docs.invoicexpress.com/v3/digital-signatures/signv3digitalsignaturedocument.md): 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. ## 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. ### Download CIUS-PT File - [GET /api/v1/edi/{id}/cius-pt](https://docs.invoicexpress.com/v3/edi/getv3documentciuspt.md): Generates and downloads the CIUS-PT (electronic invoice) file for a document. The operation is asynchronous: while the file is being generated the response body is {"generating": true}; keep polling until the body contains key and url. Both cases return HTTP 200 — unlike the SAF-T export and the PDF and QR code endpoints, this endpoint does not return 202 while generating. The only difference is which fields are present in the body. Note that this endpoint takes a bare document id with no document-type segment, so any document in the account can be addressed. Only Invoice, InvoiceReceipt, SimplifiedInvoice, DebitNote and CreditNote documents are eligible — VAT MOSS invoices are not, and return 406. Draft documents also return 406. ### Get CIUS Additional Fields - [GET /api/v1/edi/{id}/additional_fields](https://docs.invoicexpress.com/v3/edi/getv3documentciusadditionalfields.md): Returns the CIUS/EDI additional fields (order and delivery references, accounting cost, delivery date) associated with a document. Every field is always present in the response; each one is null when no additional fields have been stored for the document yet. ### Create or Update CIUS Additional Fields - [POST /api/v1/edi/{id}/additional_fields](https://docs.invoicexpress.com/v3/edi/createv3documentciusadditionalfields.md): Creates the document's CIUS/EDI additional fields, or updates them if they already exist — the same endpoint serves both cases. Returns 201 when the record is created and 200 when an existing record is updated. Fields omitted from the payload keep their stored value, so this is a partial update rather than a replace. ## 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. ### 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). | 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 | ### 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 - [GET /api/v3/accounts/social_security](https://docs.invoicexpress.com/v3/social-security/getv3socialsecurity.md): 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. ### Create Social Security Settings - [POST /api/v3/accounts/social_security](https://docs.invoicexpress.com/v3/social-security/createv3socialsecurity.md): 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. ### Update Social Security Settings - [PUT /api/v3/accounts/social_security](https://docs.invoicexpress.com/v3/social-security/updatev3socialsecurity.md): 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. ### Delete Social Security Settings - [DELETE /api/v3/accounts/social_security](https://docs.invoicexpress.com/v3/social-security/deletev3socialsecurity.md): 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. ### Create Social Security Report - [POST /api/v3/accounts/social_security_reports](https://docs.invoicexpress.com/v3/social-security/createv3socialsecurityreport.md): 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. ### Get Social Security Report - [GET /api/v3/accounts/social_security_reports/{year}/{quarter}](https://docs.invoicexpress.com/v3/social-security/getv3socialsecurityreport.md): 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. ### Update Social Security Report - [PUT /api/v3/accounts/social_security_reports/{year}/{quarter}](https://docs.invoicexpress.com/v3/social-security/updatev3socialsecurityreport.md): 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. ### Get Social Security Quarterly Declaration - [GET /services/v1/social_security/quarterly_declaration](https://docs.invoicexpress.com/v3/social-security/getv3socialsecurityquarterlydeclaration.md): 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. ### List Social Security Quarterly Declarations - [GET /services/v1/social_security/quarterly_declarations](https://docs.invoicexpress.com/v3/social-security/listv3socialsecurityquarterlydeclarations.md): 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.