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

# Instalação no Android

> Rode o Agente Fire no mesmo tablet Android do KDS para as comandas chegarem a uma impressora térmica da LAN.

O Chrome em HTTPS não consegue enviar bytes ESC/POS para uma impressora sozinho. Se o tablet não tem uma ponte local, o cozinheiro envia o ticket e **nada imprime** — o cliente espera no balcão sem comprovante.

Esta página é para quem configura o **Fire Agent Android** (`Agent 1.0.1`, pacote `com.firepos.fireagent`) no tablet do KDS. PCs Windows continuam usando a [Instalação no Windows](/pt/manuals/fire-agent/installation).

<Note>
  **O mínimo que você precisa saber**

  * Há duas cadeias independentes: **KDS ↔ agente** (DNS + WSS + token) e **agente ↔ impressora** (TCP na LAN, quase sempre porta 9100).
  * O **nome** que você salva no app é o que escolhe no fire-kds. Precisam ser iguais.
  * Em cozinhas HTTPS, `kds-agent.fire.rest` deve resolver para **`127.0.0.1` neste tablet**. Se o DNS mandar para a internet, a impressão não começa.
</Note>

## O caminho simples

<Steps>
  <Step title="Instale o APK">
    Instale **`Agente-1.0.1.apk`** no tablet. Abra o app e defina **Language** no idioma que usar (os rótulos desta página seguem a UI em inglês).
  </Step>

  <Step title="Inicie o agente">
    Em **Home**, toque em **Start agent**. O selo deve ler **LIVE**. Aceite notificações se o Android pedir (precisa para o serviço em primeiro plano).
  </Step>

  <Step title="Adicione a impressora">
    Abra **Printers**. Informe **Name in KDS**, **IP address** e **TCP port** (quase sempre `9100`). Toque em **Save printer** e depois **Test print**.
  </Step>

  <Step title="Arme o mesmo nome no KDS">
    No fire-kds, abra **Printer for this screen** e escolha esse nome exato. Ative **Print on bump** na loja para um envio tirar papel. Veja [Periféricos, impressão e validação](/pt/manuals/kds/peripherals-printing).
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/firepos/JUO9jSaQ-nNdc1h3/images/manuals/fire-agent/android/01-home-off.png?fit=max&auto=format&n=JUO9jSaQ-nNdc1h3&q=85&s=3b6034748abe50b63bdacc31b5d8e683" alt="Aba Home do Agente Fire Android com o agente parado e Start agent" width="1280" height="800" data-path="images/manuals/fire-agent/android/01-home-off.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/firepos/JUO9jSaQ-nNdc1h3/images/manuals/fire-agent/android/02-home-live.png?fit=max&auto=format&n=JUO9jSaQ-nNdc1h3&q=85&s=411f1bcd562fbb53c2b0c53f1e614384" alt="Aba Home do Agente Fire Android em LIVE com a linha de status ws e wss" width="1280" height="800" data-path="images/manuals/fire-agent/android/02-home-live.png" />
</Frame>

<Tip>
  Se o **Test print** já sai na impressora da cozinha e o KDS mostra o agente online, você pode parar aqui.
</Tip>

## Home, Diagnostics, Printers, Settings

| Aba             | O que você faz                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Home**        | **Start agent** / **Pause agent**. O status mostra `ws://127.0.0.1:9100` e `wss://kds-agent.fire.rest:9101`.      |
| **Diagnostics** | **Help center**. Verifique **KDS** (agente, DNS, WSS, token) e **Printers** (TCP para cada IP salva) em separado. |
| **Printers**    | Adicionar, **Test print**, excluir e, se quiser, **Find printers on network**.                                    |
| **Settings**    | Idioma (ES / EN / PT). **Auth token** e **WebSocket port** são só para suporte.                                   |

<Frame>
  <img src="https://mintcdn.com/firepos/JUO9jSaQ-nNdc1h3/images/manuals/fire-agent/android/03-diagnostics-ok.png?fit=max&auto=format&n=JUO9jSaQ-nNdc1h3&q=85&s=2b5c9e920effa57f9b25bbf4982e3e5d" alt="Diagnostics do Agente Fire Android com KDS e impressoras ok" width="1280" height="800" data-path="images/manuals/fire-agent/android/03-diagnostics-ok.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/firepos/JUO9jSaQ-nNdc1h3/images/manuals/fire-agent/android/04-printers-list.png?fit=max&auto=format&n=JUO9jSaQ-nNdc1h3&q=85&s=1e7e4dab4ee478bad44b1cfdee685de6" alt="Aba Printers do Agente Fire Android com uma impressora LAN e Test print" width="1280" height="800" data-path="images/manuals/fire-agent/android/04-printers-list.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/firepos/JUO9jSaQ-nNdc1h3/images/manuals/fire-agent/android/05-settings-connection.png?fit=max&auto=format&n=JUO9jSaQ-nNdc1h3&q=85&s=518c19e0b54127e69f9756d18477c21f" alt="Settings do Agente Fire Android com Auth token e WebSocket port" width="1280" height="800" data-path="images/manuals/fire-agent/android/05-settings-connection.png" />
</Frame>

