Integrações de POS

A página de configurações Integrações conecta um servidor HandyCafe elegível a um terminal Ödeal D2D. A disponibilidade é verificada pela nuvem do HandyCafe. O menu e a página ficam completamente ocultos quando a lan house não tem permissão para usar a Ödeal.

Antes de Começar

Você precisa de uma assinatura ativa da nuvem do HandyCafe, de uma chave de comerciante da Ödeal e de uma chave secreta da Ödeal. Também é necessário criar o terminal na área Cihazlarım da Ödeal. O nome exato atribuído a esse terminal é o externalDeviceKey dele. Comece pelo ambiente Stage. Passe para Produção somente depois que a Ödeal aprovar as credenciais de produção e a configuração de callback.

Configurar a Ödeal

1. Abra Configurações e selecione Integrações.
2. Em Conta Ödeal, informe a chave de comerciante e a chave secreta fornecidas pela Ödeal. O HandyCafe envia esses valores diretamente para a nuvem do HandyCafe. Eles são criptografados e não ficam armazenados no banco de dados local nem voltam a ser exibidos.
3. Selecione Teste de Conexão. Quando há chaves novas, o HandyCafe as salva com segurança antes de testar a conexão com a API da Ödeal. Esse teste verifica apenas a conta Ödeal. Ele não comprova que o terminal está pareado ou online.
4. Adicione o terminal. Informe um nome local claro para o dispositivo. Em Nome do dispositivo na Ödeal (externalDeviceKey), informe o nome exato do dispositivo criado na Ödeal. Depois informe o PaxID opcional, o ambiente, o tempo de espera do pagamento, a cidade do cliente, o distrito do cliente, a alíquota de IVA da sessão e a alíquota de IVA do pedido.
5. Ative Integração de POS Ativa e selecione Salvar.
6. Conclua um recibo em dinheiro no Stage e um pagamento com cartão no Stage para conferir o pareamento do terminal e os dois caminhos de liquidação.

Nesta versão há suporte para apenas um terminal Ödeal ativo por servidor. Isso evita que um pagamento seja encaminhado para o terminal errado antes de existir um seletor de terminal para o operador de caixa.

O HandyCafe salva o inventário de terminais localmente antes de a nuvem verificar um novo par de credenciais. Uma recusa de credencial pela Ödeal não descarta o nome do terminal nem os campos de pareamento. Um terminal que precisa de novas credenciais fica armazenado como inativo até que essas credenciais sejam verificadas para o ambiente selecionado.

A página Integrações lê o inventário de terminais diretamente do banco de dados SQLite local e o exibe sem esperar pela nuvem. Apenas o status da credencial criptografada e a permissão remota do provedor exigem uma requisição à nuvem.

Se a Ödeal recusar a configuração, o HandyCafe exibe a explicação devolvida por ela. Uma resposta de perfil de organização não encontrado significa que o par de chave de comerciante e chave secreta não pertence a nenhuma organização no ambiente Stage ou Produção selecionado.

Comportamento do Pagamento

Quando o método de pagamento ativo é dinheiro ou cartão, o fechamento da sessão de PC, o fechamento da sessão de console e o encerramento de um pedido avulso enviam uma cesta idempotente para a Ödeal. O dinheiro é enviado como a opção de pagamento CASH documentada pela Ödeal. O terminal registra o pagamento em dinheiro e imprime o cupom fiscal ou o recibo e-Arquivo sem abrir uma tela de cobrança no cartão. O cartão é enviado como CREDITCARD; o HandyCafe aguarda o resultado do callback enquanto o cliente conclui o pagamento no terminal. Um fechamento que combina dinheiro e cartão envia as duas opções de pagamento com os respectivos valores.

O cliente pode escolher parcelamento no terminal quando o cartão e o contrato do estabelecimento permitem. O HandyCafe armazena a quantidade de parcelas informada junto com a venda local. A venda local só é confirmada depois que a Ödeal confirma a transação. Se a gravação local falhar depois dessa confirmação, o HandyCafe solicita um cancelamento no mesmo dia. Um cancelamento que falha gera um erro de conciliação manual e precisa ser conferido no relatório de transações da Ödeal. Os tipos de método de pagamento diferentes de dinheiro e cartão seguem pelo fluxo de liquidação já existente do HandyCafe.

