Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **FatturaPA / SDI (Italy)** — Export FatturaPA 1.2 XML (`FPR12` B2B and `FPA12` public administration), send via a configurable SDI intermediary HTTP adapter, track transmissions and SDI notifications (`RC`/`NS`/`MC`/`NE`/`DT`), and poll status every 15 minutes. See `docs/admin/configuration/FATTURAPA_SDI.md`.

## [5.20.0] - 2026-11-10
### Added

Expand Down
117 changes: 117 additions & 0 deletions app/integrations/sdi_transport.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
"""Generic HTTP transport for Italian SDI (FatturaPA) intermediaries."""

from __future__ import annotations

import base64
import logging
from typing import Any, Dict, Optional

import requests

logger = logging.getLogger(__name__)


class SdiTransportError(RuntimeError):
pass


def bridge_base_url(transport_url: str) -> str:
"""Strip a trailing /send path to get the intermediary base URL."""
url = (transport_url or "").rstrip("/")
if url.lower().endswith("/send"):
url = url[: -len("/send")]
return url.rstrip("/")


class GenericSdiTransport:
"""
HTTP adapter for a user-configured SDI intermediary.

Send contract:
POST {url}
Authorization: Bearer {token}
JSON: {
filename, formato, recipient: {codice_destinatario, pec},
xml_base64, sha256
}
Response: {message_id, sdi_identifier?}

Status contract:
GET {base}/message/{message_id}/status
Response: {
status, sdi_identifier?,
notifications: [{type: RC|NS|MC|NE|DT|AT, date, detail}]
}
"""

def __init__(self, url: str, token: Optional[str] = None, timeout: int = 30):
self.url = (url or "").strip()
self.token = (token or "").strip() or None
self.timeout = timeout or 30
if not self.url:
raise SdiTransportError("SDI transport URL is not configured")

def _headers(self) -> Dict[str, str]:
headers = {"Content-Type": "application/json", "Accept": "application/json"}
if self.token:
headers["Authorization"] = f"Bearer {self.token}"
return headers

def send(
self,
*,
filename: str,
formato: str,
codice_destinatario: str,
pec: Optional[str],
xml: str,
sha256: str,
) -> Dict[str, Any]:
payload = {
"filename": filename,
"formato": formato,
"recipient": {
"codice_destinatario": codice_destinatario,
"pec": pec,
},
"xml_base64": base64.b64encode(xml.encode("utf-8")).decode("ascii"),
"sha256": sha256,
}
try:
resp = requests.post(self.url, json=payload, headers=self._headers(), timeout=self.timeout)
except requests.RequestException as e:
raise SdiTransportError(f"SDI transport request failed: {e}") from e

if resp.status_code >= 400:
raise SdiTransportError(f"SDI transport returned HTTP {resp.status_code}: {resp.text[:500]}")

try:
data = resp.json()
except Exception as e:
raise SdiTransportError(f"SDI transport returned non-JSON response: {e}") from e

if not isinstance(data, dict):
raise SdiTransportError("SDI transport response must be a JSON object")
if not data.get("message_id"):
raise SdiTransportError("SDI transport response missing message_id")
return data

def get_status(self, message_id: str) -> Dict[str, Any]:
base = bridge_base_url(self.url)
status_url = f"{base}/message/{message_id}/status"
try:
resp = requests.get(status_url, headers=self._headers(), timeout=self.timeout)
except requests.RequestException as e:
raise SdiTransportError(f"SDI status request failed: {e}") from e

if resp.status_code >= 400:
raise SdiTransportError(f"SDI status returned HTTP {resp.status_code}: {resp.text[:500]}")

try:
data = resp.json()
except Exception as e:
raise SdiTransportError(f"SDI status returned non-JSON response: {e}") from e

