Emitir comprobante

Comprobantes - Emision

Emision, anulacion y cobro de comprobantes.

Descripcion

Endpoint para emitir comprobantes fiscales electrónicos (CFE). Valida los permisos del usuario y las políticas aplicables, genera el XML del comprobante, lo firma electrónicamente y lo registra en el sistema. Devuelve los datos del CFE emitido incluyendo serie, número, CAE y código QR.

El proceso incluye:

Validación de permisos y límites de uso
Generación y firma electrónica del XML
Registro del comprobante en el sistema
Asociación opcional con caja existente
Devolución de datos para impresión y consulta

Cambio de contrato (2026-02-17)

Desde el 17 de febrero de 2026, el objeto cfe.totales es opcional en este endpoint.

Si cfe.totales viene en el request, el sistema lo usa tal cual y no recalcula.
Si cfe.totales no viene, o viene vacío ({}), el sistema calcula totales automáticamente a partir de cfe.detalles para generar el XML.
Si cfe.emisor no viene, o viene sin ruc, el sistema lo completa automáticamente con datos de la empresa/sucursal.
Para ese emisor automático, la sucursal se resuelve por idEmpresa + codComercio.
El codigoDgiSucursal se toma del historial vigente de la sucursal según idDoc.fechaEmision; si no hay historial aplicable, usa Sucursal.CodigoCasaDgi y luego Empresa.CodigoCasaDgiPorDefecto.

Compatibilidad:

Integraciones existentes que ya envían cfe.totales no cambian comportamiento.
Integraciones nuevas pueden enviar solo idDoc + detalles (más los nodos que correspondan) y omitir totales.
Integraciones nuevas también pueden omitir emisor cuando idEmpresa y codComercio están informados correctamente.

Endpoint

Metodo: POST
Path: /api/v1/comprobante/emitir

Headers

Authorization: Bearer
Content-Type: application/json

Parámetros principales

idEmpresa

Identificador único de la empresa en el sistema. Corresponde al ID interno de la empresa que está emitiendo el comprobante.

Cómo obtenerlo:

Via API: GET /api/v1/usuario/empresas - devuelve lista de empresas del usuario actual
Via API: GET /api/v1/usuario/{idUsuario}/empresas - devuelve empresas de un usuario específico

codComercio

Código que identifica al comercio (sucursal) dentro de la empresa. Es parte de la identificación fiscal ante DGI.

Cómo obtenerlo:

Via API: GET /api/v1/sucursal/todas - devuelve lista de sucursales con sus códigos

codTerminal

Código que identifica la terminal/caja dentro de una sucursal. Combinado con codComercio, identifica unívocamente el punto de emisión.

Cómo obtenerlo:

Via API: GET /api/v1/puntoemision/todos - devuelve todos los puntos de emisión
Via API: GET /api/v1/puntoemision/sucursal/{idSucursal} - devuelve terminales de una sucursal específica

Relación entre codComercio y codTerminal

La combinación codComercio + codTerminal identifica unívocamente:

Sucursal: Determinada por el codComercio
Caja/Punto de emisión: Determinada por el codTerminal dentro de esa sucursal

Esta estructura permite que una empresa tenga múltiples sucursales (cada una con su codComercio) y cada sucursal tenga múltiples cajas/terminales (cada una con su codTerminal).

cfe.emisor (opcional)

Puede omitirse cfe.emisor. En ese caso el backend genera el nodo Emisor automáticamente:

RUT y razón social desde Empresa.
Teléfono, email, domicilio, ciudad y departamento priorizando Sucursal (resuelta por codComercio) y con fallback a Empresa.
Código DGI de sucursal según historial (SucursalCodigoDgiHistorial) para la fechaEmision del comprobante.

Recomendación:

Si querés que se use la configuración correcta de sucursal en el emisor automático, enviá siempre codComercio e idDoc.fechaEmision.

cfe.totales (opcional)

Puede omitirse el objeto totales si se envían líneas en cfe.detalles.

