# Conectando via USB (CreateUsb)

Este guia explica como estabelecer uma conexão com um POS Integrado usando o transporte USB (serial).

## O que é a conexão USB

O modelo de conexão USB estabelece um link físico direto entre o sistema de automação e o terminal POS por meio de uma interface serial. Você chama `CreateUsb` com os parâmetros necessários para a sua plataforma; a função retorna uma instância de Connector que expõe as mesmas funções de operação no dispositivo que os conectores HTTP.

## Quando usar a conexão USB

Use uma conexão USB quando:

* O terminal POS estiver fisicamente próximo do sistema de automação
* A conectividade de rede estiver indisponível ou restrita
* For necessária uma conexão direta, ponto a ponto

O USB oferece um canal simples e determinístico, mas é sensível à desconexão física — se o cabo for retirado, o canal é perdido e precisa ser restabelecido.

<Callout type="warning">

Se você usar `setupParams` (Kotlin) ou o comando Setup (.NET) com o terminal, verifique as seções de comportamento de reconexão nesta documentação.

</Callout>

## Antes de começar

Antes de conectar via USB, confirme que:

* O terminal POS está ligado e configurado para o modo POS Integrado
* O cabo USB está corretamente conectado entre o POS e o sistema de automação
* A biblioteca do POS Integrado está disponível na sua aplicação
* O sistema operacional reconhece o POS como um dispositivo serial (por exemplo, porta COM no Windows, `/dev/ttyACM0` no Linux)

## Passo 1: Criar o USB Connector

Crie um Connector usando `CreateUsb` com o parâmetro necessário para a sua plataforma.

**Parâmetros:**

| Parâmetro | Tipo | Obrigatório | Descrição | Disponibilidade |
| :--- | :--- | :--- | :--- | :--- |
| `address` | string | Sim | O endereço da porta serial local (por exemplo, Windows: `COM1`, `COM3`; Linux: `/dev/ttyACM0`). | .NET |
| `usbDevice` | UsbDevice | Sim | Objeto de dispositivo Android para a conexão USB. | Kotlin |
| `setupParams` | HashMap&lt;String, String> | Não | Configuração do terminal (por exemplo, friendly name). Consulte a seção do fluxo de reconexão para mais detalhes. | Kotlin |

**Exemplo — C#:**

```csharp
Connector connector = Connector.CreateUsb("COM3");
```

**Exemplo — Kotlin:**

```kotlin
fun setupConnectorInstance(context: Context): POSIntegrado? {
    val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
    
    // Retrieve available device for USB connection
    val deviceList: List<UsbDevice> = usbManager.deviceList.map { it.value }
    
    // Select a available device
    val selectedDevice = deviceList.firstOrNull()
    
    val connectorInstance = if (selectedDevice != null) {
        POSIntegrado.createUsb(
            context = context,
            usbDevice = selectedDevice,
            setupParams = hashMapOf(
                SetupParameters.SELLER_FRIENDLY_NAME to "My Store"
            )
        )
    } else {
        null
    }
    
    return connectorInstance
}
```

Quando a chamada é bem-sucedida, uma instância de Connector é retornada. A conexão é inicializada, mas o terminal ainda não foi validado.

## Passo 2: Validar o terminal

Antes de executar qualquer operação no dispositivo, valide o terminal usando `Polling`:

```csharp
var pollingResult = connector.PollingAsync();
```

Prossiga apenas se a resposta do Polling indicar que o terminal está pronto.

## Passo 3: Executar operações

Uma vez validado, use o Connector para executar operações no dispositivo como `Sale`, `Refund` ou `GetReports`. Somente uma operação pode ser processada por vez em cada Connector.

## Passo 4: Fechar a conexão

Após concluir todas as operações, libere a conexão:

```csharp
connector.Close();
```

A instância do Connector se torna inválida após o fechamento e não pode ser reutilizada.

## Próximos passos

* [Modelos de Conexão](/pt/integrated-pos/first-steps-pos/connection-models) — Comparação entre USB e rede.
* [Connector e Fluxos de Comunicação](/pt/integrated-pos/core-concepts-pos/connector-communication-flows) — Ciclo de vida e regra de execução sequencial.
* [Reconexão, Polling e Resiliência](/pt/integrated-pos/core-concepts-pos/polling-reconnection) — Quando fazer polling e como funciona a reconexão.
* [Referência de Métodos e Parâmetros](/pt/integrated-pos/reference/methods-parameters) — Lista detalhada de parâmetros e exemplos de código para .NET e Kotlin.