Emite un CFE

POST

/v1/cfe/emitir

• Producción
• Homologación / pruebas

Emite un Comprobante Fiscal Electrónico (CFE) y lo envía a DGI.

Este es el endpoint recomendado para integraciones nuevas: el cuerpo es un JSON estructurado y Host Factura se encarga de armar el XML, firmarlo, asignar CAE, manejar la numeración y enviarlo a DGI.

Tipos de CFE soportados

Ver la sección “Tipos de Comprobante Fiscal Electrónico (CFE) soportados” en la introducción para la tabla completa con los 24 tipos (códigos 101 a 153).

Los más usados son:

Código	Descripción	Receptor
101	e-Ticket	Opcional (consumidor final)
102	Nota de Crédito de e-Ticket	Heredado de la referencia
103	Nota de Débito de e-Ticket	Heredado de la referencia
111	e-Factura	Obligatorio
112	Nota de Crédito de e-Factura	Heredado de la referencia
113	Nota de Débito de e-Factura	Heredado de la referencia
121-123	e-Factura Exportación y sus Notas	Obligatorio + exportacionInfo
124	e-Remito Exportación	Obligatorio + remitoInfo
181	e-Remito	Obligatorio + remitoInfo
182	e-Resguardo	Obligatorio + códigos de retención

Ítems

Cada elemento de items[] puede ser:

• De catálogo: solo { id, quantity }. Los datos del producto se toman del catálogo de la cuenta.
• Ad-hoc: { name, quantity, price, billingIndex, description?, unit?, code? }. billingIndex es obligatorio: 1=Exento, 2=10%, 3=22%, 4=Otras.

Emisión de Notas de Crédito y Notas de Débito

Las Notas se usan para modificar el monto de un Comprobante Fiscal Electrónico previamente emitido. No hay que volver a enviar los datos del receptor ni la fecha original — todo eso se hereda automáticamente del CFE referenciado.

Notas de Crédito (102, 112, 122, 132, 142, 152): reducen el monto del comprobante original. Casos típicos:

• Devolución de mercadería por parte del cliente.
• Error de facturación (monto mal cargado, ítem facturado por error).
• Descuento aplicado posteriormente.
• Bonificación comercial.

Notas de Débito (103, 113, 123, 133, 143, 153): aumentan el monto del comprobante original. Casos típicos:

• Intereses por mora.
• Cargos adicionales no facturados originalmente (flete, envasado, etc.).
• Ajustes de precio por diferencias detectadas posteriormente.

Reglas de correspondencia entre el tipo de la Nota y el del CFE referenciado:

Tipo de Nota	Puede referenciar
102 (Nota de Crédito de e-Ticket) / 103 (Nota de Débito de e-Ticket)	e-Ticket (101)
112 (Nota de Crédito de e-Factura) / 113 (Nota de Débito de e-Factura)	e-Factura (111)
122 / 123 (Notas de e-Factura Exportación)	e-Factura Exportación (121)
132 / 133 (Notas de e-Ticket por Cuenta Ajena)	e-Ticket por Cuenta Ajena (131)
142 / 143 (Notas de e-Factura por Cuenta Ajena)	e-Factura por Cuenta Ajena (141)
152 / 153 (Notas de e-Boleta de Entrada)	e-Boleta de Entrada (151)

Cómo emitirla: enviá el tipo correspondiente y referenciaId con el UUID del CFE original. Los items[] representan las líneas que se están acreditando/debitando — no son los ítems originales.

CFE de Cobranza (e-Recibo)

Para documentar el cobro de una venta a crédito (o un adelanto de precios), emití un e-Ticket (101) o e-Factura (111) con esCobranza: true (A-C20 IndCobPropia=1). Reglas:

• Todas las líneas deben ser no facturables: billingIndex 6 (no facturable) o 7 (no facturable negativo). La operación ya se gravó al emitir la factura original, así que la cobranza no vuelve a generar IVA.
• La representación impresa lleva la leyenda “Cobranza” (requisito DGI).
• referenciaId (opcional) apunta a la factura a crédito cobrada y arma la Referencia (Zona F).
• Admite cobros parciales: el monto cobrado es el de las líneas.
• Documentar la cobranza es opcional según DGI; la forma de pago de la factura original es solo informativa y no obliga a emitir un recibo posterior.

