Die API auf einen Blick
Vorgang auswählen, Ergebnis prüfen und Beispiel öffnen. Die vollständige Anleitung folgt darunter.
https://restapi.imaginaits.com/x-auth-token: YOUR_TOKEN| Methode | Endpunkt und Beispiel | Zweck | Was zu prüfen ist |
|---|---|---|---|
| POST | /puttransaction.phpcURL-Beispiel anzeigen | Zahlung oder Erstattung anlegenDetails anzeigen → | status=ok erfasst den Vorgang; anschließend den Status abfragen. |
| GET | /statustransaction.phpcURL-Beispiel anzeigen | Transaktion abfragenDetails anzeigen → | PENDING, PAID, CANCELLED oder ERROR in Cloud. |
| GET | /listtransactions.phpcURL-Beispiel anzeigen | Transaktionen auflistenDetails anzeigen → | Nach Status filtern und mit dem zurückgegebenen Cursor fortsetzen. |
| GET | /transactioncashflow.phpcURL-Beispiel anzeigen | Einzahlung, Auszahlung und Aufschlüsselung abfragenDetails anzeigen → | Gemeldete Beträge und Stückelungen dieser Transaktion. |
| GET | /inventory.phpcURL-Beispiel anzeigen | Gemeldeten Bestand abfragenDetails anzeigen → | currency, recyclable, stacker und updated_at, sofern verfügbar. |
| POST | /canceltransaction.phpcURL-Beispiel anzeigen | Bisherige kompatible StornierungDetails anzeigen → | ok oder CANCELLED allein bestätigen keine Stornierung am Gerät. |
| POST | /canceltransactionv2.phpcURL-Beispiel anzeigen | CancelTransactionV2: Stornierung mit Nachverfolgung anfordernDetails anzeigen → | operation_id und Idempotency-Key aufbewahren. 202 bedeutet ausstehend. |
| GET | /v2.php?action=capabilitiescURL-Beispiel anzeigen | Verfügbare Funktionen abfragenDetails anzeigen → | cancellation_tracking zeigt an, ob die Nachverfolgung aktiv ist. |
| GET | /v2.php?action=transactioncURL-Beispiel anzeigen | Transaktion und Nachverfolgung gemeinsam abfragenDetails anzeigen → | Trennt cloud_status von execution_confirmation. |
| GET | /v2.php?action=operationcURL-Beispiel anzeigen | Stornierungsanfrage abfragenDetails anzeigen → | confirmed, execution_state, cash_flow und requires_review. |
Grundablauf
- Zahlung anlegenamount: 2100 = 21,00 EUR. transaction_id aufbewahren.
- Ergebnis abfragenDieselbe Referenz abfragen; HTTP 200 allein reicht nicht.
- Bei ausstehender Zahlung stornierenCancelTransactionV2 liefert operation_id; bis confirmed=true abfragen.
202 = Anfrage erfasst. V1 CANCELLED = Cloud-Status. confirmed=true mit CONFIRMED_BY_IMACASH = vollständiger ImaCash-Abschlussbericht.
Kompatibilität
POST /v2.php?action=cancel bleibt mit demselben Vertrag verfügbar. Neue Integrationen verwenden CancelTransactionV2: /canceltransactionv2.php. Bestehende Integrationen müssen nicht geändert werden.
Vor dem Start
Wählen Sie REST API Imagina unter ImaCash Konfiguration > Integration. Cloud muss REST für die Lizenz und deren Wartung oder Testzeitraum zulassen. Kopieren Sie den Lizenz-Token, nicht das Administratorpasswort oder interne Connector-Geheimnis. Fehlt der Token, notieren Sie Version und numerische Lizenzreferenz und kontaktieren den Support; erstellen Sie keine weitere Buchung oder Demo zur Diagnose.
Verbindung, Token und Geltungsbereich
Die Basis-URL lautet https://restapi.imaginaits.com/. Senden Sie x-auth-token mit jeder HTTPS-Anfrage. Jeder Token gilt nur für seine Lizenz. Er gehört nicht in URLs, Screenshots, Protokolle, Repositories oder E-Mails. Die Beispiele verwenden YOUR_TOKEN und fiktive Referenzen. Die Dokumentation führt keine Vorgänge aus.
Referenzen und Beträge
transaction_id bezeichnet einen Vorgang Ihrer Anwendung und Lizenz dauerhaft: verwenden Sie nach einem Timeout exakt denselben Wert. user und terminal sind geschäftliche Bediener- und Arbeitsplatzreferenzen, keine Zugangsdaten oder ImaCash-Berechtigungen. amount verwendet Untereinheiten: 2100 sind 21,00 EUR, -2100 eine Erstattung von 21,00 EUR. method=1 bedeutet Bargeld, method=0 Karte; ein Karteneintrag beweist keine Bankzahlung.
Zahlung anlegen und abfragen
Senden Sie JSON mit transaction_id, amount, user, terminal und method. status=ok bestätigt die Cloud-Erfassung, keine abgeschlossene Zahlung. Fragen Sie dieselbe Referenz ab und prüfen HTTP sowie JSON. 409 beim Anlegen kann eine vorhandene Referenz bedeuten: fragen Sie diese ab und vergleichen die Daten, statt eine neue ID zu senden.
Beispiel · POST /puttransaction.php
curl --request POST 'https://restapi.imaginaits.com/puttransaction.php' \
--header 'x-auth-token: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"transaction_id":"TX-DEMO-20261029-001","amount":2100,"user":"OPERATOR-01","terminal":"DESK-01","method":1}'Beispiel · GET /statustransaction.php
curl 'https://restapi.imaginaits.com/statustransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Beispiel · GET /transactioncashflow.php
curl 'https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Kompatible V1-Stornierung
V1 behält POST /canceltransaction.php mit transaction_id als Query- oder Formularparameter, nicht als JSON. ok und CANCELLED beschreiben den Cloud-Eintrag, keine Gerätebestätigung. Manche Ablehnungen liefern HTTP 200 mit status=error. Eine spätere Abfrage von statustransaction oder transactioncashflow macht daraus keinen physischen Nachweis. Wurde bereits Geld angenommen, kann ImaCash die Stornierung aufschieben und die konfigurierte lokale Freigabe verlangen.
Beispiel · POST /canceltransaction.php
curl --request POST 'https://restapi.imaginaits.com/canceltransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'V2-Stornoverfolgung
Prüfen Sie cancellation_tracking in den Fähigkeiten. Senden Sie JSON mit Idempotency-Key, speichern operation_id und fragen alle zwei Sekunden unter Beachtung von Retry-After ab. HTTP 202 und REQUESTED bedeuten nur Erfassung. Erst confirmed=true mit CONFIRMED_BY_IMACASH bedeutet einen authentifizierten Abschlussbericht von ImaCash mit Abschluss, Währung sowie vollständigen gleichen Ein- und Ausgabebeträgen. Das ist keine unabhängige Hardwarezertifizierung. Integrator-Token, Fortschritt oder Cloud-Status allein bestätigen nichts.
| execution_state | Bedeutung und Vorgehen |
|---|---|
REQUESTED | In Cloud erfasst; ImaCash-Bericht ausstehend. |
CONFIRMED_BY_IMACASH | ImaCash meldet Storno mit Abschluss und vollständigen konsistenten Geldflüssen. |
REJECTED_ALREADY_PAID | ImaCash meldet eine bezahlte Buchung; Storno nicht bestätigt. |
REPORTED_UNVERIFIED | Unvollständiger Bericht; nicht als bestätigt behandeln. |
REVIEW_REQUIRED | Widerspruch oder Fehler; lokale Prüfung und Support erforderlich. |
Beispiel · GET /v2.php?action=capabilities
curl 'https://restapi.imaginaits.com/v2.php?action=capabilities' --header 'x-auth-token: YOUR_TOKEN'Beispiel · POST /canceltransactionv2.php
curl --request POST 'https://restapi.imaginaits.com/canceltransactionv2.php' \
--header 'x-auth-token: YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: cancel-DEMO-20261029-001' \
--header 'X-Request-ID: request-DEMO-001' \
--data '{"transaction_id":"TX-DEMO-20261029-001"}'Beispiel · HTTP 202
{
"status": "ok",
"api_version": "2.0",
"request_id": "request-DEMO-001",
"data": {
"operation_id": "0123456789abcdef0123456789abcdef",
"transaction_id": "TX-DEMO-20261029-001",
"execution_state": "REQUESTED",
"confirmed": false,
"confirmation_source": null,
"reported_state": null,
"requested_at_utc": "2026-10-29 09:00:00.000000",
"reported_at_utc": null,
"cash_flow": {
"received_minor": null,
"returned_minor": null,
"currency": null
},
"requires_review": false
}
}Beispiel · GET /v2.php?action=operation
curl 'https://restapi.imaginaits.com/v2.php?action=operation&operation_id=OPERATION_ID_FROM_RESPONSE' --header 'x-auth-token: YOUR_TOKEN'Beispiel · HTTP 200
{
"status": "ok",
"api_version": "2.0",
"request_id": "request-DEMO-002",
"data": {
"operation_id": "0123456789abcdef0123456789abcdef",
"transaction_id": "TX-DEMO-20261029-001",
"execution_state": "CONFIRMED_BY_IMACASH",
"confirmed": true,
"confirmation_source": "imacash_report",
"reported_state": "CANCELLED",
"requested_at_utc": "2026-10-29 09:00:00.000000",
"reported_at_utc": "2026-10-29 09:00:02.000000",
"cash_flow": {
"received_minor": 100,
"returned_minor": 100,
"currency": "EUR"
},
"requires_review": false
}
}Beispiel · GET /v2.php?action=transaction
curl 'https://restapi.imaginaits.com/v2.php?action=transaction&transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Wiederholungen, Unterbrechungen und Freigaben
Behalten Sie Schlüssel und Referenz bei einer V2-Wiederholung bei. Derselbe Schlüssel für eine andere Referenz wird abgelehnt. Ein neuer Schlüssel für einen Vorgang mit vorhandener Anfrage ebenso: ermitteln Sie operation_id über die Vorgangsabfrage. Ist ImaCash geschlossen, fehlt sein Bericht oder fehlen Details, bleibt das Ergebnis unbestätigt. Zeigen Sie nach angemessener Wartezeit eine erforderliche Prüfung an und bewahren die Referenz; wiederholen Sie keine Zahlungen, Erstattungen oder Neustarts. V2 behält lokale Passwörter, Rechte und Schutzmechanismen.
Eine bezahlte Buchung erstatten
Ein PAID-Vorgang kann hier nicht storniert werden. Legen Sie für eine Erstattung einen neuen Vorgang mit eigener Referenz und negativem Betrag an; behalten Sie die Verbindung zum Original in Ihrer Anwendung. Die Erfassung bestätigt keine Geldausgabe: warten Sie auf ImaCash und prüfen die Beträge. Verwenden Sie die Verkaufs-ID nicht erneut.
Beispiel · POST /puttransaction.php
curl --request POST 'https://restapi.imaginaits.com/puttransaction.php' \
--header 'x-auth-token: YOUR_TOKEN' --header 'Content-Type: application/json' \
--data '{"transaction_id":"REFUND-DEMO-20261029-001","amount":-2100,"user":"OPERATOR-01","terminal":"DESK-01","method":1}'Fehler und Support
401: Token fehlt. 403: Token oder Lizenz nicht berechtigt, gegebenenfalls REST oder Wartung. V2 404: Ressource fehlt oder liegt außerhalb des Geltungsbereichs. 409: Schlüssel-, Referenz- oder Statuskonflikt; error.code prüfen. 400: ungültige Parameter oder JSON. 405: falsche Methode. 413: zu großer Inhalt. 503: Dienst oder Verfolgung nicht verfügbar, kein Beweis für einen Gerätedefekt. Timeout oder 5xx beweisen keinen Nichtempfang. Geben Sie dem Support request_id, operation_id, Referenz, Zeit und HTTP-Code ohne Zugangsdaten.
Kompatibilität und veröffentlichte Grenzen
V1-Routen, Authentifizierung, Felder und Statuswerte bleiben erhalten. V2 ergänzt eine Route ohne Migrationspflicht oder neue V1 transaction_status-Werte. *_at_utc verwendet UTC; created_at behält sein bisheriges Format. device_state=not_observed bedeutet nicht getrennt. Es gibt keine direkten Gerätebefehle oder allgemeinen ausgehenden Webhooks; prüfen Sie die Fähigkeiten. Fehlende Beträge sind null, keine bestätigten Nullen. Einige ältere Clients lassen Nullbeträge im Bericht aus: Auch nach lokalem Abschluss bleibt V2 bei REPORTED_UNVERIFIED, wenn dieser ausdrückliche Wert fehlt.
Vor dem Produktiveinsatz prüfen
Prüfen Sie in einer autorisierten Testumgebung Erfassung, Abfragen, doppelte Referenzen, Storno vor/nach Geldeinwurf, verweigerte lokale Freigabe, ImaCash offline und verlorene Antworten. Ihre Anwendung darf allein aus 200/202 keinen Abschluss ableiten. Stimmen Sie Modell und Software mit dem Anbieter ab; ein HTTP-Beispiel ersetzt keine physische Prüfung.