Portugal (ATCUD and SAF-T)

Portugal entities use stricter issuance data than the baseline document API. Configure the entity with valid Portuguese issuer details, create the ATCUD series used for numbering, then issue documents with Portugal-specific operator data.

Entity Setup

Portugal entities require complete issuer details before live issuance.

Create Portugal entitytypescript

const _entity = await sdk.entities.create({
  name: "Lisboa Orbital Services",
  country: "Portugal",
  country_code: "PT",
  tax_number: "501964843",
  address: "Avenida da Liberdade 10",
  city: "Lisboa",
  post_code: "1000-001",
  phone: "+351210000000",
  email: "billing@example.pt",
});

ATCUD Series

Create an active ATCUD series for each Portugal document type you issue.

Create ATCUD seriestypescript

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

Issuing Documents

Portugal invoices must be issued with exportable customer, line, tax, series, and operator data.

Create issued invoicetypescript

const _invoice = await sdk.invoices.create({
  customer: {
    name: "Porto Payloads Lda",
    country: "Portugal",
    country_code: "PT",
    tax_number: "516403125",
  },
  items: [
    {
      name: "Ground operations service",
      quantity: 1,
      price: 100,
      classification: "service",
      taxes: [{ rate: 23 }],
    },
  ],
  pt: {
    series_id: "pt_series_000000000000000000000001",
    operator_first_name: "Antonio",
    operator_last_name: "Silva",
    operator_tax_number: "123456789",
  },
});

Linked Credit Notes

Every standard or custom Portugal credit note must reference an issued original invoice from the same entity. Send linked_documents as an array of original-invoice ID strings, for example [invoice.id]; do not send document objects. A request without an original invoice ID is rejected before the credit note, document relation, payment, or number is created. The original must be an issued (non-draft, non-voided, non-deleted) invoice of the same entity; a link to a draft, voided, deleted, or foreign invoice is rejected with a 422 naming the reason before anything is persisted.

Cancelling a Portugal invoice voids it in place and does not create a credit note automatically. For a business correction that requires a credit note, create the linked credit note explicitly using the flow below.

Use this verified flow:

Create the catalog item explicitly and use its item_id on the original invoice.
Issue the original invoice before creating the credit note.
Build each credit-note line from the stored original invoice line. Keep its item_id, price, discounts, and taxes unchanged; the credited quantity can be lower but cannot exceed the original quantity.
Create the credit note with linked_documents: [invoice.id] and the active credit-note ATCUD series.

The request to POST /credit-notes looks like:

{
  "customer": {
    "name": "Porto Payloads Lda",
    "country": "Portugal",
    "country_code": "PT",
    "tax_number": "516403125"
  },
  "linked_documents": [
    "inv_6595a27b5d35015c3ef0c3fd"
  ],
  "items": [
    {
      "item_id": "itm_6595a27b5d35015c3ef0c3fd",
      "name": "Ground operations service",
      "description": "Ground operations service",
      "classification": "service",
      "quantity": 1,
      "unit": "serviço",
      "price": 100,
      "discounts": [],
      "taxes": [
        {
          "classification": "standard"
        }
      ]
    }
  ],
  "pt": {
    "series_id": "pt_credit_note_series_00000000000001",
    "operator_first_name": "Antonio",
    "operator_last_name": "Silva",
    "operator_tax_number": "123456789"
  }
}

linked_documents is an array of original-invoice ID strings (e.g. "inv_6595a27b5d35015c3ef0c3fd"), not document objects.

SAF-T Export

Generate monthly SAF-T PT XML for Portugal entities.

GET /fiscalization/pt/saft/report rejects a to date in the future; for the current month, request up to today’s date rather than the end of the month.

Export SAF-Ttypescript

const _xml = await sdk.ptSafT.generateReport({
  from: "2026-01-01",
  to: "2026-01-31",
});

See the PT ATCUD Series API Reference, PT SAF-T API Reference, and Invoices API Reference.