PT ATCUD Series

PT ATCUD Series

Manage Portugal ATCUD series registrations used for PT numbering and SAF-T exports.

Endpoints

IntroductionPOST/fiscalization/pt/atcud-seriesPOST/fiscalization/pt/atcud-series/activeGET/fiscalization/pt/atcud-seriesGET/fiscalization/pt/atcud-series/{id}POST/fiscalization/pt/atcud-series/{id}/retire

The PT ATCUD Series Entry object

object

Attributes

idstring

Other attributesExpand all

entity_idstring

document_typestring

series_codestring

validation_codestring

first_numberstring

start_datestring<date>

is_manualboolean

initial_sequenceinteger

retired_atstring<date-time>nullable

---

Create PT ATCUD series

POST/fiscalization/pt/atcud-series

Create a Portugal ATCUD series registration. Invoice and advance invoice share the FT family. Series codes are unique without regard to case within each document family. Manual recovery series must start at 1. Creating a series does not retire existing series.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

document_typestringrequired

Portugal fiscal document type tracked for ATCUD series numbering.

Possible values: "invoice", "advance_invoice", "credit_note", "estimate"

series_codestringrequired

AT-communicated series code used in the PT document number.

validation_codestringrequired

AT-issued validation code: at least 8 uppercase consonants or digits 2–9 in production; uppercase alphanumeric codes starting with AA in sandbox only. No fixed maximum length. The entity environment determines which format is accepted.

start_datestring<date>required

First date for which the communicated series is valid.

Other parametersExpand all

first_numberstringoptionalnullable

is_manualbooleanoptionalnullable

initial_sequenceintegeroptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ptAtcudSeries.create({
  document_type: "invoice",
  series_code: "FT2026A",
  validation_code: "BCDF2345",
  first_number: "FT FT2026A/00001",
  start_date: "2026-01-01",
  is_manual: false,
  initial_sequence: 1
}, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Example:

MinimalManual credit note series

Response

Returns

idstring

Other parametersExpand all

entity_idstring

document_typestring

series_codestring

validation_codestring

first_numberstring

start_datestring<date>

is_manualboolean

initial_sequenceinteger

retired_atstring<date-time>nullable

json

Copy

{
  "id": "id",
  "entity_id": "entity-id",
  "document_type": "invoice",
  "series_code": "FT2026A",
  "validation_code": "BCDF2345",
  "first_number": "FT FT2026A/00001",
  "start_date": "2026-01-01",
  "is_manual": false,
  "initial_sequence": 1,
  "retired_at": null
}

---

Get active PT ATCUD series

POST/fiscalization/pt/atcud-series/active

Return the current non-manual, non-retired PT ATCUD series by document family. Invoice and advance invoice share one FT selection; canonical invoice registrations take precedence over historical advance-invoice aliases.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

document_typestringoptional

Possible values: "invoice", "advance_invoice", "credit_note", "estimate"

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ptAtcudSeries.getActive(undefined, {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

json

Copy

[
  {
    "id": "id",
    "entity_id": "entity-id",
    "document_type": "invoice",
    "series_code": "FT2026A",
    "validation_code": "BCDF2345",
    "first_number": "FT FT2026A/00001",
    "start_date": "2026-01-01",
    "is_manual": false,
    "initial_sequence": 1,
    "retired_at": null
  }
]

---

List PT ATCUD series

GET/fiscalization/pt/atcud-series

List PT ATCUD series registered on the selected PT entity, including retired series.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

document_typestringoptional

Possible values: "invoice", "advance_invoice", "credit_note", "estimate"

is_manualbooleanoptionalnullable

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ptAtcudSeries.list({
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

json

Copy

[
  {
    "id": "id",
    "entity_id": "entity-id",
    "document_type": "invoice",
    "series_code": "FT2026A",
    "validation_code": "BCDF2345",
    "first_number": "FT FT2026A/00001",
    "start_date": "2026-01-01",
    "is_manual": false,
    "initial_sequence": 1,
    "retired_at": null
  }
]

---

Get PT ATCUD series

GET/fiscalization/pt/atcud-series/{id}

Get one PT ATCUD series by ID, including retired series.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Space Invoices resource identifier (format: {prefix}_{hex24})

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ptAtcudSeries.get("inv_6595a27b5d35015c3ef0c3fd", {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

idstring

Other parametersExpand all

entity_idstring

document_typestring

series_codestring

validation_codestring

first_numberstring

start_datestring<date>

is_manualboolean

initial_sequenceinteger

retired_atstring<date-time>nullable

json

Copy

{
  "id": "id",
  "entity_id": "entity-id",
  "document_type": "invoice",
  "series_code": "FT2026A",
  "validation_code": "BCDF2345",
  "first_number": "FT FT2026A/00001",
  "start_date": "2026-01-01",
  "is_manual": false,
  "initial_sequence": 1,
  "retired_at": null
}

---

Retire PT ATCUD series

POST/fiscalization/pt/atcud-series/{id}/retire

Permanently retire a PT ATCUD series locally, preventing future issuance while preserving the series and historical documents. Requires entity administrator access. Repeated requests return the original retirement timestamp. This action does not communicate finalization to AT.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Space Invoices resource identifier (format: {prefix}_{hex24})

cURLNode.js SDKFetchPythonGoRubyPHP

Copy

import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.ptAtcudSeries.retirePtAtcudSeries("inv_6595a27b5d35015c3ef0c3fd", {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);

Response

Returns

idstring

Other parametersExpand all

entity_idstring

document_typestring

series_codestring

validation_codestring

first_numberstring

start_datestring<date>

is_manualboolean

initial_sequenceinteger

retired_atstring<date-time>nullable

json

Copy

{
  "id": "id",
  "entity_id": "entity-id",
  "document_type": "invoice",
  "series_code": "FT2026A",
  "validation_code": "BCDF2345",
  "first_number": "FT FT2026A/00001",
  "start_date": "2026-01-01",
  "is_manual": false,
  "initial_sequence": 1,
  "retired_at": null
}

---