> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CliSiTef

> Cobra débito, crédito, vale y Pix en un pinpad CliSiTef desde el kiosco Android con @fire-spark/payments-clisitef-pinpad-rn.

CliSiTef (Software Express) es el pinpad de los kioscos de Fire spark en Brasil. Un pago del dashboard es un botón del checkout. El adaptador habla con el pinpad; tu kiosco dibuja los avisos que él envía.

| | |
| - | - |
| Países | Brasil |
| Monedas | BRL |
| Estado | Disponible |
| Paquete | `@fire-spark/payments-clisitef-pinpad-rn` |

Solo kiosco Android. POS, web e iOS no usan este paquete.

Sigue las secciones de abajo para integrarlo a mano. Para dárselo a un agente, copia el prompt de [Prompt para un agente](#prompt-para-un-agente).

## Requisitos

* Un kiosco Android con el pinpad por USB.
* Un development build. Expo Go no carga el módulo nativo.
* Los binarios de CliSiTef de ese entorno (homologación o producción), de Software Express. Guárdalos fuera de git.

> [!WARNING]
>
> Los binarios y un `CLSIT` de producción se quedan fuera del repositorio. El template del kiosco es público, y Software Express licencia los binarios.

## Activarlo

1. En el dashboard, abre tu comercio, ve a **Payments** y crea un pago con el proveedor **CliSiTef** y el método **PIN pad**.
2. En **Connection Settings**, completa:

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Modalities | `modalities` | No | `DEBIT`, `CREDIT`, `VOUCHER` o `PIX`. Al menos una. Ver [Botón del checkout](#botón-del-checkout) |
| CNPJ Enterprise | `cnpj_enterprise` | No | CNPJ de la empresa registrado en SiTef, 14 dígitos |
| Operator | `operator` | No | Opcional. Si lo omites, el adaptador envía `KIOSKO_BR` |
| Restrictions by modality | `restrictions_by_modality` | No | Opcional. Oculta opciones del menú de CliSiTef para una modalidad, por ejemplo las cuotas en crédito |

3. En **Store settings**, completa cada tienda. La API le entrega al kiosco solo la fila de su tienda.

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| SiTef IP | `sitef_ip` | No | Servidor SiTef de la tienda |
| Store code | `store_code` | No | Código de tienda en SiTef, 8 caracteres |
| Store CNPJ | `cnpj_store` | No | CNPJ de la tienda. El adaptador quita la puntuación |
| Supervisor password | `secret_supervisor_password` | Sí | Opcional. Se usa en una anulación cuando el dispositivo no tiene una. El valor del dispositivo gana |

4. En cada kiosco, abre el dispositivo y la pestaña **Payments**. Los valores viven en `settings_overrides.payment_settings`, con el id del pago como clave. Ver [Configurar un dispositivo](https://firespark.cloud/docs/es/guides/payments/configure-a-device.md).

| Campo | Clave | Secreto | Notas |
| - | - | - | - |
| Terminal number | `terminal_number` | No | Terminal SiTef asignado a este kiosco |
| Supervisor password | `secret_supervisor_password` | Sí | Opcional. Las anulaciones automáticas lo envían. Si está vacío, el adaptador lo pide con `ui.input` |

`pinpad_type` no está en el formulario. Si lo omites, el cliente usa `ANDROID_USB`. Para Bluetooth o detección automática, pon `pinpad_type` en `ANDROID_BT` o `ANDROID_AUTO` en los mismos ajustes del dispositivo con el endpoint [Actualizar dispositivo de kiosco](https://firespark.cloud/docs/es/integrations-api/kiosk/devices/put.md).

> [!NOTE]
>
> Un pago al que le falta un dato de la tienda o del dispositivo no llega al kiosco, así que su botón no aparece en el checkout. En el listado de dispositivos, la columna **Payments** muestra lo que sigue vacío.

## Botón del checkout

Cada pago CliSiTef es un botón. El template del kiosco ya pinta una tarjeta por pago a partir de `services.payments.list`. No agregas un componente de botón.

* Varias modalidades en un pago: el cliente elige una antes de que arranque el pinpad. El adaptador pregunta con `ui.select`, título `Selecione a forma de pagamento` y opciones `Débito`, `Crédito`, `Voucher` y `Pix`. Si cierra el selector, la promesa se rechaza y el pinpad no arranca.
* Pix en su propio botón: crea un segundo pago con `modalities: ["PIX"]`. Queda al lado de la tarjeta y del efectivo. El template trata como Pix un pago cuya única modalidad es `PIX` (`isPixOnlyPayment` en los helpers del checkout) y muestra la ilustración de Pix. Cualquier otro pago `PIN_PAD` muestra la ilustración de tarjeta.

> [!NOTE]
>
> Pix es una transferencia: el cliente paga con un QR desde su banco. El QR y el resultado igual pasan por los binarios nativos de CliSiTef (`@fire-spark/payments-clisitef-client`), el mismo módulo que el débito y el crédito. Pix es una modalidad `PIX` de este pago. No puede funcionar por separado, ni como un método `BANK_TRANSFER` aparte.

Débito y vale comparten una función de CliSiTef. Las restricciones son lo que los separa. Una lista de restricciones de crédito sobre el vale hace que SiTef rechace el cobro.

## Usarlo en el SDK

Agrega los dos paquetes a la app del kiosco. No forman parte del template público. Fíjalos a la misma versión que `@fire-spark/payments`.

```bash theme={null}
pnpm add @fire-spark/payments-clisitef-pinpad-rn@0.11.0 @fire-spark/payments-clisitef-client@0.11.0
```

`@fire-spark/payments-clisitef-client` es el módulo Android y el config plugin de Expo. `@fire-spark/payments-clisitef-pinpad-rn` es el adaptador. Cobra con el adaptador: confirma, deshace y recupera una transacción después de un reinicio.

En `app.config.ts`:

```typescript theme={null}
export default {
  plugins: [
    [
      "@fire-spark/payments-clisitef-client",
      { binariesDir: process.env.CLISITEF_BINARIES_DIR }
    ]
  ]
};
```

`binariesDir` es absoluta, o relativa a la raíz de la app. Apúntala a una carpeta fuera de git:

```text theme={null}
binaries/
  clisitef-android.jar
  jniLibs/
    arm64-v8a/
      libclisitef.so
```

Después genera el proyecto Android:

```bash theme={null}
CLISITEF_BINARIES_DIR=/ruta/a/binarios npx expo prebuild --platform android --clean
```

El plugin copia el JAR y los `.so`, activa `useLegacyPackaging` (Android 14 y posteriores no cargan un `libclisitef.so` comprimido) y agrega los permisos de internet y Bluetooth. El prebuild se detiene con `[clisitef] missing ...` si falta el JAR o `libclisitef.so`.

Registra el adaptador una vez por pedido, con almacenamiento del dispositivo. Pasa `storage` siempre: una transacción que el débito dejó abierta sigue visible para el crédito, y la app puede deshacerla después de un reinicio. Software Express admite una sola instancia del cliente. El adaptador ya usa la compartida.

```typescript theme={null}
import AsyncStorage from "@react-native-async-storage/async-storage";
import { clisitefPinPadPayments } from "@fire-spark/payments-clisitef-pinpad-rn";

const deviceStorage = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key)
};

order.setPaymentAdapters([
  clisitefPinPadPayments({ storage: deviceStorage })
]);

order.setPaymentOptions({
  isProduction: merchant.env_is_prod,
  collectAt: "KIOSK",
  deviceSettings: kioskConfig.overrides.payment_settings,
  deviceId: kioskConfig.device.id
});
```

`kioskConfig` es lo que devuelve `getKioskConfig`. Los valores del dispositivo llegan en `overrides.payment_settings`.

El adaptador no dibuja nada. Los avisos llegan por `setPaymentUI`. Muestra el texto de CliSiTef tal como llega, en portugués.

```typescript theme={null}
order.setPaymentUI({
  message: ({ text }) => setTerminalMessage(text),
  select: ({ title, options }) => openPicker(title, options),
  input: ({ label, type }) => openInput(label, type),
  confirm: ({ text }) => openYesNo(text),
  action: ({ type, payload }) => {
    if (type !== "qr") return;
    if (payload) showQr(payload);
    else hideQr();
  }
});
```

| Método | Cuándo llega | Qué devuelves |
| - | - | - |
| `message` | "Insira o cartão", "Digite a senha", "Aguarde" | Nada. Llegan varios seguidos: muestra el último |
| `select` | La modalidad, la red del vale, o un menú de SiTef que el adaptador deja abierto | Una promesa con el `value` elegido. Recházala si el cliente cancela |
| `input` | Un dato que pide SiTef, incluida la clave de supervisor | Una promesa con el texto. `type: "password"` va enmascarado |
| `confirm` | Una pregunta de sí o no | Una promesa con `true` o `false` |
| `action` | El QR de Pix | Nada. Ver el contrato de abajo |

Contrato del QR de Pix:

```typescript theme={null}
{ type: "qr", payload: "00020126...", format: "text", expiresAt: null } // mostrar
{ type: "qr", payload: "" } // ocultar
```

`payload` es el texto de copia y pega de Pix. Dibújalo como código QR. Un `payload` vacío lo oculta, y también lo oculta el fin de `payIntent`. `expiresAt` llega `null`: SiTef no manda vencimiento, y el plazo del cobro es de 180 segundos. Los mensajes siguen llegando debajo del QR. El control de cancelar rechaza la promesa del flujo.

Cobra el pago que eligió el cliente:

```typescript theme={null}
await order.setTenders([
  {
    method: "PIN_PAD",
    provider: "clisitef",
    payment_id: payment.id,
    collect_at: "DEVICE",
    allocation: null
  }
]);

const result = await order.payIntent({
  onProgress: progress => render(progress)
});
```

`payIntent({ payment })` sigue colocando un tender. Para partir CliSiTef con otro método, llama a `setTenders` con una asignación y después a `payIntent()`. Ver [Usar pagos en el SDK](https://firespark.cloud/docs/es/guides/payments/use-payments-in-the-sdk.md).

El plazo del cobro es de 180 segundos. Cubre la carga de tablas del pinpad, la elección de modalidad, la tarjeta y el PIN. Deja `runtime.timeout_ms` sin definir para conservar ese plazo. Un valor en el pago lo reemplaza, así que pon `180000` o más. Para subir el valor por defecto del adaptador, pasa `timeoutMs`:

```typescript theme={null}
clisitefPinPadPayments({ storage: deviceStorage, timeoutMs: 240_000 });
```

`order.getMissingPaymentFields(payment)` lista los campos del dispositivo que siguen vacíos. La API ya oculta un pago incompleto. Usa el helper en la pantalla de administración del kiosco cuando quieras mostrar qué falta.

## Qué ve el cliente

El mensaje del pinpad, el selector de modalidad cuando el pago tiene más de una, y el QR de Pix. En `PAID`, imprime `metadata.receipt.customer` (texto plano, la vía del cliente) y sigue con el pedido. En `FAILED` con `CANCELLED_BY_USER`, vuelve a la lista de métodos sin mostrar un error. En `AMBIGUOUS` (`metadata.needs_review`), deja el cobro como está: la tarjeta puede haberse leído, o el QR puede haberse mostrado. Manda al cliente al mostrador.

El NSU, el código de autorización, la marca, los últimos 4 dígitos y el cupón fiscal están en `result.metadata.payment`. Pix no tiene marca ni últimos 4 (`entry_mode: "QR"`). El kiosco no los guarda por su cuenta.

## Webhooks

Ninguno.

## Anulaciones

`order.cancel()` anula un pedido que no se entregó. `order.refund()` reembolsa uno que sí. Cada uno anula los cobros del pinpad y llama a su endpoint una vez.

| Modalidad | Función de CliSiTef |
| - | - |
| Crédito | 210 |
| Débito y vale | 211 |
| Pix | 123 |

El adaptador envía el monto, la fecha, el NSU del host y la clave de supervisor (`secret_supervisor_password` del dispositivo o, si no hay, de la tienda). Si no hay ninguna, la pide con `ui.input` (`type: "password"`). Mantén `setPaymentUI` montado durante la anulación.

| Resultado | Qué hace el kiosco |
| - | - |
| `REFUNDED` o `CANCELLED` | La anulación terminó. Imprime `metadata.provider.void.receipt.customer` si está |
| `PAID` con `needs_review` y un error reintentable | La anulación quedó en cola. Dile al cliente que vaya al mostrador. Desde la pantalla de administración del kiosco, corre `order.runPaymentTerminal(payment, "retry_pending_reversals")` |
| `PAID` con `REVERSAL_NOT_ALLOWED` o `MANUAL_REVERSAL_REQUIRED` | SiTef rechazó la anulación, o faltó un dato (NSU del host, fecha o modalidad). Anúlala desde el menú administrativo de SiTef |

## Errores comunes

| Código Spark | Código del proveedor | Qué hacer |
| - | - | - |
| `CANCELLED_BY_USER` | `-2`, `-6`, `-15` | El cliente canceló en el pinpad o cerró tu aviso. Vuelve a los métodos |
| `CARD_DECLINED` | `-40` y otros códigos positivos | SiTef o el autorizador rechazó. Ofrece reintentar u otro método |
| `TERMINAL_BUSY` | `-12` | Quedó una rutina abierta. El siguiente cobro la aborta y reintenta `configure` una vez |
| `TERMINAL_NOT_CONFIGURED` | — | Faltan datos de la tienda o del dispositivo, o `init` falló (IP, tienda o terminal). Revisa [Activarlo](#activarlo) |
| `WALLET_REJECTED` | `-24` | Pix no está habilitado para esta tienda en SiTef. Quita `PIX` de `modalities`, o pide a operaciones que lo habilite |
| `TIMEOUT` | `CLISITEF_TIMEOUT` | Se acabó el plazo de 180 segundos. Pon `runtime.timeout_ms` en `180000` o más |
| `AMBIGUOUS` | — | Se cortó el enlace después de leer la tarjeta o de mostrar el QR. Déjalo para revisión. Ver [Errores de pago](https://firespark.cloud/docs/es/guides/payments/errors.md) |

## Compatibilidad

| `@fire-spark/payments-clisitef-pinpad-rn` | Proveedor | `@fire-spark/payments` |
| - | - | - |
| 0.11.0 | CliSiTef (Software Express), Android | Misma versión que `@fire-spark/payments-clisitef-client` |

## Prompt para un agente

Pega esto en el agente que edita la app del kiosco. Cubre solo CliSiTef. Las secciones de arriba son el mismo trabajo, escrito para una persona.

```text title="Prompt de integración" theme={null}
Integra solo el pinpad CliSiTef en esta app de kiosco Android de Fire spark. No agregues ningún otro proveedor de pagos. No agregues este paquete a POS, web ni iOS.

CliSiTef (Software Express) cobra débito, crédito, vale y Pix en un pinpad USB en Brasil (BRL). Un pago del dashboard es un botón del checkout. El template del kiosco ya pinta una tarjeta por pago a partir de services.payments.list (CheckoutPaymentMethodCard). No crees un componente de botón nuevo.

Paquetes, fijados a la misma versión que @fire-spark/payments:
- @fire-spark/payments-clisitef-pinpad-rn@0.11.0 (adaptador)
- @fire-spark/payments-clisitef-client@0.11.0 (módulo Android y config plugin de Expo)

Cobra solo con clisitefPinPadPayments. No llames al cliente nativo, ni a finishTransaction, ni a abortTransaction. El adaptador confirma, deshace y recupera una transacción después de un reinicio. Software Express admite una sola instancia del cliente; el adaptador ya usa la compartida.

Setup nativo:
- Expo Go no carga el módulo. Usa un development build.
- En app.config.ts agrega el plugin ["@fire-spark/payments-clisitef-client", { binariesDir: process.env.CLISITEF_BINARIES_DIR }].
- Los binarios se quedan fuera de git (licencia de Software Express). La carpeta tiene clisitef-android.jar y jniLibs/<abi>/libclisitef.so. No commitees binarios ni un CLSIT de producción.
- Genera Android con CLISITEF_BINARIES_DIR definido: npx expo prebuild --platform android --clean.
- El plugin copia el JAR y los .so, activa useLegacyPackaging y agrega los permisos de internet y Bluetooth. El prebuild se detiene con "[clisitef] missing ..." si falta el JAR o libclisitef.so.

Regístralo una vez por pedido. Pasa siempre el almacenamiento del dispositivo (AsyncStorage). Sin él, una transacción que el débito dejó abierta no la ve el crédito y no se puede deshacer después de un reinicio.

import AsyncStorage from "@react-native-async-storage/async-storage";
import { clisitefPinPadPayments } from "@fire-spark/payments-clisitef-pinpad-rn";

const deviceStorage = {
  get: (key: string) => AsyncStorage.getItem(key),
  set: (key: string, value: string) => AsyncStorage.setItem(key, value),
  remove: (key: string) => AsyncStorage.removeItem(key)
};

order.setPaymentAdapters([
  clisitefPinPadPayments({ storage: deviceStorage })
]);

order.setPaymentOptions({
  isProduction: merchant.env_is_prod,
  collectAt: "KIOSK",
  deviceSettings: kioskConfig.overrides.payment_settings,
  deviceId: kioskConfig.device.id
});

kioskConfig es lo que devuelve getKioskConfig. Los valores del dispositivo llegan en overrides.payment_settings.

El adaptador no dibuja nada. Implementa setPaymentUI y muestra el texto de CliSiTef tal como llega, en portugués:
- message: muestra el último texto ("Insira o cartão", "Digite a senha", "Aguarde"). No devuelve nada.
- select: selector de modalidad, red del vale o un menú de SiTef. Resuelve con el value elegido. Rechaza si el cliente cancela. El título de las modalidades es "Selecione a forma de pagamento". Las opciones son Débito, Crédito, Voucher y Pix.
- input: resuelve con el texto. type "password" va enmascarado (clave de supervisor). type "number" es un monto.
- confirm: resuelve con true o false.
- action: QR de Pix. { type: "qr", payload, format: "text", expiresAt: null } muestra el QR. payload es el texto de copia y pega de Pix; dibújalo como QR, no como imagen. payload "" lo oculta. También ocúltalo cuando termina payIntent. expiresAt es null. El plazo del cobro es de 180 segundos. Sigue mostrando el texto de message debajo del QR. El control de cancelar rechaza la promesa del flujo.

Botón del checkout:
- Varias modalidades en un pago: el cliente elige una en ui.select antes de que arranque el pinpad. Si select se rechaza, el pinpad no arranca.
- Pix en su propio botón: un segundo pago con modalities: ["PIX"]. El template lo trata como Pix con isPixOnlyPayment y muestra la ilustración de Pix. Cualquier otro pago PIN_PAD muestra la ilustración de tarjeta.
- Pix es una transferencia (el cliente paga con un QR desde su banco), pero el QR y el resultado pasan por los binarios nativos de CliSiTef, el mismo módulo que el débito y el crédito. Es una modalidad PIX del proveedor "clisitef" y el método "PIN_PAD". No implementes Pix como BANK_TRANSFER ni como un paquete aparte.
- Débito y vale comparten una función de CliSiTef y se separan con restrictions_by_modality. No copies una lista de restricciones de crédito sobre el vale.

Cobra el pago que eligió el cliente:

await order.setTenders([{
  method: "PIN_PAD",
  provider: "clisitef",
  payment_id: payment.id,
  collect_at: "DEVICE",
  allocation: null
}]);
const result = await order.payIntent({ onProgress: progress => render(progress) });

El plazo del cobro es de 180 segundos (carga de tablas del pinpad, modalidad, tarjeta y PIN). Deja runtime.timeout_ms sin definir. Si lo defines, usa 180000 o más. Sube el valor por defecto del adaptador con clisitefPinPadPayments({ storage: deviceStorage, timeoutMs: 240_000 }).

Resultados:
- PAID: imprime metadata.receipt.customer (texto plano, vía del cliente) y sigue con el pedido.
- FAILED CANCELLED_BY_USER: vuelve a la lista de métodos y no muestres un error.
- AMBIGUOUS (metadata.needs_review): no reintentes. La tarjeta puede haberse leído o el QR puede haberse mostrado. Manda al cliente al mostrador.
- El NSU, el código de autorización, la marca, los últimos 4 y el cupón fiscal están en result.metadata.payment. Pix no tiene marca ni últimos 4 (entry_mode "QR"). No los guardes por tu cuenta.

Anulaciones: order.cancel() si el pedido no se entregó, order.refund() si se entregó. Mantén setPaymentUI montado. Funciones de CliSiTef: crédito 210, débito y vale 211, Pix 123. El adaptador envía monto, fecha, NSU del host y secret_supervisor_password (el valor del dispositivo gana sobre el de la tienda). Si no hay ninguna clave, la pide con ui.input type "password".
- REFUNDED o CANCELLED: imprime metadata.provider.void.receipt.customer si está.
- PAID con needs_review y un error reintentable: la anulación quedó en cola. Desde la pantalla de administración del kiosco corre order.runPaymentTerminal(payment, "retry_pending_reversals").
- PAID con REVERSAL_NOT_ALLOWED o MANUAL_REVERSAL_REQUIRED: una persona la anula en el menú administrativo de SiTef.

Errores a manejar: CANCELLED_BY_USER (-2, -6, -15), CARD_DECLINED (-40 y otros códigos positivos), TERMINAL_BUSY (-12; el siguiente cobro aborta y reintenta configure una vez), TERMINAL_NOT_CONFIGURED (faltan datos de tienda o dispositivo), WALLET_REJECTED (-24; Pix no está habilitado para la tienda), TIMEOUT (CLISITEF_TIMEOUT; se acabó el plazo de 180 segundos), AMBIGUOUS (no reintentes).

Los valores del dashboard los llena una persona; no los inventes. Proveedor CliSiTef, método PIN pad. Config del pago: modalities (DEBIT, CREDIT, VOUCHER, PIX; al menos una), cnpj_enterprise (14 dígitos), operator opcional (por defecto KIOSKO_BR), restrictions_by_modality opcional. Por tienda: sitef_ip, store_code (8 caracteres), cnpj_store. Por kiosco, settings_overrides.payment_settings[paymentId]: terminal_number (obligatorio), secret_supervisor_password opcional. pinpad_type es opcional y por defecto ANDROID_USB (también ANDROID_BT y ANDROID_AUTO). Un pago al que le falta un dato de tienda o dispositivo no aparece en el checkout. order.getMissingPaymentFields(payment) lista lo que sigue vacío.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.