REST API Imagina

Collegare il software tramite REST nel Cloud

Questa scheda aiuta a preparare l’integrazione. REST nel Cloud scambia operazioni con ImaCash tramite HTTPS ed è distinta da ImaApi locale. Il manuale spiega contratto ed esempi passo per passo.

Aprire il manuale in italiano · Scaricare gli esempi

Postman · cURL · Python · C# · JavaScript · Riferimento OpenAPI in inglese

Requisiti e token personale della licenza

In Configurazione > Integrazione di ImaCash seleziona REST API Imagina. La licenza richiede autorizzazione REST e manutenzione o prova ammesse dal Cloud. Copia il token della licenza e invialo tramite HTTPS in x-auth-token; se manca, contatta il supporto. Non è la password amministratore e non deve comparire in URL, schermate, log o repository.

Riferimenti e importi

transaction_id identifica un’operazione del tuo software nella licenza. user e terminal sono riferimenti commerciali di operatore e postazione, non credenziali o permessi locali. amount usa unità minori: 2100 rappresenta 21,00 EUR. Registrare una carta non dimostra il pagamento bancario.

Creare, consultare e incassare

Crea l’operazione e conserva il riferimento. Una registrazione riuscita nel Cloud non conferma l’incasso. Consulta la stessa operazione e verifica risultato di ImaCash e importi prima di chiudere la vendita. Il manuale contiene campi, metodi ed esempi completi.

Richiedere e confermare un annullamento

V1 conserva il contratto: CANCELLED descrive il Cloud. In V2, REQUESTED e HTTP 202 registrano soltanto la richiesta. Solo CONFIRMED_BY_IMACASH con confirmed=true indica un rapporto finale completo e coerente di ImaCash; non è una certificazione indipendente del dispositivo. REJECTED_ALREADY_PAID significa che ImaCash segnala la vendita pagata.

Rimborsare una vendita pagata

Questo circuito non annulla una vendita PAID. Se è dovuto un rimborso, crea un’operazione con nuovo riferimento e importo negativo, mantenendo il legame con la vendita originale. Attendi il risultato di ImaCash e l’uscita del contante; registrare il rimborso non dimostra la restituzione.

Reinvii ed esiti incerti

Conserva transaction_id e, in V2, la stessa Idempotency-Key. Salva operation_id e consulta il monitoraggio prima di reinviare. Un timeout non dimostra che la richiesta non sia arrivata. Se il monitoraggio richiede verifica, occorrono controllo locale e supporto; un reinvio non lo sblocca. Non ripetere incassi o rimborsi e non riavviare per risolvere un’incertezza.

Errori e riferimenti per il supporto

Verifica il JSON oltre all’HTTP: V1 può rispondere 200 con status=error. Il manuale spiega 400, 401, 403, 404, 405, 409, 413 e 503. Conserva per il supporto request_id, operation_id, riferimento, ora e codice HTTP, senza credenziali o dati dei clienti.

V1, V2 e ambito effettivo

V1 resta disponibile e V2 è facoltativa. Un rapporto incompleto, anche se un vecchio client omette gli importi zero, può restare REPORTED_UNVERIFIED. device_state=not_observed non dimostra connessione o disconnessione. Non sono disponibili comandi diretti al dispositivo né webhook generali in uscita; i permessi locali restano necessari. Valida modello e versione con il fornitore prima dell’uso reale.