Moneda extranjera

Cuando moneda != "UYU", cambio es obligatorio. Obtené el tipo de cambio vigente con GET /v1/cotizaciones (caché 24h, datos del BCU).

Pre-requisitos de la cuenta

Para que la emisión funcione, la cuenta debe tener: CVA (certificado digital) activo, CAE vigente para el tipo+serie+sucursal, y datos básicos de empresa cargados. Si falta algo, recibirás 409 NO_CAE_VIGENTE u otro error específico.

Metadatos personalizados

El campo opcional metadata adjunta datos propios del negocio (no fiscales) al CFE: número de transacción de pago, método de pago, referencia externa, etc. Las claves deben corresponder a campos ya definidos para la cuenta desde el panel web (Configuración → Campos personalizados); no existe un endpoint público para crearlos ni listarlos. Claves desconocidas o valores fuera de tipo devuelven 422 METADATA_INVALIDA (detalle en error.details). Se devuelven de vuelta en data.metadata, tanto en esta respuesta como en GET /v1/cfe/info/{id}. No soportado en POST /v1/cfe/emitir-xml. Editar los metadatos de un CFE ya emitido solo es posible desde el panel web, no por esta API. Guía completa: Metadatos personalizados.

Autorizaciones

• BearerAuth

Cuerpo de la solicitud

Datos del CFE a emitir

object

clienteId

string format: uuid

cliente

object

tipoDocumento

Any of:

number

number

string

string

documento

string

razonSocial

string

denominacion

string

direccion

string

ciudad

string

estado

string

pais

string

email

string

items

required

Array<object>

>= 1 items

object

id

string format: uuid

name

string

quantity

required

number

price

number

billingIndex

integer

unit

string

description

string

code

string

codeType

string

kind

string

tipo

required

integer

moneda

required

string

Allowed values: UYU USD ARS BRL EUR

cambio

number

adenda

string

formaPago

Any of:

number

number

Allowed values: 1

number

number

Allowed values: 2

fchVenc

A-C12 Fecha de vencimiento del pago (AAAA-MM-DD). Pensada para ventas a crédito (formaPago=2).

string

esCobranza

Emite un CFE de Cobranza (e-Recibo, A-C20 IndCobPropia=1): solo e-Ticket (101) o e-Factura (111), con todas las líneas no facturables (billingIndex 6 o 7) y la leyenda “Cobranza” en la representación impresa. Opcionalmente, referenciaId apunta a la factura a crédito cobrada (Referencia Zona F).

boolean

referenciaId

string format: uuid

exportacionInfo

object

clausulaVenta

required

string

modalidadVenta

required

integer

viaTransporte

required

integer

remitoInfo

object

tipoTraslado

required

integer

>= 1 <= 2

propiedadMercaderia

integer

clauVenta

string

modVenta

integer

viaTransp

integer

tipoTraslado

integer

>= 1 <= 2

propiedadMercaderia

integer

metadata

Metadatos personalizados de la cuenta (campos NO fiscales definidos desde el panel web, Configuración → Campos personalizados). Las claves deben coincidir con las definidas para la cuenta; valores fuera de tipo/formato son rechazados con 422 METADATA_INVALIDA. No soportado en POST /v1/cfe/emitir-xml.

object

key

additional properties

Any of:

string

string

number

number

boolean

boolean

Array<string>

Array<string>

unknown

nullable

unknown

nullable

Ejemplos

e-Ticket a consumidor final (sin datos de receptor)

Caso típico de POS: venta de bajo monto a consumidor final, sin RUT ni datos del cliente. Para tipo 101 (e-Ticket), si el monto neto en UI no supera el tope (~10.000 UI), el receptor es opcional.

{
  "tipo": 101,
  "moneda": "UYU",
  "formaPago": 1,
  "items": [
    {
      "name": "Café americano",
      "quantity": 2,
      "price": 90,
      "billingIndex": 3
    },
    {
      "name": "Medialuna",
      "quantity": 1,
      "price": 60,
      "billingIndex": 3
    }
  ]
}

