Flutter

Integração do SDK SoftPOS em Flutter — instalação, API Dart e comportamento no iOS

Em construção

Esta seção documenta um SDK ainda em desenvolvimento. A API pode mudar, os pacotes ainda não estão publicados e os fluxos descritos não foram homologados em produção.

O pacote eagleix_softpos é uma ponte fina sobre o SDK nativo, via MethodChannel: toda a lógica de venda continua no AAR Android.

Instalação

pubspec.yaml

dependencies:
  eagleix_softpos: ^0.1.0

O plugin Android depende do AAR com.eagleix.softpos:sdk, então o repositório Maven privado da Eagle precisa estar declarado no projeto Android do app:

android/build.gradle

allprojects {
    repositories {
        maven { url "<repositório Maven informado pela Eagle>" }
    }
}

Requer Flutter 3.19+ e Dart 3.3+.

Uso

import 'package:eagleix_softpos/eagleix_softpos.dart';

// 1. Gate de plataforma — false no iOS e em Android < 12.
if (!await EagleSoftpos.isSupported()) return;

// 2. Inicialização (uma vez, ex.: no bootstrap do app).
await EagleSoftpos.initialize(EagleInitOptions(
  apiKey: apiKey,
  baseUrl: baseUrl,
  environment: 'SANDBOX',
));

// 3. Garantir o m-SiTef.
if (!await EagleSoftpos.isMSitefInstalled()) {
  await EagleSoftpos.openPlayStore();
  return;
}

// 4. Ativar o vendedor (uma vez por vendedor).
final activation = await EagleSoftpos.activateSeller(sellerToken);

// 5. Cobrar.
final result = await EagleSoftpos.startSale(SaleRequest(
  amountInCents: 5000,
  method: PaymentMethod.credit,
  installments: 3,
));

if (result.approved) {
  mostrarComprovante(result.customerReceipt);
} else {
  mostrarRecusa(result.codRespDescription);
}

API

Método	Retorno	Descrição
`isSupported()`	`Future<bool>`	`false` no iOS e em Android abaixo de 12
`initialize(options)`	`Future<void>`	Configura `apiKey`, `baseUrl` e `environment`
`isMSitefInstalled()`	`Future<bool>`	Presença do app m-SiTef no aparelho
`openPlayStore()`	`Future<void>`	Abre a página do m-SiTef na loja
`activateSeller(sellerToken)`	`Future<ActivationResult>`	Ativa o vendedor e guarda o `posId` da sessão
`startSale(request)`	`Future<SaleResult>`	Executa a venda

class SaleRequest {
  SaleRequest({
    required int amountInCents,
    required PaymentMethod method,   // menu | debit | credit | pixWallets
    int installments = 1,
    String? receiptNumber,
    String? operator,
    int collectTimeoutSeconds = 60,
  });
}

class SaleResult {
  final bool approved;
  final int codRespCode;
  final String codRespCategory;   // SUCCESS | DENIED | CANCELED | ERROR
  final String codRespDescription;
  final String? nsuSitef;
  final String? nsuHost;
  final String? authorizationCode;
  final String? cardBrand;
  final String? acquirerNetwork;
  final int? installments;
  final String? merchantReceipt;
  final String? customerReceipt;
}

Erros

Falhas lançam EagleException, com um EagleErrorCode tipado:

try {
  final result = await EagleSoftpos.startSale(request);
} on EagleException catch (e) {
  switch (e.code) {
    case EagleErrorCode.mSitefNotInstalled:
      await EagleSoftpos.openPlayStore();
    case EagleErrorCode.sellerNotActivated:
      irParaAtivacao();
    case EagleErrorCode.network:
      mostrarOffline();
    default:
      mostrarErro(e.message);
  }
}

`EagleErrorCode`	Quando acontece
`notInitialized`	Chamada antes de `initialize`
`mSitefNotInstalled`	App m-SiTef ausente
`unsupportedAndroidVersion`	Android abaixo de 12
`unsupportedPlatform`	Chamada feita no iOS
`sellerNotActivated`	Venda antes de `activateSeller`
`network`	Falha de comunicação com o backend Eagle
`backend`	Backend Eagle respondeu erro de negócio
`unexpected`	Demais falhas

Recusa e cancelamento não lançam exceção: voltam como SaleResult com approved == false. Trate-os por codRespCategory.

Comportamento no iOS

O plugin declara apenas a plataforma Android, e o guard é feito em Dart (Platform.isAndroid) — não há MissingPluginException no iOS. Lá:

isSupported() e isMSitefInstalled() retornam false;
os demais métodos lançam EagleException(EagleErrorCode.unsupportedPlatform).

Gate a UI de cobrança por isSupported(). Esse é o único tratamento de plataforma que o seu código precisa ter.

Diferenças em relação ao SDK nativo

Recurso	Nativo	Flutter
Estado observável (`Eagle.state`)	Sim	Não — o estado é o ciclo do `Future`
Backend customizado (`EagleBackend`)	Sim	Não — sempre HTTP, via `baseUrl`
Logger customizado	Sim	Não

Flutter

Instalação

Uso

API

Erros

Comportamento no iOS

Diferenças em relação ao SDK nativo

On this page