La API de un vistazo
Elige la operación, consulta qué devuelve y abre su ejemplo. El detalle completo sigue debajo.
https://restapi.imaginaits.com/x-auth-token: YOUR_TOKEN| Método | Endpoint y ejemplo | Para qué sirve | Qué comprobar |
|---|---|---|---|
| POST | /puttransaction.phpVer ejemplo cURL | Crear un cobro o un abonoVer detalle → | status=ok registra la venta; consulta después su estado. |
| GET | /statustransaction.phpVer ejemplo cURL | Consultar una ventaVer detalle → | PENDING, PAID, CANCELLED o ERROR en Cloud. |
| GET | /listtransactions.phpVer ejemplo cURL | Listar ventasVer detalle → | Filtra por estado y continúa con el cursor devuelto. |
| GET | /transactioncashflow.phpVer ejemplo cURL | Consultar entradas, salidas y desgloseVer detalle → | Importes y denominaciones informados para esa venta. |
| GET | /inventory.phpVer ejemplo cURL | Consultar el inventario recibidoVer detalle → | currency, recyclable, stacker y updated_at, cuando estén disponibles. |
| POST | /canceltransaction.phpVer ejemplo cURL | Cancelación anterior, compatibleVer detalle → | ok o CANCELLED no confirman por sí solos la cancelación de la máquina. |
| POST | /canceltransactionv2.phpVer ejemplo cURL | CancelTransactionV2: solicitar cancelación con seguimientoVer detalle → | Guarda operation_id. 202 significa pendiente; conserva Idempotency-Key. |
| GET | /v2.php?action=capabilitiesVer ejemplo cURL | Consultar las funciones disponiblesVer detalle → | cancellation_tracking indica si el seguimiento está habilitado. |
| GET | /v2.php?action=transactionVer ejemplo cURL | Consultar venta y seguimiento juntosVer detalle → | Separa cloud_status de execution_confirmation. |
| GET | /v2.php?action=operationVer ejemplo cURL | Consultar la solicitud de cancelaciónVer detalle → | confirmed, execution_state, cash_flow y requires_review. |
Circuito básico
- Crear el cobroamount: 2100 = 21,00 EUR. Guarda transaction_id.
- Consultar el resultadoConsulta la misma referencia; HTTP 200 no basta.
- Cancelar si sigue pendienteCancelTransactionV2 devuelve operation_id; consulta hasta confirmed=true.
202 = solicitud registrada. CANCELLED de V1 = estado en Cloud. confirmed=true con CONFIRMED_BY_IMACASH = informe final completo de ImaCash.
Compatibilidad
POST /v2.php?action=cancel continúa funcionando con el mismo contrato. Para nuevas integraciones utiliza CancelTransactionV2: /canceltransactionv2.php. No es necesario cambiar las integraciones anteriores.
Antes de empezar
Selecciona REST API Imagina en Configuración > Integración de ImaCash. Cloud debe autorizar la licencia para REST y admitir su mantenimiento o período de prueba. Copia el token propio de esa licencia; no uses la contraseña del administrador ni el secreto interno del conector. Si el token no aparece, anota versión y referencia numérica de licencia y consulta soporte: no crees otra venta ni otra demo para diagnosticarlo.
Conexión, token y alcance
La URL base es https://restapi.imaginaits.com/. Envía x-auth-token en cada petición, siempre por HTTPS. Cada token limita las consultas y operaciones a su licencia. No lo incluyas en URLs, capturas, registros, repositorios o correos. Los ejemplos usan YOUR_TOKEN y referencias inventadas. La documentación no ejecuta operaciones.
Referencias e importes
transaction_id identifica de forma estable una operación de tu programa en esa licencia: reutiliza exactamente el mismo valor tras un timeout, no generes otro para reintentar. user y terminal son referencias comerciales del operario y puesto, no credenciales ni permisos de ImaCash. amount se expresa en unidades menores: 2100 son 21,00 EUR y -2100 es un abono de 21,00 EUR. method=1 es efectivo y method=0 tarjeta; registrar una tarjeta no acredita un pago bancario.
Crear y consultar un cobro
Envía JSON con transaction_id, amount, user, terminal y method. status=ok confirma el registro en Cloud, no un cobro finalizado. Consulta la misma referencia y comprueba el JSON, además del HTTP. Un 409 al crear puede indicar que esa referencia ya existe: consúltala y compara sus datos; no envíes otra con un ID nuevo.
Ejemplo · 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}'Ejemplo · GET /statustransaction.php
curl 'https://restapi.imaginaits.com/statustransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Ejemplo · GET /transactioncashflow.php
curl 'https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Cancelación compatible V1
V1 conserva POST /canceltransaction.php con transaction_id en query o formulario, no como JSON. Su respuesta ok y su estado CANCELLED describen el registro en Cloud: no son una confirmación de la máquina. Algunos rechazos devuelven HTTP 200 con status=error. Comprobar después statustransaction o transactioncashflow no convierte esa marca en prueba física. Si ya ha entrado dinero, ImaCash puede aplazar la cancelación y exigir la autorización local configurada.
Ejemplo · POST /canceltransaction.php
curl --request POST 'https://restapi.imaginaits.com/canceltransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'Cancelación con seguimiento V2
Comprueba cancellation_tracking en capacidades. Solicita la cancelación con JSON e Idempotency-Key, guarda operation_id y consulta su seguimiento cada dos segundos, respetando Retry-After. HTTP 202 y REQUESTED solo significan solicitud registrada. Solo confirmed=true con CONFIRMED_BY_IMACASH acredita que llegó un informe final autenticado de ImaCash, con cierre, moneda y entrada/salida completas e iguales. No representa una certificación independiente del hardware. Un token de integrador, un progreso o el estado de Cloud por sí solos no confirman.
| execution_state | Significado y actuación |
|---|---|
REQUESTED | Solicitud registrada en Cloud; falta el informe de ImaCash. |
CONFIRMED_BY_IMACASH | Cancelación comunicada por ImaCash con cierre y flujos completos y coherentes. |
REJECTED_ALREADY_PAID | ImaCash comunica que la venta fue cobrada; no se confirma la cancelación. |
REPORTED_UNVERIFIED | Llegó un informe de cancelación incompleto; no darla por confirmada. |
REVIEW_REQUIRED | Resultado contradictorio o error; requiere comprobación local y soporte. |
Ejemplo · GET /v2.php?action=capabilities
curl 'https://restapi.imaginaits.com/v2.php?action=capabilities' --header 'x-auth-token: YOUR_TOKEN'Ejemplo · 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"}'Ejemplo · 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
}
}Ejemplo · 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'Ejemplo · 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
}
}Ejemplo · 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'Reenvíos, desconexiones y autorizaciones
Conserva la misma clave y la misma referencia al reenviar una solicitud V2: recuperas su seguimiento. La misma clave con otra referencia se rechaza. Otra clave para una venta que ya tiene solicitud también se rechaza; consulta la venta para recuperar operation_id. Si ImaCash está cerrado, no envía informe o falta detalle, la operación permanece sin confirmar. Tras un plazo razonable, muestra revisión pendiente y conserva la referencia; no repitas cobros, devoluciones ni reinicios. V2 no elimina contraseñas, permisos o protecciones locales.
Abonar una venta cobrada
Una venta PAID no se cancela con este circuito. Si corresponde devolver dinero, crea un abono nuevo, con referencia propia e importe negativo, conservando en tu programa su relación con la venta original. El registro del abono no confirma la salida de efectivo: espera el resultado de ImaCash y comprueba los importes. No reutilices el ID de la venta ni simules una cancelación.
Ejemplo · 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}'Errores y soporte
401: falta token. 403: token o licencia no autorizados; puede faltar REST o mantenimiento. 404 en V2: recurso ausente o fuera de alcance. 409: conflicto de clave, referencia o estado; lee error.code. 400: parámetros o JSON incorrectos. 405: método incorrecto. 413: cuerpo excesivo. 503: servicio o seguimiento no disponibles, no una avería de máquina demostrada. Un timeout o 5xx no prueba que la operación no haya llegado. Para soporte conserva request_id, operation_id, referencia, hora y código HTTP, ocultando credenciales.
Compatibilidad y límites publicados
Las rutas, autenticación, campos y estados V1 permanecen. V2 es una ruta adicional, no obliga a migrar y no introduce estados nuevos en transaction_status de V1. Sus marcas *_at_utc usan UTC; created_at conserva el formato legacy. device_state=not_observed no equivale a máquina desconectada. No hay comandos directos al dispositivo ni webhooks generales de salida en esta ampliación: consulta capacidades. Los desgloses ausentes son null, no cero confirmado. Algunos clientes anteriores omiten los importes cero en su informe: aunque terminen localmente, V2 conserva REPORTED_UNVERIFIED si falta ese dato explícito.
Prueba antes de pasar a producción
En un entorno de pruebas autorizado, contrasta alta, consulta, referencia repetida, cancelación sin efectivo y con efectivo, autorización local rechazada, ImaCash sin conexión y pérdida de una respuesta. Comprueba que tu programa no cierre como cancelado al recibir solo un 200/202. Valida cada modelo y versión del dispositivo con su proveedor; un ejemplo HTTP no sustituye esa comprobación.