Ir al contenido

Liquidaciones de la plataforma

Una liquidación es el documento de cobro con el que se factura el uso de la plataforma: un período, las líneas de consumo con su monto e IVA, y la factura (DTE) que la respalda. Esta ficha trata las liquidaciones de la plataforma, no la liquidación factura (tipo 43) que emites tú a un tercero con emitirDte: esa está en Documentos tributarios electrónicos.

Hay dos lados, y una misma empresa puede estar en los dos:

  • Recibidas: lo que se le liquida a tu empresa como cliente. Las puede leer cualquier empresa con una credencial de reseller de lectura o de escritura.
  • Emitidas: lo que un reseller le liquida a sus empresas clientes. Quien emite puede confirmarlas, reintentar su factura y corregirlas con notas de crédito y refacturas.
  • Listar las liquidaciones (recibidas o emitidas), su historial por período y el detalle de cada una.
  • Descargar el PDF de una liquidación.
  • Ver la cadena documental de una liquidación: su factura, sus notas de crédito y sus refacturas.
  • Confirmar liquidaciones en borrador, lo que encola la emisión de su factura.
  • Reintentar la factura de una liquidación confirmada que quedó pendiente.
  • Corregir una liquidación ya facturada con una nota de crédito o una refactura.
QuéDetalle
Una credencial de reseller, no la llave del proyectoEstas operaciones declaran los roles RESELLER_API_LECTURA y RESELLER_API_ESCRITURA. La llave que instala redcumbre init es FULL-API y no las alcanza. La credencial la crea una persona con rol RESELLER_FULL_ACCESS; cómo se crea, qué tope tiene y cómo se rota está en Reseller.
Qué rol necesita cada operaciónLectura o escritura sirven para leer (los GET). Confirmar, reintentar, asociar un documento y crear notas de crédito o refacturas exigen la credencial de escritura; con la de lectura responden 403.
Ser reseller para lo emitidolistarLiquidacionesComoReseller y las acciones sobre liquidaciones emitidas exigen que la empresa tenga perfil de reseller; si no, 403 con NO_ES_RESELLER.
Un emisor de facturación válido (sólo para confirmar y reintentar)El emisor con que el reseller factura sus liquidaciones. Tiene que ser de producción y de facturación (FULL_DTE o PORTAL_MIPYME).

redcumbre api usa la llave del proyecto. Para que use la credencial del reseller, apunta la variable de la llave sólo en ese comando, sin tocar el .env (el archivo lo escribió redcumbre reseller credenciales crear; no lo leas ni lo imprimas):

Ventana de terminal
REDCUMBRE_LLAVE_PRUEBA=keys/reseller-<empresa>-lectura-prueba.json redcumbre api listarLiquidaciones

En producción la variable es REDCUMBRE_LLAVE_PRODUCCION y el comando lleva --produccion. En el resto de la ficha, redcumbre api … significa «con la credencial del reseller que corresponda».

