Operación sign-cfe

Objetivo

POST /sign-cfe es la operación principal para numerar y firmar un CFE con respuesta inmediata.

Se usa cuando el sistema integrador necesita el resultado en la misma llamada.

Endpoint

POST /sign-cfe

Cuándo usarlo

• emisión interactiva
• emisión con respuesta inmediata
• escenarios donde la aplicación necesita recibir serie, numero y cfe_firmado en el acto

Campos de request

Ejemplo de request

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>",
    "adenda": "Pago contado",
    "emails": ["[email protected]"],
    "send_now": false
  }'

Campos de response

Ejemplo de response exitosa

{
  "uuid": "venta-pos-000123",
  "tipo_cfe": "101",
  "serie": "A",
  "numero": "301",
  "codigo_respuesta": "00",
  "mensaje_respuesta": "CFE firmado localmente",
  "codigo_terminal": "1",
  "codigo_comercio": "1",
  "numero_inicial_cae": "301",
  "numero_final_cae": "400",
  "vencimiento_cae": "2028-01-01",
  "cfe_firmado": "<CFE>...</CFE>",
  "datos_codigo_qr": "https://...",
  "codigo_seguridad": "ZmCpqT",
  "fecha_firma_cfe": "2026-04-29T19:00:00Z",
  "imagen_qr": null
}

Ejemplo de response con error funcional

{
  "uuid": "venta-pos-000123",
  "tipo_cfe": "101",
  "serie": null,
  "numero": null,
  "codigo_respuesta": "31",
  "mensaje_respuesta": "error de validacion: el XML fue rechazado por el validador local: TOT_MNTTOTAL_INVALID: MntTotal no coincide con la suma esperada",
  "codigo_terminal": "1",
  "codigo_comercio": "1",
  "numero_inicial_cae": null,
  "numero_final_cae": null,
  "vencimiento_cae": null,
  "cfe_firmado": null,
  "datos_codigo_qr": null,
  "codigo_seguridad": null,
  "fecha_firma_cfe": null,
  "imagen_qr": null
}

Códigos funcionales relevantes

Cuando el rechazo viene del validador local, mensaje_respuesta incluye los motivos concretos encontrados. Si hay muchos errores, se devuelven los primeros motivos y un contador de errores adicionales.

Códigos HTTP relevantes

Escenarios de error típicos

XML inválido

Resultado esperado:

• rechazo funcional
• codigo_respuesta = "31"

uuid faltante

Resultado esperado:

• rechazo temprano del request
• mensaje típico: uuid es obligatorio

tipo_cfe inválido

Resultado esperado:

• rechazo temprano del request
• mensaje típico: tipo_cfe debe ser mayor a cero

ruteo incompleto

Resultado esperado:

• rechazo temprano del request
• mensajes típicos:
  • cod_comercio es obligatorio para enrutar por punto de emisión
  • cod_terminal es obligatorio para enrutar por punto de emisión

Regla de integración

Considerar emisión exitosa solo si:

• HTTP 200
• codigo_respuesta = "00"
• serie y numero vienen informados