> ## Documentation Index > Fetch the complete documentation index at: https://invopop-link-fix.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # AT issuing invoices guide > Issue invoices, deliveries, and payments in Portugal using Invopop's certified implementation. export const ptAtCancelDeliveryWorkflow = { "name": "AT cancel delivery", "description": "Cancel a delivery document through AT and generate PDF", "schema": "bill/delivery", "steps": [{ "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090", "name": "Cancel SAF-T record", "provider": "at-pt.cancel" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "void" } }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }], "rescue": [{ "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } }] }; export const ptAtIssueDeliveryWorkflow = { "name": "AT issue delivery", "description": "Issue a delivery document through AT and generate PDF", "schema": "bill/delivery", "steps": [{ "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "76f194b0-f2b9-11ef-acb2-cd64e858247e", "name": "Record document for SAF-T", "provider": "at-pt.record" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "sent" } }], "rescue": [{ "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } }] }; export const ptAtCancelPaymentWorkflow = { "name": "AT cancel payment", "description": "Cancel a payment through AT and generate PDF", "schema": "bill/payment", "steps": [{ "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090", "name": "Cancel SAF-T record", "provider": "at-pt.cancel" }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "void" } }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }], "rescue": [{ "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } }] }; export const ptAtIssuePaymentWorkflow = { "name": "AT issue payment", "description": "Issue a payment through AT and generate PDF", "schema": "bill/payment", "steps": [{ "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "76f194b0-f2b9-11ef-acb2-cd64e858247e", "name": "Record document for SAF-T", "provider": "at-pt.record" }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "sent" } }], "rescue": [{ "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } }] }; export const ptAtCancelInvoiceWorkflow = { "name": "AT cancel invoice", "description": "Cancel an invoice through AT and generate PDF", "schema": "bill/invoice", "steps": [{ "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090", "name": "Cancel SAF-T record", "provider": "at-pt.cancel" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "void" } }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }], "rescue": [{ "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } }] }; export const ptAtIssueInvoiceWorkflow = { "name": "AT issue invoice", "description": "Issue an invoice through AT and generate PDF", "schema": "bill/invoice", "steps": [{ "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "76f194b0-f2b9-11ef-acb2-cd64e858247e", "name": "Record document for SAF-T", "provider": "at-pt.record" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "sent" } }], "rescue": [{ "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } }] }; export const WorkflowDiagram = ({workflow}) => { const stateColors = { processing: "yellow", sent: "blue", received: "blue", registered: "green", completed: "green", error: "red" }; const StateChip = ({state, label}) => {label.charAt(0).toUpperCase() + label.slice(1)} ; const providerIcons = { "silo.state": "https://silo.invopop.com/images/status.svg", "silo.close": "https://silo.invopop.com/images/check-badge.svg", "silo.if": "https://assets.invopop.com/apps/silo/if.svg", "silo.folder": "https://silo.invopop.com/images/folder.svg", "silo.modify": "https://silo.invopop.com/images/modify.svg", "silo.correct": "https://silo.invopop.com/images/replace.svg", "silo.sleep": "https://assets.invopop.com/icons/sleep.svg", silo: "https://assets.invopop.com/apps/silo/icon.svg", "sequence.enumerate": "https://sequence.invopop.com/images/enumerate.svg", "transform.job.create": "https://transform.invopop.com/images/jobs.svg", webhook: "https://webhook.invopop.com/icon.svg", lookup: "https://lookup.invopop.com/icon.png", dropbox: "https://dropbox.invopop.com/icon.png", pdf: "https://pdf.invopop.com/file-pdf.svg", peppol: "https://assets.invopop.com/apps/peppol/icon.svg", ubl: "https://assets.invopop.com/apps/ubl/logo.svg", cii: "https://assets.invopop.com/apps/cii/logo.svg", "gov-fr": "https://assets.invopop.com/flags/fr.svg", "chorus-pro": "https://assets.invopop.com/apps/chroruspro/icon.svg", "gov-es": "https://assets.invopop.com/apps/gov-es/icon.svg", "gov-es.sii": "https://assets.invopop.com/apps/sii/icon.svg", "gov-es.ticketbai": "https://assets.invopop.com/apps/ticketbai/icon.svg", "gov-es.facturae": "https://assets.invopop.com/apps/facturae/icon.svg", verifactu: "https://assets.invopop.com/apps/verifactu/icon.svg", "gov-pl": "https://assets.invopop.com/apps/ksef/icon.svg", "gov-sa": "https://assets.invopop.com/apps/zatca/icon.svg", "gov-ar": "https://assets.invopop.com/apps/arca/icon.svg", "at-pt": "https://assets.invopop.com/apps/at-pt/icon.svg", "sat-mx": "https://assets.invopop.com/apps/sat-mexico/icon.svg", "sw-sapien": "https://assets.invopop.com/apps/sw-sapien/icon.svg", "sdi-it": "https://assets.invopop.com/apps/sdi-italy/icon.svg", "ticket-it": "https://assets.invopop.com/apps/agenzia-entrate/icon.svg", "nfe-br": "https://assets.invopop.com/apps/notas-fiscais-eletronicas-brazil/icon.svg", chargebee: "https://assets.invopop.com/apps/chargebee/icon.svg", stripe: "https://assets.invopop.com/apps/stripe/icon.svg", email: "https://assets.invopop.com/apps/email/icon.svg", cron: "https://assets.invopop.com/apps/cron/icon.svg", ilyda: "https://assets.invopop.com/apps/ilyda/icon.svg", invoicexpress: "https://assets.invopop.com/apps/invoicexpress/icon.svg", plemsi: "https://assets.invopop.com/flags/co.svg" }; const iconFor = provider => { const parts = (provider || "").split("."); for (let i = parts.length; i > 0; i--) { const url = providerIcons[parts.slice(0, i).join(".")]; if (url) return url; } return null; }; const StepIcon = ({provider}) => { const url = iconFor(provider); return {url ? : null} ; }; const renderSummary = summary => { const nodes = []; const re = /`([^`]+)`(\{[^}]*\})?/g; let last = 0; let m; let k = 0; while ((m = re.exec(summary)) !== null) { if (m.index > last) nodes.push(summary.slice(last, m.index)); const attrs = m[2] || ""; if (attrs.indexOf(".state") >= 0) { const state = (attrs.match(/\.state\s+\.([\w-]+)/) || [])[1] || m[1]; nodes.push(); } else if (attrs) { nodes.push( {m[1]} ); } else { nodes.push( {m[1]} ); } last = m.index + m[0].length; } if (last < summary.length) nodes.push(summary.slice(last)); return nodes; }; const NoteRow = ({text}) =>
{"// " + text}
; const renderSteps = (steps, counter) => (steps || []).map(step => { counter.n += 1; const n = counter.n; const branches = (step.next || []).filter(b => b.steps && b.steps.length > 0); return
{step.notes ? : null}
{n}
{step.name} {step.summary ? {renderSummary(step.summary)} : null}
{branches.length > 0 ?
{branches.map((branch, bi) =>
{branch.code || branch.status}
{renderSteps(branch.steps, counter)}
)}
: null}
; }); const counter = { n: 0 }; const wf = workflow || ({}); return
{renderSteps(wf.steps, counter)} {wf.rescue && wf.rescue.length > 0 ?
{renderSteps(wf.rescue, counter)}
: null}
; }; ## Introduction Invopop, as a certified provider in Portugal, allows you to issue fully-compliant tax documents and report them to the *Autoridade Tributária e Aduaneira* (AT). Using the AT Portugal app, you can generate PDFs with the correct signatures, ATCUD and QR codes for all your documents (invoices, transport documents, payments, etc.). Also, you can report them to the AT either in batch, via periodic SAF-T PT reports, or in real-time, using the AT web services. This guide will walk you through the process of issuing invoices, delivery documents, and payments in a supplier's name, cancelling them if needed, and reporting them to the AT. ## Prerequisites To issue invoices and other documents in Portugal, you will need: * **A registered supplier**: follow the [AT supplier registration guide](/guides/pt-at-supplier) to connect the AT Portugal app, register the supplier, and register their document series before issuing. * Document details: * Line items with quantity, price, description * Applicable VAT rates * Any other details required for the specific document type ## Setup Prepare the processing and cancel workflows for the document types you plan to issue: invoices, deliveries, and payments. The AT Portugal app must already be connected and configured, and the supplier registered — this is covered in the [supplier registration guide](/guides/pt-at-supplier). All of the following steps must be carried out from the [Invopop Console](https://console.invopop.com). You can skip this step if you don't plan to issue invoices. Add to my workspace → Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view. ```json Example AT issue invoice workflow theme={null} { "name": "AT issue invoice", "description": "Issue an invoice through AT and generate PDF", "schema": "bill/invoice", "steps": [ { "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "76f194b0-f2b9-11ef-acb2-cd64e858247e", "name": "Record document for SAF-T", "provider": "at-pt.record" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "sent" } } ], "rescue": [ { "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } } ] } ``` You can skip this step if you don't plan to cancel invoices. Add to my workspace → Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view. ```json Example AT cancel invoice workflow theme={null} { "name": "AT cancel invoice", "description": "Cancel an invoice through AT and generate PDF", "schema": "bill/invoice", "steps": [ { "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090", "name": "Cancel SAF-T record", "provider": "at-pt.cancel" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "void" } }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } } ], "rescue": [ { "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } } ] } ``` You can skip this step if you don't plan to issue delivery documents. Add to my workspace → Copy and paste into a new [Empty Delivery workflow](https://console.invopop.com/redirect/workflows/new?template=empty-delivery) code view. ```json Example AT issue delivery workflow theme={null} { "name": "AT issue delivery", "description": "Issue a delivery document through AT and generate PDF", "schema": "bill/delivery", "steps": [ { "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "76f194b0-f2b9-11ef-acb2-cd64e858247e", "name": "Record document for SAF-T", "provider": "at-pt.record" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "sent" } } ], "rescue": [ { "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } } ] } ``` You can skip this step if you don't plan to cancel delivery documents. Add to my workspace → Copy and paste into a new [Empty Delivery workflow](https://console.invopop.com/redirect/workflows/new?template=empty-delivery) code view. ```json Example AT cancel delivery workflow theme={null} { "name": "AT cancel delivery", "description": "Cancel a delivery document through AT and generate PDF", "schema": "bill/delivery", "steps": [ { "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090", "name": "Cancel SAF-T record", "provider": "at-pt.cancel" }, { "id": "59174840-c09a-11f0-b8a2-b531dbe0da3c", "name": "Send document to AT", "provider": "at-pt.send" }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "void" } }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } } ], "rescue": [ { "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } } ] } ``` You can skip this step if you don't plan to issue payments. Add to my workspace → Copy and paste into a new [Empty Payment workflow](https://console.invopop.com/redirect/workflows/new?template=empty-payment) code view. ```json Example AT issue payment workflow theme={null} { "name": "AT issue payment", "description": "Issue a payment through AT and generate PDF", "schema": "bill/payment", "steps": [ { "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "76f194b0-f2b9-11ef-acb2-cd64e858247e", "name": "Record document for SAF-T", "provider": "at-pt.record" }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "sent" } } ], "rescue": [ { "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } } ] } ``` You can skip this step if you don't plan to cancel payments. Add to my workspace → Copy and paste into a new [Empty Payment workflow](https://console.invopop.com/redirect/workflows/new?template=empty-payment) code view. ```json Example AT cancel payment workflow theme={null} { "name": "AT cancel payment", "description": "Cancel a payment through AT and generate PDF", "schema": "bill/payment", "steps": [ { "id": "6f884d90-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "processing" } }, { "id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090", "name": "Cancel SAF-T record", "provider": "at-pt.cancel" }, { "id": "7a708240-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "void" } }, { "id": "93795a50-f2b9-11ef-acb2-cd64e858247e", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Original", "config": { "date_format": "%Y-%m-%d", "hide_promo": true, "label": "Original", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "" } }, { "id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508", "name": "Generate PDF", "provider": "pdf", "summary": "Portuguese · A4 · Duplicado", "config": { "date_format": "%Y-%m-%d", "label": "Duplicado", "layout": "A4", "locale": "pt", "logo_height": 40, "watermark": "", "duplicate": true } } ], "rescue": [ { "id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e", "name": "Set state", "provider": "silo.state", "config": { "state": "error" } } ] } ``` ## Running In this section, we'll provide details on how to issue AT invoices and other documents on behalf of a registered supplier, cancel them, and report them to the AT. The recommended approach for running jobs is to perform two steps: first upload the document to the [silo](/api-ref/silo/entries/create-an-entry-put), then [create a job](/api-ref/transform/jobs/create-a-job-put). ### Send a document The following examples show partial [GOBL](https://docs.gobl.org) documents you can copy and paste directly into the [Invopop Console](https://console.invopop.com) or store via the API as silo entries. After uploading, you must run the corresponding processing workflow (invoice, delivery, or payment) created during setup. GOBL Documents reported to the AT require the regime to be set to PT and addons to include pt-saft-v1. Invopop will try to assign these automatically, but we recommend defining them explicitly before uploading. Documents are issued under one of the series registered during supplier onboarding, and their sequence number (the `code` property) is assigned automatically by the **Record document for SAF-T** step — do not add a sequence step. See [Series management](/guides/pt-at-supplier#series-management) in the supplier registration guide for naming rules, sequence assignment, and series types. In this example, we're issuing a simple invoice from a Portuguese supplier to another Portuguese business. Notice: * the minimal version in the first tab contains only the essential fields required to create the invoice, without totals or calculations, * the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the [GOBL](https://docs.gobl.org) library, * the `supplier` and `series` fields are set to example values; you'll need to replace them with the details of supplier and series registered as per the previous sections. The series must be registered in the Supplier Portal and follow Portuguese naming conventions (see [Series management](/guides/pt-at-supplier#series-management) for details), * when running `gobl build`, or uploading the file, the system automatically calculates totals, assigns the [`pt-saft-invoice-type`](https://docs.gobl.org/addons/pt-saft-v1#invoice-type) extension to `FT` (Fatura), sets the [`pt-saft-payment-means`](https://docs.gobl.org/addons/pt-saft-v1#payment-means) extension to `CC` for card payment, and applies the [`pt-saft-tax-rate`](https://docs.gobl.org/addons/pt-saft-v1#tax-rate-code) extension to `NOR` for standard VAT, * the built version in the second tab shows the normalized document with calculated totals, line item sums (including advance payment deductions), tax breakdowns, and automatically generated fields, and, * the `h` item unit causes the [`pt-saft-product-type`](https://docs.gobl.org/addons/pt-saft-v1#product-type) extension to be set to `S` (Serviço), and the [`pt-region`](https://docs.gobl.org/regimes/pt#region-code) extension is automatically set to `PT`. ```json AT B2B Invoice (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "standard", "series": "FT SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "504614240" }, "addresses": [ { "num": "156", "street": "Avenida da República", "locality": "Lisboa", "code": "1050-045", "country": "PT" } ], "emails": [ { "addr": "maria@example.com" } ], "registration": { "capital": "150000.00", "office": "CRC Lisboa", "other": "sob NIF 770013813" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ], "emails": [ { "addr": "gusto@example.com" } ], "websites": [ { "url": "https://gusto.example.com" } ], "telephones": [ { "num": "+351912345678" } ] }, "lines": [ { "quantity": "20.0", "item": { "name": "Development services", "price": "50.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ], "payment": { "advances": [ { "date": "2024-12-23", "key": "card", "description": "Advance payment", "amount": "12.34" } ] } } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "standard", "series": "FT SERIES-A", "issue_date": "2024-12-23", "value_date": "2024-12-23", "currency": "EUR", "tax": { "ext": { "pt-saft-invoice-type": "FT", "pt-saft-source": "P" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "504614240" }, "addresses": [ { "num": "156", "street": "Avenida da República", "locality": "Lisboa", "code": "1050-045", "country": "PT" } ], "emails": [ { "addr": "maria@example.com" } ], "registration": { "capital": "150000.00", "office": "CRC Lisboa", "other": "sob NIF 770013813" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ], "emails": [ { "addr": "gusto@example.com" } ], "websites": [ { "url": "https://gusto.example.com" } ], "telephones": [ { "num": "+351912345678" } ] }, "lines": [ { "i": 1, "quantity": "20.0", "item": { "name": "Development services", "price": "50.00", "unit": "h", "ext": { "pt-saft-product-type": "S" } }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "1000.00" } ], "payment": { "advances": [ { "date": "2024-12-23", "key": "card", "description": "Advance payment", "amount": "12.34", "ext": { "pt-saft-payment-means": "CC" } } ] }, "totals": { "sum": "1000.00", "total": "1000.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" } ], "amount": "230.00" } ], "sum": "230.00" }, "tax": "230.00", "total_with_tax": "1230.00", "payable": "1230.00", "advance": "12.34", "due": "1217.66" } } ``` In this example, a self-employed professional (*trabalhador independente*) invoices a Portuguese company for consulting services. On top of the standard VAT, the customer retains personal income tax (*IRS*) at source. Notice: * the minimal version in the first tab contains only the essential fields; the line carries a second tax on top of `VAT`: an `IRS` combo with `percent` set to `25%` and no `rate`, * the document-level `tax.notes` entry with `cat: "IRS"` carries the legal basis for the withholding (here *Art. 101.º CIRS*); the SAF-T export surfaces it as the `WithholdingTaxType` (`IRS`) and `WithholdingTaxDescription` of the `WithholdingTax` block, and, * in the built version the `IRS` tax becomes its own `retained` category in `totals.taxes`, separate from `VAT`, with `retained: "250.00"` (25% of the 1000,00 base). ```json AT Withholding Invoice (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "standard", "series": "FT SERIES-A", "issue_date": "2024-08-03", "currency": "EUR", "tax": { "notes": [ { "cat": "IRS", "text": "Art. 101.º CIRS" } ] }, "supplier": { "name": "João Silva, Trabalhador Independente", "tax_id": { "country": "PT", "code": "545259045" }, "addresses": [ { "street": "Rua das Flores", "locality": "Lisboa", "code": "1000-000", "country": "PT" } ], "emails": [ { "addr": "joao.silva@example.com" } ] }, "customer": { "name": "Empresa Cliente, Lda.", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "lines": [ { "quantity": "1", "item": { "name": "Serviços de consultoria", "price": "1000.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "standard" }, { "cat": "IRS", "percent": "25%" } ] } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "standard", "series": "FT SERIES-A", "issue_date": "2024-08-03", "value_date": "2024-08-03", "currency": "EUR", "tax": { "ext": { "pt-saft-invoice-type": "FT", "pt-saft-source": "P" }, "notes": [ { "cat": "IRS", "text": "Art. 101.º CIRS" } ] }, "supplier": { "name": "João Silva, Trabalhador Independente", "tax_id": { "country": "PT", "code": "545259045" }, "addresses": [ { "street": "Rua das Flores", "locality": "Lisboa", "code": "1000-000", "country": "PT" } ], "emails": [ { "addr": "joao.silva@example.com" } ] }, "customer": { "name": "Empresa Cliente, Lda.", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "lines": [ { "i": 1, "quantity": "1", "item": { "name": "Serviços de consultoria", "price": "1000.00", "unit": "h", "ext": { "pt-saft-product-type": "S" } }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } }, { "cat": "IRS", "percent": "25%" } ], "total": "1000.00" } ], "totals": { "sum": "1000.00", "total": "1000.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" } ], "amount": "230.00" }, { "code": "IRS", "retained": true, "rates": [ { "base": "1000.00", "percent": "25%", "amount": "250.00" } ], "amount": "250.00" } ], "sum": "230.00", "retained": "250.00" }, "tax": "230.00", "total_with_tax": "1230.00", "retained_tax": "250.00", "payable": "980.00" } } ``` In this example, we're issuing a standard invoice from a Portuguese supplier that has adhered to the **Cash VAT scheme** (*regime de IVA de Caixa*), under which VAT becomes due only when the customer actually pays rather than when the invoice is issued. Notice: * the only difference from the standard AT B2B invoice above is the `cash-vat` tag (`$tags: ["cash-vat"]`), which flags the supplier's membership in the scheme, * the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon reacts to that tag by setting the [`pt-saft-cash-vat`](https://docs.gobl.org/addons/pt-saft-v1#cash-vat-scheme-indicator) extension to `1` in the invoice's `tax` section, and, * the document is otherwise a normal `standard` invoice: the [`pt-saft-invoice-type`](https://docs.gobl.org/addons/pt-saft-v1#invoice-type) extension is still set to `FT` (Fatura) and the standard VAT rate still maps to the [`pt-saft-tax-rate`](https://docs.gobl.org/addons/pt-saft-v1#tax-rate-code) extension `NOR`. ```json AT Cash VAT invoice (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "cash-vat" ], "type": "standard", "series": "FT SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "504614240" }, "addresses": [ { "num": "156", "street": "Avenida da República", "locality": "Lisboa", "code": "1050-045", "country": "PT" } ], "emails": [ { "addr": "maria@example.com" } ], "registration": { "capital": "150000.00", "office": "CRC Lisboa", "other": "sob NIF 770013813" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ], "emails": [ { "addr": "gusto@example.com" } ] }, "lines": [ { "quantity": "20.0", "item": { "name": "Development services", "price": "50.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "cash-vat" ], "type": "standard", "series": "FT SERIES-A", "issue_date": "2024-12-23", "value_date": "2024-12-23", "currency": "EUR", "tax": { "ext": { "pt-saft-cash-vat": "1", "pt-saft-invoice-type": "FT", "pt-saft-source": "P" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "504614240" }, "addresses": [ { "num": "156", "street": "Avenida da República", "locality": "Lisboa", "code": "1050-045", "country": "PT" } ], "emails": [ { "addr": "maria@example.com" } ], "registration": { "capital": "150000.00", "office": "CRC Lisboa", "other": "sob NIF 770013813" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ], "emails": [ { "addr": "gusto@example.com" } ] }, "lines": [ { "i": 1, "quantity": "20.0", "item": { "name": "Development services", "price": "50.00", "unit": "h", "ext": { "pt-saft-product-type": "S" } }, "sum": "1000.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "1000.00" } ], "totals": { "sum": "1000.00", "total": "1000.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "1000.00", "percent": "23.0%", "amount": "230.00" } ], "amount": "230.00" } ], "sum": "230.00" }, "tax": "230.00", "total_with_tax": "1230.00", "payable": "1230.00" } } ``` In this example, we're issuing a simplified invoice (*Fatura Simplificada*) — the short-form invoice used for low-value retail sales where the customer doesn't need to be identified. Notice: * the document carries the `simplified` tag (`$tags: ["simplified"]`) and omits the `customer` entirely, * the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon reacts to the tag by setting the [`pt-saft-invoice-type`](https://docs.gobl.org/addons/pt-saft-v1#invoice-type) extension to `FS` (Fatura Simplificada), and the `series` follows the matching `FS ` prefix convention, * if the document also records full payment (for example, a 100% advance), the addon derives the type `FR` (Fatura-Recibo) instead, and the series must then use the `FR ` prefix, and, * as with the other examples, totals and tax breakdowns are calculated automatically when running `gobl build` or uploading. ```json AT Simplified Invoice (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "simplified" ], "type": "standard", "series": "FS SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "504614240" }, "addresses": [ { "num": "156", "street": "Avenida da República", "locality": "Lisboa", "code": "1050-045", "country": "PT" } ], "emails": [ { "addr": "maria@example.com" } ], "registration": { "capital": "150000.00", "office": "CRC Lisboa", "other": "sob NIF 770013813" } }, "lines": [ { "quantity": "1", "item": { "name": "Suporte técnico presencial", "price": "45.00", "unit": "h" }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "simplified" ], "type": "standard", "series": "FS SERIES-A", "issue_date": "2024-12-23", "value_date": "2024-12-23", "currency": "EUR", "tax": { "ext": { "pt-saft-invoice-type": "FS", "pt-saft-source": "P" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "504614240" }, "addresses": [ { "num": "156", "street": "Avenida da República", "locality": "Lisboa", "code": "1050-045", "country": "PT" } ], "emails": [ { "addr": "maria@example.com" } ], "registration": { "capital": "150000.00", "office": "CRC Lisboa", "other": "sob NIF 770013813" } }, "lines": [ { "i": 1, "quantity": "1", "item": { "name": "Suporte técnico presencial", "price": "45.00", "unit": "h", "ext": { "pt-saft-product-type": "S" } }, "sum": "45.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "45.00" } ], "totals": { "sum": "45.00", "total": "45.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "45.00", "percent": "23.0%", "amount": "10.35" } ], "amount": "10.35" } ], "sum": "10.35" }, "tax": "10.35", "total_with_tax": "55.35", "payable": "55.35" } } ``` In this example, we're issuing a delivery note from a Portuguese supplier to another Portuguese receiver. Notice: * the first tab shows the minimal version containing only the essential fields required to create the delivery document; there are no totals or calculations, * the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the [GOBL](https://docs.gobl.org) library, * the `supplier` and `series` fields are set to example values; you'll need to replace them with the details of supplier and series registered as per the previous sections. The series must be registered in the Supplier Portal and follow Portuguese naming conventions (see [Series management](/guides/pt-at-supplier#series-management) for details), * this is a `note` document type with the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#movement-type) extension set to `GR` (Guia de Remessa), * when running `gobl build`, or uploading the document, the system automatically calculates totals, applies the standard VAT rate with the [`pt-saft-tax-rate`](https://docs.gobl.org/addons/pt-saft-v1#tax-rate-code) extension set to `NOR`, and normalizes all fields, * the second tab shows the built version of the document with the calculated totals, line item sums, tax breakdowns, and automatically generated fields, and, * the [`pt-region`](https://docs.gobl.org/regimes/pt#region-code) extension is automatically set to `PT`. ```json AT Delivery (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "note", "series": "GR SERIES-A", "issue_date": "2026-04-01", "currency": "EUR", "despatch_date": "2026-04-02", "receive_date": "2026-04-03", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "receiver": { "name": "Gusto Armazém", "addresses": [ { "street": "Zona Industrial, Lote 23", "locality": "Lisboa", "code": "1300-300", "country": "PT" } ] }, "lines": [ { "quantity": "10", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ], "notes": [ { "text": "Delivery note for products" } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "note", "series": "GR SERIES-A", "issue_date": "2026-04-01", "currency": "EUR", "despatch_date": "2026-04-02", "receive_date": "2026-04-03", "tax": { "ext": { "pt-saft-movement-type": "GR" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "receiver": { "name": "Gusto Armazém", "addresses": [ { "street": "Zona Industrial, Lote 23", "locality": "Lisboa", "code": "1300-300", "country": "PT" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "sum": "50.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "50.00" } ], "totals": { "sum": "50.00", "total": "50.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "50.00", "percent": "23.0%", "amount": "11.50" } ], "amount": "11.50" } ], "sum": "11.50" }, "tax": "11.50", "total_with_tax": "61.50", "payable": "61.50" }, "notes": [ { "text": "Delivery note for products" } ] } ``` A return guide (*Guia de Devolução*) records goods being returned to the supplier — for example, defective items, unsold stock, or any other scenario where previously delivered goods are sent back. Notice: * the document carries the `return` tag (`$tags: ["return"]`), which the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon uses to automatically set the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#movement-type) extension to `GD` (Guia de Devolução), * the `series` follows the `GD ` prefix convention and must be registered through the Supplier Portal, and, * the flow of goods is reversed compared to a delivery note: the `customer` is the party returning the goods, and the `supplier` is the one receiving them back. ```json AT Return guide (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": ["return"], "type": "note", "series": "GD SERIES-A", "issue_date": "2026-04-03", "currency": "EUR", "despatch_date": "2026-04-03", "receive_date": "2026-04-03", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "despatcher": { "name": "Gusto Armazém", "addresses": [ { "street": "Zona Industrial, Lote 23", "locality": "Lisboa", "code": "1300-300", "country": "PT" } ] }, "receiver": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "lines": [ { "quantity": "3", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ], "notes": [ { "text": "Goods returned by the customer." } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "return" ], "type": "note", "series": "GD SERIES-A", "issue_date": "2026-04-03", "currency": "EUR", "despatch_date": "2026-04-03", "receive_date": "2026-04-03", "tax": { "ext": { "pt-saft-movement-type": "GD" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "despatcher": { "name": "Gusto Armazém", "addresses": [ { "street": "Zona Industrial, Lote 23", "locality": "Lisboa", "code": "1300-300", "country": "PT" } ] }, "receiver": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "lines": [ { "i": 1, "quantity": "3", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "sum": "15.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "15.00" } ], "totals": { "sum": "15.00", "total": "15.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "15.00", "percent": "23.0%", "amount": "3.45" } ], "amount": "3.45" } ], "sum": "3.45" }, "tax": "3.45", "total_with_tax": "18.45", "payable": "18.45" }, "notes": [ { "text": "Goods returned by the customer." } ] } ``` For shipments where the specific recipient is not known upfront — for example, multi-stop delivery runs — issuers can emit a global waybill (*Guia de Transporte Global*) to cover the goods in transport. Notice: * the document `type` is set to `waybill`, which the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon normalizes to the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#movement-type) extension `GT` (Guia de Transporte), * the `series` follows the `GT ` prefix convention required by the AT and must be registered through the Supplier Portal, and, * the `customer` field is omitted: when no customer is provided on a `GT`, the SAF-T submission auto-fills the AT-prescribed generic entry *Consumidor final* with NIF `999999990` and address *Desconhecido*. ```json AT Global waybill (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "waybill", "series": "GT SERIES-A", "issue_date": "2026-04-01", "currency": "EUR", "despatch_date": "2026-04-02", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "lines": [ { "quantity": "100", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ], "notes": [ { "text": "Global waybill for multi-stop delivery" } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "waybill", "series": "GT SERIES-A", "issue_date": "2026-04-01", "currency": "EUR", "despatch_date": "2026-04-02", "tax": { "ext": { "pt-saft-movement-type": "GT" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "lines": [ { "i": 1, "quantity": "100", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "sum": "500.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "500.00" } ], "totals": { "sum": "500.00", "total": "500.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "500.00", "percent": "23.0%", "amount": "115.00" } ], "amount": "115.00" } ], "sum": "115.00" }, "tax": "115.00", "total_with_tax": "615.00", "payable": "615.00" }, "notes": [ { "text": "Global waybill for multi-stop delivery" } ] } ``` Once the recipient of part of the goods covered by a global waybill is known, a concrete document — typically a `GR` (Guia de Remessa) — must be issued with the full transaction details, including the `customer` and a cross-reference back to the originating `GT` so the AT can correlate both records. Notice: * the `customer` is now populated with the actual recipient of the goods, and, * the `preceding` array carries one entry with the `series`, `code`, and `issue_date` of the originating `GT`. ```json AT Delivery note from global waybill (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "note", "series": "GR SERIES-A", "issue_date": "2026-04-02", "currency": "EUR", "despatch_date": "2026-04-02", "receive_date": "2026-04-02", "preceding": [ { "series": "GT SERIES-A", "code": "1", "issue_date": "2026-04-01" } ], "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "receiver": { "name": "Gusto Armazém", "addresses": [ { "street": "Zona Industrial, Lote 23", "locality": "Lisboa", "code": "1300-300", "country": "PT" } ] }, "lines": [ { "quantity": "10", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ], "notes": [ { "text": "Stop delivery from global waybill GT SERIES-A/1" } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "note", "series": "GR SERIES-A", "issue_date": "2026-04-02", "currency": "EUR", "preceding": [ { "issue_date": "2026-04-01", "series": "GT SERIES-A", "code": "1" } ], "despatch_date": "2026-04-02", "receive_date": "2026-04-02", "tax": { "ext": { "pt-saft-movement-type": "GR" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "receiver": { "name": "Gusto Armazém", "addresses": [ { "street": "Zona Industrial, Lote 23", "locality": "Lisboa", "code": "1300-300", "country": "PT" } ] }, "lines": [ { "i": 1, "quantity": "10", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "sum": "50.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "50.00" } ], "totals": { "sum": "50.00", "total": "50.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "50.00", "percent": "23.0%", "amount": "11.50" } ], "amount": "11.50" } ], "sum": "11.50" }, "tax": "11.50", "total_with_tax": "61.50", "payable": "61.50" }, "notes": [ { "text": "Stop delivery from global waybill GT SERIES-A/1" } ] } ``` A return can also be linked back to a global waybill — for example, when surplus goods that were not delivered to any customer come back to the depot at the end of a delivery run. Notice: * as in the standalone return guide, the `return` tag drives the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#movement-type) extension to `GD`, * the `preceding` array references the originating `GT`, and, * the `customer` is omitted, since the goods are returning to the issuer's own depot rather than to a specific party. ```json AT Return from global waybill (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": ["return"], "type": "note", "series": "GD SERIES-A", "issue_date": "2026-04-03", "currency": "EUR", "preceding": [ { "issue_date": "2026-04-01", "series": "GT SERIES-A", "code": "1" } ], "despatch_date": "2026-04-03", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "receiver": { "name": "Innovatech Depot", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "lines": [ { "quantity": "2", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "taxes": [ { "cat": "VAT", "rate": "standard" } ] } ], "notes": [ { "text": "Surplus from global waybill GT SERIES-A/1 returned to depot." } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/delivery", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "return" ], "type": "note", "series": "GD SERIES-A", "issue_date": "2026-04-03", "currency": "EUR", "preceding": [ { "issue_date": "2026-04-01", "series": "GT SERIES-A", "code": "1" } ], "despatch_date": "2026-04-03", "tax": { "ext": { "pt-saft-movement-type": "GD" } }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "despatcher": { "name": "Innovatech Logistics", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "receiver": { "name": "Innovatech Depot", "addresses": [ { "street": "Rua da Indústria 45", "locality": "Porto", "code": "4050-300", "country": "PT" } ] }, "lines": [ { "i": 1, "quantity": "2", "item": { "name": "Product A", "price": "5.00", "unit": "unit", "ext": { "pt-saft-product-type": "P" } }, "sum": "10.00", "taxes": [ { "cat": "VAT", "key": "standard", "rate": "general", "percent": "23.0%", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" } } ], "total": "10.00" } ], "totals": { "sum": "10.00", "total": "10.00", "taxes": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "10.00", "percent": "23.0%", "amount": "2.30" } ], "amount": "2.30" } ], "sum": "2.30" }, "tax": "2.30", "total_with_tax": "12.30", "payable": "12.30" }, "notes": [ { "text": "Surplus from global waybill GT SERIES-A/1 returned to depot." } ] } ``` In this example, we're issuing a payment receipt from a Portuguese supplier to another Portuguese business. Notice: * the minimal version in the first tab contains only the essential fields required to create the payment document, * the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the [GOBL](https://docs.gobl.org) library, * the `supplier` and `series` fields are set to example values; you'll need to replace them with the details of supplier and series registered as per the previous sections. The series must be registered in the Supplier Portal and follow Portuguese naming conventions (see [Series management](/guides/pt-at-supplier#series-management) for details), * this is a single `receipt` payment that bundles **multiple payment methods**: 30,00 EUR in cash plus 31,50 EUR by card, summing to the document total of 61,50 EUR. Each method gets its own [`pt-saft-payment-means`](https://docs.gobl.org/addons/pt-saft-v1#payment-means) extension auto-assigned (`NU` for cash, `CC` for card), * when running `gobl build`, the system automatically assigns the [`pt-saft-payment-type`](https://docs.gobl.org/addons/pt-saft-v1#payment-type) extension to `RG` and the [`pt-saft-source`](https://docs.gobl.org/addons/pt-saft-v1#document-source) extension to `P`, * the built version in the second tab shows the normalized document with all automatically generated fields and extensions properly set, * the payment lines reference the original invoice being paid, though a single receipt can reference multiple invoices if needed, * this receipt could represent either a full or partial payment of the referenced invoice; it simply records the amounts and taxes being paid, so the total may or may not cover the full invoice amount, and, * there are no calculations in the minimal version; all normalizations will be made automatically when uploading. ```json AT Payment (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/payment", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "receipt", "series": "RG SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ], "emails": [ { "addr": "gusto@example.com" } ], "websites": [ { "url": "https://gusto.example.com" } ], "telephones": [ { "num": "+351912345678" } ] }, "lines": [ { "document": { "issue_date": "2024-12-23", "series": "FT SERIES-A", "code": "1", "description": "Invoice 1" }, "amount": "61.50", "tax": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "50.00", "percent": "23.0%", "amount": "11.50" } ], "amount": "11.50" } ], "sum": "11.50" } } ], "methods": [ { "key": "cash", "description": "Cash portion", "amount": "30.00" }, { "key": "card", "description": "Card portion", "amount": "31.50" } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/payment", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "type": "receipt", "series": "RG SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "ext": { "pt-saft-payment-type": "RG", "pt-saft-source": "P" }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ], "emails": [ { "addr": "gusto@example.com" } ], "websites": [ { "url": "https://gusto.example.com" } ], "telephones": [ { "num": "+351912345678" } ] }, "lines": [ { "i": 1, "document": { "issue_date": "2024-12-23", "series": "FT SERIES-A", "code": "1", "description": "Invoice 1" }, "amount": "61.50", "tax": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "50.00", "percent": "23.0%", "amount": "11.50" } ], "amount": "11.50" } ], "sum": "11.50" } } ], "methods": [ { "key": "cash", "description": "Cash portion", "amount": "30.00", "ext": { "pt-saft-payment-means": "NU" } }, { "key": "card", "description": "Card portion", "amount": "31.50", "ext": { "pt-saft-payment-means": "CC" } } ], "total": "61.50" } ``` In this example, we're issuing a payment receipt for a supplier under the **Cash VAT scheme** (*regime de IVA de Caixa*). For these suppliers, the receipt is the document that actually triggers the VAT becoming due, so the AT distinguishes it from an ordinary receipt. Notice: * the document carries the `cash-vat` tag (`$tags: ["cash-vat"]`), exactly as the Cash VAT invoice does, * on a `receipt`, that tag drives the [`pt-saft-payment-type`](https://docs.gobl.org/addons/pt-saft-v1#payment-type) extension to `RC` (*Recibo no âmbito do regime de IVA de Caixa*) instead of the default `RG` (*Outro Recibo*) you'd get on the ordinary AT payment receipt above, * the `series` follows the `RC ` prefix convention and must be registered through the Supplier Portal, * the payment line references the original invoice being settled, carrying its VAT breakdown so the AT can match the now-due tax to the issued invoice, and, * as with any receipt, the [`pt-saft-payment-means`](https://docs.gobl.org/addons/pt-saft-v1#payment-means) extension is auto-assigned per method (`TB` for the bank transfer) and the [`pt-saft-source`](https://docs.gobl.org/addons/pt-saft-v1#document-source) extension is set to `P`. ```json AT Cash VAT receipt (minimal) theme={null} { "$schema": "https://gobl.org/draft-0/bill/payment", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "cash-vat" ], "type": "receipt", "series": "RC SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "lines": [ { "document": { "issue_date": "2024-12-23", "series": "FT SERIES-A", "code": "1", "description": "Invoice 1" }, "amount": "61.50", "tax": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "50.00", "percent": "23.0%", "amount": "11.50" } ], "amount": "11.50" } ], "sum": "11.50" } } ], "methods": [ { "key": "credit-transfer", "description": "Bank transfer", "amount": "61.50" } ] } ``` ```json Built version theme={null} { "$schema": "https://gobl.org/draft-0/bill/payment", "$regime": "PT", "$addons": [ "pt-saft-v1" ], "$tags": [ "cash-vat" ], "type": "receipt", "series": "RC SERIES-A", "issue_date": "2024-12-23", "currency": "EUR", "ext": { "pt-saft-payment-type": "RC", "pt-saft-source": "P" }, "supplier": { "name": "Innovatech Lda", "tax_id": { "country": "PT", "code": "770013813" }, "addresses": [ { "street": "Rua das Flores 200 3º Esquerdo", "locality": "Porto", "code": "4050-265", "country": "PT" } ], "registration": { "capital": "100000.00", "office": "Porto" } }, "customer": { "name": "Gusto Unipessoal Lda", "tax_id": { "country": "PT", "code": "514329874" }, "addresses": [ { "street": "Avenida da Liberdade 152 2º Direito", "locality": "Lisboa", "code": "1250-146", "country": "PT" } ] }, "lines": [ { "i": 1, "document": { "issue_date": "2024-12-23", "series": "FT SERIES-A", "code": "1", "description": "Invoice 1" }, "amount": "61.50", "tax": { "categories": [ { "code": "VAT", "rates": [ { "key": "standard", "ext": { "pt-region": "PT", "pt-saft-tax-rate": "NOR" }, "base": "50.00", "percent": "23.0%", "amount": "11.50" } ], "amount": "11.50" } ], "sum": "11.50" } } ], "methods": [ { "key": "credit-transfer", "description": "Bank transfer", "amount": "61.50", "ext": { "pt-saft-payment-means": "TB" } } ], "total": "61.50" } ``` ### Cancel a document If you need to cancel a document that has already been issued and reported to the AT, you can use the cancel workflows created during setup. The cancellation process follows the same pattern as sending a document: create a job for the silo entry you want to cancel using the cancel workflow appropriate for the document type. ### Recovering documents issued offline If you lose the connection to Invopop and cannot issue documents through your regular workflow, Portuguese law defines exactly what to do. [Despacho n.º 8632/2014](https://info.portaldasfinancas.gov.pt/pt/informacao_fiscal/legislacao/diplomas_legislativos/Documents/Despacho_n%C2%BA_8632_2014_03_07.pdf), section 2.4, regulates the issuance of documents during a period of software unavailability (*inoperacionalidade do programa*) and their later integration into the certified invoicing system. #### While offline: issue on paper During the outage, documents must be issued manually on pre-printed paper forms acquired from an AT-authorized typography (*tipografia autorizada*). These paper documents: * Carry their own series and sequential numbering, pre-printed by the typography. * Include a pre-printed ATCUD: the typography registers the series with the AT and obtains the validation code on your behalf. * Do **not** require a QR code: the QR code obligation only applies to documents issued by certified software. We recommend keeping a pad of these forms on hand as your offline contingency. #### Once back online: recover the documents Immediately after the connection is restored, each paper document must be re-entered ("recovered") through Invopop so it becomes part of the certified record and gets reported to the AT: 1. **Register a recovery series** ([type `R`](/guides/pt-at-supplier#series-type)), either through the Supplier Portal or the [series registration endpoint](/api-ref/apps/at-pt/series-register). You can do this ahead of time as part of your contingency setup. Documents recovered from paper can only be issued under a recovery series. 2. **Create a GOBL document replicating the paper document exactly** — same line items, taxes, and totals — with these specifics: * The `issue_date` must be the date of the original paper document. * The `$tags` array must include `bypass`, so the totals are taken verbatim from the paper document instead of being recalculated. * The [`pt-saft-source`](https://docs.gobl.org/addons/pt-saft-v1#document-source) extension must be set to `M` (manual). * The [`pt-saft-source-ref`](https://docs.gobl.org/addons/pt-saft-v1#source-document-reference) extension must reference the paper document using the format defined in section 2.4.5 of the despacho: the document type code followed by the letter `M`, a space, and the paper document's series and number separated by a slash. ```json theme={null} { "$schema": "https://gobl.org/draft-0/bill/invoice", "$regime": "PT", "$addons": ["pt-saft-v1"], "$tags": ["bypass"], "series": "FT RECOVERY", "issue_date": "2026-05-28", "tax": { "ext": { "pt-saft-source": "M", "pt-saft-source-ref": "FTM ABC123/00042" } } } ``` This partial example shows only the recovery-specific fields. Complete the document with the supplier, customer, lines, and totals copied from the paper document. 3. **Run your regular invoice workflow** on the document. The recovered document is sealed like any other software-issued document — it receives a hash, an ATCUD from the recovery series, and a QR code — and is reported to the AT through the usual channels (real-time webservice and/or SAF-T PT). The reference to the paper document is included in the SAF-T `HashControl` field, as required by the despacho. Keep in mind: * Each paper document can be recovered only once. Attempting to recover the same source reference twice is rejected. * Any later document referencing a recovered one (e.g., a credit note rectifying it) must reference the original paper document's series and number, not the number assigned to the recovered document. Recovery series also cover a second scenario regulated by section 2.5 of the same despacho: re-entering documents lost to a system failure from their printed duplicates. In that case, the `pt-saft-source-ref` extension uses the letter `D` instead of `M` (e.g., `FTD FT SERIES/123`), and the original series is automatically decommissioned once the first document is recovered, as the law requires it to be closed. ### Reporting documents to the AT The AT Portugal app supports two methods for reporting documents to the *Autoridade Tributária e Aduaneira*: 1. **Real-time reporting** - Documents are submitted individually to the AT immediately upon issuance via webservice 2. **SAF-T PT reporting** - Documents are reported in batch format through periodic SAF-T PT reports The workflow templates provided in this guide enable both reporting mechanisms. #### Real-time reporting The **Send document to AT** step uses the AT's webservice to submit each document to the tax authority immediately after it is recorded. This step is optional. If you prefer to report documents only via SAF-T PT reports, you can remove it from your workflows. The **Send document to AT** step requires the supplier to have the appropriate AT user permissions (`WFA` for invoices, `WDT` for transport documents) as described in the [supplier registration guide](/guides/pt-at-supplier#register-a-supplier). #### SAF-T PT reporting SAF-T PT reports allow you to submit documents to the AT in batch format. The **Record document for SAF-T** step takes care of recording the documents for this purpose. The **Record document for SAF-T** step is required in all workflows, regardless of whether you also use real-time reporting. The AT may request SAF-T PT reports for audit purposes at any time, so all documents must be properly recorded. To generate a SAF-T PT report, a supplier can follow these steps: 1. Go to the [Invopop AT Portugal Supplier Portal](https://at-pt.invopop.com/portal) 2. Log in using the email address provided with the supplier's information 3. Go to the **SAF-T PT** section, enter a date range and click **Generate** The system will generate a SAF-T PT file containing all documents issued within the specified date range that have been recorded for SAF-T reporting. This file can then be submitted to the AT through [their portal](https://faturas.portaldasfinancas.gov.pt/faturas/comerciante/enviar-saft.action) or via [command line](https://faturas.portaldasfinancas.gov.pt/envioBatchInfoNovo.action). ## FAQ In Portugal, fiscally relevant documents issued through invoicing software must be reported to the Tax Authority (AT). There are two possible reporting models: 1. **SAF-T monthly export** – a single XML file including all documents for the month. This file is generated by the invoicing software and then uploaded manually to the AT portal, as there is no API available for submitting it automatically. 2. **Real-time transmission** – instead of a monthly file, each invoice is sent individually to the AT at the time of issuance, using the authority's API. Whether one model or the other is used usually depends on the issuer's accountant's preference (who typically uploads the SAF-T monthly report should they choose that model). Invopop's [AT Portugal app](/apps/at-portugal) supports both reporting methods, so each supplier can pick the one that best fits their needs. Install the AT Portugal app, register the supplier with their NIF, and pick a reporting model (monthly SAF-T or real-time submission). Run invoices through the AT Issue Invoice workflow — Invopop generates the ATCUD, QR, and signature automatically. When issuing in Portugal you may see an error similar to: > `recording envelope: totals: (payable: too high according to Artigo 40.º do CIVA.)` **What it means:** Article 40 of the Portuguese VAT Code (*Código do IVA*) sets limits and rules for **simplified invoices** (*faturas simplificadas*). If the payable amount exceeds what is allowed for a simplified invoice in your situation, the rules effectively require a **full invoice** (*fatura completa*) with proper buyer identification—not an anonymous or minimal customer. **What to do:** * Treat the document as a **full invoice** and supply **real customer tax data** when you have it. * If you **do not** have the buyer's tax information, Portuguese practice allows the generic retail customer: set the customer **name** to `Consumidor final` and the **tax ID** to `999999990`. * For transactions **above €1,000**, the law also expects **name and address** on the document. The AT may not always reject submissions that omit some of that detail, but you should follow the rule for full compliance. Adjust your GOBL customer block (or equivalent) accordingly and re-run the workflow. This error means your workflow includes the **Send to the AT** step for a payment receipt. Payment receipts are not supported for real-time reporting — the AT does not accept them via the real-time webservice. **The fix:** remove the **Send to the AT** step from your payment workflow. RG receipts are only reportable through the monthly SAF-T file. The **Record for SAF-T reporting** step alone is all you need for full compliance. Portugal defines two payment receipt types: * **RG — Outros Recibos**: Standard payment receipts, reported through the monthly SAF-T file only. Real-time reporting is not available for this type. * **RC — Recibo no âmbito do regime de IVA de Caixa**: Receipts specific to the VAT Cash accounting regime. RC payments are not currently supported by the AT Portugal app. See the [Portugal tax regime in GOBL](https://docs.gobl.org/regimes/pt) for tax categories, NIF rules, and AT-specific extensions. The [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon documents fields required by the SAF-T schema. More available in our [Portugal FAQ](/faq/portugal) section *** | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Compliance | [Invoicing compliance in Portugal](/compliance/portugal)
[Compliance timeline](/timelines/portugal) | | Apps | [AT Portugal](/apps/at-portugal) | | Guides | [Supplier registration](/guides/pt-at-supplier)
[Issuing invoices](/guides/pt-at) | | FAQ | [Portugal FAQ](/faq/portugal) | | GOBL | [Portugal Tax Regime](https://docs.gobl.org/regimes/pt)
[Portugal SAF-T addon](https://docs.gobl.org/addons/pt-saft-v1) | Ask and answer questions about Portugal's regulation →