Los ejemplos usan el modo de prueba. Con una credencial de prueba las lecturas devuelven siempre el mismo conjunto de ejemplo: tres liquidaciones (dos emitidas a los dos primeros clientes de ejemplo y una recibida de REDCUMBRE) cuyos identificadores son negativos. Las escrituras se validan igual que en producción pero no guardan nada: responden con el conjunto de ejemplo.

  1. Lista las liquidaciones. Las que tu empresa recibe como cliente:

    Ventana de terminal
    redcumbre api listarLiquidaciones --param limit=20

    Resultado esperado: 200 con success: true, data (las filas), total, limit, offset y sandbox: true. Admite estado, periodo y search; limit hasta 300 (por defecto 10) y offset. Las que tu empresa emite como reseller: listarLiquidacionesComoReseller (mismos filtros). El historial por período, de la más reciente a la más antigua, sólo de las confirmadas en que eres el cliente: listarHistorialDeLiquidaciones (filtros periodo y tipoDestinatario: tenant o reseller). Para recorrer todas las páginas, agrega --todas.

  2. Lee el detalle y la cadena documental.

    Ventana de terminal
    redcumbre api obtenerLiquidacion --param id=<id>
    redcumbre api listarDocumentosDeLiquidacion --param id=<id>

    Resultado esperado: el detalle trae cabecera, líneas, estado y documentos. La cadena documental es un árbol: cada documento trae su tipo, sus datos tributarios y, en derivados, los documentos que nacieron de él. Si tu empresa recibió la liquidación y no la emitió, la respuesta no incluye los identificadores de DTE. Para leer el DTE completo de una liquidación que emitiste tú, usa el dteId con la API de documentos (Documentos tributarios electrónicos) y una llave FULL-API de tu propia empresa.

  3. Descarga el PDF.

    Ventana de terminal
    redcumbre api descargarPdfDeLiquidacion --param id=<id> --salida liquidacion.pdf

    Resultado esperado: un archivo PDF en liquidacion.pdf. Está disponible para liquidaciones confirmadas y, para quien las emite, también en borrador; en otro caso responde 404. Con una credencial de máquina rige un tope de 120 descargas por hora por credencial: al superarlo responde 429 con DOWNLOAD_RATE_LIMIT_EXCEEDED. Dónde guardar el archivo: Documentos y PDF.

  4. Antes de confirmar, comprueba el emisor de facturación. Sin un emisor válido la confirmación se rechaza:

    Ventana de terminal
    redcumbre api obtenerEmisorDeFacturacion

    Resultado esperado: 200 con el emisor configurado (id, razonSocial, rut, tipoIntegracion) y, en problema, el motivo si no sirve (por ejemplo, que no hay emisor configurado, que es un emisor de prueba o que su integración no emite facturas). Si problema no es null, no confirmes: el emisor se configura en la cobranza del reseller (ver Reseller, operación actualizarCobranzaDelReseller).

  5. Confirma liquidaciones en borrador. En producción, esto emite una factura ante el SII por cada liquidación. Confirma un lote de liquidaciones BORRADOR y encola la emisión de su DTE; el proceso termina en segundo plano:

    {
    "liquidacionIds": [1042, 1043],
    "idempotencyKey": "confirmar-2026-10"
    }
    Ventana de terminal
    redcumbre api confirmarLiquidaciones --cuerpo @confirmar.json

    Resultado esperado: 201 con data.jobsCreated igual a la cantidad encolada. Si alguna liquidación no existe o no está en BORRADOR, o si no hay emisor de facturación válido, responde 400 y no encola ninguna. Al confirmarse, cada liquidación pasa a CONFIRMADA y recibe sus fechas de vencimiento y de corte, según la cobranza del reseller. En el modo de prueba no escribe nada y responde con el conjunto de ejemplo.

  6. Reintenta la factura que quedó pendiente. Si una liquidación confirmada no alcanzó a facturarse:

    Ventana de terminal
    redcumbre api reintentarDteDeLiquidacion --param id=<id>

    Resultado esperado: 201 con el DTE generado. Responde 400 si la liquidación no está confirmada, no tiene un DTE pendiente, ya tiene su factura, o el reseller no tiene un emisor de facturación válido: en ese caso no emite otro documento. No necesita idempotencyKey; repetirlo no duplica.

  7. Corrige una liquidación facturada. Sobre un documento de la cadena (el id que entrega listarDocumentosDeLiquidacion, que es el documentoOrigenId). Las dos operaciones crean un borrador, y exigen idempotencyKey. La nota de crédito sólo procede sobre liquidaciones confirmadas.

    {
    "documentoOrigenId": 501,
    "motivo": "AJUSTE_PRECIO",
    "motivoDescripcion": "Se cobró de más un período de consumo",
    "lineas": [
    { "metricaName": "dte_33_emitido", "units": 10, "unitAmount": 120 }
    ],
    "idempotencyKey": "nc-liquidacion-1042-ajuste"
    }

    Los motivos son AJUSTE_PRECIO, DEVOLUCION, ERROR_FACTURACION, DESCUENTO_RETROACTIVO y OTRO. La refactura vuelve a facturar con las líneas correctas:

    {
    "documentoOrigenId": 501,
    "lineas": [
    { "metricaName": "dte_33_emitido", "units": 10, "unitAmount": 100 }
    ],
    "idempotencyKey": "refactura-liquidacion-1042"
    }
    Ventana de terminal
    redcumbre api crearNotaDeCreditoDeLiquidacion --param id=<id> --cuerpo @nota.json
    redcumbre api crearRefacturaDeLiquidacion --param id=<id> --cuerpo @refactura.json

    Resultado esperado: 201 con el borrador creado. Cuando el documento ya fue emitido por otra vía, asociarDocumentoALiquidacion lo adjunta a la cadena de la liquidación, con el dteId del documento y su tipo (FACTURA, NOTA_CREDITO o REFACTURA):

    {
    "dteId": "dte_17ae8ad6ff3c4a1b9d2e",
    "tipo": "NOTA_CREDITO",
    "idempotencyKey": "asociar-nc-liquidacion-1042"
    }

    Resultado esperado: 201; el documento aparece después en listarDocumentosDeLiquidacion.

    Las escrituras que crean algo exigen idempotencyKey en el cuerpo: sin ella, la operación responde 400 con CLAVE_DE_REPETICION_REQUERIDA y no se ejecuta. El CLI la agrega sola y la imprime; para reintentar sin duplicar, repite el comando con --clave <esa clave>. Misma clave y mismos datos devuelven la respuesta de la primera vez; la misma clave con otros datos responde 409 con CLAVE_USADA_CON_OTROS_DATOS.

  • Una lectura: 200, success: true y sandbox: true en el modo de prueba. Los identificadores negativos delatan el conjunto de ejemplo.
  • Una confirmación: data.jobsCreated coincide con la cantidad enviada; al rato, obtenerLiquidacion muestra el estado CONFIRMADA y su documento en listarDocumentosDeLiquidacion. En el modo de prueba nada de esto cambia: la respuesta es el conjunto de ejemplo.
  • Un reintento: el DTE aparece en la cadena documental de la liquidación.
  • Una corrección: el borrador (o el documento asociado) aparece como derivado del documento de origen.
