# Referência de interfaces de serviço

Esta página cataloga todas as interfaces AIDL que sua Manufacturer Service App pode implementar. Também lista os valores fixos que a plataforma da Getnet espera de algumas delas. Para as chamadas que exercitam essas interfaces, consulte [Implementar os serviços de hardware](/pt/pos-manufacturers/how-to-guides-pos-mfg/implement-hardware-services).

## IMainService

O ponto de entrada. A Middleware App se vincula ao seu serviço pelo pacote `com.pagonxt.hal.platform.service` e obtém um stub `IMainService`. Por esse stub ela alcança todas as demais interfaces.

| Método de acesso | Devolve |
| :--- | :--- |
| `getStats()` | `IStatService` |
| `getPrinter()` | `IPrinterService` |
| `getCard()` | `ICardService` |
| `getMifare()` | `IMifareService` |
| `getBeeper()` | `IBeeperService` |
| `getLed()` | `ILedService` |
| `getInfo()` | `IInfoService` |
| `getCamera()` | `ICameraService` |
| `getEmv()` | `IEMVInterface` |

## ICardService

Cuida da busca de cartão em todas as tecnologias de leitura que seu dispositivo suporta.

| Método | Descrição |
| :--- | :--- |
| `search(long timeout, in String[] searchType, in ICardCallback callback)` | Busca um cartão usando um ou mais dos tipos de busca abaixo, até `timeout` se esgotar. |
| `stopAllReaders()` | Para todos os leitores ativos. Chame assim que `onCard`, `onMessage` ou `onError` disparar. |

Tipos de busca:

| Constante | Valor |
| :--- | :--- |
| `MAG` | `"1"` |
| `CHIP` | `"2"` |
| `NFC` | `"3"` |

`onCard` devolve um `CardResponse` com `pan` (chip e NFC) ou `track1` / `track2` / `track3` (tarja magnética).

## IMifareService

Cobre presença de cartão Mifare, autenticação e leitura/escrita em nível de bloco.

| Método | Descrição |
| :--- | :--- |
| `searchCard(in IMifareCallback callback)` | Busca um cartão Mifare. |
| `searchCardAndActivate(in IMifareActivateCallback callback)` | Busca e ativa um cartão Mifare em uma só chamada. |
| `activate(int cardType)` | Ativa um cartão do tipo indicado. |
| `halt()` | Para o cartão ativo. |
| `getCardSerialNo(int cardType)` | Devolve o número de série (UID) do cartão como string hexadecimal. |
| `authenticateSectorWithKeyA(int sector, in byte[] key)` | Autentica um setor com a Key A. |
| `authenticateBlockWithKeyA(int sector, in byte[] key)` | Autentica um bloco com a Key A. |
| `authenticateSectorWithKeyB(int block, in byte[] key)` | Autentica um setor com a Key B. |
| `authenticateBlockWithKeyB(int block, in byte[] key)` | Autentica um bloco com a Key B. |
| `close()` | Fecha a sessão Mifare atual. |
| `decrement(int index, int value)` | Decrementa em `value` o bloco de valor em `index`. |
| `increment(int index, int value)` | Incrementa em `value` o bloco de valor em `index`. |
| `isExist()` | Devolve se há um cartão Mifare presente. |
| `readBlock(int index)` | Lê o bloco em `index`, devolvido como string. |
| `restore(int index)` | Restaura o bloco de valor em `index`. |
| `transfer(int index)` | Transfere o bloco de valor em `index`. |
| `writeBlock(int index, String data)` | Escreve `data` no bloco em `index`. |
| `exchangeAPDU(in byte[] apdu)` | Envia um APDU bruto e devolve um `APDUResponse`. |

As chaves têm 6 bytes. A autenticação de bloco e de setor usa os nomes de parâmetro como declarados no AIDL acima. `authenticateBlockWithKeyA`/`B` recebem um parâmetro literalmente chamado `sector`, embora ele identifique um bloco.

## IPrinterService

