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.
Qué RUT alcanza tu llave
Sección titulada «Qué RUT alcanza tu llave»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).
Las 42 operaciones
Sección titulada «Las 42 operaciones»Documentos recibidos (18)
Sección titulada «Documentos recibidos (18)»| Qué quieres hacer | Operación |
|---|---|
| Ver el resumen de un período | obtenerResumenDteRecibidos |
| Listar los documentos recibidos, con filtros y paginación | listarDteRecibidos |
| Ver un documento | obtenerDteRecibido |
| Ver el historial de acuse de un documento | listarHistorialAcuseDteRecibido |
| Descargar el XML, el PDF o un archivo adjunto | descargarXmlDteRecibido, descargarPdfDteRecibido, descargarArchivoDteRecibido |
| Subir XML y PDF de documentos recibidos | subirDteRecibido |
| Sincronizar los recibidos con el SII | sincronizarRecibidos |
| Ver el estado y el historial de esa sincronización | consultarEstadoSincronizacionDteRecibidos, listarHistorialSincronizacionDteRecibidos |
| Aceptar un documento, o varios de una vez | aceptarRecibido, aceptarRecibidosMasivo |
| Reclamar un documento | reclamarRecibido |
| Clasificar el IVA de un documento | preclasificarRecibido, reclasificarRecibido |
| Guardar las líneas de un documento que no trae XML | guardarLineasRecibido |
| Conciliar a mano un documento con discrepancia | conciliarRecibido |
Libro de compras (10)
Sección titulada «Libro de compras (10)»| Qué quieres hacer | Operación |
|---|---|
| Listar los receptores con libro | listarReceptoresLibroCompras |
| Ver el resumen de un período | obtenerResumenLibroCompras |
| Listar los documentos del libro, o ver uno | listarDocumentosLibroCompras, obtenerDocumentoLibroCompras |
| Descargar el XML de un documento | descargarXmlLibroCompras |
| Descargar la exportación del período | descargarExportacionLibroCompras |
| Sincronizar el libro con el SII | sincronizarLibroCompra |
| Ver el estado y el historial de la sincronización | consultarEstadoSincronizacionLibroCompras, listarHistorialSincronizacionLibroCompras |
| Conciliar a mano un documento | conciliarLibroCompra |
Libro de ventas (14)
Sección titulada «Libro de ventas (14)»| Qué quieres hacer | Operación |
|---|---|
| Listar los RUT con libro de ventas | listarEmisoresLibroVentas |
| Activar o desactivar la sincronización de un RUT | activarEmisorLibroVenta, desactivarEmisorLibroVenta |
| Ver el resumen de un período y el desglose diario de boletas | obtenerResumenLibroVentas, obtenerResumenDiarioBoletasLibroVentas |
| Listar los documentos del libro, o ver uno | listarDocumentosLibroVentas, obtenerDocumentoLibroVentas |
| Descargar el XML de un documento | descargarXmlLibroVentas |
| Descargar la exportación del período | descargarExportacionLibroVentas |
| Sincronizar el libro con el SII | sincronizarLibroVenta |
| Cargar el XML de una venta propia | subirXmlLibroVenta |
| Ver el estado y el historial de la sincronización | consultarEstadoSincronizacionLibroVentas, listarHistorialSincronizacionLibroVentas |
| Conciliar a mano un documento | conciliarLibroVenta |
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.
Páginas de hasta 300 registros
Sección titulada «Páginas de hasta 300 registros»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 y reclamar: la clave de repetición
Sección titulada «Aceptar y reclamar: la clave de repetición»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
409con el códigoCLAVE_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.
Sincronizar con el SII
Sección titulada «Sincronizar con el SII»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
429e informa a qué hora se permite la siguiente. - Con
periodos(formatoAAAA-MM, hasta 12) pides exactamente esos meses. - En el libro de ventas,
activarEmisorLibroVentaenciende la sincronización de un RUT y carga su historia desde el período que indiques enpisoPeriodo. 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.
Eventos que recibes por webhook
Sección titulada «Eventos que recibes por webhook»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.
| Evento | Cuándo llega | Libro |
|---|---|---|
libro.sincronizado | Terminó la sincronización del libro de un RUT, con los documentos nuevos y los cambiados | Compras y ventas |
libro.sincronizacion_fallida | La sincronización falló; trae el motivo y puedes volver a intentarla | Compras y ventas |
compra.documento_recibido | Llegó un documento a tus compras | Sólo compras |
compra.acuse_resuelto | Un documento quedó aceptado o reclamado ante el SII, por tu acción o por el propio SII | Sólo compras |
compra.acuse_fallido | El acuse de un documento falló definitivamente | Só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 carga llega una sola vez
Sección titulada «La primera carga llega una sola vez»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.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
404 en un RUT o un documento | El 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 tope | Pediste más registros por página de los permitidos | Baja limit y pagina con offset |
400 al aceptar masivo | Mandaste más documentos que el tope por llamada | Divide la lista; no se aceptó ninguno |
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 |
Qué sigue
Sección titulada «Qué sigue»- Webhooks: firma, reintentos y el contenido de los cinco eventos.
- Modo de prueba: la llave de prueba y qué responde.