clisitef_payment_tech 3.1.0

Plugin Flutter para integrar sua aplicação com o SDK Android da Clisitef para meios de pagamento.

Clisitef Payment Tech

Sobre   |   Funcionalidades   |   Tecnologias   |   Requisitos   |   Start   |   Licença   |   Autor

🎯 Sobre

Plugin Flutter para facilitar integração com o TEF da Clisitef.

🔐 Licenciamento

O plugin só funciona com uma licença válida, validada pela API de licenças da JY Labtech (jylabtech_core).

Onde adquirir

Cadastre-se e gerencie suas licenças no portal portal.jylabtech.com.br. Quem já tinha conta no portal antigo entra com o mesmo e-mail e a mesma senha.

• Produto: Licença plugin de pagamento — a mesma licença vale para qualquer plugin de pagamento da JY Labtech.
• Plano mensal: cobrado por dispositivo. Cada aparelho que valida a licença ocupa uma vaga.
• Plano debug: cortesia concedida automaticamente no cadastro, válida por 365 dias e limitada a 2 aparelhos. Use para desenvolvimento e testes.
• Os aparelhos vinculados podem ser consultados e desativados pelo portal. Um aparelho desativado deixa de validar a licença.
• As chaves de licença já existentes continuam valendo, com os mesmos valores. Chaves novas (formato JYL-...) também funcionam.

Chaves

As chaves são informadas em ClisitefTech.I.initPayment (não são mais lidas de local.properties):

Parâmetro	Valor
licenceKey	Obrigatório. A chave da sua licença, copiada do portal.
licenceInternalKey	Opcional. Padrão: constante licenceCheck (https://portal-api.jylabtech.com.br/pos-payments/licence/check em base64).

await ClisitefTech.I.initPayment(licenceKey: 'SUA_LICENCA');

O plugin sempre valida a licença no servidor oficial da JY Labtech. A URL fica travada no código nativo: se o licenceInternalKey apontar para qualquer outro endereço, inclusive o servidor antigo (aHR0cHM6Ly9wb3MtcGF5bWVudHMtYXBp...), o valor é ignorado e a validação é feita no servidor oficial.

Como funciona a validação

• Na chamada de initPayment, o plugin envia ao servidor a chave e a identificação do aparelho (ANDROID_ID, serial e modelo). O aparelho é vinculado à licença na primeira validação.
• Toda operação (configureClisitef, clisitefTransaction e os métodos do m-SiTef) confere a licença no nativo antes de chamar o SDK. Não basta ter chamado initPayment uma vez: se a licença vencer, for suspensa ou cancelada, as operações seguintes falham.
• Com a licença válida, o resultado fica salvo no aparelho de forma criptografada e o plugin funciona offline até o vencimento da licença, por no máximo 7 dias sem nova consulta. Depois disso é preciso conexão com a internet para validar de novo. Um cache com data de gravação no futuro (relógio adulterado), de outra chave ou de outro servidor é descartado.
• O vencimento (expiredAt) já considera o período de tolerância em caso de atraso no pagamento.
• A consulta ao servidor tem timeout de 15 segundos e roda fora da thread principal.

Erros de licença

Se a licença for inválida, vencida, suspensa ou cancelada, initPayment e qualquer operação lançam PlatformException com code: 'LICENCE_ERROR' e message com a mensagem devolvida pelo servidor (ou Erro ao validar licença (HTTP <código>) quando o servidor não devolve mensagem). Chamar uma operação sem um initPayment bem-sucedido lança PlatformException com code: 'LICENCE_NOT_INITIALIZED'.

HTTP	Situação	O que fazer
404	Licença não encontrada.	Confira o licenceKey (sem espaços).
412	Limite de aparelhos da licença atingido ou aparelho desativado.	Desative um aparelho antigo ou contrate mais vagas no portal; reative o aparelho, se for o caso.
428	Licença vencida, suspensa ou cancelada.	Regularize ou renove a licença no portal.
403	Chave não enviada.	Informe o licenceKey em initPayment.
400	O aparelho não enviou um identificador estável.	Verifique se o app consegue ler o ANDROID_ID do aparelho.
429	Muitas tentativas em pouco tempo.	Aguarde alguns instantes e tente de novo.

Um licenceKey vazio gera PlatformException com code: 'INVALID_ARGUMENT'.

Troubleshooting

• Erro de conexão / timeout: o aparelho precisa de acesso à internet (sem proxy) na primeira validação e, depois, ao menos a cada 7 dias.
• 404 com uma chave que funcionava: confira se não houve erro ao copiar a chave.
• 412 após trocar de aparelho: desative o aparelho antigo no portal para liberar a vaga.
• Licença renovada, mas o app continua bloqueado: reinicie o app para chamar initPayment novamente; com conexão, a licença é consultada de novo.

✨ Funcionalidades

✔️ Cartão de crédito ✔️ Cartão de débito ✔️ PIX ✔️ Cancelamento ✔️ Reimpressão

🚀 Tecnologias

Para que o plugin funcione corretamente é necessário ter cadastro na Fiserv e passar alguns dados de configuração como parâmetro das funções.

• Flutter

✅ Requisitos

Para que o plugin funcione corretamente é necessário ter cadastro no Fiserv e suas credenciais de acesso.

⚠️⚠️⚠️ Esse plugin não funciona com PROXY!!! ⚠️⚠️⚠️

🏁 Starting

Adicione a dependência no pubspec.yaml:

dependencies:
  clisitef_payment_tech: ^3.1.0

Inicialmente para liberar o uso do plugin, é necessário chamar o método initPayment, responsável por validar as chaves de licença (veja Licenciamento) e inicializar o SDK. A chamada é assíncrona e deve ser aguardada antes de qualquer operação:

import 'package:clisitef_payment_tech/clisitef_payment_tech.dart';

await ClisitefTech.I.initPayment(licenceKey: 'SUA_LICENCA');

Os modelos ficam em package:clisitef_payment_tech/payments/model/...:

import 'package:clisitef_payment_tech/payments/enum/sitef_modality.dart';
import 'package:clisitef_payment_tech/payments/model/sitef_settings.dart';
import 'package:clisitef_payment_tech/payments/model/sitef_transaction.dart';
import 'package:clisitef_payment_tech/payments/model/tef_transaction_response.dart';

Através da função abaixo você irá realizar o setup do SDK conforme documentação da Fiserv. Passe como parâmetro as credenciais.

final int result = await ClisitefTech.I.payment.configureClisitef(
  sitefSettings: const SitefSettingsClisitef(
    serverIp: '...',
    storeCode: '...',
    posNumber: '...',
  ),
);

Transação: Utilize a função abaixo para chamar um método de pagamento, passando os devidos parâmetros solicitados.

final TefTransactionResponseClisitef response =
    await ClisitefTech.I.payment.clisitefTransaction(
  sitefSettings: sitefSettings,
  sitefTransaction: sitefTransaction,
);

Testes

Testes Dart (canal de plataforma e propagação de LICENCE_ERROR):

flutter test

Testes JVM do nativo (URL travada, regras da licença, resposta do servidor e cache offline), com JDK 17:

FLUTTER_SDK=$(dirname $(dirname $(which flutter))) \
  example/android/gradlew -p android/native testDebugUnitTest

Depois de alterar o código em android/native, regenere os binários com make build-native (ou sh scripts/build_android_aar.sh).

📝 License

This project is under license from MIT. For more details, see the LICENSE file.

JY Labtech

Feito por Jhonathan Queiroz

Back to top