# Comandos da API

Esta referência define a estrutura de baixo nível dos pacotes de comunicação e as sequências operacionais necessárias para interagir com o Pinpad Getnet.

## Enquadramento de mensagens e protocolo

Cada mensagem transmitida pela interface serial segue um protocolo de enquadramento rigoroso, com caracteres de controle ASCII para garantir a integridade dos dados.

### Estrutura geral do quadro

Todos os pacotes devem seguir o seguinte formato:
`<STX> [PAYLOAD] <ETX> {LRC}`

| Componente     | Valor Hex | Descrição                                                      |
| -------------- | --------- | -------------------------------------------------------------- |
| **`<STX>`**    | `02h`     | **Start of Text**: indica o início de um quadro de mensagem.   |
| **\[PAYLOAD]** | Variável  | O comando em si e seus parâmetros.                             |
| **`<ETX>`**    | `03h`     | **End of Text**: indica o fim do payload da mensagem.          |
| **\{LRC\}**      | Variável  | **Caractere de verificação**: byte de Longitudinal Redundancy Check. |

### Delimitadores internos do payload

Dentro da seção `[PAYLOAD]`, vários parâmetros são separados pelo caractere **Separador de Arquivos (`<FS>`)** (`1Ch`).

## Matriz operacional de comandos

Esta matriz mapeia operações lógicas específicas para a sequência de comandos necessária entre o Sistema Host e o Pinpad.

| Operação             | Configuração   | Ação         | Captura de dados | Finalização   |
| -------------------- | -------------- | ------------ | --------------- | ------------- |
| **Pagamento padrão** | `Y19`          | `Y15`        | `Y02` (Auto PP) | `Y03`         |
| **Cashback**         | `Y19` (TTY 09) | `Y15`        | `Y02` (Auto PP) | `Y03`         |
| **Estorno**          | `Y19` (TTY 20) | —            | `Y02` (Auto PP) | `Y03`         |
| **Pagamento QR**     | —              | `Y0Q`        | —               | `Y0Q` (Limpar) |
| **Echo Test**        | —              | `Y0I`        | —               | —             |
| **Atualização (YDL)** | `YDL` (Init)  | `YDL` (Data) | —               | `YDL` (End)   |

## Definições principais de payload

Cada campo abaixo é separado por `<FS>` (`1Ch`) e enquadrado por `<STX>`/`<ETX>`/`{LRC}`, como descrito acima. A coluna **Atributo** usa: `H` (hexadecimal), `N` (numérico), `A` (alfabético), `AN` (alfanumérico), `ANS` (alfanumérico e caracteres especiais).

### Y19 - Inicializar transação

Obrigatório para iniciar operações com cartão. O Host envia a chave RSA, o valor e os parâmetros de criptografia; o Pinpad retorna os dados do cartão (fluxo contactless).

**Requisição Y19 (Host → Pinpad)**

