Skip to navigation
Referencia APITerminal Print Commands

Imprimir un comprobante en una terminal

Manda una copia del comprobante de una venta ya pagada a la impresora de la terminal donde se hizo. La terminal imprime sin salir de Modo espera, así que el siguiente cobro entra igual.

Esto separa la impresión del cobro: print_receipt en POST /api/terminal_session_commands imprime la copia del cliente en automático al aprobar; este endpoint imprime cualquier copia, de cualquier venta anterior, cuando tu sistema lo pida.

Caso típico

El cajero cobra con print_receipt: true y show_post_payment_screens: false: sale la copia del cliente y la terminal vuelve a Modo espera. Cuando el cajero ya cortó ese papel, tu sistema manda POST /api/terminal_print_commands con copy: "merchant" y sale la copia del comercio.

Reglas

  • El checkout_id viene de la respuesta del comando de cobro. La venta debe estar pagada (sale_not_paid si no) y haberse hecho en esa misma terminal (sale_on_another_terminal si no).
  • copy elige la copia: merchant (la del comercio, el default) o customer.
  • duplicate: true imprime DUPLICADO en el papel. Úsalo cuando reimprimes una copia que ya salió, para que el papel no se lea como una venta distinta.
  • Una venta reembolsada imprime el comprobante del reembolso.
  • La entrega es best-effort y llega a una terminal en Modo espera; una terminal ocupada la levanta cuando vuelve, dentro de los 10 minutos siguientes. El resultado de impresión no se expone por API y nunca afecta el estado financiero del pago.

Idempotencia

Manda un external_id propio y el mismo request no imprime dos veces: el segundo retorna el comando original con 200 en vez de 201.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Request

This endpoint expects an object.
terminal_idstringRequired

ID público de la terminal (trm_...). Lo obtienes en el panel, en POS → detalle de la terminal.

checkout_idstringRequired

ID del checkout de la venta a imprimir (ch_...), tal como viene en la respuesta del comando de cobro.

copyenumOptionalDefaults to merchant

Cuál copia imprimir.

Allowed values:
duplicatebooleanOptionalDefaults to false

Marca el papel como DUPLICADO. Úsalo al reimprimir una copia que ya salió.

external_idstringOptional

ID único de tu sistema para esta impresión dentro de la cuenta autenticada. Se usa para idempotencia.

Response

Ya existía un comando con ese external_id; se retorna el original

idstringOptional

ID público del comando de impresión

external_idstring or nullOptional

ID de tu sistema enviado al crear el comando, o null si no se envió uno

terminal_idstringOptional
ID de la terminal POS que imprime
checkout_idstringOptional
ID del checkout de la venta impresa
copyenumOptional

Cuál copia se mandó a imprimir

Allowed values:
duplicatebooleanOptional
Indica si el papel sale marcado como DUPLICADO
created_atdatetimeOptional

Momento en que se creó el comando

Errors

403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error