e-Factura a empresa (RUT)

Emisión a una empresa identificada por RUT (tipoDocumento=2). Mezcla un ítem de catálogo (solo con id y quantity) con un ítem ad-hoc.

{
  "tipo": 111,
  "moneda": "UYU",
  "formaPago": 2,
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EMPRESA EJEMPLO S.A.",
    "direccion": "18 DE JULIO 1234",
    "ciudad": "MONTEVIDEO",
    "estado": "MONTEVIDEO",
    "pais": "UY",
    "email": "facturacion@empresa-ejemplo.com.uy"
  },
  "items": [
    {
      "id": "3f1a5c80-7b22-4e8d-9f1c-2b3a4c5d6e7f",
      "quantity": 3
    },
    {
      "name": "Servicio de consultoría — Septiembre",
      "quantity": 1,
      "price": 12500,
      "billingIndex": 3,
      "description": "Horas: 40 — Hora: $312.50"
    }
  ],
  "adenda": "Forma de pago: transferencia BROU 001-1234567-89"
}

e-Factura en USD (cambio obligatorio)

Cuando la moneda es distinta de UYU, el campo cambio (TC al día) es obligatorio. Usalo en conjunto con GET /v1/cotizaciones para obtener el TC vigente del BCU.

{
  "tipo": 111,
  "moneda": "USD",
  "cambio": 39.85,
  "formaPago": 2,
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EXPORTADORA EJEMPLO S.A.",
    "pais": "UY"
  },
  "items": [
    {
      "name": "Producto X",
      "quantity": 10,
      "price": 100,
      "billingIndex": 3
    }
  ]
}

Nota de Crédito de un e-Ticket previo

Para reducir el monto de un CFE previamente emitido (por devolución, error de cobro, descuento posterior, etc.), emití una Nota de Crédito: tipo 102 si el original es e-Ticket, tipo 112 si el original es e-Factura. Enviá referenciaId con el UUID del CFE original; la fecha y los datos del receptor se heredan automáticamente.

{
  "tipo": 102,
  "moneda": "UYU",
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "items": [
    {
      "name": "Devolución por error de cobro",
      "quantity": 1,
      "price": 240,
      "billingIndex": 3
    }
  ]
}

Nota de Débito por intereses por mora

Para aumentar el monto de un CFE previamente emitido (intereses por mora, cargos adicionales, ajustes de precio, etc.), emití una Nota de Débito: tipo 103 si el original es e-Ticket, tipo 113 si el original es e-Factura. Enviá referenciaId con el UUID del CFE original; la fecha y los datos del receptor se heredan automáticamente.

{
  "tipo": 113,
  "moneda": "UYU",
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "items": [
    {
      "name": "Intereses por mora — atraso 45 días",
      "quantity": 1,
      "price": 1830,
      "billingIndex": 3,
      "description": "TNA 12% sobre saldo $15.250"
    }
  ]
}

e-Factura de Cobranza (e-Recibo) de una venta a crédito

Documenta el cobro de una venta a crédito previa. Es un e-Ticket (101) o e-Factura (111) con esCobranza: true (A-C20 IndCobPropia=1): todas las líneas van como no facturable (billingIndex 6 o 7), porque la operación ya se gravó al emitir la factura original — la cobranza solo documenta el ingreso de dinero y no vuelve a generar IVA. La representación impresa lleva la leyenda “Cobranza”. Opcionalmente, referenciaId apunta a la factura a crédito cobrada. Admite cobros parciales (el monto cobrado es el de las líneas).

{
  "tipo": 111,
  "moneda": "UYU",
  "formaPago": 1,
  "esCobranza": true,
  "referenciaId": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "cliente": {
    "tipoDocumento": 2,
    "documento": "219999830019",
    "razonSocial": "EMPRESA EJEMPLO S.A.",
    "pais": "UY"
  },
  "items": [
    {
      "name": "Cobranza Factura A-123",
      "quantity": 1,
      "price": 12200,
      "billingIndex": 6
    }
  ],
  "adenda": "Cancelación de Factura A-123 — Transferencia BROU 001-1234567-89"
}

