REST API Imagina

Integrar tu software con REST en Cloud

Esta ficha te orienta antes de programar. REST en Cloud intercambia operaciones por HTTPS con ImaCash; es distinta de ImaApi local. El manual explica el contrato y los ejemplos paso a paso.

Abrir el manual en español · Descargar ejemplos

Postman · cURL · Python · C# · JavaScript · Referencia OpenAPI en inglés

Requisitos y token propio

En Configuración > Integración de ImaCash selecciona REST API Imagina. La licencia necesita REST autorizado y mantenimiento o prueba admitidos por Cloud. Copia su token propio y úsalo por HTTPS en x-auth-token; si no aparece, consulta soporte. No es la contraseña del administrador y no debe figurar en URLs, capturas, logs o repositorios.

Referencias e importes

transaction_id identifica una operación de tu software dentro de la licencia. user y terminal son referencias de negocio del operario y puesto, no credenciales ni permisos locales. amount usa unidades menores: 2100 representa 21,00 EUR. Una tarjeta registrada no acredita el pago bancario.

Crear, consultar y cobrar

Crea la operación y conserva su referencia. Una respuesta de registro correcto en Cloud no confirma el cobro. Consulta esa misma operación y contrasta el resultado de ImaCash y los importes antes de cerrar la venta. El manual recoge los campos, métodos y ejemplos completos.

Solicitar y confirmar una cancelación

V1 conserva su contrato: CANCELLED describe Cloud. En V2, REQUESTED y HTTP 202 solo registran la solicitud. Solo CONFIRMED_BY_IMACASH con confirmed=true indica un informe final completo y coherente de ImaCash; no es una certificación independiente del dispositivo. REJECTED_ALREADY_PAID indica que ImaCash comunica la venta cobrada.

Abonar una venta cobrada

Una venta PAID no se cancela por este circuito. Si procede devolver dinero, crea un abono con referencia nueva e importe negativo y conserva su relación con la venta original. Espera el resultado de ImaCash y la salida de efectivo; registrar el abono no demuestra la devolución.

Reenvíos y resultados inciertos

Conserva transaction_id y, en V2, la misma Idempotency-Key. Guarda operation_id y consulta el seguimiento antes de reenviar. Un timeout no demuestra que la solicitud no llegó. Si el seguimiento exige revisión, hay que comprobarlo localmente con soporte; otro reenvío no lo libera. No repitas cobros o abonos ni reinicies para resolver una incertidumbre.

Errores y referencias de soporte

Comprueba el JSON además del HTTP: V1 puede responder 200 con status=error. El manual explica 400, 401, 403, 404, 405, 409, 413 y 503. Para soporte conserva request_id, operation_id, referencia, hora y código HTTP, sin credenciales ni datos de clientes.

V1, V2 y alcance real

V1 sigue disponible y V2 es optativa. Un informe incompleto, también si un cliente anterior omite importes cero, puede quedar REPORTED_UNVERIFIED. device_state=not_observed no acredita conectividad ni desconexión. No se ofrecen comandos directos al dispositivo ni webhooks generales de salida, ni se omiten permisos locales. Valida modelo y versión con el proveedor antes del uso real.