REST API Imagina

Relier votre logiciel par REST dans Cloud

Cette fiche prépare votre intégration. REST dans Cloud échange des opérations avec ImaCash par HTTPS ; cette interface est distincte d’ImaApi locale. Le manuel détaille le contrat et les exemples étape par étape.

Ouvrir le manuel en français · Télécharger les exemples

Postman · cURL · Python · C# · JavaScript · Référence OpenAPI en anglais

Prérequis et jeton propre

Dans Configuration > Intégration d’ImaCash, sélectionnez REST API Imagina. La licence doit être autorisée pour REST avec une maintenance ou un essai admis par Cloud. Copiez son jeton propre et envoyez-le par HTTPS dans x-auth-token ; s’il manque, contactez le support. Ce n’est pas le mot de passe administrateur : ne le placez jamais dans des URL, captures, journaux ou dépôts.

Références et montants

transaction_id identifie une opération de votre logiciel pour la licence. user et terminal sont des références métier de l’opérateur et du poste, sans valeur d’identifiants secrets ni de permissions locales. amount utilise les unités mineures : 2100 représente 21,00 EUR. Enregistrer une carte ne prouve pas le paiement bancaire.

Créer, consulter et encaisser

Créez l’opération et conservez sa référence. Un enregistrement réussi dans Cloud ne confirme pas l’encaissement. Consultez la même opération et vérifiez le résultat d’ImaCash et les montants avant de clôturer la vente. Le manuel fournit les champs, méthodes et exemples complets.

Demander et confirmer une annulation

V1 conserve son contrat : CANCELLED décrit Cloud. Avec V2, REQUESTED et HTTP 202 enregistrent seulement la demande. Seul CONFIRMED_BY_IMACASH avec confirmed=true indique un rapport final complet et cohérent d’ImaCash ; ce n’est pas une certification indépendante du matériel. REJECTED_ALREADY_PAID signifie qu’ImaCash déclare la vente payée.

Rembourser une vente payée

Ce circuit n’annule pas une vente PAID. Si un remboursement est dû, créez une opération avec une nouvelle référence et un montant négatif, en conservant son lien avec la vente initiale. Attendez le résultat d’ImaCash et la sortie des espèces ; l’enregistrement ne prouve pas le remboursement.

Renvois et résultats incertains

Conservez transaction_id et, avec V2, la même Idempotency-Key. Gardez operation_id et consultez le suivi avant tout renvoi. Un délai dépassé ne prouve pas que la demande n’est pas arrivée. Si le suivi exige une vérification, contrôlez localement avec le support ; un renvoi ne le débloque pas. Ne répétez ni paiement ni remboursement et ne redémarrez pas pour résoudre une incertitude.

Erreurs et références pour le support

Vérifiez le JSON en plus du HTTP : V1 peut renvoyer 200 avec status=error. Le manuel explique 400, 401, 403, 404, 405, 409, 413 et 503. Conservez pour le support request_id, operation_id, référence, heure et code HTTP, sans identifiants secrets ni données clients.

V1, V2 et portée réelle

V1 reste disponible et V2 est facultative. Un rapport incomplet, notamment si un ancien client omet les montants nuls, peut rester REPORTED_UNVERIFIED. device_state=not_observed ne prouve ni connexion ni déconnexion. Aucun accès direct aux commandes du matériel ni webhook général sortant n’est proposé ; les permissions locales restent requises. Validez modèle et version avec le fournisseur avant usage réel.