# 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. ## 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.