L’API en un coup d’œil
Choisissez une opération, vérifiez son résultat et ouvrez son exemple. Le guide complet se trouve ci-dessous.
https://restapi.imaginaits.com/x-auth-token: YOUR_TOKEN| Méthode | Endpoint et exemple | Utilisation | Points à vérifier |
|---|---|---|---|
| POST | /puttransaction.phpVoir l’exemple cURL | Créer un encaissement ou un remboursementVoir le détail → | status=ok enregistre la transaction ; consultez ensuite son état. |
| GET | /statustransaction.phpVoir l’exemple cURL | Consulter une transactionVoir le détail → | PENDING, PAID, CANCELLED ou ERROR dans Cloud. |
| GET | /listtransactions.phpVoir l’exemple cURL | Lister les transactionsVoir le détail → | Filtrez par état et utilisez le curseur renvoyé pour continuer. |
| GET | /transactioncashflow.phpVoir l’exemple cURL | Consulter les entrées, sorties et le détailVoir le détail → | Montants et coupures signalés pour cette transaction. |
| GET | /inventory.phpVoir l’exemple cURL | Consulter l’inventaire reçuVoir le détail → | currency, recyclable, stacker et updated_at, si disponibles. |
| POST | /canceltransaction.phpVoir l’exemple cURL | Annulation historique compatibleVoir le détail → | ok ou CANCELLED ne confirme pas seul l’annulation sur la machine. |
| POST | /canceltransactionv2.phpVoir l’exemple cURL | CancelTransactionV2 : demander une annulation suivieVoir le détail → | Conservez operation_id et Idempotency-Key. 202 signifie en attente. |
| GET | /v2.php?action=capabilitiesVoir l’exemple cURL | Consulter les fonctions disponiblesVoir le détail → | cancellation_tracking indique si le suivi est activé. |
| GET | /v2.php?action=transactionVoir l’exemple cURL | Consulter la transaction et son suiviVoir le détail → | Sépare cloud_status d’execution_confirmation. |
| GET | /v2.php?action=operationVoir l’exemple cURL | Consulter la demande d’annulationVoir le détail → | confirmed, execution_state, cash_flow et requires_review. |
Parcours de base
- Créer l’encaissementamount : 2100 = 21,00 EUR. Conservez transaction_id.
- Consulter le résultatConsultez la même référence ; HTTP 200 ne suffit pas.
- Annuler si toujours en attenteCancelTransactionV2 renvoie operation_id ; consultez jusqu’à confirmed=true.
202 = demande enregistrée. CANCELLED en V1 = état Cloud. confirmed=true avec CONFIRMED_BY_IMACASH = rapport final complet d’ImaCash.
Compatibilité
POST /v2.php?action=cancel reste disponible avec le même contrat. Pour une nouvelle intégration, utilisez CancelTransactionV2 : /canceltransactionv2.php. Les intégrations existantes restent compatibles.
Avant de commencer
Sélectionnez REST API Imagina dans Configuration > Intégration d’ImaCash. Cloud doit autoriser la licence pour REST et accepter sa maintenance ou sa période d’essai. Copiez le jeton de cette licence, jamais le mot de passe administrateur ni le secret interne du connecteur. Si le jeton manque, notez la version et la référence numérique de licence et contactez le support ; ne créez pas une autre vente ou démo pour le diagnostic.
Connexion, jeton et périmètre
L’URL de base est https://restapi.imaginaits.com/. Envoyez x-auth-token dans chaque requête HTTPS. Chaque jeton limite les opérations à sa licence. Ne l’insérez pas dans les URL, captures, journaux, dépôts ou courriels. Les exemples utilisent YOUR_TOKEN et des références fictives. Cette documentation n’exécute aucune opération.
Références et montants
transaction_id est une référence stable de votre opération et licence : réutilisez exactement la même après un délai dépassé. user et terminal sont les références commerciales de l’opérateur et du poste, pas des identifiants de connexion ni des permissions ImaCash. amount utilise les unités mineures : 2100 correspond à 21,00 EUR et -2100 à un remboursement de 21,00 EUR. method=1 signifie espèces, method=0 carte ; enregistrer une carte ne confirmé pas un paiement bancaire.
Créer et consulter un paiement
Envoyez un JSON contenant transaction_id, amount, user, terminal et method. status=ok confirmé l’enregistrement dans Cloud, pas la fin du paiement. Consultez la même référence et vérifiez HTTP et JSON. Un 409 à la création peut signaler une référence existante : consultez-la et comparez les données, sans envoyer un autre identifiant.
Exemple · 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}'Exemple · GET /statustransaction.php
curl 'https://restapi.imaginaits.com/statustransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Exemple · GET /transactioncashflow.php
curl 'https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Annulation compatible V1
V1 conserve POST /canceltransaction.php avec transaction_id dans la query ou le formulaire, pas en JSON. Sa réponse ok et l’état CANCELLED concernent Cloud, sans confirmer la machine. Certains refus renvoient HTTP 200 avec status=error. Consulter ensuite statustransaction ou transactioncashflow ne transforme pas cette marque en preuve physique. Si de l’argent a déjà été reçu, ImaCash peut différer l’annulation et demander l’autorisation locale configurée.
Exemple · POST /canceltransaction.php
curl --request POST 'https://restapi.imaginaits.com/canceltransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Suivi d’annulation V2
Vérifiez cancellation_tracking dans les capacités. Envoyez le JSON avec Idempotency-Key, conservez operation_id et consultez le suivi toutes les deux secondes en respectant Retry-After. HTTP 202 et REQUESTED confirment seulement l’enregistrement. Seul confirmed=true avec CONFIRMED_BY_IMACASH indique la réception d’un rapport final authentifié d’ImaCash avec fin, devise et montants entrants/sortants complets et égaux. Ce n’est pas une certification indépendante du matériel. Un jeton d’intégrateur, un progrès ou l’état Cloud seuls ne confirment rien.
| execution_state | Signification et action |
|---|---|
REQUESTED | Demande enregistrée dans Cloud ; rapport ImaCash attendu. |
CONFIRMED_BY_IMACASH | ImaCash signale une annulation avec fin et flux complets cohérents. |
REJECTED_ALREADY_PAID | ImaCash signale une vente payée ; annulation non confirmée. |
REPORTED_UNVERIFIED | Rapport d’annulation incomplet ; ne pas confirmer. |
REVIEW_REQUIRED | Résultat contradictoire ou erreur ; vérification locale et support nécessaires. |
Exemple · GET /v2.php?action=capabilities
curl 'https://restapi.imaginaits.com/v2.php?action=capabilities' --header 'x-auth-token: YOUR_TOKEN'Exemple · 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"}'Exemple · 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
}
}Exemple · 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'Exemple · 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
}
}Exemple · 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'Renvois, déconnexions et autorisations
Conservez la même clé et référence pour renvoyer une demande V2 et retrouver son suivi. La même clé pour une autre référence est refusée. Une nouvelle clé pour une vente ayant déjà une demande est aussi refusée ; consultez la vente pour retrouver operation_id. Si ImaCash est fermé, ne transmet rien ou manque de détails, la demande reste non confirmée. Après une attente raisonnable, affichez une vérification en cours et conservez la référence ; ne répétez ni paiement, ni remboursement, ni redémarrage. V2 conserve les mots de passe, permissions et protections locales.
Rembourser une vente payée
Une vente PAID ne s’annule pas par ce circuit. Créez un remboursement distinct avec sa propre référence et un montant négatif ; conservez le lien avec la vente d’origine dans votre logiciel. L’enregistrement ne confirmé pas la sortie d’espèces : attendez le résultat d’ImaCash et contrôlez les montants. Ne réutilisez pas l’identifiant de vente.
Exemple · 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}'Erreurs et support
401 : jeton absent. 403 : jeton ou licence non autorisés, REST ou maintenance éventuellement absents. 404 V2 : ressource absente ou hors périmètre. 409 : conflit de clé, référence ou état ; lisez error.code. 400 : paramètres ou JSON invalides. 405 : mauvaise méthode. 413 : corps trop grand. 503 : service ou suivi indisponibles, sans prouver une panne de machine. Un délai dépassé ou 5xx ne prouve pas que la demande n’est pas arrivée. Communiquez request_id, operation_id, référence, heure et code HTTP au support, sans identifiants secrets.
Compatibilité et limites publiées
Les routes, l’authentification, les champs et les états V1 restent identiques. V2 ajoute une route sans migration obligatoire ni nouvel état dans transaction_status V1. Ses horodatages *_at_utc sont en UTC ; created_at garde son format historique. device_state=not_observed ne signifie pas machine déconnectée. Aucun ordre direct au dispositif ni webhook sortant générique n’est fourni : consultez les capacités. Un montant absent vaut null, pas zéro confirmé. Certains anciens clients omettent les montants nuls dans leur rapport : même après la fin locale, V2 conserve REPORTED_UNVERIFIED si cette valeur explicite manque.
Tester avant la production
Dans un environnement de test autorisé, vérifiez création, consultation, référence répétée, annulation avant/après insertion d’espèces, autorisation locale refusée, ImaCash hors ligne et perte de réponse. Votre logiciel ne doit pas conclure à une annulation sur un simple 200/202. Validez chaque modèle et version avec le fournisseur ; un exemple HTTP ne remplace pas un test physique.