# Comandos de la API

Esta referencia define la estructura de bajo nivel de los paquetes de comunicación y las secuencias operativas necesarias para interactuar con el Pinpad de Getnet.

## Estructura de los mensajes y protocolo

Cada mensaje transmitido por la interfaz serie sigue un protocolo de estructura estricto, con caracteres de control ASCII. Así se garantiza la integridad de los datos.

### Estructura general de la trama

Todos los paquetes deben seguir el siguiente formato:
`<STX> [PAYLOAD] <ETX> {LRC}`

| Componente     | Valor hex | Descripción                                                       |
| -------------- | --------- | ----------------------------------------------------------------- |
| **`<STX>`**    | `02h`     | **Inicio de texto**: indica el comienzo de una trama de mensaje.  |
| **\[PAYLOAD]** | Variable  | El comando propiamente dicho y sus parámetros.                    |
| **`<ETX>`**    | `03h`     | **Fin de texto**: indica el final del payload del mensaje.        |
| **\{LRC\}**      | Variable  | **Carácter de verificación**: byte de Longitudinal Redundancy Check. |

### Delimitadores internos del payload

Dentro de la sección `[PAYLOAD]`, los parámetros se separan con el carácter **Separador de Archivos (`<FS>`)** (`1Ch`).

## Matriz operativa de comandos

Esta matriz relaciona cada operación lógica con la secuencia de comandos requerida entre el Sistema Host y el Pinpad.

| Operación                 | Configuración  | Acción       | Captura de datos | Finalización    |
| ------------------------- | -------------- | ------------ | ---------------- | --------------- |
| **Pago estándar**         | `Y19`          | `Y15`        | `Y02` (Auto PP)  | `Y03`           |
| **Cashback**              | `Y19` (TTY 09) | `Y15`        | `Y02` (Auto PP)  | `Y03`           |
| **Devolución**            | `Y19` (TTY 20) | —            | `Y02` (Auto PP)  | `Y03`           |
| **Pago con QR**           | —              | `Y0Q`        | —                | `Y0Q` (Limpiar) |
| **Prueba de eco**         | —              | `Y0I`        | —                | —               |
| **Actualización (YDL)**   | `YDL` (Init)   | `YDL` (Data) | —                | `YDL` (End)     |

## Definiciones principales del payload

Cada campo que aparece a continuación se separa con `<FS>` (`1Ch`) y se enmarca con `<STX>`/`<ETX>`/`{LRC}`, como se describió antes. La columna **Attr** usa: `H` (hexadecimal), `N` (numérico), `A` (alfabético), `AN` (alfanumérico), `ANS` (alfanumérico y caracteres especiales).

### Y19 - Inicializar transacción

Es obligatorio para iniciar las operaciones con tarjeta. El Host envía la clave RSA, el importe y los parámetros de cifrado; el Pinpad devuelve los datos de la tarjeta (flujo contactless).

**Solicitud Y19 (Host → Pinpad)**