Ejemplo mínimo (sin totales):

{
  "idEmpresa": 123,
  "codComercio": "001",
  "codTerminal": "T1",
  "cfe": {
    "idDoc": {
      "tipoCfe": 101,
      "fechaEmision": "2026-02-17",
      "formaPago": 1
    },
    "detalles": [
      {
        "numeroLineaDetalle": 1,
        "indicadorFacturacion": 3,
        "nombreItem": "Producto A",
        "cantidad": 1,
        "unidadMedida": "N/A",
        "precioUnitario": 122,
        "montoItem": 122
      }
    ]
  }
}

Trazabilidad en detalles (opcional)

Para productos con trazabilidad configurada (lote, serie o ambos), cada línea de detalles puede incluir el objeto datosTrazabilidad.

datosTrazabilidad

Objeto con la selección de trazabilidad para la línea. Campos opcionales según el tipo:

id_lote: ID del lote (cuando el producto controla por lote).
id_serie: ID de la serie (cuando el producto controla por serie).

Notas:

Si el producto requiere trazabilidad y no se envía datosTrazabilidad, la emisión puede fallar por validación en el front.
Para tipo LoteYSerie deben enviarse ambos campos.

Guías prácticas

Para ejemplos completos de cómo usar este endpoint, consulta las siguientes guías:

Request

curl -X POST '$BASE/api/v1/comprobante/emitir'

