Integración con la imprenta digital

Guía para conectar un sistema administrativo con nuestra imprenta digital y obtener el número de control de sus documentos, conforme a la Providencia SNAT/2024/000102.

Qué hace esta integración y qué no

Lo que hace: recibe el documento que tu sistema ya calculó, le asigna un número de control único y consecutivo, lo resguarda, y te devuelve ese número junto con la dirección de comprobación para que la imprimas como código QR.

Lo que no hace: no calcula impuestos ni arma el documento por ti. Los montos los envía tu sistema y son responsabilidad del emisor.

Emitir un documento

POST https://sello.gustitoxpress.app/api/emitir

Cabeceras

Authorization: Bearer TU_LLAVE
Content-Type: application/json

La llave viaja en la cabecera, nunca en la dirección: las direcciones quedan escritas en registros e historiales.

Cuerpo

{
  "rif": "J-12345678-9",
  "serie": "A",
  "tipo": "factura",
  "numero_documento": 501,
  "hash": "identificador-unico-en-tu-sistema",
  "fecha": "2026-07-29T14:32:00.000Z",
  "base_bs": 10000.00,
  "iva_bs": 1600.00,
  "total_bs": 11600.00,
  "documento": {
    "cliente": { "nombre": "Consumidor final", "rif": "V-12345678-9" },
    "renglones": [
      { "nombre": "Servicio de mantenimiento", "cantidad": 1,
        "precio_bs": 10000.00, "alicuota": 16 }
    ]
  }
}

Campo	Tipo	Descripción
rif obligatorio	texto	RIF del emisor, tal como fue dado de alta
serie obligatorio	texto	La serie que te asignamos
tipo obligatorio	texto	factura, nota_credito o nota_debito
numero_documento obligatorio	entero	El correlativo de tu propio sistema
hash obligatorio	texto	Identificador único de ese documento en tu sistema. Es lo que evita que un reintento se numere dos veces
fecha obligatorio	texto	Fecha y hora de emisión, formato ISO 8601
base_bs obligatorio	número	Base imponible en bolívares
iva_bs obligatorio	número	Impuesto en bolívares
total_bs obligatorio	número	Total en bolívares
documento obligatorio	objeto	El detalle completo, con la estructura que use tu sistema. Se resguarda tal cual

Respuesta

{
  "numero_control": 1043,
  "sello": "https://sello.gustitoxpress.app/v/bec23e6d693c1263e2b1cb377902ac8a",
  "ya_estaba": false
}

Campo	Qué hacer con él
numero_control	Imprimirlo en el documento y guardarlo en tu sistema
sello	Imprimirlo como código QR en el documento. También conviene imprimir la dirección en texto, por si el QR sale mal impreso
ya_estaba	Si viene true, ese documento ya había sido numerado antes y te estamos devolviendo el mismo número. No es un error

Ejemplo

curl -X POST https://sello.gustitoxpress.app/api/emitir \
  -H "Authorization: Bearer TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "rif": "J-12345678-9",
    "serie": "A",
    "tipo": "factura",
    "numero_documento": 501,
    "hash": "fact-501",
    "fecha": "2026-07-29T14:32:00.000Z",
    "base_bs": 10000,
    "iva_bs": 1600,
    "total_bs": 11600,
    "documento": { "cliente": { "nombre": "Consumidor final" } }
  }'

Respuestas de error

Código	Qué significa	Qué hacer
400	Faltan datos o el documento está incompleto	La respuesta trae la lista faltan con los campos exactos
401	No autorizado	Revisa la llave, o si el emisor está suspendido
429	Demasiados intentos fallidos	Espera unos minutos antes de reintentar

Tres cosas importantes

1. El campo hash te protege

Si tu sistema pierde la conexión justo después de enviar, no sabes si el documento se numeró. Reintenta con el mismo hash: si ya estaba numerado, te devolvemos el mismo número de control y el mismo sello, con ya_estaba: true. Nunca vas a terminar con dos números de control para la misma factura.

2. Guarda el número de control y el sello

Son parte del documento fiscal. El sello impreso debe seguir funcionando años después, así que guárdalo junto al documento en tu sistema.

3. Qué se muestra al escanear el sello

Solo el emisor, su RIF, el tipo, el número, el número de control, la fecha y el monto. Nunca el detalle de lo consumido, por resguardo de los datos del cliente.