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.
Qué resuelve
Sección titulada «Qué resuelve»- 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é necesitas antes
Sección titulada «Qué necesitas antes»| Qué | Detalle |
|---|---|
| Una credencial de reseller, no la llave del proyecto | Estas 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ón | Lectura 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 emitido | listarLiquidacionesComoReseller 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). |
Cómo usar la credencial con el CLI
Sección titulada «Cómo usar la credencial con el CLI»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):
REDCUMBRE_LLAVE_PRUEBA=keys/reseller-<empresa>-lectura-prueba.json redcumbre api listarLiquidacionesEn 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.
-
Lista las liquidaciones. Las que tu empresa recibe como cliente:
Ventana de terminal redcumbre api listarLiquidaciones --param limit=20Resultado esperado:
200consuccess: true,data(las filas),total,limit,offsetysandbox: true. Admiteestado,periodoysearch;limithasta 300 (por defecto 10) yoffset. 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(filtrosperiodoytipoDestinatario:tenantoreseller). Para recorrer todas las páginas, agrega--todas. -
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 eldteIdcon la API de documentos (Documentos tributarios electrónicos) y una llaveFULL-APIde tu propia empresa. -
Descarga el PDF.
Ventana de terminal redcumbre api descargarPdfDeLiquidacion --param id=<id> --salida liquidacion.pdfResultado esperado: un archivo PDF en
liquidacion.pdf. Está disponible para liquidaciones confirmadas y, para quien las emite, también en borrador; en otro caso responde404. Con una credencial de máquina rige un tope de 120 descargas por hora por credencial: al superarlo responde429conDOWNLOAD_RATE_LIMIT_EXCEEDED. Dónde guardar el archivo: Documentos y PDF. -
Antes de confirmar, comprueba el emisor de facturación. Sin un emisor válido la confirmación se rechaza:
Ventana de terminal redcumbre api obtenerEmisorDeFacturacionResultado esperado:
200con el emisor configurado (id,razonSocial,rut,tipoIntegracion) y, enproblema, 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). Siproblemano esnull, no confirmes: el emisor se configura en la cobranza del reseller (ver Reseller, operaciónactualizarCobranzaDelReseller). -
Confirma liquidaciones en borrador. En producción, esto emite una factura ante el SII por cada liquidación. Confirma un lote de liquidaciones
BORRADORy 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.jsonResultado esperado:
201condata.jobsCreatedigual a la cantidad encolada. Si alguna liquidación no existe o no está enBORRADOR, o si no hay emisor de facturación válido, responde400y no encola ninguna. Al confirmarse, cada liquidación pasa aCONFIRMADAy 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. -
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:
201con el DTE generado. Responde400si 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 necesitaidempotencyKey; repetirlo no duplica. -
Corrige una liquidación facturada. Sobre un documento de la cadena (el
idque entregalistarDocumentosDeLiquidacion, que es eldocumentoOrigenId). Las dos operaciones crean un borrador, y exigenidempotencyKey. 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_RETROACTIVOyOTRO. 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.jsonredcumbre api crearRefacturaDeLiquidacion --param id=<id> --cuerpo @refactura.jsonResultado esperado:
201con el borrador creado. Cuando el documento ya fue emitido por otra vía,asociarDocumentoALiquidacionlo adjunta a la cadena de la liquidación, con eldteIddel documento y sutipo(FACTURA,NOTA_CREDITOoREFACTURA):{"dteId": "dte_17ae8ad6ff3c4a1b9d2e","tipo": "NOTA_CREDITO","idempotencyKey": "asociar-nc-liquidacion-1042"}Resultado esperado:
201; el documento aparece después enlistarDocumentosDeLiquidacion.Las escrituras que crean algo exigen
idempotencyKeyen el cuerpo: sin ella, la operación responde400conCLAVE_DE_REPETICION_REQUERIDAy 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 responde409conCLAVE_USADA_CON_OTROS_DATOS.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- Una lectura:
200,success: trueysandbox: trueen el modo de prueba. Los identificadores negativos delatan el conjunto de ejemplo. - Una confirmación:
data.jobsCreatedcoincide con la cantidad enviada; al rato,obtenerLiquidacionmuestra el estadoCONFIRMADAy su documento enlistarDocumentosDeLiquidacion. 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
derivadodel documento de origen.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
403 en una escritura | La credencial es de lectura | Usa la credencial de escritura |
403 con NO_ES_RESELLER | La empresa no tiene perfil de reseller | Las liquidaciones emitidas sólo existen para un reseller |
400 al confirmar | Una liquidación no existe o no está en BORRADOR, o no hay emisor de facturación válido | Mira obtenerEmisorDeFacturacion y el estado de cada liquidación. No se encoló ninguna |
400 al reintentar | La liquidación no está confirmada, no tiene DTE pendiente o ya tiene su factura | No hay nada que reintentar |
400 con CLAVE_DE_REPETICION_REQUERIDA | Falta idempotencyKey en una escritura | Agrégala |
409 con CLAVE_USADA_CON_OTROS_DATOS o CLAVE_EN_CURSO | Clave reusada con otros datos, o la primera llamada sigue en curso | Usa otra clave, o reintenta en unos segundos |
404 | La 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 prueba | Verifica el id |
429 con DOWNLOAD_RATE_LIMIT_EXCEEDED | Más de 120 descargas de PDF por hora | Espera a la hora siguiente |
429 con LIMITE_EXCEDIDO | Más de 10.000 llamadas por hora con la credencial | Espera; respeta Retry-After |
400 con OPERACION_NO_DISPONIBLE_EN_PRUEBA | La operación no tiene comportamiento de ejemplo en el modo de prueba | Hazla sólo en producción |
Antes de pasar a producción
Sección titulada «Antes de pasar a 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 correrconfirmarLiquidacionescon 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 enkeys/reseller-<empresa>-escritura-produccion.jsony 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_DTEoPORTAL_MIPYME. Uno de prueba,SOLO_BOLETAoAPI_EXTERNAno sirve yobtenerEmisorDeFacturacionlo dice enproblema.