Ihre Software über Cloud REST anbinden
Diese Seite hilft bei der Vorbereitung. Cloud REST tauscht Vorgänge über HTTPS mit ImaCash aus und unterscheidet sich von der lokalen ImaApi. Das Handbuch erläutert Vertrag und Beispiele Schritt für Schritt.
Deutsches Handbuch öffnen · Beispiele herunterladen
Postman · cURL · Python · C# · JavaScript · OpenAPI-Referenz auf Englisch
Voraussetzungen und eigenes Token
Wählen Sie in ImaCash unter Einstellungen > Integration REST API Imagina. Die Lizenz benötigt eine REST-Freigabe und von Cloud zugelassene Wartung oder Testlaufzeit. Kopieren Sie das eigene Token und senden Sie es über HTTPS in x-auth-token; fehlt es, wenden Sie sich an den Support. Es ist kein Administratorpasswort und gehört nicht in URLs, Bildschirmbilder, Protokolle oder Repositories.
Referenzen und Beträge
transaction_id kennzeichnet einen Vorgang Ihrer Software innerhalb der Lizenz. user und terminal sind Geschäftsreferenzen für Bediener und Kasse, keine Zugangsdaten oder lokalen Rechte. amount verwendet Untereinheiten: 2100 bedeutet 21,00 EUR. Die Erfassung einer Karte bestätigt keine Bankzahlung.
Anlegen, abfragen und kassieren
Legen Sie den Vorgang an und bewahren Sie die Referenz auf. Erfolgreiche Erfassung in Cloud bestätigt keine Zahlung. Fragen Sie denselben Vorgang ab und prüfen Sie ImaCash-Ergebnis und Beträge vor dem Verkaufsabschluss. Das Handbuch enthält vollständige Felder, Methoden und Beispiele.
Stornierung anfordern und bestätigen
V1 behält seinen Vertrag: CANCELLED beschreibt Cloud. Bei V2 erfassen REQUESTED und HTTP 202 lediglich die Anfrage. Nur CONFIRMED_BY_IMACASH mit confirmed=true kennzeichnet einen vollständigen, schlüssigen Abschlussbericht von ImaCash; dies ist keine unabhängige Geräteprüfung. REJECTED_ALREADY_PAID bedeutet, dass ImaCash den Verkauf als bezahlt meldet.
Bezahlten Verkauf erstatten
Dieser Ablauf storniert keinen PAID-Verkauf. Ist eine Erstattung fällig, legen Sie einen neuen Vorgang mit eigener Referenz und negativem Betrag an und bewahren Sie den Bezug zum ursprünglichen Verkauf. Warten Sie auf ImaCash-Ergebnis und Bargeldausgabe; die Erfassung beweist keine Rückzahlung.
Wiederholungen und unklare Ergebnisse
Behalten Sie transaction_id und bei V2 dieselbe Idempotency-Key bei. Speichern Sie operation_id und prüfen Sie die Verfolgung vor erneutem Senden. Ein Timeout beweist nicht, dass die Anfrage nicht ankam. Verlangt die Verfolgung eine Prüfung, sind lokale Kontrolle und Support erforderlich; erneutes Senden hebt dies nicht auf. Zahlungen oder Erstattungen nicht wiederholen und bei Unklarheit nicht neu starten.
Fehler und Supportreferenzen
Prüfen Sie neben HTTP auch JSON: V1 kann 200 mit status=error liefern. Das Handbuch erläutert 400, 401, 403, 404, 405, 409, 413 und 503. Bewahren Sie für den Support request_id, operation_id, Referenz, Uhrzeit und HTTP-Code auf, ohne Zugangsdaten oder Kundendaten.
V1, V2 und tatsächlicher Umfang
V1 bleibt verfügbar und V2 ist optional. Ein unvollständiger Bericht, auch wenn ältere Clients Nullbeträge auslassen, kann REPORTED_UNVERIFIED bleiben. device_state=not_observed belegt weder Verbindung noch Trennung. Direkte Gerätebefehle und allgemeine ausgehende Webhooks werden nicht angeboten; lokale Rechte bleiben erforderlich. Prüfen Sie Modell und Version mit dem Anbieter vor dem realen Einsatz.
¿Qué es la REST API de ImaCash?
La REST API es el puente que conecta tu sistema POS con ImaCash y los dispositivos de control de efectivo. Funciona con peticiones HTTP simples en formato JSON, y todo el acceso está protegido por token para mantener la seguridad.
¿Cuándo usar esta integración?
Esta API está pensada para cuando tu POS no puede conectarse directamente con ImaCash por diferencias de plataforma, arquitectura o tecnología. En lugar de modificar tu sistema, usas nuestra API para comunicarte.
¿Cuáles son los requisitos para integrar un POS a la Rest API de ImaCash?
Überprüfen Sie, ob Ihre Software die technischen Standards erfüllt, die für eine nahtlose Integration mit ImaCash erforderlich sind, indem Sie API REST verwenden. Es gibt nur 6 Anforderungen, Schau sie dir hier an.
Wichtig
Para operaciones físicas directas con la máquina (como conteos manuales, vaciados o mantenimiento), tendrás que trabajar con la interfaz de ImaCash directamente. La API gestiona la comunicación de datos, no el control físico del hardware.
Konfiguration
WICHTIGER HINWEIS: Para que el POS pueda vincularse a ImaCash mediante la REST API de Imagina, necesitarás un token de autenticación que deberás solicitar a nuestro equipo.
Flujo de Comunicación POS - ImaCash mediante REST API
La siguiente imagen ilustra cómo funciona la comunicación entre el sistema POS e ImaCash a través de la REST API:
- El POS crea una transacción mediante POST /PutTransaction.php
- ImaCash espera y procesa la transacción mediante GET /statusTransaction.php
- ImaCash actualiza el estado una vez completado el proceso
- El POS recibe la confirmación del estado de la transacción
Para más información sobre la implementación técnica y documentación completa de la API pulsa a continuación: