REST-API-Referenz

Überblick

TaprNext stellt Frappe-ähnliche RPC-Methoden unter /api/method/... und Standard-Resource-APIs unter /api/resource/... bereit. Für Integrationen bevorzugen Sie die dokumentierten PEPPOL- und Rechnungsmethoden.

Authentifizierung

Authorization: token <api_key>:<api_secret>

Erzeugen Sie Schlüssel für einen Benutzer mit den richtigen Rollen und Legal-Entity-Berechtigungen. Basis-URL:

https://your-site.tapr.ch

PEPPOL-Übertragung

Methode	Pfad	Hinweise
Rohes XML oder Factur-X-PDF senden	`POST /api/method/tapr_next.api.peppol.transmission.send_peppol_invoice`	Query: `receiver_id`, `sender_id`, `country_code`; bei XML auch `doc_type_id`, `process_id`. Body: XML oder PDF. Metered.
SI aus XML anlegen und senden	`POST /api/method/tapr_next.api.peppol.transmission.send_invoice`	Vollständiger Create-and-Send-Flow aus übermitteltem XML
Lieferung / Status	`GET/POST /api/method/tapr_next.api.peppol.transmission.check_status`	`reference_id`
XML validieren	`POST /api/method/tapr_next.api.peppol.transmission.validate_xml`	Body: XML

Beispiel — direkter AS4-Versand (XML)

POST /api/method/tapr_next.api.peppol.transmission.send_peppol_invoice?receiver_id=9930:DE123&sender_id=9927:CHE123&country_code=CH&doc_type_id=...&process_id=urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
Authorization: token key:secret
Content-Type: application/xml

PEPPOL eingehend & Dokumente

Methode	Pfad
Empfangen (API-Storage-Modus)	`POST /api/method/tapr_next.api.peppol.inbound.receive_peppol_message`
Empfangene Rechnungen auflisten	`tapr_next.api.peppol.inbound.get_received_invoices`
Eine empfangene Rechnung abrufen	`tapr_next.api.peppol.inbound.get_received_invoice` — `name` oder `reference_id`; liefert Kopf, Summen sowie `items` / `charges` / `taxes`; `include_xml=1` ergänzt `raw_xml`
Externe Buchung bestätigen	`tapr_next.api.peppol.inbound.confirm_invoice_posted`
SMP-Lookup (metered)	`tapr_next.api.peppol.lookup.lookup_participant`
SMP-Lookup (intern)	`tapr_next.api.peppol.lookup.lookup_peppol_participant`
Empfängerformate	`tapr_next.api.peppol.documents.get_peppol_receiver_formats`
Dokumentformat setzen	`tapr_next.api.peppol.documents.set_peppol_document_format`
Rechnungs-XML auf SI/PI validieren	`tapr_next.api.peppol.documents.validate_invoice_xml`

Webhooks

Methode	Pfad
Webhook konfigurieren	`tapr_next.api.peppol.webhooks.configure_webhook` (System Manager)
Zustellung erneut auslösen	`tapr_next.api.peppol.webhooks.retrigger_webhook`

Event-Typen umfassen Invoice Received, MLR Received und All. Auth-Optionen: none, bearer, API-Key-Header, basic; optional HMAC-Secret.

Verkaufs- und Einkaufsrechnungen (UI/Backend)

Methode	Pfad
Hochgeladene Datei verarbeiten	`tapr_next.api.invoices.process_uploaded_file` (`invoice_type`: `purchase` \| `sales`)
Entwurf aus New-Invoice-Formular anlegen	`tapr_next.api.invoices.create_draft_invoice` — `peppol_receiver_id` ist bei einer Sales Invoice Pflicht und bei einer Purchase Invoice optional. Optionales `peppol_registration` wählt die eigene PEPPOL-ID der Legal Entity (Absender bei SI, Empfänger bei PI) und muss eine aktive Registrierung dieser Entity sein
Rechnung duplizieren	`tapr_next.api.invoices.duplicate_invoice`
Workflow anwenden	`tapr_next.api.workflow.apply_workflow_action`
Workflow-Status / -Aktionen	`tapr_next.api.workflow.*`

