Ir al contenido

Compras y libros por API

Con una llave de tu empresa puedes hacer por API lo mismo que haces en las pantallas de Compras y de Libros: leer los documentos que te enviaron tus proveedores, aceptarlos o reclamarlos ante el SII, sincronizar el libro de compras y el de ventas, y descargar su exportación. Además, tu servidor se entera solo de lo que ocurre, porque la plataforma te avisa por webhook.

Son 42 operaciones. Los ejemplos de esta página usan RUT sintéticos como 76000001-9; no uses datos reales al probar.


La llave opera las compras de un receptor, y el libro de ventas de un emisor, sólo si ese RUT tiene un emisor Full DTE activo en tu empresa. La regla se mide por RUT y se evalúa en cada llamada:

  • Un RUT sin emisor Full DTE activo responde igual que uno que no existe: no aparece en los listados de receptores ni de emisores, sus documentos no aparecen y sus operaciones responden 404.
  • Que tu empresa tenga otro RUT Full DTE no basta: un RUT que factura por otro canal no entra por tener al lado uno que sí.
  • Si un emisor deja de ser Full DTE o se desactiva, su RUT sale del alcance desde ese momento. Lo que ya hiciste con la llave queda como está.

Para saber qué RUT tienes al alcance, pide primero los receptores (listarReceptoresLibroCompras) o los emisores (listarEmisoresLibroVentas).


Qué quieres hacerOperación
Ver el resumen de un períodoobtenerResumenDteRecibidos
Listar los documentos recibidos, con filtros y paginaciónlistarDteRecibidos
Ver un documentoobtenerDteRecibido
Ver el historial de acuse de un documentolistarHistorialAcuseDteRecibido
Descargar el XML, el PDF o un archivo adjuntodescargarXmlDteRecibido, descargarPdfDteRecibido, descargarArchivoDteRecibido
Subir XML y PDF de documentos recibidossubirDteRecibido
Sincronizar los recibidos con el SIIsincronizarRecibidos
Ver el estado y el historial de esa sincronizaciónconsultarEstadoSincronizacionDteRecibidos, listarHistorialSincronizacionDteRecibidos
Aceptar un documento, o varios de una vezaceptarRecibido, aceptarRecibidosMasivo
Reclamar un documentoreclamarRecibido
Clasificar el IVA de un documentopreclasificarRecibido, reclasificarRecibido
Guardar las líneas de un documento que no trae XMLguardarLineasRecibido
Conciliar a mano un documento con discrepanciaconciliarRecibido
Qué quieres hacerOperación
Listar los receptores con librolistarReceptoresLibroCompras
Ver el resumen de un períodoobtenerResumenLibroCompras
Listar los documentos del libro, o ver unolistarDocumentosLibroCompras, obtenerDocumentoLibroCompras
Descargar el XML de un documentodescargarXmlLibroCompras
Descargar la exportación del períododescargarExportacionLibroCompras
Sincronizar el libro con el SIIsincronizarLibroCompra
Ver el estado y el historial de la sincronizaciónconsultarEstadoSincronizacionLibroCompras, listarHistorialSincronizacionLibroCompras
Conciliar a mano un documentoconciliarLibroCompra
Qué quieres hacerOperación
Listar los RUT con libro de ventaslistarEmisoresLibroVentas
Activar o desactivar la sincronización de un RUTactivarEmisorLibroVenta, desactivarEmisorLibroVenta
Ver el resumen de un período y el desglose diario de boletasobtenerResumenLibroVentas, obtenerResumenDiarioBoletasLibroVentas
Listar los documentos del libro, o ver unolistarDocumentosLibroVentas, obtenerDocumentoLibroVentas
Descargar el XML de un documentodescargarXmlLibroVentas
Descargar la exportación del períododescargarExportacionLibroVentas
Sincronizar el libro con el SIIsincronizarLibroVenta
Cargar el XML de una venta propiasubirXmlLibroVenta
Ver el estado y el historial de la sincronizaciónconsultarEstadoSincronizacionLibroVentas, listarHistorialSincronizacionLibroVentas
Conciliar a mano un documentoconciliarLibroVenta

Cada operación está en la referencia de la API con sus parámetros y respuestas. Con el CLI las ejecutas con redcumbre api <operación>; las dos cargas de archivos (subirDteRecibido y subirXmlLibroVenta) usan --archivo <campo>=@ruta.


Todo listado se pagina con limit y offset. El máximo de limit es 300 registros por página: un valor mayor se rechaza con 400.

Para recorrer todo un período, avanza offset de a limit hasta que una página venga con menos registros de los pedidos. Si necesitas el período entero de una vez, usa la exportación del libro.


