API REST ImaCash: guia de integração

Antes de começar

Selecione REST API Imagina em Configuração > Integração do ImaCash. Cloud tem de autorizar a licença para REST e aceitar a manutenção ou o período de teste. Copie o token dessa licença, nunca a palavra-passe do administrador nem o segredo interno do conector. Se não aparecer, anote a versão e a referência numérica da licença e contacte o suporte; não crie outra venda ou demo para diagnosticar.

Ligação, token e âmbito

A URL base é https://restapi.imaginaits.com/. Envie x-auth-token em cada pedido HTTPS. Cada token limita as operações à sua licença. Não o inclua em URLs, capturas, registos, repositórios ou correio. Os exemplos usam YOUR_TOKEN e referências fictícias. A documentação não executa operações.

Referências e valores

transaction_id identifica de forma estável uma operação do seu programa e licença: reutilize exatamente o mesmo valor após um timeout. user e terminal são referências comerciais do operador e posto, não credenciais nem permissões ImaCash. amount usa unidades menores: 2100 representa 21,00 EUR e -2100 uma devolução de 21,00 EUR. method=1 significa numerário e method=0 cartão; registar cartão não confirma pagamento bancário.

Criar e consultar uma cobrança

Envie JSON com transaction_id, amount, user, terminal e method. status=ok confirma o registo em Cloud, não a cobrança concluída. Consulte a mesma referência e verifique HTTP e JSON. Um 409 ao criar pode indicar referência existente: consulte-a e compare os dados, sem enviar outro ID.

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}'

curl 'https://restapi.imaginaits.com/statustransaction.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'

curl 'https://restapi.imaginaits.com/transactioncashflow.php?transaction_id=TX-DEMO-20261029-001' --header 'x-auth-token: YOUR_TOKEN'

Reenvios, falhas de ligação e autorizações

Mantenha a mesma chave e referência ao reenviar V2 para recuperar o acompanhamento. A mesma chave para outra referência é rejeitada. Outra chave para uma venda com pedido existente também é rejeitada; consulte a venda para recuperar operation_id. Se ImaCash estiver fechado, não enviar relatório ou faltarem detalhes, fica sem confirmação. Após uma espera razoável, mostre revisão pendente e conserve a referência; não repita cobranças, devoluções ou reinícios. V2 conserva palavras-passe, permissões e proteções locais.

Devolver uma venda paga

Uma venda PAID não pode ser cancelada por este circuito. Crie uma devolução com referência própria e valor negativo, conservando a relação com a venda original no seu programa. O registo não confirma dinheiro entregue: aguarde ImaCash e verifique os valores. Não reutilize o ID da venda.

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}'

Erros e suporte

401: falta token. 403: token ou licença não autorizados, possivelmente REST ou manutenção. 404 V2: recurso ausente ou fora do âmbito. 409: conflito de chave, referência ou estado; leia error.code. 400: parâmetros ou JSON inválidos. 405: método incorreto. 413: corpo excessivo. 503: serviço ou acompanhamento indisponíveis, sem provar avaria da máquina. Timeout ou 5xx não provam que o pedido não chegou. Envie ao suporte request_id, operation_id, referência, hora e HTTP, sem credenciais.

Compatibilidade e limites publicados

Rotas, autenticação, campos e estados V1 mantêm-se. V2 adiciona uma rota sem migração obrigatória ou novos estados em transaction_status V1. *_at_utc usa UTC; created_at conserva o formato anterior. device_state=not_observed não significa máquina desligada. Não há comandos diretos ao dispositivo nem webhooks genéricos de saída: consulte capacidades. Valores ausentes são null, não zeros confirmados. Alguns clientes anteriores omitem valores zero no relatório: mesmo após a conclusão local, V2 mantém REPORTED_UNVERIFIED se faltar esse valor explícito.

Testar antes de produção

Num ambiente autorizado, teste criação, consulta, referência repetida, cancelamento antes/depois de inserir dinheiro, autorização local recusada, ImaCash sem ligação e perda de resposta. Não conclua cancelamento apenas por 200/202. Valide cada modelo e versão com o fornecedor; um exemplo HTTP não substitui o ensaio físico.

Exemplos para descarregar