ERPNext Portugal

A Frappe app that brings Portuguese tax compliance to ERPNext. It implements the requirements of the Portuguese Tax Authority (Autoridade Tributária e Aduaneira — AT) for electronic invoicing, including document series registration, tax type classification, and VAT exemption codes as defined by the SAFT-PT standard.

Features

AT document series management — register and track invoice series with the AT, covering all document types (invoices, credit notes, transport documents, payments, etc.)
Portuguese tax classification — classify tax categories as IVA (VAT), IS (Stamp Duty), or NS (Not subject/exempt)
VAT exemption codes — built-in reference data for all legal exemption codes with the exact mention required on the invoice and the applicable legal standard
Tax codes per line — link each tax template line to the correct Portuguese tax code and, when exempt, to the corresponding exemption code
Regional tax settings — configure a company's tax region (mainland Portugal, Azores, or Madeira) to apply the correct VAT rates

DocTypes

AT Serie

Represents a document series registered (or to be registered) with the AT. The doctype is submittable — submitting it triggers the registration request.

Field	AT service name	Description
`series_code`	—	Series identifier code (up to 35 chars), e.g. `2026`
`series_type`	tipoSerie	Series type: N Normal · F Self-billing · R Rectification
`document_class`	classeDoc	Document class: SI Sales & Invoicing · MG Stock & Goods · WD Working Documents · PY Payments
`document_type`	tipoDoc	AT document type code: FT, FS, FR, ND, NC, GR, GT, GA, GC, GD, CM, CC, FC, FO, NE, OU, OR, PF, RP, RE, CS, LD, RA, RC, RG
`planned_start_date`	dataInicioPrevUtiliz	Planned first use date
`processing_method`	meioProcessamento	Processing method: PI Paper · PF File · OM Online
`initial_sequence_number`	numInicialSeq	Initial sequence number (default: 1)

After registration the following AT-returned fields are filled in automatically (read-only):

Field	AT service name	Description
`at_validation_code`	codValidacaoSerie	Validation code returned by the AT
`at_registration_date`	dataRegisto	AT registration date
`at_status`	Estado	Status: A Active · N Not active · F Finalised
`last_document_sequence`	seqUltimoDocEmitido	Last document sequence number issued

Portugal Tax Code

Reference table for Portuguese tax codes used in item tax templates. Each record has a 3-character unique code and a human-readable title.

Portugal Tax Exemption

Reference table for all VAT exemption reasons defined by the AT. Each record stores:

Field	Description
`code`	3-character unique exemption code (e.g. `M01`)
`invoice_mention`	Exact text required on the invoice
`applicable_standard`	Legal basis (e.g. article of the VAT Code)

Custom Fields

This app adds the following fields to standard ERPNext doctypes:

DocType	Field	Type	Description
Company	`Tax country region`	Select	Tax region: PT mainland · PT-AC Azores · PT-MA Madeira (required)
Tax Category	`Portugal Tax Type`	Select	Classification: IVA · IS · NS
Item Tax Template Detail	`Portugal Tax Code`	Link → Portugal Tax Code	Tax code for the template line
Item Tax Template Detail	`Portugal Tax Exemption`	Link → Portugal Tax Exemption	Exemption code (mandatory when tax code is NS)
Sales Invoice	`Series`	Link → AT Serie	AT-registered series for the invoice (required)

Installation

Requirements

Frappe v16 and ERPNext v16
Python 3.10+

Setup

# 1. Get the app
bench get-app https://github.com/envlab-tech/erpnext_portugal --branch version-16

# 2. Install into your site
bench --site <your-site> install-app erpnext_portugal

# 3. Run migrations
bench --site <your-site> migrate

Contributing

This app uses pre-commit for code formatting and linting. After cloning, enable it:

cd apps/erpnext_portugal
pre-commit install

Pre-commit runs the following tools on every commit:

ruff — Python linting and formatting
eslint — JavaScript linting
prettier — JavaScript / Vue / SCSS formatting
pyupgrade — Python syntax modernisation

License

MIT

User Reviews

No reviews yet, be the first to review.

0.0

0 rating

Explore more apps