# Get Social Security Quarterly Declaration 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. Endpoint: GET /services/v1/social_security/quarterly_declaration Version: 3.1.0 Security: apiKeyAuth ## Query parameters: - `year` (integer) Year of the quarter, read as an integer like Ruby to_i (2026abc and 2_026 are 2026; abc is 0). If it is missing or not positive, or quarter is missing or not 1 to 4, both parameters fall back to the last completed quarter (200). Supported range: 1583 to 9999, except year=9999&quarter=4 (500). Outside it, results are not guaranteed and may answer 500. An array or hash (year[]=1) answers 500. Example: 2026 - `quarter` (integer) Quarter, 1 to 4, read as an integer like Ruby to_i (a single underscore between digits is accepted). If it is missing or any other value, both parameters fall back to the last completed quarter (200, no 422). An array or hash (quarter[]=1) answers 500. Example: 2 - `api_key` (string, required) Your API Key. Example: "YOUR_API_KEY" ## Response 200 fields (application/json): - `year` (integer) Example: 2026 - `niss` (string) Read live from the current settings, so a correction shows up at once, even on a past quarter. Example: "12345678902" - `worker_type` (string) Read live from the current settings. Selects the contribution rate. Enum: "independente", "eni" - `quarter` (integer) Example: 2 - `start_date` (string) First day of the quarter. Example: "2026-04-01" - `end_date` (string) Last day of the quarter. Example: "2026-06-30" - `total_amount` (string) The figure to declare in Segurança Social Direta: the gross amount invoiced in the quarter, before VAT. Decimal string (for example "1250.5"), not a JSON number. Counts Invoice, SimplifiedInvoice and InvoiceReceipt documents (and legacy documents with no type) with status sent, settled or second_copy, dated inside the quarter. Example: "1250.5" - `services_amount` (string) Heuristic services share of total_amount, from the unit of each invoice line. Normally adds up to total_amount together with goods_amount, but the two come from different sources (total_amount from the document totals, the split from the line subtotals) and may differ by rounding. Decimal string. Example: "1000.5" - `goods_amount` (string) Heuristic goods share of total_amount. Decimal string. Example: "250.0" - `document_count` (integer) Number of documents counted. Example: 4 - `monthly_breakdown` (array) Always exactly 3 entries, in month order. - `monthly_breakdown.month` (integer) Calendar month number. Example: 5 - `monthly_breakdown.total_amount` (string) Gross invoiced amount of the month before VAT (total_before_taxes), as a decimal string (for example "500.0"). Not a JSON number. Example: "500.0" - `monthly_breakdown.services_amount` (string) Part of total_amount classified as services (invoice lines whose unit is not unit, product or article). A heuristic split. Decimal string. Example: "400.0" - `monthly_breakdown.goods_amount` (string) Part of total_amount classified as goods (invoice lines whose unit is unit, product or article). A heuristic split. Decimal string. Example: "100.0" - `monthly_breakdown.document_count` (integer) Number of documents counted in the month. Example: 2 - `contribution_year` (integer) Year whose IAS caps the contribution base. Equals year, except for quarter 4, which is declared in January and uses year + 1. If that year is not in the IAS table (a future year, or before 2014) the latest known IAS is used (537.13, the 2026 value). Example: 2026 - `ias` (string) IAS (Indexante dos Apoios Sociais) of contribution_year, as a decimal string without fixed decimals ("537.13", "522.5"). Returned so a client can explain the estimate. Example: "537.13" - `monthly_base_cap` (string) Cap on the monthly contribution base, 12 times ias. Decimal string. Example: "6445.56" - `estimated_relevant_income` (number) ESTIMATE. services_amount x 0.70 + goods_amount x 0.20, rounded to 2 decimals. JSON number. Example: 750.35 - `estimated_monthly_payment` (number) ESTIMATE. Contribution for each of the 3 months this declaration bills, not for the quarter. max(round(min(estimated_relevant_income / 3, monthly_base_cap) x rate, 2), 20.00), with rate 0.214 for independente and 0.252 for eni. Never below the 20.00 monthly minimum, so a quarter with no invoicing still shows 20.0. JSON number. Example: 53.52 - `submitted_at` (string,null) When the account recorded a self-report for this quarter, otherwise null. It can be set on a quarter that is still open. ## Response 401 fields (application/json): - `errors` (array) Example: [{"error":"Authentication Error"}] - `errors.error` (string) ## Response 403 fields (application/json): - `errors` (array) Example: [{"error":"You do not have permission to perform this action"}] - `errors.error` (string) ## Response 422 fields (application/json): - `errors` (array) Example: [{"error":"No NISS is set for this account yet."}] - `errors.error` (string) ## Response 500 fields (application/json): - `errors` (array) Example: [{"error":"An unexpected error occurred"}] - `errors.error` (string)