Testes e Operações do Terminal

O Teste de Conexão verifica apenas as credenciais de comerciante da Ödeal e o acesso à API. Ele não imprime recibo, não cobra cartão nem comprova que o externalDeviceKey está pareado com o terminal.

A documentação da API D2D fornecida não define endpoints separados de Imprimir Recibo de Teste ou Cobrança de Teste. Os testes de homologação usam cestas normais no ambiente Stage: envie uma cesta em dinheiro e confira o cupom impresso, depois envie uma cesta em cartão e conclua uma transação à vista ou parcelada no terminal. Use somente os dados de cartão de teste do Stage fornecidos pela Ödeal.

Os casos de homologação da Ödeal incluem o fechamento do dia e a reimpressão do último recibo. Ambas são operações do terminal. A D2D não documenta chamadas remotas de API para elas, portanto o HandyCafe não as expõe como botões remotos.

Ativação e Desativação Remota

Os administradores do HandyCafe controlam a Ödeal em Admin > Configurações de Admin > Provedores de POS, no Painel do HandyCafe. A chave global é o controle mestre. Os padrões por país usam códigos ISO de duas letras, como TR. Os controles por lan house podem abrir ou fechar a Ödeal explicitamente para uma licença. Uma decisão específica da lan house prevalece sobre o padrão do país. Ao redefinir a decisão específica, a lan house volta a seguir o padrão do país dela.

A ordem de decisão é chave global, decisão específica da lan house e por fim padrão do país. Uma chave global desativada fecha a Ödeal para todas as lan houses. Um fechamento explícito da lan house oculta a página mesmo que o país dela esteja aberto. Uma abertura explícita da lan house libera a página mesmo que o país dela não esteja na lista padrão. Desativar o acesso bloqueia imediatamente a criação de novas cestas. As transações pendentes já existentes ainda podem ser consultadas ou canceladas, de modo que um pagamento em andamento não fique preso.

O servidor verifica a disponibilidade pela nuvem do HandyCafe e mantém em cache a última decisão de país e de lan house verificada com sucesso. O catálogo de provedores retorna HTTP 200 com um error.code estruturado quando a credencial dele é inválida. O aplicativo desktop trata essa resposta renovando a credencial e tentando de novo. Uma falha temporária de autenticação ou de rede não reinterpreta como desativada uma decisão de administrador que está ativa, então o menu Integrações continua estável. Uma resposta bem-sucedida posterior atualiza o cache imediatamente, inclusive quando ela traz uma decisão de desativação do administrador. Sem nenhuma decisão verificada anteriormente, um país de lan house desconhecido, uma assinatura inativa ou um provedor desativado mantém a página oculta. As novas operações da Ödeal são sempre autorizadas de novo pela nuvem, mesmo quando a visibilidade em cache é usada. O país salvo na licença é usado quando o perfil sincronizado da lan house não tem país.

Segurança e Recuperação

As credenciais da Ödeal são criptografadas na nuvem do HandyCafe com a chave do cofre da implantação. As requisições de callback são autenticadas pela chave de requisição configurada ou pelos cabeçalhos de chave de comerciante e chave secreta da Ödeal. Os códigos de referência da cesta são estáveis para cada pedido ou sessão. Repetir o mesmo fechamento não cria uma segunda cobrança.

O cancelamento na Ödeal só está disponível segundo as regras de mesmo dia dela, antes de o lote do terminal fechar. Uma cesta pendente pode ser removida separadamente antes de o pagamento ser concluído. A Ödeal D2D não oferece uma operação geral de reembolso. Use o back office e o relatório de transações da Ödeal quando a janela de cancelamento já tiver passado.

A Ödeal D2D não oferece uma operação documentada de relatório Z remoto ou de fechamento de dia. Conclua o fechamento do dia no terminal. O HandyCafe consegue ler relatórios de transações para conciliação e registra os callbacks de retorno de pagamento enviados pela Ödeal.