{
  "idEmpresa": 123,
  "codComercio": "001",
  "codTerminal": "T1",
  "adenda": "Texto libre",
  "uuid": "uuid-opcional",
  "destinatariosPdf": "correo1@dominio.com,correo2@dominio.com",
  "origen": "Api|Web|...",
  "esAppMovil": 0,
  "idComprobanteGuardado": 0,
  "idVendedor": 0,
  "idCaja": 0,
  "cfe": {
    "idDoc": {
      "tipoCfe": 111,
      "serie": "A",
      "numero": 1,
      "fechaEmision": "YYYY-MM-DD",
      "periodoDesde": "YYYY-MM-DD",
      "periodoHasta": "YYYY-MM-DD",
      "montoBruto": 0,
      "formaPago": 1,
      "fechaVencimiento": "YYYY-MM-DD",
      "fechaValor": "YYYY-MM-DD",
      "clausulaVenta": "...",
      "modalidadVenta": "...",
      "viaTransporte": "...",
      "tipoTraslado": "...",
      "indicadorPagoTerceros": "...",
      "indicadorCobranzaPropia": 0,
      "numeroInterno": "...",
      "informacionAdicional": "...",
      "secretoProfesional": "...",
      "indicadorCompraMEReventa": "...",
      "indicadorPropiedadMercaderiaTransportada": "...",
      "codPaisProp": "...",
      "tipoDocumentoProp": "...",
      "docProp": "...",
      "razonSocialProp": "..."
    },
    "emisor": {
      "ruc": "...",
      "razonSocial": "...",
      "nombreComercial": "...",
      "giro": "...",
      "telefono": "...",
      "segundoTelefono": "...",
      "email": "...",
      "sucursal": "...",
      "codigoDgiSucursal": "...",
      "domicilioFiscal": "...",
      "ciudad": "...",
      "departamento": "...",
      "informacionAdicional": "..."
    },
    "receptor": {
      "tipoDocumento": "...",
      "codigoPais": "...",
      "documento": "...",
      "documentoExt": "...",
      "razonSocial": "...",
      "direccion": "...",
      "ciudad": "...",
      "departamento": "...",
      "pais": "...",
      "codigoPostal": "...",
      "informacionAdicional": "...",
      "lugarEntrega": "...",
      "idCompraCliente": "...",
      "idCliente": "...",
      "idProveedor": "..."
    },
    "totales": {
      "tipoMoneda": "UYU",
      "tipoCambio": 1,
      "montoNoGravado": 0,
      "montoExportacionYAsim": 0,
      "montoImpuestoPercibido": 0,
      "montoIvaSuspenso": 0,
      "montoNetoIvaTasaMinima": 0,
      "montoNetoIvaTasaBasica": 0,
      "montoNetoIvaOtraTasa": 0,
      "tasaIvaTasaMinima": 0,
      "tasaIvaTasaBasica": 0,
      "montoIvaTasaMinima": 0,
      "montoIvaTasaBasica": 0,
      "montoIvaOtraTasa": 0,
      "montoTotal": 0,
      "montoTotalRetenido": 0,
      "cantidadLineasDetalle": 1,
      "montoNoFacturable": 0,
      "montoPagar": 0,
      "retencionesPercepciones": [],
      "montoCreditoFiscal": 0
    },
    "detalles": [
      {
        "numeroLineaDetalle": 1,
        "indicadorFacturacion": 1,
        "nombreItem": "...",
        "NCM": "...",
        "descripcionItem": "...",
        "cantidad": 1,
        "unidadMedida": "...",
        "precioUnitario": "0.00",
        "descuentoPct": 0,
        "descuentoMonto": 0,
        "idPromo": 0,
        "promoNombre": "",
        "promoTipo": "DESC_PCT|DESC_MONTO|PRECIO_FIJO",
        "promoDescuentoMonto": 0,
        "precioUnitarioFinal": 0,
        "recargoPct": 0,
        "recargoMonto": 0,
        "montoItem": 0,
        "indicadorAgenteResponsable": "...",
        "codigos": [],
        "retencionesPercepciones": [],
        "subDescuentos": [],
        "idVariante": "...",
        "idListaPrecio": "...",
        "datosTrazabilidad": {
          "id_lote": 123,
          "id_serie": 456
        }
      }
    ],
    "referencias": [
      {
        "numeroLineaReferencia": 1,
        "indicadorGlobal": "...",
        "tipoDocumentoReferencia": "...",
        "serieFacturaReferencia": "...",
        "numeroFacturaReferencia": "...",
        "razonReferencia": "...",
        "fechaFacturaReferencia": "YYYY-MM-DD",
        "tipoMonedaCfeReferencia": "...",
        "tipoCambioCfeReferencia": "...",
        "montoCfeReferencia": "..."
      }
    ],
    "descuentosRecargosGlobales": [
      {
        "numeroLinea": 1,
        "tipoMovimiento": "...",
        "tipoDescuento": "...",
        "codigoDescuento": "...",
        "glosa": "...",
        "valorDescuento": "...",
        "indicadorFacturacion": "..."
      }
    ],
    "mediosPago": [
      {
        "numeroLineaMedioPago": 1,
        "codigoMedioPago": "...",
        "glosaMedioPago": "...",
        "ordenMedioPago": "...",
        "valorPago": "..."
      }
    ],
    "subTotalesInfo": [
      {
        "numeroLineaSubtotal": 1,
        "glosaSubtotal": "...",
        "ordenSubtotal": "...",
        "valorSubtotal": "..."
      }
    ],
    "complementoFiscal": {
      "tipoDocumento": "...",
      "codPais": "...",
      "nroDocumento": "...",
      "nombreMandante": "..."
    }
  }
}

Response

{
  "_Id": 999,
  "CodRespuesta": "00",
  "MensajeRespuesta": "OK",
  "IdComprobante": 123,
  "TipoCfe": 111,
  "Serie": "A",
  "Nro": 1,
  "IdCAE": "...",
  "NroInicalCAE": "...",
  "NroFinalCAE": "...",
  "DatosQR": "...",
  "CodSeguridad": "...",
  "XmlFirmado": "<xml>..."
}

Errores

Empresa deshabilitada
La fecha de emision no puede ser anterior a la fecha de inicio de actividad de la empresa (YYYY-MM-DD).
Politica cfe.maximo_por_mes: PoliticaServicio::mensajeUso(...)
El XML no es un CFE valido
El campo 'cfe.totales' debe ser un arreglo cuando se envía.