Ir al contenido

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.

  • 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éDetalle
Llave de la empresaRol FULL-API. En el modo de prueba, la de keys/redcumbre-prueba.json.
Un RUT al alcanceLa 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 delegadoPara aceptar y reclamar: el certificado que la empresa delegó para recibir documentos.
Webhooks configuradosPara los avisos: ver Webhooks. Se configuran en el panel, no por API.

Antes de nada, averigua qué RUT tienes al alcance:

Ventana de terminal
redcumbre api listarReceptoresLibroCompras --json
redcumbre api listarEmisoresLibroVentas --json

Resultado 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.

  1. Lista y lee los documentos recibidos. Los listados paginan con limit (máximo 300) y offset (Reglas comunes):

    Ventana de terminal
    redcumbre api listarDteRecibidos --param limit=50 --param offset=0 --json
    redcumbre api obtenerDteRecibido --param id=<id> --json

    Resultado esperado: 200 con la página y los totales al nivel raíz, y luego el documento. Un id que no es del conjunto de ejemplo responde 404. Para el XML o el PDF: descargarXmlDteRecibido, descargarPdfDteRecibido y descargarArchivoDteRecibido, con --salida <archivo>.

    Cada fila trae dos ids. id es el documento en tu empresa: es el que reciben el detalle, el XML, el PDF, los archivos, aceptar y reclamar. maestroId es el documento del SII, compartido por las empresas que lo reciben: con él esas operaciones responden 404.

  2. Sincroniza con el SII. Encola una ejecución por RUT y la responde, sin esperar al SII:

    Ventana de terminal
    redcumbre api sincronizarRecibidos --json
    redcumbre api consultarEstadoSincronizacionDteRecibidos --json

    Resultado esperado: 201 con las ejecuciones encoladas, y después el estado de cada una. Una segunda sincronización pedida muy pronto responde 429 con la hora en que se permite la siguiente. Los libros tienen la suya: sincronizarLibroCompra y sincronizarLibroVenta, que aceptan periodos (formato AAAA-MM, hasta 12) y, en ventas, emisorRut:

    {
    "emisorRut": "76000001-9",
    "periodos": ["2026-10", "2026-11"]
    }
    Ventana de terminal
    redcumbre api sincronizarLibroVenta --cuerpo @sincronizar.json --json

    Un RUT fuera del alcance responde 404. Para que el libro de ventas de un RUT se sincronice solo, actívalo con activarEmisorLibroVenta (exige una credencial vigente del SII para ese RUT; pisoPeriodo marca desde cuándo carga la historia) y desactívalo con desactivarEmisorLibroVenta.

  3. Lee los libros. Cada libro tiene su resumen, su listado, su detalle, su XML y su exportación; todos piden el RUT (receptorRut en compras, emisorRut en ventas) y el período AAAA-MM:

    Ventana de terminal
    redcumbre api obtenerResumenLibroCompras --param receptorRut=76000001-9 --param periodo=2026-01 --json
    redcumbre api listarDocumentosLibroVentas --param emisorRut=76000001-9 --param periodo=2026-01 --json
    redcumbre api descargarExportacionLibroCompras --param receptorRut=76000001-9 --param periodo=2026-01 --param formato=<formato> --salida libro.csv

    Resultado esperado: 200 con el resumen del período, la página de documentos y el archivo descargado. En ventas, obtenerResumenDiarioBoletasLibroVentas da 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, y tenantRecordId, el documento en tu empresa. El detalle (obtenerDocumentoLibroCompras), el XML (descargarXmlLibroCompras) y la conciliación reciben tenantRecordId; con maestroId responden 404. Un tenantRecordId en null significa 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 el id de la fila, no el dteId.

  4. 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 --json

    Resultado esperado: 202 con 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). Sin clasificacionIva se usa la clasificación que el documento ya tenga.

  5. 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 --json

    Resultado esperado: 202 con el lote encolado; los documentos que no se pueden aceptar salen en erroresValidacion, cada uno con su motivo. Cada documento del lote queda aceptado por separado.

  6. Reclama un documento. El tipo de reclamo es RCD, RFP o RFT:

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

    Resultado esperado: 201. Si el reclamo no llega al SII, el documento vuelve a su estado anterior y puedes reclamarlo de nuevo.

  7. Clasifica y concilia. preclasificarRecibido y reclasificarRecibido fijan la clasificación de IVA; guardarLineasRecibido reemplaza las líneas de un documento que no trae XML; conciliarRecibido, conciliarLibroCompra y conciliarLibroVenta confirman a mano los montos de un documento con discrepancia, con una nota opcional. Todas responden 201 (la reclasificación, 200).

  8. Sube archivos. subirDteRecibido sube hasta 50 XML y 50 PDF de documentos recibidos (campos xml y pdf); subirXmlLibroVenta sube el XML de una venta propia, uno por archivo (campo xml). Son cargas multipart:

    Ventana de terminal
    redcumbre api subirDteRecibido --archivo xml=@factura.xml --json
    redcumbre api subirXmlLibroVenta --archivo xml=@venta.xml --json

    Resultado esperado: 202 con 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.

Los cinco eventos llegan a la URL por defecto de la empresa, con el formato de Webhooks (event, tenantId, timestamp y data):

EventoCuándoLibro
libro.sincronizadoTerminó la sincronización del libro de un RUTCompras y ventas
libro.sincronizacion_fallidaLa sincronización falló (motivo: sii-no-disponible, otra-sincronizacion-en-curso o error-interno)Compras y ventas
compra.documento_recibidoLlegó un documento (canal: correo, sincronizacion o carga-xml)Sólo compras
compra.acuse_resueltoUn documento quedó aceptado o reclamado (desenlace, origen, accion)Sólo compras
compra.acuse_fallidoEl 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: 202 con el evento, y el aviso llega a tu destino de prueba o al relay abierto.
  • El RUT está al alcance: aparece en listarReceptoresLibroCompras o en listarEmisoresLibroVentas.
  • La sincronización terminó: el estado (consultarEstadoSincronizacion…) y el historial (listarHistorialSincronizacion…) muestran la ejecución cerrada, y llega libro.sincronizado con nuevos y cambiados. Si falla, llega libro.sincronizacion_fallida con el motivo.
  • El acuse quedó registrado: listarHistorialAcuseDteRecibido muestra el desenlace del documento y llega compra.acuse_resuelto. Si falló, llega compra.acuse_fallido: un 202 anterior 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.
Si vesSignificaQué haces
404 con un RUT o un documentoEl 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 ejemploLista primero los receptores o emisores y usa uno de esos
400 con limit sobre el máximoPediste más de 300 por páginaBaja limit y pagina con offset
400 al aceptar en loteLa lista trae más de 300 documentos, y no se aceptó ningunoDivide la lista
400 al aceptar o reclamarEl documento ya está en proceso, o en un estado que no lo permiteEspera a que termine o lee su estado y su historial de acuse
409 con CLAVE_USADA_CON_OTROS_DATOSReusaste una clave de repetición con otro contenidoUsa una clave nueva para una llamada distinta
429 al sincronizarSincronizaste hace pocoEspera la hora que indica la respuesta
La activación de un RUT en ventas fallaEl RUT no tiene credencial vigente del SIIPídele a la persona que la renueve
  • 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-9 existen 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.