if not isinstance(data, dict):
raise SdiTransportError("SDI status response must be a JSON object")
return data
2 changes: 2 additions & 0 deletions app/models/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@
from .invoice_image import InvoiceImage
from .invoice_pdf_template import InvoicePDFTemplate
from .invoice_peppol import InvoicePeppolTransmission, PeppolInboundDocument
from .invoice_sdi import InvoiceSdiTransmission
from .invoice_template import InvoiceTemplate
from .issue import Issue
from .kanban_board_template import KanbanBoardTemplate
Expand Down Expand Up @@ -201,6 +202,7 @@
"InvoiceEmail",
"InvoicePeppolTransmission",
"PeppolInboundDocument",
"InvoiceSdiTransmission",
"Webhook",
"WebhookDelivery",
"Quote",
Expand Down
17 changes: 17 additions & 0 deletions app/models/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,11 @@ class Client(db.Model):
country = db.Column(db.String(2), nullable=True) # ISO 3166-1 alpha-2
vat_id = db.Column(db.String(50), nullable=True)
leitweg_id = db.Column(db.String(100), nullable=True) # XRechnung BT-10 / German Leitweg-ID
# Italian FatturaPA / SDI recipient fields
sdi_codice_destinatario = db.Column(db.String(7), nullable=True) # 6=PA (FPA12), 7=B2B (FPR12)
pec_email = db.Column(db.String(200), nullable=True)
codice_fiscale = db.Column(db.String(16), nullable=True)
provincia = db.Column(db.String(2), nullable=True)
default_hourly_rate = db.Column(db.Numeric(9, 2), nullable=True)
status = db.Column(db.String(20), default="active", nullable=False) # 'active' or 'inactive'
prepaid_hours_monthly = db.Column(db.Numeric(7, 2), nullable=True)
Expand Down Expand Up @@ -70,6 +75,10 @@ def __init__(
country=None,
vat_id=None,
leitweg_id=None,
sdi_codice_destinatario=None,
pec_email=None,
codice_fiscale=None,
provincia=None,
default_hourly_rate=None,
company=None,
prepaid_hours_monthly=None,
Expand All @@ -94,6 +103,10 @@ def __init__(
self.country = country.strip().upper()[:2] if country else None
self.vat_id = vat_id.strip() if vat_id else None
self.leitweg_id = leitweg_id.strip() if leitweg_id else None
self.sdi_codice_destinatario = sdi_codice_destinatario.strip().upper() if sdi_codice_destinatario else None
self.pec_email = pec_email.strip() if pec_email else None
self.codice_fiscale = codice_fiscale.strip().upper() if codice_fiscale else None
self.provincia = provincia.strip().upper()[:2] if provincia else None
self.default_hourly_rate = Decimal(str(default_hourly_rate)) if default_hourly_rate else None
self.prepaid_hours_monthly = (
Decimal(str(prepaid_hours_monthly)) if prepaid_hours_monthly not in (None, "") else None
Expand Down Expand Up @@ -298,6 +311,10 @@ def to_dict(self):
"country": getattr(self, "country", None),
"vat_id": getattr(self, "vat_id", None),
"leitweg_id": getattr(self, "leitweg_id", None),
"sdi_codice_destinatario": getattr(self, "sdi_codice_destinatario", None),
"pec_email": getattr(self, "pec_email", None),
"codice_fiscale": getattr(self, "codice_fiscale", None),
"provincia": getattr(self, "provincia", None),
"default_hourly_rate": str(self.default_hourly_rate) if self.default_hourly_rate else None,
"status": self.status,
"is_active": self.is_active,
Expand Down
12 changes: 12 additions & 0 deletions app/models/invoice.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,10 @@ class Invoice(db.Model):
vat_exemption_reason = db.Column(db.Text, nullable=True)
vat_exemption_code = db.Column(db.String(50), nullable=True)

# Italian public-administration procurement codes (FatturaPA DatiOrdineAcquisto)
cig = db.Column(db.String(15), nullable=True)
cup = db.Column(db.String(15), nullable=True)

# Metadata
created_by = db.Column(db.Integer, db.ForeignKey("users.id"), nullable=False)
created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
Expand Down Expand Up @@ -108,6 +112,14 @@ def __init__(self, invoice_number, project_id, client_name, due_date, created_by
self.vat_category = kwargs.get("vat_category")
self.vat_exemption_reason = kwargs.get("vat_exemption_reason")
self.vat_exemption_code = kwargs.get("vat_exemption_code")
self.cig = kwargs.get("cig")
self.cup = kwargs.get("cup")
if "subtotal" in kwargs and kwargs.get("subtotal") is not None:
self.subtotal = Decimal(str(kwargs["subtotal"]))
if "tax_amount" in kwargs and kwargs.get("tax_amount") is not None:
self.tax_amount = Decimal(str(kwargs["tax_amount"]))
if "total_amount" in kwargs and kwargs.get("total_amount") is not None:
self.total_amount = Decimal(str(kwargs["total_amount"]))

def __repr__(self):
return f"<Invoice {self.invoice_number} ({self.client_name})>"
Expand Down
116 changes: 116 additions & 0 deletions app/models/invoice_sdi.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
"""FatturaPA / SDI transmission audit model."""

from datetime import datetime

from app import db

# Terminal statuses that no longer need polling
SDI_FINAL_STATUSES = frozenset({"delivered", "not_delivered", "rejected", "accepted", "refused", "expired", "failed"})

# Map SDI notification types to transmission status
SDI_NOTIFICATION_STATUS = {
"RC": "delivered", # Ricevuta di consegna
"NS": "rejected", # Notifica di scarto
"MC": "not_delivered", # Mancata consegna (still legally issued)
"NE": "accepted", # Notifica esito (accepted or refused — refined by detail)
"DT": "expired", # Decorrenza termini
"AT": "failed", # Attestazione di trasmissione con impossibilità di recapito
}


class InvoiceSdiTransmission(db.Model):
"""Track SDI (FatturaPA) sends for an invoice."""

__tablename__ = "invoice_sdi_transmissions"

id = db.Column(db.Integer, primary_key=True)
invoice_id = db.Column(db.Integer, db.ForeignKey("invoices.id"), nullable=False, index=True)

filename = db.Column(db.String(100), nullable=True)
progressivo = db.Column(db.String(10), nullable=True)
formato = db.Column(db.String(5), nullable=True) # FPR12 | FPA12
xml = db.Column(db.Text, nullable=True)
xml_sha256 = db.Column(db.String(64), nullable=True)

# pending, sent, delivered, not_delivered, rejected, accepted, refused, expired, failed
status = db.Column(db.String(20), nullable=False, default="pending", index=True)

sdi_identifier = db.Column(db.String(100), nullable=True)
message_id = db.Column(db.String(200), nullable=True)
notifications = db.Column(db.JSON, nullable=True)
error_message = db.Column(db.Text, nullable=True)

created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
sent_at = db.Column(db.DateTime, nullable=True)
updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)

invoice = db.relationship("Invoice", backref=db.backref("sdi_transmissions", lazy="dynamic"))

def mark_sent(self, message_id=None, sdi_identifier=None, response_payload=None):
self.status = "sent"
self.sent_at = datetime.utcnow()
self.updated_at = datetime.utcnow()
if message_id:
self.message_id = str(message_id)
if sdi_identifier:
self.sdi_identifier = str(sdi_identifier)
if response_payload is not None:
notes = list(self.notifications or [])
notes.append({"type": "send_response", "payload": response_payload, "date": datetime.utcnow().isoformat()})
self.notifications = notes

def mark_failed(self, error_message, response_payload=None):
self.status = "failed"
self.updated_at = datetime.utcnow()
self.error_message = str(error_message) if error_message is not None else "Unknown error"
if response_payload is not None:
notes = list(self.notifications or [])
notes.append({"type": "error", "payload": response_payload, "date": datetime.utcnow().isoformat()})
self.notifications = notes

def apply_notification(self, notif_type: str, detail=None, date=None):
"""Apply an SDI notification type (RC/NS/MC/NE/DT/AT) and update status."""
ntype = (notif_type or "").strip().upper()
notes = list(self.notifications or [])
notes.append(
{
"type": ntype,
"detail": detail,
"date": date or datetime.utcnow().isoformat(),
}
)
self.notifications = notes
self.updated_at = datetime.utcnow()

if ntype == "NE":
# Notifica esito: detail may indicate acceptance or refusal
detail_s = str(detail or "").lower()
if any(x in detail_s for x in ("rifiut", "refus", "ec02", "reject")):
self.status = "refused"
else:
self.status = "accepted"
return

mapped = SDI_NOTIFICATION_STATUS.get(ntype)
if mapped:
self.status = mapped
if ntype == "NS" and detail:
self.error_message = str(detail)[:2000]

def to_dict(self):
return {
"id": self.id,
"invoice_id": self.invoice_id,
"filename": self.filename,
"progressivo": self.progressivo,
"formato": self.formato,
"xml_sha256": self.xml_sha256,
"status": self.status,
"sdi_identifier": self.sdi_identifier,
"message_id": self.message_id,
"error_message": self.error_message,
"notifications": self.notifications,
"created_at": self.created_at.isoformat() if self.created_at else None,
"sent_at": self.sent_at.isoformat() if self.sent_at else None,
"updated_at": self.updated_at.isoformat() if self.updated_at else None,
}
26 changes: 26 additions & 0 deletions app/models/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,15 @@ class Settings(db.Model):
company_country = db.Column(db.String(2), default="", nullable=True) # ISO 3166-1 alpha-2
company_iban = db.Column(db.String(34), default="", nullable=True)
company_bic = db.Column(db.String(11), default="", nullable=True)
# Italian FatturaPA / SDI company fields
company_codice_fiscale = db.Column(db.String(16), default="", nullable=True)
company_regime_fiscale = db.Column(db.String(4), default="RF01", nullable=True)
company_provincia = db.Column(db.String(2), default="", nullable=True)
sdi_enabled = db.Column(db.Boolean, default=False, nullable=False)
sdi_transport_url = db.Column(db.String(500), default="", nullable=True)
sdi_transport_token = db.Column(db.String(255), default="", nullable=True)
sdi_transmitter_id = db.Column(db.String(16), default="", nullable=True)
sdi_timeout = db.Column(db.Integer, default=30, nullable=True)

# PDF template customization
invoice_pdf_template_html = db.Column(db.Text, default="", nullable=True)
Expand Down Expand Up @@ -323,6 +332,14 @@ def __init__(self, **kwargs):
self.company_country = kwargs.get("company_country", "")
self.company_iban = kwargs.get("company_iban", "")
self.company_bic = kwargs.get("company_bic", "")
self.company_codice_fiscale = kwargs.get("company_codice_fiscale", "")
self.company_regime_fiscale = kwargs.get("company_regime_fiscale", "RF01")
self.company_provincia = kwargs.get("company_provincia", "")
self.sdi_enabled = kwargs.get("sdi_enabled", False)
self.sdi_transport_url = kwargs.get("sdi_transport_url", "")
self.sdi_transport_token = kwargs.get("sdi_transport_token", "")
self.sdi_transmitter_id = kwargs.get("sdi_transmitter_id", "")
self.sdi_timeout = kwargs.get("sdi_timeout", 30)

# PDF template customization
self.invoice_pdf_template_html = kwargs.get("invoice_pdf_template_html", "")
Expand Down Expand Up @@ -673,6 +690,14 @@ def to_dict(self):
"company_country": getattr(self, "company_country", "") or "",
"company_iban": getattr(self, "company_iban", "") or "",
"company_bic": getattr(self, "company_bic", "") or "",
"company_codice_fiscale": getattr(self, "company_codice_fiscale", "") or "",
"company_regime_fiscale": getattr(self, "company_regime_fiscale", "") or "RF01",
"company_provincia": getattr(self, "company_provincia", "") or "",
"sdi_enabled": bool(getattr(self, "sdi_enabled", False)),
"sdi_transport_url": getattr(self, "sdi_transport_url", "") or "",
"sdi_transport_token_set": bool(getattr(self, "sdi_transport_token", "")),
"sdi_transmitter_id": getattr(self, "sdi_transmitter_id", "") or "",
"sdi_timeout": getattr(self, "sdi_timeout", None),
"invoice_prefix": self.invoice_prefix,
"invoice_number_pattern": self.invoice_number_pattern,
"invoice_start_number": self.invoice_start_number,
Expand Down Expand Up @@ -763,6 +788,7 @@ def to_dict(self):
_SECRET_FIELDS = (
"mail_password",
"peppol_access_point_token",
"sdi_transport_token",
"ai_api_key",
"jira_client_secret",
"slack_client_secret",
Expand Down
Loading
Loading