| Campo | Tamanho | Atributo | Descrição |
| --- | --- | --- | --- |
| `RSA` | 256–512 | ANS | Chave pública RSA (módulo) usada para criptografar a Trilha 1. Veja [Criptografia do Pinpad](https://docs.globalgetnet.com/pt/products/in-store-payments/host-to-host?doc=h2h-pinpad-encryption). |
| `EXP` | 1–12 | ANS | Expoente RSA. |
| `TEC` | 3 | N | Tempo limite entre comandos, em segundos (`000`–`999`). |
| `ET1` | 1 | N | Envia a Trilha 1 (banda). Sem uso: o valor é ignorado pelo Pinpad. |
| `PTC` | 1 | N | Solicita o tipo de conta (comum em cartões MAESTRO). |
| `PMK` | 1 | AN | Posição da chave mestra (`0`–`9` ou `N`). PMK do PIN = valor; PMK do PAN = valor + 1. |
| `WRK` | 1–16 | ANS | Chave de trabalho. |
| `ENC` | 1 | N | Criptografia DUKPT do PAN: `0` desativada, `1` ativada, `2` ativada usando o slot 3. |
| `IMP` | 12 | N | Valor da compra; os dois últimos dígitos são decimais. |
| `ICB` | 12 | N | Valor do cashback (`000000000000` se não usado); os dois últimos dígitos são decimais. |
| `TTY` | 2 | N | Tipo de transação. Veja [Tabelas de Códigos](/pt/host-to-host/reference-h2h/code-tables). |

**Resposta Y19 (Pinpad → Host) — Contactless**

| Campo | Tamanho | Atributo | Descrição |
| --- | --- | --- | --- |
| `TJA` | 1–19 | N | Número do cartão (8 primeiros e 4 últimos dígitos; o restante mascarado com `*`). Vem da Trilha II. |
| `CSE` | 3 | N | Código de serviço (da Trilha II); enviado em texto claro. |
| `CBC` | 3 | N | Código do banco. Sem uso: sempre `000`. |
| `NYA` | 1–26 | ANS | Nome do portador do cartão para o comprovante (Trilha I ou TAG 5F20); preenchido à direita com espaços. |
| `REG` | 6 | N | Número do registro. Sem uso: `000041`. |
| `MDI` | 1 | A | Modo de entrada (`M`, `B`, `C`, `L`, `E`). Veja [Tabelas de Códigos](/pt/host-to-host/reference-h2h/code-tables). |
| `VER` | 1–15 | ANS | Versão do software do Pinpad. |
| `FDV` | 4 | N | Data de validade (`YYMM`), da Trilha II. |
| `TC2` | 256–512 | ANS | Trilha II criptografada com a chave RSA do Y19. Vem da Trilha II ou da TAG 57. |
| `1NL` | 1 | N | Indicador de Trilha I não lida: `0` lida, `1` não lida. |
| `NSF` | 1–12 | N | Número de série físico do Pinpad. |
| `CPG` | 1–300 | ANS | Criptograma EMV (TLV). `N` se não se aplicar. |
| `CAU` | 6 | N | Código de autorização. Retornado como 6 espaços em branco. |
| `CRE` | 2 | N | Código de resposta do emissor (TAG 8A e resultado do SDK). |
| `NSP` | 3 | N | Número de sequência do PAN (TAG 5F34). |
| `APN` | 0–32 | ANS | Nome da aplicação EMV selecionada, em hexadecimal, para o comprovante (TAG 9F12 / TAG 50). |
| `AID` | 0–16 | ANS | Identificador da aplicação EMV selecionada (TAG 4F). |
| `KSN-PAN` | 20 | H | Key Serial Number do PAN criptografado com DUKPT. |
| `ENC-PAN` | 1–256 | ANS | Criptograma do PAN criptografado com DUKPT. |
| `TDC` | 1 | AN | Tipo de conta (MAESTRO). `N` para não imprimir. |
| `PIN` | 16–32 | ANS | PINBLOCK, se um PIN foi digitado; caso contrário, omitido. |
| `KSN` | 20 | N | Key Serial Number do PIN DUKPT; incrementa a cada operação EMV com PIN. Omitido se não houver PIN. |

### Y02 - Resposta de dados adicionais

Gerado pelo Pinpad após a leitura de um cartão. A requisição pode atualizar valores e solicitar dados de banda; a estrutura da resposta depende do modo de entrada (BANDA ou CHIP).

**Requisição Y02 (Host → Pinpad)**

| Campo | Tamanho | Atributo | Descrição |
| --- | --- | --- | --- |
| `U4D` | 1 | N | Solicita os 4 últimos dígitos (somente banda). |
| `CDS` | 1 | N | Solicita o código de segurança (somente banda). |
| `ET1` | 1 | N | Envia a Trilha 1 (banda). Sem uso: o valor é ignorado. |
| `SPI` | 1 | N | Solicita o PIN (somente banda). |
| `PTC` | 1 | N | Solicita o tipo de conta (comum em MAESTRO). |
| `PMK` | 1 | AN | Posição da chave mestra (`0`–`9` ou `N`). PMK do PIN = valor; PMK do PAN = valor + 1. |
| `WRK` | 1–16 | ANS | Chave de trabalho (`N` se não estiver solicitando PIN nem criptografia de trilhas). Sem uso: o valor é ignorado. |
| `ENC` | 1 | N | Criptografia DUKPT do PAN: `0` desativada, `1` ativada, `2` ativada usando o slot 3. |
| `IMP` | 12 | N | Valor da compra; atualiza o valor de `Y19.IMP`. |
| `ICB` | 12 | N | Valor do cashback; atualiza o valor de `Y19.ICB`. |

**Resposta Y02 (Pinpad → Host) — Banda magnética (BANDA)**

| Campo | Tamanho | Atributo | Descrição |
| --- | --- | --- | --- |
| `TJA` | 1–19 | N | Número do cartão (8 primeiros e 4 últimos; o restante mascarado com `*`). Vem da Trilha II. |
| `FDV` | 4 | N | Data de validade (`YYMM`), da Trilha II. |
| `TC1` | 256–512 | ANS | Trilha I criptografada com a chave RSA do Y19 (banda). |
| `TC2` | 256–512 | ANS | Trilha II criptografada com a chave RSA do Y19 (banda). |
| `1NL` | 1 | N | Indicador de Trilha I não lida: `0` lida, `1` não lida. |
| `CDS` | 1–4 | N | Código de segurança criptografado com a chave RSA do Y19 (digitado pelo usuário). |
| `NSF` | 1–12 | N | Número de série físico do Pinpad. |
| `KSN-PAN` | 20 | H | Key Serial Number do PAN criptografado com DUKPT. |
| `ENC-PAN` | 1–256 | ANS | Criptograma do PAN criptografado com DUKPT. |
| `TDC` | 1 | AN | Tipo de conta (MAESTRO). `N` para não imprimir. |
| `PIN` | 16–32 | ANS | PINBLOCK, se um PIN foi digitado; caso contrário, omitido. |
| `KSN` | 20 | N | Key Serial Number do PIN DUKPT; incrementa a cada operação com PIN. |

**Resposta Y02 (Pinpad → Host) — Chip (CHIP)**

| Campo | Tamanho | Atributo | Descrição |
| --- | --- | --- | --- |
| `TJA` | 1–19 | N | Número do cartão (8 primeiros e 4 últimos; o restante mascarado com `*`). Vem da Trilha II. |
| `FDV` | 4 | N | Data de validade (`YYMM`), da Trilha II. |
| `TC2` | 256–512 | ANS | Trilha II criptografada com a chave RSA do Y19. Vem da TAG 57 (chip). |
| `1NL` | 1 | N | Indicador de Trilha I não lida: `0` lida, `1` não lida. |
| `NSF` | 1–12 | N | Número de série físico do Pinpad. |
| `CPG` | 1–300 | ANS | Criptograma EMV (formato TLV). `N` se nenhuma informação for enviada. |
| `CAU` | 6 | N | Código de autorização. Retornado como 6 espaços em branco. |
| `CRE` | 2 | N | Código de resposta do emissor. |
| `NSP` | 3 | N | Número de sequência do PAN (TAG 5F34). |
| `APN` | 0–32 | ANS | Nome da aplicação EMV selecionada, em hexadecimal, para o comprovante (TAG 9F12 / TAG 50). |
| `AID` | 0–16 | ANS | Identificador da aplicação EMV selecionada (TAG 4F). |
| `KSN-PAN` | 20 | H | Key Serial Number do PAN criptografado com DUKPT. |
| `ENC-PAN` | 1–256 | ANS | Criptograma do PAN criptografado com DUKPT. |
| `TDC` | 1 | AN | Tipo de conta (MAESTRO). `N` para não imprimir. |
| `PVF` | 1 | N | Indicador de PIN offline verificado pelo cartão. Deve ser `0` para PIN online. |
| `PIN` | 16–32 | ANS | PINBLOCK, se um PIN foi digitado; caso contrário, omitido. |
| `KSN` | 20 | N | Key Serial Number do PIN DUKPT; incrementa a cada operação EMV com PIN. |

### Y03 - Autorização do Host

A instrução final enviada pelo Host para concluir o fluxo.

**Campos principais \[Host]**:

* **\[CAU]**: Código de autorização do emissor.
* **\[CRE]**: Código de resposta (por exemplo, "00" para sucesso).

## Tratamento de erros (Y0E)

Se uma operação falhar, o terminal retorna um relatório `Y0E` em vez da resposta esperada da sequência.

| Código | Mensagem       | Descrição                                   |
| ------ | -------------- | ------------------------------------------- |
| **01** | **CANCELADO**  | Cancelamento iniciado pelo usuário ou pelo Host. |
| **04** | **ERROR EMV**  | Falha na leitura do chip ou de protocolo.   |
| **08** | **SIN LLAVES** | Chaves DUKPT ausentes no Slot 3.            |