Catalogo de campos de las bandejas de entrada

Referencia técnica para catalogo de campos de las bandejas de entrada dentro del cliente local.

Bandeja REST local Arquitectura FFI Recuperación

Objetivo

Esta guía resume los campos disponibles tanto para envío como para respuesta en las bandejas REST y de intercambio de archivos.

Campos comunes de envio para `enqueue`, `sign-cfe` y JSON por archivos

Campo	Tipo	Obligatorio	Descripcion
`tipo_cfe`	numero	Si	Tipo de CFE, por ejemplo `101`, `111`, `182`
`uuid`	texto	Si	Identificador externo unico
`xml`	texto	Si	XML del CFE sin firmar
`cod_comercio`	texto	No	Codigo de comercio para enrutar perfil
`cod_terminal`	texto	No	Codigo de terminal para enrutar perfil
`adenda`	texto	No	Adenda adicional
`emails`	lista de texto	No	Destinatarios asociados
`impresora`	texto	No	Especificacion de impresion
`send_now`	booleano	No	Si es `true`, intenta enviar al servidor en el mismo flujo

Regla de ruteo por punto de emision

Campo	Regla
`cod_comercio`	Si se usa, debe venir junto con `cod_terminal`
`cod_terminal`	Si se usa, debe venir junto con `cod_comercio`

Si ninguno de los dos viene, el daemon usa el perfil activo.

Campos de request de `reprint` y `pdf`

Campo	Tipo	Obligatorio	Descripcion
`uuid`	texto	Condicional	Identificador del comprobante
`tipo_cfe`	numero	Condicional	Requerido si no se usa `uuid`
`serie`	texto	Condicional	Requerido si no se usa `uuid`
`numero`	numero	Condicional	Requerido si no se usa `uuid`
`impresora`	texto	Si	En `/reprint` define impresora. En `/pdf` usar `pdf`
`variant`	texto	No	Variante de impresion, por ejemplo `personalizado`, `rollo`, `escpos`
`fallback_copies`	numero	No	Copias por defecto
`cod_comercio`	texto	No	Ruteo a punto de emision
`cod_terminal`	texto	No	Ruteo a punto de emision

Campos de request de `validar-xml`

Campo	Tipo	Obligatorio	Descripcion
`xml`	texto	Si	XML a validar

Campos de request de `existe-constancia`

Campo	Tipo	Obligatorio	Descripcion
`tipo_cfe`	numero	Si	Tipo de comprobante
`serie`	texto	Si	Serie emitida
`numero`	numero	Si	Numero emitido
`cod_comercio`	texto	No	Ruteo
`cod_terminal`	texto	No	Ruteo

Campos de response de `sign-cfe`

Campo	Tipo	Descripcion
`Uuid`	texto o null	UUID del integrador
`TipoCfe`	texto o null	Tipo de CFE
`Serie`	texto o null	Serie asignada
`Numero`	texto o null	Numero asignado
`CodigoRespuesta`	texto	`00`, `31`, `96`
`MensajeRespuesta`	texto	Resultado funcional
`CodigoTerminal`	texto o null	Terminal efectiva
`CodigoComercio`	texto o null	Comercio efectivo
`NumeroInicialCae`	texto o null	Inicio de rango CAE
`NumeroFinalCae`	texto o null	Fin de rango CAE
`VencimientoCae`	texto o null	Fecha de vencimiento del CAE
`CfeFirmado`	texto o null	XML firmado
`DatosCodigoQr`	texto o null	URL o datos del QR
`CodigoSeguridad`	texto o null	Codigo de seguridad
`FechaFirmaCfe`	texto o null	Timestamp de firma
`ImagenQr`	texto o null	Reservado; hoy suele ser `null`

Campos de response de `enqueue`

Campo	Tipo	Descripcion
`ok`	booleano	Si la solicitud fue aceptada
`stored_path`	texto	Ruta del archivo creado en inbox
`uuid`	texto	UUID aceptado
`send_now`	booleano	Valor efectivo del request

Campos de response de `health`

Campo	Tipo	Descripcion
`ok`	booleano	Estado general del listener
`service`	texto	Nombre del servicio
`rest_base_url`	texto	URL base activa
`state.running`	booleano	Si el daemon esta en ejecucion

Campos principales de response de `state`