Resource API (Frappe)

POST /api/resource/Sales Invoice
GET  /api/resource/Sales Invoice?filters=...
GET  /api/resource/Purchase Invoice/<name>

JSON-Bodies entsprechend den DocType-Feldern verwenden (Legal Entity, Positionen, PEPPOL Receiver ID, Summen). Server-Validate-Hooks berechnen in vielen Fällen Steuern/Summen neu — bevorzugt saubere Positionsdaten senden.

ERP-Helfer

Methode	Zweck
`tapr_next.api.erp.lookup_purchase_order`	Bestelllookup
`tapr_next.api.erp.lookup_vendor`	Lieferantenlookup
`tapr_next.api.erp.get_erp_vendors` / `get_erp_items` / `get_erp_currencies` / `get_erp_purchase_orders`	ERP-Stammdaten-Suche

ERP-Activity-Push

Der ERP-Sync läuft sonst nach Zeitplan: AR-Rechnungen alle 10 Minuten, ausstehende AP-Buchungen stündlich. Ein ERP kann diesen Endpunkt aufrufen, um diese Jobs für eine Legal Entity sofort zu starten. Die Zeitpläne laufen als Sicherheitsnetz weiter.

POST /api/method/tapr_next.api.erp_events.notify_erp_activity
Authorization: token <api_key>:<api_secret>
Content-Type: application/json

{"event_type": "invoice.ready", "erp_type": "erpnext", "legal_entity": "Your Company AG", "reference": "ACC-SINV-2026-00042"}

Parameter	Pflicht	Hinweise
`event_type`	Ja	`invoice.ready` → AR-Fetch; `invoice.posted` → AR-Fetch + ausstehende AP-Buchungen; `invoice.paid`, `invoice.cancelled` → ausstehende AP-Buchungen. Andere Werte liefern `status: "ignored"`
`erp_type`	Ja	Muss dem ERP-Typ der Setup-Zeile der Legal Entity entsprechen (`erpnext`, `d365`, …)
`legal_entity`	Ja	Name der Legal Entity oder der in der Setup-Zeile hinterlegte ERP-Firmenname
`reference`, `event_id`, `occurred_at`	Nein	Nur fürs Log

Die Antwort hat immer dieselben Schlüssel: status (accepted / ignored / error), message, legal_entity, event_type, jobs, duplicate_jobs, duplicate. Ein bereits eingereihter Job für diese Entity wird nicht doppelt eingereiht. Aufrufer brauchen System Manager, Accounts Manager oder Sales Manager sowie Berechtigung auf die Legal Entity; Rate-Limit: 60 Aufrufe pro Minute je aufrufender IP und Legal Entity.

Locks & Presence

Methode	Zweck
`tapr_next.api.locks.acquire_invoice_lock`	Bearbeitungsmodus betreten
`tapr_next.api.locks.release_invoice_lock`	Freigeben
`tapr_next.api.locks.refresh_invoice_lock`	Keep-alive
`tapr_next.api.locks.get_invoice_lock_status`	Status
`tapr_next.api.locks.force_release_invoice_lock`	Admin-Unlock

Benutzer & Abonnement

Methode	Zweck
`tapr_next.api.user.get_current_user_roles`	Rollen des Session-Benutzers
`tapr_next.api.user.get_user_legal_entities`	Zulässige Legal Entities
`tapr_next.api.subscription.get_subscription_info`	Plan und Limits

Rate Limits und Metering

Einige PEPPOL-Methoden sind metered und zählen gegen Plan-Kontingente (Messages / API-Aufrufe).
Bei überschrittenen Kontingenten erwarten Sie HTTP-Fehler; Plan upgraden oder auf Reset warten.
Free-Plan-Defaults umfassen niedrige monatliche Message- und Benutzerlimits.

Best Practices

Dedizierten Integrationsbenutzer mit Least Privilege verwenden.
XML vor Produktionsversand validieren.
Idempotente Client-Keys nutzen, wo das Gateway sie unterstützt.
reference_id aus Sends für MLR-/Status-Korrelation protokollieren.
Validierungsfehler-Payloads auswerten — oft mit feldbezogenem PEPPOL-Regeltext.