Monta e imprime um recibo a partir de uma fila de elementos de texto, código de barras, código QR e imagem.

| Método | Descrição |
| :--- | :--- |
| `init()` | Inicializa a impressora. Todo outro método lança `IllegalStateException` se for chamado antes deste. |
| `getStatus()` | Devolve o status atual da impressora. |
| `setGray(int gray)` | Define o nível de escala de cinza aplicado às imagens. |
| `addText(int align, String text)` | Enfileira uma linha de texto com o alinhamento indicado. |
| `addBarCode(int align, String barcode)` | Enfileira um código de barras. |
| `addQrCode(int align, int imageHeight, String qrCode)` | Enfileira um código QR com a altura indicada. |
| `addImageBitmap(int align, in Bitmap bitmap)` | Enfileira uma imagem `Bitmap`. |
| `addImageByteArray(int align, in byte[] byteArray)` | Enfileira uma imagem a partir de bytes brutos. |
| `defineFontFormat(int fontFormat)` | Define a fonte ativa. |
| `print(in IPrinterCallback callback)` | Imprime tudo o que está enfileirado. |
| `printAndRemovePaper(in IPrinterCallback callback)` | Imprime tudo o que está enfileirado e depois avança e corta o papel. |

### Constantes de fonte

`defineFontFormat` recebe uma destas três constantes.

| Constante | Valor | Tamanho |
| :--- | :--- | :--- |
| `FONT_12_16A` | `11` | Pequeno |
| `FONT_16_32B` | `15` | Médio |
| `FONT_32_32B` | `22` | Grande |

### Especificações da impressora

Valores e comportamentos fixos que sua implementação de impressora deve seguir.

| Regra | Valor |
| :--- | :--- |
| Tamanho máximo de imagem | 378 pixels. Seu serviço redimensiona automaticamente imagens maiores. |
| Máximo de caracteres por linha — fontes média e grande | 32 caracteres. Média e grande só diferem na altura. |
| Máximo de caracteres por linha — fonte pequena | 48 caracteres. |
| Limiar de escala de cinza | 175. Seu serviço é responsável pela transformação em escala de cinza. |
| Chamadas repetidas a `init()` | Não devem limpar a fila de impressão. Limpe-a apenas quando o método `print()` do seu serviço rodar. |
| Métodos de imagem | Todos os métodos `addImage*` devem aceitar entrada `Bitmap`. |
| Texto longo | Chamadas a `addText` que ultrapassem o limite de caracteres devem quebrar automaticamente em várias linhas. |
| Nova linha após conteúdo enfileirado | Todo método que enfileira conteúdo (texto ou imagem) deve acrescentar automaticamente uma quebra de linha. |

## IBeeperService

Toca retorno sonoro para as ações do portador e do operador.

| Método | Descrição |
| :--- | :--- |
| `custom(int durationMillis)` | Toca um bipe pela duração indicada, em milissegundos. |

Sons nomeados e sua duração exigida:

| Som | Duração |
| :--- | :--- |
| `success` | Bipe de 500 ms. |
| `error` | Bipe de 1000 ms. |
| `digit` | Bipe de 100 ms. |
| `nfc` | Bipe de 100 ms, pausa de 300 ms, bipe de 100 ms. |

## ILedService

Um par liga/desliga por cor: `turnOnRed` / `turnOffRed`, `turnOnBlue` / `turnOffBlue`, `turnOnYellow` / `turnOffYellow`, `turnOnGreen` / `turnOffGreen`.

## IInfoService