Campo	Tipo	Descripcion
`running`	booleano	Si el daemon esta activo
`pid`	numero o null	PID actual
`rest_enabled`	booleano	Si REST esta habilitado
`file_inbox_enabled`	booleano	Si la bandeja de archivos esta habilitada
`rest_port`	numero o null	Puerto REST
`rest_base_url`	texto o null	URL REST efectiva
`started_at`	texto o null	Inicio del daemon
`heartbeat_at`	texto o null	Ultimo heartbeat
`last_cycle_at`	texto o null	Ultimo ciclo
`last_sync_at`	texto o null	Ultima sincronizacion
`last_reserve_at`	texto o null	Ultima reserva de rango
`last_flush_at`	texto o null	Ultimo flush
`last_retry_at`	texto o null	Ultimo retry
`last_reconcile_at`	texto o null	Ultima conciliacion
`last_cert_rotation_at`	texto o null	Ultima rotacion de certificado
`cycle_count`	numero	Cantidad de ciclos ejecutados
`inbox_pending`	numero	Pendientes en bandeja
`inbox_processed`	numero	Procesados
`inbox_failed`	numero	Fallidos
`last_error`	texto o null	Ultimo error registrado

Campos de response de `validar-xml`

Campo	Tipo	Descripcion
`ok`	booleano	Si la operacion pudo ejecutarse
`valido`	booleano	Si el XML paso validaciones
`issues`	lista	Lista de errores o advertencias
`issues[].code`	texto	Codigo del issue
`issues[].message`	texto	Mensaje del issue

Campos de response de `existe-constancia`

Campo	Tipo	Descripcion
`ok`	booleano	Si la consulta pudo ejecutarse
`existe`	booleano	Si existe localmente
`codigo_respuesta`	texto o null	Resultado funcional guardado
`estado`	texto o null	Estado de la constancia
`uuid`	texto o null	UUID asociado
`tipo_cfe`	numero o null	Tipo del comprobante
`serie`	texto o null	Serie
`numero`	numero o null	Numero

Campos del formato de texto `310`

Posicion	Campo	Uso
`1`	Tipo de mensaje	Debe ser `310`
`2`	UUID	Identificador externo
`3`	Tipo CFE	Tipo del comprobante
`6`	Request ID	Identificador auxiliar
`7`	Hora	Informativo
`8`	Fecha	Informativo
`9`	Codigo terminal	Ruteo
`10`	Codigo comercio	Ruteo
`20`	Destino impresion	Especificacion de impresora
`22`	Email PDF	Destinatarios para el flujo local

Debajo de la primera linea va el XML, y opcionalmente un bloque <Adenda>.

Campos del formato de respuesta `311`

Posicion	Campo
`1`	Tipo de mensaje `311`
`2`	UUID
`3`	Tipo CFE
`4`	Serie
`5`	Numero
`6`	Request ID
`7`	Hora de firma
`8`	Fecha de firma
`9`	Codigo terminal
`10`	Codigo comercio
`11`	Numero autorizacion CAE
`12`	Numero inicial CAE
`13`	Numero final CAE
`14`	Vencimiento CAE
`15`	Codigo respuesta
`16`	Datos codigo QR
`17`	Mensaje respuesta
`18`	Numero inicial CAE repetido
`19`	Numero final CAE repetido
`20`	Destino impresion
`21`	Codigo seguridad
`22`	Email PDF

Cuando la operacion es exitosa, debajo de la linea 311 se agrega el XML firmado.

Campos mínimos a persistir del lado integrador

Para una operación emitida se recomienda guardar:

uuid
tipo_cfe
cod_comercio
cod_terminal
serie
numero
codigo_respuesta
mensaje_respuesta

Campos mínimos para reimpresión o PDF

El integrador debería poder localizar un comprobante por:

uuid

o, alternativamente:

tipo_cfe
serie
numero
cod_comercio
cod_terminal

Relación con otras guías

la guía Bandeja REST del cliente local explica el panorama general
la guía Proceso de integración para emisión describe el orden recomendado
la guía Integración por REST local documenta cada endpoint con más detalle
la guía Integración por bandeja de archivos documenta los contratos por carpeta

Objetivo

Campos comunes de envio para enqueue, sign-cfe y JSON por archivos

Regla de ruteo por punto de emision

Campos de request de reprint y pdf

Campos de request de validar-xml

Campos de request de existe-constancia

Campos de response de sign-cfe

Campos de response de enqueue

Campos de response de health

Campos principales de response de state

Campos de response de validar-xml

Campos de response de existe-constancia

Campos del formato de texto 310

Campos del formato de respuesta 311