L’API a colpo d’occhio
Scegli l’operazione, controlla il risultato e apri l’esempio. La guida completa continua qui sotto.
https://restapi.imaginaits.com/x-auth-token: YOUR_TOKEN| Metodo | Endpoint ed esempio | Utilizzo | Cosa verificare |
|---|---|---|---|
| POST | /puttransaction.phpVedi esempio cURL | Creare un incasso o rimborsoVedi dettagli → | status=ok registra la transazione; consulta poi il suo stato. |
| GET | /statustransaction.phpVedi esempio cURL | Consultare una transazioneVedi dettagli → | PENDING, PAID, CANCELLED o ERROR in Cloud. |
| GET | /listtransactions.phpVedi esempio cURL | Elencare le transazioniVedi dettagli → | Filtra per stato e continua con il cursore restituito. |
| GET | /transactioncashflow.phpVedi esempio cURL | Consultare entrate, uscite e dettaglioVedi dettagli → | Importi e tagli comunicati per questa transazione. |
| GET | /inventory.phpVedi esempio cURL | Consultare l’inventario ricevutoVedi dettagli → | currency, recyclable, stacker e updated_at, se disponibili. |
| POST | /canceltransaction.phpVedi esempio cURL | Annullamento precedente compatibileVedi dettagli → | ok o CANCELLED non confermano da soli l’annullamento sulla macchina. |
| POST | /canceltransactionv2.phpVedi esempio cURL | CancelTransactionV2: richiedere un annullamento tracciatoVedi dettagli → | Conserva operation_id e Idempotency-Key. 202 indica attesa. |
| GET | /v2.php?action=capabilitiesVedi esempio cURL | Consultare le funzioni disponibiliVedi dettagli → | cancellation_tracking indica se il tracciamento è attivo. |
| GET | /v2.php?action=transactionVedi esempio cURL | Consultare transazione e tracciamento insiemeVedi dettagli → | Separa cloud_status da execution_confirmation. |
| GET | /v2.php?action=operationVedi esempio cURL | Consultare la richiesta di annullamentoVedi dettagli → | confirmed, execution_state, cash_flow e requires_review. |
Flusso di base
- Creare l’incassoamount: 2100 = 21,00 EUR. Conserva transaction_id.
- Consultare il risultatoConsulta lo stesso riferimento; HTTP 200 non basta.
- Annullare se ancora in attesaCancelTransactionV2 restituisce operation_id; consulta fino a confirmed=true.
202 = richiesta registrata. CANCELLED in V1 = stato Cloud. confirmed=true con CONFIRMED_BY_IMACASH = rapporto finale completo di ImaCash.
Compatibilità
POST /v2.php?action=cancel rimane disponibile con lo stesso contratto. Per nuove integrazioni usa CancelTransactionV2: /canceltransactionv2.php. Le integrazioni esistenti non richiedono modifiche.
Prima di iniziare
Seleziona REST API Imagina in Configurazione > Integrazione di ImaCash. Cloud deve autorizzare REST per la licenza e accettarne manutenzione o periodo di prova. Copia il token della licenza, non la password amministratore o il segreto interno del connettore. Se manca, annota versione e riferimento numerico della licenza e contatta il supporto; non creare altre vendite o demo per la diagnosi.
Connessione, token e ambito
L’URL base è https://restapi.imaginaits.com/. Invia x-auth-token in ogni richiesta HTTPS. Ogni token limita le operazioni alla propria licenza. Non inserirlo in URL, schermate, log, repository o email. Gli esempi usano YOUR_TOKEN e riferimenti fittizi. La documentazione non esegue operazioni.
Riferimenti e importi
transaction_id identifica stabilmente un’operazione del gestionale e della licenza: riutilizza lo stesso valore dopo un timeout. user e terminal sono riferimenti commerciali di operatore e postazione, non credenziali o permessi ImaCash. amount usa unità minori: 2100 indica 21,00 EUR e -2100 un rimborso di 21,00 EUR. method=1 indica contanti, method=0 carta; registrare una carta non conferma un pagamento bancario.
Creare e consultare un pagamento
Invia JSON con transaction_id, amount, user, terminal e method. status=ok conferma la registrazione in Cloud, non il pagamento concluso. Consulta lo stesso riferimento e controlla HTTP e JSON. Un 409 in creazione può indicare un riferimento esistente: consultalo e confronta i dati, senza inviare un altro ID.
Esempio · 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}'Esempio · GET /statustransaction.php
curl 'https://restapi.imaginaits.com/statustransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Esempio · GET /transactioncashflow.php
curl 'https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Annullamento compatibile V1
V1 conserva POST /canceltransaction.php con transaction_id nella query o nel modulo, non in JSON. La risposta ok e lo stato CANCELLED riguardano Cloud, senza confermare la macchina. Alcuni rifiuti restituiscono HTTP 200 con status=error. Consultare statustransaction o transactioncashflow non trasforma il dato in prova fisica. Se è già entrato denaro, ImaCash può rinviare l’annullamento e richiedere l’autorizzazione locale configurata.
Esempio · POST /canceltransaction.php
curl --request POST 'https://restapi.imaginaits.com/canceltransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Monitoraggio V2
Verifica cancellation_tracking nelle capacità. Invia JSON e Idempotency-Key, conserva operation_id e consulta ogni due secondi rispettando Retry-After. HTTP 202 e REQUESTED indicano solo registrazione. Soltanto confirmed=true con CONFIRMED_BY_IMACASH indica un rapporto finale autenticato di ImaCash con chiusura, valuta e flussi completi ed equivalenti. Non è una certificazione indipendente dell’hardware. Token integratore, avanzamento o stato Cloud da soli non confermano.
| execution_state | Significato e azione |
|---|---|
REQUESTED | Richiesta registrata in Cloud; si attende il rapporto ImaCash. |
CONFIRMED_BY_IMACASH | ImaCash comunica annullamento con chiusura e flussi completi coerenti. |
REJECTED_ALREADY_PAID | ImaCash comunica vendita pagata; annullamento non confermato. |
REPORTED_UNVERIFIED | Rapporto incompleto; non considerare confermato. |
REVIEW_REQUIRED | Risultato contraddittorio o errore; servono verifica locale e supporto. |
Esempio · GET /v2.php?action=capabilities
curl 'https://restapi.imaginaits.com/v2.php?action=capabilities' --header 'x-auth-token: YOUR_TOKEN'Esempio · 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"}'Esempio · 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
}
}Esempio · 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'Esempio · 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
}
}Esempio · 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'Reinvii, disconnessioni e autorizzazioni
Conserva chiave e riferimento per ripetere V2 e recuperarne il monitoraggio. La stessa chiave per un altro riferimento viene rifiutata. Anche una nuova chiave per una vendita con richiesta esistente è rifiutata: consulta la vendita per operation_id. Se ImaCash è chiuso, non risponde o mancano dettagli, resta non confermata. Dopo un’attesa ragionevole mostra verifica necessaria e conserva il riferimento; non ripetere pagamenti, rimborsi o riavvii. V2 mantiene password, permessi e protezioni locali.
Rimborsare una vendita pagata
Una vendita PAID non si annulla con questo flusso. Crea un rimborso distinto con riferimento proprio e importo negativo, conservando nel gestionale il legame con la vendita originale. Registrarlo non conferma l’erogazione: attendi ImaCash e verifica gli importi. Non riutilizzare l’ID della vendita.
Esempio · 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}'Errori e supporto
401: token mancante. 403: token o licenza non autorizzati, eventualmente REST o manutenzione. 404 V2: risorsa assente o fuori ambito. 409: conflitto di chiave, riferimento o stato; controlla error.code. 400: parametri o JSON non validi. 405: metodo errato. 413: corpo eccessivo. 503: servizio o monitoraggio non disponibili, senza dimostrare un guasto macchina. Timeout o 5xx non provano il mancato arrivo. Fornisci al supporto request_id, operation_id, riferimento, ora e HTTP, senza credenziali.
Compatibilità e limiti pubblicati
Rotte, autenticazione, campi e stati V1 rimangono. V2 aggiunge una rotta senza migrazione obbligatoria o nuovi valori in transaction_status V1. *_at_utc usa UTC; created_at mantiene il formato precedente. device_state=not_observed non significa macchina disconnessa. Non ci sono comandi diretti al dispositivo o webhook generici in uscita: consulta le capacità. Gli importi assenti sono null, non zeri confermati. Alcuni client precedenti omettono gli importi zero nel rapporto: anche dopo la conclusione locale, V2 conserva REPORTED_UNVERIFIED se manca quel valore esplicito.
Test prima della produzione
In un ambiente autorizzato verifica creazione, consultazione, riferimento ripetuto, annullamento prima/dopo denaro, autorizzazione locale negata, ImaCash offline e risposta persa. Non considerare annullato un pagamento solo per 200/202. Valida modello e versione con il fornitore; un esempio HTTP non sostituisce una prova fisica.