Proceso de integración para emisión

Referencia técnica para proceso de integración para emisión dentro del cliente local.

Bandeja REST local Arquitectura FFI Recuperación

Objetivo

Esta guía describe el proceso recomendado para integrar la emisión de CFE usando el cliente local.

Resumen del flujo

En una integración estándar el sistema tercero:

construye el XML base del CFE
identifica el punto de emisión
valida el XML localmente
firma y emite o deja en cola
genera PDF o dispara impresión
persiste la referencia externa para reimpresión y recuperación

Paso 1. Verificar disponibilidad del cliente local

Antes de emitir, el integrador debería confirmar que la bandeja está activa:

curl http://127.0.0.1:18787/health

Si este paso falla, no conviene seguir con la emisión.

Paso 2. Definir el punto de emisión

Hay dos modos:

usar el perfil activo del daemon
enviar cod_comercio y cod_terminal

Cuando el sistema administra más de un punto de emisión, se recomienda enviar siempre ambos valores.

Paso 3. Construir el XML base

El XML de entrada debe llegar:

sin firma
sin asumir numeración definitiva para tipos normales
con RUCEmisor consistente con el perfil local
con estructura válida según DGI

La guía Ejemplos de XML por tipo de CFE muestra modelos de arranque.

Paso 4. Validar antes de firmar

Validar antes de firmar evita consumir tiempo operativo sobre XML inválido.

curl -X POST http://127.0.0.1:18787/validar-xml \
  -H 'Content-Type: application/json' \
  -d '{
    "tipo_cfe": 101,
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><CFE xmlns=\"http://cfe.dgi.gub.uy\" version=\"1.0\"><eTck>...</eTck></CFE>",
    "cod_comercio": "1",
    "cod_terminal": "1"
  }'

Paso 5. Elegir modo de procesamiento

Emisión síncrona

Usar POST /sign-cfe cuando:

el usuario necesita respuesta inmediata
la aplicación confirma la emisión en la misma pantalla
el integrador quiere recibir el XML firmado en la respuesta

Emisión asíncrona

Usar POST /enqueue cuando:

se desea desacoplar la app del proceso de emisión
se trabaja con cola local
la confirmación funcional puede resolverse después

Paso 6. Interpretar correctamente la respuesta

En POST /sign-cfe no alcanza con revisar el HTTP.

El integrador debe validar:

HTTP 200
codigo_respuesta = "00"
serie y numero informados

Si el HTTP es 200 pero codigo_respuesta indica rechazo, la emisión no debe considerarse exitosa.

Paso 7. Persistir referencias del lado integrador

Se recomienda guardar al menos:

uuid
tipo_cfe
cod_comercio
cod_terminal
serie
numero
codigo_respuesta

Eso permite reimpresión, generación posterior de PDF y recuperación operativa.

Paso 8. Resolver representación impresa

Luego de emitido el comprobante, el integrador puede:

pedir PDF con POST /pdf
pedir reimpresión con POST /reprint

Esto es especialmente útil cuando la aplicación separa la emisión fiscal de la salida física.

Paso 9. Recuperación y verificación

Cuando hay dudas sobre el estado final de una operación, conviene:

consultar GET /state
reintentar usando el mismo uuid según corresponda al flujo

Flujo mínimo recomendado

Para una integración nueva, este suele ser el camino más corto:

GET /health
POST /validar-xml
POST /sign-cfe
persistir uuid, serie, numero
POST /pdf o POST /reprint si aplica

Flujo recomendado para alto volumen o desacople

GET /health
POST /validar-xml
POST /enqueue
monitorear estado local
resolver impresión y recuperación en una etapa posterior

Ejemplo de primera integración

Para empezar sin complejidad innecesaria, la recomendación es integrar primero un único caso simple: eTicket contado con POST /sign-cfe.

La secuencia mínima sería:

hacer GET /health
construir un XML base simple
validarlo con POST /validar-xml
emitir con POST /sign-cfe
guardar uuid, serie, numero y cfe_firmado
opcionalmente generar PDF

Request de emisión de ejemplo

curl -X POST http://127.0.0.1:18787/sign-cfe \
  -H 'Content-Type: application/json' \
  -d '{
    "tipo_cfe": 101,
    "uuid": "venta-pos-000123",
    "cod_comercio": "1",
    "cod_terminal": "1",
    "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><CFE xmlns=\"http://cfe.dgi.gub.uy\" version=\"1.0\"><eTck>...</eTck></CFE>",
    "send_now": false
  }'

Qué validar del response

HTTP 200
codigo_respuesta = "00"
serie con valor
numero con valor

Qué guardar del response

uuid
tipo_cfe
serie
numero
codigo_respuesta
cfe_firmado

Paso siguiente recomendado

Una vez estable este flujo, recién conviene sumar:

POST /pdf
POST /reprint
POST /enqueue
más tipos de CFE
casos con receptor y referencias

Riesgos típicos

asumir que la bandeja local usa el mismo contrato que la API REST pública
enviar XML firmado cuando el flujo espera XML base
no persistir uuid
tratar un HTTP 200 como éxito funcional sin revisar codigo_respuesta
no rutear correctamente por cod_comercio y cod_terminal

Relación con el resto de la documentación

Después de esta guía, el orden recomendado es: