Integración por bandeja de archivos

Objetivo

Esta guía describe cómo integrar un sistema externo con el cliente local usando intercambio de archivos.

Está pensada para integradores. Cubre:

• carpetas de trabajo
• formatos soportados
• respuestas esperadas
• ruteo por punto de emisión
• impresión automática

Estructura de carpetas

La bandeja trabaja con estas ubicaciones lógicas:

• carpeta base
• carpeta de entrada
• carpeta temporal
• carpeta de salida
• carpeta de error

Ejemplo:

BandejaArchivos/
  Entrada/
  Temporal/
  Salida/
  Error/

Flujo:

1. el integrador deja el archivo en Entrada
2. el cliente local lo mueve a Temporal
3. si sale bien termina en Salida
4. si falla termina en Error

Ruteo por punto de emisión

Hay dos modos:

• usar el perfil activo del daemon
• enviar cod_comercio y cod_terminal para enrutar a un punto de emisión específico

Regla:

• si se envía uno de esos campos, deben enviarse ambos

Formato JSON

Ejemplo:

{
  "tipo_cfe": 111,
  "uuid": "externo-123",
  "cod_comercio": "1",
  "cod_terminal": "1",
  "xml": "<CFE xmlns=\"http://cfe.dgi.gub.uy\" version=\"1.0\">...</CFE>",
  "adenda": "Texto opcional",
  "emails": ["cliente@example.com"],
  "impresora": "CajaFiscal;FORMATO=personalizado;COPIAS=2",
  "send_now": true
}

Campos principales:

Formato TXT compatible

Actualmente el mensaje soportado es:

• 310: solicitud de numeración y firma local

La respuesta es:

• 311

Ejemplo:

310|UUID|111|||1|120000|20150101|FCTEST01|TEST01|||||||||||
<CFE xmlns="http://cfe.dgi.gub.uy" version="1.0">
...
</CFE>
<Adenda>
Texto de adenda
</Adenda>

Campos relevantes de la primera línea:

Respuesta 311

Cuando el procesamiento termina, el daemon genera un archivo *-response.txt.

Si el procesamiento fue correcto:

• el original pasa a Salida
• se genera *-response.txt
• debajo de la primera línea se deja el XML firmado

Si falla:

• el original pasa a Error
• se genera *.error.txt
• también se genera *.response.txt

La respuesta puede incluir:

• UUID
• TipoCfe
• Serie
• Numero
• CodigoRespuesta
• MensajeRespuesta
• CodigoTerminal
• CodigoComercio
• NumeroInicialCAE
• NumeroFinalCAE
• VencimientoCAE
• CFEFirmado
• FechaFirmaCFE
• CodigoSeguridad
• DatosCodigoQr

Códigos de respuesta

El resultado funcional principal viaja en:

• CodigoRespuesta
• MensajeRespuesta

Regla práctica:

• considerar emitido un comprobante solo si existe respuesta de éxito y la operación devolvió serie y número válidos

Impresión automática

La impresión puede enviarse:

• en JSON, con impresora
• en TXT, usando Destino de impresión

Ejemplos:

• CajaFiscal
• CajaFiscal;COPIAS=2
• CajaFiscal;FORMATO=personalizado;COPIAS=2
• CajaFiscal;FORMATO=escpos;COPIAS=2
• CajaFiscal;FORMATO=rollo;COPIAS=2

Parámetros:

Errores frecuentes

• falta cod_comercio o cod_terminal al enrutar por punto de emisión
• no existe el perfil local para ese punto
• no hay impresora configurada
• error de firma
• error de rango
• error SOAP

Recomendaciones

• usar uuid realmente únicos
• no considerar éxito solo porque el archivo salió de Entrada
• registrar en el sistema externo uuid, tipo_cfe, serie, numero, codigo_respuesta y mensaje_respuesta
• si se usa ruteo por punto de emisión, enviar siempre cod_comercio y cod_terminal