e-Ticket con metadatos personalizados

El campo metadata adjunta datos propios del negocio (no fiscales) al CFE: número de transacción de pago, método de pago, referencia externa, etc. Las claves deben corresponder a campos personalizados ya definidos para la cuenta desde el panel web (Configuración → Campos personalizados); no hay endpoint público para crearlos ni listarlos. Valores fuera de tipo o claves no configuradas devuelven 422 METADATA_INVALIDA con el detalle en error.details. 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"
  }
}

Respuestas

200

CFE emitido. Verificá el campo data.estado (aceptado/pendiente/rechazado/observado).

object

data

required

object

id

required

string format: uuid

tipo

required

integer

tipoDescripcion

required

string

serie

required

string

nullable

numero

required

integer

nullable

rutEmisor

required

string

nullable

moneda

required

string

tipoCambio

required

number

nullable

subtotal

required

number

iva

required

number

total

required

number

adenda

required

string

anulado

required

boolean

estado

required

string

Allowed values: pendiente aceptado rechazado observado

estadoDgi

required

string

nullable

fechaEstadoDgi

required

string

nullable

motivoRechazo

required

string

nullable

codigoRespuesta

required

string

codigoSucursalDgi

required

number

nullable

clienteId

required

string

nullable

cuentaId

required

string format: uuid

sucursalId

required

string format: uuid

nullable

puntoEmisionId

required

string format: uuid

nullable

referenciaId

required

string format: uuid

nullable

uuidReferencia

required

string format: uuid

sobreId

required

string format: uuid

nullable

reporteDiarioId

required

string format: uuid

nullable

cfeRecurrenteId

required

string format: uuid

nullable

fechaCreacion

required

string

fechaActualizacion

required

string

metadata

required

Metadatos personalizados capturados en la emisión. {} si la cuenta no tiene campos configurados o no se enviaron valores.

object

key

additional properties

Any of:

string

string

number

number

boolean

boolean

Array<string>

Array<string>

unknown

nullable

unknown

nullable

Ejemplos

CFE emitido y aceptado por DGI

{
  "data": {
    "id": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
    "tipo": 111,
    "tipoDescripcion": "e-Factura",
    "serie": "A",
    "numero": 1234,
    "rutEmisor": "210000000000",
    "moneda": "UYU",
    "tipoCambio": 1,
    "subtotal": 12500,
    "iva": 2750,
    "total": 15250,
    "adenda": "Forma de pago: transferencia BROU 001-1234567-89",
    "anulado": false,
    "estado": "aceptado",
    "estadoDgi": "A",
    "fechaEstadoDgi": "2026-05-17T13:42:11.000Z",
    "motivoRechazo": null,
    "codigoRespuesta": "00",
    "codigoSucursalDgi": 1,
    "clienteId": null,
    "cliente": {
      "tipoDocumento": "RUC",
      "documento": "219999830019",
      "denominacion": "EMPRESA EJEMPLO S.A.",
      "direccion": null,
      "ciudad": null,
      "departamento": null,
      "pais": "UY"
    },
    "cuentaId": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
    "sucursalId": null,
    "puntoEmisionId": null,
    "referenciaId": null,
    "uuidReferencia": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "sobreId": "2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
    "reporteDiarioId": null,
    "cfeRecurrenteId": null,
    "fechaCreacion": "2026-05-17T13:42:10.000Z",
    "fechaActualizacion": "2026-05-17T13:42:11.000Z",
    "metadata": {}
  }
}

400

Datos inválidos. Falla la validación Zod del body, o el CFE no es construible.

Códigos posibles:

• CLIENT_CI_INVALID — Cédula uruguaya con dígito verificador incorrecto.
• NOTA_REFERENCE_UNDEFINED — Es una Nota de Crédito o Nota de Débito y falta referenciaId.
• EXPORTACION_INFO_REQUIRED — Es CFE de exportación y falta exportacionInfo.
• REMITO_INFO_REQUIRED — Es e-Remito y falta remitoInfo.
• ITEM_INVALIDO — Un ítem no tiene nombre o unidad.
• PUNTO_EMISION_REQUERIDO — Sucursal con múltiples puntos sin x-point-id.
• SUCURSAL_INVALIDA — x-branch-id no pertenece a la cuenta.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Cédula uruguaya con dígito verificador inválido

{
  "error": {
    "code": "CLIENT_CI_INVALID",
    "message": "La cédula uruguaya del cliente no es válida (dígito verificador incorrecto)"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Sucursal con múltiples puntos sin x-point-id

{
  "error": {
    "code": "PUNTO_EMISION_REQUERIDO",
    "message": "La sucursal tiene múltiples puntos de emisión activos: x-point-id es requerido"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

401

No autenticado. La API_KEY no fue enviada o no es válida.

Códigos posibles: API_AUTH_HEADER_MISSING, API_AUTH_HEADER_INVALID, API_ACCESS_INVALID.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Falta header Authorization

{
  "error": {
    "code": "API_AUTH_HEADER_MISSING",
    "message": "Se esperaba la cabecera Authorization con esquema Bearer"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Secret key inválida o revocada

{
  "error": {
    "code": "API_ACCESS_INVALID",
    "message": "Acceso no autorizado"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

403

Acceso prohibido. La credencial es válida pero el plan o el alcance de sucursal lo impiden.

Códigos posibles: API_FEATURE_DISABLED, API_ACCESS_BRANCH_MISMATCH.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

El plan no incluye API

{
  "error": {
    "code": "API_FEATURE_DISABLED",
    "message": "El plan de esta cuenta no tiene habilitado el acceso a la API"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Header x-branch-id distinto al fijo del ApiAccess

{
  "error": {
    "code": "API_ACCESS_BRANCH_MISMATCH",
    "message": "El ApiAccess está fijado a otra sucursal y no coincide con x-branch-id"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

404

Recurso referenciado no existe.

• CLIENTE_NO_ENCONTRADO — clienteId no existe en la cuenta.
• CFE_REFERENCIA_NO_EXISTE — referenciaId no existe (al emitir una Nota de Crédito o Nota de Débito).

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Cliente referenciado no existe

{
  "error": {
    "code": "CLIENTE_NO_ENCONTRADO",
    "message": "Cliente no encontrado (uuid)"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

409

Conflicto con el estado actual (típicamente CAE).

• NO_CAE_VIGENTE — No hay CAE activo para el tipo solicitado.
• CAE_RANGE_EXHAUSTED — Se agotó el rango de numeración del CAE.
• SUCURSAL_INACTIVA — La sucursal resuelta está deshabilitada.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

No hay CAE vigente para el tipo solicitado

{
  "error": {
    "code": "NO_CAE_VIGENTE",
    "message": "No hay CAE vigente para eTck"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Rango de numeración del CAE agotado

{
  "error": {
    "code": "CAE_RANGE_EXHAUSTED",
    "message": "Se agotó el rango del CAE A para eTck"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

422

Metadatos personalizados inválidos (metadata).

• METADATA_INVALIDA — una o más claves no están definidas para la cuenta, o el valor no cumple el tipo/formato configurado. El detalle campo por campo va en error.details.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Metadatos personalizados inválidos

{
  "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"
}

429

Rate limit excedido. Esperá los segundos indicados en el header Retry-After.

object

error

required

object

code

required

Identificador estable del error en SCREAMING_SNAKE_CASE

string

message

required

Mensaje legible en español

string

details

Información adicional (puede ser objeto, array o string)

nullable

requestId

UUID de correlación; mismo valor que el header X-Request-ID

string format: uuid

Ejemplos

Excediste el rate limit

{
  "error": {
    "code": "API_RATE_LIMITED",
    "message": "Se superó el límite de requests para esta API key"
  },
  "requestId": "5b2c7c8a-1f6e-4d29-9a0b-7c3a8d1e2f4c"
}

Headers

Retry-After

integer

Ejemplo

42

Segundos hasta que se libera la ventana de rate limit