Metadatos personalizados

Además de los datos fiscales que exige DGI, tu cuenta puede definir campos propios para capturar información de negocio en cada CFE: número de transacción de pago, método de pago, referencia de un sistema externo, centro de costos, etc. Estos campos viajan en el objeto metadata y no afectan el XML que se envía a DGI — son un sidecar de tu cuenta, no parte del comprobante fiscal.

Definición de campos: solo desde el panel web

Los campos personalizados (nombre, clave, tipo, si son requeridos, opciones válidas, etc.) se definen desde Configuración → Campos personalizados en el panel de Host Factura. No existe un endpoint público en la API v1 para crear, editar o listar estas definiciones — la API solo permite capturar valores al emitir y leerlos en el detalle del CFE.

Enviar metadatos al emitir

Incluí el campo opcional metadata en el body de POST /v1/cfe/emitir (no soportado en POST /v1/cfe/emitir-xml):

{
  "tipo": 101,
  "moneda": "UYU",
  "formaPago": 1,
  "items": [
    { "name": "Cuota mensual — Plan Premium", "quantity": 1, "price": 1490, "billingIndex": 3 }
  ],
  "metadata": {
    "numero_transaccion": "TXN-8827461",
    "metodo_pago": "tarjeta",
    "referencia_externa": "sub_9F2K1"
  }
}

Cada clave debe corresponder a un campo ya definido para la cuenta. Los valores pueden ser texto, número, booleano o una lista de textos (para campos de tipo multiopción), según el tipo configurado para esa clave.

Validación

La validación es dinámica, contra las definiciones de la cuenta (no un esquema fijo): tipo de dato, si el campo es requerido, longitud máxima, opciones permitidas, etc. Si algo no cumple, la respuesta es:

{
  "error": {
    "code": "METADATA_INVALIDA",
    "message": "Metadatos inválidos: metodo_pago: valor no permitido; nro_transaccion: requerido",
    "details": [
      "metodo_pago: valor no permitido",
      "nro_transaccion: requerido"
    ]
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

HTTP 422 METADATA_INVALIDA. El CFE no se emite si la validación falla — no hay riesgo de quemar numeración por un metadato mal formado.

Consejo

Si tu cuenta no tiene campos personalizados configurados, o el campo enviado no está definido, la clave se rechaza. No hace falta enviar metadata si no tenés campos configurados: el valor por defecto es {}.

Leer los metadatos de un CFE

El detalle de un CFE (GET /v1/cfe/info/{id}) incluye los metadatos capturados en data.metadata:

{
  "data": {
    "id": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
    "tipo": 101,
    "...": "...",
    "metadata": {
      "numero_transaccion": "TXN-8827461",
      "metodo_pago": "tarjeta",
      "referencia_externa": "sub_9F2K1"
    }
  }
}

data.metadata es {} cuando la cuenta no tiene campos configurados o no se enviaron valores al emitir. POST /v1/cfe/emitir devuelve el mismo campo en su respuesta.

Editar metadatos después de emitir

La edición post-emisión de metadatos (reemplazar el set completo de valores de un CFE ya emitido) está disponible solo desde el panel web, no por la API pública. Los metadatos nunca modifican ni re-firman el XML del CFE — son puramente informativos de tu lado.

Otros usos (solo panel web)

Desde el panel, los campos personalizados también permiten:

• Mostrarlos en el PDF y la representación impresa del CFE (si el campo se marca “mostrar en PDF”).
• Armar reportes y widgets de indicadores (torta, barras, KPI, serie temporal) sobre los valores capturados, en el dashboard de la cuenta.
• Visibilidad condicional: un campo puede depender del valor de otro (por ejemplo, “número de transacción” solo aplica si “método de pago” es tarjeta o transferencia).

Estas capacidades son de configuración/consulta desde el panel y no tienen endpoint en la API v1.

Metadatos en webhooks

Si necesitás que tus sistemas reciban los metadatos en tiempo real (sin tener que hacer un GET /v1/cfe/info/{id} después de cada emisión), activá el opt-in incluirMetadata en tu suscripción de webhooks. Ver Webhooks → Metadatos en el evento cfe.emitido.

Esquema completo del campo metadata en request y response: Referencia OpenAPI — operación POST /v1/cfe/emitir.