Writing a provider¶
Providers are discovered automatically: write a package under
pretix_ptinvoicing/providers/<name>/ containing a subclass of
pretix_ptinvoicing.providers.base.InvoiceProvider. Nothing to register, no migration.
pretix_ptinvoicing/providers/acme/
├── __init__.py # settings form + provider class
├── client.py # thin HTTP wrapper
├── payload.py # pretix Order → request body (pure functions)
└── urls.py # optional: the provider's own views (e.g. an OAuth callback)
The contract¶
| Member | Purpose |
|---|---|
identifier / verbose_name |
Stored settings value and admin-facing label. |
settings_form_class |
A pretix SettingsForm. Prefix field names by hand (acme_api_key) — pretix event settings are one flat namespace. |
deduplicates_issuance |
True only if the API itself rejects a second document for the same identifier_id. |
recovers_documents / find_document(identifier_id, kind, since) |
Optional. Set the flag and implement the method if the API can be asked for the closed document already issued under identifier_id (kind is "invoice" or "credit_note", since the time of the first attempt). The core then looks before any attempt that could duplicate and adopts what it finds. |
is_configured |
False while not set up; issuance then records an error row saying so. The base class derives in_use from it (selected as the event's provider and configured), which drives the settings page's "Not in use yet" notice. |
issue(order, identifier_id) |
Issue the invoice-receipt; return an IssuedDocument. |
credit(order, document_id, identifier_id) |
Issue a credit note for the full document. |
download(document_id) |
Return the PDF bytes. Make sure they are a PDF — some APIs link to an HTML download page. |
lookups(data) |
Optional. Live dropdowns for the settings page. |
document_number(document_id) |
Optional. The number people read (e.g. FR M2026/20), built only from what the API returns. Called right after issuance, so it must never raise: return None on failure. |
logo |
Optional. Static path of the logo on the settings page's provider card; without one the card shows verbose_name. |
lookup_triggers |
Optional. lookups() fields whose value changes what lookups() returns (Moloni's company). Changing one re-runs the lookup. |
settings_template |
Optional. A template rendered at the top of the provider's settings, with the provider as provider — for what isn't a form field (Moloni's connect button). |
hidden_settings_fields() |
Optional. Settings fields to leave off the page right now. They're dropped from the form, so saving keeps their stored values. |
keepalive() |
Optional. Called about once a day per connection (see connection_holder), e.g. to refresh an expiring token. Return True if the connection is dead, and the contact address of each event using it is e-mailed to reconnect. |
stored_keys |
Optional. Settings keys the provider stores beside its form's fields (cached tokens), so Use the organizer's settings removes them from an event too. |
connection_holder |
Optional. The event or organizer whose connection keepalive() keeps alive; the base class returns the holder. Override it when a connection can be inherited, so one shared by several events is refreshed once. |
reference_limit / reference_limit_field |
Optional, for a provider with a product catalog: how long prefix + product reference may be (None without a limit), and the settings field that holds it, for the settings page's live note. |
item_fields() |
Optional. Extra form fields for the Invoicing (PT) tab on pretix's product page; their values come back on each line as Line.item_settings. |
discount_places |
Decimals the API keeps of a line's percentage discount (default 2). The core rounds to it and compensates in the net price. |
A provider is constructed with a holder: an event, or an organizer on the organizer's settings
page. self.holder is that object, self.event the event (None for an organizer),
self.organizer the organizer, and self.settings the holder's settings store (writable). An
event's store falls back to its organizer's, so reading needs no special care. An organizer-held
provider is only ever asked for lookups() and connecting; documents are always issued for an
event.
IssuedDocument has document_id, link, permanent_url and number. A provider that fills
number itself can skip document_number(); the bundled ones call it from issue() and credit().
The identifier_id the core passes is stable per document: a retry gets the same one. An order paid
again after a credited refund gets a new invoice, and with it a new identifier_id (…-r1, …), so
pass it through to the API's dedup field unchanged.
Provider URLs¶
A provider that needs its own views (an OAuth callback, a connect button) lists them in
providers/<name>/urls.py. The core adds every provider's urlpatterns to the plugin's, so names
reverse as plugins:pretix_ptinvoicing:<name> and the core never names a provider. Prefix URL names
with the provider's identifier (acme_connect), since they share one namespace. Use the full
Control-panel path, as the core does. A view that should also work on the organizer's settings
page needs a second route under control/organizer/<str:organizer>/invoicing/settings/…; Moloni's
providers/moloni/views.py shows the pattern (one mixin with the logic, one small class per
holder).
from django.urls import path
from . import views
urlpatterns = [
path(
"control/event/<str:organizer>/<str:event>/invoicing/settings/acme/connect/",
views.ConnectView.as_view(),
name="acme_connect",
),
]
A minimal provider¶
A made-up "Acme" API, showing every method.
from django import forms
from django.utils.translation import gettext_lazy as _
from pretix.base.forms import SettingsForm
from ...orderdata import bare_tin, client_name, invoice_lines
from ..base import InvoiceProvider, IssuedDocument, ProviderError
from .client import AcmeClient
class AcmeSettingsForm(SettingsForm):
# Field names are the storage keys — namespace them by hand.
acme_api_key = forms.CharField(
label=_("API key"), widget=forms.PasswordInput(render_value=True)
)
acme_sandbox = forms.BooleanField(label=_("Use sandbox"), required=False)
acme_tax_id = forms.IntegerField(
label=_("VAT rate (Acme)"),
help_text=_("Populated automatically once the API key is valid."),
)
class AcmeProvider(InvoiceProvider):
identifier = "acme"
verbose_name = "Acme Invoicing"
settings_form_class = AcmeSettingsForm
deduplicates_issuance = True # Acme rejects a repeated `external_id`
@property
def is_configured(self):
return bool(self.settings.get("acme_api_key") and self.settings.get("acme_tax_id"))
def _client(self):
return AcmeClient(
api_key=self.settings.get("acme_api_key"),
sandbox=self.settings.get("acme_sandbox", as_type=bool, default=False),
)
def issue(self, order, identifier_id):
tin = bare_tin(
order,
custom_field_is_nif=self.settings.get(
"ptinvoicing_nif_custom_field", as_type=bool, default=False
),
)
result = self._client().create_invoice_receipt(
{
"external_id": identifier_id, # the API's dedup field
"customer": {"name": client_name(order), "vat": tin},
"lines": [
{
"description": line.name,
"quantity": line.qty,
# Net unit price before the line discount; the core chose it so
# that the document adds up to what was paid.
"unit_price": format(line.price_net, "f"),
"discount_percent": format(line.discount, "f"),
"tax_id": self.settings.get("acme_tax_id", as_type=int),
}
for line in invoice_lines(order, discount_places=self.discount_places)
],
}
)
return IssuedDocument(
document_id=str(result["id"]),
link=result.get("pdf_url"),
permanent_url=result.get("public_url"),
)
def credit(self, order, document_id, identifier_id):
result = self._client().credit_document(document_id, external_id=identifier_id)
return IssuedDocument(document_id=str(result["id"]), link=result.get("pdf_url"))
def download(self, document_id):
return self._client().download_pdf(document_id)
def lookups(self, data):
# `data` is what the admin has typed (prefix stripped), not what's saved.
api_key = (data.get("acme_api_key") or "").strip()
if not api_key:
raise ProviderError(_("No API key provided."))
client = AcmeClient(api_key=api_key, sandbox=data.get("acme_sandbox") == "true")
return {
"acme_tax_id": [
{"id": t["id"], "label": f"{t['name']} ({t['rate']}%)"}
for t in client.list_taxes()
]
}
Use the shared order helpers
pretix_ptinvoicing.orderdata has the provider-independent buyer data: bare_tin (the NIF,
without a PT prefix, honouring the custom-field setting), client_name (company, then name,
then "Consumidor Final"), is_valid_pt_nif, one_line(value, limit) and FINAL_CONSUMER_NIF.
invoice_lines(order, discount_places=) returns what to invoice as Lines: every position
and fee, identical tickets grouped, free lines dropped, vouchers and discounts turned into
price_net plus a percentage discount. Build your items from it rather than from
order.positions, and add reference_prefix(event) in front of Line.catalog_key if your
API has a product catalog. Never import from another provider's package.
Errors: rejection vs. transient¶
The task decides what to do from the exception type alone. providers.base defines both:
| Raised | Meaning | Task behaviour |
|---|---|---|
ProviderError |
The provider refused the request | Marked error, shown to the admin, not retried |
ProviderUnreachable (or anything else) |
Transient failure: network error, timeout | Marked error and retried 3× (2 min apart) if deduplicates_issuance or recovers_documents; otherwise left for a human, with a "check in the provider before retrying" message |
Wrap API-level rejections in a ProviderError subclass, passing the per-field errors as detail so
the Control panel shows them:
import requests
from django.utils.translation import gettext_lazy as _
from ..base import ProviderError
class AcmeAPIError(ProviderError):
pass
class AcmeClient:
timeout = 30
def __init__(self, api_key, sandbox=False):
self.api_key = api_key
self.base_url = "https://sandbox.acme.test" if sandbox else "https://api.acme.test"
def _request(self, method, path, payload=None):
# Network errors are left to propagate: they are transient.
response = requests.request(
method,
f"{self.base_url}{path}",
json=payload,
headers={"Authorization": f"Bearer {self.api_key}"},
timeout=self.timeout,
)
if 400 <= response.status_code < 500:
body = response.json()
raise AcmeAPIError(
body.get("message") or _("Rejected by Acme"),
detail=body.get("errors"), # e.g. {"customer.vat": "invalid"}
http_status=response.status_code,
)
response.raise_for_status() # 5xx → transient
return response.json()
def create_invoice_receipt(self, payload):
return self._request("POST", "/invoice-receipts", payload)
def credit_document(self, document_id, external_id):
return self._request("POST", f"/documents/{document_id}/credit", {"external_id": external_id})
def list_taxes(self):
return self._request("GET", "/taxes")["data"]
def download_pdf(self, document_id):
try:
response = requests.get(
f"{self.base_url}/documents/{document_id}/pdf",
headers={"Authorization": f"Bearer {self.api_key}"},
timeout=self.timeout,
)
response.raise_for_status()
except requests.RequestException as e:
# download() is called from a view, which only catches ProviderError.
raise AcmeAPIError(_("Could not download the document: %(e)s") % {"e": e})
return response.content
Note
The bundled Fact.pt and Moloni clients raise ProviderUnreachable for requests failures.
Prefer it over a bare requests exception in yours too: anything that swallows lookup errors
(the settings page, the daily keepalive) catches both types, and nothing else.
deduplicates_issuance and retries
If your API has no field it dedupes on, set deduplicates_issuance = False. A request that timed
out may still have created the document, and a blind retry would issue a second official
invoice. With the flag off, a failure waits for a human to check and press Retry, unless
the provider recovers_documents: implement find_document() (Moloni searches its documents
by reference) and the core asks before every attempt, which makes automatic retries safe
again. Return only closed, issued documents from it, never drafts. A provider that does
dedupe can implement it too (Fact.pt does): it is then asked on re-attempts only, to link back
a document that a timed-out call created.
Refreshing credentials¶
self.settings is writable, so a provider with expiring OAuth tokens can cache them per event
instead of logging in on every issuance:
def _access_token(self):
token = self.settings.get("acme_access_token")
expires = self.settings.get("acme_access_expires", as_type=float, default=0)
if token and expires > time.time() + 60:
return token
data = AcmeClient.login(
self.settings.get("acme_username"), self.settings.get("acme_password")
)
self.settings.set("acme_access_token", data["access_token"])
self.settings.set("acme_access_expires", time.time() + data["expires_in"])
return data["access_token"]
Keep cached tokens out of settings_form_class so the settings page doesn't render or overwrite
them, and list their keys in stored_keys.
Inherited credentials
An event may be using its organizer's credentials. Reading through self.settings handles
that, but a write lands on the event. For a token that is rotated (refreshing spends the old
one), that would leave the organizer and its other events holding a dead token. Check
self.inherits(key) and write to self.organizer.settings when the value came from there;
Moloni's connection_holder and _client(store=) are the worked example.
Testing¶
Put provider tests in tests/test_<name>_*.py, and mock HTTP with
responses. Select the provider and configure its
credentials, or the task skips the order:
import responses
from django_scopes import scopes_disabled
from pretix_ptinvoicing.models import IssuedInvoice
from pretix_ptinvoicing.tasks import issue_invoice
@responses.activate
def test_issue(event, order):
event.settings.ptinvoicing_provider = "acme"
event.settings.acme_api_key = "k"
event.settings.acme_tax_id = 1
responses.add(
responses.POST,
"https://api.acme.test/invoice-receipts",
json={"id": 42, "pdf_url": "https://acme.test/42.pdf"},
)
issue_invoice.apply(kwargs={"order_pk": order.pk, "event_pk": event.pk})
with scopes_disabled():
invoice = IssuedInvoice.objects.get(order=order)
assert invoice.status == IssuedInvoice.STATUS_SUCCESS
assert invoice.document_id == "42"
@responses.activate
def test_rejection_is_terminal(event, order):
event.settings.ptinvoicing_provider = "acme"
event.settings.acme_api_key = "k"
event.settings.acme_tax_id = 1
responses.add(
responses.POST,
"https://api.acme.test/invoice-receipts",
status=422,
json={"message": "bad", "errors": {"customer.vat": "invalid"}},
)
issue_invoice.apply(kwargs={"order_pk": order.pk, "event_pk": event.pk})
with scopes_disabled():
invoice = IssuedInvoice.objects.get(order=order)
assert invoice.status == IssuedInvoice.STATUS_ERROR
assert invoice.attempts == 1