Compras y libros
Esta ficha explica cómo trabajar por API con lo que te venden tus proveedores (los documentos recibidos y el libro de compras) y con lo que vendes tú (el libro de ventas): leerlos, sincronizarlos con el SII, descargarlos, conciliarlos y, en compras, aceptar o reclamar un documento ante el SII. Cubre las 42 operaciones y los cinco avisos por webhook.
Qué resuelve
Sección titulada «Qué resuelve»- Listar y leer los documentos recibidos y los de cada libro, con sus filtros y su paginación.
- Aceptar o reclamar un documento recibido ante el SII, de uno en uno o en lote.
- Sincronizar el libro de compras y el de ventas, y seguir cada ejecución.
- Descargar el XML, el PDF o la exportación de un período.
- Subir a mano documentos recibidos (XML y PDF) o una venta propia (XML).
- Enterarte por webhook de cada documento nuevo, de cada acuse y de cada sincronización, sin consultar.
Qué necesitas antes
Sección titulada «Qué necesitas antes»| Qué | Detalle |
|---|---|
| Llave de la empresa | Rol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json. |
| Un RUT al alcance | La llave opera un RUT sólo si tiene un emisor Full DTE activo en la empresa. Un RUT sin emisor Full DTE activo responde 404, igual que uno que no existe, y no aparece en los listados. La regla se mide por RUT y en cada llamada. |
| Certificado delegado | Para aceptar y reclamar: el certificado que la empresa delegó para recibir documentos. |
| Webhooks configurados | Para los avisos: ver Webhooks. Se configuran en el panel, no por API. |
Antes de nada, averigua qué RUT tienes al alcance:
redcumbre api listarReceptoresLibroCompras --jsonredcumbre api listarEmisoresLibroVentas --jsonResultado esperado: 200 con los RUT de la empresa con libro de compras y de ventas. Si la lista viene vacía, ningún RUT tiene un emisor Full DTE activo y todo lo demás responderá 404. Con la llave de prueba el receptor de ejemplo es 76000001-9.
Los ejemplos usan el modo de prueba: validan contra un conjunto de ejemplo y responden como hechos, pero no guardan nada y no llegan al SII. Mismo contrato en producción.
-
Lista y lee los documentos recibidos. Los listados paginan con
limit(máximo 300) yoffset(Reglas comunes):Ventana de terminal redcumbre api listarDteRecibidos --param limit=50 --param offset=0 --jsonredcumbre api obtenerDteRecibido --param id=<id> --jsonResultado esperado:
200con la página y los totales al nivel raíz, y luego el documento. Unidque no es del conjunto de ejemplo responde404. Para el XML o el PDF:descargarXmlDteRecibido,descargarPdfDteRecibidoydescargarArchivoDteRecibido, con--salida <archivo>.Cada fila trae dos ids.
ides el documento en tu empresa: es el que reciben el detalle, el XML, el PDF, los archivos, aceptar y reclamar.maestroIdes el documento del SII, compartido por las empresas que lo reciben: con él esas operaciones responden404. -
Sincroniza con el SII. Encola una ejecución por RUT y la responde, sin esperar al SII:
Ventana de terminal redcumbre api sincronizarRecibidos --jsonredcumbre api consultarEstadoSincronizacionDteRecibidos --jsonResultado esperado:
201con las ejecuciones encoladas, y después el estado de cada una. Una segunda sincronización pedida muy pronto responde429con la hora en que se permite la siguiente. Los libros tienen la suya:sincronizarLibroCompraysincronizarLibroVenta, que aceptanperiodos(formatoAAAA-MM, hasta 12) y, en ventas,emisorRut:{"emisorRut": "76000001-9","periodos": ["2026-10", "2026-11"]}Ventana de terminal redcumbre api sincronizarLibroVenta --cuerpo @sincronizar.json --jsonUn RUT fuera del alcance responde
404. Para que el libro de ventas de un RUT se sincronice solo, actívalo conactivarEmisorLibroVenta(exige una credencial vigente del SII para ese RUT;pisoPeriodomarca desde cuándo carga la historia) y desactívalo condesactivarEmisorLibroVenta. -
Lee los libros. Cada libro tiene su resumen, su listado, su detalle, su XML y su exportación; todos piden el RUT (
receptorRuten compras,emisorRuten ventas) y el períodoAAAA-MM:Ventana de terminal redcumbre api obtenerResumenLibroCompras --param receptorRut=76000001-9 --param periodo=2026-01 --jsonredcumbre api listarDocumentosLibroVentas --param emisorRut=76000001-9 --param periodo=2026-01 --jsonredcumbre api descargarExportacionLibroCompras --param receptorRut=76000001-9 --param periodo=2026-01 --param formato=<formato> --salida libro.csvResultado esperado:
200con el resumen del período, la página de documentos y el archivo descargado. En ventas,obtenerResumenDiarioBoletasLibroVentasda el desglose diario de boletas. Para traer todo un período de una vez, usa la exportación: es el camino para lo que el webhook no te avisó.En el libro de compras cada fila trae
maestroId, que identifica el documento del SII, ytenantRecordId, el documento en tu empresa. El detalle (obtenerDocumentoLibroCompras), el XML (descargarXmlLibroCompras) y la conciliación recibentenantRecordId; conmaestroIdresponden404. UntenantRecordIdennullsignifica que la plataforma todavía no incorporó el documento: aparece en el libro, pero no tiene detalle ni descarga. En ventas, el detalle, el XML y la conciliación reciben elidde la fila, no eldteId. -
Acepta un documento. Antes lee el recuadro de abajo: no hay vuelta atrás. Manda siempre una clave de repetición:
{"clasificacionIva": "GIRO","idempotencyKey": "aceptar-doc-1042-intento-1"}Ventana de terminal redcumbre api aceptarRecibido --param id=<id> --cuerpo @aceptar.json --jsonResultado esperado:
202con el lote encolado. Con la misma clave y el mismo contenido, la plataforma responde lo mismo y no vuelve a actuar ante el SII; con la misma clave y otro contenido,409(CLAVE_USADA_CON_OTROS_DATOS). SinclasificacionIvase usa la clasificación que el documento ya tenga. -
Acepta varios de una vez. La lista admite hasta 300 documentos por llamada; si mandas más, se rechaza entera, sin aceptar ninguno:
{"ids": ["-4"],"clasificacionIva": "GIRO","respetarPreClasificacion": false,"idempotencyKey": "aceptar-lote-2026-11-12-1"}Ventana de terminal redcumbre api aceptarRecibidosMasivo --cuerpo @aceptar-lote.json --jsonResultado esperado:
202con el lote encolado; los documentos que no se pueden aceptar salen enerroresValidacion, cada uno con su motivo. Cada documento del lote queda aceptado por separado. -
Reclama un documento. El tipo de reclamo es
RCD,RFPoRFT:{"tipoReclamo": "RCD","notaReclamo": "Mercadería no recibida","idempotencyKey": "reclamar-doc-1042-intento-1"}Ventana de terminal redcumbre api reclamarRecibido --param id=<id> --cuerpo @reclamar.json --jsonResultado esperado:
201. Si el reclamo no llega al SII, el documento vuelve a su estado anterior y puedes reclamarlo de nuevo. -
Clasifica y concilia.
preclasificarRecibidoyreclasificarRecibidofijan la clasificación de IVA;guardarLineasRecibidoreemplaza las líneas de un documento que no trae XML;conciliarRecibido,conciliarLibroComprayconciliarLibroVentaconfirman a mano los montos de un documento con discrepancia, con una nota opcional. Todas responden201(la reclasificación,200). -
Sube archivos.
subirDteRecibidosube hasta 50 XML y 50 PDF de documentos recibidos (camposxmlypdf);subirXmlLibroVentasube el XML de una venta propia, uno por archivo (campoxml). Son cargas multipart:Ventana de terminal redcumbre api subirDteRecibido --archivo xml=@factura.xml --jsonredcumbre api subirXmlLibroVenta --archivo xml=@venta.xml --jsonResultado esperado:
202con los documentos encolados y los archivos omitidos con su motivo (la carga de recibidos), o el id del documento, si se creó y su estado de conciliación (la carga de ventas). Lo que cuesta un documento nuevo que entra por una carga depende de tu plan:redcumbre tarifas --produccion.
Recibir los avisos
Sección titulada «Recibir los avisos»Los cinco eventos llegan a la URL por defecto de la empresa, con el formato de Webhooks (event, tenantId, timestamp y data):
| Evento | Cuándo | Libro |
|---|---|---|
libro.sincronizado | Terminó la sincronización del libro de un RUT | Compras y ventas |
libro.sincronizacion_fallida | La sincronización falló (motivo: sii-no-disponible, otra-sincronizacion-en-curso o error-interno) | Compras y ventas |
compra.documento_recibido | Llegó un documento (canal: correo, sincronizacion o carga-xml) | Sólo compras |
compra.acuse_resuelto | Un documento quedó aceptado o reclamado (desenlace, origen, accion) | Sólo compras |
compra.acuse_fallido | El acuse falló definitivamente (causa: agotado o rechazado-por-sii) | Sólo compras |
- Llegan sin elegirlos si la lista de «Eventos habilitados» está vacía. Para dejar de recibirlos, elige una lista que no los incluya (en el panel, General → Webhooks; un agente no cambia esa configuración con una llave: pídeselo a la persona).
- Documento y acuse son sólo de compras; el libro de ventas emite sólo los dos de libro.
- La primera carga llega una sola vez. Los avisos de la primera sincronización de un RUT llevan
primeraCarga: true, y no hay forma de repetirla. Lo anterior a la activación, un RUT que entró al alcance después y lo que ocurrió antes de que existiera tu endpoint no llegan como evento: para eso usa el listado (listarDteRecibidos,listarDocumentosLibroCompras,listarDocumentosLibroVentas) y la exportación del libro. - Provócalos en prueba sin esperar:
redcumbre eventos disparar compra.documento_recibido. Resultado esperado:202con el evento, y el aviso llega a tu destino de prueba o al relay abierto.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- El RUT está al alcance: aparece en
listarReceptoresLibroCompraso enlistarEmisoresLibroVentas. - La sincronización terminó: el estado (
consultarEstadoSincronizacion…) y el historial (listarHistorialSincronizacion…) muestran la ejecución cerrada, y llegalibro.sincronizadoconnuevosycambiados. Si falla, llegalibro.sincronizacion_fallidacon elmotivo. - El acuse quedó registrado:
listarHistorialAcuseDteRecibidomuestra el desenlace del documento y llegacompra.acuse_resuelto. Si falló, llegacompra.acuse_fallido: un202anterior sólo dice que el acuse quedó encolado, no que el SII lo registró. - Estás en el modo de prueba:
sandbox: true. Nada de lo que hagas ahí cambia datos reales.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
404 con un RUT o un documento | El RUT no tiene un emisor Full DTE activo en la empresa, o el documento no existe o es de otro RUT. En prueba, tampoco es del conjunto de ejemplo | Lista primero los receptores o emisores y usa uno de esos |
400 con limit sobre el máximo | Pediste más de 300 por página | Baja limit y pagina con offset |
400 al aceptar en lote | La lista trae más de 300 documentos, y no se aceptó ninguno | Divide la lista |
400 al aceptar o reclamar | El documento ya está en proceso, o en un estado que no lo permite | Espera a que termine o lee su estado y su historial de acuse |
409 con CLAVE_USADA_CON_OTROS_DATOS | Reusaste una clave de repetición con otro contenido | Usa una clave nueva para una llamada distinta |
429 al sincronizar | Sincronizaste hace poco | Espera la hora que indica la respuesta |
| La activación de un RUT en ventas falla | El RUT no tiene credencial vigente del SII | Pídele a la persona que la renueve |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»- Aceptar y reclamar son reales ante el SII. En producción cada comando que escribe lleva
--produccion --confirmar <slug>, y lo aceptado o reclamado no se deshace. Ver Modo de prueba y producción. - Los documentos nuevos que entran por sincronización o por carga se miden al terminar su ingesta, y sólo cuentan los que son nuevos. Lo que cuesta depende de tu plan:
redcumbre tarifas --produccion. - Tu conjunto de ejemplo no pasa a producción. Los ids negativos y el receptor
76000001-9existen sólo para la llave de prueba. - No valides el formato de un id. Son identificadores opacos: en prueba llegan como texto negativo (
"-14") y en producción como texto de letras y números. Guárdalos y reenvíalos tal como llegan; una validación escrita contra el modo de prueba falla en producción. - La primera carga ocurre una vez. Decide antes de activar un RUT si descartas o procesas los avisos con
primeraCarga: true; no podrás pedirlos de nuevo.