Devolve os dados de identificação do dispositivo. Consulte [InfoResponse](#inforesponse) para a lista completa de campos.

## ICameraService

Lê a câmera frontal do dispositivo para casos de uso de escaneamento.

| Método | Descrição |
| :--- | :--- |
| `readFront(long timeout, in ICameraCallback callback)` | Lê a câmera frontal até `timeout` se esgotar, ou até quem chamou cancelar a leitura. |

O `ICameraCallback` reporta por `onSuccess(code)`, `onTimeout()`, `onCancel()` e `onError(error)`.

## IStatService

Reporta as contagens de uso de leituras de cartão e de consumo de papel, tanto no dispositivo inteiro quanto por aplicação chamadora.

| Método | Descrição |
| :--- | :--- |
| `getPaperStatus()` | Consumo total de papel, no dispositivo inteiro. |
| `getAllAppPaperStatus()` | Consumo de papel, por aplicação chamadora. |
| `getMagStatus()` | Total de leituras de tarja magnética bem-sucedidas. |
| `getAllAppMagStatus()` | Leituras de tarja magnética bem-sucedidas, por aplicação. |
| `getMagStatusFail()` | Total de falhas de tarja magnética. |
| `getAllAppMagStatusFail()` | Falhas de tarja magnética, por aplicação. |
| `getChipStatus()` | Total de inserções de chip bem-sucedidas. |
| `getAllAppChipStatus()` | Inserções de chip bem-sucedidas, por aplicação. |
| `getChipStatusFail()` | Total de falhas de inserção de chip. |
| `getAllAppChipStatusFail()` | Falhas de inserção de chip, por aplicação. |
| `getNfcStatus()` | Total de transações contactless (NFC) bem-sucedidas. |
| `getAllAppNfcStatus()` | Transações contactless bem-sucedidas, por aplicação. |
| `getNfcStatusFail()` | Total de falhas contactless. |
| `getAllAppNfcStatusFail()` | Falhas contactless, por aplicação. |
| `getMifareStatus()` | Total de leituras de proximidade Mifare bem-sucedidas. |
| `getMifareStatusFail()` | Total de falhas de proximidade Mifare. |
| `getAllStatisticsByApp()` | Todas as contagens de sucesso e falha acima, agrupadas por aplicação. |

Vários métodos HAL recebem um parâmetro `userId` que identifica a aplicação chamadora. Exemplos incluem `print(int userId, IPrinterCallback callback)` e `searchMag(int userId, long timeout, in ICardCallback callback)`. Resolva `userId` para um nome de pacote com `packageManager.getNameForUid(userId)` para atribuir as estatísticas corretamente.

## IEMVInterface

Usada por `IMainService::getEmv`. Consulte [Máquina de estados EMV](/pt/pos-manufacturers/core-concept-pos-mfg/emv-state-machine) para ver como esses métodos se encaixam em uma transação.

| Método | Descrição |
| :--- | :--- |
| `create(IEMVEventsAIDL events)` | Associa um listener de eventos ao serviço. Chame antes de qualquer transação. |
| `reset()` | Reinicia todos os parâmetros de longo prazo. |
| `version()` | Devolve uma `List<Version>` descrevendo o kernel EMV em execução. |
| `setAIDParameter(in List<AIDParameter> data)` | Define os parâmetros específicos de AID. De longo prazo, prioridade alta exceto para os parâmetros definidos por `setTLV`. |
| `setCAKey(in List<CAKey> data)` | Define a lista de chaves da autoridade certificadora. De longo prazo, prioridade baixa. |
| `setRevoked(in List<Revoked> data)` | Define a lista de números de série de certificado revogados. De longo prazo. |
| `setRiskManagement(in Risk risk)` | Define os parâmetros de gestão de risco da transação. De longo prazo. |
| `setTLV(in List<TLV> tlvs)` | Define uma lista de TLVs apenas para a transação atual. De curto prazo, prioridade máxima. |
| `setTerminal(in Terminal terminal)` | Define os dados do terminal. De longo prazo, sobrescreve parâmetros definidos anteriormente. |
| `start(in List<String> aidList, in Transaction transaction)` | Inicia a coleta de dados do cartão para uma transação. O kernel EMV ignora qualquer AID que não esteja presente em `setAIDParameter`. |
| `get(in List<String> list, IGetCallback get)` | Recupera os TLVs solicitados de forma assíncrona. |
| `getSimplified(in List<String> data)` | Recupera os TLVs solicitados de forma síncrona, devolvidos como `List<TLV>`. |
| `cancel()` | Cancela o fluxo EMV atual. A aplicação ainda precisa aguardar o evento de fim antes de dar a transação por cancelada. |

## IMaintenanceInterface

Cobre a manutenção do dispositivo: autoverificações, atualizações remotas e ajustes de relógio.

| Método | Descrição |
| :--- | :--- |
| `setSelfTestHourRange(String min, String max)` | Define a janela de reinício por autoverificação (auto-reset), como strings `"HH:mm"`. Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `setAutoUpdateHourRange(String min, String max)` | Define a janela de tentativa de atualização automática, como strings `"HH:mm"`. Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `setAutoUpdate(boolean isEnabled, boolean autoRebootEnabled)` | Ativa ou desativa a atualização automática. Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `setAllowGprsUpdate(boolean isEnabled)` | Permite ou bloqueia a atualização remota por 3G/4G. Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `installApp(String filePath, IMaintenanceResult result)` | Instala o APK em `filePath` em segundo plano (sem interação do usuário). Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `uninstallApp(String packageName, IMaintenanceResult result)` | Desinstala `packageName` em segundo plano (sem interação do usuário). Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `setTimeZone(String id)` | Define o fuso horário do dispositivo. Devolve `0` em caso de sucesso, `-1` em caso de erro. |
| `setDateTime(String dateTime)` | Define a data e hora local do dispositivo, como `"YYYYMMDDHHmmss"` (por exemplo, `"20250314093500"`). Devolve `0` em caso de sucesso, `-1` em caso de erro. |

## IEncryptionInterface

Cobre o status das chaves e a criptografia de dados para a gestão de chaves do dispositivo.

| Método | Descrição |
| :--- | :--- |
| `getKSNbyPosition(int index)` | Devolve o KSN codificado em hexadecimal da chave em `index`, ou uma string vazia se não existir. |
| `injectWorkingKey(int index, int mkIndex, in byte[] keyBlock)` | Injeta uma chave de trabalho em `index`, criptografada pela chave mestra em `mkIndex`. |
| `encryptData(int index, int method, in byte[] plainText)` | Criptografa `plainText` com a chave em `index`. `method` é `1` para modo CBC ou `2` para modo EBC, conforme documenta o kit do fabricante. Devolve os dados criptografados, ou `null` em caso de erro. |

## InfoResponse

Campos devolvidos por `IInfoService` e pelas chamadas de informação de dispositivo relacionadas:

| Campo | Descrição |
| :--- | :--- |
| `sdkVersion` | Versão do SDK instalado. |
| `bcVersion` | Versão do componente de boot/base. |
| `osVersion` | Versão do sistema operacional. |
| `serialNumber` | Número de série do dispositivo. |
| `psamId` | Identificador PSAM. |
| `model` | Modelo do dispositivo. |
| `manufacture` | Fabricante do dispositivo. |
| `imsi` | IMSI do SIM, se presente. |
| `imei` | IMEI do dispositivo. |
| `iccid` | ICCID do SIM, se presente. |
| `romVersion` | Versão da ROM. |
| `androidKernelVersion` | Versão do kernel Android. |
| `androidOSVersion` | Versão do sistema operacional Android. |
| `hardwareVersion` | Revisão de hardware. |
| `firmwareVersion` | Versão do firmware. |
| `hardWareSn` | Número de série de hardware. |

## Recursos relacionados

* [Arquitetura HAL](/pt/pos-manufacturers/core-concept-pos-mfg/hal-architecture) — como essas interfaces se encaixam.
* [Implementar os serviços de hardware](/pt/pos-manufacturers/how-to-guides-pos-mfg/implement-hardware-services) — as chamadas que exercitam a maioria das interfaces acima.
* [Máquina de estados EMV](/pt/pos-manufacturers/core-concept-pos-mfg/emv-state-machine) — o fluxo construído sobre `IEMVInterface`.