O agente escuta só em **`127.0.0.1`**. O fire-kds no Android tenta primeiro `wss://kds-agent.fire.rest:9101` e, se falhar, cai na URL do Windows. Veja [Ferramentas web do agente](/pt/manuals/fire-agent/web-tools).

## Receitas

<AccordionGroup>
  <Accordion title="Um tablet, uma impressora de cozinha">
    1. Inicie o agente até **LIVE**.
    2. Salve uma impressora chamada `Kitchen` no IP da LAN, porta `9100`.
    3. **Test print**.
    4. No fire-kds escolha `Kitchen` e ative **Print on bump**.
  </Accordion>

  <Accordion title="Diagnostics marca KDS em vermelho e impressoras em verde">
    1. Fique em **Diagnostics → KDS**.
    2. Se **DNS** falhar, a TI precisa apontar `kds-agent.fire.rest` para `127.0.0.1` neste tablet.
    3. Se o token falhar, iguale **Auth token** a `NEXT_PUBLIC_FIRE_AGENT_TOKEN` no fire-kds.
    4. Não mexa na impressora — a parte 2 já está saudável.
  </Accordion>

  <Accordion title="Diagnostics marca KDS em verde e impressoras em vermelho">
    1. Confirme que a impressora está na **mesma Wi‑Fi / VLAN**.
    2. Revise IP e porta `9100` (alguns equipamentos usam 9102).
    3. Rode **Test print** em **Printers**.
    4. O KDS pode conectar e ainda assim não imprimir se o TCP até a impressora falhar.
  </Accordion>

  <Accordion title="Rotacionar o token sem um APK novo">
    1. Abra **Settings → Advanced: KDS connection**.
    2. Cole o **Auth token** novo.
    3. **Save settings** (o agente reinicia se estava **LIVE**).
    4. Atualize o mesmo token no deploy do fire-kds desse tablet.
  </Accordion>
</AccordionGroup>

## Exemplo com números

| Checagem           | Saudável                            | Quebrado                                                           |
| ------------------ | ----------------------------------- | ------------------------------------------------------------------ |
| Selo Home          | **LIVE**                            | **OFF** — o envio nunca chega ao agente                            |
| Nome da impressora | `Kitchen` no app e no KDS           | `kitchen` versus `Kitchen` — o KDS reporta impressora desconhecida |
| DNS                | `kds-agent.fire.rest` → `127.0.0.1` | IP público — o KDS em HTTPS não abre WSS                           |
| Test print         | Sai papel                           | Parte 2 vermelha — VLAN / IP / porta                               |

## Erros que saem caro

<Warning>
  **DNS público para `kds-agent.fire.rest`.** O navegador precisa falar com o agente neste tablet. Se o nome sair do aparelho, os tickets fiscal e comanda não imprimem e o envio ainda parece ok.
</Warning>

<Warning>
  **Token diferente.** **Auth token** deve ser igual a `NEXT_PUBLIC_FIRE_AGENT_TOKEN` do fire-kds. Senão o KDS mostra o agente offline ou `Unauthorized`.
</Warning>

<Warning>
  **Nome no agente ≠ nome no KDS.** A regra da loja pode estar certa e mesmo assim não imprimir. Use a mesma string, com espaços e acentos.
</Warning>

<Warning>
  **Impressora em outra rede.** O agente envia **TCP RAW** para o IP que você digitou. Wi‑Fi de convidados ou VLAN bloqueada parece impressora morta.
</Warning>

## Glossário

| Termo           | Significado                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| **LIVE**        | O serviço em primeiro plano está no ar. O KDS pode abrir o WebSocket local. |
| **WSS 9101**    | Socket TLS para o fire-kds em HTTPS (`wss://kds-agent.fire.rest:9101`).     |
| **WS 9100**     | Socket simples para HTTP / desenvolvimento local.                           |
| **Name in KDS** | Rótulo que você escolhe em **Printer for this screen**.                     |
| **TCP 9100**    | Porta RAW/ESC-POS da impressora térmica (não a do agente).                  |

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Instalo isto no Windows também?">
    Não. O Windows usa o [instalador do Windows](/pt/manuals/fire-agent/installation). Este APK é só para o dispositivo Android do KDS.
  </Accordion>

  <Accordion title="Tem código de emparelhamento?">
    Não. Você instala o app, inicia e cadastra impressoras. Códigos de emparelhamento são para [dispositivos de cozinha no fire-kds](/pt/manuals/kds/device-pairing), não para este agente.
  </Accordion>

  <Accordion title="Por que duas portas?">
    **9100** é WS simples. **9101** é WSS com o certificado incluso para o KDS em HTTPS conectar. A porta da impressora costuma ser 9100 também — é outro salto.
  </Accordion>

  <Accordion title="Inicia depois de reiniciar?">
    Sim por padrão, depois de abrir o app pelo menos uma vez após instalar (Android 12+). Se **Home** mostrar **OFF**, toque em **Start agent**.
  </Accordion>
</AccordionGroup>

## O que esta página não faz

* Não escolhe **Comanda** versus **Fiscal** — isso é **Print on bump** da loja.
* Não substitui as credenciais Fire para os *dados* fiscais. O agente só leva bytes ao papel.
* Não expõe uma API pública de impressão. O tráfego fica em `127.0.0.1`.