Skip to content

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).

providers/acme/urls.py
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.

providers/acme/__init__.py
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:

providers/acme/client.py
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:

tests/test_acme.py
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