Instellix · API Cheat Sheet

Case Study-Kategorien

Schnellzugriff nach Integrationsaufgabe
Kategorie	Kundenfrage / Aufgabe	Einstieg
Customers / Identity	Welcher Kunde gehört zu diesem App-User?	Customer lesen; lokale Identitätszuordnung
Contracts	Welche Verträge laufen für den Kunden?	Verträge suchen; Details und Lifecycle
Documents	Welche Rechnungen und Gutschriften gibt es?	Dokumente filtern; strukturierten Beleg lesen
Files / PDF	Wie öffne ich den Beleg?	Archivierte Datei über fileIdent abrufen
Payments	Ist eine Zahlung ausgeführt und zugeordnet?	Intent, Settlement und Assignment unterscheiden
Dunning / OPOS	Was ist offen, was wird gemahnt?	OPOS-Fall, Mahnstufe und Sperren
Webhooks	Wann aktualisiere ich den App-Status?	Events empfangen; Notification-Log prüfen

API-Zugang

Für alle KategorienBack to top

POST

`/{realm}/oauth2/token`

Token beziehen, anschließend Bearer verwenden

Authentifizierung

Basic Auth mit client_id:client_secret; Grant client_credentials. Token bis zum Ablauf wiederverwenden. expires_in ist in Sekunden angegeben.

API-Aufrufe

Authorization: Bearer <access_token>

Offizielle Referenz

Identifikatoren ohne Verwechslung

Route und Feldnamen sind maßgeblichBack to top

Schlüssel-Mapping — Details und Quellen in den Kategorieblöcken
Schlüssel	Bedeutung	Verwendung
`ident / debtorIdent`	Externe Customer-Referenz	Customer lesen; Customer am Vertrag / CPA referenzieren
`contractIdent`	Externer, unveränderlicher Contract-Schlüssel	Contract-Suche; Lifecycle-Aktionen gemäß Route
`contractId`	Numerische interne Contract-ID	Contract-PATCH
`documentIdent / fileIdent`	Document-Ident; Files-Referenz entspricht der Beleg-Ident	JSON-Beleg und PDF abrufen
`paymentIntentIdent`	Schlüssel des Payment Intent	Retry / Cancel
`oposCaseIdent`	Schlüssel eines OPOS-Falls	Mahnsperre; Decisions
`Idempotency-Key`	Stabiler Notification-Schlüssel	Webhook-Duplikate erkennen

Customers / Identity

Kunde und App-User sicher zuordnenBack to top

GET

`/v2/customers/{ident}`

Einen Kunden über die externe Referenz lesen

Löst

Customer-Stammdaten für das Kundenprofil abrufen. ident ist der externe Kundenschlüssel.

Parameter

slimResponse=false ist Standard; true lässt verschachtelte Collections weg.

Offizielle Referenz

GET

`/v2/customers/pageable`

Kunden gezielt suchen

Query

search=ident=='client123' · pageNumber=0 · pageSize=100 · orderBy=ident · direction=DESC.

Listen sind standardmäßig slim; vollständige verschachtelte Listen werden in der Referenz nicht empfohlen.

Offizielle Referenz

POST

`/v2/customers`

Customer anlegen

Eindeutige ident und mindestens eine Adresse. Adresstyp INVOICE oder SHIPPING; der Typ ist nach Anlage unveränderlich. addressIdent kann automatisch generiert werden.

Offizielle Referenz

Contracts

Vertragsdaten und LifecycleBack to top

GET

`/v2/contracts/pageable`

Verträge finden

Query

search=contractIdent=='contract123' · pageNumber=0 · pageSize=100 · orderBy=contractId · direction=DESC.

slimResponse=true ist Standard und lässt Attachments und Purchase Items weg.

Offizielle Referenz

POST

`/v2/contracts`

Customer mit einem Plan verbinden

Vorhandenen Customer und konfigurierten Plan referenzieren. contractIdent ist eindeutig und unveränderlich. Pflichtfelder enthalten contractIdent, date und optionQuantities. Ident-Referenzen wie debtorIdent und planIdent gegenüber deprecated Numeric-Referenzen bevorzugen.

Offizielle Referenz

PATCH

`/v2/contracts/{contractId}`

Bestehenden Vertrag aktualisieren

Hier steht die numerische contractId im Pfad. Ein Update von properties ersetzt die gesamte Liste. Deprecated startDate / endDate nicht als Lifecycle-Steuerung verwenden: Activation / Termination sind die vorgesehenen Aktionen.

Offizielle Referenz

Documents

Strukturierter Beleg, noch keine DateiBack to top

GET

`/v2/documents`

Rechnungen und andere Belege auflisten

Query

search=type==INVOICE · page=0 · size=20 (maximal 100) · sort=ident,asc.

Sortierkriterien sind wiederholbar. Diese Route verwendet page / size, nicht pageNumber / pageSize.

Offizielle Referenz

GET

`/v2/documents/{documentIdent}`

Strukturierten Beleg lesen

Dokumentdaten über die documentIdent abrufen. Für das PDF anschließend die Files-Route nutzen; der Document-Abruf ersetzt keinen Dateidownload.

Offizielle Referenz

Files / PDF