Aceptar (aceptarRecibido), aceptar varios (aceptarRecibidosMasivo) y reclamar (reclamarRecibido) registran un acto ante el SII. Si tu llamada se corta y la repites, no quieres que el acto se registre dos veces. Para eso, manda en el cuerpo una clave de repetición, el campo idempotencyKey (hasta 255 caracteres, la que tú elijas; un identificador único por intento de tu sistema sirve):

{
"clasificacionIva": "GIRO",
"idempotencyKey": "aceptar-factura-1042-intento-1"
}
  • Misma clave y mismo contenido: la plataforma responde lo mismo que la primera vez y no vuelve a actuar ante el SII.
  • Misma clave y otro contenido: responde 409 con el código CLAVE_USADA_CON_OTROS_DATOS.
  • La clave se recuerda al menos 24 horas, y es propia de tu empresa y del modo (la de prueba no choca con la de producción).

Manda siempre la clave en estas tres operaciones, y reutilízala sólo para reintentar la misma llamada.


Las sincronizaciones (sincronizarRecibidos, sincronizarLibroCompra, sincronizarLibroVenta) no esperan al SII: encolan una ejecución por RUT y la responden. Síguelas con las operaciones de estado y de historial, o espera el aviso por webhook.

  • Una segunda sincronización pedida muy pronto responde 429 e informa a qué hora se permite la siguiente.
  • Con periodos (formato AAAA-MM, hasta 12) pides exactamente esos meses.
  • En el libro de ventas, activarEmisorLibroVenta enciende la sincronización de un RUT y carga su historia desde el período que indiques en pisoPeriodo. Exige una credencial vigente del SII para ese RUT.
  • Cada documento recibido nuevo que entra por una sincronización o por la carga de un archivo se cobra al terminar su ingesta, sólo si es nuevo.

Cinco eventos te avisan sin que tengas que consultar. Llegan con el formato de todos los webhooks: un POST firmado con event, tenantId, timestamp y data.

EventoCuándo llegaLibro
libro.sincronizadoTerminó la sincronización del libro de un RUT, con los documentos nuevos y los cambiadosCompras y ventas
libro.sincronizacion_fallidaLa sincronización falló; trae el motivo y puedes volver a intentarlaCompras y ventas
compra.documento_recibidoLlegó un documento a tus comprasSólo compras
compra.acuse_resueltoUn documento quedó aceptado o reclamado ante el SII, por tu acción o por el propio SIISólo compras
compra.acuse_fallidoEl acuse de un documento falló definitivamenteSólo compras

Documento y acuse son sólo de compras. En ventas recibes únicamente los dos eventos de libro.

Llegan sin que los elijas. Si la lista de «Eventos habilitados» de tu URL por defecto está vacía, que significa «todos», los recibes sin hacer nada. Los avisos salen por cada empresa que tiene el RUT al alcance (la regla Full DTE de arriba), aunque no tenga una llave creada.

Para dejar de recibirlos, elige una lista: en General → Webhooks selecciona sólo los eventos que quieres. Los cinco quedan fuera de esa lista y no llegan. Si tu empresa no tiene ningún RUT al alcance, el panel ni siquiera los ofrece.

Su contenido está en Webhooks → Eventos de compras y ventas. Para provocarlos sin esperar, en el modo de prueba usa redcumbre eventos disparar <evento>.

La primera vez que se sincroniza un RUT (al activarlo, o la importación inicial de sus documentos), los eventos que salen llevan primeraCarga: true. Así decides si los consumes o los descartas, por ejemplo para no procesar de golpe años de historia.

  • Se emite una sola vez y no hay forma de repetirla. Que la primera carga termine bien la deja cerrada; una que falla no la cierra, y la siguiente vuelve a avisar hasta que una termine.
  • Una sincronización normal posterior emite normal, con primeraCarga: false, por cada documento nuevo que trae.
  • Lo anterior no llega como evento. Ni lo que ocurrió antes de la activación, ni lo de un RUT que entró al alcance después, ni lo que pasó antes de que existiera tu endpoint. Para eso usa el listado de documentos y la exportación del libro, que traen todo el período que pidas.

Si vesSignificaQué haces
404 en un RUT o un documentoEl RUT no tiene un emisor Full DTE activo en tu empresa, o el documento no existe (o es de otro RUT)Pide primero listarReceptoresLibroCompras o listarEmisoresLibroVentas
400 con limit mayor al topePediste más registros por página de los permitidosBaja limit y pagina con offset
400 al aceptar masivoMandaste más documentos que el tope por llamadaDivide la lista; no se aceptó ninguno
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

  • Webhooks: firma, reintentos y el contenido de los cinco eventos.
  • Modo de prueba: la llave de prueba y qué responde.