React Native

Integração do SDK SoftPOS em React Native — instalação, API tipada 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-react-native é uma ponte fina sobre o SDK nativo: toda a lógica de venda continua no AAR Android. A API é Promise-based e tipada em TypeScript.

Instalação

yarn add @eagleix/softpos-react-native

No Android o autolinking resolve o módulo nativo. O módulo depende do AAR com.eagleix.softpos:sdk, então o repositório Maven privado da Eagle precisa estar declarado nos repositories do projeto Android do app.

android/build.gradle

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

Rode um build nativo depois de instalar (npx react-native run-android) — Fast Refresh não carrega módulos nativos novos.

Uso

import { EagleSoftpos, PaymentMethod } from '@eagleix/softpos-react-native';

// 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({
  apiKey: Config.EAGLE_API_KEY,
  baseUrl: Config.EAGLE_BASE_URL,
  environment: 'SANDBOX',
});

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

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

// 5. Cobrar.
const result = await EagleSoftpos.startSale({
  amountInCents: 5000,
  method: PaymentMethod.Credit,
  installments: 3,
});

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

API

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

interface EagleInitOptions {
  apiKey: string;
  baseUrl: string;
  environment: 'SANDBOX' | 'PRODUCTION';
}

interface SaleRequest {
  amountInCents: number;
  method: PaymentMethod;        // Menu | Debit | Credit | PixWallets
  installments?: number;        // padrão 1
  receiptNumber?: string;
  operator?: string;
  collectTimeoutSeconds?: number; // padrão 60
}

interface SaleResult {
  approved: boolean;
  codRespCode: number;
  codRespCategory: 'SUCCESS' | 'DENIED' | 'CANCELED' | 'ERROR';
  codRespDescription: string;
  nsuSitef?: string;
  nsuHost?: string;
  authorizationCode?: string;
  cardBrand?: string;
  acquirerNetwork?: string;
  installments?: number;
  merchantReceipt?: string;
  customerReceipt?: string;
}

Erros

Falhas rejeitam a Promise com um code de EagleErrorCode:

import { EagleErrorCode } from '@eagleix/softpos-react-native';

try {
  const result = await EagleSoftpos.startSale({ amountInCents: 5000, method: PaymentMethod.Credit });
} catch (e: any) {
  switch (e.code) {
    case EagleErrorCode.MSitefNotInstalled: return EagleSoftpos.openPlayStore();
    case EagleErrorCode.SellerNotActivated: return irParaAtivacao();
    case EagleErrorCode.Network:            return mostrarOffline();
    default:                                return mostrarErro(e.message);
  }
}

Código	Quando acontece
`NOT_INITIALIZED`	`startSale`/`activateSeller` antes de `initialize`
`MSITEF_NOT_INSTALLED`	App m-SiTef ausente
`UNSUPPORTED_ANDROID_VERSION`	Android abaixo de 12
`UNSUPPORTED_PLATFORM`	Chamada feita no iOS
`SELLER_NOT_ACTIVATED`	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 rejeitam a Promise: voltam como SaleResult com approved: false. Trate-os por codRespCategory.

Comportamento no iOS

O m-SiTef Tap on Phone não existe no iOS. Para o app híbrido compilar e rodar nas duas plataformas sem código condicional, a API é idêntica, mas no iOS:

isSupported() e isMSitefInstalled() retornam false;
os demais métodos rejeitam com UNSUPPORTED_PLATFORM.

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

Diferenças em relação ao SDK nativo

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

Se o seu app precisa de um desses, chame o SDK nativo diretamente no módulo Android e exponha o que faltar pela sua própria ponte.

React Native

Instalação

Uso

API

Erros

Comportamento no iOS

Diferenças em relação ao SDK nativo

On this page