Archivierten Output ausliefernBack to top

GET

`/v2/files/{fileIdent}`

Rechnung als PDF öffnen

Schlüssel

fileIdent entspricht laut Referenz der Document-Ident / invoiceIdent. Keine neue Datei-ID erfinden.

Header

Für PDF explizit Accept: application/pdf setzen. Die dokumentierte Accept-Vorgabe ist application/json.

Abrufvorlage

curl "$BASE/v2/files/$DOCUMENT_IDENT" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/pdf' \
  --output invoice.pdf

Offizielle Referenz

Payments

Charging, Settlement und Assignment trennenBack to top

POST

`/v2/customer-payment-accounts`

Tokenisierte Zahlungsreferenz hinterlegen

CPA für debtorIdent anlegen. merchantPaymentGatewayIdent und paymentProviderReference werden benötigt. ident kann generiert werden. displayName darf keine vollständigen Karten- oder IBAN-Daten enthalten.

Offizielle Referenz

GET

`/v2/payment-intents`

Payment Intents suchen

Paginierte Suche mit RSQL search. Intent-Status beschreibt den Ausführungsprozess; für Settlement und Zuordnung die entsprechenden Ressourcen prüfen.

Offizielle Referenz

GET

`/v2/payment-assignments`

Zahlungszuordnung nachverfolgen

search (RSQL), page=0, size=10 (maximal 100), sort=ident.

Offizielle Referenz

Weitere dokumentierte Operationen

Payment-Operationen
Methode / Route	Zweck / Caveat
`POST /v2/payment-intents`	Intent anlegen; Schema
`POST /v2/payment-intents/{paymentIntentIdent}/actions/retry`	Nur im Status `FAILED`; Retry
`POST /v2/payment-intents/{paymentIntentIdent}/actions/cancel`	Nur im Status `FAILED`; Cancel
`GET /v2/settlement-reports`	Reports suchen; Settlement
`POST /v2/payment-assignments`	Manuelle Zuordnung zu `DOCUMENT` oder `ORDER`; Assignment

Dunning / OPOS

Offene Posten, Mahnungen und SperrenBack to top

GET

`/v2/opos-cases`

Offene-Posten-Fälle suchen

RSQL search; page=0, size=20, sort=initialDocumentIdent,ASC. Mehrere Sortierkriterien sind möglich.

Offizielle Referenz

PUT

`/v2/opos-cases/{oposCaseIdent}/dunning-block`

Mahnsperre setzen oder entfernen

Body — Beispiel

{ "active": true, "note": "Review pending" }

active ist Pflicht; note ist optional und maximal 100 Zeichen lang.

Offizielle Referenz

POST

`/v2/opos-cases/{oposCaseIdent}/decisions`

Fachliche Entscheidung erfassen

Eindeutige ident und type sind erforderlich. Zulässige Typen hängen vom DEBIT-/CREDIT-Saldo ab. Bei aktivem Prebooked Item ist amount Pflicht; sonst wird ohne Angabe der Case-Saldo verwendet.

Offizielle Referenz

Entscheidungen nachvollziehen

GET /v2/opos-cases/{oposCaseIdent}/decisions — Liste
GET /v2/opos-cases/{oposCaseIdent}/decisions/{decisionIdent} — Einzelentscheidung

Webhooks

Ereignisse empfangen und nachvollziehenBack to top

GET

`/v2/notifications`

Notification-Log abfragen

Query

search (RSQL), page ab 0, size standardmäßig 20, maximal 100.

Offizielle Referenz

POST

`/v2/notifications/{ident}/actions/resend`

Ein Ereignis erneut senden

Gezielter Resend einer Notification. Die Referenz zeigt noch einen Nitrobox-Host; den API-Host aus dem Onboarding verwenden.

Offizielle Referenz

Relevante Event-Namen

Auswahl dokumentierter Events
Bereich	Technischer Identifier
Customers	`customer.created` · `customer.updated`
Contracts	`contract.created` · `contract.updated` · `contract.terminated`
Documents	`invoice.created` · `invoice.updated` · `invoice.archived`
Payments	`paymentIntent.result` · `paymentAssignment.processed` · `paymentAssignment.reversed`
Dunning / OPOS	`dunning.issued` · `dunning.archived` · `OPOS_CASE_UPDATED`

Query-Merkzettel

RSQL-Dokumentation Back to top

RSQL: == gleich, != ungleich, =gt= größer, ; UND, , ODER. String-Werte in Anführungszeichen setzen und Query-Werte URL-encodieren.

curl --get "$BASE/v2/contracts/pageable" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "search=contractIdent=='$CONTRACT_IDENT'" \
  --data-urlencode 'pageSize=20'

Shell-Vorlage: BASE, TOKEN und CONTRACT_IDENT vorher mit eigenen Werten belegen.

Pagination und Sortierung je Route prüfenDie generische RSQL-Seite nennt orderBy und direction; einzelne Operationen nutzen sort. Parameter nicht pauschal übertragen. ODER- und Properties-Suchen können langsam sein.

Empfehlung: Suchfelder und Identifikatoren nur aus der passenden Operation übernehmen. App-User dürfen den Kundenscope eines Filters nicht selbst bestimmen.