Si vesSignificaQué haces
403 en una escrituraLa credencial es de lecturaUsa la credencial de escritura
403 con NO_ES_RESELLERLa empresa no tiene perfil de resellerLas liquidaciones emitidas sólo existen para un reseller
400 al confirmarUna liquidación no existe o no está en BORRADOR, o no hay emisor de facturación válidoMira obtenerEmisorDeFacturacion y el estado de cada liquidación. No se encoló ninguna
400 al reintentarLa liquidación no está confirmada, no tiene DTE pendiente o ya tiene su facturaNo hay nada que reintentar
400 con CLAVE_DE_REPETICION_REQUERIDAFalta idempotencyKey en una escrituraAgrégala
409 con CLAVE_USADA_CON_OTROS_DATOS o CLAVE_EN_CURSOClave reusada con otros datos, o la primera llamada sigue en cursoUsa otra clave, o reintenta en unos segundos
404La liquidación no existe, no es de tu empresa, es un borrador que no puedes ver, o es de producción y usas una credencial de pruebaVerifica el id
429 con DOWNLOAD_RATE_LIMIT_EXCEEDEDMás de 120 descargas de PDF por horaEspera a la hora siguiente
429 con LIMITE_EXCEDIDOMás de 10.000 llamadas por hora con la credencialEspera; respeta Retry-After
400 con OPERACION_NO_DISPONIBLE_EN_PRUEBALa operación no tiene comportamiento de ejemplo en el modo de pruebaHazla sólo en producción
  • En producción, confirmar y reintentar emiten documentos ante el SII. Lo que cuesta depende de tu plan: redcumbre tarifas confirmarLiquidaciones --produccion. Una confirmación factura de verdad a tus clientes. No hay una acción para deshacerla: se corrige con nota de crédito. Confirma con la persona antes de correr confirmarLiquidaciones con una credencial de producción.
  • Cambia de credencial, no sólo de modo. La de producción se crea aparte (redcumbre reseller credenciales crear --tipo escritura --entorno produccion --nombre "…"), queda en keys/reseller-<empresa>-escritura-produccion.json y no se muestra. Los comandos que escriben en producción llevan --produccion --confirmar <slug>. Ver Modo de prueba y producción.
  • Los datos son los tuyos. Las lecturas dejan de devolver el conjunto de ejemplo y muestran tus liquidaciones, con identificadores positivos.
  • Necesitas un emisor de facturación de producción, de integración FULL_DTE o PORTAL_MIPYME. Uno de prueba, SOLO_BOLETA o API_EXTERNA no sirve y obtenerEmisorDeFacturacion lo dice en problema.