| Campo | Longitud | Attr | Descripción |
| --- | --- | --- | --- |
| `RSA` | 256–512 | ANS | Clave pública RSA (módulo) usada para cifrar la Pista I. Consulte [Cifrado del Pinpad](https://docs.globalgetnet.com/es/products/in-store-payments/host-to-host?doc=h2h-pinpad-encryption). |
| `EXP` | 1–12 | ANS | Exponente RSA. |
| `TEC` | 3 | N | Tiempo de espera entre comandos, en segundos (`000`–`999`). |
| `ET1` | 1 | N | Enviar la Pista I (banda). Sin uso: el Pinpad ignora el valor. |
| `PTC` | 1 | N | Solicitar el tipo de cuenta (se usa habitualmente con tarjetas MAESTRO). |
| `PMK` | 1 | AN | Posición de la clave maestra (`0`–`9`, o `N`). PMK del PIN = valor; PMK del PAN = valor + 1. |
| `WRK` | 1–16 | ANS | Clave de trabajo. |
| `ENC` | 1 | N | Cifrado DUKPT del PAN: `0` desactivado, `1` activado, `2` activado usando la ranura 3. |
| `IMP` | 12 | N | Importe de la compra; los dos últimos dígitos son decimales. |
| `ICB` | 12 | N | Importe del cashback (`000000000000` si no se usa); los dos últimos dígitos son decimales. |
| `TTY` | 2 | N | Tipo de transacción. Consulte [Tablas de Códigos](/es/host-to-host/reference-h2h/code-tables). |

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

| Campo | Longitud | Attr | Descripción |
| --- | --- | --- | --- |
| `TJA` | 1–19 | N | Número de tarjeta (los primeros 8 y los últimos 4 dígitos; el resto enmascarado con `*`). Proviene de la Pista II. |
| `CSE` | 3 | N | Código de servicio (de la Pista II); se envía en claro. |
| `CBC` | 3 | N | Código del banco. Sin uso: siempre `000`. |
| `NYA` | 1–26 | ANS | Nombre del titular de la tarjeta para el comprobante (Pista I o TAG 5F20); se completa con espacios a la derecha. |
| `REG` | 6 | N | Número de registro. Sin uso: `000041`. |
| `MDI` | 1 | A | Modo de entrada (`M`, `B`, `C`, `L`, `E`). Consulte [Tablas de Códigos](/es/host-to-host/reference-h2h/code-tables). |
| `VER` | 1–15 | ANS | Versión del software del Pinpad. |
| `FDV` | 4 | N | Fecha de vencimiento (`YYMM`), de la Pista II. |
| `TC2` | 256–512 | ANS | Pista II cifrada con la clave RSA de Y19. Proviene de la Pista II o del TAG 57. |
| `1NL` | 1 | N | Indicador de Pista I no leída: `0` leída, `1` no leída. |
| `NSF` | 1–12 | N | Número de serie físico del Pinpad. |
| `CPG` | 1–300 | ANS | Criptograma EMV (TLV). `N` si no aplica. |
| `CAU` | 6 | N | Código de autorización. Se devuelve como 6 espacios en blanco. |
| `CRE` | 2 | N | Código de respuesta del emisor (TAG 8A y resultado del SDK). |
| `NSP` | 3 | N | Número de secuencia del PAN (TAG 5F34). |
| `APN` | 0–32 | ANS | Nombre de la aplicación EMV seleccionada, en hexadecimal, para el comprobante (TAG 9F12 / TAG 50). |
| `AID` | 0–16 | ANS | Identificador de la aplicación EMV seleccionada (TAG 4F). |
| `KSN-PAN` | 20 | H | Key Serial Number del PAN cifrado con DUKPT. |
| `ENC-PAN` | 1–256 | ANS | Criptograma del PAN cifrado con DUKPT. |
| `TDC` | 1 | AN | Tipo de cuenta (MAESTRO). `N` para no imprimirlo. |
| `PIN` | 16–32 | ANS | PINBLOCK si se ingresó un PIN; en caso contrario se omite. |
| `KSN` | 20 | N | Key Serial Number del PIN DUKPT; se incrementa en cada operación EMV con PIN. Se omite si no hay PIN. |

### Y02 - Respuesta de datos adicionales

Lo genera el Pinpad después de leer una tarjeta. La solicitud puede actualizar importes y pedir datos de banda; la estructura de la respuesta depende del modo de entrada (BANDA o CHIP).

**Solicitud Y02 (Host → Pinpad)**

| Campo | Longitud | Attr | Descripción |
| --- | --- | --- | --- |
| `U4D` | 1 | N | Solicitar los últimos 4 dígitos (solo banda). |
| `CDS` | 1 | N | Solicitar el código de seguridad (solo banda). |
| `ET1` | 1 | N | Enviar la Pista I (banda). Sin uso: se ignora el valor. |
| `SPI` | 1 | N | Solicitar el PIN (solo banda). |
| `PTC` | 1 | N | Solicitar el tipo de cuenta (habitualmente MAESTRO). |
| `PMK` | 1 | AN | Posición de la clave maestra (`0`–`9`, o `N`). PMK del PIN = valor; PMK del PAN = valor + 1. |
| `WRK` | 1–16 | ANS | Clave de trabajo (`N` si no se solicita PIN ni cifrado de pistas). Sin uso: se ignora el valor. |
| `ENC` | 1 | N | Cifrado DUKPT del PAN: `0` desactivado, `1` activado, `2` activado usando la ranura 3. |
| `IMP` | 12 | N | Importe de la compra; actualiza el valor de `Y19.IMP`. |
| `ICB` | 12 | N | Importe del cashback; actualiza el valor de `Y19.ICB`. |

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

| Campo | Longitud | Attr | Descripción |
| --- | --- | --- | --- |
| `TJA` | 1–19 | N | Número de tarjeta (los primeros 8 y los últimos 4; el resto enmascarado con `*`). Proviene de la Pista II. |
| `FDV` | 4 | N | Fecha de vencimiento (`YYMM`), de la Pista II. |
| `TC1` | 256–512 | ANS | Pista I cifrada con la clave RSA de Y19 (banda). |
| `TC2` | 256–512 | ANS | Pista II cifrada con la clave RSA de Y19 (banda). |
| `1NL` | 1 | N | Indicador de Pista I no leída: `0` leída, `1` no leída. |
| `CDS` | 1–4 | N | Código de seguridad cifrado con la clave RSA de Y19 (ingresado por el usuario). |
| `NSF` | 1–12 | N | Número de serie físico del Pinpad. |
| `KSN-PAN` | 20 | H | Key Serial Number del PAN cifrado con DUKPT. |
| `ENC-PAN` | 1–256 | ANS | Criptograma del PAN cifrado con DUKPT. |
| `TDC` | 1 | AN | Tipo de cuenta (MAESTRO). `N` para no imprimirlo. |
| `PIN` | 16–32 | ANS | PINBLOCK si se ingresó un PIN; en caso contrario se omite. |
| `KSN` | 20 | N | Key Serial Number del PIN DUKPT; se incrementa en cada operación con PIN. |

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

| Campo | Longitud | Attr | Descripción |
| --- | --- | --- | --- |
| `TJA` | 1–19 | N | Número de tarjeta (los primeros 8 y los últimos 4; el resto enmascarado con `*`). Proviene de la Pista II. |
| `FDV` | 4 | N | Fecha de vencimiento (`YYMM`), de la Pista II. |
| `TC2` | 256–512 | ANS | Pista II cifrada con la clave RSA de Y19. Proviene del TAG 57 (chip). |
| `1NL` | 1 | N | Indicador de Pista I no leída: `0` leída, `1` no leída. |
| `NSF` | 1–12 | N | Número de serie físico del Pinpad. |
| `CPG` | 1–300 | ANS | Criptograma EMV (formato TLV). `N` si no se envía información. |
| `CAU` | 6 | N | Código de autorización. Se devuelve como 6 espacios en blanco. |
| `CRE` | 2 | N | Código de respuesta del emisor. |
| `NSP` | 3 | N | Número de secuencia del PAN (TAG 5F34). |
| `APN` | 0–32 | ANS | Nombre de la aplicación EMV seleccionada, en hexadecimal, para el comprobante (TAG 9F12 / TAG 50). |
| `AID` | 0–16 | ANS | Identificador de la aplicación EMV seleccionada (TAG 4F). |
| `KSN-PAN` | 20 | H | Key Serial Number del PAN cifrado con DUKPT. |
| `ENC-PAN` | 1–256 | ANS | Criptograma del PAN cifrado con DUKPT. |
| `TDC` | 1 | AN | Tipo de cuenta (MAESTRO). `N` para no imprimirlo. |
| `PVF` | 1 | N | Indicador de PIN offline verificado por la tarjeta. Debe ser `0` para PIN online. |
| `PIN` | 16–32 | ANS | PINBLOCK si se ingresó un PIN; en caso contrario se omite. |
| `KSN` | 20 | N | Key Serial Number del PIN DUKPT; se incrementa en cada operación EMV con PIN. |

### Y03 - Autorización del Host

La instrucción final que el Host envía para completar el flujo.

**Campos clave \[Host]**:

* **\[CAU]**: código de autorización del emisor.
* **\[CRE]**: código de respuesta (por ejemplo, "00" para éxito).

## Manejo de errores (Y0E)

Si una operación falla, el terminal devuelve un reporte `Y0E` en lugar de la respuesta esperada de la secuencia.

| Código | Mensaje        | Descripción                                     |
| ------ | -------------- | ----------------------------------------------- |
| **01** | **CANCELADO**  | Cancelación iniciada por el usuario o el Host.  |
| **04** | **ERROR EMV**  | Fallo de lectura del chip o de protocolo.       |
| **08** | **SIN LLAVES** | Faltan las claves DUKPT en la ranura 3.         |