REST API Imagina

Ligar o seu software por REST no Cloud

Esta ficha ajuda a preparar a integração. REST no Cloud troca operações com o ImaCash por HTTPS e é distinta da ImaApi local. O manual explica o contrato e os exemplos passo a passo.

Abrir o manual em português · Descarregar exemplos

Postman · cURL · Python · C# · JavaScript · Referência OpenAPI em inglês

Requisitos e token próprio

Em Configuração > Integração do ImaCash, selecione REST API Imagina. A licença precisa de autorização REST e de manutenção ou período de teste aceites pelo Cloud. Copie o token próprio e envie-o por HTTPS em x-auth-token; se não aparecer, contacte o suporte. Não é a palavra-passe do administrador e não deve constar de URLs, capturas, registos ou repositórios.

Referências e montantes

transaction_id identifica uma operação do seu software dentro da licença. user e terminal são referências comerciais do operador e posto, não credenciais nem permissões locais. amount usa unidades menores: 2100 representa 21,00 EUR. Registar um cartão não comprova o pagamento bancário.

Criar, consultar e cobrar

Crie a operação e conserve a referência. O registo bem-sucedido no Cloud não confirma o pagamento. Consulte a mesma operação e confira o resultado do ImaCash e os montantes antes de fechar a venda. O manual apresenta campos, métodos e exemplos completos.

Pedir e confirmar um cancelamento

V1 conserva o contrato: CANCELLED descreve o Cloud. Em V2, REQUESTED e HTTP 202 apenas registam o pedido. Só CONFIRMED_BY_IMACASH com confirmed=true indica um relatório final completo e coerente do ImaCash; não é uma certificação independente do equipamento. REJECTED_ALREADY_PAID significa que o ImaCash comunica a venda paga.

Reembolsar uma venda paga

Este circuito não cancela uma venda PAID. Se for devido um reembolso, crie uma operação com nova referência e montante negativo, mantendo a ligação à venda original. Aguarde o resultado do ImaCash e a saída de numerário; registar o reembolso não comprova a devolução.

Reenvios e resultados incertos

Conserve transaction_id e, em V2, a mesma Idempotency-Key. Guarde operation_id e consulte o acompanhamento antes de reenviar. Um timeout não prova que o pedido não chegou. Se o acompanhamento exigir revisão, são necessárias verificação local e ajuda do suporte; outro reenvio não o desbloqueia. Não repita cobranças ou reembolsos nem reinicie para resolver uma incerteza.

Erros e referências de suporte

Verifique o JSON além do HTTP: V1 pode responder 200 com status=error. O manual explica 400, 401, 403, 404, 405, 409, 413 e 503. Para suporte, conserve request_id, operation_id, referência, hora e código HTTP, sem credenciais ou dados de clientes.

V1, V2 e alcance real

V1 continua disponível e V2 é opcional. Um relatório incompleto, incluindo clientes antigos que omitem montantes zero, pode ficar REPORTED_UNVERIFIED. device_state=not_observed não comprova ligação nem desconexão. Não há comandos diretos ao equipamento nem webhooks gerais de saída, e as permissões locais continuam necessárias. Valide modelo e versão com o fornecedor antes da utilização real.