# 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.

Antes de empezar necesitas dos cosas: estar dado de alta como emisor (te pedimos el comprobante de RIF vigente, la razón social y el domicilio fiscal tal como aparecen en el RIF) y tu llave de acceso, que te entregamos una sola vez.

## 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

Los montos van en bolívares. El documento fiscal venezolano se emite en la moneda de curso legal, aunque el negocio cobre en divisas. Si tu sistema trabaja en dólares, convierte con la tasa del día antes de enviar.

### 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.

¿Dudas con la integración? Escríbenos a contacto@gustitoxpress.app con el RIF del emisor y te ayudamos.