Saltar al contenido

MiAplicación Facturación · API

Documentación de la API

Emite documentos tributarios electrónicos contra el SII de Chile desde tu POS, tu e-commerce o tu ERP. Una sola integración para los 8 tipos de DTE, con certificado digital y CAF propios.

Introducción

Una sola implementación del protocolo del SII (Chile) para toda la organización. Tu POS, tu e-commerce o tu ERP factura llamando a esta API; nadie más vuelve a hablar con el SII por su cuenta.

DatoValor
URL basehttps://api.miaplicacion.cl
FormatoJSON (application/json), UTF-8. Los binarios (PDF, XML, Excel) salen con su propio Content-Type.
AutenticaciónCabecera X-Api-Key
Superficie215 endpoints alcanzables con una API key, en 14 áreas
La referencia por HTTPGET /api/docs la devuelve en text/markdown, sin autenticación. Es un archivo aparte que se mantiene sincronizado con esta página.
OpenAPI y PostmanGET /api/docs/openapi.json y GET /api/docs/miaplicacion.postman_collection.json, sin autenticación.
SDK y servidor MCPUn SDK de Node (@miaplicacion/sdk) y uno de Python (miaplicacion), generados desde la especificación (203 métodos en 14 grupos), y un servidor MCP (@miaplicacion/mcp) para que un asistente de IA consulte la API con tu key: solo lectura por defecto (emitir_dte existe solo si lo habilitas), transporte stdio y construido sobre el SDK de Node. Ninguno está publicado todavía en npm ni en PyPI.

Especificación y colección descargables

Descarga la especificación OpenAPI 3.1 o la colección de Postman: se generan desde el código, cubren las operaciones que alcanza una API key con su scope y marcan con x-requiere-plan: erp las del ERP. En Postman, completa las variables apiKey y empresaId.

bash
curl -O https://api.miaplicacion.cl/api/docs/openapi.json
curl -O https://api.miaplicacion.cl/api/docs/miaplicacion.postman_collection.json

Las catorce áreas

  • Identidad — GET /api/me: a qué empresa pertenece tu credencial y con qué scopes.
  • Emisión — los 8 tipos de DTE contra el SII, con el certificado digital y el CAF de la empresa.
  • Consulta y configuración — listados, exportaciones, PDF y libro de ventas.
  • Cesión de facturas — listado y detalle de las cesiones y su AEC y de las facturas recibidas en cesión y, con cesion:emitir (no viene por defecto), verificar, ceder, recibir el AEC de una factura cedida a la empresa y volver a cederla.
  • Auditoría tributaria — lectura del portal del SII: F29, RCV, renta.
  • Boletas de honorarios — las BHE recibidas y su resumen por período, y el libro de las emitidas. Solo lectura.
  • Contabilidad — plan de cuentas, asientos, libros y balance. Solo lectura.
  • Inventario — stock, kardex, lotes, series, valorizado, tomas y alertas; entradas, traslados, ajustes y mermas. Opt-in por empresa.
  • Ventas y cobranza: la configuración del módulo, las listas de precios y las cotizaciones y notas de venta, las cuentas por cobrar, los pagos recibidos y los reportes de cobranza y de ventas. Opt-in por empresa, con recordatorios de cobranza por correo y webhooks propios.
  • Compras y cuentas por pagar: la configuración del módulo, las cuentas por pagar del RCV de compras y de la 46 que emites, los pagos a proveedores con su asiento y los reportes (antigüedad, estado de cuenta de un proveedor y calendario de pagos). Opt-in por empresa y aparte de ventas.
  • Punto de venta y caja: la configuración del módulo, los puntos de venta (cajas), las sesiones de caja con su libro de movimientos y su arqueo, la venta con sus pagos y su vuelto, las ventas en espera, el escáner, la emisión de la boleta o factura de cada venta y el reporte Z de la sesión con su CSV. Opt-in por empresa.
  • Canales de venta: la configuración del módulo, los canales (tu tienda en línea o tu marketplace) con su bodega y su colchón, el catálogo de cada canal con su stock disponible, sin costos, la recepción de sus órdenes, idempotente y con el total pagado cuadrado, y la emisión de su boleta o factura sin doble emisión (sola al llegar pagada, o a pedido), su cancelación (con nota de crédito si se emitió) y sus webhooks: uno por cada cambio de estado de una orden y uno por canal con lo que cambió de su stock. Opt-in por empresa.
  • Reportes: el margen por producto, vendedor, canal o sucursal (venta neta, costo del inventario y margen, con lo sin costo conocido aparte) y el flujo de caja proyectado por semana desde las cuentas por cobrar y por pagar. Solo lectura, con contabilidad:leer.
  • Webhooks: simular un evento de prueba (estados forzables) en una empresa sandbox o con una key mk_cert_. La gestión de suscripciones sigue en el panel.

Cambios del 14-10-2026 (líneas API y ERP)

  • POST /dte acepta la cabecera opcional Idempotency-Key: con la misma clave y el mismo cuerpo recibes la misma respuesta, sin otra emisión ni otro folio. Ver Reintentos seguros.
  • Dos líneas de producto, MiAplicación API y MiAplicación ERP. Las rutas de inventario, ventas y cobranza, compras, punto de venta, canales, contabilidad, y en la auditoría el panel, el F29 y la renta, responden 403 PLAN_SIN_ERP a una empresa sin ERP. Ver MiAplicación API y ERP.
  • Los topes de puntos de venta (PLAN_LIMITE_PUNTOS_VENTA) y de canales (PLAN_LIMITE_CANALES) responden 409, como el de bodegas (TOPE_BODEGAS_PLAN); antes eran 403. Los PLAN_SIN_* de cada módulo traen requiere: "erp" y sugieren un plan ERP.
  • Crear una API key con scopes del ERP en una empresa sin ERP responde 422 SCOPES_SIN_ERP.
  • El contador lee la contabilidad y no la modifica: toda escritura le responde 403 CONTABILIDAD_SOLO_ADMIN (las de activo fijo, ACTIVO_FIJO_SOLO_ADMIN).
  • La depreciación acelerada sigue la Res. Ex. SII N°43/2002: un tercio de la vida útil normal, en años enteros (8 años → 24 meses). Ver Activo fijo.
  • La especificación OpenAPI 3.1 y la colección de Postman se descargan sin autenticación. Todas las notas con fecha están en Cambios de la API.

Cambios del 09-10-2026 (compras y cuentas por pagar)

Empieza el módulo de compras y cuentas por pagar, opt-in por empresa y separado de ventas. Por ahora trae su configuración (GET .../compras/configuracion, con compras:leer), dos scopes nuevos y el plazo de pago opcional del proveedor en el contacto (compras.plazoDias); con el módulo apagado nada cambia. Después llegaron las cuentas por pagar que salen del RCV de compras (GET .../compras/cuentas y su detalle) y el listado aparte de los documentos que no son deuda (GET .../compras/documentos-sin-cuenta), todos con compras:leer. Y ahora también la cuenta por pagar de la factura de compra 46 que emites (con las notas 56/61 que la corrigen), que se mantiene sola cada 10 minutos. Lo último: los pagos a proveedores (POST .../compras/pagos, con compras:escribir y su asiento pago_proveedor), la compensación de un saldo a favor y la cesión de una factura como deudor, marcada a mano. Y los reportes de las cuentas por pagar con compras:leer: la antigüedad, el estado de cuenta de un proveedor con sus compensaciones y el calendario de pagos por semana, además del filtro ?beneficiario= de los pagos y el historial de la cesión.

Cambios del 09-10-2026 (ventas y cobranza)

Empieza el módulo de ventas y cobranza, opt-in por empresa. Por ahora trae su configuración, cuatro scopes nuevos, las condiciones comerciales opcionales del contacto, las listas de precios por cliente (con GET .../ventas/precio, el precio neto de un ítem para un cliente) y las cotizaciones y notas de venta (sin folio ni SII, con los totales del DTE equivalente), con su PDF comercial, el envío por correo y la aceptación pública de la cotización por un enlace; con el módulo apagado nada cambia. También trae las cuentas por cobrar de solo lectura (GET .../cobranza/cuentas, con cobranza:leer): una por factura a crédito, con las notas que la corrigen; al encender el módulo se cargan solas las de lo ya aceptado. Y los pagos recibidos (cobranza:escribir): se imputan a una o más cuentas en una sola transacción con su asiento de cobro, se anulan, y el límite de crédito del cliente se revisa al confirmar una nota de venta. Y los reportes: la antigüedad de saldos y el estado de cuenta de un cliente (cobranza:leer) y las ventas por vendedor (ventas:leer).

Cambios del 08-10-2026 (inventario)

El módulo de inventario es opt-in por empresa: con él apagado, la emisión es idéntica a la de siempre. Encendido, POST /dte acepta campos nuevos, puede responder 400/409 de inventario sin consumir folio y el 201 trae un bloque inventario. Además, POST /dte lee SIEMPRE la configuración de emisión antes de validar: si no puede, responde 503 CONFIG_EMISION_NO_DISPONIBLE (antes, un payload inválido respondía 400 sin leerla).

Primera llamada

GET /api/me devuelve la identidad de tu credencial, incluido el empresaId que hay que poner en el path de todas las demás rutas. No toca el SII ni consume nada: es a la vez el descubrimiento del empresaId y la forma más barata de comprobar que tu key funciona.

bash
curl -H "X-Api-Key: $API_KEY" \
  https://api.miaplicacion.cl/api/me

Cambio incompatible del 06-10-2026

formaPago es obligatoria en las facturas 33, 34 y 46. Sin ella, POST /dte, el lote y la emisión masiva responden 400 antes de pedir el folio. Ver «Forma de pago» en Emisión de documentos.

Cambios del 07-10-2026

GET /auditoria-tributaria/:empresaId/documentos, las corridas de GET .../sync/estado (ultima, ultimaCompras y cada una de reanudables[]) y las de GET .../panel (sincronizacion.ultima y cada una de sincronizacion.reanudables[]) traen id en vez de _id, y la referencia de una nota 56/61 se valida estricta antes del folio. Ver «Auditoría tributaria» y La referencia de una nota 56/61.

7 reglas que no puedes ignorar

Estas no son notas al pie. Son las reglas que separan una integración que factura de una que quema folios.

1. El folio se consume al pedirlo, aunque el SII rechace después

Nunca reintentes una emisión sin corregir el payload

Un folio tomado del CAF se consume en el momento en que se pide, no cuando el SII acepta. Si el SII lo rechaza más tarde, ese folio ya salió del rango disponible. Un bucle de reintentos ciego vacía un CAF completo en segundos, y timbrar folios nuevos en el SII no es instantáneo.

Por eso la API valida todo el payload antes de tocar el CAF y devuelve todos los errores juntos en detalles[]. Devolverlos de a uno obligaría a reintentar N veces, y cada reintento arriesga un folio.

json
{
  "error": "Payload inválido",
  "detalles": [
    "El DTE 33 exige el giro del receptor.",
    "El DTE 33 exige la dirección del receptor.",
    "items[1]: \"precio\" debe ser un número >= 0."
  ]
}

2. Un folio rechazado vuelve al pool… salvo el código 101

Cuando el SII rechaza un documento, su folio vuelve al pool y se reutiliza antes que los nuevos: un folio rechazado es legalmente reutilizable.

Excepción: si el SII rechaza con el código 101 («Folio para este tipo de documento ya fue recibido»), ese folio no vuelve al pool. Ya está consumido del lado del SII (normalmente porque el mismo CAF se usó desde otro sistema) y devolverlo dejaría la emisión en un bucle de rechazos. El documento queda marcado con folioQuemadoEnSii: true y no se puede reemitir. Si ves esa marca, revisa quién más está usando ese CAF.

Salvo que venga además con folioAnuladoEnSii: true: es el otro motivo por el que un folio no vuelve al pool. Ese folio se anuló en el portal del SII y tampoco se puede reutilizar ni recuperar. Ahí no hay nada que revisar: se emite con un folio nuevo.

3. Boletas con precio BRUTO, todo lo demás con precio NETO

Tipoitems[].precio
39 boleta electrónicaCON IVA incluido (bruto)
41 boleta exentaCON IVA incluido (bruto)
33, 34, 46, 52, 56, 61NETO (sin IVA)

No es una convención nuestra: es como el SII define cada formato. Mezclarlos descuadra el total contra el detalle y el documento se rechaza. Si guardas los precios de tu catálogo en neto (lo recomendable), la conversión a bruto la hace quien emite, según el tipo de documento.

4. Producción o certificación: el de la empresa, o el que pida el documento

Cada empresa tiene un ambiente configurado, certificacion o produccion: es el ambiente por defecto de todo lo que emite. El payload de POST /dte (y cada documento del lote) puede pedir otro con ambiente; sin el campo, sale en el de la empresa. En producción cada documento es real, tiene efectos tributarios y solo se deshace con nota de crédito. Mientras integras, trabaja en certificacion.

Cambio del 29-09-2026: una API key mk_cert_ escribe siempre en certificación, aunque la empresa esté en producción: emite, anula y timbra en maullin, y pedir producción con ella es 403 AMBIENTE_NO_AUTORIZADO. Para emitir de verdad, usa una key mk_prod_…. GET /api/me lo muestra en apiKey.ambienteEfectivo.

Con otro ambiente, todo sale de ese ambiente: el SII, los folios (de un CAF timbrado ahí), la resolución de la carátula y el ambiente con el que queda guardado el documento. Las reglas, todas antes de pedir el folio:

  • Pedir certificacion con la empresa en producción: cualquiera que pueda emitir. Una key mk_cert_ sin ambiente emite exactamente así (con la resolución y los folios de certificación).
  • Pedir produccion con una key mk_cert_, con la empresa en cualquier ambiente: 403 AMBIENTE_NO_AUTORIZADO.
  • Pedir produccion con la empresa en certificación: solo una API key de producción (mk_prod_…) o un usuario admin/superadmin de la empresa. Si no, 403 AMBIENTE_NO_AUTORIZADO.
  • Modo demo con produccion: 422 AMBIENTE_MODO_DEMO.
  • Sin la resolución del SII de ese ambiente: 422 RESOLUCION_DEL_AMBIENTE_INVALIDA, con detalles[] que dicen cómo cargarla. Sin folios de ese ambiente, el 409 NO_FOLIOS de siempre.
  • En el lote, las mismas reglas por documento: 403 AMBIENTE_NO_AUTORIZADO o 422 LOTE_AMBIENTE_NO_DISPONIBLE, con los errores indexados.

Anular y reemitir salen en el ambiente del documento, no en el de la empresa, con las mismas reglas (una key mk_cert_ no anula un documento de producción: 403 AMBIENTE_NO_AUTORIZADO); lo que sigue cortando es el modo demo (422 CONFIG_DISTINTA_DEL_DOCUMENTO). El RCOF va por el ambiente de las boletas, solo: si en el día hubo boletas propias de los dos ambientes, se envía también el del otro, y la respuesta trae otrosAmbientes[] (ambiente, success y el resultado, o error y code si no se pudo; el de la empresa sale igual). El libro de compras y ventas del otro ambiente sale solo si lo pides con ambiente en POST /sii-emision/libros, con los parámetros de ese libro y la misma regla de autorización: un libro TOTAL cierra el período, así que nunca se envía solo. Las resoluciones van por ambiente: la del otro se carga en el panel o con resolucionCertificacion / resolucionProduccion en PUT /sii-emision (la de producción, solo un superadministrador).

Al cambiar el ambiente de la empresa las resoluciones se intercambian: la vigente queda guardada como la de su ambiente y, si el cambio no trae número ni fecha, entra la del ambiente nuevo. En ese PUT, nroResol y fchResol van los dos o ninguno (con uno solo, 400). Volver a certificación sin una resolución de certificación guardada se permite, pero queda con número 0 y sin fecha (no se inventa): hasta cargarla, emitir en certificación, el RCOF y el libro responden 422 RESOLUCION_DEL_AMBIENTE_INVALIDA antes del folio. Si lo que falta es la resolución del ambiente de la empresa y hubo boletas del otro, el RCOF responde 207: el de la empresa con su error y el del otro en otrosAmbientes[].

El ambiente de la empresa se cambia desde el panel, en Configuración › Emisión electrónica; ninguna API key puede cambiarlo. Pasar a producción lo hace un superadministrador, y solo después de que el SII apruebe el set de pruebas y la declaración de cumplimiento del contribuyente. Volver a certificación lo puede hacer también el administrador de la empresa; los documentos ya emitidos en producción no cambian.

Pasar a producción exige una resolución del SII válida en la configuración: nroResol entero mayor que 0 (el 0 es el número de certificación) y fchResol con formato AAAA-MM-DD. Sin ella, el cambio se rechaza con 422, con lo que falta en detalles[], y la empresa sigue en certificación.

La misma regla vale para una configuración que ya está en producción: si su resolución no sirve ahí (por ejemplo, nroResol 0 o sin fchResol), cualquier guardado se rechaza con el mismo 422, aunque no toque ni el ambiente ni la resolución, hasta que se corrija la resolución o se vuelva a certificación.

En certificación la resolución principal es siempre la de certificación: si un guardado escribe nroResol/fchResol o cambia el ambiente y el ambiente resultante es certificación, el nroResol tiene que ser 0; si no, se rechaza con 422 y detalles[]. La de producción se carga como resolución de producción (resolucionProduccion). Un guardado que no toca la resolución ni el ambiente no se bloquea por esta regla.

5. Tope de 60 líneas de detalle por documento

Es el tope del formato DTE del SII. Un items con 61 elementos se rechaza antes de pedir el folio, con el mismo texto en los dos caminos que emiten: Un DTE admite hasta 60 líneas de detalle (enviaste 61). El código HTTP depende del camino, porque cada uno mantiene el que ya usaba para lo suyo:

CaminoCódigo
POST /dte (y la reemisión, desde el panel)400, junto al resto de los errores de payload, dentro de detalles[]
POST /dte/:id/anular con items explícitos422, igual que los otros cortes de anular

Si una venta tiene más líneas, agrúpalas o parte el documento. Este tope es lo único que lo hace cumplir: el armador del XML no lo revisa, y un documento de 61 líneas que se saltara la validación lo rechazaría el SII con el folio ya consumido.

6. Boletas sobre 135 UF: Ley 21.713

Sobre 135 UF (estricto: exactamente 135 UF no cruza el umbral), una boleta 39 o 41 deja de ser una venta al público anónimo y el SII exige tres cosas:

  • medioPago presente: efectivo, pago_electronico, transferencia, cheque u otro.
  • El RUT real del receptor, no el genérico 66666666-6.
  • La razón social del receptor (cliente.nombre o cliente.razonSocial).

Los tres faltantes se devuelven juntos en detalles[], antes de pedir el folio. Si el valor de la UF no está disponible al emitir, la regla se omite entera: una caída del indicador no puede detener la facturación de nadie. No la uses como si fuera una garantía.

7. El XML es el documento tributario; el PDF es su representación

El documento con validez tributaria es el XML firmado, no el PDF. El contribuyente está obligado a conservarlo 6 años. Descárgalo y archívalo:

bash
curl -H "X-Api-Key: $API_KEY" \
  https://api.miaplicacion.cl/api/empresas/$EMPRESA_ID/dte/$DOC_ID/xml \
  -o DTE_33_1042.xml

Sale como application/xml; charset=ISO-8859-1. El encoding lo impone el SII: no lo conviertas a UTF-8 antes de archivarlo.

Autenticación

Toda petición autenticada lleva la cabecera X-Api-Key. No es Authorization, no es Bearer.

bash
curl -H "X-Api-Key: mk_cert_7Kq2xR9fLm3nVbT8wYzA1cD5eH0jP4sU" \
  https://api.miaplicacion.cl/api/dte/tipos

Formato de la key

texto
mk_cert_<32 caracteres base62>    ← ambiente de certificación
mk_prod_<32 caracteres base62>    ← ambiente de producción
  • 40 caracteres en total.
  • Los primeros 12 son el prefijo visible (mk_cert_7Kq2): es lo único que se puede volver a ver después de crearla.
  • El servidor guarda solo el SHA-256 de la key completa. La key en claro existe una sola vez, en la respuesta de creación. Si la pierdes, hay que revocarla y crear otra.
  • El prefijo importa: una key mk_cert_ escribe en el SII siempre en certificación (emite, anula y timbra en maullin), aunque la empresa esté en producción; pedir ambiente: "produccion" o anular un documento de producción con ella es 403 AMBIENTE_NO_AUTORIZADO. Una key mk_prod_ emite en el ambiente de la empresa y puede pedir produccion aunque la empresa esté en certificación. Cambio del 29-09-2026: antes una mk_cert_ sin ambiente emitía en el de la empresa.

Las keys se crean desde el panel (o por POST /api/empresas/:empresaId/api-keys con el JWT de un usuario admin o superadmin). La gestión de keys no es accesible con una API key: una credencial filtrada no puede fabricarse otra.

Los scopes del ERP (inventario:*, ventas:*, cobranza:*, compras:*, pos:*, canales:* y contabilidad:leer) solo se le dan a una key de una empresa con MiAplicación ERP. Pedirlos sin él responde 422 y no crea la key:

json
{
  "error": "La empresa no tiene MiAplicación ERP: esos permisos no se pueden dar.",
  "code": "SCOPES_SIN_ERP",
  "requiere": "erp",
  "plan": {
    "clave": "negocio",
    "nombre": "API Negocio"
  },
  "planSugerido": {
    "clave": "erp_pyme",
    "nombre": "ERP Pyme",
    "bodegasMax": 1
  },
  "detalles": [
    "El scope inventario:leer es de MiAplicación ERP y la empresa no lo tiene: quítalo o activa el ERP desde «Mis empresas»."
  ]
}

Al crearla, el proyecto es obligatorio: dice qué integrador emite con esa key y sale de la lista administrada de la plataforma (taller.bike, farmyx.cl, «otros clientes»…). Un proyecto que no está en la lista es 400 con detalles[]. Es lo único editable de una key: PATCH /api/empresas/:empresaId/api-keys/:keyId con { proyecto }, también solo con JWT. Cada documento emitido con la key guarda una copia de su nombre y su proyecto (origen), y GET /api/me lo devuelve en apiKey.proyecto.

Registro de peticiones

Cada petición hecha con una API key queda registrada 30 días: la key (id y prefijo), el método, la plantilla de la ruta (/api/empresas/:empresaId/dte, nunca la URL con sus datos), el status, la duración, la fecha y el X-Request-Id de la respuesta. No se guarda el cuerpo, la query ni las cabeceras. Las peticiones del panel (JWT) y las que no autentican no se registran.

Lo lee un admin de la empresa o el superadmin con GET /api/empresas/:empresaId/api-keys/peticiones. Como el resto de la gestión de keys, es solo JWT: una API key recibe 403, así que esta ruta no cuenta en la superficie de las keys.

ParámetroQué hace
desde, hastaRango ISO 8601, los dos incluidos. Sin hasta, ahora; sin desde, 24 horas antes de hasta.
apiKeyIdSolo las de una key.
statusExacto (404) o por clase (2xx, 4xx, 5xx).
limite1 a 200; 50 por defecto.
cursorEl siguienteCursor de la página anterior.
json
{
  "peticiones": [
    {
      "id": "6710f2c4e1a9b8d3c2f10a77",
      "apiKeyId": "670f9a1be1a9b8d3c2f1003c",
      "prefijo": "mk_prod_a1b2",
      "metodo": "POST",
      "ruta": "/api/empresas/:empresaId/dte",
      "status": 201,
      "duracionMs": 842,
      "fecha": "2026-10-15T14:03:11.204Z",
      "requestId": "3f1c9a52-7d0e-4b8a-9c41-2e6f0b7d5a13"
    }
  ],
  "siguienteCursor": "eyJmZWNoYSI6IjIwMjYtMTAtMTVUMTQ6MDM6MTEuMjA0WiIsImlkIjoiNjcxMGYyYzRlMWE5YjhkM2MyZjEwYTc3In0",
  "resumen": [
    { "apiKeyId": "670f9a1be1a9b8d3c2f1003c", "prefijo": "mk_prod_a1b2", "total": 1250, "errores4xx": 12, "errores5xx": 0, "p95DuracionMs": 1000 }
  ],
  "desde": "2026-10-14T14:05:00.000Z",
  "hasta": "2026-10-15T14:05:00.000Z"
}

Van de la más nueva a la más vieja; siguienteCursor es null en la última página. resumen trae una fila por key en el rango (total, 4xx, 5xx y el p95 de la duración en milisegundos, aproximado por tramos) y respeta el filtro de key, no el de status. Un parámetro inválido responde 400 con todos los motivos juntos en detalles[]; una consulta que tarda demasiado responde 503: acota el rango o filtra por key.

La regla que sorprende: el JWT siempre gana

Si llega un JWT, tu API key se ignora

Si en la misma petición viaja un JWT (en la cookie auth_token o en Authorization: Bearer …), manda el JWT y la X-Api-Key se ignora por completo, incluso si el JWT está vencido o es inválido.

No es un descuido: permitir el fallback convertiría cualquier sesión vencida en una emisión silenciosa con otro principal y otro rol. En la práctica significa que, si pruebas desde un navegador con sesión abierta en el panel, tu API key no se está usando. Integra desde tu servidor.

Errores de credencial

Usan la forma { msg }, distinta del resto de la API (ver Errores).

HTTPCuerpoCuándo
401{"msg":"No autorizado"}La petición no trae credencial: ni X-Api-Key (o viene vacía) ni JWT.
401{"msg":"API key inválida"}Prefijo inexistente, hash equivocado o key revocada. Es el mismo mensaje para los tres casos, a propósito.
401{"msg":"Autenticación por API key deshabilitada"}Kill switch API_KEYS_HABILITADAS=false: botón de pánico ante una filtración.
403{"msg":"Tu empresa está pendiente de activación.","pending":true}La empresa aún no está activa.
403{"msg":"Esta cuenta no está activa.","suspended":true}Empresa suspendida o eliminada.
403{"msg":"La empresa asociada a tu cuenta ya no existe."}La empresa fue borrada.

Alcance de una key

Una key está atada a una empresa. Todas las rutas llevan el :empresaId en el path, y si no coincide con el de la key recibes un 403. El texto (y hasta la clave donde viene) depende del módulo:

RutasCuerpo del 403
/dte (incluido el lote), /folios{ "error": "Solo puedes operar los documentos de tu propia empresa" }
/sii-emision{ "error": "Solo puedes acceder a la emisión SII de tu propia empresa" }
/contabilidad{ "error": "Solo puedes acceder a la contabilidad de tu propia empresa" }
/auditoria-tributaria{ "message": "Solo puedes acceder a la auditoría tributaria de tu propia empresa." } (con message, no con error)

Discrimina por el status, no por el texto. Un 403 puede venir por varias causas, y los campos ayudan a separar algunas, pero no todas:

  • Scope faltante: trae scopeRequerido (ver Scopes).
  • Cuenta o empresa no activa: trae msg (tabla de errores de credencial).
  • Empresa ajena (tabla de arriba), ruta cerrada a API keys o rol sin permiso (por ejemplo No tienes permisos para emitir documentos tributarios): traen solo error (o message en auditoría). Entre estos, lo único que los distingue es el texto; no construyas lógica sobre él.

Además, el principal API key tiene un rol sintético emisor: no puede tocar el certificado digital, el CAF ni el ambiente, aunque le concedas todos los scopes. Esas tres rutas son soloJwt: comprometen la identidad tributaria de la empresa y exigen un usuario humano.

El timbraje de folios sí es alcanzable, pero con el scope folios:timbrar, que se concede a mano: no sustituye la identidad tributaria de la empresa (usa el certificado que ya está cargado) y es lo que desatasca al integrador que se quedó sin folios. Ver Quedarse sin folios.

Cuál es tu empresaId: GET /api/me

Es la primera llamada que conviene hacer. Devuelve la identidad de la credencial que llama, incluido el empresaId que hay que poner en el path de todas las demás rutas, así que no hace falta que nadie te lo dicte por correo ni sacarlo de las peticiones de red del panel.

bash
curl -H "X-Api-Key: mk_cert_XXXX" https://api.miaplicacion.cl/api/me
json
{
  "tipo": "apikey",
  "empresa": {
    "id": "66e0000000000000000000a1",
    "rut": "76543210-K",
    "razonSocial": "Integraciones del Sur SpA",
    "estado": "vigente",
    "ambiente": "certificacion"
  },
  "apiKey": {
    "id": "66e0000000000000000000b7",
    "nombre": "POS caja 2",
    "prefijo": "mk_cert_9F2A",
    "ambiente": "certificacion",
    "proyecto": "taller.bike",
    "scopes": ["dte:emitir", "dte:leer", "folios:leer"],
    "activa": true,
    "ultimoUso": "2026-09-04T13:22:10.418Z",
    "creadaEn": "2026-08-01T18:03:44.002Z",
    "revocadaEn": null,
    "expiraEn": null,
    "ambienteEfectivo": "certificacion"
  }
}
  • empresa.id es exactamente el :empresaId que esperan las demás rutas.
  • apiKey.prefijo son los 12 primeros caracteres de la key, nunca la key completa: sirve para saber cuál de las credenciales del cliente tienes configurada sin que la respuesta filtre nada. El servidor solo guarda el SHA-256 y no puede reconstruirla ni aunque quisiera.
  • apiKey.scopes son los permisos que se están evaluando en esta misma petición. Si un 403 te dice que falta un scope, compáralo con esta lista.
  • empresa.ambiente y apiKey.ambiente pueden no coincidir: el prefijo mk_cert_ / mk_prod_ se congela al crear la key y no se reescribe cuando la empresa pasa a producción.
  • apiKey.ambienteEfectivo es el ambiente en el que escribe tu key cuando el payload no trae ambiente: una mk_cert_, siempre certificacion (aunque empresa.ambiente diga produccion); una mk_prod_, el de la empresa. No considera el modo demo, que además fuerza certificación.
  • apiKey.expiraEn es la fecha en que la key deja de funcionar, o null si no vence. Hoy solo vencen las keys de la cuenta demo de prueba (7 días desde su creación). Una key vencida responde el mismo 401 que una inexistente.

Requiere el scope dte:leer, que viene por defecto en toda key nueva. Con un JWT de usuario devuelve otra cosa ({"tipo":"usuario","usuario":{…},"empresa":{…},"empresas":[…]}), la misma forma que GET /api/auth/yo. empresas[] son todas las empresas a las que entra ese usuario (la suya por defecto y las de sus membresías), cada una con id, rut, razonSocial, estado, plan, integracionSii, cuentaDemo, su rol en ella y titular (true si es quien la paga); para el superadmin, []. Con una API key la respuesta no cambia: la key es de una sola empresa. Las rutas /api/cuenta/* (agregar empresas, pagarlas y ver la suscripción) son del panel: solo JWT, inalcanzables con una API key.

MiAplicación API y ERP

Desde el 14-10-2026 hay dos líneas de producto, cada una con sus planes. El catálogo público (GET /api/publico/planes, sin autenticación) trae lineas[] y, en cada plan, su linea (api o erp).

LíneaPara quiénQué incluye
MiAplicación API (api)Quien ya tiene su sistema (POS, e-commerce, ERP propio) y solo necesita hablar con el SII.Emisión de los 8 DTE, lote, anular, reenviar por correo, PDF y XML y estado en el SII; folios y timbraje; RCOF y libros; webhooks; lectura del RCV, de las BHE y de las cesiones; el panel de facturación.
MiAplicación ERP (erp)Pymes.Todo lo de la API, más inventario, ventas y cobranza, compras y cuentas por pagar, punto de venta y caja, canales de venta, contabilidad (con activo fijo), la auditoría tributaria (panel, F29 y renta) y aceptar o reclamar documentos recibidos.

Lo que hoy responde 501 en producción (la cesión de facturas, aceptar o reclamar en el SII y la emisión de BHE) no se ofrece como disponible hasta habilitarlo.

Planes de MiAplicación ERP

CLP + IVA al mes; null en el catálogo es sin tope. Los planes de la API (emprende, negocio, crecimiento, alto_volumen y corporativo) traen 0 bodegas, 0 puntos de venta y 0 canales: esos módulos son del ERP.

Plan (clave)PrecioDTE/mesUsuariosBodegasPuntos de ventaCanalesCesiones/mes
ERP Pyme (erp_pyme)$39.9901.000101110
ERP Negocio (erp_negocio)$69.9903.0002533320
ERP Full (erp_full)$99.99010.00050101010100
ERP Corporativo (erp_corporativo)A convenirSin topeSin topeSin topeSin topeSin topeSin tope

Sandbox gratis

Para integrar sin pagar ni tener certificado: $0, sin límite de tiempo, solo certificación. El catálogo público lo trae en su propia clave (GET /api/publico/planes → sandbox), fuera de planes: no se contrata, no se cotiza (POST /api/publico/cotizar con plan: "sandbox" responde 400) ni se paga. Se pide al registrarse, con contratacion: { plan: "sandbox" } en POST /api/auth/registro (sin meses ni certificaciones). La respuesta 201 suma sandbox con la key mk_cert_ en claro, una sola vez:

json
{
  "sandbox": {
    "soloCertificacion": true,
    "emisionesPorDia": 50,
    "apiKey": { "id": "6a0f…", "nombre": "Sandbox", "prefijo": "mk_cert_Ab3x", "key": "mk_cert_…",
                "ambiente": "certificacion", "scopes": ["dte:emitir", "dte:leer", "dte:anular", "folios:leer"], "proyecto": "sandbox" },
    "aviso": "Guarda esta API key ahora: es la única vez que se muestra. …"
  }
}
  • La empresa queda vigente de inmediato, sin pago, en modo demo: emite con el certificado, el CAF y el RUT del emisor de pruebas de la plataforma, siempre en certificación. Nunca produce un documento real a nombre de tu RUT.
  • Nunca producción mientras no contrates un plan: PUT .../sii-emision con otro ambiente o con modoDemo distinto de true responde 403 SANDBOX_SOLO_CERTIFICACION; la key es mk_cert_ (pedir ambiente: "produccion" → 403 AMBIENTE_NO_AUTORIZADO).
  • Tope diario: 50 documentos por empresa y día de Chile (POST /dte, anular, lote y reemitir). La unidad se reserva antes de emitir, de forma atómica; si la respuesta sale antes del folio (400, 401, 403, 404, 409, 413, 415 o 429) vuelve. Pasado, 429 SANDBOX_TOPE_DIARIO antes de pedir el folio. La emisión masiva por archivo no existe en el sandbox.
  • Tope de altas: 3 sandbox por conexión y 1 por correo en 24 horas, sin +etiqueta y, en Gmail, sin puntos (429 SANDBOX_LIMITE_REGISTROS). Sin emisor de pruebas disponible, 503 SANDBOX_NO_DISPONIBLE.
  • Eventos de webhooks forzables: Simular eventos. Al confirmarse el pago de un plan, la empresa deja de ser sandbox y conserva sus datos; la plataforma no le asigna un plan sin pago (409 SANDBOX_REQUIERE_CONTRATACION).

Programa Aliados (precio de integrador y de contador)

Si administras varias empresas como su titular (quien las agrega y las paga), el plan de cada una tiene un descuento según cuántas de tus empresas están activas, en las dos líneas. El catálogo público lo publica en programaAliados.tramos[].

Tramo (clave)Empresas activasDescuento sobre el plan
Aliado (aliado)3 o más20 %
Aliado Pro (aliado_pro)10 o más35 %
Aliado Elite (aliado_elite)50 o más60 %
  • Cuentan tus empresas vigente con un plan pagado que las cubre hoy; no cuentan las pendientes, suspendidas o eliminadas, las vencidas, las cuentas demo ni el emisor demo. La empresa que contratas cuenta si es tuya: con 2 activas, la tercera ya contrata como Aliado.
  • Va sobre el precio mensual del plan; no aplica a Corporativo, a las certificaciones ni a los DTE adicionales.
  • No se acumula con el descuento por pago adelantado: se aplica el mayor. Con un tramo, la cotización trae porcentajePrepago, aliado y descuentoAplicado: { origen, porcentaje, motivo }.
  • Se evalúa al contratar, renovar o cambiar de plan. Lo que ya pagaste no se recalcula. El servidor siempre cuenta: un tramo en el cuerpo se ignora, y POST /api/publico/cotizar nunca aplica un tramo.

La compuerta del ERP

Toda ruta de inventario, ventas y cobranza, compras, punto de venta, canales y contabilidad, y en la auditoría tributaria GET /panel, GET /auditoria (F29), GET /renta y todo lo de aceptar o reclamar con sus reglas, pasa por una compuerta que mira el plan de la empresa:

  • Con ERP, pasa. Una contratación ERP vencida sigue contando (nada suspende solo): lo que se frena es encender un módulo y crear o reactivar bodegas, cajas o canales (el PLAN_SIN_* de cada módulo).
  • Sin ERP, responde 403 PLAN_SIN_ERP sin hacer nada más. plan es el de la empresa (null si no tiene ninguno) y planSugerido, el ERP de entrada (con su tope de bodegas del catálogo en bodegasMax).
  • Sin ERP, pero con datos del ERP (la empresa bajó a un plan de la API): los datos nunca se borran y quedan en solo lectura. GET y HEAD siguen respondiendo; una escritura recibe el mismo 403 con soloLectura: true.
  • Si el plan no se puede leer, 503 ACCESO_NO_VERIFICADO: nunca pasa sin revisarlo. Reintenta.
  • Con el :empresaId de otra empresa responde el 403 de siempre del módulo: la compuerta no revela el plan de nadie.
json
{
  "error": "Esta es una función de MiAplicación ERP y el plan API Negocio de la empresa no la incluye. Actívalo desde «Mis empresas», con el plan ERP Pyme o uno superior.",
  "code": "PLAN_SIN_ERP",
  "requiere": "erp",
  "plan": {
    "clave": "negocio",
    "nombre": "API Negocio"
  },
  "planSugerido": {
    "clave": "erp_pyme",
    "nombre": "ERP Pyme",
    "bodegasMax": 1
  },
  "soloLectura": false
}

Distingue por code, no por el texto. En la especificación OpenAPI (GET /api/docs/openapi.json) cada operación del ERP lleva x-requiere-plan: erp.

La emisión sin ERP

Si una empresa sin ERP dejó un módulo encendido (bajó de plan), la emisión se comporta como con el módulo apagado: no mueve stock ni crea cuentas por cobrar o por pagar. Anular un documento que sí movió stock lo revierte igual. Si el plan no se puede leer al emitir, la emisión responde 503 antes de pedir el folio.

Permisos por área (solo usuarios con sesión). Un administrador puede restringir a un usuario emisor o contador a ciertas áreas del ERP: ventas, cobranza, compras, inventario, pos, canales, ordenes_trabajo, contabilidad y reportes. Las API keys no se ven afectadas: las siguen gobernando sus scopes. Si un usuario con sesión pide una ruta del ERP fuera de sus áreas, la API responde 403:

json
{
  "error": "No tienes acceso al área Inventario en esta empresa. Pídele a un administrador que te la habilite.",
  "code": "AREA_NO_PERMITIDA",
  "area": "inventario"
}

Si el acceso no se pudo verificar, 503 ACCESO_NO_VERIFICADO: reintenta. Un administrador, el titular y el superadmin nunca se restringen. En la auditoría tributaria, aceptar o reclamar facturas recibidas (POST .../documentos/accion y .../reclamo/*) es del área compras; el panel, la auditoría y la renta, de contabilidad. Leer la configuración de ventas (GET .../ventas/configuracion) acepta ventas o cobranza, porque el módulo es uno solo; escribirla exige ventas. Si a una ruta que acepta varias áreas le faltan todas, el 403 trae además areas: [...]. La emisión (POST /dte), los clientes y productos, BHE, cesión y sii-emision siguen solo por rol.

Sucursales (solo usuarios con sesión). Un administrador puede asignar a un usuario emisor o contador a una o más sucursales. Las API keys no se restringen por sucursal. Un usuario del panel asignado a sucursales recibe, antes de pedir el folio, 403 SUCURSAL_NO_PERMITIDA si emite (o anula, reemite u opera una caja) en una sucursal que no es suya, y 422 SUCURSAL_REQUERIDA si tiene varias y el documento no trae sucursalId. Sus listados y reportes solo muestran sus sucursales.

Scopes

Veinticuatro permisos. Una key solo alcanza las rutas cuyo scope tiene concedido.

ScopeQué abre
dte:emitirEmitir cualquiera de los 8 tipos, uno a uno (POST /dte), por lote (POST /dte/lote) o por archivo (la vista previa y la emisión de la emisión masiva por archivo).
dte:leerIdentidad de la propia credencial (GET /api/me), catálogo de tipos, listados, consulta por folio, estado, XML, PDF, exportaciones y libro de ventas; los lotes y, de la emisión masiva por archivo, la plantilla, el avance y el resultado.
dte:anularEmitir la nota que anula un documento (nota de crédito 61, o nota de débito 56 si el documento es una nota de crédito).
dte:enviar_correoReenviar por correo un documento ya emitido.
folios:leerDisponibilidad de folios por tipo, y lo que el SII ofrece timbrar (timbraje/disponibilidad).
folios:timbrarPOST /sii-emision/timbraje: pedirle folios al SII a nombre del contribuyente. No viene por defecto.
config:leerLectura de la configuración de emisión.
sii:leerLecturas de lo ya sincronizado en nuestra base: panel, F29, RCV, renta, estado del sync. No hablan con el SII.
sii:consultar_en_lineaLas 3 consultas por documento que sí abren conexión EN VIVO al web service del SII (eventos, cedible, plazo).
contabilidad:leerPlan de cuentas, asientos, 5 libros, períodos, reglas, activos fijos, banco y cierre, y los reportes de margen y flujo de caja. Solo los GET.
bhe:leerEl libro de boletas de honorarios emitidas por la plataforma (GET .../bhe/emitidas y su detalle). No habla con el SII.
inventario:leerLas lecturas del inventario (GET .../inventario/*): configuración, bodegas, variantes, stock, kardex, lotes, series, valorizado, fotos, operaciones, tomas y alertas. Incluye costos.
inventario:escribirLas cinco operaciones manuales que mueven stock: entradas, traslados, ajustes, mermas y consumos; y la producción: recetas y órdenes de producción (crear, confirmar y anular). El resto de las escrituras del inventario son solo con sesión.
ventas:leerLas lecturas de ventas y cobranza (GET .../ventas/*): la configuración del módulo, las listas de precios con sus precios y el precio de un ítem para un cliente, y las cotizaciones y notas de venta (también su PDF).
ventas:escribirCrear, editar y desactivar listas de precios y cargar o quitar sus precios; crear, editar, cambiar de estado, convertir y mandar por correo cotizaciones y notas de venta. Configurar el módulo sigue siendo solo con sesión.
cobranza:leerLas cuentas por cobrar (GET .../cobranza/cuentas y su detalle), los pagos recibidos (GET .../cobranza/pagos y su detalle), la antigüedad de saldos (GET .../cobranza/antiguedad), el estado de cuenta de un cliente (GET .../cobranza/estado-cuenta) y el registro de los recordatorios de cobranza (GET .../cobranza/recordatorios).
cobranza:escribirRegistrar y anular pagos recibidos (POST .../cobranza/pagos y POST .../cobranza/pagos/:pagoId/anular), con su asiento de cobro.
compras:leerLas lecturas de compras y cuentas por pagar (GET .../compras/*): la configuración del módulo, las cuentas por pagar y su detalle, los documentos del RCV sin cuenta, los pagos a proveedores y su detalle, y los reportes (antigüedad, estado de cuenta de un proveedor y calendario de pagos).
compras:escribirRegistrar y anular pagos a proveedores (POST .../compras/pagos y .../pagos/:pagoId/anular), con su asiento de pago. Configurar el módulo, compensar un saldo a favor y marcar una cesión siguen siendo solo con sesión.
pos:leerLas lecturas del punto de venta (GET .../pos/*): la configuración del módulo, los puntos de venta (cajas), las sesiones de caja con su esperado y su resumen, y el libro de movimientos.
pos:escribirOperar la caja como un emisor: abrir una sesión de caja, registrar un ingreso, retiro o gasto, registrar y emitir ventas (emitir exige además dte:emitir) y cerrarla con el arqueo. Configurar el módulo, crear o editar puntos de venta y anular un movimiento siguen siendo solo con sesión.
canales:leerLas lecturas de los canales de venta (GET .../canales/*): la configuración del módulo, los canales, el catálogo de cada canal con su stock disponible (GET .../canales/:canalId/catalogo) y las órdenes (GET .../canales/ordenes y GET .../canales/:canalId/ordenes/:ordenId).
canales:escribirEl permiso del integrador de un canal: enviar sus órdenes (POST .../canales/:canalId/ordenes), confirmar su pago (POST .../ordenes/:ordenId/pagar), emitir su boleta o factura (POST .../ordenes/:ordenId/emitir; la emisión automática también corre con este scope) y cancelarlas (POST .../ordenes/:ordenId/cancelar, con su nota de crédito si se emitieron). Configurar el módulo, crear o editar canales y resolver una emisión o una cancelación en revisión siguen siendo solo con sesión.
cesion:emitirCeder una factura a un factoring: el precheck (GET .../cesiones/precheck/:emitidaId, que consulta al SII con el certificado de la empresa) y ceder (POST .../cesiones), aceptando la declaración jurada en nombre de la empresa. También recibir el AEC de una factura cedida a la empresa (POST .../cesiones/recibidas) y el precheck para volver a cederla (GET .../cesiones/recibidas/:tenenciaId/precheck). Los dos prechecks tienen además un cupo propio de 30 por hora por empresa (ver Cesión de facturas). Una key mk_cert_ solo cede en certificación. No viene por defecto.

Los que trae una key nueva

Por defecto, una key recién creada trae solo tres: dte:emitir dte:leer folios:leer

Los scopes inventario:*, ventas:*, cobranza:*, compras:*, pos:*, canales:* y contabilidad:leer son de MiAplicación ERP: una key de una empresa sin ERP no los puede tener (422 SCOPES_SIN_ERP al crearla) y sus rutas responden 403 PLAN_SIN_ERP. sii:leer es de la API, pero tres de sus rutas (GET /panel, GET /auditoria y GET /renta de la auditoría) son del ERP.

Todo lo demás se concede a propósito, y hay motivos concretos:

  • dte:enviar_correo deja al llamador elegir el destinatario. Una key filtrada con ese permiso puede mandarse los documentos de la empresa a su propio correo.
  • sii:leer, sii:consultar_en_linea y contabilidad:leer: una key se crea para facturar, no para leerle la contabilidad ni la auditoría a la empresa. Es la diferencia entre «el POS se filtró» y «el POS se filtró y con él el balance del cliente».
  • inventario:leer e inventario:escribir: el inventario es opt-in y una key que factura no lo necesita. El primero muestra costos y valorizado; el segundo cambia el stock sin un documento tributario.
  • ventas:* y cobranza:*: ventas y cobranza también es opt-in, y precios, clientes y deudas son información comercial. Hoy ventas:leer abre la configuración, las listas de precios, el precio por cliente y las cotizaciones y notas de venta, y ventas:escribir mantiene las listas y los documentos; cobranza:leer abre las cuentas por cobrar y los pagos recibidos, y cobranza:escribir registra y anula pagos (y con ellos, asientos de cobro en la contabilidad de la empresa).
  • compras:*: compras y cuentas por pagar es opt-in y separado de ventas; proveedores, costos y deudas con ellos son información comercial. Hoy compras:leer abre la configuración del módulo, las cuentas por pagar, los documentos del RCV sin cuenta, los pagos a proveedores y los reportes de cuentas por pagar, y compras:escribir registra y anula pagos a proveedores (y con ellos, asientos de pago en la contabilidad de la empresa).
  • pos:*: el punto de venta es opt-in por empresa, y una key que factura no necesita ver ni operar las cajas. Hoy pos:leer abre la configuración del módulo, los puntos de venta y las sesiones de caja con su libro, y pos:escribir abre y cierra sesiones, registra ingresos, retiros y gastos, y registra ventas; emitir la boleta o factura de una venta pide además dte:emitir.
  • canales:*: los canales de venta son opt-in por empresa, y una key que solo factura no necesita verlos.canales:leer abre la configuración del módulo, los canales, el catálogo de cada canal y sus órdenes, y canales:escribir abre solo las órdenes: enviarlas, confirmar su pago, emitir su boleta o factura y cancelarlas, con su nota de crédito si se emitieron (sin pedir además dte:emitir ni dte:anular).
  • sii:consultar_en_linea va separado porque cuesta latencia, cuesta cuota del SII y un tercero con la key podría provocarle bloqueos a la cuenta del cliente en el portal.
  • folios:timbrar escribe fuera de nuestra infraestructura, igual que cesion:emitir (abajo): entra al portal del SII con el certificado digital de tu empresa y pide folios a nombre del contribuyente. Cada timbraje consume cuota del SII y el rango queda asignado a tu RUT: no se devuelve. Consultar qué se puede pedir (folios:leer) sí viene por defecto; pedirlo, no.
  • cesion:emitir: ceder una factura le transfiere su crédito a un tercero (un factoring) en el registro de cesiones del SII, firmando con el certificado digital de tu empresa, y quien cede acepta la declaración jurada en nombre de la empresa. Leer las cesiones sigue siendo dte:leer.

403 por scope faltante

El error nombra el scope que falta, para que puedas arreglarlo sin abrir un ticket:

json
{
  "error": "Esta API key no tiene el scope requerido: dte:emitir",
  "scopeRequerido": "dte:emitir"
}

El chequeo de scope corre antes de cualquier limitador de tasa: una key sin permiso recibe su 403 sin gastarle cuota de emisión a la empresa.

Y hay rutas que exigen un usuario humano, sin scope que las habilite (certificado, CAF, ambiente, gestión de keys y de webhooks, todas las escrituras contables y de auditoría). Responden: {"error":"Esta operación no está disponible para una API key: requiere un usuario autenticado"}

Emisión de documentos

Un solo endpoint emite cualquiera de los 8 tipos (y, en un servidor con la exportación habilitada, los documentos de exportación 110, 111 y 112: ver Documentos de exportación). Las boletas (39/41) viajan por el canal REST del SII y el resto por el canal de upload: son dos protocolos distintos. La API rutea internamente; tú solo mandas { tipo }.

http
POST /api/empresas/:empresaId/dte

Scope: dte:emitir

Ejemplo completo: petición y respuesta

Una factura 33 con una línea afecta y una exenta, receptor completo y los campos opcionales que más se usan. Los precios van netos. Va con "ambiente": "certificacion": sin el campo, sale en el ambiente de la empresa (y con una key mk_cert_, siempre en certificación). Ojo si copias el ejemplo con un JWT o una key mk_prod_ y la empresa está en producción: pedir certificación exige su resolución cargada; sin ella responde 422 RESOLUCION_DEL_AMBIENTE_INVALIDA. Para emitir en el ambiente de la empresa, quita el campo.

POST /api/empresas/:empresaId/dte · factura 33

json
{
  "tipo": 33,
  "fecha": "2026-10-02",
  "cliente": {
    "rut": "76123456-0",
    "razonSocial": "COMERCIAL LOS ALERCES SPA",
    "giro": "Venta al por menor de artículos de ferretería",
    "direccion": "Av. Providencia 1234, of. 502",
    "comuna": "Providencia",
    "ciudad": "Santiago"
  },
  "items": [
    {
      "nombre": "Servicio de mantención mensual",
      "descripcion": "Mantención preventiva de equipos, octubre 2026",
      "cantidad": 2,
      "precio": 45000,
      "descuento": 5000
    },
    {
      "nombre": "Arriendo de bodega",
      "descripcion": "Inmueble sin amoblar, octubre 2026",
      "cantidad": 1,
      "precio": 120000,
      "exento": true
    }
  ],
  "formaPago": 2,
  "fechaVencimiento": "2026-11-01",
  "medioPago": "transferencia",
  "ventaId": "V-2026-000123",
  "pagoId": "P-88412",
  "ambiente": "certificacion"
}
json
{
  "success": true,
  "folio": 1042,
  "tipoDTE": 33,
  "fechaEmision": "2026-10-02",
  "total": 221150,
  "rutEmisor": "78287987-1",
  "rutReceptor": "76123456-0",
  "trackid": "1234567890",
  "emitidaId": "66f0a1b2c3d4e5f607182930",
  "emisorDirectoSii": true,
  "message": "DTE 33 folio 1042 enviado al SII (trackid 1234567890)",
  "rawResponse": "<RECEPCIONDTE>…<STATUS>0</STATUS><TRACKID>1234567890</TRACKID></RECEPCIONDTE>"
}
  • Los montos. La línea afecta da 2 × 45.000 − 5.000 = 85.000 neto, con IVA de 16.150 (19 % redondeado al peso); la exenta, 120.000. El total es 85.000 + 16.150 + 120.000 = 221150. El 201 trae solo el total: el desglose (MntNeto, IVA, MntExe) está en el XML firmado y en el listado.
  • trackid es un string y emitidaId es el id del documento guardado: con él se consulta el estado (GET /dte/:id/estado) y se anula.
  • ventaId y pagoId no vuelven en el 201: quedan guardados en el documento (ver la fila ventaId / pagoId del cuerpo).
  • avisos aparece solo si hay algo que avisar (hoy, el logo por URL); rawResponse es la respuesta cruda del SII y no es contrato: en el canal de upload es el texto XML del acuse.
  • El 409 no consumió ningún folio: se timbra y se reintenta. Si los folios que quedan son de un CAF caducado, el mismo 409 llega con "errorType": "CAF_VENCIDO". Ver Quedarse sin folios.

Un payload con varios errores se rechaza con 400 y todos los errores juntos en detalles[], antes de pedir el folio. Los mensajes son los literales de la API:

El mismo POST, con siete errores

json
{
  "tipo": 33,
  "cliente": {
    "rut": "76123456-1",
    "razonSocial": "COMERCIAL LOS ALERCES SPA",
    "direccion": "Av. Providencia 1234, of. 502",
    "comuna": "Providencia"
  },
  "items": [
    {
      "nombre": "Servicio de mantención mensual",
      "cantidad": 2,
      "precio": -45000
    },
    {
      "nombre": "Arriendo de bodega",
      "cantidad": 1,
      "precio": 120000,
      "exento": "si"
    }
  ],
  "formaPago": 5,
  "ventaId": true,
  "ambiente": "prod"
}
json
{
  "error": "Payload inválido",
  "detalles": [
    "RUT de receptor inválido: \"76123456-1\".",
    "El DTE 33 exige el giro del receptor.",
    "items[0]: \"precio\" debe ser un número >= 0.",
    "items[1]: \"exento\" debe ser true o false (llegó \"si\").",
    "formaPago debe ser 1 (contado), 2 (crédito) o 3 (sin costo).",
    "ventaId debe ser texto o número (llegó true).",
    "ambiente debe ser \"certificacion\" o \"produccion\" (llegó \"prod\"). Sin el campo, el documento sale en el ambiente configurado para la empresa."
  ]
}

La boleta 39 viaja por el canal REST, con precio bruto y sin receptor obligatorio:

POST /api/empresas/:empresaId/dte · boleta 39

json
{
  "tipo": 39,
  "items": [
    {
      "nombre": "Cambio de aceite",
      "cantidad": 1,
      "precio": 35000
    },
    {
      "nombre": "Filtro de aire",
      "cantidad": 2,
      "precio": 8990
    }
  ],
  "medioPago": "efectivo",
  "ventaId": "POS-3-000871"
}
json
{
  "success": true,
  "folio": 5310,
  "tipoDTE": 39,
  "fechaEmision": "2026-10-02",
  "total": 52980,
  "rutEmisor": "78287987-1",
  "rutReceptor": "66666666-6",
  "trackid": "4818203",
  "emitidaId": "66f0a1b2c3d4e5f607182931",
  "emisorDirectoSii": true,
  "message": "Boleta electrónica 5310 enviada al SII (trackid 4818203)",
  "rawResponse": {
    "rut_emisor": "78287987-1",
    "trackid": 4818203,
    "fecha_recepcion": "2026-10-02 13:05:41",
    "estado": "REC",
    "file": "EnvioBOLETA_78287987_1_1790957141000.xml"
  }
}

El 201 tiene la misma forma que el de la factura. Cambian tres cosas: rutReceptor es 66666666-6 (consumidor final) cuando no mandas cliente, el message dice «Boleta electrónica…» y rawResponse es el JSON del canal REST (su trackid viene como número; el tuyo, el de arriba, siempre como string). Los 52.980 del total incluyen el IVA: 44.521 neto + 8.459 IVA.

Los 8 tipos

CódigoNombreCanalReceptorReferenciaPrecioitems[].exento
33Factura electrónicauploadobligatorio + giro/dirección/comunaopcional (hasta 40)netosí
34Factura no afecta o exentauploadobligatorio + giro/dirección/comunaopcional (hasta 40)netoredundante
39Boleta electrónicaRESTopcionalno admitebrutosí
41Boleta exenta electrónicaRESTopcionalno admitebrutoredundante
46Factura de comprauploadobligatorio + giro/dirección/comunaopcional (hasta 40)netorechazado
52Guía de despachouploadobligatorio + giro/dirección/comunaopcional (hasta 40)netosí
56Nota de débitouploadobligatorio (solo identificación)obligatorianetosí
61Nota de créditouploadobligatorio (solo identificación)obligatorianetosí

Las notas (56/61) identifican al receptor pero no exigen giro, dirección ni comuna: heredan esos datos del documento referenciado.

La columna Referencia es el campo referencia: en 33/34/46/52 cita otros documentos (la guía, la orden de compra, la HES), en 56/61 es el documento que la nota corrige y la boleta no la admite. Ver Referencias a otros documentos.

Los documentos de exportación (110 factura, 111 nota de débito y 112 nota de crédito de exportación) no están en la tabla: existen solo donde el servidor los habilita (SII_EXPORTACION_HABILITADA=true). Entonces GET /dte/tipos los lista con exportacion: true (también en tiposUpload); si no, no aparecen y POST /dte los rechaza como cualquier tipo no soportado. Ver Documentos de exportación.

La última columna es el campo lineasExentas del catálogo, y no es lo mismo que exento. La respuesta de GET /api/dte/tipos trae los dos:

json
{
  "tipos": [
    { "codigo": 34, "nombre": "Factura no afecta o exenta electrónica", "canal": "upload",
      "exento": true,  "lineasExentas": false, "requiereReceptor": true, "admiteReferencias": true },
    { "codigo": 61, "nombre": "Nota de crédito electrónica", "canal": "upload",
      "exento": false, "lineasExentas": true,  "requiereReceptor": true, "admiteReferencias": true,
      "requiereReferencia": true }
  ],
  "tiposUpload": [33, 34, 46, 52, 56, 61]
}
CampoSignifica
exentoEl TIPO es exento por definición: 34 y 41. No depende del contenido; todo lo que se emita con ese tipo va sin IVA.
lineasExentasEl tipo acepta items[].exento para marcar líneas sueltas con IndExe=1.
admiteReferenciasEl tipo acepta referencia (<Referencia> en el XML): opcional y hasta 40 en 33/34/46/52, obligatoria en 56/61 (que además traen requiereReferencia: true). false en 39/41: esta API no acepta referencia en boletas.

La diferencia es sutil y se presta a confusión

Una nota de crédito (61) que anula una boleta exenta sale exenta, pero exento sigue siendo false para el 61: el mismo 61 anula una factura afecta al día siguiente. Lo exento es el documento concreto, no el tipo. Mentir en exento habría roto a quien lo lee como «este tipo nunca lleva IVA».

Y al revés: en 34 y 41 lineasExentas es false porque el documento entero ya es exento y marcar una línea no agrega nada. Mandar exento: true ahí es redundante, no un error.

Cuerpo de la petición

CampoObligatorioNotas
tiposí33, 34, 39, 41, 46, 52, 56 o 61. 110, 111 o 112 solo con la exportación habilitada: ver Documentos de exportación.
itemssíDe 1 a 60 elementos.
items[].nombresí
items[].descripcionnoTexto bajo el nombre de la línea (DscItem en el XML), en todos los tipos. Se recorta a 1000 caracteres.
items[].preciosí (salvo con lista)≥ 0. Bruto en 39/41, neto en el resto. Con ventas encendido, una línea con itemId y sin precio toma el de la lista del receptor (ver Ventas y cobranza); un precio que mandas gana siempre.
items[].cantidadnoAusente = 1. Debe ser > 0.
items[].descuentonoEn pesos. No puede dejar la línea en negativo.
items[].descuentoPctnoPorcentaje del descuento de la línea: mayor que 0 y hasta 100, con hasta 2 decimales. Viaja en el XML como DescuentoPct, justo antes de DescuentoMonto, en 33, 34, 46, 52, 56 y 61. Exige el descuento en pesos que le corresponde: redondeo(redondeo(cantidad × precio) × descuentoPct / 100), con el medio peso hacia arriba (el 1,15 % de 3000 es 35). Ausente, null o 0: la línea sale como siempre, solo con el monto. En 39/41 se ignora (la boleta no lo lleva); en 110/111/112 no se admite. Errores: items[0]: "descuentoPct" debe ser un número mayor que 0 y hasta 100, con hasta 2 decimales (llegó 5.123). y items[0]: "descuento" no calza con "descuentoPct": el 5 % de la línea (336 × 2687 = 902832) redondeado es 45142 y llegó 45000.
items[].exentonoBooleano. Marca la línea con IndExe=1. Solo en los tipos con lineasExentas.
items[].unidadMedidanoTexto de 1 a 4 caracteres, sin contar los espacios de los extremos. Viaja en el XML como UnmdItem en los 8 tipos. Vacío o más largo: items[0]: "unidadMedida" debe ser un texto de 1 a 4 caracteres (llegó "kilos").
items[].codigosnoCódigo del producto (SKU, EAN, código interno…), hasta 5 por línea: [{ tipo, valor }]. Viaja en el XML como CdgItem en los 8 tipos. tipo de 1 a 10 caracteres y valor de 1 a 35, sin contar los espacios de los extremos. Ausente, null o []: el documento sale como siempre. Ver Códigos del producto.
descuentosRecargosno (33, 34, 39, 41, 56, 61)Descuentos y recargos globales (sobre el total, no sobre una línea), hasta 20: [{ tipo, unidad, valor, glosa?, exento? }]. En facturas y notas viajan en el XML como DscRcgGlobal; en boletas (39/41) se reparten en las líneas (DescuentoMonto/RecargoMonto). Se aplican en cadena. tipo D o R, unidad % o $. En 46, 52 y una nota con codRetencion es 400. Ausente, null o []: el documento sale como siempre. Ver Descuentos y recargos globales.
clientesegún tiporut (con o sin puntos, con guion; se valida el dígito verificador), nombre o razonSocial y —en 33/34/46/52— giro, direccion y comuna.
cliente.nombre / razonSocialsegún tipoTexto. Un objeto o una lista se rechaza: cliente.nombre debe ser texto.
cliente.email / telefononoTexto. Un objeto o una lista se rechaza: cliente.email debe ser texto.
cliente.ciudadnoCiudad del receptor (CiudadRecep en el XML), en los tipos del canal de upload; la boleta no la lleva. Se recorta a 20 caracteres.
fechanoAAAA-MM-DD. Ausente = hoy en hora de Chile. Tiene que ser un día real entre 2002-08-01 y 2050-12-31: fecha debe tener formato AAAA-MM-DD y ser una fecha real. o fecha fuera del rango que acepta el SII (2002-08-01 a 2050-12-31).
referenciaen 56/61; opcional en 33/34/46/52; 400 en 39/41En 33/34/46/52, un objeto o un arreglo de hasta 40 con los documentos que cita (guía 52, orden de compra 801, HES…): tipoDteRef y folioReferencia obligatorios; fechaReferencia (sin ella, la fecha del documento), codRef y motivo opcionales. Ver Referencias a otros documentos. En 56/61, el documento que la nota corrige o anula (un objeto): folioReferencia, tipoDteRef, fechaReferencia, codRef (1 anula, 2 corrige texto, 3 corrige montos), motivo. fechaReferencia sigue la misma regla que fecha (referencia.fechaReferencia debe tener formato AAAA-MM-DD y ser una fecha real.) y motivo tiene que ser texto (referencia.motivo debe ser texto.). En 56/61 tipoDteRef es un entero de 1 a 3 dígitos o un código de 1 a 3 letras o dígitos, codRef es 1, 2 o 3 (el número o el mismo dígito como texto) y la nota que anula exige tipo y folio numéricos: ver La referencia de una nota 56/61.
codRetencionno (46, 56, 61)Entero de la tabla 4 del SII. En 46, default 15. En 56/61 es opt-in: solo para la nota que modifica una factura de compra. La tasa sale del código: ver Retención de IVA en la factura de compra.
retencionTotalno (46)Booleano. Declara que se retuvo el 100% del IVA aunque el código sea de retención parcial (vendedor de difícil fiscalización). Cambia el código al alterno del SII (30 → 301).
indTrasladono (52)De 1 a 7. Default 1 (venta).
transportesí en 52 desde el 2026-11-01; opcional en 33/34/46Datos del traslado (Res. Ex. SII N° 144/2026). En la 52 son obligatorios patente (o patenteDesconocida: true), rutTransportista, chofer { rut, nombre }, destino { direccion, comuna }, fechaSalida y fechaLlegada; opcionales patenteCarro, destino.ciudad y horaSalida. Solo se acepta en 33, 34, 46 y 52: en 39, 41, 56 y 61 es 400. Ver el ejemplo de la guía 52.
formaPagosí en 33, 34 y 461 contado, 2 crédito, 3 sin costo (entrega gratuita): el entero o el mismo dígito como texto ("2", con o sin espacios alrededor). "01", "2.0", true o [2] son 400: formaPago debe ser 1 (contado), 2 (crédito) o 3 (sin costo). Sin valor por defecto (desde el 06-10-2026): sin ella, 400 en esos tipos. En los demás tipos, 400 si viene; en exportación la forma de pago va en exportacion.formaPagoExportacion.
fechaVencimientonoAAAA-MM-DD, no anterior a la emisión, entre 2002-08-01 y 2050-12-31. Solo 33, 34 y 46.
medioPagonoefectivo, pago_electronico, transferencia, cheque, otro. Aplica a todos los tipos.
observacionesnoTexto libre del documento, en todos los tipos (también 110, 111 y 112), por ejemplo "Compra para premio campaña Primavera". Se recortan los espacios de los extremos (y los repetidos) y admite hasta 100 caracteres: observaciones admite hasta 100 caracteres (tiene 120). Se guarda en el documento y se imprime en el PDF (carta y ticket) como «Observaciones: …». Solo en 33 y 34 va además al XML firmado, como IdDoc/TermPagoGlosa («Términos del Pago - glosa» para el SII); en los demás tipos nunca va al XML. Vacío, solo espacios o null = sin observaciones. Un valor que no es texto: observaciones debe ser texto. En el lote va por documento, con las mismas reglas. Ver Observaciones del documento.
sucursalIdnoId de una sucursal configurada de la empresa.
ventaId / pagoIdnoTus propios identificadores, para conciliar. Texto libre de hasta 100 caracteres (se recortan los espacios de los extremos). Un número se acepta y se guarda como texto (42 → "42"). Vacío o null = sin identificador. Un booleano, un objeto o una lista se rechaza con 400, antes de consumir folio: ventaId debe ser texto o número (llegó true). Un texto más largo, también: ventaId admite hasta 100 caracteres (llegó uno de 120: "…"). Dónde se recuperan: solo en el listado paginado GET /sii-emision/documentos, que devuelve el documento completo. No vuelven en el 201, ni en el listado por cursor, ni en la consulta por folio, ni en el webhook, y no hay filtro por ellos: guarda tú la relación con el emitidaId o con el tipo y folio que te devuelve el 201.
logoUrlnoURL https de un PNG o JPEG que pasa a ser el logo de la empresa en el PDF (de este documento y de todos). Hasta 2048 caracteres. Vacío o null = no cambia el logo. Formato inválido → 400 antes del folio. Solo lo aplican una API key o un usuario admin/superadmin. Ver Logo de la empresa por URL.
ambientenocertificacion o produccion. Sin el campo, sale en el ambiente de la empresa; con una key mk_cert_, siempre en certificación. Otro valor es 400 antes del folio: ambiente debe ser "certificacion" o "produccion" (llegó "prod"). Sin el campo, el documento sale en el ambiente configurado para la empresa. Quién puede pedir producción, en la regla 4.
items[].itemId, items[].varianteId, items[].bodegaId, items[].lotes, items[].series, bodegaIdnoSolo con el inventario encendido (apagado se ignoran). El ítem y la variante que mueve la línea (sin itemId, se vincula por items[].codigos[].valor), su bodega (o la del documento), sus lotes [{ numero, fechaVencimiento?, cantidad }] y sus números de serie.
inventariono{ bodegaDestinoId?, mueveStock?, devolucion?, repone? }: el destino de una guía 52 de traslado interno, mover igual una guía sobre una factura propia, reponer una 61 CodRef 3, o no reponer una 61 que anula. Ver Inventario en la emisión.

formaPago y fechaVencimiento en un tipo en que esta API no los acepta no se ignoran en silencio: se rechazan con Esta API solo acepta formaPago y fchVenc en los tipos 33, 34 y 46. Descartarlos calladamente dejaría al usuario creyendo que emitió a crédito con vencimiento mientras el documento, que es irreversible, salió al contado.

Forma de pago (formaPago): obligatoria en 33, 34 y 46

Cambio incompatible, vigente desde el 06-10-2026

Hasta esa fecha, una factura (33), una factura exenta (34) o una factura de compra (46) sin formaPago salía al contado (<FmaPago>1</FmaPago> en el XML). Desde el 06-10-2026 la API no supone nada: sin el campo responde 400, con el resto de los errores en detalles[] y antes de pedir el folio. Vale para POST /dte, para cada documento del lote (el error vuelve indexado) y para la emisión masiva por archivo (columna formaPago). Boletas, guías y notas no cambian: esta API solo la acepta en 33, 34 y 46, y en los demás tipos, si viene, es 400. Es una restricción de esta API, no del SII (en su esquema FmaPago es opcional también en guías y notas).

ValorForma de pago (campo FmaPago del Formato DTE del SII)
1Contado
2Crédito
3Sin costo (entrega gratuita)

Por qué no hay un valor por defecto:

  • Sobre una 33 o una 34 al contado o sin costo, el Registro de Aceptación o Reclamo del SII no admite eventos: el receptor no puede aceptarla ni reclamarla. El SII responde «No se puede registrar un evento (acuse de recibo, reclamo o aceptacion de contenido) de un DTE pagado al contado o gratuito». Emitir al contado por omisión le quitaba ese derecho a quien compró a crédito.
  • El SII, en cambio, entiende crédito cuando el tag falta (Formato DTE v2.5, campo 13 <FmaPago>). Ningún valor sirve para todas las ventas: lo decide quien emite.

fechaVencimiento sigue siendo opcional, también a crédito. Sin formaPago, una factura 33 responde:

bash
El DTE 33 (Factura electrónica) exige formaPago: 1 (contado), 2 (crédito) o 3 (sin costo, entrega gratuita). Elígela según la venta: al contado o sin costo el receptor no podrá aceptar ni reclamar la factura en el SII; a crédito, sí.

En la 46 el mensaje termina en «(sin costo, entrega gratuita).»: la factura de compra no pasa por ese registro.

Qué cambiar en tu integración. Manda formaPago en toda 33, 34 y 46. Si hasta ahora no la mandabas, tus facturas salían al contado: "formaPago": 1 deja el XML exactamente igual que antes. Si la venta es a crédito, manda 2 (y, si quieres, fechaVencimiento).

Observaciones del documento (observaciones)

Un texto libre corto que quieres que se lea en el documento: «Compra para premio campaña Primavera», «Retira en bodega 3». Se acepta en todos los tipos: 33, 34, 39, 41, 46, 52, 56, 61 y, con la exportación habilitada, 110, 111 y 112.

bash
{
  "tipo": 39,
  "items": [{ "nombre": "Bicicleta de premio", "precio": 119000 }],
  "observaciones": "Compra para premio campaña Primavera"
}
  • Largo: hasta 100 caracteres, contados después de recortar los espacios de los extremos y colapsar los repetidos. Más largo es 400 antes de pedir el folio, junto con el resto de los errores en detalles[]: observaciones admite hasta 100 caracteres (tiene 120).
  • Texto: un número, un booleano, un objeto o una lista es 400: observaciones debe ser texto. Vacío, solo espacios o null = sin observaciones: el documento sale exactamente igual que sin el campo.
  • Cómo se normaliza, en todos los tipos: los saltos de línea y los tabuladores pasan a ser un espacio, y los caracteres que no existen en ISO-8859-1 (emoji, la raya «—», las comillas tipográficas “ ”) quedan como ?. Las tildes y la ñ se conservan. En 33 y 34 es la regla de todo texto del XML del SII; en los demás tipos, donde el texto solo va al PDF, se aplica la misma para que el papel diga lo mismo en cualquier documento.
33 y 34Demás tipos (39, 41, 46, 52, 56, 61, 110, 111, 112)
XML firmadoSí, como IdDoc/TermPagoGlosa: el SII lo recibe como «Términos del Pago - glosa»Nunca
PDF del documento (carta y ticket, reimpresión, reenvío por correo)SíSí
PDF que se envía al correo del receptor al emitirSíSí (46, 52, 56 y 61; boletas y exportación no envían ese correo)
Consulta pública de boletas (/consulta-boleta)—No se imprime
Muestra impresa para la certificación del SIINoNo
Registro del documento (GET .../dte/por-folio/:tipoDte/:folio)SíSí

En el PDF va como «Observaciones: …», a todo el ancho y justo antes del detalle; si es largo, envuelve en varias líneas. Nunca se monta sobre el timbre.

Reemitir un documento rechazado conserva sus observaciones, y el borrador de copia de un documento las trae. La nota de crédito que genera anular no las hereda: si quieres una nota con texto, emítela con POST /dte y su propio observaciones.

Líneas exentas (items[].exento)

exento: true marca una línea como no afecta a IVA (IndExe=1 en el XML). Es la misma convención que la boleta 39 ya usaba para mezclar líneas afectas y exentas: no hay un segundo vocabulario que aprender, y no es un campo por documento.

json
{
  "tipo": 61,
  "items": [
    { "nombre": "Servicio afecto", "cantidad": 1, "precio": 10000 },
    { "nombre": "Libro exento",    "cantidad": 1, "precio": 5000, "exento": true }
  ]
}

Ese documento declara MntNeto 10000 + MntExe 5000 + IVA 1900 = MntTotal 16900: el caso mixto es válido y cuadra contra el detalle. IndExe va solo en las líneas exentas.

Si todas las líneas quedan exentas, los totales salen como los de un 34 (solo MntExe y MntTotal, sin MntNeto y sin IVA), no con un neto e IVA en cero. Cuadra igual aritméticamente, pero ningún documento exento del SII usa esa segunda forma.

Dos rechazos, los dos antes de pedir el folio

Importa el orden: el folio se consume aunque el SII rechace después.

  • exento que no es booleano ("true", 1, "si") → 400: items[0]: "exento" debe ser true o false (llegó "si"). Se valida estricto y no con Boolean(…): un "false" mandado por error es truthy, y el documento saldría con el IVA al revés sin que nadie lo note hasta que el SII lo compare con el original.
  • exento: true en una factura de compra 46 → 400: El DTE 46 (Factura de compra electrónica) no admite líneas exentas (items[].exento): declara una retención de IVA sobre el neto, y una línea sin IVA dejaría el MntTotal descuadrado contra el detalle. Sus Totales declaran una retención de IVA calculada sobre el neto, y una línea sin IVA no tiene nada que retener: el documento saldría con el MntTotal descuadrado contra el detalle y el SII lo rechaza.

En 34 y 41 marcar la línea es redundante, no un error: el documento entero ya es exento y la marca se ignora.

Códigos del producto (items[].codigos)

El código con que identificas el producto viaja en el XML del documento, en cada línea: <CdgItem><TpoCodigo>…</TpoCodigo><VlrCodigo>…</VlrCodigo></CdgItem>, justo después de NroLinDet (el orden de DTE_v10.xsd y EnvioBOLETA_v11.xsd). Vale en los 8 tipos y admite hasta 5 códigos por línea. tipo es la codificación (INT1 para el código interno, EAN13… la que use tu sistema; el panel manda INT1 con el código del catálogo) y valor, el código.

json
{
  "tipo": 39,
  "items": [
    {
      "nombre": "Cafe molido 250 g",
      "cantidad": 2,
      "precio": 4990,
      "codigos": [
        { "tipo": "INT1", "valor": "CAF-250" },
        { "tipo": "EAN13", "valor": "7801234567890" }
      ]
    },
    { "nombre": "Bolsa", "cantidad": 1, "precio": 50 }
  ]
}
  • Sin codigos (o con null o []) la línea sale exactamente como antes: el XML no cambia ni un byte.
  • Se validan antes de pedir el folio, todos juntos en detalles[]: que sea un arreglo, máximo 5, tipo de 1 a 10 caracteres y valor de 1 a 35 (sin contar los espacios de los extremos, que se recortan) y solo caracteres imprimibles de ISO-8859-1 (ni saltos de línea ni tabulaciones). El mismo ejemplo con un tipo largo y un código sin valor:
json
{
  "error": "Payload inválido",
  "detalles": [
    "items[0].codigos[0]: \"tipo\" debe ser un texto de 1 a 10 caracteres (llegó \"CODIGO-INTERNO\").",
    "items[0].codigos[1]: \"valor\" debe ser un texto de 1 a 35 caracteres (llegó undefined)."
  ]
}
  • El PDF muestra el primer código de cada línea solo si alguna lo trae: en carta, en una columna «CÓDIGO» a la izquierda de la descripción; en el ticket, delante del nombre (CAF-250 · Cafe molido 250 g). Sin códigos, el PDF es el de siempre.
  • Se conservan: quedan en detalles[].codigos del documento, la nota de crédito que lo anula repite los códigos de cada línea y la reemisión de un rechazado los vuelve a mandar.

Referencias a otros documentos (referencia)

Una factura (33, 34, 46) o una guía de despacho (52) puede citar otros documentos: la guía 52 con que se despachó, la orden de compra del cliente (801), su hoja de entrada de servicios (HES)… Van en referencia, como un objeto o un arreglo de hasta 40, y salen en el XML como bloques <Referencia> en ese mismo orden (NroLinRef 1, 2, 3…). Son opcionales: sin referencia el documento sale exactamente como antes. Los nombres son los mismos que en las notas 56/61:

CampoObligatorioNotas
tipoDteRefsíTipo del documento referenciado (TpoDocRef): de 1 a 3 letras o dígitos. Un DTE (33, 52…) o un documento del cliente (801 orden de compra, 802 nota de pedido, 803 contrato, HES…). SET se rechaza: es exclusivo del set de certificación del SII.
folioReferenciasíNúmero o texto de 1 a 18 caracteres (FolioRef): admite el folio alfanumérico de una orden de compra. La nota que anula (una 61, o una 56 sobre una 61) es la excepción: ahí tiene que ser numérico (ver La referencia de una nota 56/61).
fechaReferencianoFecha del documento referenciado (FchRef), AAAA-MM-DD, entre 2002-08-01 y 2050-12-31. Si no viene, FchRef lleva la fecha del documento que emites.
codRefno1 (anula), 2 (corrige texto) o 3 (corrige montos), como en las notas: el número o el mismo dígito como texto ("1"). "1.0", "0x1", true o [1] son 400.
motivonoTexto de hasta 90 caracteres (RazonRef).

Una factura que cita la guía con que se despachó y la orden de compra del cliente:

json
{
  "tipo": 33,
  "cliente": {
    "rut": "76123456-0",
    "razonSocial": "COMERCIAL LOS ALERCES SPA",
    "giro": "Venta al por menor de artículos de ferretería",
    "direccion": "Av. Providencia 1234, of. 502",
    "comuna": "Providencia"
  },
  "items": [
    { "nombre": "Perfil de aluminio 3m", "cantidad": 40, "precio": 7200 }
  ],
  "formaPago": 2,
  "referencia": [
    { "tipoDteRef": 52, "folioReferencia": 318, "fechaReferencia": "2026-10-01" },
    { "tipoDteRef": 801, "folioReferencia": "OC-2026-0457", "fechaReferencia": "2026-09-28", "motivo": "Orden de compra del cliente" }
  ]
}

Todo se valida antes de pedir el folio, y los errores vuelven juntos en detalles[], con el índice de cada referencia (sin índice si mandaste un objeto):

json
{
  "error": "Payload inválido",
  "detalles": [
    "referencia[0].fechaReferencia debe tener formato AAAA-MM-DD y ser una fecha real.",
    "referencia[1].tipoDteRef debe tener de 1 a 3 letras o dígitos (llegó \"ORDEN\").",
    "referencia[1].folioReferencia debe ser un número o un texto de 1 a 18 caracteres (llegó \"OC-2026-0457-SUCURSAL-NORTE\")."
  ]
}
CasoRespuesta
Más de 40 referencias400: Un DTE admite hasta 40 referencias (enviaste 41).
folioRef, fechaRef, fchRef, tpoDocRef o razonRef (nombres del XML o de otra API)400: referencia[0].razonRef no existe: usa "motivo".
referencia en una boleta 39/41400: Esta API no emite referencias en boletas (39/41): "referencia" no se acepta en estos tipos. Si necesitas referenciar una guía, una orden de compra u otro documento, emite una factura (33 o 34).
referencias (en plural), en cualquier tipo400: "referencias" no es un campo de POST /dte: las referencias van en "referencia", como un objeto o un arreglo de hasta 40.

Las referencias de 33/34/46/52 viven en el XML firmado del documento (GET /dte/:id/xml). El campo referencia que guarda el documento sigue siendo solo el de las notas 56/61: es el que el libro de ventas usa para descontarlas.

Antes se ignoraban sin avisar

Hasta el 4 de octubre de 2026, en las facturas 33/34/46 y en las boletas 39/41 la API respondía 201 sin <Referencia> y con el folio consumido; en la guía 52 las referencias viajaban sin validar (un tipoDteRef: 801 sin folio salía como <FolioRef>undefined</FolioRef>). Si tu integración ya las mandaba, los documentos emitidos antes de este cambio salieron sin ellas. Ahora salen en el XML o el payload se rechaza con 400, sin consumir folio. En la 52, una referencia sin fechaReferencia sigue funcionando como antes: FchRef lleva la fecha de la guía.

La referencia de una nota 56/61

En una nota de débito (56) o de crédito (61), referencia es un objeto con el documento que la nota corrige o anula. Desde el 07-10-2026 la forma de cada campo se valida antes de pedir el folio. Antes, un folioReferencia: {} o un codRef: true salían al XML tal cual y el SII rechazaba la nota con el folio ya consumido.

CampoRegla
folioReferenciaObligatorio. Número o texto de 1 a 18 caracteres, la misma forma que en 33/34/46/52.
tipoDteRefObligatorio. Un entero positivo de hasta 3 dígitos (61, "33") o un código de 1 a 3 letras o dígitos (HES, 801). "110.0", "1 10", [110], true o un objeto son 400. SET se rechaza, igual que en 33/34/46/52.
codRefOpcional: sin él, la nota anula (CodRef 1). 1, 2 o 3, como número o como el mismo dígito en texto. "1.0", "0x1", true o [1] son 400.

La nota que anula exige tipo y folio numéricos. Una 61 que anula (codRef 1, o sin codRef), o una 56 que anula una 61, tiene que traer tipoDteRef numérico (entero de 1 a 3 dígitos) y folioReferencia numérico (solo dígitos). Es una restricción de esta API, no del SII (su esquema admite un TpoDocRef alfanumérico y un FolioRef de texto): sin eso la anulación no queda registrada y el corte de una sola anulación por documento no la ve. Responde 400:

texto
referencia.folioReferencia debe ser numérico, solo dígitos (llegó "A123"): esta API lo exige en la nota que anula (codRef 1, o sin codRef) para registrar la anulación y evitar anular dos veces el mismo documento.

Una 56 con codRef 1 sobre otro tipo (una 33, una HES, una 801) no es una anulación que esta API registre, y su referencia admite el folio alfanumérico. Reemitir desde el panel una nota rechazada que anula sin tipo o folio numérico responde 422 REFERENCIA_QUE_ANULA_NO_NUMERICA, antes de tocar el pool de folios.

Una 56/61 no referencia un documento de exportación. Una referencia con tipoDteRef 110, 111 o 112 es 400 en POST /dte y en el lote, y 422 NOTA_NACIONAL_SOBRE_EXPORTACION al reemitir: un documento de exportación se corrige o anula con una nota de exportación (111 o 112). Para anular una 110, usa POST /dte/:id/anular.

Qué cambia para tu integración

Valores que antes pasaban ("1.0", true o [1] en codRef; un objeto o un folio de 19 caracteres en folioReferencia) ahora son 400, sin consumir folio. Si mandas codRef como número y el tipo y el folio del documento anulado como números, nada cambia.

Logo de la empresa por URL (logoUrl)

Si ya tienes el logo de tu cliente publicado en una URL, mándala en logoUrl y la API lo descarga, lo valida y lo guarda como el logo de la empresa: el mismo que se sube desde el panel. El PDF del documento que estás emitiendo ya sale con él.

json
{
  "tipo": 39,
  "items": [{ "nombre": "Café", "precio": 1500 }],
  "logoUrl": "https://cdn.tu-sistema.cl/clientes/123/logo.png?v=4"
}

El logo es de la empresa, no del documento

El PDF se genera cada vez que se pide, con el logo vigente: cambiarlo cambia también el PDF de los documentos ya emitidos (el del panel, el de la API y la consulta pública). No hay un logo por documento.

Solo se descarga si cambió. La API recuerda de qué URL sacó el logo: la misma logoUrl con un logo ya cargado no se descarga de nuevo, así que, una vez cargado, mandarla en cada emisión no agrega demora. Para forzar una recarga, cambia la URL (por ejemplo, ?v=5). Subir un logo desde el panel reemplaza al de la URL, y la próxima emisión con logoUrl vuelve a descargarlo.

Un fallo se recuerda una hora. Si la descarga o la validación de una URL falla, durante la hora siguiente la misma logoUrl no se vuelve a intentar: la emisión responde al tiro con el mismo aviso. Una URL distinta se intenta de inmediato; si ya corregiste la imagen, cambia la URL (?v=6) para no esperar.

RequisitoSi no se cumple
Texto, URL válida, https, hasta 2048 caracteres400 antes del folio, en detalles[] junto a los demás errores: logoUrl debe usar https (llegó "http").
Dominio público: no IPs privadas, loopback ni nombres que resuelvan a ellasaviso
La URL entrega la imagen directamente: sin redirecciones (un 301/302 cuenta como fallo)aviso
Responde 2xx en menos de 5 s en total (DNS, conexión y descarga)aviso
PNG o JPEG por su contenido (el Content-Type es informativo), hasta 200 KB y 2000×2000 pxaviso
La imagen se puede decodificar entera: PNG completo (bloques con su CRC, datos al tamaño que declaran sus dimensiones, cierre IEND), de 8 bits (grises y paleta también de 1, 2 o 4), sin entrelazado; JPEG completo (de SOI a EOI), de 8 bits, en grises, color o CMYKaviso

Las reglas de la imagen son las mismas del logo que se sube desde el panel: un archivo con buen encabezado y datos rotos hacía fallar el PDF de todos los documentos de la empresa. Un PNG, además, tiene que venir sin ambigüedades: un solo IHDR y primero, a lo más una paleta (PLTE) y una transparencia (tRNS), en ese orden y antes de los datos, los IDAT seguidos y ningún bloque crítico desconocido.

El PNG se normaliza

Lo que se guarda no es tu archivo: es un PNG que la API vuelve a armar con la misma imagen (mismas dimensiones, mismos píxeles). Se pierden los metadatos (texto, autor, fechas) y el perfil de color (iCCP, gamma): los colores se imprimen tal como vienen en los píxeles. Tampoco se conserva la transparencia por color clave de un PNG en grises o RGB sin canal alfa: se imprime opaco. Para transparencia, usa RGBA, grises con alfa o paleta con transparencia. El JPEG se guarda tal cual.

Si la descarga falla, la emisión sigue con el logo que la empresa ya tenía, y el 201 trae un campo adicional avisos. Solo aparece si hay algo que avisar: sin logoUrl, o con un logo que se actualizó bien, la respuesta es la de siempre.

Por seguridad, todo fallo de red (destino no permitido, DNS, conexión, timeout, redirección o código HTTP de tu servidor) trae el mismo detalle, el del ejemplo: si la API distinguiera esos casos, serviría para sondear otros servidores. Revisa la URL desde tu lado (por ejemplo, con curl -I). Los fallos del archivo sí se detallan (El logo pesa más de 200 KB: …, La imagen descargada no sirve como logo: …), porque los puedes comprobar tú mismo.

json
{
  "success": true,
  "folio": 1042,
  "…": "…",
  "avisos": [
    { "code": "LOGO_NO_ACTUALIZADO", "detalle": "No se pudo descargar el logo desde esa URL: tiene que ser un dominio público con HTTPS que entregue la imagen directamente (sin redirecciones) en menos de 5 s." }
  ]
}

La descarga ocurre antes de pedir el folio: si la emisión después falla por otra razón (por ejemplo, 409 sin folios), el logo ya quedó actualizado. En el lote va una sola vez, a nivel del lote.

Quién puede cambiar el logo

Una API key con dte:emitir (sin scope nuevo) o un usuario admin/superadmin de la empresa, los mismos que lo suben desde el panel. Un usuario con rol emisor emite pero no cambia la identidad impresa: si manda logoUrl, el documento se emite igual, no se descarga nada, el logo no cambia y el 201 trae el aviso LOGO_NO_AUTORIZADO. Un logoUrl con formato inválido es 400 para todos: es un error del payload.

Descuentos y recargos globales (descuentosRecargos)

Un descuento o recargo que afecta al total del documento y no a una línea («10% cliente frecuente», «flete $2.000») va en descuentosRecargos, con el vocabulario del formato del SII. En facturas y notas sale en el XML como un bloque <DscRcgGlobal> por cada uno, entre el último <Detalle> y la primera <Referencia>; en boletas se reparte en las líneas (ver abajo). Los totales del documento (MntNeto, MntExe, IVA, MntTotal, y el MNT del timbre) ya salen con ellos aplicados.

json
{
  "tipo": 33,
  "cliente": {
    "rut": "78287987-1",
    "razonSocial": "Ferreteria El Sol SpA",
    "giro": "Comercio",
    "direccion": "Av. Siempre Viva 123",
    "comuna": "Providencia"
  },
  "items": [
    { "nombre": "Perfil de aluminio", "cantidad": 3, "precio": 5000 }
  ],
  "formaPago": 1,
  "descuentosRecargos": [
    { "tipo": "D", "unidad": "%", "valor": 10, "glosa": "Cliente frecuente" },
    { "tipo": "R", "unidad": "$", "valor": 2000, "glosa": "Flete" }
  ]
}

Las líneas suman $15.000 netos; el descuento es $1.500 (10% de las líneas) y el recargo, $2.000. El documento declara MntNeto 15500, IVA 2945 y MntTotal 18445.

CampoRegla
tipo"D" descuento o "R" recargo (TpoMov).
unidad"%" porcentaje o "$" pesos (TpoValor).
valorUn número, tal como se pide (ValorDR). En %: mayor que 0 y hasta 100, con hasta 2 decimales. En $: un entero de pesos mayor que 0.
glosaOpcional, hasta 45 caracteres (GlosaDR). No se recorta: más larga es 400.
exentoOpcional, true o false estricto. true lo aplica a las líneas exentas (IndExeDR = 1) y exige que haya alguna; sin él (o con false) se aplica a las afectas, y tiene que haber alguna. En 34 y 41 todo es exento: se aplica a lo exento sin pedirlo, y exento: false es 400.
  • Sobre qué se calcula: en cadena. Se aplican en el orden en que los mandas, cada uno sobre lo que dejó el anterior de su parte (afectas o exentas), como los aplica el SII: 10% y luego 5% sobre $15.000 dejan 15.000 × 0,90 × 0,95 = $12.825 (neto), no $12.750. Un monto en $ se suma o resta sobre esa misma base. Cada monto se redondea a peso entero.
  • Facturas y notas (33, 34, 56, 61): sobre el NETO. El IVA se recalcula sobre el neto ya ajustado (round(neto × 19%)).
  • Boletas (39, 41): sobre el BRUTO, igual que sus precios, y repartidos en las líneas. En la boleta el SII compara MntTotal con la suma de los MontoItem y no descuenta <DscRcgGlobal>, así que la boleta no lleva ese bloque: cada descuento se reparte entre las líneas de su parte, en proporción a su monto, como DescuentoMonto de la línea (un recargo, como RecargoMonto), y la suma de las líneas da el total exacto. El neto sale después, como siempre, del bruto ajustado (round(bruto / 1,19)). Una boleta con $9.881 afectos y $4.155 exentos y un 10% sobre lo afecto totaliza $13.048 (neto 7.473, IVA 1.420, exento 4.155): la línea afecta sale con DescuentoMonto 988 y MontoItem 8893.
  • No se admiten en la factura de compra (46) ni en la nota con codRetencion (retienen el IVA sobre las líneas, y un descuento global descuadraría la retención) ni en la guía (52). Ahí el descuento va en cada línea (items[].descuento).
  • Boletas sobre 135 UF: el umbral se mide con el total después de los descuentos y recargos.
  • Un descuento que deja una parte (afecta o exenta) en cero o menos es 400.
  • IndExeDR = 2 (no facturable) no se soporta.

Se validan antes de pedir el folio, todos juntos en detalles[]. El mismo ejemplo con un porcentaje sobre 100 y un recargo con tipo y valor inválidos:

json
{
  "error": "Payload inválido",
  "detalles": [
    "descuentosRecargos[0]: \"valor\" en porcentaje debe ser mayor que 0 y hasta 100, con hasta 2 decimales (llegó 150).",
    "descuentosRecargos[1]: \"tipo\" debe ser \"D\" (descuento) o \"R\" (recargo) (llegó \"X\").",
    "descuentosRecargos[1]: \"valor\" en pesos debe ser un entero mayor que 0 (llegó 2000.5)."
  ]
}

Otros textos que puedes recibir:

  • descuentosRecargos no aplica al DTE 46 (factura de compra): retiene el IVA sobre las líneas con código de retención y un descuento o recargo global descuadraría esa retención. Aplica el descuento en cada línea (items[].descuento).
  • descuentosRecargos no aplica al DTE 52 (guía de despacho). Aplica el descuento en cada línea (items[].descuento).
  • descuentosRecargos[0]: tiene "exento": true, pero el documento no tiene líneas exentas.
  • Los descuentos globales dejan la parte afecta del documento en $-5000: tiene que quedar mayor que cero.

Qué pasa después

  • PDF. Solo con descuentos o recargos, el bloque de totales suma un renglón «SUBTOTAL» (la suma de las líneas) y uno por cada movimiento antes del neto: «DESCUENTO 10% Cliente frecuente» -$1.500, «RECARGO Flete» +$2.000. En carta y en ticket. En la boleta, como las líneas ya traen el descuento, no hay subtotal ni cifra que se reste dos veces: un renglón informativo, «DESCUENTO GLOBAL 10% Cliente frecuente: -$988, incluido en las líneas». Sin ellos, el PDF es el de siempre.
  • Consulta del documento. GET .../dte/por-folio/:tipo/:folio devuelve descuentosRecargos junto a detalles, cada uno con el monto en pesos que movió. Sin ellos la clave no aparece. En la boleta, cada línea trae su montoItem final y, si le tocó algo del reparto, descuentoGlobal o recargoGlobal; su descuento sigue siendo el que pediste para la línea.
  • Anular. La nota que anula una factura o nota con descuentos globales los repite tal cual: mismas líneas, mismos movimientos, mismos totales. La que anula una boleta copia sus líneas, que ya traen el descuento, y totaliza lo mismo que la boleta, peso a peso. Con items explícitos manda tu detalle y la nota no copia los descuentos.
  • Reemitir un rechazado los vuelve a mandar (los de una factura, leídos del XML firmado) y los aplica una sola vez: el mismo folio sale con el mismo total.
  • En el lote van por documento, con las mismas reglas.

Documentos de exportación (110, 111 y 112)

Solo donde el servidor la habilita

Con SII_EXPORTACION_HABILITADA=true. Sin esa variable, GET /dte/tipos no los lista y POST /dte los rechaza como tipo no soportado. Una 111 con codRef 1 sobre una 110 se emite, pero el SII de certificación todavía no dio veredicto sobre ese caso.

La factura de exportación (110) y sus notas de débito (111) y de crédito (112) son exentas por definición, van por el canal de upload y se emiten con el mismo POST /dte. Lo que cambia frente a una factura nacional:

  • Receptor extranjero. El RUT lo pone el servidor (55.555.555-5): omite cliente.rut (otro valor es 400). cliente.razonSocial es obligatoria y, en la 110, también direccion (en el extranjero) y ciudad. Opcionales: giro, contacto, correo, comuna, numId (su identificador en su país) y nacionalidad (código de país de la tabla de Aduana). El receptor no se guarda en la agenda de contactos.
  • Montos en la moneda de venta. precio y cantidad (hasta 6 decimales cada uno) van en la moneda de exportacion.moneda, que es uno de los nombres del esquema del SII ("DOLAR USA", "EURO"…; "PESO CL" no se acepta). El monto de cada línea es precio × cantidad, redondeado a 2 decimales. Los decimales van con punto, como número o como texto ("943.21"), sin separador de miles. En la 110 de bienes cada línea exige cantidad y unidadMedida (sigla de la tabla de unidades de Aduana: KN, U, LT…). Un precio 0 se acepta. Una línea sin cantidad se emite con cantidad 1 (también en el PDF): el SII calcula precio × cantidad y, sin cantidad, deja reparo.
  • Tipo de cambio obligatorio. exportacion.tipoCambio: pesos por unidad de la moneda de venta, del Banco Central a la fecha de emisión (hasta 6 enteros y 4 decimales). La fecha que manda es la fecha del documento (la del payload, o hoy en Chile). Una fecha que no es un AAAA-MM-DD real es 400 con dos errores: el de la fecha y exportacion.tipoCambio: no se puede resolver sin una fecha de emisión AAAA-MM-DD real (es el tipo de cambio de esa fecha). El total en pesos es el total × el tipo de cambio, redondeado al peso (la mitad, hacia arriba).
  • Bloque de Aduana, dentro de exportacion, con los códigos del Anexo 51 de Aduanas (la API los valida contra esas tablas). viaTransporte y paisReceptor son obligatorios en toda 110, también en la de servicios. En la 110 de bienes (sin indServicio) son obligatorios además modalidadVenta, clausulaVenta, totalClausulaVenta, puertoEmbarque, puertoDesembarque y totalBultos. Una exportación de servicios lleva indServicio: 3; los códigos 4, 5 y 6 todavía no se aceptan. Un campo de exportacion que la API no conoce es 400.
  • Forma de pago. formaPago no va (400): va exportacion.formaPagoExportacion, de la tabla de Aduana. Con 32 (pago anticipado) la 110 exige exportacion.fechaCancelacion; con 21 (sin pago), el total del documento tiene que ser 0. El plazo va en exportacion.terminosPago ({ codigo, glosa, dias }).
  • Enteros grandes. exportacion.totalItems y exportacion.totalBultos admiten hasta 18 dígitos y se guardan como texto. Con más de 15 dígitos mándalos como texto: un número de JSON así ya llega redondeado y se rechaza.
  • Notas 111 y 112. referencia es obligatoria y tiene que apuntar a la factura 110 que modifican (tipoDteRef: 110, con codRef); su fechaReferencia también es obligatoria. Las excepciones son las notas que anulan otra nota, con una sola referencia y codRef 1: la 112 que anula una 111 referencia solo la 111, y la 111 que anula una 112 referencia solo la 112. Una 111 que referencia una 112 con otro codRef (y sin la 110) es 400: Una nota de débito de exportación que referencia una nota de crédito de exportación (tipoDteRef 112) solo puede anularla (codRef 1, como única referencia); para corregir montos o texto debe referenciar la factura de exportación (tipoDteRef 110). Una 112 que corrige texto (codRef 2) lleva todas sus líneas en 0. En la 110, la referencia 807 (DUS) va una sola vez.
  • Lo que no se acepta (400, antes del folio): medioPago, codRetencion, retencionTotal, indTraslado, transporte, descuentosRecargos, items[].descuento, items[].exento y referencias en plural. La facturación recurrente no los emite: Los documentos de exportación (110, 111 y 112) no se emiten por la facturación recurrente: emítelos uno a uno con POST /dte, por lote con POST /dte/lote o con la emisión masiva por archivo.
  • Por lote (POST /dte/lote), cada 110, 111 o 112 lleva fecha (AAAA-MM-DD) y exportacion.tipoCambio explícitos: el lote emite en segundo plano y no fija el día ni busca el tipo de cambio por su cuenta. Se valida igual que en POST /dte, antes de crear el lote, y la 112 que anula pasa por la misma protección contra doble anulación. Sin ellos, el 400 LOTE_INVALIDO trae en ese índice fecha es obligatoria en un documento de exportación del lote, en formato AAAA-MM-DD: el lote emite en segundo plano y el tipo de cambio es el de la fecha de emisión, así que la fecha va explícita. o exportacion.tipoCambio es obligatorio en un documento de exportación del lote: el tipo de cambio del Banco Central a la fecha del documento, en pesos por unidad de la moneda de venta (el lote no lo busca por su cuenta).
  • Por la emisión masiva por archivo (ver Exportación en la emisión masiva): con las columnas de exportación de la plantilla y las mismas reglas del lote.

Una factura de exportación de bienes con todos los bloques. El 201: 1200 × 3,25 + 500,5 × 7,1 = 7.453,55 dólares; × 943,21 = 7.030.262,8955, redondeado a 7.030.263 pesos.

POST /api/empresas/:empresaId/dte · factura de exportación 110

json
{
  "tipo": 110,
  "fecha": "2026-10-07",
  "cliente": {
    "razonSocial": "SOCIEDAD \"EL SOL\" LTDA",
    "direccion": "AV. B. O'HIGGINS 123",
    "ciudad": "Buenos Aires",
    "giro": "Importación",
    "numId": "30-12345678-9",
    "nacionalidad": 224,
    "correo": "compras@elsol.example"
  },
  "items": [
    {
      "nombre": "Vino tinto reserva",
      "cantidad": 1200,
      "unidadMedida": "LT",
      "precio": "3.25",
      "codigos": [
        {
          "tipo": "INT1",
          "valor": "VT-01"
        }
      ]
    },
    {
      "nombre": "Aceite de oliva",
      "descripcion": "Botella 500 ml",
      "cantidad": "500.5",
      "unidadMedida": "KN",
      "precio": "7.1"
    }
  ],
  "exportacion": {
    "moneda": "DOLAR USA",
    "tipoCambio": "943.21",
    "tipoDespacho": 1,
    "formaPagoExportacion": 32,
    "fechaCancelacion": "2026-10-01",
    "modalidadVenta": 1,
    "clausulaVenta": 5,
    "totalClausulaVenta": "7453.55",
    "viaTransporte": 1,
    "nombreTransporte": "MSC ARICA",
    "puertoEmbarque": 905,
    "puertoDesembarque": 262,
    "pesoBruto": "15000.5",
    "unidadPesoBruto": 6,
    "totalBultos": 32,
    "tiposBulto": [
      {
        "codigo": 74,
        "cantidad": 2,
        "idContainer": "MSCU123456-7",
        "sello": "S-998877",
        "emisorSello": "NAVIERA DE PRUEBA"
      }
    ],
    "flete": "350.5",
    "paisReceptor": 224,
    "paisDestino": 224
  },
  "referencia": [
    {
      "tipoDteRef": "807",
      "folioReferencia": "9876543",
      "fechaReferencia": "2026-10-05",
      "motivo": "DUS"
    }
  ]
}
json
{
  "success": true,
  "folio": 7,
  "tipoDTE": 110,
  "fechaEmision": "2026-10-07",
  "total": 7030263,
  "rutEmisor": "78287987-1",
  "rutReceptor": "55555555-5",
  "trackid": "424242",
  "emitidaId": "66f0a1b2c3d4e5f607182932",
  "emisorDirectoSii": true,
  "message": "DTE 110 folio 7 enviado al SII (trackid 424242)",
  "rawResponse": "<RECEPCIONDTE>…<STATUS>0</STATUS><TRACKID>424242</TRACKID></RECEPCIONDTE>",
  "exportacion": {
    "moneda": "DOLAR USA",
    "total": "7453.55",
    "tipoCambio": {
      "valor": "943.21",
      "fecha": "2026-10-07",
      "origen": "manual",
      "fuente": "payload"
    }
  }
}

total va en pesos, como en el resto de los tipos (es también el montoTotal guardado). La moneda de venta va aparte, en exportacion: el total en esa moneda como texto decimal exacto y el tipo de cambio usado.

Anular. POST /dte/:id/anular sobre una 110 emite una nota de crédito de exportación 112 con codRef 1, en la moneda de la 110 y con el tipo de cambio de la fecha de la nota, nunca el de la 110: mándalo en el body como { "exportacion": { "tipoCambio": "…" } }, que es la única clave de exportacion que se acepta al anular. Sin items, la nota repite las líneas de la 110. Anular una nota de débito de exportación (111) emite una 112 con codRef 1 y una sola referencia, a la 111, en la moneda de la 111 y con el tipo de cambio del día de la nota (exportacion.tipoCambio). Anular una nota de crédito de exportación (112) emite una nota de débito de exportación 111 con codRef 1 y una sola referencia, a la 112, en la moneda de la 112 y con el tipo de cambio del día de la nota (exportacion.tipoCambio); responde 201, como cualquier anulación. Así las aceptó el SII de certificación el 22-10-2026 (Formato DTE v2.5, Pág.46, casos a y c: un único documento de referencia). POST /dte también acepta esas dos notas. Si la 112 ya tiene una 111 que la anula y el SII no la rechazó, 409 DOCUMENTO_YA_ANULADO con notaDebito. Cuando el SII acepta esa 111, la verificación pública de la 112 muestra anulado: true y notaDebito. En un servidor sin la exportación habilitada, 422 EXPORTACION_NO_HABILITADA. Reemitir una 110, 111 o 112 rechazada responde 422.

Estado en el SII. GET /dte/:id/estado consulta el envío por su trackid, como en todos los tipos. Una 110, 111 o 112 en ENVIO_INCIERTO la plataforma la consulta por folio en el SII, como una factura nacional (ver Cómo sale un documento de ENVIO_INCIERTO), con el total en la moneda de venta tal como viajó en el XML, en texto decimal exacto ("100.05"): con el total en pesos el SII no lo encuentra. Un documento sin ese total guardado queda para resolverlo a mano.

PDF, folios y libros. El PDF lleva un bloque de exportación con los montos en la moneda de venta, el tipo de cambio con su fecha y el total en pesos; no imprime el monto en palabras y no tiene copia cedible (el Manual de Muestras Impresas del SII no la contempla para exportación). Los CAF, el timbraje, el umbral de alerta de folios y el auto-timbraje de 110 a 112 existen solo con la exportación habilitada. El libro de ventas suma la 111 y resta la 112. El libro IECV que se envía al SII incluye la 110, la 111 y la 112 con sus montos en pesos (los de OtraMoneda, al tipo de cambio de su fecha de emisión), MntIVA 0 y TpoDocRef solo en la 112 que anula una 110 o una 111 (formato IECV v3.0, págs. 10, 22, 23 y 39); ya no deja el período incompleto. No informa los ajustes de tipo de cambio 500 y 501. Un libro de ventas parcial (no cierra el período) con 110, 111 y 112, enviado el 22-10-2026 al SII de certificación, quedó LOK «Envio de Libro Aceptado - Cuadrado». Falta probar el resumen del período con exportación, que solo va en un envío que cierra el período. El panel lee las tablas de Aduana en GET /dte/exportacion/catalogos (solo con sesión); una integración manda los códigos directamente.

Respuesta 201

json
{
  "success": true,
  "folio": 1042,
  "tipoDTE": 33,
  "fechaEmision": "2026-10-02",
  "total": 221150,
  "rutEmisor": "78287987-1",
  "rutReceptor": "76123456-0",
  "trackid": "1234567890",
  "emitidaId": "66f0a1b2c3d4e5f607182930",
  "emisorDirectoSii": true,
  "message": "DTE 33 folio 1042 enviado al SII (trackid 1234567890)",
  "rawResponse": { "…": "respuesta cruda del SII" }
}

rawResponse no es contrato estable

Es la respuesta cruda del SII, sin normalizar: su forma la decide el SII y cambia entre canales. Úsala para depurar, no para lógica de negocio.

trackid es siempre un string

En los cuatro sitios donde aparece: esta respuesta, el listado y la consulta por folio, GET /dte/:id/estado y el payload de los webhooks. Es un identificador, no una cantidad: no lo conviertas a número para compararlo. Lo traen en null un documento que nunca llegó al SII y también uno en ENVIO_INCIERTO, cuyo envío quedó sin confirmar.

Estados posibles

HTTPCuándo
201Emitido y enviado al SII. Todavía no hay veredicto: llega después, por webhook o por consulta de estado. Guarda emitidaId (es el :id de las consultas), folio y trackid.
400Payload inválido. detalles[] trae todos los errores. No se consumió folio. Incluye lo que el armador del XML rechazaría: una línea cuyo descuento la deja con monto negativo (Ítem 1 ("Servicio") con monto negativo: el SII lo rechaza.) o un documento que totaliza cero (El total del documento debe ser mayor que cero.; en boletas, El total de la boleta debe ser mayor que cero.).
400Un valor que la base de datos no puede convertir al tipo del campo (CastError): { "error": "El campo \"x\" tiene un valor inválido." }, nombrando el campo y sin el texto interno.
403Sin scope, o la empresa del path no es la de la key (ver Alcance de una key).
409errorType: "NO_FOLIOS" o "CAF_VENCIDO" (quedaban folios, pero su CAF caducó a los 6 meses del timbraje y el SII los rechaza; el CAF de boletas 39/41 no vence), y tipoDte con el tipo que hay que timbrar. Es un estado del negocio, no una falla. No se consumió folio. Con CAF_VENCIDO, los folios que quedaban en ese CAF se perdieron. Ver Quedarse sin folios.
409code: "DOCUMENTO_YA_ANULADO" — solo al anular (POST /dte/:id/anular, o POST /dte con una nota 61 CodRef 1 o una 56 CodRef 1 que referencia una 61): el documento ya tiene una nota que lo anula y el SII no la rechazó. Trae notaCredito: { id, folio, estadoSii }, o notaDebito con la misma forma cuando el documento anulado es una nota de crédito. No se consumió folio. Ver Una sola anulación por documento.
409code: "ANULACION_EN_CURSO" — solo al anular: otra petición está anulando ese mismo documento en este momento. No se consumió folio. No reintentes a ciegas: consulta el documento.
422El SII o el guard rechazaron la emisión (certificado vencido, empresa en producción sin número de resolución…). Al anular (o con una nota que anula: 61 CodRef 1, o 56 CodRef 1 sobre una 61), también code: "CONFIG_EMISION_INVALIDA": la configuración de emisión no sirve para emitir (no existe, está desactivada, falta el certificado o el emisor demo no está disponible). Solo al anular y al reemitir, además, code: "CONFIG_DISTINTA_DEL_DOCUMENTO": la configuración de hoy emitiría la nota en otro modo (demo / folios propios) que el documento; un ambiente distinto ya no corta, la nota sale en el del documento. POST /dte y el lote no cargan el documento referenciado, así que no tienen con qué compararlo y nunca lo devuelven. En esos dos no se consumió folio.
409code: "IDEMPOTENCIA_EN_CURSO" — solo con la cabecera Idempotency-Key: la emisión original con esa clave sigue en curso (o se interrumpió). No se emitió otro documento. Ver Reintentos seguros.
422code: "IDEMPOTENCY_KEY_REUTILIZADA" — solo con Idempotency-Key: la clave ya se usó con otro cuerpo, o desde otra credencial. No se emitió nada.
503code: "IDEMPOTENCIA_NO_DISPONIBLE" — solo con Idempotency-Key: no se pudo verificar la clave. No se consumió folio. Reintentable con la misma clave.
502errorType: "ENVIO_INCIERTO" — el envío se cortó sin saber si el SII lo recibió. El folio SÍ se consumió y el documento quedó guardado (emitidaId, folio, tipoDte en el cuerpo). No reintentes la emisión. Ver Envío incierto.
503code: "CONFIG_EMISION_NO_DISPONIBLE": no se pudo leer la configuración de emisión (base de datos no disponible). Desde el 08-10-2026 POST /dte, el lote y la emisión masiva la leen siempre, antes de validar el payload; al anular, sin ella no se verifica la doble anulación. No se consumió folio. Reintentable. Con el inventario encendido, además: 400 INVENTARIO_INVALIDO y 409 STOCK_INSUFICIENTE, también sin folio.
429Límite de tasa. Ver Límites de tasa.
500Falla inesperada nuestra. Trae error con un texto genérico (por ejemplo, { "error": "No se pudo emitir el documento por un error interno." }), sin errorType ni detalles: el detalle técnico nunca llega en la respuesta. Reconócelo por el status, no por el texto. No reintentes a ciegas: revisa primero el listado incremental por si el documento alcanzó a emitirse. Ver Errores.

La tabla vale para los tres endpoints que emiten

No solo para POST /dte: también para POST /dte/:id/anular y para la reemisión de un documento rechazado (esta última, solo desde el panel). Los tres devuelven el mismo cuerpo (error, errorType, detalles, tipoDte cuando falta folio, y emitidaId + folio + tipoDte en el 502 de envío incierto) y el mismo 409, así que una sola función de tu lado los maneja a los tres.

Además, anular responde 422 con errorType: "ENVIO_INCIERTO" si el documento original está incierto: no se emite una nota sobre algo que el SII quizá no tiene. Y responde 422 con errorType: "DOCUMENTO_RECHAZADO" (y detalles: null) si está RECHAZADO: el SII no tiene ese documento, no hay nada que anular y, si su folio se reutilizó, la nota referenciaría otro documento. Las dos cortan antes de pedir el folio de la nota.

Envío incierto (ENVIO_INCIERTO)

Hay un desenlace que no es ni «emitido» ni «falló»: el sobre se despachó al SII y la respuesta no llegó de forma legible: la conexión se cortó después de enviar, el SII no contestó a tiempo, o devolvió un 502/504 sin cuerpo. En ese caso no se puede afirmar que el SII no lo recibió.

No reintentes la emisión

La segunda emisión sale con otro folio y, si la primera entró, el SII termina con dos documentos por la misma venta, que solo se deshacen con nota de crédito. Por eso la API no reintenta ni finge un fallo limpio: responde 502.

json
{
  "error": "El envío del DTE tipo 33 folio 1042 al SII quedó INCIERTO: …. NO lo reemitas ni vuelvas a emitir la misma venta: consúltalo por folio (GET /api/empresas/:empresaId/dte/por-folio/33/1042) …",
  "errorType": "ENVIO_INCIERTO",
  "detalles": null,
  "emitidaId": "66f1c0…",
  "folio": 1042,
  "tipoDte": 33
}

tipoDte en este 502 identifica el documento; no es el tipoDte del 409, que dice qué timbrar. Distingue siempre por errorType, nunca por la presencia del campo.

Cómo queda guardado

CampoValorPor qué
estadoSiiENVIO_INCIERTONo es un veredicto (el SII no dijo nada) ni un estado intermedio (no hay trackid por el cual preguntar).
trackidnullEl SII no lo entregó. GET /dte/:id/estado responde 422 con code: "ENVIO_INCIERTO_SIN_TRACKID".
folioRetenidoPorRevisartrueEl folio no vuelve al pool: puede estar consumido en el SII.
intentoel calculado antes del envíoUna reutilización posterior del folio no choca con el índice único.
xmlDte, ted, montos, receptor, detalleslos del documento que viajóEl registro es completo: cuando se resuelva, el PDF, el libro y la certificación funcionan sobre él.

Qué hacer de tu lado

  • No reintentes la emisión de esa venta, ni por POST /dte ni en un lote nuevo. Tampoco existe reemisión: el endpoint de reemitir lo rechaza (solo se reemite un RECHAZADO).
  • Guarda emitidaId y folio con tu venta, igual que harías con un 201.
  • Consúltalo cuando quieras saber en qué quedó: GET /api/empresas/:empresaId/dte/por-folio/:tipoDte/:folio. Mientras estadoSii siga en ENVIO_INCIERTO, la venta está en revisión.
  • Filtra los pendientes con GET .../sii-emision/documentos?estado=ENVIO_INCIERTO.

Mientras está incierto, el documento no se contabiliza (centralización), no suma en el libro de ventas (aparece en pendientes[]), no va al IECV y no dispara ningún webhook mientras siga en ese estado: dte.rechazado sale cuando se resuelve como no recibido o con el folio anulado (sin veredicto del SII), y dte.aceptado / dte.aceptado_reparos / dte.rechazado cuando se confirma que el SII lo recibió y llega su veredicto. En la consulta pública de boletas viaja como estadoSii: "ENVIO_INCIERTO" y la página lo muestra como «en proceso», nunca como aceptada.

Cómo sale un documento de ENVIO_INCIERTO

De tu lado no hay que llamar a nada para resolverlo. Cuando se resuelve, lo ves cambiar de estado en la consulta por folio, en el listado por cursor y por webhook. Pero no hay un plazo garantizado: puede quedar en ENVIO_INCIERTO hasta que alguien lo resuelva a mano.

TipoQuién lo resuelve
33, 34, 46, 52, 56, 61, 110, 111, 112La plataforma intenta resolverlo sola: le pregunta al SII por ese folio cada pocos minutos. En exportación (110, 111 y 112), con el total en la moneda de venta (ver Documentos de exportación).
39, 41 (boletas)Solo a mano. La consulta por folio del SII responde «no recibido» incluso para boletas que aceptó, así que la plataforma no le pregunta: un usuario con rol admin de la empresa (o un superadmin de la plataforma) la resuelve desde el panel, después de verificarla en el portal del SII.

Lo que puede pasar con una factura, guía o nota incierta:

El SII responde que…Estado en que quedaFolioWebhook
No tiene el documento, y ya pasaron 15 minutos (por defecto) desde el envíoRECHAZADOVuelve al pool y se reutilizadte.rechazado
El folio está anuladoRECHAZADO, con folioQuemadoEnSii: true y folioAnuladoEnSii: trueNo vuelve al pool: se emite con uno nuevodte.rechazado
Sí lo tiene, con su trackidREC, con ese trackid, y sigue el ciclo normal hasta el veredictoConsumido, como el de cualquier documento emitidoEl del veredicto (dte.aceptado, dte.aceptado_reparos o dte.rechazado), cuando llegue

«Sí lo tiene» incluye un documento recibido que además tiene encima una nota que lo modifica o lo anula: el SII responde MMD (12, «Existe Nota de Debito que Modifica Montos Documento»), MMC (13, «Existe Nota de Credito que Modifica Montos Documento»), AND (14, «Existe Nota de Debito que Anula Documento») o ANC (15, «Existe Nota de Credito que Anula Documento»), y se trata igual que un documento recibido: el folio está consumido y nunca vuelve al pool. Se observaron en certificación con documentos de exportación.

Un «no lo tiene» antes de esos 15 minutos no se cree: el SII puede estar registrando todavía el envío, y se le vuelve a preguntar. El documento sigue en ENVIO_INCIERTO, y queda para resolverlo a mano desde el panel, cuando:

  • el SII tiene ese folio con otros datos;
  • dice que lo tiene, pero sin un trackid utilizable;
  • no da una respuesta clara después de muchas consultas;
  • la configuración de emisión vigente de la empresa ya es de otro RUT emisor o de otro ambiente que el documento (por ejemplo, se activó o se apagó el modo demo después de emitir): la plataforma no puede preguntarle al SII con ese certificado y no lo consulta. Este caso no lo marca para revisión humana: se vuelve a intentar en cada vuelta y se resuelve solo si la configuración vuelve a coincidir con el documento. Mientras no coincida, la única salida es resolverlo a mano.

Resuelto a mano (boletas, o lo que la plataforma no pudo decidir) en Documentos emitidos, con «Resolver envío sin confirmar», termina en los mismos estados: como recibido, vuelve a REC con su trackid y sigue el ciclo normal; como no recibido, pasa a RECHAZADO, su folio vuelve al pool (salvo que el SII ya lo tenga como consumido) y sale dte.rechazado.

Un RECHAZADO que sale de un envío incierto no trae veredicto del SII: trackid sigue en null y GET /dte/:id/estado responde 422 (ver Estado en el SII).

Qué cuenta como incierto, y qué no

  • Incierto (502): un corte con la conexión ya establecida (read ECONNRESET, socket hang up), el timeout del envío (SII_DTE_UPLOAD_TIMEOUT_MS, 120 s por defecto, en los dos canales), una respuesta HTTP sin estado legible del SII (un 502/504 de proxy) y un «recibido» sin trackid.
  • No incierto (422, sin registro): un STATUS ≠ 0 del SII es un rechazo normal. Una conexión que nunca se estableció se reintenta (3 veces en facturas y notas, 1 vez en boletas para no dejar al POS esperando minutos) y, si se agota, responde 422. Lo mismo si el SII no entrega el token del canal de upload a tiempo: cada llamada de semilla y de token tiene un tope total de SII_DTE_SOAP_TIMEOUT_MS (30 s por defecto, reintentos incluidos) y, pasado ese tope, la emisión responde 422: el documento no se envió.
  • El registro existe antes del 502: el documento queda guardado antes de que recibas la respuesta. Si ni así se pudo guardar (se reintenta una vez), el 502 llega igual, con emitidaId: null y con folio y tipoDte, y el folio no vuelve al pool. Nunca se convierte en un 422 genérico.

Reintentos seguros: Idempotency-Key

Un timeout de tu lado no dice si el documento se emitió. Si reintentas sin más, la segunda emisión pide otro folio y, si la primera llegó al SII, quedan dos documentos por la misma venta. Para reintentar sin ese riesgo, manda la cabecera Idempotency-Key en POST /api/empresas/:empresaId/dte (la emisión unitaria; el lote tiene su propia idempotencyKey en el cuerpo). Es opcional: sin ella, todo funciona exactamente igual que siempre. Sigue el borrador IETF draft-ietf-httpapi-idempotency-key-header-07.

bash
curl -X POST "https://api.miaplicacion.cl/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
  -d '{ "tipo": 39, "items": [{ "nombre": "Cambio de aceite", "cantidad": 1, "precio": 35000 }] }'
  • Formato: de 1 a 128 caracteres con letras sin tilde, dígitos, -, _, . o :. Usa un UUID nuevo por documento. También se acepta entre comillas dobles (la forma de String de RFC 8941). Una clave mal formada, o más de una en la misma petición, responde 400 con su detalle en detalles[], junto con los errores del payload.
  • Alcance: la clave es de tu empresa, y solo la puede repetir la misma credencial (la misma API key o el mismo usuario) que la usó primero.
  • Mismo cuerpo, misma clave: si la emisión original ya terminó, recibes la MISMA respuesta (status y cuerpo), sin otra emisión ni otro folio. Vale también para sus errores (un 422 del SII o un 502 de envío incierto se repiten tal cual). Única diferencia: al repetir un 5xx de una emisión que ya había tomado folio, el cuerpo agrega idempotencia: { tipoDte, folio, consulta } con el documento por folio que hay que revisar. El cuerpo se compara completo, sin importar el orden de las claves JSON.
  • Otro cuerpo con la misma clave (o desde otra credencial): 422 IDEMPOTENCY_KEY_REUTILIZADA y no se emite nada.
  • La original todavía en curso: 409 IDEMPOTENCIA_EN_CURSO. Espera unos segundos y reintenta con la misma clave. El cuerpo trae idempotencia.consulta, con el documento por folio si la emisión alcanzó a tomarlo; si no, el listado.
  • Cuándo no queda guardada: si la emisión se cortó antes de pedir el folio (payload inválido, cortes de ambiente, NO_FOLIOS, STOCK_INSUFICIENTE, doble anulación, configuración), no se consumió nada y la misma clave se puede volver a usar.
  • Vencimiento: una clave terminada se recuerda 24 horas desde que terminó. Pasado ese plazo, la misma clave emite un documento nuevo: no reintentes con una clave vieja.
  • Una emisión interrumpida (nuestro proceso se cayó a mitad) deja la clave en curso para siempre: nunca se libera sola, porque pudo haber consumido el folio. Consulta el documento por folio y, si no aparece ahí ni en el listado, emítelo con una clave nueva.
  • Si la base no responde al verificar la clave: 503 IDEMPOTENCIA_NO_DISPONIBLE, sin emitir nada; reintenta con la misma clave.

409 con la emisión original en curso

json
{
  "error": "Ya hay una emisión con esta Idempotency-Key en curso, o se interrumpió antes de responder: no se emitió otro documento. Reintenta en unos segundos con la misma clave para recibir su respuesta. Tomó el folio 1042 (tipo 33): si sigue en curso, consúltalo con GET /api/empresas/66f0a1b2c3d4e5f607182931/dte/por-folio/33/1042 antes de emitir el documento con otra clave.",
  "code": "IDEMPOTENCIA_EN_CURSO",
  "idempotencia": {
    "estado": "en_curso",
    "desde": "2026-10-14T13:05:12.000Z",
    "tipoDte": 33,
    "folio": 1042,
    "consulta": "GET /api/empresas/66f0a1b2c3d4e5f607182931/dte/por-folio/33/1042"
  }
}

422 con la misma clave y otro cuerpo

json
{
  "error": "Esta Idempotency-Key ya se usó con otro pedido: no se emitió nada.",
  "code": "IDEMPOTENCY_KEY_REUTILIZADA",
  "detalles": [
    "Idempotency-Key: esta clave ya se usó con otro cuerpo. Para reintentar el MISMO documento manda exactamente el mismo cuerpo; para un documento distinto (o corregido), usa una clave nueva."
  ]
}

Anular un documento

http
POST /api/empresas/:empresaId/dte/:id/anular

Scope: dte:anular. Cuerpo opcional { "motivo": "…", "items": [...] }.

El SII no tiene «anulación»: tiene una nota con CodRef 1 que referencia al original. Este endpoint resuelve por ti el tipo, folio y fecha de referencia, y también qué nota se emite: sobre cualquier documento, una nota de crédito 61; sobre una nota de crédito, una nota de débito 56 (TpoDocRef 61, el folio y la fecha de la nota de crédito), porque una nota de crédito no se anula con otra nota de crédito. Sin items, la nota replica el detalle completo (anulación total).

Al anular una nota de crédito la réplica es tal cual: la 61 y la 56 van las dos con precios NETOS, y la nota de débito declara el mismo neto, exento e IVA que la nota de crédito. El motivo por defecto es Anula nota de crédito N° <folio>. Antes, anular una 61 respondía 422; ahora emite la nota de débito.

Un :id que no existe, que no tiene formato de id o que es de otra empresa responde lo mismo, 404 { "error": "Documento no encontrado" }, sin consumir nada: la respuesta no revela si el documento existe en otra empresa.

Anular consume un folio de tipo 61 (de tipo 56 si anulas una nota de crédito).

Una sola anulación por documento: 409

Cada llamada a anular emite una nota de crédito real. Para que un doble clic o un reintento tras un timeout de red no anulen dos veces el mismo documento (dos notas, dos folios del 61), la API corta antes de pedir el folio en dos casos. Los dos responden 409 con code (y errorType y detalles en null).

DOCUMENTO_YA_ANULADO — ya existe una nota del tipo que anula ese documento (61; o 56 si el documento es una nota de crédito) que:

  • es de la misma empresa, del mismo ambiente y del mismo modo demo que el documento;
  • lo referencia (mismo tipo y folio) con CodRef 1 (anula). Las notas CodRef 2 o 3, que corrigen texto o montos, no cuentan. Tampoco una nota de otro tipo: la nota de crédito 61 folio 5 la anula una 56 que referencia 61/5, no una 61 que referencie otra cosa con el folio 5;
  • no fue rechazada por el SII. En proceso, aceptada, con reparos o en ENVIO_INCIERTO sí cuenta: puede terminar aceptada;
  • si es una nota de crédito 61, no está anulada a su vez por una nota de débito 56 CodRef 1 (TpoDocRef 61, su folio) de la misma empresa, ambiente y modo demo, aceptada por el SII (con o sin reparos). Anular una nota de crédito deja vigente otra vez el documento que anulaba, y se puede volver a anular. Si esa nota de débito está en proceso, en ENVIO_INCIERTO, sin veredicto o rechazada, la nota de crédito sigue contando. Es un solo nivel: no importa si la nota de débito fue anulada a su vez.
json
HTTP/1.1 409 Conflict
{
  "error": "El documento tipo 39 folio 20 ya fue anulado por la nota de crédito tipo 61 folio 7 (estado ACEPTADO). No se emite otra: consumiría un folio y anularía dos veces el mismo documento. Solo si el SII rechaza esa nota se puede volver a anular.",
  "code": "DOCUMENTO_YA_ANULADO",
  "errorType": null,
  "detalles": null,
  "notaCredito": { "id": "66f1c0…", "folio": 7, "estadoSii": "ACEPTADO" }
}

Cuando el documento es una nota de crédito, la nota que ya existe es una 56 y viaja en notaDebito (misma forma), y el mensaje nombra la nota de débito tipo 56.

Si esa nota quedó en ENVIO_INCIERTO, el mensaje lo dice y pide resolver ese envío primero:

texto
El documento tipo 39 folio 20 ya tiene una nota de crédito que lo anula (tipo 61 folio 7), pero su envío al SII quedó en ENVIO_INCIERTO: el SII puede haberla recibido. Primero hay que resolver ese envío (consúltalo por folio: GET /api/empresas/:empresaId/dte/por-folio/61/7); mientras tanto no se emite otra nota. Si el SII nunca la registró o la rechaza, se podrá anular de nuevo.

ANULACION_EN_CURSO — otra petición está anulando ese mismo documento en este momento (su nota todavía no queda guardada):

texto
Ya hay una anulación en curso del documento tipo 39 folio 20: otra petición está emitiendo su nota de crédito en este momento. No la repitas: espera a que termine y consulta el documento. Si esa anulación falla sin emitir la nota, podrás volver a intentarlo.

La reserva se suelta apenas la otra anulación termina (bien o mal). Si el proceso se cayera en medio, vence sola a los 15 minutos (con el timeout de envío por defecto).

  • POST /dte con una nota 61 CodRef 1 (o sin codRef, que por defecto es 1), o con una nota 56 CodRef 1 que referencia una 61, pasa por el mismo corte: es la misma operación por otro camino.
  • En un lote, la nota que anula (61 CodRef 1, o 56 CodRef 1 sobre una 61) que choca queda fallido con el code en su errorType (DOCUMENTO_YA_ANULADO, ANULACION_EN_CURSO, CONFIG_EMISION_INVALIDA o CONFIG_EMISION_NO_DISPONIBLE), sin folio (no se consumió nada), y el resto del lote sigue. Si un mismo lote trae dos notas que anulan el mismo folio, la primera se emite y la segunda sale DOCUMENTO_YA_ANULADO.
  • La reemisión (solo panel) de una nota que anula (61 CodRef 1, o 56 CodRef 1 sobre una 61) rechazada pasa por el mismo corte: si mientras tanto el documento se anuló con otra nota, no se reemite, y responde el mismo 409 con el mismo cuerpo. Antes esa ruta devolvía un 400 con solo el texto: si tu manejador trataba ese 400 como caso especial, pásalo a leer el code del 409.

La nota sale con la configuración de hoy: 422 si no calza con el documento

La nota de crédito sale en el ambiente del documento que anula, aunque la empresa haya cambiado de ambiente desde entonces, con la resolución y los folios de ese ambiente y la misma regla de autorización (403 AMBIENTE_NO_AUTORIZADO o 422 RESOLUCION_DEL_AMBIENTE_INVALIDA; una key mk_cert_ nunca anula un documento de producción: 403). Lo que no se puede cambiar es el modo: si desde que emitiste el documento la empresa apagó (o encendió) el modo demo, la nota saldría con otro emisor y no lo anularía ante el SII. anular lo detecta antes del folio:

json
HTTP/1.1 422 Unprocessable Entity
{
  "error": "El documento tipo 39 folio 20 se emitió en certificacion en modo demo, pero con la configuración actual de la empresa la nota de crédito saldría en certificacion con folios propios. Esa nota no anularía este documento ante el SII: no se emitió nada ni se consumió folio. Para anularlo, vuelve la configuración de emisión al ambiente y al modo del documento.",
  "code": "CONFIG_DISTINTA_DEL_DOCUMENTO",
  "errorType": null,
  "detalles": null
}

Y sin una configuración de emisión utilizable no se anula: sin ella no hay cómo verificar que el documento no esté ya anulado. Dos respuestas, las dos antes del folio:

CausaRespuesta¿Reintentar?
La configuración no sirve para emitir (no existe, la emisión está desactivada, falta el certificado o el emisor demo de la plataforma no está disponible).422 CONFIG_EMISION_INVALIDA, con el mensaje de la configuración (por ejemplo, La emisión directa con el SII está desactivada para esta empresa.).No: primero hay que corregirla.
La configuración no se pudo leer (la base de datos no respondió).503 CONFIG_EMISION_NO_DISPONIBLE. El detalle técnico no viaja en la respuesta.Sí: es transitorio, reintenta en unos minutos.

Qué code sale por cada camino

CONFIG_EMISION_INVALIDA y CONFIG_EMISION_NO_DISPONIBLE valen igual para POST /dte con una nota que anula (61 CodRef 1, o 56 CodRef 1 sobre una 61) y para el lote. CONFIG_DISTINTA_DEL_DOCUMENTO no: esos dos caminos no cargan el documento referenciado, así que no tienen con qué comparar la configuración. Ese 422 solo sale al anular y al reemitir.

Sin folios al anular: 409, igual que al emitir

Anular responde exactamente igual que emitir cuando no hay folio, y con tipoDte: 61, el tipo de la nota de crédito, no el del documento que estás anulando. Al anular una nota de crédito, la que pide folio es la nota de débito: sin folios del 56 responde el mismo 409 con tipoDte: 56.

json
{
  "error": "No quedan folios disponibles para el DTE tipo 61. Carga un nuevo CAF desde el SII.",
  "errorType": "NO_FOLIOS",
  "detalles": null,
  "tipoDte": 61
}

Es el camino donde más se nota: el SII autoriza folios de nota de crédito de a uno, así que es el tipo que se agota primero. Si automatizas el timbraje, usa el tipoDte de la respuesta y no el tipo del documento original: timbrar boletas no te deja anular una boleta.

Cambio de comportamiento para quien ya consume la API

Antes, anular sin folios devolvía 422 con un { error } sin código: había que leer el texto para saber que faltaba timbrar. Ahora devuelve 409 con errorType y tipoDte, igual que POST /dte.

Los 422 de anular que no son de folios (documento mixto antiguo, rechazo del SII…) siguen siendo 422. Lo que cambió es solo el caso «no hay folio»: si tratabas cualquier 4xx de anular como error definitivo, ahora puedes distinguir el que se resuelve timbrando.

La anulación hereda la condición del original

No tienes que marcar nada. Anular una 34 o una 41 produce una nota de crédito exenta, automáticamente. Anular un documento mixto conserva qué línea era exenta y cuál no.

Antes no: anular una boleta exenta 41 de $50.000 emitía una nota afecta de $59.500 (IVA sobre algo que nunca lo tuvo) que después había que anular con otra nota de crédito. Hoy sale exenta y cuadra al peso.

OriginalQué emite la nota
34 o 41 (exento por tipo)Todas las líneas exentas. MntExe = MntTotal, sin IVA.
33, 39 o 52 con líneas mixtasLa marca por línea guardada en el documento original.
46 (factura de compra)Todas afectas: POST /dte rechaza items[].exento en un 46, así que su detalle guardado nunca tiene líneas exentas. Al anularlo sí puedes mandar items con exento, pero se rechaza con 422 (ver abajo, la anulación de un 46).
Documento mixto antiguo, sin la marca por línea422

Si mandas items explícitos, mandas tú: ahí hablas la convención de la nota (precios NETOS y exento por línea) y nada se hereda. Lo único que se hereda igual es la retención de IVA del original: una nota parcial sobre una factura de compra sigue siendo un documento con retención.

La anulación de un 46 reversa la retención

Cambio de contrato para quien ya consume la API

La nota que anula una factura de compra (46), o una nota de débito 56 que la modifica, declara la MISMA retención de IVA que el documento original: <ImptoReten> en el encabezado, <CodImpAdic> en cada línea y, por lo tanto, un MntTotal distinto. Con retención total pasa de neto + IVA a neto; con retención parcial, a neto + IVA − retenido. Antes la nota salía sin retención y devolvía un IVA que el vendedor nunca cobró. Si concilias contra el MntTotal de la nota, este es el número que cambia.

El código viaja resuelto desde el original (un codRetencion: 30 emitido con retencionTotal: true se guardó como 301, y es el 301 el que reversa la nota). Aplica también con items explícitos. En los tipos que no retienen (33, 34, 39, 41, 52) la nota no lleva retención, igual que siempre.

Cortes de anular, todos antes de pedir el folio

La nota pide su propio folio del 61, que se consume aunque el documento nunca llegue a existir. Por eso todo lo que se puede rechazar mirando el payload y el documento original se rechaza antes de pedirlo: en ninguno de estos casos se consume nada.

SituaciónRespuesta
El original declara un código de retención que no está en la tabla del SII.422 El documento tipo 46 folio 7 declara el código de retención 99, que no está en la tabla del SII (…), así que la nota que lo anula no puede reversar esa retención. Revisa el documento original.
Mandas items con alguna línea exento: true al anular un documento que retiene IVA.422 El DTE 61 (Nota de crédito electrónica) no admite líneas exentas (items[].exento): declara una retención de IVA sobre el neto, y una línea sin IVA dejaría el MntTotal descuadrado contra el detalle.
Mandas items que no es un arreglo con al menos un elemento ([], un string, un objeto).422 items debe ser un arreglo con al menos un detalle.
Mandas items cuyos montos suman 0 ([{}], todo a precio: 0, una línea que su propio descuento anula).422 El total del documento debe ser mayor que cero.
Mandas items con una línea de monto negativo (precio negativo, o descuento mayor que la línea).422 Ítem 1 ("Producto") con monto negativo: el SII lo rechaza.
Mandas items con una línea que no es un objeto (null, un número, un arreglo).422 items[1] tiene que ser un objeto con el detalle de la línea (nombre, cantidad, precio); llegó null.
Mandas items con más de 60 líneas.422 Un DTE admite hasta 60 líneas de detalle (enviaste 61).
El original quedó guardado sin un RUT de receptor válido (ausente, vacío, "N/A", dígito verificador malo) y es de un tipo que lo exige desde su emisión (todo lo que no es boleta 39/41).422: el registro está corrupto y la nota no puede emitirse contra el consumidor final (66666666-6). Revisa el documento original.
Anulas sin items y el detalle guardado no suma lo que declara el encabezado del documento (un detalle que no corresponde al documento).422, con un texto según el canal. Boleta 39/41 (detalle bruto): El documento tipo 39 folio 7 totaliza $10000, pero su detalle guardado suma $9000. Manda "items" con el detalle que la nota debe anular. Todo lo demás (detalle neto): El documento tipo 33 folio 7 declara $11010233 netos y $0 exentos, pero su detalle guardado suma $11010232. Manda "items" con el detalle que la nota debe anular.
Anulas sin items una boleta cuyo detalle guardado no permite armar una nota que cuadre con su total (por ejemplo, un registro migrado con una línea de descuento negativa).422, con un margen de 1 peso (el redondeo del 19%): El documento tipo 39 folio 20 no se puede anular replicando su detalle guardado: la nota no cuadraría con el total del documento. El detalle afecto suma 10000 neto, que con IVA da 11900, pero se pidió que totalizara 10000: son 1900 pesos de diferencia y el margen es 1 (el redondeo del 19%). Revisa cómo se repartió el neto entre las líneas. Manda "items" con el detalle que la nota debe anular.
Ya existe una nota vigente que anula el documento, u otra anulación en curso.409 DOCUMENTO_YA_ANULADO / ANULACION_EN_CURSO: ver Una sola anulación por documento.
La configuración de emisión de hoy está en otro modo (demo / folios propios) que el documento. (Un ambiente distinto no corta: la nota sale en el del documento.)422 CONFIG_DISTINTA_DEL_DOCUMENTO: ver La nota sale con la configuración de hoy.
La configuración de emisión no sirve para emitir (no existe, desactivada, sin certificado, emisor demo no disponible).422 CONFIG_EMISION_INVALIDA, con el mensaje de la configuración.
No se pudo leer la configuración de emisión de la empresa (base de datos no disponible).503 CONFIG_EMISION_NO_DISPONIBLE
El documento original está en ENVIO_INCIERTO.422 con errorType: "ENVIO_INCIERTO": ver Envío incierto.
El documento es un mixto antiguo sin la marca por línea.422 { error }

Para anular solo la parte exenta de una operación que retiene IVA, emite esa parte en un documento aparte. Omitir items (o mandarlo null) sigue significando «anulación total», que no es un caso degenerado.

Anular una boleta al público: la nota va contra el consumidor final

La nota de crédito hereda el receptor del documento que anula, y el 61 exige receptor con RUT válido. Para una boleta 39/41 al público sin identificar, ese receptor es el RUT genérico del consumidor final: la nota sale con <RUTRecep>66666666-6</RUTRecep><RznSocRecep>Consumidor final</RznSocRecep>. No tienes que mandar nada distinto: la llamada es la misma, con o sin items.

  • Vale para la boleta emitida por esta API (se guardó con 66666666-6) y para registros antiguos o migrados sin un RUT de receptor utilizable (ausente, null, vacío, "N/A", dígito verificador malo).
  • Si la boleta guardó una razón social, esa manda. Una boleta con receptor identificado (RUT válido y distinto del genérico) hereda su RUT y su razón social; si no guardó razón social, la API no inventa «Consumidor final» para un RUT real: la nota sale con el relleno Receptor del armador del XML.
  • Cualquier otro tipo (33, 34, 46, 52, 56) sin un RUT de receptor válido sigue respondiendo 422, antes del folio: ahí no es una venta al público sino un dato corrupto. Lo mismo para un tipo que no esté en el catálogo: el corte es fail-closed.

Cambio de comportamiento para quien ya consume la API

Una boleta sin RUT de receptor respondía 422 («no se puede anular por esta vía»), y una con un RUT ilegible fallaba después de pedir el folio del 61. Ahora las dos emiten la nota (y consumen el folio del 61). Si tu código trataba ese 422 como «anúlala por el portal del SII», revísalo: repetir la anulación en los dos lados emitiría dos notas de crédito sobre la misma boleta.

Anular sin items funciona en cualquier documento afecto

Anular sin items una factura 33, una guía 52, una nota de débito 56 o una factura de compra 46 con retención parcial respondía siempre 422, culpando al detalle guardado: el chequeo comparaba el detalle neto contra el MntTotal, que en un documento afecto es neto + IVA. Ahora se mide contra el neto declarado y emite la nota que corresponde, cuadrada peso a peso. Si armaste el workaround de mandar siempre items, sigue funcionando igual. La boleta (39/41) nunca estuvo afectada.

422 al anular un documento mixto antiguo

Los documentos emitidos antes de este cambio guardaron cuánto sumaba lo exento (montoExento), pero no qué línea lo era. Con un original mixto, repartir el IVA a ojo emitiría un documento tributario incorrecto, así que la anulación se corta antes de pedir el folio con un 422:

json
{
  "error": "El documento tipo 39 folio 20 tiene $5000 exentos, pero su detalle guardado no registra qué líneas lo eran (se emitió antes de que se guardara esa marca). Manda \"items\" con el detalle que la nota debe anular, con \"exento\": true en las líneas exentas."
}

La salida es la que dice el mensaje: repetir la llamada con items explícitos. Un documento enteramente exento antiguo (donde montoExento es igual al total) no necesita nada: ahí no hay nada que adivinar.

La nota de crédito cuadra peso a peso con el documento que anula

El MntTotal de la nota es idéntico al del documento referenciado: no hay desvío de redondeo, ni con varias líneas, ni con cantidades grandes, ni con descuentos por línea. Si concilias saldos comparando el original contra su nota, la diferencia es siempre 0.

La boleta lleva precios brutos y la nota los lleva netos, pero la conversión no divide el precio unitario por 1,19: parte del monto de cada línea, reparte el neto del documento entre ellas y hace que la nota declare el mismo neto y el mismo IVA que declaró el original. Recalcular el IVA no alcanza, porque neto + round(neto × 19%) no puede producir cualquier total bruto.

Lo que sí cambia y se ve en el detalle: cuando la cantidad es mayor que 1, el precio unitario de la nota puede salir redondeado hacia arriba con un descuento que lo compensa. Una línea de 5 unidades que reversa $5.231 netos sale como "precio": 1047, "descuento": 4 (5 × 1.047 − 4 = 5.231), porque el monto de la línea no siempre es divisible por la cantidad y el SII no admite descuentos negativos. El monto de la línea cuadra exacto. Con cantidad 1 no cambia nada.

Emisión masiva (lote)

http
POST /api/empresas/:empresaId/dte/lote
GET  /api/empresas/:empresaId/dte/lote
GET  /api/empresas/:empresaId/dte/lote/:loteId

Scopes: dte:emitir para crear, dte:leer para consultar. Los mismos que la emisión unitaria.

N documentos en una petición. Cada elemento de documentos[] tiene exactamente la forma del cuerpo de POST /dte (mismos campos, mismas reglas de precios brutos/netos, misma validación).

json
{
  "idempotencyKey": "cierre-caja-2026-09-11-caja-3",
  "documentos": [
    { "tipo": 39, "items": [{ "nombre": "Café", "precio": 1500 }] },
    { "tipo": 33, "cliente": { "rut": "76086428-5", "razonSocial": "Cliente SpA", "giro": "Comercio", "direccion": "Calle 1", "comuna": "Santiago" },
      "items": [{ "nombre": "Servicio", "precio": 100000 }], "formaPago": 2 }
  ]
}
CampoObligatorioNotas
idempotencyKeysí1 a 128 caracteres, único por empresa. Identifica este envío.
documentossí1 a 100 elementos (SII_LOTE_MAX_DOCUMENTOS). Cada uno con la forma de POST /dte, salvo logoUrl. Pasarse del tope es un 400 code: "LOTE_PAYLOAD".
logoUrlnoEl logo de la empresa por URL, una vez por lote, con las mismas reglas que en POST /dte.

logoUrl va a nivel del lote, no dentro de cada documento: el logo es de la empresa, y N URLs serían N descargas para quedarse con la última. Un documento que trae la clave (con cualquier valor, también vacío o null) no se ignora en silencio: el lote se rechaza con 400 LOTE_INVALIDO en ese índice. Un logoUrl del lote con formato inválido es un 400 LOTE_PAYLOAD. El logo se descarga antes de crear el lote y de responder el 202 (la petición puede tardar hasta 5 s más); si falla, o quien crea el lote es un usuario emisor, el lote se emite igual con el logo anterior y el 202 trae avisos (LOGO_NO_ACTUALIZADO / LOGO_NO_AUTORIZADO), que también quedan en la bitácora del lote.

Dos fases con reglas distintas, a propósito

1. Validación (sin tocar folios). Se validan los N documentos con la misma validación de POST /dte. Si uno solo falla, se rechaza el lote entero: no se crea nada, no se emite nada, no se consume ningún folio, y la respuesta trae todos los errores juntos, indexados por posición:

json
{
  "error": "Lote rechazado: 2 de 4 documento(s) con errores de validación. No se emitió nada ni se consumió ningún folio. Corrige y reenvía el lote completo.",
  "code": "LOTE_INVALIDO",
  "detalles": [
    { "indice": 1, "errores": ["items debe ser un arreglo con al menos un detalle."] },
    { "indice": 3, "errores": ["Tipo de DTE no soportado: 99. Soportados: 33, 34, 39, 41, 46, 52, 56, 61."] }
  ]
}

Corriges y reenvías el mismo lote con la misma idempotencyKey (no se guardó nada, así que sigue libre). Todo o nada porque un folio se consume al pedirlo: emitir N−1 y rechazar uno te dejaría con N−1 folios consumidos y un lote que ya no puedes reenviar sin duplicarlos.

2. Emisión (folios ya comprometidos). Responde 202 con el lote en pendiente y los documentos se emiten uno a uno, en orden, en segundo plano. Desde acá cada documento es independiente: si el SII rechaza el 7.º, los 6 anteriores siguen emitidos y el 8.º se emite igual.

json
{
  "lote": {
    "id": "66f1c0…",
    "estado": "pendiente",
    "total": 2, "emitidos": 0, "fallidos": 0,
    "documentos": [
      { "indice": 0, "tipoDte": 39, "estado": "pendiente" },
      { "indice": 1, "tipoDte": 33, "estado": "pendiente" }
    ]
  },
  "mensaje": "Lote validado y emisión iniciada en segundo plano. Consulta GET .../dte/lote/:loteId para seguir el avance."
}

El que falla queda fallido con su error. Un fallido sin folio es el único que se puede volver a mandar. Según el errorType:

Documento fallidoQué significa
errorType: "NO_FOLIOS" / "CAF_VENCIDO"No se consumió nada y se arregla timbrando.
errorType "DOCUMENTO_YA_ANULADO", "ANULACION_EN_CURSO", "CONFIG_EMISION_INVALIDA" o "CONFIG_EMISION_NO_DISPONIBLE"Una nota que anula (61 CodRef 1, o 56 CodRef 1 sobre una 61) que chocó con el corte de doble anulación. Sin folio consumido. Ver Una sola anulación por documento.
errorType: "ENVIO_INCIERTO", con folio y dteEmitidoIdEl folio sí se consumió y el SII puede tener el documento. No lo incluyas en el lote nuevo de «los que faltan»: consúltalo por folio (ver Envío incierto).
errorType "STOCK_INSUFICIENTE", "INVENTARIO_INVALIDO" (u otro código de inventario), "INVENTARIO_NO_DISPONIBLE" o "CONFIG_EMISION_NO_DISPONIBLE"Con el inventario encendido, el documento no pudo reservar su stock justo antes de su folio. Sin folio consumido; el lote sigue con el siguiente.

Con el inventario encendido, el 400 LOTE_INVALIDO trae también los errores de inventario de cada documento y los del lote sumado (la misma serie en dos documentos y, con bloquearSinStock, el documento con el que el acumulado pasa lo disponible). Si no se pudo leer la configuración de emisión, el lote responde 503 { error, code: "CONFIG_EMISION_NO_DISPONIBLE", detalles: [] } y no se crea.

Una línea con itemId y sin precio toma el de la lista del receptor, como en POST /dte (ver La lista de precios en la emisión), antes de validar; el precio queda guardado en el lote. Si las listas no se pudieron leer y lo único malo de los documentos es el precio que les faltaba, 503 { error, code: "LISTAS_PRECIO_NO_DISPONIBLES", detalles: [] } con No se pudieron leer las listas de precios de la empresa: no se creó el lote ni se consumió ningún folio. Reintenta en unos minutos. No se creó nada.

Seguir el avance

GET .../dte/lote/:loteId devuelve el mismo objeto con el avance (enEjecucion: true|false) y, por documento emitido, folio, trackid (string), fechaEmision, total y dteEmitidoId (el id con el que se consulta en el resto de la API). Estados del lote: pendiente → emitiendo → completado | completado_con_errores | error (se cayó fuera del ciclo por documento; lo ya emitido sigue emitido). GET .../dte/lote lista los últimos lotes de la empresa sin el detalle por documento.

CasoRespuesta de GET .../dte/lote/:loteId
:loteId sin formato de id400 { "error": "loteId inválido: \"abc\"", "code": "LOTE_ID_INVALIDO", "detalles": [] }
El lote no existe o es de otra empresa (responde igual, para no revelar que existe)404 { "error": "No existe ese lote de emisión para la empresa.", "code": "LOTE_NO_ENCONTRADO", "detalles": [] }
Error inesperado nuestro500 { "error": "Error interno en la emisión por lote", "code": "LOTE_ERROR_INTERNO", "detalles": [] }

Idempotencia

Reenviar un lote con una idempotencyKey ya usada por la empresa responde 200 con el lote existente y no emite nada de nuevo, sin importar el cuerpo. Es lo que te protege de un timeout de red después del 202: reintenta con la misma key y recibes el lote que ya está corriendo.

La key queda ocupada para siempre, sin importar cómo terminó el lote: uno en error o huérfano también la bloquea, y reintentar con ella te devuelve ese lote roto. Un lote roto es justamente el que puede tener documentos emitidos sin anotar: para lo que falta, lote nuevo con key nueva.

Lotes huérfanos

Un lote huérfano no se reanuda

Un lote en estado: "emitiendo" con enEjecucion: false quedó a medio emitir porque el proceso se cayó. No se reanuda, ni solo ni a pedido: cada documento se persiste en /dte (folio consumido, SII notificado) antes de que el lote anote el resultado. Si la caída ocurre entre ambos, el documento en vuelo sí existe en /dte y en el lote sigue pendiente; reanudarlo lo emitiría de nuevo con otro folio.

  • Los documentos emitido del lote son definitivos: tienen su folio, trackid y dteEmitidoId.
  • Los pendiente pueden o no existir: coteja contra /dte (listado incremental o por-folio) antes de darlos por no emitidos. Normalmente es solo el que seguía al último emitido.
  • Crea un lote nuevo, con una idempotencyKey nueva, solo con los que de verdad faltan.

Límites

POST /dte/lote tiene su propio cupo, SII_MAX_LOTES_POR_MINUTO (default 3 lotes por minuto y por empresa), separado de la cuota de emisión unitaria: una petición de lote compromete hasta 100 folios. El peor caso por minuto es SII_MAX_LOTES_POR_MINUTO × SII_LOTE_MAX_DOCUMENTOS folios. Exceder el cupo es un 429 con Retry-After (ver Límites de tasa).

Emisión masiva por archivo (CSV o XLSX)

http
GET  /api/empresas/:empresaId/dte/masiva/plantilla?formato=xlsx|csv
POST /api/empresas/:empresaId/dte/masiva/previsualizar   (multipart: archivo)
POST /api/empresas/:empresaId/dte/masiva/emitir          (multipart: archivo, huella opcional)
GET  /api/empresas/:empresaId/dte/masiva/:masivaId
GET  /api/empresas/:empresaId/dte/masiva/:masivaId/resultado?formato=xlsx|csv

Scopes: dte:emitir para la vista previa y la emisión, dte:leer para la plantilla, el avance y el resultado. Los mismos que el lote. La usan el panel («Emisión masiva») y, desde el 22-10-2026, una API key; con sesión, el admin y el emisor (el contador solo consulta).

Es el lote con un archivo adelante: una fila por línea de detalle, y las filas de un documento comparten idDocumento. La plantilla trae las columnas y, en XLSX, una hoja con las instrucciones de cada una. El archivo va en multipart/form-data, en el campo archivo (CSV en UTF-8 o Windows-1252, separado por ; o ,, o XLSX; hasta 5 MB y 1.000 documentos).

  • Vista previa: lee, agrupa y valida todos los documentos con las reglas del lote, sin pedir folios ni guardar nada. Responde 200 aunque haya errores, cada uno con su fila; puedeEmitir dice si se puede emitir y huella es el id que tendrá la emisión.
  • Emitir: vuelve a leer y a validar el archivo entero; si un documento falla, 400 MASIVA_INVALIDA sin pedir ningún folio. Si todo está bien, 202 con masiva (su id es el masivaId) y los lotes se emiten uno tras otro en segundo plano. Manda la huella de la vista previa: si el archivo cambió, 409 MASIVA_ARCHIVO_DISTINTO. El mismo archivo otra vez responde 200 con la emisión anterior y no emite nada. Una empresa emite un archivo a la vez (409 MASIVA_EN_CURSO).
  • Precios de lista: la columna itemId (items[].itemId) es el id de un producto o servicio del catálogo y itemVarianteId (items[].varianteId), su variante. Con itemPrecio vacío, el precio sale de la lista de precios del receptor (módulo de Ventas), en el convenio de cada tipo: BRUTO en la boleta 39, NETO en los demás (ver La lista de precios en la emisión). Por eso itemPrecio ya no es obligatoria en cada línea; el encabezado necesita itemPrecio o itemId (si no: Faltan columnas obligatorias en la primera fila: itemPrecio (o itemId). Usa la plantilla.). La huella sigue siendo la del contenido del archivo. Si las listas no se pueden leer y no hay otro error, la vista previa y la emisión responden 503 LISTAS_PRECIO_NO_DISPONIBLES sin crear nada.
  • Con una API key: los lotes quedan a nombre de la key, como los de POST /dte/lote. Una key mk_cert_ emite en certificación aunque la empresa esté en producción, y pedir produccion en la columna ambiente es 403 AMBIENTE_NO_AUTORIZADO. La vista previa y la emisión cuentan en el cupo de escritura de la key; la plantilla, el avance y el resultado, en el de lectura.
  • Límites: cada parte del archivo cuenta en el cupo de lotes de la empresa (SII_MAX_LOTES_POR_MINUTO); la vista previa tiene su propio cupo (SII_MAX_PREVISUALIZACIONES_POR_MINUTO, 20 por minuto y por empresa). Emitir no existe en la cuenta demo (403 CUENTA_DEMO_RESTRINGIDA) ni en el sandbox (403 SANDBOX_NO_DISPONIBLE).

Exportación en la emisión masiva

Solo donde el servidor habilita la exportación (SII_EXPORTACION_HABILITADA=true), la emisión masiva por archivo emite 110, 111 y 112 (ver Documentos de exportación). La plantilla trae entonces más columnas, todas del documento (se repiten iguales en sus filas). Del receptor extranjero:

texto
receptorNumId  receptorNacionalidad  receptorContacto

Van a cliente.numId, cliente.nacionalidad y cliente.contacto. Las de exportacion:

texto
exportacionMoneda  exportacionTipoCambio  exportacionIndServicio  exportacionTipoDespacho
exportacionFormaPago  exportacionFechaCancelacion
exportacionTerminosPagoCodigo  exportacionTerminosPagoGlosa  exportacionTerminosPagoDias
exportacionModalidadVenta  exportacionClausulaVenta  exportacionTotalClausulaVenta
exportacionViaTransporte  exportacionNombreTransporte  exportacionRutCiaTransporte
exportacionNombreCiaTransporte  exportacionIdAdicTransporte  exportacionBooking  exportacionOperador
exportacionPuertoEmbarque  exportacionIdAdicPuertoEmbarque  exportacionPuertoDesembarque
exportacionIdAdicPuertoDesembarque
exportacionTara  exportacionUnidadTara  exportacionPesoBruto  exportacionUnidadPesoBruto
exportacionPesoNeto  exportacionUnidadPesoNeto  exportacionTotalItems  exportacionTotalBultos
exportacionFlete  exportacionSeguro
exportacionPaisReceptor  exportacionPaisDestino
exportacionDestinoDireccion  exportacionDestinoComuna  exportacionDestinoCiudad

Cada una va al campo de exportacion de su nombre (exportacionMoneda a exportacion.moneda), salvo exportacionFormaPago (a exportacion.formaPagoExportacion), las tres exportacionTerminosPago… (a exportacion.terminosPago) y las tres exportacionDestino… (a exportacion.destino). Lo obligatorio lo decide la misma validación de POST /dte según el tipo; la hoja «Instrucciones» de la plantilla lo dice columna por columna.

  • Las reglas son las del lote: cada documento lleva su fecha y su exportacionTipoCambio escritos (la emisión masiva emite en segundo plano y no los busca), con los mismos errores de Documentos de exportación, todos antes del primer folio.
  • Precios, cantidades y montos van en la moneda de venta, con coma decimal (3,25), y viajan como texto decimal exacto, sin redondear. En las notas 111 y 112 sobre una 110, refCodigo es obligatorio.
  • En las columnas de exportación y en itemPrecio e itemCantidad de una 110, 111 o 112, un monto con un solo separador seguido de exactamente tres dígitos (1.125 o 1,125) se rechaza por ambiguo: escribe 1,1250 si es un decimal o 1125 si son miles. El error lo dice, por ejemplo itemPrecio: «1.125» es ambiguo (¿decimal o miles?): si es un decimal, usa coma y agrega un cero al final: 1,1250; si son miles, escríbelo sin separador: 1125. 1.234,5 y 12.345.678 se leen como siempre. Una celda numérica de Excel se lee como decimal exacto, sin notación científica. Los documentos que no son de exportación se leen igual que antes.
  • receptorRut va vacío (el servidor pone 55.555.555-5) y receptorEmail va a cliente.correo. receptorTelefono no va: con dato, el documento tiene el error receptorTelefono no va en un documento de exportación (110, 111 y 112): bórralo de las filas de este documento.
  • Una columna de exportación con dato en un documento de otro tipo también es error, por ejemplo exportacionMoneda: esta columna es solo de los documentos de exportación (110, 111 y 112) y este documento es tipo 33: bórralas de sus filas.
  • Los tipos de bulto (exportacion.tiposBulto) no caben en el archivo: un documento que los necesite se emite con POST /dte o con el lote. Tampoco van descuentos ni recargos, retención, transporte…, formaPago, fechaVencimiento ni medioPago.
  • El total de cada documento en la vista previa (y la suma de la confirmación) va en pesos: el mismo montoTotal que guardará la emisión.
  • Sin la exportación habilitada nada cambia: la plantilla es la de siempre y una columna de exportación en el archivo es una columna que no es parte de la plantilla (error del encabezado).

Verificado en certificación el 22-10-2026: una 110 emitida por la emisión masiva quedó aceptada por el SII.

Ejemplos por tipo

En todos los ejemplos:

bash
export API_KEY="mk_cert_7Kq2xR9fLm3nVbT8wYzA1cD5eH0jP4sU"
export EMPRESA_ID="66e0000000000000000000a1"
export BASE="https://api.miaplicacion.cl"

39 — Boleta electrónica (precio BRUTO)

El caso más común: venta al público, sin receptor identificado.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 39,
    "items": [
      { "nombre": "Cambio de aceite", "cantidad": 1, "precio": 35000 },
      { "nombre": "Filtro de aire",   "cantidad": 2, "precio": 8990 }
    ],
    "medioPago": "efectivo"
  }'

precio incluye IVA: 35.000 es lo que el cliente paga por esa línea.

41 — Boleta exenta (precio BRUTO)

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 41,
    "items": [
      { "nombre": "Clase particular de matemáticas", "cantidad": 4, "precio": 15000 }
    ]
  }'

33 — Factura electrónica (precio NETO)

El receptor necesita RUT, razón social, giro, dirección y comuna. Los cinco.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 33,
    "cliente": {
      "rut": "76123456-0",
      "razonSocial": "COMERCIAL LOS ALERCES SPA",
      "giro": "Venta al por menor de artículos de ferretería",
      "direccion": "Av. Providencia 1234, of. 502",
      "comuna": "Providencia"
    },
    "items": [
      { "nombre": "Servicio de mantención mensual", "cantidad": 1, "precio": 100000 }
    ],
    "formaPago": 2,
    "fechaVencimiento": "2026-10-04"
  }'

Con 100.000 neto, el total emitido es 119.000 (IVA 19%).

34 — Factura no afecta o exenta (precio NETO)

Mismos requisitos de receptor que la 33, sin IVA.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 34,
    "cliente": {
      "rut": "76123456-0",
      "razonSocial": "COMERCIAL LOS ALERCES SPA",
      "giro": "Venta al por menor de artículos de ferretería",
      "direccion": "Av. Providencia 1234, of. 502",
      "comuna": "Providencia"
    },
    "items": [
      { "nombre": "Servicio de exportación", "cantidad": 1, "precio": 250000 }
    ],
    "formaPago": 2
  }'

46 — Factura de compra (precio NETO)

Acá el emisor es el comprador y el «cliente» es el proveedor: la empresa retiene el IVA del vendedor. codRetencion es un entero de la tabla 4 del SII; sin él se usa 15.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 46,
    "cliente": {
      "rut": "12132194-7",
      "razonSocial": "JUAN PÉREZ SOTO",
      "giro": "Recolección de chatarra",
      "direccion": "Camino El Roble 45",
      "comuna": "Maipú"
    },
    "items": [
      { "nombre": "Chatarra de cobre (kg)", "cantidad": 120, "precio": 4500 }
    ],
    "formaPago": 1,
    "codRetencion": 15
  }'

Retención de IVA en la factura de compra (46)

codRetencion no es una etiqueta: decide cuánta plata recibe el proveedor

No todos los códigos retienen el IVA completo. Los de producto retienen un porcentaje sobre el neto, y el vendedor cobra el IVA que no se le retuvo.

CódigoProductoTasa sobre el netoCódigo si se retiene TODO
15 (default)IVA retenido total19% (todo el IVA)—
30Legumbres10%301
31Productos silvestres19% (todo el IVA)—
32Ganado8%321
33Madera8%331
34Trigo4%341
36Arroz10%361
37Especies hidrobiológicas10%371
38Chatarra19% (todo el IVA)—
39PPA19% (todo el IVA)—
41Construcción19% (todo el IVA)—
47Cartones19% (todo el IVA)—
48Frambuesas y pasas14%481

Fuente: tabla «Códigos Otros Impuestos y Retenciones» del SII y el punto 4 del Formato DTE. El 49 (factura de compra sin retención, exclusivo de la Bolsa de Productos) no está soportado: exige otra estructura de Totales.

La aritmética. Con retención parcial el total NO es el neto:

texto
codRetencion: 30   ·   items por $100.000 netos

MONTO NETO         $ 100.000
I.V.A. 19%         $  19.000
IVA RETENIDO 10%   $  10.000     ← 10% del NETO, no del IVA
TOTAL              $ 109.000     ← neto + IVA − retenido

Con retención total (el código 15 y los demás de la columna «19%») lo retenido es el IVA entero y el total vuelve a ser el neto: $100.000.

Vendedor de difícil fiscalización (retencionTotal). Cuando un producto de retención parcial se retiene por completo, el SII exige el código alterno. Se declara con retencionTotal: true y la API hace el cambio: "codRetencion": 30, "retencionTotal": true sale con TipoImp 301, TasaImp 19, el IVA completo retenido y MntTotal = neto. Mandar directamente "codRetencion": 301 es equivalente.

Se rechazan con 400, antes de pedir el folio:

CasoRespuesta
retencionTotal que no es booleano ("true", 1)retencionTotal debe ser true o false (llegó "true"). Estricto por la misma razón que items[].exento: un "false" es truthy y el documento saldría reteniendo el 100%.
retencionTotal: false sobre un código que solo existe como retención total (15, 31, 38, 39, 41, 47, 301, 321…)codRetencion 15 es de retención TOTAL del IVA y no admite retencionTotal: false.
retencionTotal en un tipo que no es 46retencionTotal solo aplica a la factura de compra (46).

Compatibilidad

El default sigue siendo el 15 y su XML no cambió. Si hoy emites sin codRetencion (o con 15), no tienes nada que hacer. Lo que sí cambia es que un codRetencion de producto (30, 32, 33, 34, 36, 37, 48) emite la retención parcial que le corresponde en vez del IVA completo: si lo usabas para operaciones de retención total, agrega "retencionTotal": true.

En el XML, la retención parcial declara además <IVANoRet> (el IVA que no se retuvo); con retención total no se emite. En la representación impresa el rótulo lleva la tasa solo cuando es parcial (IVA RETENIDO 10%).

Notas de crédito y débito de una factura de compra (56/61 con codRetencion)

Una nota que corrige o anula una factura de compra tiene que reversar la misma retención que declaró la factura: si no, devuelve un IVA que el vendedor nunca cobró. Para eso, manda en la nota el mismo codRetencion de la factura:

json
{
  "tipo": 61,
  "cliente": { "rut": "99500200-0", "nombre": "PROVEEDOR" },
  "items": [{ "nombre": "Producto 1", "cantidad": 399, "precio": 9013 }],
  "referencia": { "tipoDteRef": 46, "folioReferencia": 7, "fechaReferencia": "2026-09-15", "codRef": 3, "motivo": "Devolución" },
  "codRetencion": 15
}
  • La nota sale con <ImptoReten>, <CodImpAdic> en cada línea afecta y MntTotal = neto + IVA − retenido, exactamente como la factura.
  • Es opt-in. Sin codRetencion la nota se emite como siempre (sin retención).
  • Cambio de contrato: antes codRetencion en un 56/61 se ignoraba en silencio; ahora se valida contra la tabla (un código inválido es 400, antes del folio) y se aplica. Si lo mandabas por error en notas que no son de una factura de compra, quítalo.
  • Con codRetencion, la nota no admite items[].exento (una línea sin IVA no tiene nada que retener). Se rechaza antes del folio. retencionTotal sigue siendo solo del 46.
  • Con POST /dte/:id/anular no hace falta mandarlo: la retención se hereda del original (ver Anular un documento).

52 — Guía de despacho (precio NETO)

indTraslado va de 1 a 7 (tabla de motivos del SII); sin él se usa 1 (venta).

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 52,
    "fecha": "2026-11-02",
    "cliente": {
      "rut": "76123456-0",
      "razonSocial": "COMERCIAL LOS ALERCES SPA",
      "giro": "Venta al por menor de artículos de ferretería",
      "direccion": "Av. Providencia 1234, of. 502",
      "comuna": "Providencia"
    },
    "items": [
      { "nombre": "Perfil de aluminio 3m", "cantidad": 40, "precio": 7200 }
    ],
    "indTraslado": 5,
    "transporte": {
      "patente": "ABCD12",
      "patenteCarro": "JK4455",
      "rutTransportista": "77654321-7",
      "chofer": { "rut": "12345678-5", "nombre": "Juan Pérez Soto" },
      "destino": { "direccion": "Camino Lonquén 1500, bodega 3", "comuna": "Talagante", "ciudad": "Talagante" },
      "fechaSalida": "2026-11-02",
      "horaSalida": "08:30",
      "fechaLlegada": "2026-11-02"
    }
  }'

Desde el 2026-11-01, la guía sin transporte es 400

La Res. Ex. SII N° 144/2026 (que deja sin efecto la 154/2025) exige los datos del traslado en la guía de despacho. Rige si la fecha del documento o la de hoy (hora de Chile) ya llegó al 2026-11-01: una guía fechada el 31 de octubre y emitida el 5 de noviembre también los exige. Son obligatorios:

  • patente (1 a 8 letras o dígitos; guiones, puntos y espacios se quitan) o, si no se conoce, patenteDesconocida: true. Las dos juntas son 400.
  • rutTransportista y chofer con rut y nombre (hasta 30 caracteres). Los RUT se validan con dígito verificador.
  • destino.direccion (hasta 70 caracteres) y destino.comuna (hasta 20).
  • fechaSalida y fechaLlegada (AAAA-MM-DD, la llegada no antes de la salida).

Opcionales: patenteCarro (la del carro o remolque, mismo formato que patente), destino.ciudad (hasta 20) y horaSalida (HH:MM o HH:MM:SS): «Para todos los efectos la información de hora de salida es opcional» (resolutivo 7° N° 4). Todo se valida antes del folio: sin el objeto transporte llega un solo error que lo dice; con el objeto incompleto, uno por campo en detalles[]: Desde el 2026-11-01 la guía de despacho exige transporte.rutTransportista (Res. Ex. SII N° 144/2026).

56 — Nota de débito (precio NETO, referencia obligatoria)

Aumenta el monto de un documento ya emitido. codRef 3 = corrige montos.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 56,
    "cliente": { "rut": "76123456-0", "razonSocial": "COMERCIAL LOS ALERCES SPA" },
    "items": [
      { "nombre": "Diferencia de flete no facturada", "cantidad": 1, "precio": 18000 }
    ],
    "referencia": {
      "tipoDteRef": 33,
      "folioReferencia": 1042,
      "fechaReferencia": "2026-09-01",
      "codRef": 3,
      "motivo": "Ajuste de flete"
    }
  }'

61 — Nota de crédito (precio NETO, referencia obligatoria)

Anula (codRef 1), corrige texto (2) o corrige montos (3) de un documento ya emitido.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 61,
    "cliente": { "rut": "76123456-0", "razonSocial": "COMERCIAL LOS ALERCES SPA" },
    "items": [
      { "nombre": "Servicio de mantención mensual", "cantidad": 1, "precio": 100000 }
    ],
    "referencia": {
      "tipoDteRef": 33,
      "folioReferencia": 1042,
      "fechaReferencia": "2026-09-01",
      "codRef": 1,
      "motivo": "Anula factura emitida por error"
    }
  }'

Para una anulación total tienes el atajo POST /dte/:id/anular, que resuelve la referencia por ti (ver Anular un documento).

61 — Nota de crédito EXENTA (anula una 34 o una 41)

Una nota que anula un documento exento no puede agregar IVA. Se marca línea por línea con exento: true; no hay un campo exento por documento.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 61,
    "cliente": { "rut": "76123456-0", "razonSocial": "COMERCIAL LOS ALERCES SPA" },
    "items": [
      { "nombre": "Libro", "cantidad": 1, "precio": 50000, "exento": true }
    ],
    "referencia": {
      "tipoDteRef": 41,
      "folioReferencia": 7,
      "fechaReferencia": "2026-09-01",
      "codRef": 1,
      "motivo": "Anula boleta exenta"
    }
  }'

Totales que salen: <MntExe>50000</MntExe><MntTotal>50000</MntTotal>. Ni un peso de IVA, y cuadra al peso con la boleta que anula. Si el original fue emitido por esta API, POST /dte/:id/anular arma esto solo: la condición se hereda del documento referenciado.

61 y 56 — Nota MIXTA (líneas afectas y exentas)

IndExe va solo en las líneas exentas y los totales cuadran MntNeto + MntExe + IVA = MntTotal:

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/dte" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": 61,
    "cliente": { "rut": "76123456-0", "razonSocial": "COMERCIAL LOS ALERCES SPA" },
    "items": [
      { "nombre": "Servicio afecto", "cantidad": 1, "precio": 10000 },
      { "nombre": "Libro exento",    "cantidad": 1, "precio": 5000, "exento": true }
    ],
    "referencia": {
      "tipoDteRef": 33,
      "folioReferencia": 1042,
      "fechaReferencia": "2026-09-01",
      "codRef": 3,
      "motivo": "Corrige montos"
    }
  }'

Totales: MntNeto 10000 + MntExe 5000 + IVA 1900 = MntTotal 16900. La nota de débito (56) admite exactamente lo mismo: un interés exento sobre un documento exento se marca igual.

Consultas y folios

Listado incremental por cursor

http
GET /api/empresas/:empresaId/dte?cursor=&limite=

Scope: dte:leer. Es la reconciliación del canal push: si perdiste un webhook, barres desde donde quedaste sin releer el histórico completo. Devuelve lo que cambió después de la posición del cursor, ordenado por (updatedAt, _id) ascendente. Por eso un documento que cambia de estado (por ejemplo, de REC a ACEPTADO) vuelve a aparecer en un barrido posterior: guárdalo por su id con un upsert, no lo insertes dos veces.

ParámetroDefaultNotas
cursor—El siguienteCursor de la respuesta anterior, sin modificarlo. Es opaco.
actualizadoDesde—Alternativa al cursor: fecha ISO 8601 desde donde barrer.
ultimoId—Solo junto a actualizadoDesde; por sí solo devuelve 400.
limite50Máximo 200. Un valor basura cae al default, nunca da 500.
bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/empresas/$EMPRESA_ID/dte?limite=100"
json
{
  "documentos": [
    {
      "id": "66f0a1b2c3d4e5f607182930",
      "tipoDte": 33,
      "folio": 1042,
      "ambiente": "certificacion",
      "fechaEmision": "2026-09-04",
      "rutEmisor": "78287987-1",
      "rutReceptor": "76123456-0",
      "razonSocialReceptor": "COMERCIAL LOS ALERCES SPA",
      "montoNeto": 100000,
      "iva": 19000,
      "montoExento": 0,
      "montoTotal": 119000,
      "estadoSii": "ACEPTADO",
      "trackid": "1234567890",
      "canal": "upload",
      "intento": 1,
      "createdAt": "2026-09-04T18:22:11.004Z",
      "updatedAt": "2026-09-04T18:31:02.881Z"
    }
  ],
  "siguienteCursor": "MjAyNi0wOS0wNFQxODozMTowMi44ODFafDY2ZjBhMWIy…",
  "limite": 100
}

siguienteCursor apunta al último documento devuelto, no a «la próxima página». Una respuesta vacía devuelve null y tú conservas la posición que ya tenías: es lo que permite dejar el barrido corriendo en un cron sin que se te mueva el piso.

El cursor es opaco a propósito

No lo fabriques a mano: el par que lo sostiene es un detalle del índice, y una fecha en hora local redondeada al segundo te hace saltar documentos sin que te enteres. El correo y el teléfono del receptor no se exponen: son el contacto personal del comprador y ninguna integración los necesita para conciliar.

Consulta por folio

http
GET /api/empresas/:empresaId/dte/por-folio/:tipoDte/:folio

Tú conoces el folio (es lo que imprimiste), no el id de la base. Devuelve el mismo objeto del listado más detalles[].

Si el mismo folio existe en certificación y en producción, gana producción: la respuesta correcta a «¿qué pasó con el folio 1042?» es el documento con efectos tributarios, no el ensayo. Dentro del mismo ambiente gana el intento más alto (el intento 1 de un folio reemitido es el que el SII rechazó). Por eso la respuesta expone ambiente e intento.

PDF por folio

http
GET /api/empresas/:empresaId/dte/por-folio/:tipoDte/:folio/pdf?formato=ticket|ticket80|ticket58|carta&copia=tributaria|cedible
formatoQué imprime
ticket80Ticket de 80 mm (226,77 pt de ancho).
ticket58Ticket de 58 mm (164,41 pt de ancho). Es un papel distinto, no una escala del de 80.
cartaHoja carta.
ticketEl ticket que la empresa tenga configurado, NO necesariamente el de 80 mm. Alias histórico: existía desde antes de que hubiera dos anchos. Si necesitas un ancho concreto, pídelo por su nombre.

Sin formato, mandan, en este orden, las preferencias de impresión de la empresa y, sin ellas, el tipo del documento: ticket de 80 mm para 39/41, carta para el resto. Un formato desconocido es 400, no un PDF por defecto en silencio.

bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/empresas/$EMPRESA_ID/dte/por-folio/33/1042/pdf?formato=carta" \
  -o factura-1042.pdf

Copia cedible (?copia=tributaria|cedible). Sin copia sale el ejemplar tributario de siempre. copia=cedible agrega el cuadro de acuse de recibo (Ley 19.983) y la leyenda CEDIBLE (CEDIBLE CON SU FACTURA en la guía). Existe solo para las facturas 33, 34 y 46 y la guía 52 que sea venta (traslado 1 o 9), y solo en carta: pedirla para una nota, una boleta, una guía que no es venta o con un formato de ticket es 400 con el motivo en detalles[].

bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/empresas/$EMPRESA_ID/dte/por-folio/33/1042/pdf?copia=cedible" \
  -o factura-1042-cedible.pdf

Estado en el SII

http
GET /api/empresas/:empresaId/dte/:id/estado

Scope: dte:leer. Consulta el veredicto al SII usando el trackid guardado. Un :id inexistente, malformado o de otra empresa responde 404 { "error": "Documento no encontrado" }, sin consultar al SII.

estado es JSON crudo del SII

Igual que rawResponse: su forma la decide el SII y varía entre el canal REST de boletas y el de upload. No es un contrato estable. Para lógica de negocio usa estadoSii del listado, que sí está normalizado: ACEPTADO, ACEPTADO_REPAROS, RECHAZADO, ENVIO_INCIERTO (ver abajo), o un estado intermedio del SII (REC, SOK, CRT, FOK, PDR, EOK, -11, CDC).

ENVIO_INCIERTO: se envió, pero la confirmación del SII no llegó

El documento salió hacia el SII y la respuesta no llegó de forma legible. El SII puede haberlo registrado o no. No es un veredicto ni un estado intermedio: el folio ya se consumió y queda retenido, y el documento no tiene trackid.

De tu lado no hay que llamar a nada para resolverlo, pero no hay un plazo garantizado. En facturas, guías y notas (33, 34, 46, 52, 56 y 61) la plataforma intenta resolverlo sola: le pregunta al SII por ese folio cada pocos minutos, y el documento pasa a RECHAZADO (el SII no lo tiene tras 15 minutos, o el folio está anulado) o a REC con su trackid (el SII lo tiene), con su webhook. Si no puede decidirlo, sigue en ENVIO_INCIERTO y queda para resolverlo a mano. En boletas (39 y 41) la plataforma no pregunta: solo las resuelve a mano un admin de la empresa (o un superadmin), desde el panel, después de verificarlas en el portal del SII. Detalle completo en Cómo sale un documento de ENVIO_INCIERTO.

No reintentes la emisión ni vuelvas a emitir la misma venta mientras siga en ENVIO_INCIERTO (tampoco hay reemisión: solo se reemite un RECHAZADO): si el SII sí recibió el primero, quedan dos documentos tributarios por una sola venta.

Esta consulta también actualiza el documento: si el SII ya dio un veredicto, estadoSii queda normalizado (un RFR del SII se guarda como RECHAZADO), el folio de un rechazo vuelve al pool de reutilizables y sale el webhook que corresponda. Un estado que todavía no es terminal (un EPR sin estadística) no se marca: el documento sigue en su estado intermedio hasta que el SII se pronuncie.

Un rechazo con el código 101 («folio ya recibido») es la excepción: se marca folioQuemadoEnSii y ese folio no vuelve al pool, porque el SII ya lo consumió.

Un documento sin trackid devuelve 422, con dos cuerpos distintos. Si está en ENVIO_INCIERTO trae code: "ENVIO_INCIERTO_SIN_TRACKID" y errorType: "ENVIO_INCIERTO": el envío salió y el SII puede tenerlo, así que no es un «nunca llegó». Sigue su estado con la consulta por folio (lee el documento guardado, también para boletas) y no lo reemitas. Es el mismo status que da anular sobre un documento incierto. Este primer texto es el de las facturas, guías y notas, también las de exportación (110, 111 y 112, que hasta el 22-10-2026 recibían la variante de boleta).

json
{
  "error": "El documento tipo 33 folio 1042 está en ENVIO_INCIERTO: su envío al SII quedó sin confirmar y no hay trackid con el cual consultar el estado, pero el SII puede haberlo recibido. La plataforma lo consulta por folio automáticamente (sin garantía de resolverlo) y un administrador puede resolverlo desde el panel. No lo reemitas ni vuelvas a emitir la misma venta: sigue su estado con GET /api/empresas/:empresaId/dte/por-folio/33/1042.",
  "code": "ENVIO_INCIERTO_SIN_TRACKID",
  "errorType": "ENVIO_INCIERTO",
  "detalles": null
}

La variante de boleta dice que la plataforma no puede consultarla sola:

texto
La boleta tipo 39 folio 55 está en ENVIO_INCIERTO: su envío al SII quedó sin confirmar y no hay trackid con el cual consultar el estado, pero el SII puede haberla recibido. La plataforma NO puede consultarla sola (el SII no responde bien la consulta por folio de boletas): solo la resuelve un administrador desde el panel, después de verificarla en el portal del SII. No la reemitas ni vuelvas a emitir la misma venta: sigue su estado con GET /api/empresas/:empresaId/dte/por-folio/39/55.

Cualquier otro documento sin trackid (hoy, un RECHAZADO que salió de un envío incierto que el SII confirmó no haber recibido, o que se resolvió a mano como no recibido) responde { "error": "El documento no tiene trackid: nunca llegó al SII." }, sin code.

XML firmado y reenvío por correo

http
GET  /api/empresas/:empresaId/dte/:id/xml
POST /api/empresas/:empresaId/dte/:docId/enviar-correo

El XML es el documento tributario (regla 7). El reenvío por correo lleva scope dte:enviar_correo, que no viene en las keys nuevas, y acepta { "para": "cliente@ejemplo.cl" }; sin para usa el correo del receptor guardado en el documento. Responde síncrono: acá no hay folio en juego, y un 202 optimista solo serviría para que creas que el correo salió. Límite: 10 por minuto y por empresa.

EndpointCasoRespuesta
GET …/dte/:id/xml:id inexistente, malformado o de otra empresa404 { "error": "Documento no encontrado" }
GET …/dte/:id/xmlEl documento no tiene XML guardado404 { "error": "El documento no tiene XML almacenado" }
POST …/enviar-correo:docId sin formato de id (se corta antes de buscar el documento)400 docId inválido: "abc". Tiene que ser el identificador del documento.
POST …/enviar-correoUn para que no es un correo (se corta antes de buscar el documento)400 El correo "x" no tiene un formato válido.
POST …/enviar-correoEl resto de los fallos404 / 422 / 503 según el caso

Folios disponibles

http
GET /api/empresas/:empresaId/folios

Scope: folios:leer. Quedarse sin folios detiene la facturación en seco y timbrar un CAF nuevo no es instantáneo: este endpoint existe para que avises antes, no cuando la venta ya falló.

json
{
  "ambiente": "certificacion",
  "umbralAlerta": 20,
  "configurado": true,
  "folios": [
    {
      "tipoDte": 33,
      "nombre": "Factura electrónica",
      "disponibles": 412,
      "alerta": false,
      "rangos": [
        { "desde": 1000, "hasta": 1500, "actual": 1088,
          "disponibles": 412, "agotado": false, "vencido": false,
          "fechaAutorizacion": "2026-07-15" }
      ]
    }
  ]
}

disponibles incluye los folios liberados por rechazos (que se reutilizan antes que los nuevos). alerta: true cuando quedan umbralAlerta o menos.

Cada rango trae vencido. Un CAF vencido aporta 0 a disponibles (tanto en el rango como en el total del tipo), aunque le queden folios sin usar: la emisión no entrega ninguno de sus folios y el SII los rechazaría. El rango sigue apareciendo en la lista, marcado vencido: true, para que sepas por qué el tipo cruzó la alerta. agotado mira solo el contador, no la fecha: un rango puede estar vencido sin estar agotado.

Una empresa recién registrada, sin configuración, responde 200 con configurado: false y folios: []. No es un error.

Cuenta los folios del ambiente de la EMPRESA, no los de tu key

ambiente es el de la empresa y solo suman los CAF de ese ambiente. Con una key mk_cert_ en una empresa que ya está en producción, tus documentos salen en certificación, pero esta respuesta cuenta los folios de producción: puede marcar alerta: false y aun así la emisión de tu key responder 409 NO_FOLIOS. Para esa key, la referencia es ese 409 (y la disponibilidad del timbraje, que sí va a certificación).

Si igual te quedaste sin folios, el camino de salida (409, disponibilidad, timbraje y reemisión) está en Quedarse sin folios.

Quedarse sin folios: el flujo completo

Cuatro llamadas, orquestadas por ti. La API no automatiza ninguna: no timbra sola al quedarse sin folios, no reintenta la emisión y no decide cuántos folios pedir. Expone las piezas y tu software decide.

La excepción es el auto-timbraje

Si la empresa lo tiene activado (se activa desde el panel, no con una API key; GET .../sii-emision te dice si lo está, en config.autoTimbraje.habilitado), la plataforma sí pide folios sola cuando se acaban, así que pueden aparecer folios nuevos sin que los pidas. Mientras ese timbraje corre, un timbraje tuyo o una consulta de disponibilidad pueden responder 409 TIMBRAJE_EN_CURSO: es el mismo candado por RUT emisor.

texto
emitir → 409 NO_FOLIOS → consultar disponibilidad → timbrar → volver a emitir

El mismo flujo sirve para anular y para reemitir: los tres endpoints que emiten un DTE responden el mismo 409 con el mismo cuerpo.

Paso 1 — El 409 que lo empieza

json
{
  "error": "No quedan folios disponibles para el DTE tipo 33. Carga un nuevo CAF desde el SII.",
  "errorType": "NO_FOLIOS",
  "detalles": null,
  "tipoDte": 33
}

tipoDte dice cuál tipo se quedó sin folios, para que no tengas que adivinarlo ni parsear el mensaje. No siempre es el que mandaste: al anular, el que falta es el 61 de la nota de crédito (o el 56 de la nota de débito, si anulas una nota de crédito), no el del documento original.

Los tres endpoints que emiten responden así, con el mismo cuerpo:

EndpointSin foliosOtro fallo de emisión
POST /api/empresas/:empresaId/dte409 + errorType + tipoDte (el que mandaste)422
POST /api/empresas/:empresaId/dte/:id/anular409 + errorType + tipoDte 61 (56 si anulas una nota de crédito)422
POST /api/empresas/:empresaId/sii-emision/documentos/:id/reemitir (solo panel)409 + errorType + tipoDte422

La reemisión no está disponible para una API key

Es una ruta exclusiva del panel: con una key responde 403 Esta operación no está disponible para una API key: requiere un usuario autenticado y nunca llega a los errores de abajo. Se documentan porque el panel la usa y comparte el mismo mapeo: si tu integración muestra documentos reemitidos desde el panel, estas son las respuestas que vio el usuario.

Qué conserva. La reemisión vuelve a emitir el mismo documento, con el mismo folio, leyendo del XML firmado del rechazado lo que el registro no guarda: el receptor completo (giro, dirección, comuna y ciudad), la descripción y la unidad de medida de cada línea, las referencias (todas en 33/34/46/52; en 56/61, todas salvo la del set de pruebas), el motivo del traslado de la guía 52 y el transporte, además de las condiciones y el medio de pago, la retención, la sucursal y tu ventaId/pagoId. Hasta el 4 de octubre de 2026 perdía el receptor completo, las descripciones, las referencias (salvo la primera de una nota), el motivo del traslado (la guía volvía como venta) y el ventaId/pagoId. En las boletas 39/41 el receptor sale del registro (RUT, razón social, correo y teléfono). Una guía 52 cuyo tipo de traslado no se puede leer del XML no se reemite (400, sin consumir folio): hay que emitirla de nuevo indicando indTraslado, para no declararla como venta por error.

La excepción: los rechazos previos a pedir el folio. El cuerpo idéntico vale para los fallos de emisión. Lo que se rechaza antes de pedir el folio no pasa por ese mapeo, y hay dos formas:

  • Los rechazos de negocio (documento inexistente, no rechazado, folio quemado o anulado, IVA que no cuadra…) y el error interno traen solo { error }: sin code, sin errorType y sin detalles.
  • Los cortes de doble anulación y de configuración traen { error, code, errorType: null, detalles: null } (y notaCredito en DOCUMENTO_YA_ANULADO): el mismo cuerpo que dan anular y POST /dte.
CasoRespuesta
anular cuando el documento original no tiene detalle suficiente para replicarlo422 { error }
reemitir un documento inexistente, no rechazado, ya reemitido, o con el folio quemado (código 101) o retenido400 { error }. Un documento de otra empresa (o un :id malformado) responde exactamente igual que uno inexistente: No existe el documento a reemitir.
reemitir un documento cuyo folio fue anulado en el SII (folioAnuladoEnSii)400 { error }: El folio 7 (tipo 33) fue ANULADO en el SII: no se puede reemitir sobre él ni recuperarlo. Emite un documento nuevo, con folio nuevo.
reemitir una guía 52 cuyo tipo de traslado (IndTraslado) no se puede leer de su XML (falta, es ilegible o no está entre 1 y 9)400 { error }: No se puede reemitir la guía de despacho folio 3: no se pudo leer el tipo de traslado de la guía original; para no declararla como venta por error, emítela de nuevo indicando "indTraslado".
reemitir un documento cuyo XML trae una referencia que hoy no se acepta al emitir (un tipo que no son de 1 a 3 letras o dígitos; un folio vacío, de más de 18 caracteres, con caracteres no imprimibles o undefined; más de 40 referencias): son de antes de que se validaran400 { error }: No se puede reemitir el documento tipo 52 folio 3: su XML firmado trae referencias que el SII no acepta (referencia 1: TpoDocRef "FACT" no tiene de 1 a 3 letras o dígitos). Emite un documento nuevo con las referencias corregidas., con un problema por referencia
reemitir una factura, guía o nota cuyo neto e IVA guardados no cuadran con el 19% (por ejemplo, un registro migrado con iva: 0)400 { error }: No se puede reemitir el documento tipo 33 folio 7: declara $10000 netos y $0 de IVA, y la reemisión tiene que conservar ese par. …, seguido del detalle del descuadre
reemitir una nota que anula (61 CodRef 1, o 56 CodRef 1 sobre una 61) cuyo documento ya se anuló con otra nota, o que otra petición está anulando409 { error, code, errorType: null, detalles: null } (más notaCredito en DOCUMENTO_YA_ANULADO)
reemitir cualquier documento cuando la configuración de emisión de hoy está en otro modo (demo / folios propios) que el documento (un documento de otro ambiente se reemite en el suyo)422 CONFIG_DISTINTA_DEL_DOCUMENTO. Con la configuración inválida, 422 CONFIG_EMISION_INVALIDA; si no se pudo leer, 503 CONFIG_EMISION_NO_DISPONIBLE
reemitir o anular con un error inesperado nuestro (por ejemplo, la base de datos no responde)500 { error } con un texto genérico; el detalle técnico queda en nuestro registro

Ninguno consumió folio y ninguno se arregla timbrando. Si tu manejador lee errorType, trata ausente igual que null: en las dos formas significa lo mismo («no fue por falta de folios»), y la diferencia es solo que el error se detectó antes de llegar al mapeo de emisión.

Cambio de comportamiento

Hasta ahora solo POST /dte respondía 409: anular devolvía un 422 genérico y la reemisión un 400 con el resultado crudo del servicio (incluía success: false y details). Hoy los tres comparten un solo mapeo. Si ya distinguías el 409 al emitir, funciona igual en los otros dos sin cambiarle nada; si tratabas el 400 de la reemisión como caso especial, pásalo a 422.

La reemisión, además, reutiliza su propio folio (el que quedó liberado por el rechazo): hoy no llega a pedir uno nuevo, así que en la práctica su 409 no se dispara. Responde igual por contrato, para que no vuelva a divergir.

Con NO_FOLIOS no se consumió ningún folio: reemitir es seguro

El error salta al pedir el folio, antes de armar y firmar el documento: nada llegó al SII. Es el único error de emisión del que se puede afirmar esto.

No lo confundas con un timeout o un error de red después de haber enviado: ahí el documento pudo haberse emitido igual, el folio está consumido y reintentar a ciegas duplica el documento. Ante un timeout, consulta primero GET /api/empresas/:empresaId/dte/por-folio/:tipoDte/:folio o el listado incremental antes de reemitir.

Paso 2 — Qué te ofrece el SII

http
GET /api/empresas/:empresaId/sii-emision/timbraje/disponibilidad?tipo=33

Scope: folios:leer (viene por defecto). Abre una sesión real en el portal del SII con el certificado digital de tu empresa y lee lo que ofrece, sin pedir nada.

bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/empresas/$EMPRESA_ID/sii-emision/timbraje/disponibilidad?tipo=33"
json
{
  "success": true,
  "disponibilidad": {
    "ambiente": "certificacion",
    "rutEmisor": "76192083-9",
    "tiposOfrecidos": [{ "codigo": 33, "nombre": "Factura electrónica" }],
    "tipoDte": 33,
    "tipoOfrecido": true,
    "maxAutorizable": 5,
    "foliosDisponibles": 0
  }
}

Lo que decide el paso siguiente:

  • maxAutorizable: el techo que el SII autoriza en este timbraje. Pedir más responde 422 TIMBRAJE_CANTIDAD_EXCEDE sin timbrar nada.
  • tiposOfrecidos / tipoOfrecido: si el tipo no aparece, el SII no te lo ofrece todavía (falta habilitarlo o certificarlo) y timbrarlo responde 422 TIMBRAJE_TIPO_NO_OFRECIDO. Ahí no hay reintento que sirva.
  • foliosDisponibles: los folios vigentes que el portal ya te reconoce para ese tipo. Es el número que informa el portal del SII, no el disponibles de GET /folios, que cuenta los CAF cargados en la plataforma.

El SII autoriza pocos folios por vez

Hemos visto maxAutorizable de 1 y 2: el cupo sube a medida que el contribuyente factura, y al principio es diminuto. Pedir 50 no se recorta al máximo en silencio, falla con un error explícito. Por eso conviene consultar la disponibilidad antes de timbrar, y no pedir una cantidad fija sacada de tu configuración.

maxAutorizable es una referencia, no una garantía

El 07-09-2026 el portal informó maxAutorizable: 7, se pidieron 7 y el propio portal los rechazó («La cantidad de documentos a timbrar debe ser menor o igual al máximo autorizado»); con 5 autorizó. No sabemos por qué el portal contradice su propio campo.

Si automatizas el timbraje leyendo este número, trata el rechazo como parte del flujo: ante un 422 TIMBRAJE_SOLICITUD_RECHAZADA reintenta con menos folios en vez de detenerte. El mensaje trae el texto literal del portal, y el rechazo llega antes de autorizar nada: no consume folios y reintentar es seguro.

Sin ?tipo= devuelve solo el catálogo de tipos ofrecidos, sin entrar al detalle.

Paso 3 — Pedir los folios

http
POST /api/empresas/:empresaId/sii-emision/timbraje

Scope: folios:timbrar, que no viene en las keys nuevas: pídele a quien administra tus credenciales que lo conceda. Sin él, 403 nombrando el scope.

bash
curl -X POST "$BASE/api/empresas/$EMPRESA_ID/sii-emision/timbraje" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tipo": 33, "cantidad": 2 }'
CampoObligatorioQué es
tiposíTipo de DTE (33, 34, 39, 41, 46, 52, 56, 61).
cantidadsí (salvo en dry)Folios a pedir. Nunca mayor que maxAutorizable.
drynotrue llega hasta ver la oferta del portal y se detiene antes de pedir nada. Ensayo sin consecuencias.
json
{
  "success": true,
  "timbraje": {
    "dry": false,
    "ambiente": "certificacion",
    "rutEmisor": "76192083-9",
    "tipoDte": 33,
    "cantidad": 2,
    "folioDesde": 41,
    "folioHasta": 42,
    "fechaAutorizacion": "2026-09-06",
    "persistido": true
  }
}

El CAF queda cargado en la configuración de la empresa; el XML del CAF nunca viaja por HTTP, porque contiene la clave privada con la que se firma el timbre de cada documento.

Timbrar es irreversible

Los folios quedan asignados a tu RUT en el SII y no se devuelven, aunque después no los uses. Es una operación de cada varios días, no de cada venta.

  • Cupo propio: 10 por hora y por credencial, además del cupo de escritura (429 con Retry-After). El dry: true también descuenta: también abre sesión en el portal.
  • Uno a la vez por RUT emisor. Un segundo timbraje simultáneo del mismo RUT responde 409 TIMBRAJE_EN_CURSO: el SII rechaza logins concurrentes del mismo certificado. El candado es por RUT y no por empresa: dos empresas configuradas con el mismo RUT emisor se bloquean entre sí, y cualquier otra operación que abra sesión en el portal con ese RUT (por ejemplo la consulta del estado de certificación de boletas) también cuenta. Ojo: el texto del 409 habla de «esta empresa» («Ya hay un timbraje en curso para esta empresa…», o «Ya hay otra operación en curso en el portal del SII con el certificado de esta empresa…»), pero el que manda es el RUT emisor.
  • La consulta de disponibilidad toma el mismo candado. GET .../timbraje/disponibilidad también abre sesión en el portal, así que también puede responder 409 TIMBRAJE_EN_CURSO si hay un timbraje (u otra operación con ese RUT) en curso. Y al revés: un timbraje puede responder «Ya hay un timbraje en curso para esta empresa…» cuando lo único en curso es una consulta de disponibilidad. Si automatizas los dos pasos, no los lances en paralelo: espera la respuesta de la disponibilidad antes de timbrar.
  • Los errores llegan en la forma A con code: { error, code }, más detalles[] (errores de validación) o detalle cuando corresponde. No es la forma B de auditoría: el texto va en error, no en message (ver Errores). Los códigos: TIMBRAJE_PAYLOAD (400), TIMBRAJE_CONFIG / TIMBRAJE_CERTIFICADO (400), TIMBRAJE_FOLIO_INICIAL_SOLO_USUARIO (403), TIMBRAJE_EN_CURSO / TIMBRAJE_FOLIO_INICIAL_NO_CALZA (409), TIMBRAJE_TIPO_NO_OFRECIDO / TIMBRAJE_CANTIDAD_EXCEDE / TIMBRAJE_SOLICITUD_RECHAZADA / TIMBRAJE_NO_AUTORIZADO_POR_SII / TIMBRAJE_SIN_VERIFICACION_ACTIVIDADES / TIMBRAJE_FOLIO_INICIAL_REQUERIDO (422), TIMBRAJE_SESION / TIMBRAJE_PORTAL (502), TIMBRAJE_RED (504), TIMBRAJE_PERSISTENCIA (500).
  • El primer timbraje de un tipo en producción lo hace una persona. Cuando el portal pide el folio inicial y no se puede suponer (producción sin timbrajes previos de ese tipo, o un timbraje anterior que continuar), responde 422 TIMBRAJE_FOLIO_INICIAL_REQUERIDO sin consumir nada. Ese folio inicial lo indica un administrador de la empresa desde el panel: mandar folioInicial desde una API key es 403 TIMBRAJE_FOLIO_INICIAL_SOLO_USUARIO. Después de ese primer timbraje, tu key timbra sola. TIMBRAJE_FOLIO_INICIAL_NO_CALZA (409) es el caso del panel: se indicó un folio inicial y el portal no lo pidió, o el rango que ofrece no parte ahí; se corta antes de timbrar.
  • TIMBRAJE_CANTIDAD_EXCEDE es nuestro guard (la cantidad pedida supera el maxAutorizable que el portal declaró); TIMBRAJE_SOLICITUD_RECHAZADA es el portal rechazando la solicitud aunque la cantidad cupiera en ese número. El mensaje trae el texto literal del portal, que es la única explicación que da el SII. En los dos casos no se autorizó ni se consumió nada.
  • TIMBRAJE_NO_AUTORIZADO_POR_SII es el portal diciendo «NO SE AUTORIZA TIMBRAJE ELECTRÓNICO»: la empresa tiene folios de ese tipo sin usar (cuentan también los de CAF vencidos o timbrados con otro sistema) o situaciones pendientes con el SII. El SII lo evalúa por tipo: los demás tipos pueden seguir timbrándose. Llega en el timbraje (también con dry: true) y en la disponibilidad, con detalle: { tipoDte, ambiente, etiqueta, causa: "folios_sin_usar_o_situacion_pendiente" } (tipoDte es null si el portal lo dijo antes de elegir el tipo). No lo reintentes: hay que anular en el SII los folios sin usar de ese tipo (en la app: Folios → Anular folios; es irreversible y solo lo hace un administrador desde el panel) o emitirlos, y recién ahí volver a pedir. No se autorizó ni se consumió nada.
  • TIMBRAJE_SIN_VERIFICACION_ACTIVIDADES (422) es el portal diciendo que la empresa no registra la Verificación de Actividades, y por eso el SII no le autoriza timbrar. Llega con detalle: { tipoDte, ambiente, etiqueta, causa: "sin_verificacion_de_actividades" }. No lo reintentes: la verificación la pide el contribuyente en sii.cl (menú «Peticiones Administrativas», luego «Verificación de actividad») o en la oficina del SII de su domicilio, y cuando el SII la apruebe se vuelve a pedir. No se autorizó ni se consumió nada.

En producción, los folios son reales

El timbraje pide los folios en el ambiente de la empresa. Si está en produccion, una API key de producción (mk_prod_) con folios:timbrar obtiene folios reales, que no se pueden devolver: no hay un interruptor aparte que lo frene. El dry: true y la consulta de disponibilidad no autorizan nada: son la forma de verificar el portal de producción antes de timbrar de verdad.

Una key mk_cert_ timbra siempre en maullin (desde el 29-09-2026): con la empresa en producción recibe un CAF de certificación (IDK 100), que solo usan las emisiones de certificación, y la respuesta trae "certificacionForzada": true. Su consulta de disponibilidad también mira maullin.

Paso 4 — Volver a emitir

El mismo POST /api/empresas/:empresaId/dte de antes, con el mismo cuerpo. Como el 409 no consumió folio, es una emisión nueva y no una reemisión: no hay documento previo que anular ni referenciar.

Antes de que pase: GET /folios

El flujo de arriba es el de emergencia. El barato es no llegar a él: consulta GET /api/empresas/:empresaId/folios (scope folios:leer, sin tocar el SII) y timbra cuando alerta: true, no cuando la venta ya falló. El webhook folios.bajos avisa lo mismo, pero no es inmediato: sale en una revisión que corre cada hora.

Configuración, auditoría y contabilidad

Configuración y listados del panel

Once endpoints bajo /sii-emision: los nueve de esta tabla y los dos del timbraje, que están en Quedarse sin folios. El listado de acá es paginado por número de página, a diferencia del listado por cursor: sirve para pintar una tabla; para reconciliar, usa el cursor.

RutaScopeNotas
GET /sii-emisionconfig:leerDevuelve { configurada, config }. Nunca incluye la clave del certificado ni el CAF.
GET /sii-emision/autorizacionesdte:leerLos tipos de DTE autorizados por el SII, desde lo guardado. Ver abajo.
GET /sii-emision/documentosdte:leerListado paginado; parámetros en la tabla de abajo. Responde { documentos, total, pagina, limite }. Un parámetro mal formado es 400 con todos los errores en detalles[], y la base no se toca.
GET /sii-emision/documentos/exportardte:leerformato=csv|xlsx (default csv). Mismos filtros. Excluye los documentos del modo demo salvo incluirDemo=true.
GET /sii-emision/documentos/proyectosdte:leerLos valores posibles del filtro proyecto: { proyectos[], hayPanel, haySistema, haySinProyecto, haySinRegistro }. Acepta solo ?ambiente; sin él, una API key ve los dos ambientes.
GET /sii-emision/documentos/:id/pdfdte:leerformato=ticket|ticket80|ticket58|carta. Los mismos cuatro del PDF por folio, con la misma advertencia: ticket a secas es el papel configurado, no el de 80 mm. Y la misma copia=tributaria|cedible: la cedible solo para 33, 34, 46 y 52, y solo en carta.
GET /sii-emision/libro-ventasdte:leerperiodo=AAAA-MM y ambiente son OBLIGATORIOS: un libro que mezcla ambientes no sirve para declarar. formato=json|csv|xlsx (default json). Excluye el emisor demo salvo incluirDemo=true.
GET /sii-emision/librosdte:leerEnvíos del libro IECV al SII. Ver abajo.
GET /sii-emision/libros/:iddte:leerUn envío del IECV; con ?xml=1, su XML firmado.

Parámetros de GET /sii-emision/documentos (los mismos filtros sirven para /exportar):

ParámetroValoresDefault
paginaentero ≥ 11
limiteentero, máx. 20025
desde, hastaAAAA-MM-DD sobre fechaEmision—
folioentero positivo—
tipo33, 34, 39, 41, 46, 52, 56, 61—
estadoACEPTADO, ACEPTADO_REPAROS, RECHAZADO, ENVIO_INCIERTO, REC, SOK, CRT, FOK, PDR, EOK, -11, CDC—
ambientecertificacion, produccion—
rutReceptorRUT con guion—
textobusca en la razón social del receptor—
sucursalIdid de sucursal, o matriz: la casa matriz (matriz o el id de la sucursal matriz) trae además los documentos sin sucursal; sin sucursales configuradas no filtra—
proyectoel proyecto de la key que emitió (taller.bike…) o panel, sistema, sin-proyecto, sin-registro—
montoMin, montoMaxenteros en pesos—
ordenfecha_desc, fecha_asc, folio_desc, folio_asc, monto_desc, monto_ascfecha_desc
incluirRcvtrue—

Cada documento trae reemitible: si pasa los cortes de la reemisión que no leen el XML (rechazado, no resuelto a mano, folio no anulado, quemado ni retenido, sin reemisión previa). También trae rechazoResoluble: rechazado, sin reemisión y no resuelto a mano. Un rechazado que un administrador marcó como resuelto desde el panel (su contenido salió por otro camino) trae rechazoResuelto con en (fecha), motivo y, si se indicó, reemplazo (documentoId, tipoDte, folio), y ya no es reemitible. La nota de crédito de una devolución parcial del punto de venta sale siempre reemitible: false y, si está rechazada, trae motivoNoReemitible: se corrige en el punto de venta, con la nota de reemplazo si el reembolso ya se pagó o pidiendo de nuevo la devolución si el SII la rechazó antes (el motivo dice cuál). Con incluirRcv=true (no aplica a /exportar) la respuesta trae además rcv, aparte de documentos y total: las ventas del Registro de Compras y Ventas del SII que no se emitieron con esta API, de solo lectura, con las reglas del resumen del Panel (solo producción, sin modo demo, sin el tipo 48, sin repetir lo emitido con la API). Pide una key con sii:leer que no sea de certificación; si no, rcv.motivo dice por qué.

GET /sii-emision/documentos devuelve _id, no id

A diferencia del resto de la API, y a propósito: el panel lee _id en todas sus pantallas de documentos y cambiarlo lo rompería. Si reutilizas el identificador en otras rutas (/dte/:id/estado, /dte/:id/xml, el PDF por id), toma _id de acá e id del resto de la API. El listado por cursor sí trae id.

Cada documento trae además origen, quién lo pidió: tipo (apikey, usuario o sistema) y, si fue una key, apiKeyId, apiKeyNombre y proyecto, copiados al emitir. Los documentos anteriores a ese registro no lo traen (filtro sin-registro). Y sin ?ambiente, una API key lista los dos ambientes (el panel ve solo el de la empresa): filtra por ambiente si no quieres mezclar certificación con producción.

Tipos autorizados por el SII

http
GET /api/empresas/:empresaId/sii-emision/autorizaciones

Scope: dte:leer. Qué tipos de documento tiene autorizados la empresa según el SII, para saber, por ejemplo, si todavía hace falta certificar un tipo. No consulta al SII durante la petición: responde con la última lectura guardada del registro del SII, así que es rápida y no depende de que el SII responda.

json
{
  "empresaId": "66f1a2b3c4d5e6f708192a3b",
  "rut": "77.123.456-7",
  "leida": true,
  "consultadoAt": "2026-10-19T10:00:00.000Z",
  "tipos": [
    { "codigo": 33, "autorizado": true, "desde": "2014-08-22" },
    { "codigo": 34, "autorizado": true, "desde": "2014-08-22" },
    { "codigo": 39, "autorizado": true, "desde": "2021-03-01" },
    { "codigo": 41, "autorizado": false, "desde": null },
    { "codigo": 52, "autorizado": true, "desde": "2014-08-22" },
    { "codigo": 46, "autorizado": false, "desde": null },
    { "codigo": 43, "autorizado": false, "desde": null },
    { "codigo": 110, "autorizado": false, "desde": null },
    { "codigo": 111, "autorizado": false, "desde": null },
    { "codigo": 112, "autorizado": false, "desde": null },
    { "codigo": 56, "autorizado": true, "desde": "2014-08-22" },
    { "codigo": 61, "autorizado": true, "desde": "2014-08-22" }
  ]
}
  • tipos trae siempre estos 12 códigos y en este orden: 33, 34, 39, 41, 52, 46, 43, 110, 111, 112, 56, 61, aunque no estén autorizados. desde es la fecha de autorización (AAAA-MM-DD) o null.
  • autorizado tiene tres valores: true (el SII lo autoriza), false (se leyó el registro y ese tipo no está) y null (no se sabe: no hay una lectura válida). Un null nunca significa «no autorizado»: no cobres ni bloquees por él.
  • leida es false si no hay ninguna lectura válida del registro del SII (sin certificado cargado, nunca se consultó o la última lectura falló); con leida: false, todos los autorizado van en null.
  • Los 12 tipos, 39 y 41 incluidos, salen del registro de documentos autorizados del SII que guarda la plataforma. Si su última lectura falló, o si nunca se leyó, todos van en null.
  • consultadoAt es la fecha de la última lectura válida (ISO), o null; si las dos fuentes tienen fechas distintas, la más antigua.
  • Una key de otra empresa recibe el 403 de «tu propia empresa» (como todo /sii-emision); una key sin dte:leer, el 403 con scopeRequerido. No trae certificados, credenciales ni datos internos del SII.

Libros de compras y ventas enviados al SII (IECV): solo lectura

Distinto del libro de ventas, que es un reporte armado al vuelo: esto es el registro de cada envío del LibroCompraVenta (IECV) al SII por el canal de upload, con su trackid y su veredicto. Una API key lista y lee; no envía, no resuelve a mano ni fuerza la consulta de veredictos. Esas tres exigen un usuario humano: un libro MENSUAL aceptado cierra el período en el SII y solo se reemplaza con una RECTIFICA, así que nadie lo declara con una credencial de servicio.

http
GET /api/empresas/:empresaId/sii-emision/libros
GET /api/empresas/:empresaId/sii-emision/libros/:id
GET /api/empresas/:empresaId/sii-emision/libros/:id?xml=1

Scope: dte:leer. Filtros: periodo (AAAA-MM), tipoOperacion (COMPRA, VENTA), estado, ambiente, pagina (default 1) y limite (default 25, máx. 200).

bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/empresas/$EMPRESA_ID/sii-emision/libros?periodo=2026-08&tipoOperacion=VENTA"
json
{
  "libros": [
    {
      "id": "68c8…",
      "ambiente": "certificacion",
      "tipoOperacion": "VENTA",
      "periodo": "2026-08",
      "tipoLibro": "MENSUAL",
      "tipoEnvio": "TOTAL",
      "secEnvio": 1,
      "origen": "ventas_emitidas",
      "documentos": 12,
      "resumen": { "…": "totales por tipo de documento, como se declararon" },
      "excluidos": [{ "tipoDte": 39, "folio": 100, "motivo": "boleta_canal_propio" }],
      "avisos": [],
      "hashXml": "sha1 de los bytes ISO-8859-1 subidos",
      "bytes": 18432,
      "nombreArchivo": "LIBRO_VENTA_78287987_1_2026-08.xml",
      "estado": "ACEPTADO",
      "trackid": "258837254",
      "estadoSii": "LOK",
      "estadoDetalle": { "estadoSii": "LOK", "glosa": "Envio de Libro Aceptado - Cuadrado" },
      "reparos": [],
      "enviadoAt": "2026-09-15T13:08:14.000Z",
      "veredictoAt": "2026-09-15T13:08:34.000Z",
      "intentosConsulta": 2,
      "notas": [],
      "createdAt": "2026-09-15T13:08:00.000Z",
      "updatedAt": "2026-09-15T13:08:34.000Z"
    }
  ],
  "total": 1,
  "pagina": 1,
  "limite": 25
}
  • trackid es string (o null mientras el SII no lo asignó). El XML firmado nunca viene en el JSON: se pide aparte.
  • Un parámetro mal formado es 400 con todos los errores en detalles[]. Un :id que no es un id válido es 400; uno de otra empresa es 404, no 403: no se revela que existe.
  • ?xml=1 responde application/xml; charset=ISO-8859-1 como adjunto, con los mismos bytes que recibió el SII, y hashXml es el SHA-1 de esos bytes (en los libros enviados antes del 07-10-2026 es el del texto, y no calza si el XML trae una Ñ o una tilde); 404 si el registro no conserva el XML. La regla es estricta: ausente, 0 o false → JSON; 1 o true → XML; cualquier otro valor → 400.
estadoQué significaQué hacer
preparadoXML firmado y registrado; la subida aún no terminó.Esperar. Si lleva más de 30 min, el poller lo pasa a envio_incierto.
enviadoEl SII lo recibió y asignó trackid; sin veredicto todavía.Esperar al poller (estadoSii va mostrando LSO, …).
ACEPTADOVeredicto terminal del SII (LOK). Un MENSUAL/RECTIFICA aceptado cierra el período.Nada. Para corregirlo hace falta una RECTIFICA desde el panel (con el codAutRec que entrega el SII; es lo que dice la norma, no verificado en vivo).
RECHAZADOVeredicto terminal del SII (LNC observado en vivo; LRH y otros salen de la norma y no se han observado); ver estadoDetalle.glosa.El período queda libre: corregir y reenviar desde el panel.
rechazado_uploadEl SII contestó la subida con un STATUS ≠ 0 legible: no lo registró, no hay trackid.El período queda libre: corregir y reenviar desde el panel.
descartadoNunca llegó al SII (falló el token antes de subir) o un humano lo descartó tras verificar que no entró.El período queda libre. Excepción: si después el SII contesta tarde con trackid, el registro no se reabre; queda una nota en notas[] y hay que revisar el portal antes de reenviar el período.
envio_inciertoLa subida salió y no volvió respuesta legible (corte, timeout, o más de 30 min en preparado): puede haber entrado o no. Sigue bloqueando el período.No reintentar a ciegas (un segundo TOTAL sobre un período que sí entró vuelve LNC). Un admin verifica en el portal y lo resuelve desde el panel. Si el SII contesta tarde por su cuenta, pasa solo a enviado (estadoDetalle.motivo: "respuesta_tardia").
sin_veredictoSe agotaron las consultas al SII sin un estado terminal. Sigue bloqueando el período.Un admin verifica en el portal o en el correo del SII y lo cierra desde el panel como ACEPTADO o RECHAZADO.

Mientras un envío está en preparado, enviado, envio_incierto o sin_veredicto, la API no acepta otro envío del mismo período y operación (el panel recibe 409 LIBRO_EN_CURSO). Los reparos (reparos[]) y el estado del libro tributario (estadoLibroSii) los manda el SII por correo: si están, se cargaron a mano.

estadoDetalle.motivo dice por qué el registro está donde está: upload_rechazado, envio_incierto, preparado_huerfano, respuesta_tardia, resuelto_a_mano o el motivo del veredicto del poller. avisos[] trae lo que conviene leer aunque el envío haya salido bien: un libro enviado a sabiendas incompleto y, en el caso raro de una respuesta tardía sobre un registro que ya no estaba en curso, el aviso de que el SII sí recibió el libro: ahí no reenvíes el período y verifica el trackid en el portal.

Exportación. Donde el servidor la habilita, el libro de ventas incluye la 110, la 111 y la 112 con sus montos en pesos (los de OtraMoneda, al tipo de cambio de su fecha de emisión), MntIVA 0 y TpoDocRef solo en la 112 que anula una 110 o una 111 (formato IECV v3.0, págs. 10, 22, 23 y 39). Ya no dejan el libro incompleto. No se informan los ajustes de tipo de cambio 500 y 501, y un libro de ventas parcial con exportación quedó aceptado y cuadrado por el SII de certificación; falta probar el resumen del período (ver Documentos de exportación).

Los errores de estos endpoints son de la forma A. Los del envío desde el panel agregan code (LIBRO_PARAMETROS 400, LIBRO_CONFIG 400, LIBRO_EN_CURSO y LIBRO_PERIODO_CERRADO 409, LIBRO_INCOMPLETO 422, LIBRO_ENVIO_INCIERTO 502, …) y, en los 409, detalle con el registro que bloquea. Las banderas dryRun, incluirDemo, permitirIncompleto e incluirXml son booleanas estrictas: un "true" (string) es 400, nunca un envío real.

Cesión de facturas (factoring)

Bajo /api/empresas/:empresaId/cesiones: la cesión electrónica de una factura emitida por la empresa a un cesionario (factoring, Ley 19.983), anotada en el Registro Público Electrónico de Transferencias de Crédito (RPETC) del SII.

Funciona en certificación; en producción, 501

El RPETC de certificación anotó una cesión de prueba el 07-10-2026 y, el 22-10-2026, una cadena de tres cesiones del mismo documento (la tercera, de una empresa que volvió a cederlo como cesionaria). En producción, ceder responde 501 CESION_NO_HABILITADA y no envía nada: se habilita recién con evidencia propia y una autorización explícita. Las lecturas funcionan en los dos ambientes.

  • Alcance. La empresa cede como cedente original (primera cesión) facturas 33 y 34 que el SII aceptó. No se cede un documento del modo demo, ni con la empresa en modo demo, ni uno que ya tiene una cesión en curso o aceptada. Además vuelve a ceder las facturas que recibió como cesionaria (ver Volver a ceder como cesionario).
  • Declaración jurada. Sin recibo electrónico de mercaderías, cada cesión lleva la declaración jurada del cedente, con la fórmula de la Circular SII 56/2013. Si pasa de 512 caracteres (el máximo del esquema), se usa la fórmula del Formato AEC v1.1 (campo 14); si tampoco cabe, 400 con los largos exactos. Nunca se trunca.
  • Efecto. El RPETC avisa el resultado por correo y, según su propio aviso, la cesión se entiende puesta en conocimiento del deudor el día hábil siguiente a la anotación. La clave de acceso a la cesión la recibe el cesionario, nunca el cedente: esta API no la guarda.
  • Tope por plan (solo producción): 20 cesiones al mes en Crecimiento, 100 en Alto volumen y sin tope en Corporativo; Emprende y Negocio no incluyen la cesión. Se cuentan las de producción del mes calendario de Chile, salvo las descartado, rechazado_upload, RECHAZADO y ANULADO. En certificación no hay tope.
RutaScopeQué hace
GET /dte:leerestado, ambiente, tipoDte (33 o 34), folio, emitidaId, documentoTenenciaId, pagina, limite (máx. 200, default 50). Responde { cesiones, total, pagina, limite }; con una API key y sin ambiente, los dos ambientes.
GET /:iddte:leer{ cesion }, o 404 (también la de otra empresa).
GET /:id/aecdte:leerEl AEC firmado, adjunto, en ISO-8859-1: lo que el cedente entrega al cesionario.
GET /precheck/:emitidaIdadmin con sesión, o cesion:emitir¿Se puede ceder? No escribe nada: revisa lo local y consulta en el SII la cedibilidad y si ya está cedido. Devuelve cedible, problemas, plan y la declaración jurada exacta (con cesionarioRut y cesionarioRazonSocial en la query). Con soloDeclaracion=1 no consulta al SII. Con una API key, cupo propio de 30 por hora por empresa (ver abajo).
POST /admin con sesión, o cesion:emitirCede (ver abajo). 201 con la cesión en estado enviado.
POST /actualizaradmin, con sesiónConsulta en el RPETC las cesiones enviadas de la empresa; nunca reenvía. 409 CESION_ACTUALIZACION_EN_CURSO si ya hay una vuelta en curso.
POST /:id/resolver-inciertoadmin, con sesiónBody { resolucion, trackid?, nota }: cierra a mano una envio_incierto (descartado, o enviado con su trackid) o una sin_veredicto (ACEPTADO o RECHAZADO). La nota es obligatoria.
POST /recibidasadmin con sesión, o cesion:emitirRecibe el AEC que hizo cesionaria a la empresa (ver Volver a ceder como cesionario). 201 si quedó en tenencia; 200 si ya estaba o volvió.
GET /recibidasdte:leerestado (en_tenencia o cedido), ambiente, tipoDte (33, 34, 43 o 46), folio, rutEmisor, pagina, limite (máx. 200, default 50). Responde { documentos, total, pagina, limite }.
GET /recibidas/:tenenciaIddte:leer{ documento }, o 404 «Documento en tenencia no encontrado».
GET /recibidas/:tenenciaId/precheckadmin con sesión, o cesion:emitirEl precheck para volver a cederlo: la misma query y la misma respuesta que el de un documento emitido.

Verificar y ceder: un admin de la empresa (o el superadmin) con sesión, o una API key con cesion:emitir (no viene por defecto; cuenta en el cupo de escritura de la key). Actualizar y resolver: solo un admin con sesión; una API key recibe 403 con cualquier scope. Con una key, la cesión guarda qué key aceptó la declaración jurada (declaracionJurada.aceptadaPorApiKey) y la creó (creadoPorApiKey), como { apiKeyId, apiKeyNombre, proyecto } (lo mismo que el origen de un documento; nunca la key ni su prefijo), en lugar de aceptadaPor y creadoPor. Una key mk_cert_ no cede un documento de producción (403 AMBIENTE_NO_AUTORIZADO, con la empresa en cualquier ambiente) y su precheck lo marca como no cedible sin consultar al SII. Una key que llega sin su id (sin él no queda registrado quién operó) no hace el precheck, no cede ni recibe un AEC: 403 AMBIENTE_NO_AUTORIZADO antes de consultar o escribir nada.

  • Cupo del precheck con API key. Cada precheck consulta al SII hasta cuatro veces con el certificado de la empresa. Por eso los dos prechecks (GET /precheck/:emitidaId y GET /recibidas/:tenenciaId/precheck) tienen, además del cupo de escritura de la key, un cupo propio de 30 por hora y por empresa, compartido por todas sus keys y por los dos prechecks (SII_MAX_PRECHECKS_CESION_POR_HORA; un valor que no es un entero mayor que 0 deja 30). Al pasarse, 429 con Retry-After y RateLimit-Policy: "apikey-escritura";q=60;w=60, "cesion-precheck";q=30;w=3600 (el primero, con el cupo de escritura de tu plan), y el cuerpo { "error": "La empresa superó su límite de prechecks de cesión por hora con API key. Cada precheck consulta al SII con el certificado de la empresa: reintenta más tarde (soloDeclaracion=1 no consulta al SII y no cuenta)." }. Un precheck con soloDeclaracion=1 (o true) no consulta al SII y no cuenta. El panel (usuarios con sesión) no pasa por este cupo.
  • Producción, empresa por empresa. Cuando la cesión en producción se habilite, solo podrán ceder documentos de producción las empresas que el superadmin de la plataforma habilite una por una; las demás reciben 409 CESION_NO_PERMITIDA con detalle.motivo: "produccion_no_habilitada", antes del plan, del SII y de la reserva, y su precheck responde cedible: false con ese problema. Mientras tanto, ceder en producción sigue respondiendo 501 CESION_NO_HABILITADA. En certificación no se mira.
  • Hora de la cesión. El TmstCesion del AEC (y la hora de sus firmas) se declara 5 minutos antes de la hora del servidor, para que un reloj algo adelantado no deje una cesión en el futuro; nunca antes de lo que se cede (el TmstFirma del DTE en la primera cesión, el TmstCesion de la cesión anterior al volver a ceder) y nunca después de la hora del servidor.

Cada cesión trae id (nunca _id), ambiente, emitidaId, tipoDte, folio, rutDeudor, cedente, cesionario, montoCesion, ultimoVencimiento, declaracionJurada (texto, formula y quién la aceptó), estado, trackid (string), trackidTexto (con sus ceros a la izquierda), estadoSii y hashXml (SHA-1 de los bytes del AEC subido; en las anteriores al 07-10-2026, del texto). Estados en curso: preparado, enviado, envio_incierto (no se sabe si el AEC entró: no se reintenta, se resuelve a mano) y sin_veredicto. Resueltos: ACEPTADO (anotada: la empresa ya no es la tenedora), RECHAZADO, ANULADO, rechazado_upload y descartado. El servidor consulta solo, cada 5 minutos, el estado de las enviadas. Las cesiones nuevas traen además rutEmisor; la de un documento en tenencia trae documentoTenenciaId en vez de emitidaId y seqCesion de 2 a 40.

El cuerpo de POST / lleva emitidaId (o documentoTenenciaId, ver Volver a ceder como cesionario), cesionario { rut, razonSocial, direccion, email }, montoCesion (entero, hasta el total de la factura), ultimoVencimiento (AAAA-MM-DD), aceptaDeclaracionJurada: true y declaracionJurada: el texto exacto que devolvió el precheck. Si no es idéntico al que se firmaría, 409 DECLARACION_JURADA_CAMBIO con el vigente en detalle.declaracionJurada.texto. Opcionales: cedente, nombreFirmante, emailNotificacion, otrasCondiciones, emailDeudor y contacto. Los errores llevan { error, code }: 400 CESION_PARAMETROS (todos juntos) y CESION_CONFIG; 403 AMBIENTE_NO_AUTORIZADO y CESION_NO_INCLUIDA_EN_PLAN; 404 CESION_DOCUMENTO_NO_ENCONTRADO y, en resolver-incierto, CESION_NO_ENCONTRADA (la cesión no existe en esta empresa); 409 CESION_NO_PERMITIDA (con los motivos), CESION_EN_CURSO, CESION_YA_CEDIDA, DECLARACION_JURADA_CAMBIO, CESION_TOPE_MENSUAL y, en resolver-incierto, CESION_ESTADO (la cesión no está en un estado que admita esa resolución, o alguien la resolvió antes; detalle trae cesionId y, si aplica, su estado); 422 CESION_MODO_DEMO, CESION_UPLOAD_RECHAZADO y CESION_NO_ENVIADA_VALIDACION; 501 CESION_NO_HABILITADA; 502 CESION_TOKEN, CESION_NO_ENVIADA (no salió; se puede reintentar) y CESION_ENVIO_INCIERTO: no reintentes, revisa el correo del SII o el RPETC y resuélvela con resolver-incierto.

Volver a ceder como cesionario

Cuando a la empresa le ceden una factura (es el último cesionario anotado en el RPETC), puede volver a cederla: son cesiones sucesivas del mismo documento, hasta 40 (el máximo del formato del AEC). Son tres pasos: recibir el AEC que la hizo cesionaria, el precheck y ceder con documentoTenenciaId. Quedó verificado en certificación el 22-10-2026; en producción, ceder responde 501 CESION_NO_HABILITADA, igual que la primera cesión.

  • Recibir el AEC. POST /recibidas con el archivo en multipart/form-data (campo archivo) o el XML crudo como cuerpo text/xml o application/xml, tal como lo entregó el cedente: sin convertirlo ni volver a formatearlo, porque lleva firmas. Un admin con sesión o una API key con cesion:emitir; la cuenta demo no recibe. No se pide el ambiente: sale del CAF del DTE cedido.
  • Qué se valida. La estructura del AEC según su esquema; las firmas del DTE, del DTECedido, de cada cesión y del sobre (de integridad: ver verificacion, más abajo); que la carátula calce con la última cesión; y que el último cesionario sea la empresa (el RUT de su configuración de emisión). Si pasa, se guarda byte a byte como documento en tenencia y el archivo nunca vuelve en las respuestas. 201 si se creó; 200 si ya estaba con el mismo archivo (creado: false), o si un documento que la empresa ya volvió a ceder regresa a ella con un AEC del mismo documento que trae la cadena guardada al comienzo y más cesiones (actualizado: true). Un documento que la empresa cedió por fuera del sistema (desde el portal del SII u otro software) y que le vuelve se acepta igual (actualizado: true) si el AEC nuevo extiende la cadena guardada y muestra la cesión firmada por la empresa; si no, o si hay una cesión suya de ese documento en curso, 409 TENENCIA_AEC_DISTINTO. En los dos casos, el DTE cedido y cada cesión guardada tienen que venir copiados intactos en el AEC nuevo, tal como se firmaron: una cadena con los mismos datos pero re-firmada también es 409.
  • El precheck. GET /recibidas/:tenenciaId/precheck, con la misma query y la misma respuesta que el de un documento emitido (soloDeclaracion=1 incluido); documento trae además origen: "tenencia", el emisor, el estado, la cadena y verificacion. Al revés que en la primera cesión, el RPETC tiene que informar que el documento está cedido.
  • Ceder. POST / con documentoTenenciaId en vez de emitidaId; el resto del cuerpo, la declaración jurada, el 501 de producción y el tope de cesiones al mes son los de siempre. El 201 trae además seqCesion. Cuando el RPETC anota la cesión (ACEPTADO), el documento pasa a cedido: la empresa ya no es la tenedora.
  • Listar y leer. GET /recibidas y GET /recibidas/:tenenciaId, con dte:leer. Con sesión y sin ambiente, el de la empresa; con una API key y sin ambiente, los dos. Un filtro inválido es 400 con todos los errores en detalles[]. Las cesiones hechas sobre un documento en tenencia se listan con GET /?documentoTenenciaId=.

Cada documento en tenencia trae id, ambiente, rutEmisor, razonSocialEmisor, tipoDte, folio, fechaEmision, rutReceptor (el deudor), razonSocialReceptor, montoTotal, cesiones[{ seq, cedente, cesionario, montoCesion, ultimoVencimiento, fecha }], seqUltimaCesion, ultimoCesionario, sha256 y bytes del archivo, verificacion, estado (en_tenencia o cedido), quién lo subió (recibidoPor o recibidoPorApiKey), createdAt y updatedAt.

Qué prueba la verificación de firmas. verificacion dice qué se verificó del AEC recibido y qué no. Viene en POST /recibidas (201 y 200), en cada documento de GET /recibidas, en GET /recibidas/:tenenciaId, en el precheck (precheck.documento.verificacion) y en cesion.documento al ceder con documentoTenenciaId:

  • firmas: "integridad": cada firma calza con el certificado que trae el propio archivo. Prueba que nada cambió después de firmarse; nada más.
  • cadenaDeConfianza: false: no se valida que esos certificados los haya emitido una entidad acreditada ni que estén vigentes, así que la verificación no prueba quién firmó.
  • registro: "se_valida_al_ceder": el archivo tampoco prueba que el Registro (RPETC) haya anotado esas cesiones. Eso se confirma al volver a ceder: el precheck y la cesión exigen que el RPETC informe el documento cedido.
  • nota: lo mismo en una frase, para mostrarla tal cual.
json
HTTP/1.1 201 Created
{
  "success": true,
  "creado": true,
  "actualizado": false,
  "documento": {
    "id": "6ada3b4af03de3bcbd0d9ed6",
    "ambiente": "certificacion",
    "rutEmisor": "78287987-1",
    "razonSocialEmisor": "MI APLICACION SPA",
    "tipoDte": 33,
    "folio": 149,
    "fechaEmision": "2026-10-06",
    "rutReceptor": "78287987-1",
    "razonSocialReceptor": "MI APLICACION SPA",
    "montoTotal": 1190,
    "cesiones": [
      { "seq": 1, "cedente": { "rut": "78287987-1", "razonSocial": "MI APLICACION SPA" },
        "cesionario": { "rut": "76123456-0", "razonSocial": "Factoring de Prueba SpA" },
        "montoCesion": 1190, "ultimoVencimiento": "2026-11-30", "fecha": "2026-10-22T13:25:56" },
      { "seq": 2, "cedente": { "rut": "76123456-0", "razonSocial": "Factoring de Prueba SpA" },
        "cesionario": { "rut": "78287987-1", "razonSocial": "MI APLICACION SPA" },
        "montoCesion": 1190, "ultimoVencimiento": "2026-11-30", "fecha": "2026-10-22T13:31:43" }
    ],
    "seqUltimaCesion": 2,
    "ultimoCesionario": { "rut": "78287987-1", "razonSocial": "MI APLICACION SPA" },
    "sha256": "…",
    "bytes": 21874,
    "verificacion": {
      "firmas": "integridad",
      "cadenaDeConfianza": false,
      "registro": "se_valida_al_ceder",
      "nota": "Las firmas del AEC calzan con los certificados que trae el propio archivo: nada cambió después de firmarse (integridad). No se validó que esos certificados los haya emitido una entidad acreditada ni que estén vigentes, así que no prueba quién firmó. Que el Registro (RPETC) anotó estas cesiones se confirma al volver a ceder: el precheck y la cesión exigen que el RPETC informe el documento cedido."
    },
    "estado": "en_tenencia",
    "createdAt": "2026-10-22T16:35:22.000Z",
    "updatedAt": "2026-10-22T16:35:22.000Z"
  }
}

Errores al recibir, con { error, code } y, según el caso, detalles[] o detalle: 400 AEC_SIN_ARCHIVO («Falta el AEC recibido.»); 400 XML_ARCHIVO_INVALIDO y 413 XML_DEMASIADO_GRANDE («El AEC no se pudo recibir.», la causa en detalles[]); 400 TENENCIA_CONFIG (la empresa no tiene un RUT válido en su configuración de emisión); 422 AEC_INVALIDO (todo lo que no pasó, en detalles[]); 422 AEC_AMBIENTE_INDETERMINADO (el CAF del DTE no trae un IDK legible); 422 AEC_NO_ES_CESIONARIO (detalle: { ultimoCesionario, rutEmpresa }); 409 TENENCIA_AEC_DISTINTO (ya hay otro AEC de ese documento; detalle: { id, estado, sha256Guardado, sha256Recibido }).

En AEC_INVALIDO, la estructura va primero y con todos sus errores juntos; si hay alguno, las firmas no se verifican y detalles[] no trae errores de firma (aparecen al corregir la estructura). El lector tiene topes que un AEC real no roza: hasta 20.000 elementos, 32 atributos y 8 declaraciones de namespace por elemento, y 1.024 declaraciones en total. Las firmas tienen que ser RSA, y la carátula del sobre es la de la última cesión: RutCedente es su cedente y RutCesionario, su cesionario. Estos errores, con su texto exacto (<Elemento> es la etiqueta que excede el tope):

  • No es un XML legible: Tiene más de 20000 elementos.
  • No es un XML legible: <Elemento> trae más de 32 atributos.
  • No es un XML legible: <Elemento> trae más de 8 declaraciones de namespace.
  • No es un XML legible: Tiene más de 1024 declaraciones de namespace.
  • La firma del DTE no es válida: el KeyValue no es un RSAKeyValue (trae un DSAKeyValue): solo RSA está soportado. (o «del DTECedido», «de la cesión N», «del sobre (DocumentoAEC)»).
  • La carátula no calza con la última cesión: Caratula/RutCedente es X y el cedente de la cesión N es Y. La carátula trae el «RUT del Cedente», quien envía el archivo (cesion_v1.1_2013-02.pdf p. 6).
  • La carátula no calza con la última cesión: Caratula/RutCesionario es X y el cesionario de la cesión N es Y. La carátula trae el «RUT a quien va dirigido el Archivo de Cesión» (cesion_v1.1_2013-02.pdf p. 6).

El precheck de un documento en tenencia agrega estos problemas, con su texto exacto: La empresa ya volvió a ceder este documento (estado "cedido"): ya no es la tenedora., El AEC guardado ya tiene N cesiones: el formato admite hasta 40 (AEC_v10.xsd:70), no cabe otra., El AEC guardado ya no se lee como válido: …, La empresa (X) no es el último cesionario del AEC guardado (Y): solo cede el documento quien lo tiene en tenencia (ins_tecnico_cesion.pdf p. 5)., El RPETC informa que el documento no figura cedido: la cadena del AEC recibido no está anotada en el Registro y no se cede sobre ella. y El RPETC no confirmó que el documento esté cedido (ESTADO X: glosa); no se cede a ciegas.. Además lee el AEC guardado como lo lee la cesión al armar el AEC nuevo, así que trae también esos problemas con el mismo texto que daría ceder; por ejemplo El AEC anterior tiene que declararse en ISO-8859-1 (<?xml version="1.0" encoding="ISO-8859-1"?>): sus bytes se copian tal cual. (un AEC en UTF-8 se recibe, pero para volver a cederlo tiene que venir en ISO-8859-1, porque sus bytes se copian sin tocar al AEC nuevo). precheck.documento.verificacion es el de arriba.

json
GET /api/empresas/:empresaId/cesiones/recibidas/6ada3b4af03de3bcbd0d9ed6/precheck
{
  "success": true,
  "precheck": {
    "cedible": true,
    "documento": {
      "id": "6ada3b4af03de3bcbd0d9ed6",
      "origen": "tenencia",
      "ambiente": "certificacion",
      "tipoDte": 33,
      "folio": 149,
      "fechaEmision": "2026-10-06",
      "montoTotal": 1190,
      "rutEmisor": "78287987-1",
      "razonSocialEmisor": "MI APLICACION SPA",
      "rutReceptor": "78287987-1",
      "razonSocialReceptor": "MI APLICACION SPA",
      "estado": "en_tenencia",
      "seqUltimaCesion": 2,
      "ultimoCesionario": { "rut": "78287987-1", "razonSocial": "MI APLICACION SPA" },
      "verificacion": { "firmas": "integridad", "cadenaDeConfianza": false, "registro": "se_valida_al_ceder", "nota": "…" }
    },
    "verificaciones": {
      "estadoCesion": { "cedido": true, "estadoRespuesta": "0", "glosa": "Documento Cedido" }
    },
    "…": "problemas, habilitada, plan, sugerido y declaracionJurada, como siempre"
  }
}
json
POST /api/empresas/:empresaId/cesiones
{ "documentoTenenciaId": "6ada3b4af03de3bcbd0d9ed6", "cesionario": { … }, "montoCesion": 1190, … }

HTTP/1.1 201 Created
{
  "success": true,
  "cesion": {
    "id": "…",
    "documento": { "id": "6ada3b4af03de3bcbd0d9ed6", "origen": "tenencia", "verificacion": { … }, "…": "…" },
    "estado": "enviado",
    "trackid": "263106600",
    "trackidTexto": "0263106600",
    "seqCesion": 3,
    "montoCesion": 1190,
    "cesionario": { "rut": "76123456-0", "razonSocial": "Factoring de Prueba SpA" },
    "avisos": []
  }
}

Errores propios al ceder un documento en tenencia: 400 con emitidaId y documentoTenenciaId juntos («Se cede un documento emitido (emitidaId) o uno en tenencia (documentoTenenciaId), nunca los dos.») y 404 CESION_DOCUMENTO_NO_ENCONTRADO («El documento en tenencia no existe en esta empresa.»). Lo demás, como en la primera cesión. Lo que no se ha probado contra el SII: consultar la cedibilidad y el estado de cesión de un documento de otro emisor con el certificado de la empresa; si el SII no responde lo esperado, el precheck lo deja como un problema y no se cede.

Auditoría tributaria

26 endpoints bajo /api/auditoria-tributaria/:empresaId: nueve alcanzables con una API key y 17 solo con sesión. Acá se documentan los nueve de API key y nueve de los de sesión (cuatro de aceptación y reclamo y cinco de la regla de reclamo automático); POST /sync, POST/DELETE /clave y POST /probar-sesion se mencionan por su relación con la sincronización, y los cuatro restantes (PUT /configuracion, POST /renta/gastos, DELETE /renta/gastos/:gastoId y PUT /renta/perdida-arrastre) son del panel y no se detallan (de POST /renta/gastos se cuentan solo sus meses, más abajo). Todo lo que escribe (guardar la clave tributaria, probar sesión, cambiar régimen, disparar un sync, registrar una acción sobre un DTE recibido, consultar y guardar su estado de reclamo, configurar la regla de reclamo automático, gastos de renta, pérdida de arrastre) es inalcanzable con una API key. Los seis de sii:leer no hablan con el SII: leen lo que el último sync dejó guardado.

RutaScopeParámetros
GET /configuracionsii:leerRégimen, tasas, si hay clave guardada (nunca la clave) y la sincronización de cada noche: configuracion.syncAutomaticaActiva, configuracion.syncAutomaticaConsentimiento (quién la encendió, ver abajo) y consentimientoSyncNocturna ({ version, texto }, el texto vigente de la autorización). También escrituraReclamo: si aceptar o reclamar sale hoy en cada ambiente (ver abajo).
GET /panelsii:leerperiodo=AAAA-MM, meses (máx. 36, default 12). Proyección del IVA con el F29 esperado, lo que vence (porVencer), los giros del SII con su estado de pago (giros) y la auditoría (ver abajo).
GET /auditoriasii:leermeses (máx. 48, default 24), hasta=AAAA-MM.
GET /documentossii:leerorigen=compra|venta, periodo, q, pagina, limite (máx. 100, default 25). Cada documento trae id y reclamo.
GET /rentasii:leeranio. Régimen, tasa, PPM, pérdida, «a la fecha» y proyección al cierre (ver abajo).
GET /sync/estadosii:leerCuándo corrió el último sync y cómo terminó. ultima es siempre la última corrida completa (ventas, compras y formularios); la de la vuelta automática del RCV de compras va aparte, en ultimaCompras.
GET /documentos/:tipoDoc/:folio/eventossii:consultar_en_linearutEmisor obligatorio.
GET /documentos/:tipoDoc/:folio/cediblesii:consultar_en_linearutEmisor obligatorio.
GET /documentos/:tipoDoc/:folio/plazosii:consultar_en_linearutEmisor obligatorio.

Parte de la auditoría requiere MiAplicación ERP

GET /panel, GET /auditoria (F29), GET /renta con sus gastos y pérdida de arrastre, y todo lo de aceptar o reclamar con sus reglas responden 403 PLAN_SIN_ERP a una empresa sin ERP. GET /configuracion, GET /documentos (el RCV), GET /sync/estado, las tres consultas en línea y la sincronización siguen en la API. Ver MiAplicación API y ERP.

Las tres consultas en línea van al SII de verdad

Abren una conexión al web service oficial firmando con el certificado digital de la empresa. Restricciones que conviene conocer antes de llamarlas: van con un scope aparte que no se concede por defecto; rutEmisor es obligatorio (query, con guion; sin él, 400); solo operan tipos 33, 34 y 43 (el resto se corta con un 400 antes de gastar una autenticación); el plazo de 8 días corre desde la recepción en el SII, no desde la emisión; un documento no cedible no es un error, es un veredicto con su motivo; y si el SII responde un historial de eventos que no se puede leer, GET .../eventos responde 502 RECLAMO_EVENTOS_ILEGIBLES (no se toma como «sin eventos»).

bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/auditoria-tributaria/$EMPRESA_ID/documentos/33/121/plazo?rutEmisor=78287987-1"

Cambio incompatible en GET /documentos (07-10-2026): id en vez de _id

Cada documento trae id (string) en vez de _id, como el resto de la API. Esta ruta acepta API keys con sii:leer: si leías _id, cambia a id. Los integradores conocidos no la usan.

Cambio incompatible en GET /sync/estado y GET /panel (07-10-2026)

Cada corrida trae id (string) en vez de _id. En GET /sync/estado son ultima, ultimaCompras y cada elemento de reanudables[]; en GET /panel van dentro de sincronizacion: sincronizacion.ultima y cada elemento de sincronizacion.reanudables[]. Las dos rutas aceptan API keys con sii:leer: si leías ultima._id, sincronizacion.ultima._id o el _id de una reanudable, cambia a id.

Además de los datos del RCV, cada documento trae reclamo: su estado en el Registro de Aceptación o Reclamo del SII (Ley 19.983) tal como quedó en la última consulta que hizo el panel, o null si nunca se consultó (y siempre en las ventas). No lo llena el sync: lo escribe POST /documentos/estado-reclamo, que es solo con sesión.

Campo de reclamoQué es
fechaRecepcionSiiRecepción en el SII (instante UTC). Desde acá corren los 8 días.
venceEnFin del plazo de 8 días corridos (instante UTC).
eventosHistorial del SII: codEvento, descEvento, rutResponsable (la persona que firmó) y fecha en UTC. null si nunca se pudo leer.
eventosLeidosEnCuándo se leyó ese historial. Pasado venceEn, solo una lectura posterior a venceEn más 1 hora prueba que nadie reclamó dentro del plazo: venceEn es la más temprana de las dos lecturas del plazo, que difieren hasta 1 hora con el cambio de horario.
cedible{ codResp, descResp, cedible, motivo } de la consulta de cedibilidad, o null.
noAplicatipo (el registro solo opera 33, 34 y 43), contado (evento PAG o codResp 27 del SII) o null.
rechazo27{ metodo, en } si el SII respondió codResp 27 (pagada al contado o gratuita) a una consulta; queda guardado. Si no, null.
actualizadoEnÚltima consulta que trajo algún dato (también la que solo trajo la cedibilidad).
error{ code, codResp, mensaje, en } de la última consulta si falló, o null.

GET /panel y GET /renta: el F29 esperado, lo que vence y la renta de abril

Campos agregados el 16-10-2026. Todos son nuevos: los que ya existían siguen con el mismo nombre y la misma forma, salvo el vencimiento a día hábil y los tres cambios de significado de GET /renta que se explican al final.

Campo de GET /panelQué es
porVencerLo que vence según hoy: el F29 del mes que toca declarar más los giros sin pagar que vencen ese mismo mes. null si no se pudo calcular (el resto del panel sale igual).
proyeccion.f29EsperadoEl F29 completo esperado del período: ivaDeterminado (el aPagar de siempre), retencionCambioSujeto (lo retenido en las facturas de compra 46), ppm y total, más lo declarado y diferenciaTotal. proyeccion.aPagar sigue siendo solo el IVA.
proyeccion.avisos[]Lo que conviene saber del período antes de declararlo: { id, tipo, severidad, titulo, explicacion, monto }, con tipo comprobantes_pago_con_facturas, ppm_sobre_tasa_legal o ppm_sin_tasa_legal.
proyeccion.ivaPostergado[]Un giro por cada F29 del período y de los tres anteriores con IVA postergado (código 755 mayor que 0): { id, periodo, etiqueta, monto, vence, diasParaVencer, estadoPago, nota, folio, saldo, fechaPago, banco }. Cada uno se cruza con el giro del SII de su período (concepto 283) y toma de él estadoPago, folio, saldo y el vencimiento (ver «Giros del SII y su estado de pago»). Sin ese giro, estadoPago es por_verificar y folio, saldo, fechaPago y banco vienen en null.
giros[]Los giros del SII del año actual y del anterior (en Chile), del período más reciente al más antiguo, cada uno con su estado de pago (ver «Giros del SII y su estado de pago»). [] si no hay o si la lectura falla (el resto del panel sale igual).
auditoria.avisosInformativosCuántos avisos solo informan (hoy, ppm_sobre_tasa_legal). Están en las listas de hallazgos, pero no en totalHallazgos.

porVencer trae { fecha, diasParaVencer, periodoF29, etiqueta, f29, giros, total, nota }:

  • periodoF29 es normalmente el mes anterior; pasado su vencimiento, el mes en curso (el mismo día del vencimiento sigue siendo el del mes anterior). fecha es ese vencimiento, el día 12 o 20 según diaVencimientoF29, ya corrido a día hábil.
  • f29 es { totalEsperado, declarado, origenTotal }. Si ese F29 no está declarado, totalEsperado es el f29Esperado.total y origenTotal es esperado. Si ya está declarado y posterga IVA, va su código 91 (lo que se paga en el plazo, sin el IVA postergado) con origenTotal: "codigo_91", para no contar dos veces el 755.
  • giros son los de ivaPostergado que vencen ese mismo mes y no están pagado, más cualquier giro del SII con saldo que venza ese mes aunque no sea un postergado (una diferencia de impuesto, por ejemplo). Ese último trae los mismos campos más concepto, la glosa del SII («Diferencia de impuesto f.29»), con id igual a su folio; su periodo, etiqueta, vence y diasParaVencer pueden venir en null.
  • total suma el F29 y cada giro: su saldo si se leyó del SII; si no, su monto.
  • nota avisa cuando la fecha cae en un año fuera de la tabla de feriados; si no, null.

En f29Esperado:

  • total es el IVA determinado más la retención por cambio de sujeto más el PPM a la tasa legal.
  • ppm es { base, tasaLegal, tasaLegalFundamento, porConfirmar, monto, tasaDeclarada, tasaDeclaradaOrigen, montoDeclarado }. La base es la del código 563: ventas netas más exentas del período, con los comprobantes 48. La tasa legal sale del régimen: en el 14 D N°3, 0,25% o 0,5% según los ingresos del año anterior (hasta o sobre 50.000 UF), a la mitad entre 2025-08 y 2027-12 (Circular SII 53/2025, punto 2.2); en el 14 D N°8, 0,2% o 0,5%; en el 14 A, 1% en el primer ejercicio. Sin tasa legal (14 A después del primer ejercicio, o sin régimen) tasaLegal y monto vienen en null, el total no suma PPM y sale el aviso ppm_sin_tasa_legal. porConfirmar: true quiere decir que la tasa legal no se pudo confirmar; lo habitual es que no se conozcan los ingresos del año anterior, y entonces se usó el tramo bajo. tasaDeclarada es la del F29 presentado: el código 115 si calza con el PPM pagado (tasaDeclaradaOrigen: "codigo_115") o, si no, la efectiva 62/563 ("efectiva_62_563").
  • declarado es lo que dice el F29 presentado: ivaDeterminado (89), retencion (39), ppm (62), tasaPpm (115), total (91) e ivaPostergado (755). null si no hay F29 sincronizado.
  • diferenciaTotal es lo declarado (91 más 755) menos total. Positivo quiere decir que se declaró más. null sin F29.

Los vencimientos (proyeccion.vencimiento, porVencer.fecha y el vence de cada giro) se corren a día hábil por sábado, domingo, 31 de diciembre y feriados. Los feriados salen de una tabla con las publicaciones oficiales de Gob.cl de 2025 y 2026; en otros años solo se corre por fin de semana y 31 de diciembre, y la nota lo dice. El giro de IVA postergado vence el mismo día (12 o 20) del tercer mes después del período: el de julio de 2026 vence el 20-10-2026. Si el postergado se cruzó con su giro del SII, su vence es el vencimiento que dice el SII.

Giros del SII y su estado de pago (16-10-2026). El F29 no dice si un giro ya se pagó: lo dice el SII en «Consultar y pagar giros». La sincronización con la clave tributaria guardada (la automática diaria, si está activa, o POST /sync) lee ahí los giros del año actual y del anterior y los guarda. GET /panel no habla con el SII: muestra lo que leyó la última sincronización.

estadoPagoCuándo
pagadoEl saldo del giro es 0 (saldo 0 = pagado). fechaPago (AAAA-MM-DD, fecha de Chile) y banco salen del último pago, prefiriendo el aceptado («Pago de Giro con PEL aceptado»); un saldo 0 sin ningún pago queda pagado con los dos en null.
pendienteSaldo mayor que 0, hasta el día del vencimiento inclusive.
vencidoSaldo mayor que 0, después del vencimiento.
por_verificarNo hay un giro leído del SII, o el SII no informó su saldo. Es lo que salía siempre antes de este cambio.

El estado del documento en el SII («Vigente») no decide: un giro pagado sigue «Vigente».

Cada elemento de giros[] trae { id, folio, anio, periodo, etiqueta, formulario, formularioAsociado, conceptos, montos, vencimiento, emision, saldo, estadoDocumento, pagos, estadoPago, fechaPago, banco, leidoEn }:

  • folio es string (supera los 2^31). periodo es AAAA-MM y etiqueta, por ejemplo, «julio 2026».
  • conceptos es [{ codigo, glosa, monto }], por ejemplo 283 «Postergación de Pago del IVA».
  • montos es { neto, reajustes, interesesMultas, total } (códigos 91, 92, 93 y 94). Un código ausente viene en null, no en 0.
  • vencimiento y fechaPago son fechas AAAA-MM-DD sin hora, de Chile: léelas como texto. Pasadas por un Date de JavaScript quedan en la medianoche UTC, que en Chile todavía es el día anterior. emision, leidoEn y las fechas de pagos son instantes ISO-8601.
  • pagos es [{ fecha, banco, monto, folioPago, medio, aceptado, aceptadoEn }].
  • leidoEn es cuándo lo leyó la sincronización.

Cambio de significado para quien ya lee estadoPago (16-10-2026)

Hasta ahora era siempre por_verificar; ahora puede ser pagado, pendiente o vencido. Además, porVencer.giros ya no trae los giros pagados y puede traer giros que no son postergados, con concepto, y porVencer.total suma el saldo de cada giro leído del SII en vez del monto del F29.

Hallazgo nuevo en auditoriaSeveridadQué dice
comprobantes_pago_con_facturasmediaUn período trae comprobantes de pago electrónico (48) junto con facturas o boletas: si esos pagos también se facturaron, el débito queda duplicado. monto y plataEnJuego son el IVA de los 48. Sale también en GET /auditoria.
ppm_sobre_tasa_legalbaja (informativo)Aviso anual, uno por año, con periodo: null, anio, periodos, detalle[] por mes y porConfirmar: el PPM declarado supera al de la tasa legal. Es plata adelantada que se recupera en abril. plataEnJuego es 0, no marca los meses como «con hallazgos» y no cuenta en totalHallazgos (va en avisosInformativos). Hoy sale solo en GET /panel.

En GET /renta, sin anio sigue siendo el año anterior, el que se declara en abril:

Campo de GET /rentaQué es
regimenEfectivo, regimenEfectivoEtiqueta, regimenOrigenEl régimen con que se calcula. Si la configuración tiene uno, gana (regimenOrigen: "configuracion"); si dice sin_definir, sale del F22 (código 1440, 14 D N°3; código 1690, 14 A; "f22"). regimen y regimenEtiqueta siguen siendo los de la configuración. Si la configuración choca con el F22, va un aviso.
tasaOrigen, fundamentoTasaDe dónde sale tasaPrimeraCategoria: configuracion o tabla (la tabla verificada por régimen y año, con su fundamento).
noPagaPrimeraCategoriatrue en el 14 D N°8: la empresa no paga primera categoría (tributan los dueños), así que estimacion y proyeccionCierre vienen en null.
totales.porMes[]{ periodo, mes, ingresos, compras, conDatos } por mes, más mesInicio, mesesCubiertos, mesesCerrados, mesesEsperados, ultimoMesConDatos, ultimoMesCerrado, esAnioEnCurso y esAnioCerrado, contados desde el inicio de actividades.
proyeccionCierreSolo con el año en curso: el mismo desglose de estimacion, proyectado a diciembre (los meses cerrados con RCV más su promedio por los meses que faltan), con mesesCerrados, mesesProyectados y promedioMensual. null en un año cerrado o sin meses cerrados con datos.
apartarPorMes{ monto, meses, totalAPagar, origen }: lo que queda a pagar (de la proyección o, sin ella, de la estimación) dividido por los meses que faltan hasta abril. null si no hay nada que pagar o si abril ya pasó.
ppmAdemás de total y porPeriodo: tasaUsada y tasaOrigen (declarada, la efectiva del año Σ62/Σ563, o legal), tasaLegal, sobreTasaLegal (lo pagado sobre la tasa legal, que se recupera en abril; repetido en ppmSobreTasaLegal), mesesProyectados, baseMensualProyectada, proyectado, totalConProyeccion e ingresosAnioAnteriorUf.
perdidaArrastreOrigen, perdidaArrastreManual, perdidaF22De dónde sale la pérdida: manual (la ingresada en el panel) o f22 (la del F22 de ese año tributario: el 1440 si es negativo o, si no, el 1706, sin reajuste por IPC). Si las dos existen y difieren, se usa la manual y va un aviso. Una manual en 0 es «sin pérdida» declarado en el panel: también manda sobre la del F22. Sin manual, perdidaArrastreManual es null.
gastosManuales[]Cada gasto con mesDesde y mesHasta (null si es anual) y montoALaFecha.
listaControlSueldoCon un gasto sueldo_empresarial, lo que lo respalda: pago efectivo, Libro de Remuneraciones Electrónico, DJ 1887 en marzo e impuesto único exento hasta 13,5 UTM. Sin ese gasto, null.
avisos[]{ tipo, mensaje }: régimen en conflicto, sin primera categoría, pérdida desde el F22 o distinta de la del F22, y sin proyección.

ppm.ingresosAnioAnteriorUf viene en null a propósito en el año de inicio de actividades: no hay año anterior y la tasa legal es la del tramo bajo. En los demás años, null quiere decir que no se conocen esos ingresos (falta la UF de diciembre o algún F29): se usa el tramo bajo y la tasa queda por confirmar.

Cambios de significado en GET /renta (16-10-2026)

  • estimacion es «a la fecha»: el RCV del año hasta el último mes con datos y los gastos manuales prorrateados a esos meses (un gasto anual cuenta en la proporción de meses cubiertos; uno con meses, la parte de sus meses que cae ahí). Antes los gastos entraban completos. En un año cerrado con el RCV completo da lo mismo que antes. La cifra al cierre del año en curso es proyeccionCierre.
  • perdidaArrastre es la pérdida efectiva: la ingresada a mano o, si no hay, la del F22. Antes era solo la ingresada a mano.
  • tasaPrimeraCategoria ya no queda en null sin configuración: sale de la tabla verificada por régimen y año, con tasaOrigen: "tabla" y su fundamentoTasa. faltaConfiguracion queda en true solo si ni la configuración ni el F22 dan un régimen, o si el año cae fuera de la tabla.

POST /renta/gastos (solo con sesión, del panel) acepta además mesDesde y mesHasta, opcionales: los dos o ninguno, enteros de 1 a 12, con mesDesde menor o igual que mesHasta. Con ellos, monto es el total de esos meses; sin ellos, el gasto es del año entero, como antes. Un mes que no sirve responde 400 SII_CONFIG sin guardar nada. Hay una categoría nueva, sueldo_empresarial, que cuenta como remuneración.

Solo con sesión (una API key recibe 403 aunque tenga scopes), y se documentan porque lo que escriben aparece en GET /documentos. Requieren MiAplicación ERP (403 PLAN_SIN_ERP sin él) POST /documentos/accion, la habilitación, GET /reclamo/acciones y la regla de reclamo automático; POST /documentos/estado-reclamo, que solo lee el SII, sigue en la API:

RutaQuiénQué hace
POST /documentos/estado-reclamoadmin, contadorConsulta en el SII (solo lectura) hasta 5 compras por petición y guarda el resultado en su reclamo.
POST /documentos/accionadminRegistra ACD, ERM, RCD, RFP o RFT en el SII. Irreversible. Funciona en certificación, para un documento de certificación (ambiente: certificacion); en producción hoy responde 501.
PATCH /reclamo/habilitacionadminEnciende o apaga la aceptación y el reclamo para la empresa.
GET /reclamo/accionesadmin, contadorBitácora local de las acciones enviadas sobre un documento.
GET /reclamo/reglasadmin, contadorLa regla de reclamo automático, si puede pasar a modo real y qué le falta (modoReal.faltan), y advertencias.
PUT /reclamo/reglasadminCambia la regla (parcial). 422 REGLA_RECLAMO_INVALIDA con todos los detalles; 409 REGLA_MODIFICADA si otro la cambió o el updatedAt del body ya no es el vigente.
POST /reclamo/reglas/modo-realadminPasa la regla a modo real con { confirmacion: "RECLAMAR AUTOMATICAMENTE", updatedAt }. 422 REGLA_MODO_REAL_REQUISITOS con todo lo que falta.
GET /reclamo/reglas/bitacoraadmin, contadorBitácora de la regla, paginada (pagina, porPagina; filtros resultado, modo, rutEmisor, folio).
GET /reclamo/reglas/simulacionadmin, contadorQué haría la regla hoy, sin llamar al SII ni escribir.

POST /documentos/estado-reclamo responde un resultado por documento, en el mismo orden; la falla de un documento va en su error con un 200. Lo que es de la empresa corta la petición entera sin escribir nada: 501 (consulta del SII sin confirmar o apagada), 409 (modo demo), 400 (sin certificado) y 502 SII_TOKEN_NO_DISPONIBLE si el SII no entregó el token, que se pide una vez por petición. Tiene un tope de 12 peticiones por minuto y por empresa (60 documentos): 429 ESTADO_RECLAMO_LIMITE. No gastan ese cupo las peticiones a una empresa ajena ni las de un rol sin acceso a la auditoría (las dos reciben 403). Si el SII rechaza el token a mitad de tanda, la respuesta sigue siendo 200 y los documentos que faltaban vuelven con resultados[].error.code SII_TOKEN_NO_DISPONIBLE, sin consultar.

POST /sync (solo con sesión) responde 409 SII_SYNC_EN_CURSO si ya hay una sincronización corriendo, también la de otra empresa o la vuelta automática del RCV de compras: el candado es uno para todo el servidor. Esa vuelta, que trae las compras 33, 34 y 43 (período actual y anterior) de todas las empresas con clave tributaria, viene apagada por defecto: corre solo si el operador del servidor la enciende con SII_RCV_COMPRAS_CRON=true, y entonces 3 veces al día (por defecto 8:40, 14:40 y 20:40 de Chile; SII_RCV_COMPRAS_CRON_HORAS cambia las horas). Mientras esté apagada, las compras recientes y sus plazos de 8 días se ponen al día solo con POST /sync. Si está encendida, sus corridas salen en GET /sync/estado en ultimaCompras, con alcance: compras_recientes.

Si el SII rechazó la clave tributaria, la cuenta está bloqueada o la clave vencida, POST /sync, POST /probar-sesion y POST /api/empresas/:empresaId/bhe/recibidas/sincronizar responden 422 SII_CLAVE_RECHAZADA con { code, motivo, message } (motivo: rechazada, bloqueada o vencida) sin entrar al SII: otro intento con la misma clave acerca el bloqueo de la cuenta. Sigue así hasta que se vuelva a guardar la clave (POST /clave). GET /configuracion trae el mismo motivo en configuracion.ultimoLoginErrorMotivo (o null). La sincronización estándar (sin tipo: "historica") responde 429 SII_SYNC_ENFRIAMIENTO con { code, message, disponibleEn } (ISO) si una sincronización completa de la empresa, manual o automática, terminó hace menos de 10 minutos; las fallidas no cuentan y guardar la clave reinicia la espera. Ninguno de los dos crea una corrida.

Mientras corre una sincronización, guardar o borrar la clave tributaria (POST/DELETE /clave) y POST /probar-sesion también responden 409 SII_SYNC_EN_CURSO sin hacer nada: usan la misma sesión del portal. Si lo que ocupa el servidor es la vuelta de compras, el 409 de POST /sync trae ocupadoPor: "compras_automaticas". GET /sync/estado responde { ultima, ultimaCompras, syncComprasRecientes, enCurso, ocupadoPorOtra, ocupadoPor, reanudables, discovery, circuito }:

  • ultima y ultimaCompras (o null) traen id, tipo, alcance, estado (en_curso, completada, fallida o cancelada), inicio, fin, reanudadaEn (la última vez que se reanudó; inicio queda el original), los períodos, los contadores, errores y motivoCorte. cancelada es una corrida que se cortó porque otra tomó el turno con el SII: lo que alcanzó a bajar quedó guardado.
  • enCurso es true mientras corre la sincronización completa de esta empresa. Si el servidor está ocupado con otra corrida, ocupadoPorOtra es true; si es la vuelta de compras, además ocupadoPor es compras_automaticas (y enCurso es false, aunque la vuelta esté pasando por esta misma empresa).
  • syncComprasRecientes: el último paso de la vuelta de compras por esta empresa, { ultimaEn, resultado, mensaje, ultimaCompletaEn, claveRechazada }, o null. Con claveRechazada: true el SII rechazó la clave tributaria: la vuelta no vuelve a intentarlo hasta que se guarde de nuevo.
  • discovery y circuito: diagnóstico de la plataforma (el estado de los endpoints del portal y el del corte por fallos consecutivos al SII). Vienen siempre, en null salvo para el superadmin de la plataforma: con una API key o con cualquier otro rol son null.

La vuelta de compras recorre, de a una, las empresas con clave tributaria que no son la cuenta demo ni están pendiente, suspendida o eliminada. Si el SII pidió un desafío al ingresar, esa empresa se salta por 24 horas. La sincronización completa automática es nocturna (de 00:00 a 02:30 y de 04:00 a 06:30, hora de Chile; empresas con syncAutomaticaActiva: true) y trae también las compras: una vuelta que se saltó porque el servidor estaba ocupado se recupera esa noche.

La sincronización de cada noche viene apagada. La enciende una persona desde el panel («Conexión con el SII», PUT /configuracion, solo con sesión), aceptando el texto de consentimientoSyncNocturna: encenderla sin mandar consentimientoSyncNocturna con la version vigente (hoy sync-nocturna-v1) responde 422 SII_SYNC_NOCTURNA_SIN_CONSENTIMIENTO con { code, error, consentimiento: { version, texto } } y no guarda nada de ese pedido. Queda registrado quién la encendió (usuario y correo), cuándo y qué versión aceptó: GET /configuracion lo trae en configuracion.syncAutomaticaConsentimiento ({ version, email, fecha }, o null si nadie la encendió con consentimiento). Apagarla, o mandar true ya encendida, no pide nada ni cambia ese registro. Nada la enciende por lote.

POST /documentos/accion acepta además motivoInterno (opcional, hasta 500 caracteres): queda en la bitácora local y nunca se envía al SII. GET /reclamo/acciones lo devuelve en cada acción.

POST /documentos/accion tiene un tope de 10 peticiones por minuto y por empresa (SII_MAX_RECLAMO_ACCION_POR_MINUTO): 429 RECLAMO_ACCION_LIMITE con { code, message }, Retry-After y RateLimit-Policy: "reclamo-accion";q=10;w=60. No gastan ese cupo las peticiones a una empresa ajena ni las de un contador o un emisor (reciben 403); el superadmin de la plataforma cuenta en el cupo de la empresa. La regla de reclamo automático no pasa por esta ruta.

bash
{ "code": "RECLAMO_ACCION_LIMITE", "message": "Superaste el límite de aceptaciones y reclamos en el SII por minuto para esta empresa. Reintenta en unos segundos." }

GET /configuracion trae escrituraReclamo: si aceptar o reclamar sale hoy en cada ambiente, { produccion: { disponible, deshabilitadoPorEntorno }, certificacion: { disponible, deshabilitadoPorEntorno } }. Con disponible: false, POST /documentos/accion responde 501 en ese ambiente; con deshabilitadoPorEntorno: true, porque el servidor la apagó. Hoy produccion.disponible es false. Si la empresa la encendió es otro dato: configuracion.reclamo. El panel no ofrece aceptar ni reclamar donde la respuesta sería 501: muestra un aviso y remite al portal del SII.

Verificado en certificación el 22-10-2026, en el registro de pruebas del SII y con facturas 33 a crédito de una empresa a sí misma: las cinco acciones (ACD, ERM, RCD, RFP y RFT) respondieron codResp 0 y cada una grabó un solo evento, con codEvento igual a la acción. Los rechazos 7 (evento registrado previamente), 8 (pasados 8 días desde la recepción), 11 (reclamar un documento aceptado) y 12 (aceptar uno reclamado) no grabaron ningún evento. Fuera de plazo todo responde 8, aunque el documento ya tenga eventos (manual del web service v1.2, p. 6): el 11 y el 12 solo salen dentro de los 8 días. Las fuentes oficiales (ese manual y la Ley 19.983) están guardadas, con su sha256, en api/docs/sii-fuentes/. En producción, POST /documentos/accion sigue respondiendo 501.

La regla de reclamo automático reclama (RCD) en el SII las facturas recibidas que la empresa no aceptó a tiempo, salvo las de los proveedores de su lista blanca. Está disponible en todos los planes, viene apagada y empieza en simulación: lee el SII para refrescar los eventos, deja en su bitácora lo que habría reclamado y nunca escribe en el SII.

CampoPor defectoQué es
activafalseApagarla la devuelve a simulación.
modosimulacionsimulacion o real. A real solo se pasa por POST /reclamo/reglas/modo-real.
accionRCDRCD (reclamo por el contenido del documento) o solo_notificar. Nunca una aceptación automática.
condiciones.tipos33, 34 y 43Los tipos que opera el registro del SII, sin repetir.
condiciones.montoMinimo0Monto total mínimo, en pesos, para que la regla actúe.
condiciones.rutListaBlancavacíaEmisores que la regla nunca reclama (hasta 500 RUT).
condiciones.rutListaNegravacíaSi tiene alguno, la regla actúa solo sobre esos emisores (hasta 500 RUT). Un RUT no puede estar en las dos listas.
horasAviso / horasAccion144 / 168Horas desde la recepción en el SII en que avisa y en que actúa. horasAccion no pasa de 168 (el plazo vence a las 192) y entre las dos van al menos 24 horas.
notificarEmisorfalseEl correo de cortesía al emisor todavía no está disponible: true es 422.

Para pasar a modo real hacen falta al menos 14 días en simulación, la regla activa con acción RCD, la aceptación y el reclamo habilitados en la empresa, el servicio de correo configurado y al menos un admin activo con correo. En modo real el PUT solo puede achicar el alcance. En la duda, no reclama (la factura queda aceptada tácitamente): solo reclama un documento sin ningún evento en el registro del SII (leído hace menos de 2 horas y releído justo antes de reclamar), que no esté pagado al contado ni sea gratuito, sin una aceptación o un reclamo manual pendiente, con un aviso real entregado por correo a los admins al menos 24 horas antes y con al menos 6 horas para el vencimiento. La ejecuta un proceso del servidor cada hora, que viene apagado. Mientras el registro de reclamos siga en 501 en producción, una regla en modo real no reclama nada: la bitácora y las advertencias lo dicen.

Boletas de honorarios recibidas (BHE)

Cuatro endpoints bajo /api/empresas/:empresaId/bhe/recibidas: las boletas de honorarios electrónicas que profesionales le emitieron a la empresa. No están en el Registro de Compras y Ventas, pero su retención va al F29. Las dos lecturas llevan sii:leer y no hablan con el SII: leen lo que ya está guardado.

Traerlas del SII

POST /sincronizar ya está habilitado: la consulta del portal quedó verificada con una respuesta real (07-10-2026). Es solo con sesión (admin o contador; una API key recibe 403) y la cuenta demo recibe 403. Lanza en segundo plano la sincronización de la auditoría tributaria del período (también trae el RCV y el F29): lee el informe mensual de boletas recibidas, revisa que sea el del mes y el RUT pedidos y guarda cada boleta sin duplicarla. Responde 202, 409 si ya hay una en curso (también la de otra empresa o la vuelta automática del RCV de compras), 422 sin clave tributaria y 400 con un período inválido, futuro o anterior a 24 meses (contando el actual). POST /auditoria-tributaria/:empresaId/sync también las trae en cada período.

Más de 100 boletas en un mes todavía no se leen completas

La consulta se verificó con un mes de una sola página y la paginación del portal no está verificada. Si el informe declara más boletas de las que se alcanzaron a leer, se guarda lo leído pero el período queda incompleto, con una marca que dura hasta que una lectura completa de ese mismo período la quita (otra sincronización, de este u otro período, no la borra). GET / y GET /resumen la traen en periodosIncompletos ([{ periodo, motivos, marcadoEn }], acotado al filtro; motivos, por ejemplo ["total_no_calza"]), y en el resumen ese período va con parcial: true: suma solo las boletas leídas, no lo tomes como el total del mes. La corrida que lo leyó trae además, en errores de GET .../sync/estado, uno con code: "LECTURA_INCOMPLETA", endpoint: "honorarios_recibidas", el periodo y motivo. El panel no muestra esos montos como total («Sin dato»). Una boleta anulada todavía no se ha visto en una respuesta real del portal.

RutaScopeParámetros
GET /sii:leerperiodo=AAAA-MM o desde/hasta, rutEmisor (con guion; acepta puntos), estado=VIG|ANUL, pagina (máx. 10000), limite (máx. 100, default 25).
GET /resumensii:leerperiodo o desde/hasta, rutEmisor. Totales por período, separados por quién retuvo.
POST /sincronizarsolo con sesiónBody { periodo: AAAA-MM }. Lanza la sincronización del período: 202.
GET /:id/pdfsolo con sesiónEl PDF oficial de la boleta, tal como lo entrega el SII (ver abajo).

El PDF oficial de una boleta

GET /:id/pdf entrega el PDF de la boleta tal como lo entrega el portal del SII (no uno armado por nosotros), con Content-Disposition: inline; filename="BHE_<numero>_<rutEmisor>.pdf". Habilitado desde el 08-10-2026: el pedido (armado con el informe real y los JS públicos del SII) quedó verificado con una descarga real. Si se deshabilitara, respondería 501 SII_CLIENTE_NO_IMPLEMENTADO. Es solo con sesión (admin o contador; una API key recibe 403 aunque tenga sii:leer) y la cuenta demo recibe 403: si no está guardado, abre sesión en el portal con la clave tributaria, como POST /sincronizar. El primero se guarda y los siguientes salen de nuestra base; si la boleta se anula o cambia su código de barras, se vuelve a pedir. Como un navegador, antes del PDF lee el informe del período de la boleta. 404 BHE_NO_ENCONTRADA; 409 BHE_PDF_SIN_DATOS si le falta el código de barras o el de comuna (sincroniza de nuevo su período); 409 BHE_PDF_PORTAL_OCUPADO si el portal está ocupado; 502 SII_SCHEMA_CHANGED si el SII respondió algo que no es un PDF (no se guarda nada); 422 SII_AUTH si el SII rechazó la clave.

Para no repetir el ingreso al portal con la clave: si un ingreso anterior terminó en un desafío del SII o con la clave rechazada, responde 422 BHE_PDF_VERIFICACION_SII o BHE_PDF_CLAVE_RECHAZADA hasta que se vuelva a cargar la clave (no reintentes); el desafío se destraba también si un ingreso posterior con la clave termina bien, como el de la sincronización nocturna. Con demasiadas sesiones abiertas, 422 BHE_PDF_SESIONES_EN_PAUSA por 30 minutos. Cada boleta se pide como máximo una vez cada 15 minutos mientras no llegue su PDF: dentro de esa ventana responde 429 BHE_PDF_EN_ESPERA sin ingresar al portal. Los dos últimos traen reintentarDesde (ISO 8601) y Retry-After.

Si el ingreso de este pedido termina en un desafío del SII o con demasiadas sesiones abiertas, responde 409 SII_AUTH_CHALLENGE o 429 SII_MAX_SESIONES. También sin ingresar al portal, si otro ingreso con la clave de la empresa acaba de terminar así: tras un desafío no se vuelve a intentar hasta 24 horas después, y con demasiadas sesiones, hasta 30 minutos después; entonces traen detalle.reintentarDesde (ISO 8601, o null si no se sabe cuándo fue el desafío), sin Retry-After. Tras un desafío, los pedidos siguientes responden BHE_PDF_VERIFICACION_SII hasta que se vuelva a cargar la clave o un ingreso posterior con ella termine bien. Una clave que otro ingreso acaba de marcar rechazada responde 422 SII_AUTH sin ingresar, hasta que se cargue de nuevo.

bash
curl -H "X-Api-Key: $API_KEY" \
  "$BASE/api/empresas/$EMPRESA_ID/bhe/recibidas?periodo=2026-06&estado=VIG"
Campo de cada boletaQué es
idIdentificador (string). Nunca _id.
numeroBoleta, rutEmisor, nombreEmisorNúmero de la boleta y el profesional que la emitió.
montoBruto, montoRetenido, montoLiquidoMontos en pesos tal como los informa el SII. montoRetenido suma lo retenido por el emisor y por el receptor.
retenidoPorreceptor (la empresa: lo declara y paga en su F29), emisor (el profesional) o desconocido.
estado, estadoSiiVIG o ANUL, y el valor crudo del informe.
fechaAnulacionFecha de anulación (instante UTC) o null.
codigoBarrasCódigo de barras según el informe, o null.
sociedadProfesionalestrue o false si el emisor es una sociedad de profesionales; null si el informe no lo dice.
retencion{ tasa, esperada, diferencia, calza }: la retención esperada para el año de la boleta frente a la retenida.

La tasa esperada es la del año de la boleta: 15,25 % en 2026, 16 % en 2027 y 17 % desde 2028 (Ley 21.133, art. 5 y art. quinto transitorio; pregunta frecuente del SII 001.140.7297.004 del 01-04-2026). Para los años anteriores la tasa no está verificada y calza viene en null. calza: false es una advertencia, no un error: se tolera 1 peso por redondeo y una boleta anulada no se compara.

GET /resumen responde { periodos, totales }: cada período trae cantidad, bruto, retenido y liquido de las vigentes, porRetenedor (receptor, emisor, desconocido) y anuladas aparte, porque no suman. liquido es lo que el SII informa como honorarios líquidos. Cada período trae además parcial (true si se leyó incompleto: la suma es parcial) y motivosParcial; totales.parcial es true si el filtro abarca algún período incompleto, y la respuesta trae periodosIncompletos, igual que GET /. Un filtro inválido responde 400 BHE_FILTROS_INVALIDOS con todos los errores juntos en detalles.

Boletas de honorarios emitidas (BHE)

Bajo /api/empresas/:empresaId/bhe/emitidas: las boletas de honorarios que la plataforma emite a nombre del titular de la clave tributaria de la empresa. El mandato y el estado de la emisión no cuelgan de esa base: van en /api/empresas/:empresaId/bhe/mandato y /api/empresas/:empresaId/bhe/estado-emision (ver su tabla, más abajo). Las dos lecturas llevan bhe:leer y no hablan con el SII: leen el libro local, ensayos incluidos. Con una API key basta ese scope (solo en su empresa). Con sesión (JWT) solo leen el superadmin, un admin o un contador de la empresa: un emisor recibe 403 BHE_SIN_PERMISO.

Emitir todavía no está habilitado

Se puede validar y preparar una boleta (un ensayo local), pero confirmarla responde 501 SII_CLIENTE_NO_IMPLEMENTADO y no envía nada al SII: la boleta sigue en ensayo. La boleta de honorarios no tiene ambiente de certificación: un contexto de pruebas (key mk_cert_, cuenta demo, modo demo o configuración de emisión en certificación) recibe 422 BHE_SIN_AMBIENTE_DE_CERTIFICACION. Una empresa que solo emite boletas de honorarios, sin configuración de emisión de DTE, no cuenta como contexto de pruebas.

RutaScopeQué hace
GET /bhe:leerestado, pagina (máx. 10000), limite (máx. 100, default 25). Responde { boletas, total, pagina, limite, totalPaginas }.
GET /:idbhe:leer{ boleta }, o 404 BHE_NO_ENCONTRADA. Nunca trae el token de confirmación.
POST /validarsolo con sesiónVista previa con la retención estimada y montoLiquidoEstimado, o 400 BHE_PAYLOAD_INVALIDO con todos los errores en detalles.
POST /solo con sesiónCabecera Idempotency-Key. Prepara el ensayo: 201 con confirmacion { token, venceEn } (15 minutos). La misma key con la misma boleta responde 200 sin token; con otra boleta (o un cuerpo inválido, con sus detalles), 422 BHE_IDEMPOTENCY_KEY_REUTILIZADA.
POST /:id/confirmarsolo con sesiónBody { token, confirmo: true }. Hoy responde 501 y la boleta sigue en ensayo.
POST /:id/anularsolo con sesiónBody { motivo, confirmo: true }, con uno de los tres motivos oficiales del SII (no_pago, servicio_no_prestado, error_digitacion). Hasta el día 10 del mes siguiente a la fecha de la boleta es inmediata; desde el 11 y hasta el 1 de marzo siguiente, incluido, sujeta a la confirmación del receptor; desde el 2 de marzo, o con 100 millones o más, 422 BHE_ANULACION_FORMULARIO_2117. Hoy responde 501 y la boleta sigue emitida.

Las tres escrituras son del titular o de un admin de la empresa, y confirma el mismo usuario que preparó la boleta. retencionEstimada es una estimación nuestra (la tasa del año de la fecha de la boleta), no el dato del SII; sii, numero y codigoBarras quedan en null hasta emitir. Dirección y comuna del receptor son opcionales (no verificado: la guía de 2025 las pide y la Res. Ex. 48/2017 las quitó de los datos obligatorios).

La boleta (al prepararla, en el listado, en el detalle y en el 501) y la vistaPrevia de POST /validar traen montoLiquidoEstimado: el total (líquido) estimado, el bruto menos la retención estimada. Es null si no hay tasa verificada para el año de la boleta. El monto que vale es el que informa el SII (sii.montoLiquido). Con un bruto de $600.000 en 2026 (resumido: retencionEstimada trae además fuentes, nota y aviso):

json
{
  "montoBruto": 600000,
  "retencionEstimada": {
    "esEstimacion": true,
    "anio": 2026,
    "porcentaje": 15.25,
    "monto": 91500,
    "verificada": true
  },
  "montoLiquidoEstimado": 508500
}

Boletas a medias. Una boleta que queda enviando más de 30 minutos pasa sola a incierta. Una anulando igual de vieja queda con solicitudAnulacion.incierta: true. Las dos se reconcilian con el informe del SII y nunca se reenvían. El listado y el detalle hacen esta revisión antes de responder.

En confirmar y en anular, los requisitos se revisan dos veces: antes de reservar la boleta (enviando o anulando) y otra vez justo antes de enviar. Si dejaron de cumplirse entremedio, la reserva se deshace (la boleta vuelve a ensayo o sigue emitida) y la respuesta es el mismo 422 BHE_REQUISITOS_PENDIENTES con faltantes. No se envía nada. Hoy no se llega a esa segunda revisión: el 501 sale antes de la reserva.

Ruta (solo con sesión)QuiénQué hace
POST /api/empresas/:empresaId/bhe/mandatoel titularAcepta el mandato de emisión mandato-bhe-v1 (emitir y anular boleta por boleta, con confirmación expresa). Body { aceptaMandato: true, textoVersion: "mandato-bhe-v1" }. 201 con el mandato, o 200 si ya estaba vigente; 400 BHE_MANDATO_NO_ACEPTADO con el texto a aceptar.
DELETE /api/empresas/:empresaId/bhe/mandatotitular o adminRevoca el mandato y apaga la emisión en la misma operación. Sin mandato vigente, 200 con revocado: false.
GET /api/empresas/:empresaId/bhe/estado-emisionadmin, emisor, contador{ habilitada, habilitadaEn, tipoEmisor, mandato, claveCargada, requisitosCumplidos, faltantes, envioAlSii, anulacionEnElSii, motivosAnulacion }: si se puede emitir y anular, y qué falta. tipoEmisor es { tipo, rut, declaradoEn, rutActual, vigente }: tipo (persona_natural, sociedad_profesionales o null) y el rut para el que se declaró, rutActual el de la configuración SII y vigente si la declaración vale para ese RUT. Al rol emisor le llega solo { tipo, vigente } (sin los RUT, que pueden ser datos personales del titular). Nunca trae la clave.

anulacionEnElSii dice si la empresa puede anular en el SII: hace falta el formulario del portal verificado y los requisitos al día. Con el formulario verificado y requisitos pendientes, el motivo es «No se pueden anular boletas de honorarios: faltan requisitos (ver «faltantes»).». Lo de cada boleta (estado, plazo y vía) va en anulacion del detalle. motivosAnulacion son los tres motivos oficiales del SII (guía sii.cl/servicios_online/guia_anular_bhe.pdf, paso 6); codigo es lo que se manda en POST .../emitidas/:id/anular. Los dos le llegan también al rol emisor. Hoy:

json
{
  "envioAlSii": {
    "disponible": false,
    "motivo": "El envío de boletas de honorarios al SII todavía no está disponible: el formulario del portal no está verificado."
  },
  "anulacionEnElSii": {
    "disponible": false,
    "motivo": "La anulación de boletas de honorarios en el SII todavía no está disponible: el formulario del portal no está verificado."
  },
  "motivosAnulacion": [
    {
      "codigo": "no_pago",
      "texto": "No se efectuó el pago de los servicios por parte del receptor."
    },
    {
      "codigo": "servicio_no_prestado",
      "texto": "No se efectuó la prestación de servicios."
    },
    {
      "codigo": "error_digitacion",
      "texto": "Error en la digitación."
    }
  ]
}

Aceptar y revocar el mandato están cerrados en la cuenta demo compartida: un usuario de esa cuenta recibe 403 CUENTA_DEMO_RESTRINGIDA con { error: "No disponible en la cuenta demo: aceptar el mandato de emisión de boletas de honorarios.", code } (o «revocar el mandato…» en el DELETE), sin tocar nada. El superadmin de la plataforma queda exento.

La emisión la habilita el superadmin de la plataforma, empresa por empresa (no hay ruta para la empresa). Revocar el mandato o borrar la clave tributaria la apagan, y volver a cargarlos no la enciende. En el panel, la pantalla «Honorarios emitidos» prepara, confirma y anula con estas mismas rutas.

Quién puede emitir. Según el SII, solo las personas naturales con actividades de segunda categoría (FAQ 001_105_8699) y las sociedades de profesionales (FAQ 001_120_1793): una empresa común no puede emitir boletas de honorarios electrónicas, solo recibirlas. El tipo de emisor no se deduce del RUT ni se lee del SII: lo declara el superadmin de la plataforma con evidencia, para el RUT que verificó, y sin él habilitar responde 422 BHE_REQUISITOS_PENDIENTES con el faltante TIPO_EMISOR_BHE. La declaración vale solo mientras ese RUT sea el de la configuración SII de la empresa (el de la clave tributaria): si ese RUT cambia o falta, vuelve el mismo faltante, con un texto que lo dice, y confirmar o anular responden 422 hasta que el superadmin lo verifique y lo declare de nuevo. Cambiar el tipo o su RUT, o quitarlo, apaga la emisión. Declarar el mismo tipo para el mismo RUT no cambia nada, tampoco la evidencia: para refrescarla hay que quitar la declaración y volver a declararla, y eso apaga la emisión.

Contabilidad

Requiere MiAplicación ERP

A una empresa sin ERP, sus rutas le responden 403 PLAN_SIN_ERP; una que lo tuvo conserva la lectura (GET) de sus datos. Ver MiAplicación API y ERP.

Diecisiete endpoints GET bajo /api/contabilidad/:empresaId, todos con contabilidad:leer. Solo lectura: crear asientos, anular, centralizar, cerrar períodos, importar cartolas y cerrar el ejercicio exigen un usuario humano. Y en el panel solo un admin de la empresa (o el superadmin) escribe: el contador ve toda la contabilidad y recibe 403 en cada escritura. Las dos excepciones que se mantienen son de otros módulos: el contador registra cobros (pagos recibidos) y paga proveedores.

json
{
  "error": "Solo un administrador puede modificar la contabilidad; el contador la puede ver.",
  "code": "CONTABILIDAD_SOLO_ADMIN"
}
RutaParámetros
GET /plan-cuentassoloActivas, soloImputables
GET /asientosperiodo, origen, estado, pagina, limite
GET /libros/diarioperiodo=AAAA-MM (default: período actual), formato=excel
GET /libros/mayordesde, hasta, cuenta, formato=excel
GET /libros/balance-8desde, hasta, formato=excel
GET /libros/estado-resultadosdesde, hasta, formato=excel
GET /libros/balance-generalhasta, formato=excel
GET /periodos—
GET /reglas-centralizacion—
GET /activos-fijosestado, situacion, categoria, sucursal (id o matriz), responsable, q
GET /activos-fijos/catalogo—
GET /activos-fijos/etiquetasids (hasta 100), formato=80mm|58mm|carta, simbologia=qr|code128
GET /activos-fijos/exportarformato=xlsx|csv, fecha=AAAA-MM-DD y los filtros del listado
GET /activos-fijos/alertas—
GET /banco/movimientoscuenta, periodo, conciliado
GET /banco/resumencuenta, periodo
GET /banco/sugerenciascuenta, desde, hasta (AAAA-MM-DD), dias, tolerancia
GET /cierre/:anio—

Los cinco libros devuelven JSON por defecto; con ?formato=excel sale un .xlsx como adjunto. La centralización de ventas excluye los documentos del modo demo y los de certificación: la contabilidad del cliente no debe cuadrar con boletas del emisor de pruebas.

Sugerencias de calce. GET /banco/sugerencias propone, por cada movimiento de la cartola sin conciliar, hasta 3 cobros, pagos a proveedores o documentos por cobrar o pagar, con puntaje, motivos[] y la conciliacion (o el asientoPropuesto de un documento todavía sin pago). Nunca concilia: aplicar las elegidas es POST /banco/sugerencias/aplicar, solo JWT de un admin, todo o nada (422 SUGERENCIAS_INVALIDAS con detalles[]) e idempotente.

Activo fijo

Escrituras, solo JWT. Crear, editar, depreciar y dar de baja un activo fijo, y anular el asiento de su depreciación o de su baja, lo puede hacer solo un usuario admin de la empresa o el superadmin; el contador los ve (GET /activos-fijos) y recibe 403 al operar: ACTIVO_FIJO_SOLO_ADMIN en crear, editar, depreciar y dar de baja, y CONTABILIDAD_SOLO_ADMIN al anular un asiento.

  • Listado. GET /activos-fijos acepta estado, situacion, categoria, sucursal (id o matriz), responsable y q; un filtro inválido es 400 FILTRO_INVALIDO con detalles[]. Cada activo trae id (string), codigo, vidaUtilEfectivaMeses, valorLibro y advertencias[]. Si leías _id, cambia a id: la respuesta ya no trae _id, y advertencia pasó a ser la lista advertencias[].
  • Crear. POST /activos-fijos responde 201 { activo, asiento? } (antes, el activo suelto). categoria (clave de la tabla del SII, Res. Ex. N°43/2002 y N°56/2021) propone la cuenta y la vida útil normal; una vida propia se acepta con la advertencia «distinta de la tabla del SII» y la acelerada sale de la tabla; si tu plan no tiene la cuenta propuesta: 422. La acelerada exige nuevo: true (bien adquirido nuevo o internado; art. 31 N°5 LIR, Circular SII N°6/2003). Cada activo recibe codigo (AF-0001), que no se edita. Campos opcionales: marca, modelo, numeroSerie, situacion (en_uso|en_mantencion|guardado), sucursalId (null = casa matriz), ubicacion, responsableId (usuario con acceso activo a la empresa; si no, 422), garantiaHasta y compra {rutEmisor, tipoDte, folio, razonSocial}.
  • Alta contable. alta: {cuentaContrapartidaCodigo, fecha?} registra el asiento origen: "alta_activo_fijo" (debe activo, haber contrapartida) en la misma transacción y responde {activo, asiento}; con compra no hay asiento (los dos juntos: 422). Anular el alta con depreciación: 409 ACTIVO_CON_DEPRECIACION; con alta vigente no se editan valor, cuenta ni fecha (409 ACTIVO_CON_ALTA). El alta es para los bienes sin factura en el registro de compras: con factura, vincula la compra en vez del alta.
  • Compra vinculada. Un activo vinculado a su documento de compra (33, 34 o 46; identidad rutEmisor + tipoDte + folio) no queda como gasto y activo a la vez: la centralización de compras del período del documento lleva el valor de adquisición de cada activo vinculado a su cuenta y solo el resto a gasto (el asiento trae activosFijos[]; el resumen, gasto sin lo vinculado y activoFijo: { monto, activos }). Sin activos vinculados, el asiento es el de siempre. POST /activos-fijos/:id/vincular-compra {rutEmisor, tipoDte, folio, razonSocial?} (solo JWT, admin) responde 200 { activo, asiento? }: el documento tiene que estar en el RCV o en un XML cargado de tu empresa y lo vinculado no puede superar lo que lleva a gasto (si no, 422 ACTIVO_FIJO_INVALIDO con detalles[]). Con el período ya centralizado, la reclasificación (origen: "reclasificacion_compra_activo_fijo", debe activo / haber gasto) va en la misma transacción y viene en asiento (con id), solo si esa centralización sumó el documento; uno que entró a REGISTRO después se vincula sin reclasificar, con una advertencia (anula y vuelve a centralizar el período), y con una centralización anterior al 15-10-2026 responde 409 CENTRALIZACION_SIN_DOCUMENTOS. 409: ACTIVO_CON_ALTA, ACTIVO_CON_COMPRA, ACTIVO_DADO_DE_BAJA, PERIODO_CERRADO (sin escribir nada), DOCUMENTO_EN_VARIOS_PERIODOS. POST /activos-fijos/:id/desvincular-compra responde { activo, asientoAnulado?, asiento? }: anula la reclasificación o registra el reverso (409 ACTIVO_SIN_COMPRA, ACTIVO_CON_DEPRECIACION, PERIODO_CERRADO). Con la compra vinculada no se editan valor ni cuenta (409 ACTIVO_CON_COMPRA). Una reclasificación no se anula a mano (409 ASIENTO_DE_RECLASIFICACION); anular la centralización del período la anula con ella. Si al centralizar lo vinculado supera el documento: 409 COMPRA_VINCULADA_EXCEDE_DOCUMENTO. Una nota de crédito sobre la compra rebaja el gasto, no el activo; la centralización lo avisa en resumen.advertencias.
  • Documento de compra para prellenar. GET /activos-fijos/documento-compra?rutEmisor=&tipoDte=&folio= (contabilidad:leer) devuelve { documento, rcv, lineas, vinculados, montoVinculado, disponible, vinculable, motivo? }: proveedor, montos, costo y fuente (rcv o xml; null si no está en tu RCV ni en tus XML), el estado en el RCV (centralizado y incluidoEnCentralizacion: si esa centralización sumó este documento; null si no se sabe), una advertencia si el período está centralizado sin él, las líneas del XML cargado y los activos ya vinculados. Una query inválida es 400 DOCUMENTO_COMPRA_INVALIDO.
  • Trasladar y situación. POST /activos-fijos/:id/trasladar {sucursalId?, ubicacion?, responsableId?, nota?} y POST /activos-fijos/:id/situacion {situacion, nota?} (solo JWT, admin): cada cambio deja un evento en eventos[] (los últimos 200). Sin cambios: 422.
  • Baja con venta. montoVenta + cuentaContrapartidaCodigo (y opcionalmente cuentaUtilidadCodigo/cuentaPerdidaCodigo): la diferencia contra el valor libro va a 4.2.01.002 o 5.3.01.004; la factura de venta se emite aparte. Con documentoVenta: { emitidaId } (la factura o boleta que emitiste para esa venta: aceptada, de producción, no demo) la contrapartida es una cuenta puente (activo o pasivo; por defecto 1.1.02.003 Deudores varios) y la centralización de ventas abona ese puente en vez de ventas: la baja más la centralización suman la venta del activo, sin ingreso ordinario. Si esas ventas ya estaban centralizadas y la centralización sumó el documento, la reclasificación (reclasificacion_venta_activo_fijo) va en la misma transacción; anular la baja la anula o la reversa. Un documento aceptado después de centralizar no se reclasifica (advertencia).
  • Etiquetas. GET /activos-fijos/etiquetas?ids=<id>,<id>&formato=80mm|58mm|carta&simbologia=qr|code128 (contabilidad:leer: el contador también las imprime) responde un PDF con una etiqueta por activo: código, nombre, número de serie y razón social. El QR (por defecto) lleva la URL de la ficha interna del panel, https://app.miaplicacion.cl/activos-fijos/<id>?empresa=<empresaId>, que pide sesión: nunca una página pública ni datos sensibles. Con ?empresa=, quien tiene acceso a varias empresas abre la ficha en la empresa correcta. code128 imprime el código AF-0001 como código de barras. En 80 mm y 58 mm, una etiqueta por página; en carta, 10 por hoja (2 × 5, de 4 × 2 pulgadas). Hasta 100 activos por lote; más, un id que no es de la empresa, un activo sin código o un formato desconocido: 400 ETIQUETAS_INVALIDAS con detalles[].
  • Exportar. GET /activos-fijos/exportar?formato=xlsx|csv&fecha=AAAA-MM-DD (por defecto xlsx y hoy) más los filtros del listado, como adjunto: código, nombre, categoría, fila del SII, fecha y valor de adquisición, vida útil, método, depreciación acumulada y valor libro a la fecha, estado, situación, sucursal y responsable (su correo). El valor libro a la fecha sale de las cuotas cuyo período cerró en o antes de esa fecha (no del acumulado actual), más la depreciación sin cuotas (la inicial de una carga masiva), desde la adquisición. Un activo dado de baja en o antes de la fecha ya salió de los libros: 0 y 0, estado «Dado de baja». Los adquiridos después no salen; los filtros miran el estado actual. Hasta 5.000 activos: sobre eso, 400 EXPORTACION_SOBRE_EL_TOPE (con total y limite); un formato, fecha o filtro inválidos, 400 FILTRO_INVALIDO con todo junto. El CSV va en UTF-8 con BOM y ;.
  • Carga masiva inicial. POST /activos-fijos/importar (solo JWT, admin; el contador recibe 403 antes de subir el archivo), multipart con el archivo en archivo (CSV o XLSX, hasta 5 MB y 500 filas). Con ?validar=1 responde 200 { valido, total, conErrores, filas: [{ fila, nombre, detalles[], advertencias[] }] } y no escribe nada; sin validar, crea todo en UNA transacción y responde 201 { creados, activos: [{ fila, id, codigo, nombre, advertencias[] }] }; con una sola fila mala, 422 IMPORTACION_INVALIDA (detalles[] por fila) y no se crea ninguno. Otro valor de validar es 400. Columnas: las de la exportación (obligatorias Nombre, Fecha de adquisición y Valor de adquisición; fila del SII, valor libro y estado se ignoran) más Meses depreciados, Cuenta activo, Alta (la cuenta de contrapartida del asiento de alta), Nuevo, Valor residual, Garantía hasta, Marca, Modelo, N° de serie, Ubicación y Descripción. Cada fila pasa por las validaciones de POST /activos-fijos; el código se asigna solo (uno que ya existe en la empresa se rechaza: re-subir una exportación duplicaría los activos), la sucursal va por nombre y el responsable por correo. Un bien antiguo puede traer Depreciación acumulada y Meses depreciados: entra sin asientos (regístrala en tu asiento de apertura) y con una advertencia permanente, y no va con Alta.
  • Garantía por vencer. Un proceso diario avisa a 30 y a 7 días del vencimiento de garantiaHasta, una vez por activo, garantía y umbral, en el buzón del activo fijo: GET /activos-fijos/alertas (las últimas 50, con id, activoId, tipo: "garantia_por_vencer", titulo, descripcion, datos y creadaEn). Sin correo.
  • Depreciación acelerada. Con metodo: "acelerada" la vida útil efectiva es un tercio de la normal en años enteros (Res. Ex. SII N°43/2002: 8 años → 24 meses). Una vida normal inferior a 36 meses responde 422 ACTIVO_FIJO_INVALIDO con detalles[], igual que una cuenta de tipo incorrecto o un valorResidual menor a $1 (al término, el bien queda registrado por un peso: Circular SII N°6/2003). Todos los errores vuelven juntos. Un activo acelerado que ya tenía cuotas con la regla anterior la conserva hasta terminar.
  • Catálogo. GET /activos-fijos/catalogo devuelve las reglas como dato: las categorías de la tabla de vida útil del SII (fila oficial, vidas en años y meses, cuenta propuesta, avisos), situaciones, motivos de baja, topes, los bienes que no se deprecian (terrenos) y las cuentas por defecto. Si el servidor no tiene la tabla, responde 503 TABLA_VIDA_UTIL_NO_DISPONIBLE, igual que crear, editar o filtrar con categoria y depreciar un período con activos con categoría; el resto de la API sigue.
  • Alta posterior. POST /activos-fijos/:id/alta (solo JWT, admin) registra el asiento de alta de un activo que no lo tiene, con { cuentaContrapartidaCodigo, fecha? }; responde 201 { activo, asiento }. Con el alta vigente, una compra vinculada, cuotas o dado de baja: 409.
  • Depreciar. POST /activos-fijos/depreciar devuelve además omitidos[] (id, nombre, motivo): los activos que no entraron y por qué. Si ninguno tiene cuota pendiente, responde 400 SIN_CUOTAS_PENDIENTES sin crear el asiento, con los omitidos[]. Cada activo de la respuesta trae una nota cuando su vida útil ya se había cumplido con saldo pendiente: esa cuota lo cierra completo.
  • Anular. Anular el asiento de una depreciación devuelve a cada activo su cuota y sus meses, y después se puede volver a depreciar el período.
  • Asientos. La baja sale con origen: "baja_activo_fijo" (el filtro origen de GET /asientos lo acepta) y cada asiento de activo fijo trae activosFijos[] (activoId, nombre, monto, meses).
json
{
  "error": "No hay activos con cuotas pendientes de depreciar en el período 2026-09 (1 omitido(s): ver omitidos)",
  "code": "SIN_CUOTAS_PENDIENTES",
  "omitidos": [
    {
      "id": "66f0a1b2c3d4e5f607182940",
      "nombre": "Notebook",
      "motivo": "ya tiene contabilizada la cuota de 2026-09"
    }
  ]
}

Ventas a crédito en la centralización. Con el módulo de ventas y cobranza encendido al centralizar, el asiento de ventas propias (los documentos que emites por esta API) separa la contrapartida según las cuentas por cobrar:

  • Va a Clientes (por defecto la cuenta 1.1.02.001; la cambia la regla de centralización de ventas) el dueño de una cuenta por cobrar: una factura 33 o 34 a crédito, o una nota de débito 56 con cuenta propia. Una línea por cliente, con su RUT en rutContraparte.
  • Una nota 61 o 56 que corrige una cuenta sigue a su dueño: va a Clientes si el dueño está en Clientes (es del mismo mes, o su mes se centralizó con la división, desde el RCV o todavía no se centraliza) y a Caja si el dueño entró por Caja (su mes se centralizó con el módulo apagado). Así, la nota de crédito de octubre sobre una factura de agosto centralizada antes de encender el módulo resta de Caja, igual que la factura sumó ahí.
  • Va a Caja (por defecto 1.1.01.001), como siempre, todo lo demás: boletas, guías, ventas al contado y las notas sobre una venta al contado.
  • Cada documento entra con su total (las notas de crédito restan), así que Caja más Clientes es el total del asiento. Una línea puede quedar al haber: un mes en que las notas de crédito a un cliente superan lo que se le vendió.
  • El mayor de Clientes sigue a los documentos y el auxiliar (la cuenta por cobrar) a sus reglas. Calzan, salvo cuando las notas de un documento suman más que él: una 61 con codRef 1 que anula por su total una factura ya rebajada por otra 61 deja la cuenta en 0, y el mayor muestra el exceso como saldo a favor del cliente.
  • Ese asiento lleva metadatos.ventasConClientes: true (en GET /asientos) y la glosa «Centralización de ventas AAAA-MM (POS, crédito a Clientes)». El resumen de la respuesta suma ventasConClientes: true, caja (lo que fue a Caja) y clientes (lo que fue a Clientes, con signo); caja + clientes es el total.
  • 409 CARGA_CUENTAS_PENDIENTE: la carga inicial de las cuentas por cobrar (al encender el módulo) todavía no termina. No se crea el asiento: sin esas cuentas, una venta a crédito quedaría en Caja. Reintenta en unos minutos; si no avanza, apagar el módulo deja centralizar como antes.
  • 409 CUENTAS_SIN_PROYECTAR: hay facturas a crédito (o notas de débito sin referencia) del mes cuya cuenta por cobrar todavía no se calcula. La respuesta trae documentos[] (tipoDte, folio, hasta 50) y total. Basta esperar la revisión periódica de las cuentas por cobrar (cada 10 minutos) y reintentar; si persiste, apaga Ventas y cobranza para centralizar como antes y avisa a soporte. Así, un asiento con la división nunca deja una factura a crédito en Caja.

Con el módulo apagado, y siempre con la fuente RCV del SII, el asiento es el de siempre: las mismas líneas, montos y textos, sin metadatos ni campos nuevos en el resumen; los demás errores de la centralización siguen siendo 400 con su texto.

El cobro de una venta a crédito (los pagos recibidos, cuando existan) abona según cómo se centralizó el mes de emisión del documento (en hora de Chile): si se centralizó con la división, desde el RCV o todavía no se centraliza, abona Clientes; si se centralizó sin la división (con el módulo apagado, la venta ya entró a Caja), es un traspaso de Caja a Banco. Es la misma regla con que las notas siguen a su dueño. Un asiento anulado no cuenta.

Compras por proveedor en la centralización. Con el módulo de compras y cuentas por pagar encendido al centralizar, el asiento de compras (los documentos del RCV de compras en REGISTRO del período) divide la línea de Proveedores (por defecto 2.1.01.001; la cambia la regla de centralización de compras):

  • Una línea de Proveedores por RUT del proveedor, con el RUT en rutContraparte (el mismo de su cuenta por pagar y de las líneas de sus pagos). Cada documento entra con su total y las notas de crédito 61 restan, así que las líneas suman el total de siempre. Una línea queda al debe si en el mes las notas de crédito de ese proveedor superan lo que se le compró.
  • El gasto, el IVA crédito fiscal, la glosa («Centralización de compras AAAA-MM»), el tipo y la fecha no cambian. El asiento lleva metadatos.comprasPorProveedor: true (en GET /asientos) y el resumen suma comprasPorProveedor: true y proveedores (cuántas líneas por RUT). Lo que no está en REGISTRO sigue fuera, como siempre.
  • 409 PAGOS_A_DOCUMENTOS_SIN_REGISTRO: el período tiene pagos a proveedores vigentes (con asiento) o compensaciones vigentes sobre documentos del mes que no están en REGISTRO (y tampoco lo están en otro período). La centralización no los incluye, y esos movimientos dejarían descuadrada la cuenta Proveedores. No se crea el asiento. La respuesta trae documentos[] (rutEmisor, tipoDte, folio, estadoSii, hasta 50), totalDocumentos, pagos[] y compensaciones[] (sus ids, hasta 50), totalPagos y totalCompensaciones. Anula esos pagos o compensaciones (y regístralos de nuevo si corresponde), o espera a que el documento quede en REGISTRO, y vuelve a centralizar. También responde cuando una 46 emitida en el período tiene pagos o compensaciones y todavía no aparece en REGISTRO en el RCV de compras de ningún período: ese documento viene en documentos[] con estadoSii: null y sinRegistroEnRcv: true. Sincroniza primero el RCV de compras y vuelve a centralizar.
  • Así, por RUT, el haber de Proveedores del mes menos los pagos a sus documentos es el saldo de sus cuentas por pagar (saldo − saldoAFavor). Una compensación no tiene asiento y no lo cambia dentro del mismo mes; entre una 61 y una factura de meses distintos, cada mes queda corrido en ese monto (la suma de los dos cuadra).
  • La factura de compra 46 que emites entra por su fila del RCV: el SII la registra en tu registro de compras (en REGISTRO, con el RUT del vendedor como proveedor y el mismo total). Va en la línea del vendedor, el mismo RUT de su cuenta por pagar (que sale de la 46 emitida, sin duplicarse), así que su pago cuadra. Una nota de crédito o débito que emitiste sobre tu propia 46 y que aparece en el RCV tampoco crea una cuenta por pagar propia: ya ajusta la de la 46.
  • IVA retenido de la 46 (con el módulo encendido o apagado). Cuando el RCV trae una 46 con retención, el asiento lleva el gasto por el neto (más el exento), el IVA crédito al debe, Proveedores por el total del RCV (lo que se le paga al vendedor) y una línea al haber «IVA retenido facturas de compra AAAA-MM». Esa línea va a la cuenta del rol opcional iva_retenido de la regla centralizacion_compras y, si no está configurado, a la retenciones de la regla centralizacion_honorarios (2.1.02.003 en la plantilla). La retención de cada documento nunca supera su IVA (recuperable más no recuperable). resumen.ivaRetenido aparece solo cuando hay retención; sin ella el asiento no cambia. iva_retenido no tiene valor por defecto: se configura con PUT /reglas-centralizacion, y como el PUT reemplaza el mapa completo de cuentas de la regla, hay que reenviar las demás cuentas propias. Un período centralizado antes de este cambio queda con el asiento anterior hasta que lo anules y lo vuelvas a centralizar.
  • Al encender el módulo con períodos ya centralizados: un período centralizado con el módulo apagado tiene una sola línea de Proveedores, sin RUT, y los pagos registrados después debitan Proveedores con el RUT de cada proveedor. El total de la cuenta cuadra, pero el saldo por RUT no. Al encender el módulo, anula el asiento de compras de cada período abierto y vuelve a centralizarlo: el nuevo sale con una línea por proveedor.

Con el módulo de compras apagado, el asiento de compras es el de siempre: una sola línea de Proveedores, sin metadatos ni campos nuevos en el resumen, y sin el 409.

Reportes: margen y flujo de caja

Dos reportes de solo lectura de la línea ERP, con contabilidad:leer: muestran costos y lo que se cobra y se paga. Con sesión los ven el admin y el contador; el emisor recibe 403 REPORTES_SIN_PERMISO. Los dos aceptan formato=json (por defecto), csv o xlsx: con un archivo, la misma ruta lo responde como adjunto, con la fila «Total» al final. Los parámetros inválidos responden 400 DATOS_INVALIDOS con todos los problemas en detalles[].

GET /api/empresas/:empresaId/reportes/margen?desde&hasta&agrupar=producto|vendedor|canal|sucursal&sucursalId: venta neta, costo, margen y % de margen, en un rango de fechas de emisión de hasta 12 meses (por defecto, el mes en curso por producto).

Por sucursal (agrupar=sucursal y el filtro sucursalId, el id de una sucursal de la empresa o matriz): la sucursal es la del documento, desde donde se emitió. Lo emitido sin sucursal cuenta en la casa matriz y una nota de crédito cuenta en la sucursal que la emitió. Cada fila trae sucursalId y esMatriz; la respuesta trae sucursal (null sin filtro). Un sucursalId que no es de la empresa responde 400 con detalles[].

  • Entran los documentos aceptados de producción, no demo y sin el folio anulado. Suman 33, 34, 39, 41, 56, 110 y 111; las notas de crédito 61 y 112 restan.
  • La venta es neta: montoNeto + montoExento (en una boleta, el neto; nunca el bruto), repartida entre sus líneas. El costo sale del kárdex del inventario (la operación confirmada del documento). Una nota de crédito que repuso stock resta su costo; una que no lo movió resta solo venta, en el producto de la línea que corrige.
  • Lo que no tiene costo conocido (sin inventario, con la operación sin confirmar o con costo cero) va en ventaSinCosto y no entra al margen: costo, margen y porcentajeMargen son null en un grupo sin ninguna línea con costo.
  • El vendedor es el de la cotización o nota de venta, el cajero del punto de venta o quien emitió desde el panel; lo emitido por una API key se agrupa por la key. El canal es el punto de venta, cada canal de venta, ventas, la API por proyecto, el panel o el sistema. Las notas toman el vendedor y el canal del documento que corrigen.

GET /api/empresas/:empresaId/reportes/flujo-caja?semanas=13 (de 1 a 52): cobros y pagos esperados por semana según el vencimiento de los saldos pendientes de las cuentas por cobrar y por pagar. La primera semana va de hoy al domingo y las demás, de lunes a domingo. Lo vencido y sin pagar va en vencido, aparte, y no entra al saldo acumulado; lo que vence después, en posteriores. El saldo parte de la suma de la cartola bancaria importada; sin cartola parte en 0 y lo dice en avisos.

Inventario

Requiere MiAplicación ERP

A una empresa sin ERP, sus rutas le responden 403 PLAN_SIN_ERP; una que lo tuvo conserva la lectura (GET) de sus datos. Ver MiAplicación API y ERP.

Bodegas, stock por bodega, kardex con costo promedio ponderado, lotes con vencimiento (FEFO), números de serie, variantes, packs, tomas de inventario ciegas, valorizado y alertas. Y el enganche con la emisión: emitir descuenta, una nota de crédito repone y un rechazo del SII revierte.

Opt-in por empresa

Con el módulo apagado (el estado de toda empresa hasta que un admin lo enciende) la emisión es idéntica a la de siempre: el mismo XML, el mismo 201, ningún campo nuevo. Si tu sistema lleva su propio stock, no tienes que hacer nada. Solo mueven stock los documentos de producción que no son demo: lo que emite una key mk_cert_ (siempre en certificación) nunca toca el inventario.

Viene en los planes de MiAplicación ERP, con un tope de bodegas activas: ERP Pyme 1, ERP Negocio 3, ERP Full 10 y ERP Corporativo sin tope (el campo bodegasInventario de GET /api/publico/planes; null = sin tope); los planes de la API traen 0. La bodega PRINCIPAL que crea el encendido cuenta como la primera. Habilita el plan ERP de la contratación vigente (pagada y sin vencer), el que asignó la plataforma a una empresa que nunca pagó o una cortesía vigente. Encender el módulo sin un plan ERP que lo habilite responde 403 PLAN_SIN_INVENTARIO; crear o reactivar una bodega con las activas en el tope, 409 TOPE_BODEGAS_PLAN (sin un plan ERP que lo habilite, el mismo 403). Los dos nombran el plan ERP que lo permite. Un módulo ya encendido no se bloquea si la contratación ERP vence: solo se frenan el encendido y las bodegas nuevas. Bajar a un plan de la API deja los datos del inventario en solo lectura.

json
{
  "error": "La empresa ya tiene 1 bodega activa y el plan ERP Pyme permite 1 bodega. Desactiva una que no uses o contrata el plan ERP Negocio (hasta 3 bodegas) o uno superior.",
  "code": "TOPE_BODEGAS_PLAN",
  "plan": {
    "clave": "erp_pyme",
    "nombre": "ERP Pyme"
  },
  "planSugerido": {
    "clave": "erp_negocio",
    "nombre": "ERP Negocio",
    "bodegasMax": 3
  },
  "bodegasMax": 1,
  "bodegasActivas": 1
}

Todas las rutas cuelgan de /api/empresas/:empresaId/inventario, responden id (nunca _id) y sus errores traen { error, code, detalles? }. Una empresa ajena responde 403 Solo puedes acceder al inventario de tu propia empresa.

Quién puede qué

AcciónUsuario del panelAPI key
Leer (todo lo GET)admin, emisor, contadorinventario:leer
Entradas y trasladosadmin, emisorinventario:escribir
Ajustes, mermas y consumossolo admininventario:escribir
Recetas de producción (crear, editar, activar o desactivar)solo admininventario:escribir
Crear una orden de producción (borrador)admin, emisorinventario:escribir
Confirmar y anular una orden de producciónsolo admininventario:escribir
Contar en una tomaadmin, emisorno (solo sesión)
Marcar leída una alertaadmin, emisor, contadorno (solo sesión)
Configurar el módulo, bodegas, ítems y variantes; anular una operación; abrir, confirmar, cancelar y anular tomas; carga masiva de stock por archivosolo adminno (solo sesión)

Con scope inventario:leer

RutaQué devuelveFiltros
GET /configuracionactivo, bloquearSinStock, bodegaPorDefectoId, diasAlertaVencimiento, asientoCostoVenta (valores por defecto con id null si nunca se configuró); además plan ({ clave, nombre } de la contratación vigente, o null), bodegasMax (null = sin tope, 0 = sin un plan ERP que lo habilite) y bodegasActivas—
GET /bodegasLas bodegas, la por defecto primero.incluirInactivas
GET /items/:itemId/variantesLas variantes del ítem.—
GET /stockSaldos por ítem, variante y bodega, con cantidad y costo promedio. 100 por página, a lo más 500. Con usoInterno=true, solo los insumos de uso interno; con false, solo los demás; sin él, todos.itemId, varianteId (null = sin variante), bodegaId, usoInterno (true o false; otro valor, 400 con detalles[]), limite, cursor
GET /kardexMovimientos con signo, del más nuevo al más viejo. 50 por página, a lo más 200.itemId, varianteId, bodegaId, desde, hasta, limite, cursor
GET /lotesLotes en orden FEFO.itemId, varianteId, bodegaId, conStock, porVencerDias
GET /seriesNúmeros de serie.itemId, bodegaId, estado
GET /valorizadoΣ cantidad × costo promedio; los negativos, aparte.agrupar (total, bodega, item), bodegaId, itemId, cursor, limite
GET /fotosEl valorizado guardado cada día a las 23:55.desde, hasta (AAAA-MM-DD), limite
GET /operacionesLas operaciones manuales.tipo, desde, hasta, limite, cursor
GET /operaciones/:operacionIdUna operación manual.—
GET /tomasLas tomas, sin líneas.bodegaId, estado, limite, cursor
GET /tomas/:tomaIdLa toma con sus líneas.—
GET /alertasLa bandeja de alertas de la empresa.soloNoLeidas, tipo, limite, cursor

Los cursores son opacos: manda el siguienteCursor de la respuesta anterior tal cual; null es la última página. Un id o un filtro inválido responde 400 con todos los errores juntos en detalles[].

json
{
  "saldos": [
    {
      "id": "6ac82f26ea5379cafdd35f68",
      "itemId": "6ac82f29b78f86effbcfa878",
      "varianteId": null,
      "bodegaId": "6ac82f29b78f86effbcfa87d",
      "cantidad": 4,
      "costoPromedio": 6200,
      "stockMinimo": null,
      "stockMinimoEfectivo": 5,
      "updatedAt": "2026-10-09T00:02:49.371Z"
    }
  ],
  "siguienteCursor": null
}

stockMinimo es el mínimo propio del saldo (null si no tiene); stockMinimoEfectivo, el que vigila el aviso de stock bajo: el propio o, sin él, el del ítem. Con el módulo de ventas encendido, cada saldo trae además comprometido (lo reservado por notas de venta vigentes) y disponible (cantidad − comprometido); apagado, esas dos claves no existen.

Con scope inventario:escribir

Cuatro operaciones que mueven stock sin un documento tributario. Cada una tiene folio interno propio, se aplica entera o no se aplica y queda en el kardex con quién la hizo (con una API key, usuarioId: null). Con el módulo apagado: 409 INVENTARIO_INACTIVO.

RutaCuerpoNotas
POST /entradas{ bodegaId, motivo, lineas: [{ itemId, varianteId?, cantidad, costoUnitario, lotes?, series? }], nota? }motivo: compra, carga_inicial o devolucion. Recalcula el costo promedio.
POST /traslados{ bodegaOrigenId, bodegaDestinoId, lineas: [{ itemId, varianteId?, cantidad, lotes?, series? }], nota? }Inmediato, con el costo, los lotes y las series de origen. Respeta bloquearSinStock.
POST /ajustes{ bodegaId, lineas: [{ itemId, varianteId?, cantidadContada, lote?, costoUnitario? }], nota? }Fija lo contado; el kardex guarda la diferencia. Un ítem por serie no se ajusta.
POST /mermas{ bodegaId, motivo?, lineas: [{ itemId, varianteId?, cantidad, lotes?, series? }], nota? }motivo es texto libre; en el kardex el motivo es merma. Respeta bloquearSinStock.
POST /consumos{ bodegaId, motivo?, lineas: [{ itemId, varianteId?, cantidad, lotes?, series? }], nota? }El uso interno de un insumo. Como la merma: sale al costo promedio, la serie queda baja y respeta bloquearSinStock; no entra al costo de venta (va a gasto_insumos, 5.2.02.009). Un ítem con inventario.usoInterno no se vende en ninguna superficie de venta (ITEM_USO_INTERNO) y GET /items?paraVenta=1 lo deja fuera.

Solo se leen los campos de esta tabla, a toda profundidad: usuarioId, claveIdempotencia, reposicionExacta, un motivo dentro de una línea o cualquier clave con punto o con $ se descartan, y los motivos internos (reversa, toma_inventario) no se pueden pedir.

Insumos de uso interno

Con el inventario encendido, la emisión también rechaza una línea sin itemId cuyo CdgItem es el código de un insumo; con el inventario apagado solo se revisan las líneas con itemId. La reemisión con items de reemplazo los revisa igual (400 con detalles[], antes del folio); sin reemplazo no se vuelve a revisar el documento original. En el catálogo de un canal, un ítem que se marca como insumo desaparece de la sincronización incremental sin marca de baja, igual que uno desactivado. Un consumo registrado después de centralizar el costo de venta del período no entra a ese asiento, igual que una venta registrada después: queda fuera hasta que anules el asiento y lo vuelvas a centralizar. Con consumos, el resumen de esa centralización trae consumo.

Idempotency-Key

Una cabecera de 1 a 128 caracteres. La misma clave con el mismo cuerpo responde 200 con la operación original (repetida: true) y no mueve nada; con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO. Es por empresa: la comparten sus usuarios y sus API keys.

bash
curl -X POST https://api.miaplicacion.cl/api/empresas/$EMPRESA/inventario/entradas \
  -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: compra-oc-1042" \
  -d '{"bodegaId":"6ac82f29b78f86effbcfa87d","motivo":"compra","nota":"OC 1042",
       "lineas":[{"itemId":"6ac82f29b78f86effbcfa878","cantidad":12,"costoUnitario":6200}]}'
json
{
  "operacion": {
    "id": "6ac82f29b78f86effbcfa88e",
    "tipo": "entrada_manual",
    "folio": 1,
    "estado": "confirmada",
    "bodegaId": "6ac82f29b78f86effbcfa87d",
    "bodegaDestinoId": null,
    "motivo": "compra",
    "nota": "OC 1042",
    "movimientos": [
      {
        "paso": 0,
        "linea": 1,
        "tipo": "entrada",
        "motivo": "compra",
        "itemId": "6ac82f29b78f86effbcfa878",
        "varianteId": null,
        "bodegaId": "6ac82f29b78f86effbcfa87d",
        "cantidad": 12,
        "costoUnitario": 6200,
        "documentoId": null,
        "documentoRaizId": null,
        "packItemId": null,
        "packCantidad": null
      }
    ],
    "reversaOmitida": [],
    "usuarioId": "6ac82f28b78f86effbcfa76e",
    "creadaEn": "2026-10-09T00:02:49.292Z",
    "anuladaEn": null,
    "motivoAnulacion": null,
    "anuladaPor": null
  },
  "alertas": [],
  "repetida": false
}

alertas[] avisa lo que la operación provocó: CRUZO_MINIMO (el saldo quedó bajo el mínimo) y LOTES_VENCIDOS. Con bloquearSinStock, una merma o un traslado que no alcanza responde 409:

json
{
  "error": "Stock insuficiente: disponible 4, pedido 9.",
  "code": "STOCK_INSUFICIENTE",
  "detalles": [
    {
      "itemId": "6ac82f29b78f86effbcfa878",
      "varianteId": null,
      "bodegaId": "6ac82f29b78f86effbcfa87d",
      "disponible": 4,
      "pedido": 9
    }
  ]
}

Producción: recetas y órdenes de producción

Quién puede qué: el emisor puede crear órdenes en borrador (no mueven stock); crear, editar y activar o desactivar recetas, y confirmar y anular órdenes, es solo del admin (una API key necesita inventario:escribir).

Una receta (lista de materiales) dice de qué se hace un producto terminado: cuántas unidades rinde una tanda (rendimiento) y cuánto consume esa tanda de cada componente. Una orden de producción produce una cantidad con la receta: al confirmarla saca los componentes de una bodega y entra el terminado a otra, en una sola transacción.

  • Una receta por producto terminado (409 RECETA_DUPLICADA). El terminado no puede ser pack ni insumo de uso interno (422 RECETA_INVALIDA); un insumo de uso interno sí es componente.
  • Editar (PUT) crea una versión nueva; con version, 409 RECETA_MODIFICADA si otro la cambió antes. La orden guarda la foto de la versión con que se creó.
  • Consumo de cada componente: cantidad × producir / rendimiento × (1 + mermaEsperada/100), a 6 decimales. Crear la orden no mueve stock (borrador). Un componente por serie exige sus series; uno por lote sale por FEFO o de los lotes que indiques; un terminado por lote o por serie exige lotesTerminado o seriesTerminado (422 PRODUCCION_INVALIDA, todo junto).
  • Confirmar (solo admin) nunca deja stock negativo: 409 STOCK_INSUFICIENTE con un detalle por componente y nada escrito; no consume lotes vencidos. Kardex: produccion_consumo y produccion. Dos confirmaciones a la vez: una mueve el stock y la otra recibe 409 PRODUCCION_ESTADO_INVALIDO.
  • Costo del terminado: la suma de lo que el kardex valorizó al sacar cada componente (en pesos enteros), sin mano de obra; entra exactamente por esa suma (neutro al peso) y costoUnitario es esa suma / la cantidad, a 6 decimales. No es costo de venta: el valor pasa de los componentes al terminado dentro de Mercaderías.
  • Anular revierte lo que movió la orden (un borrador se anula sin mover nada): el terminado sale al costo con que entró y su promedio vuelve al de antes; si ya salió en parte, lo que queda absorbe la diferencia. No se bloquea por stock.
RutaCuerpo o queryQué hace
GET /recetasactiva, itemId, limite, cursor{ recetas, siguienteCursor }.
GET /recetas/:recetaIdversiones=true{ receta }; con versiones, el historial.
POST /recetas{ itemId, varianteId?, rendimiento, mermaEsperada?, componentes: [{ itemId, varianteId?, cantidad }], nota? }Crea la versión 1 (201).
PUT /recetas/:recetaId{ rendimiento, mermaEsperada?, componentes, nota?, version? }Crea la versión siguiente.
PATCH /recetas/:recetaId{ activa }Una desactivada no admite órdenes nuevas (409 RECETA_INACTIVA).
GET /produccionesestado, itemId, recetaId, limite, cursor{ producciones, siguienteCursor }.
GET /producciones/:produccionId{ produccion }.
POST /producciones{ recetaId, cantidad, bodegaComponentesId?, bodegaDestinoId?, componentes?: [{ itemId, varianteId?, lotes?, series? }], lotesTerminado?, seriesTerminado?, nota? }La orden en borrador (201). Sin bodegas, la por defecto.
POST /producciones/:produccionId/confirmar{ produccion, alertas }, con costoTotal, costoUnitario y el costo de cada componente.
POST /producciones/:produccionId/anular{ motivo? }{ produccion }.

Solo con sesión

PUT /configuracion ({ activo?, bloquearSinStock?, diasAlertaVencimiento?, bodegaPorDefectoId?, asientoCostoVenta?, confirmarComprasAMercaderias? }; encender un módulo apagado pasa por el plan, antes de escribir nada; asientoCostoVenta: true habilita el asiento del costo de venta: encenderlo exige confirmarComprasAMercaderias: true y deja la regla de compras de la empresa en Mercaderías. Dos efectos se resuelven a mano en la v1: el inventario que ya existe necesita un asiento de apertura manual con fecha del primer día del mes en que se enciende, por su valorizado al inicio de ese mes (debe Mercaderías, haber Compras del giro o Patrimonio), porque al venderse vuelve a ir a Costo de ventas y los asientos son mensuales; y las compras que no son mercadería (arriendo, luz, servicios) también caen en Mercaderías y hay que reclasificarlas. La respuesta que lo enciende trae avisos con los dos puntos y el valorizado. Un true con el asiento ya encendido no hace nada, y apagarlo no revierte la regla de compras), POST/PATCH /bodegas (crear o reactivar una bodega pasa por el tope del plan), PUT /items/:itemId (el bloque de inventario del ítem), las escrituras de variantes, POST /operaciones/:operacionId/anular (solo operaciones manuales: una toma se anula por su ruta y un documento, con una nota de crédito), abrir, contar, confirmar, cancelar y anular tomas, POST /carga-masiva/previsualizar y POST /carga-masiva/confirmar (ver abajo), y POST /alertas/:alertaId/leer. Una API key recibe 403 aunque tenga los dos scopes. En la cuenta demo compartida, PUT /configuracion y PATCH /bodegas/:bodegaId responden 403 CUENTA_DEMO_RESTRINGIDA.

Carga masiva de stock

Un CSV o XLSX (la hoja Stock o la primera) de hasta 1000 filas, en el campo multipart archivo (hasta 5 MB), solo admin con sesión. Cada fila fija la cantidad de un ítem o variante en una bodega (un ajuste con motivo carga_masiva). Si entre dos subidas del mismo archivo no se movió nada, la segunda no cambia nada; si hubo ventas u otros movimientos entremedio, fija la cantidad de nuevo: pisa lo movido desde la subida anterior. Columnas: codigo (SKU o EAN del ítem o de la variante), bodega (su código) y cantidad (≥ 0, 6 decimales, coma decimal), obligatorias; costoUnitario (el de la diferencia positiva), lote y vencimiento (AAAA-MM-DD, obligatorios en un ítem por lote) y stockMinimo, opcionales. El stockMinimo es uno por saldo (las filas de los lotes de un ítem en la misma bodega llevan el mismo), y subirlo por encima de un saldo que no cambia no alerta, porque no es un cruce: el aviso sale con el próximo movimiento que deje el saldo bajo el mínimo. La carga no crea ítems: un código inexistente, un ítem sin control de stock, uno por número de serie, un pack, una bodega ajena, un lote sin vencimiento o con otro vencimiento, una cantidad inválida, dos filas del mismo saldo y dos mínimos distintos para el mismo saldo son errores de la fila, todos juntos.

POST /carga-masiva/previsualizar valida todo sin escribir y devuelve resumen y una entrada por fila (estado, errores[], saldoActual, diferencia). POST /carga-masiva/confirmar vuelve a validar: con una fila con error, 400 CARGA_INVALIDA sin aplicar nada (detalles[] por fila); si no, 201 con operacion, resumen, filas (saldoAntes, saldoDespues, diferencia), omitidas y alertas. Acepta Idempotency-Key: la misma clave con el mismo archivo responde 200 (repetida, o reanudada si se había cortado: sigue donde quedó); con otro archivo, 409 IDEMPOTENCIA_CONFLICTO. Otros códigos: CARGA_ARCHIVO_INVALIDO (400, el archivo entero), INVENTARIO_INACTIVO (409), CARGA_EN_CONFLICTO (503: repetirla con la misma Idempotency-Key y el mismo archivo sigue donde quedó) y 413 sobre 5 MB. La vista previa tiene el mismo tope por minuto que la de la emisión masiva (SII_MAX_PREVISUALIZACIONES_POR_MINUTO, 20 por defecto; 429 al pasarlo).

Tomas de inventario

La toma es ciega: al confirmar, cada línea aplica cantidadContada − stockSistemaAlContar sobre el saldo actual, así que una venta hecha mientras se contaba no se pierde. verStockSistema decide si la respuesta trae los números del sistema (stockSistemaAlAbrir, stockSistemaAlContar, diferencia): sí para un admin, un superadmin o un contador; no para el emisor (el que cuenta) ni para una API key. Códigos: TOMA_NO_ENCONTRADA (404), TOMA_YA_ABIERTA, TOMA_NO_ABIERTA, TOMA_CANCELADA, TOMA_CONFIRMANDO, TOMA_CONFIRMADA, TOMA_NO_CONFIRMADA (409), TOMA_SIN_LINEAS, TOMA_DEMASIADO_GRANDE (400) y TOMA_EN_CONFLICTO (503: repetir la confirmación sigue donde quedó).

Mientras la toma ciega está en curso

Con una toma ciega abierta o confirmando en una bodega, un usuario del panel con rol emisor recibe enmascaradas las cantidades de esa bodega: en GET /stock y GET /lotes sus filas salen con cantidad: null y enTomaCiega: true; en GET /kardex, con cantidad, saldoAntes, saldoDespues, costoPromedioResultante y costoTotal en null; GET /valorizado y GET /fotos la dejan fuera y lo dicen en bodegasExcluidas; en GET /operaciones (y su detalle) sus movimientos salen con cantidad: null; sus alertas (en GET /alertas y al marcarlas leídas) salen sin título, descripción ni cantidad; sus propias entradas y traslados no devuelven los saldos de esa bodega; y en la emisión (POST /dte, anular y reemitir) el bloque inventario.alertas va sin saldos, el 409 STOCK_INSUFICIENTE sin disponible ni números en el mensaje, y los textos de falta de stock del 400 (y del lote) dicen «disponible oculto». El vencido del 409 no se enmascara (residual aceptado). Si no se pueden revisar las tomas en curso, la emisión enmascara todo y una lectura del inventario responde 500 sin datos. Las demás bodegas se ven como siempre. No se enmascara a una API key ni a un admin, un superadmin o un contador, ni GET /series (un ítem por serie no entra en las tomas). Confirmada o cancelada la toma, el emisor vuelve a ver.

Alertas y webhooks

Tipos de alerta: stock_bajo, lote_por_vencer, lote_vencido, operacion_revisar (una venta quedó reservada sin documento local; datos.motivo dice por qué, por ejemplo folio_tomado_sin_registro), guia_revertida, factura_revertida y toma_atascada. Tres salen además por webhook:

Eventodatos
inventario.stock_bajo{ itemId, varianteId, bodegaId, codigo, nombre, cantidad, stockMinimo }
inventario.lote_por_vencer{ loteId, numero, itemId, varianteId, bodegaId, codigo, nombre, fechaVencimiento, diasParaVencer, cantidad }
inventario.lote_vencidoLa misma forma.

Inventario en la emisión

Una empresa sin MiAplicación ERP emite como con el módulo apagado aunque lo haya dejado encendido (ver La compuerta del ERP).

DocumentoQué mueve
33, 34, 39, 41, 110Salida.
33/34 sobre una guía 52 propia que ya movióNada.
52 con indTraslado 1 o 2Salida (venta); sobre una factura propia que ya descontó, nada, salvo inventario.mueveStock: true.
52 con indTraslado 3, 4, 6 o 7Salida (traslado).
52 con indTraslado 5Traslado interno a inventario.bodegaDestinoId (obligatoria).
46Entrada, al costo neto de la línea.
61/112 con CodRef 1Repone exactamente lo que movió el anulado; inventario.repone: false lo apaga.
61 con CodRef 2Nada.
61 con CodRef 3Repone solo con inventario.devolucion: true.
56/111Nada, salvo la 56 que anula una 61: revierte lo que esa 61 repuso.
  • Cada línea se vincula por items[].itemId (y varianteId) o por su código (items[].codigos[].valor). La que no se vincula no mueve nada y sale en inventario.sinVincular[] (SERVICIO, NO_CONTROLA_STOCK, SIN_CODIGO, CODIGO_DESCONOCIDO, CODIGO_AMBIGUO).
  • Los errores de inventario (y la falta de stock, con bloquearSinStock) se suman al 400 del payload, antes del folio. Sin bloquearSinStock se emite igual y el saldo queda negativo, con una alerta.
  • Después se reserva el stock y recién ahí se pide el folio: una carrera perdida es 409 STOCK_INSUFICIENTE (detalles[] de objetos) y una revalidación fallida, 400 INVENTARIO_INVALIDO. Sin folio en los dos.
  • El 201 de POST /dte y de POST /dte/:id/anular, y el 200 de la reemisión, suman inventario: { operacionId, sinVincular[], avisos[], alertas[] } cuando el documento pasó por el inventario.
  • Un rechazo del SII devuelve el stock solo. La reemisión revierte primero lo del original; si no puede, 503 INVENTARIO_NO_REVERTIDO antes del folio.
  • POST /dte, el lote y la emisión masiva leen siempre la configuración de emisión antes de validar: si la base no responde, 503 CONFIG_EMISION_NO_DISPONIBLE, también con un payload inválido.
json
{
  "inventario": {
    "operacionId": "6ac82f29b78f86effbcfa88e",
    "sinVincular": [{ "indice": 1, "nombre": "Despacho", "motivo": "SERVICIO" }],
    "avisos": [],
    "alertas": [
      {
        "code": "CRUZO_MINIMO",
        "itemId": "6ac82f29b78f86effbcfa878",
        "varianteId": null,
        "bodegaId": "6ac82f29b78f86effbcfa87d",
        "saldoAntes": 12,
        "saldoDespues": 4,
        "stockMinimo": 5
      }
    ]
  }
}

Errores del inventario

codeHTTPQué significa
DATOS_INVALIDOS400La forma del pedido; detalles[] trae todo junto.
INVENTARIO_INACTIVO409El módulo está apagado en la empresa.
INVENTARIO_INVALIDO400La revalidación del inventario de un documento falló en la reserva (sin folio).
INVENTARIO_NO_REVERTIDO503La reemisión no pudo revertir lo del original (sin folio). Reintentable.
STOCK_INSUFICIENTE409Con bloquearSinStock, no alcanza: { itemId, varianteId, bodegaId, disponible, pedido, lote?, vencido? }.
IDEMPOTENCIA_CONFLICTO409La Idempotency-Key ya se usó con otro cuerpo.
OPERACION_NO_ENCONTRADA404No es una operación manual de la empresa.
BODEGA_*, CODIGO_BODEGA_EN_USO404 / 409Bodega inexistente, inactiva, con stock o por defecto.
SUCURSAL_INACTIVA422Crear una bodega en una sucursal inactiva (detalles[]). Una sucursal que no existe sigue siendo 400 SUCURSAL_NO_ENCONTRADA.
ITEM_*, VARIANTE_*, PACK_*400 / 404 / 409Reglas del catálogo: no existe, inactivo, no controla stock, es un pack, variante obligatoria o en uso.
CODIGO_EN_USO409El SKU o el código de barras ya es de otro ítem o variante.
LOTE_*, LOTES_REQUERIDOS400 / 404 / 409El ítem se sigue por lote: falta, no existe o tiene otro vencimiento.
SERIE_*, SERIES_REQUERIDAS400 / 409El ítem se sigue por serie: falta, está repetida o no está disponible.
TOMA_*400 / 404 / 409 / 503Ver Tomas de inventario.
CONFIRMACION_REQUERIDA409Encender asientoCostoVenta sin confirmarComprasAMercaderias: true en PUT /configuracion. No se escribió nada; el mensaje explica los dos efectos contables que se resuelven a mano.
PLAN_SIN_ERP403La empresa no tiene MiAplicación ERP. Con soloLectura: true, los GET siguen respondiendo.
PLAN_SIN_INVENTARIO403Sin un plan ERP que lo habilite (contratación vigente, plan asignado o cortesía): no se enciende el módulo ni se crean o reactivan bodegas; lo ya encendido sigue funcionando. Trae requiere: erp, plan y planSugerido { clave, nombre, bodegasMax }, el ERP de entrada. No se escribió nada.
TOPE_BODEGAS_PLAN409Crear o reactivar una bodega con las activas en el tope del plan. Trae plan, bodegasMax, bodegasActivas y planSugerido (el plan ERP más barato que permite más, o null). No se escribió nada.

Ventas y cobranza

Requiere MiAplicación ERP

A una empresa sin ERP, sus rutas le responden 403 PLAN_SIN_ERP; una que lo tuvo conserva la lectura (GET) de sus datos. Ver MiAplicación API y ERP.

Cotizaciones, notas de venta, listas de precios y cuentas por cobrar sobre los documentos que ya emites. Se está construyendo por partes: hoy existen la configuración del módulo, sus scopes, las condiciones comerciales del contacto, las listas de precios por cliente y las cotizaciones y notas de venta, con su PDF y su conversión a DTE, las cuentas por cobrar, los pagos recibidos, los reportes de cobranza, los recordatorios de cobranza por correo y sus webhooks.

Opt-in por empresa

Con el módulo apagado (el estado de toda empresa hasta que un admin lo enciende) ninguna respuesta cambia: la emisión, el XML, el PDF y la centralización contable son los de siempre.

Viene en todos los planes de MiAplicación ERP, sin topes. Encender el módulo exige un plan ERP que lo habilite (la contratación vigente, pagada y sin vencer, el plan asignado por la plataforma a una empresa que nunca pagó o una cortesía vigente); sin él responde 403 PLAN_SIN_VENTAS sin escribir nada, con el ERP de entrada en planSugerido. Un módulo ya encendido no se bloquea si la contratación ERP vence: solo se frena volver a encenderlo después de apagarlo. Bajar a un plan de la API deja sus datos en solo lectura.

json
{
  "error": "La empresa no tiene una contratación vigente, así que no puede encender ventas y cobranza: MiAplicación ERP incluye ventas y cobranza, desde el plan ERP Pyme.",
  "code": "PLAN_SIN_VENTAS",
  "requiere": "erp",
  "plan": null,
  "planSugerido": {
    "clave": "erp_pyme",
    "nombre": "ERP Pyme"
  }
}

Configuración del módulo

GET /api/empresas/:empresaId/ventas/configuracion (ventas:leer, cualquier rol de la empresa):

json
{
  "configuracion": {
    "id": "6705f2c1a1b2c3d4e5f60718",
    "activo": true,
    "validezCotizacionDias": 15,
    "diasReservaNotaVenta": 7,
    "plazoPagoDefectoDias": 30,
    "bloquearPorComprometido": false,
    "bloquearEmisionPorComprometido": false,
    "recordatorios": {
      "activo": false,
      "diasAntes": [3],
      "diasDespues": [1, 7, 15, 30],
      "copiaA": null
    }
  },
  "plan": { "clave": "negocio", "nombre": "Negocio" },
  "puedeActivar": true
}
CampoQué es
idnull si la empresa nunca guardó su configuración (son los valores por defecto).
validezCotizacionDiasDías que una cotización queda vigente. Entero de 1 a 365; por defecto 15.
diasReservaNotaVentaDías que una nota de venta reserva stock. Entero de 0 a 365 (0 = no reserva); por defecto 7.
plazoPagoDefectoDiasPlazo de pago cuando el cliente no tiene el suyo. Entero de 0 a 365 (0 = contado); por defecto 30.
bloquearPorComprometidoAl confirmar una nota de venta con reserva, exigir que el stock menos lo comprometido por las demás notas alcance (si no, 409 STOCK_INSUFICIENTE_NOTA). No toca la emisión de DTE. Por defecto false.
bloquearEmisionPorComprometidoAl emitir un DTE que vende (33, 34, 39, 41, 110 y la guía 52 de venta), exigir que el stock de la bodega menos lo comprometido por notas de venta confirmadas alcance, sin contar la nota que se convierte (si no, 409 STOCK_COMPROMETIDO sin folio). Solo con el inventario operando. Independiente de la anterior. Por defecto false.
recordatoriosLos recordatorios de cobranza por correo: activo (por defecto false), diasAntes (días antes del vencimiento, 0 = el mismo día; hasta 5 enteros distintos de 0 a 60; por defecto [3]), diasDespues (días después; hasta 10 enteros distintos de 1 a 365; por defecto [1, 7, 15, 30]) y copiaA (un correo con copia oculta, o null). Los días vuelven ordenados.
plan{ clave, nombre } del plan que habilita (contratación vigente, plan asignado o cortesía), o null sin uno.
puedeActivarSi la barrera del plan dejaría encender el módulo a quien pregunta. No dice nada del rol: encender es de admin.

PUT /configuracion es solo con sesión y solo de admin. Acepta estos 7 campos, todos opcionales (manda al menos uno): activo, validezCotizacionDias, diasReservaNotaVenta, plazoPagoDefectoDias, bloquearPorComprometido, bloquearEmisionPorComprometido y recordatorios (cada campo de este bloque es opcional y el que no mandas conserva lo guardado); cualquier otra clave se ignora. Valida todo antes de escribir y responde 400 DATOS_INVALIDOS con todos los errores juntos en detalles[]. Encender un módulo apagado carga además, en segundo plano, las cuentas por cobrar de lo que el SII ya había aceptado; la respuesta no la espera.

Condiciones comerciales del contacto

El contacto (/api/empresas/:empresaId/contactos, solo con sesión) acepta un bloque opcional comercial:

json
{
  "comercial": {
    "plazoDias": 30,
    "limiteCredito": 2000000,
    "bloqueado": false,
    "listaPrecioId": "6705f2c1a1b2c3d4e5f60801"
  }
}
  • plazoDias: entero de 0 a 365, o null. limiteCredito: pesos, entero mayor o igual a 0, o null (sin límite). bloqueado: true o false. listaPrecioId: la lista de precios del cliente, o null; tiene que ser una lista activa de la misma empresa y el contacto tiene que ser cliente.
  • Sin el bloque, el contacto es exactamente el de siempre: la respuesta no trae la clave comercial. Con el bloque, trae siempre sus cuatro campos.
  • Se acepta aunque el módulo esté apagado, como cualquier otro campo del contacto: guardarlo no enciende nada.
  • Solo un admin lo escribe, con el módulo encendido o apagado. Cualquier otro rol que lo mande (también como comercial.limiteCredito) recibe 403 COMERCIAL_SOLO_ADMIN sin que se escriba nada; sin comercial en el cuerpo, todo sigue igual.
  • El bloque se reemplaza completo. comercial: null, o un bloque sin plazo, sin límite, sin bloqueo y sin lista, quita las condiciones. Datos inválidos: 400 COMERCIAL_INVALIDO con detalles[].
  • Un contacto que deja de ser cliente (un PUT que le deja roles sin cliente) pierde su lista de precios; si el bloque queda vacío, se quita entero.

Listas de precios

Una lista le cambia el precio a los clientes que la tienen asignada. Hay dos tipos, y los dos trabajan en NETO, igual que el precio del ítem:

  • porcentaje: un ajuste sobre el precio base, entre −99 y 300, con a lo más 2 decimales (-10 es un 10 % de descuento). Se redondea a pesos enteros, la mitad hacia arriba (22,5 da 23).
  • fija: un precio neto fijo (entero, sin decimales) por ítem o por variante. El del ítem completo vale también para sus variantes que no tienen uno propio en la lista.

El precio base es el de la variante si tiene uno propio; si no, el del ítem. Lo que la lista no trae sale al precio base. Las lecturas van con ventas:leer y cualquier rol; las escrituras, con ventas:escribir y solo admin. Con el módulo apagado responden 409 VENTAS_INACTIVO.

MétodoRutaQué hace
GET/listas-precio?incluirInactivas=1Las listas, activas primero y por nombre, con cuántos precios tienen y a cuántos clientes están asignadas.
POST/listas-precio{ nombre, tipo, porcentaje? } → 201. Dos listas activas no se llaman igual (409 LISTA_DUPLICADA).
GET/listas-precio/:listaIdUna lista.
PATCH/listas-precio/:listaId{ nombre?, porcentaje?, activo?, desasignar? }. El tipo no cambia.
GET/listas-precio/:listaId/preciosLos precios de una lista fija, por nombre del ítem (q, pagina, limite).
PUT/listas-precio/:listaId/precios{ precios: [{ itemId, varianteId?, precio }] }, hasta 200, todos o ninguno.
DELETE/listas-precio/:listaId/precios/:precioIdQuita un precio de la lista.
GET/precio?itemId=&varianteId=&contactoId=El precio neto de un ítem para un cliente.

Una lista no se borra: se desactiva. Si está asignada a clientes, desactivarla responde 409 LISTA_ASIGNADA con asignados; con desasignar: true se desactiva y se les quita a esos clientes en la misma operación (quedan con el precio base). Un ítem, una variante, un contacto o una lista de otra empresa responden 404, igual que uno que no existe.

json
GET /api/empresas/:empresaId/ventas/precio?itemId=…&contactoId=…

{ "precioNeto": 9000, "base": 10000, "origen": "lista", "listaId": "6705f2c1a1b2c3d4e5f60801" }

origen es lista si la lista del cliente puso el precio; si no, dice de dónde salió la base, variante o item, y listaId es null. El precio es neto: en una boleta, la conversión a bruto es tuya.

La lista de precios en la emisión

Con el módulo encendido y la empresa con ERP, POST /dte completa el precio de una línea con itemId (y varianteId) que viene sin la clave precio, antes de validar y de pedir el folio. El cliente es el contacto activo de tu empresa con el RUT de cliente.rut (uno de otra empresa con el mismo RUT no cuenta) y su lista activa pone el precio neto, el mismo de GET .../ventas/precio. En la boleta 39 una línea afecta pasa a bruto (round(neto × 1,19), el mismo redondeo de la conversión de una nota de venta); una línea con exento: true y toda la 41 quedan netas; el resto, neto.

  • Sin lista aplicable (el receptor no está en tu agenda o está desactivado, no tiene lista, su lista está desactivada o es fija y no trae ese ítem), el 400 de siempre más un detalle que lo dice. A diferencia de una cotización, el precio base del ítem no se usa solo: hoy no existe una lista por defecto de la empresa.
  • La factura de compra 46 y la exportación 110/111/112 no toman listas.
  • Solo un documento que vende toma la lista: 33, 34, 39, 41 y la guía 52 con IndTraslado 1 o 2 (o sin él). En una nota 56 o 61 (corrige el documento original, que salió con su precio) o en una guía de traslado (IndTraslado 3 a 7), una línea sin precio recibe el 400 de siempre y no se consulta ninguna lista.
  • Un precio que mandas gana siempre, también 0. Con el módulo apagado (o sin ERP), POST /dte es exactamente el de antes, y una línea que ya trae precio no hace ninguna consulta nueva.
  • Si las listas no se pueden leer, 503 LISTAS_PRECIO_NO_DISPONIBLES, sin folio; si el payload trae además otros errores, el 400 de siempre con todos ellos.
  • El lote (POST /dte/lote) y la emisión masiva por archivo aplican la misma regla a cada documento, antes de validar y del folio: una línea con itemId y sin precio toma el de la lista del receptor. El precio queda guardado en el lote y no se vuelve a calcular al emitir, aunque la lista cambie entre medio. Si las listas no se pueden leer y lo único que falta es ese precio, responden 503 LISTAS_PRECIO_NO_DISPONIBLES sin crear nada; con otros errores, el 400 de siempre con todos.

Cotizaciones y notas de venta

Documentos comerciales, no tributarios: no tienen folio del SII, no se firman ni se envían, y ningún camino toca un folio, un CAF ni el SII, salvo la conversión a DTE, que emite por el camino de POST /dte. Cada uno tiene un numero correlativo por empresa y clase, sin saltos ni repetidos. Leer, con ventas:leer y cualquier rol; escribir, con ventas:escribir y rol emisor o admin (el contador solo lee). Con el módulo apagado, 409 VENTAS_INACTIVO.

MétodoRutaQué hace
GET/documentosListado sin líneas, más reciente primero: clase, estado (acepta vencida), contactoId, vendedorId, desde, hasta, pagina y limite (25, hasta 100).
POST/documentosCrea uno en borrador → 201. Con Idempotency-Key, un reintento devuelve el mismo (200, repetido: true).
GET/documentos/:documentoIdUno, completo (líneas e historial).
PATCH/documentos/:documentoIdEdita un borrador; con lineas las reemplaza todas y vuelve a buscar los precios.
POST/documentos/:documentoId/transiciones{ a, motivo?, reserva? }: cambia de estado; reserva, solo al confirmar una nota de venta.
POST/documentos/:documentoId/nota-ventaLa nota de venta de una cotización aceptada, idempotente.
POST/documentos/:documentoId/convertirUna nota de venta confirmada o una cotización aceptada → un DTE. Exige además dte:emitir.
POST/documentos/:documentoId/conversion/resolverSolo con sesión y solo admin: resuelve una conversión en revisar (liberar o ligar).
GET/documentos/:documentoId/pdfEl PDF comercial (carta), sin validez tributaria.
POST/documentos/:documentoId/enviar{ email?, mensaje? }: lo manda por correo con el PDF; la cotización lleva el enlace de aceptación.
GET/comprometidoitemId (obligatorio), varianteId, bodegaId: qué notas de venta comprometen stock de un ítem.
  • clase es cotizacion o nota_venta. El receptor se copia del contacto (contactoId); una cotización puede ir a un receptor escrito a mano, pero la nota de venta va siempre a un contacto. vendedorId es un usuario con acceso activo a la empresa (por defecto, quien crea con sesión; con una API key, ninguno). En el alta, null es lo mismo que no mandarlo: queda quien crea. Para dejar el documento sin vendedor, edítalo después con un PATCH y "vendedorId": null.
  • Una línea con itemId y sin precioNeto toma el precio del cliente (su lista); un precioNeto mandado es manual. Los precios van siempre netos, en pesos enteros. Hasta 60 líneas.
  • Los totales son los del DTE equivalente, peso a peso: la misma función de la emisión, con el descuento de línea, el descuento global antes del IVA y las líneas exentas. Una boleta (39/41) se calcula como factura; al convertirla, el paso a bruto puede mover algunos pesos, y por eso trae totalesReferenciales: true.
  • La línea guarda el exento pedido y trae aparte exentoEfectivo (en 34/41, todas): si un 34 vuelve a 33, sus líneas vuelven a ser afectas. Una guía (52) no admite descuentoGlobal (400), y un descuento global que deja en $0 la parte afecta o la exenta de un documento mixto también es 400: en los dos casos, el descuento va en cada línea.
  • Cotización: borrador → enviada → aceptada o rechazada, y anulada desde borrador o enviada. Se muestra vencida cuando pasa su fecha, y así no se envía ni se acepta (409 COTIZACION_VENCIDA). Nota de venta: borrador → confirmada (no con el cliente bloqueado: 409 CLIENTE_BLOQUEADO; ni sobre su límite de crédito: 409 LIMITE_CREDITO_EXCEDIDO), y anulada. Lo demás es 409 TRANSICION_INVALIDA; convertida solo la deja la conversión.
  • De dos cambios simultáneos pasa uno; el otro responde 409. Cotización → nota de venta deja la cotización convertida con referencia cruzada, y un segundo pedido devuelve la misma nota. Una cotización que ya se convirtió a un DTE que el SII rechazó responde 409 COTIZACION_CON_DTE: se reemite ese DTE o se vuelve a convertir, pero no pasa a nota. Sus líneas se revisan como en el alta: un ítem que después se desactivó o pasó a insumo de uso interno responde 409 ITEM_INACTIVO (o ITEM_USO_INTERNO) con todo en detalles[], sin crear la nota.
json
POST /api/empresas/:empresaId/ventas/documentos

{
  "clase": "cotizacion",
  "contactoId": "6705f2c1a1b2c3d4e5f60300",
  "lineas": [
    { "itemId": "6705f2c1a1b2c3d4e5f60100", "cantidad": 2 },
    { "nombre": "Instalación", "cantidad": 1, "precioNeto": 15000 }
  ],
  "descuentoGlobal": { "tipo": "monto", "valor": 1000 }
}

→ 201 { "documento": { "id": "…", "clase": "cotizacion", "numero": 42, "estado": "borrador",
        "totales": { "neto": 32000, "exento": 0, "iva": 6080, "total": 38080 }, … }, "repetido": false }

Stock comprometido por notas de venta

Solo con el inventario encendido. Es una reserva calculada: no mueve el stock ni el kardex. Lo comprometido de un ítem (o variante) en una bodega es la suma de lo que piden las notas de venta confirmada con reserva: true y reservaHasta igual o posterior a hoy (en Chile). Anularla, que pase su fecha o reclamar su conversión a DTE la deja de contar sola: desde ahí el stock lo descuenta el DTE (si el SII lo rechaza, vuelve a comprometer mientras su reserva siga vigente).

  • bodegaId (alta y PATCH, opcional) es de la empresa (una ajena, 404 BODEGA_NO_ENCONTRADA) y activa (409 BODEGA_INACTIVA); sin ella, al confirmar se usa la bodega por defecto del inventario.
  • Al confirmar, reserva es true por defecto si diasReservaNotaVenta es mayor que 0 (manda reserva: false para no reservar) y reservaHasta queda en hoy + esos días, congelado. Sin inventario, la nota se confirma con reserva: false y no se calcula nada (un reserva: truemandado con el inventario apagado se ignora).
  • reservaStock es lo que la nota compromete: un pack, sus componentes; los servicios y los ítems sin control de stock, nada; los lotes y las series, a nivel de ítem o variante. Un ítem con variantes sin varianteId no se puede reservar (400).
  • Con bloquearPorComprometido, confirmar exige que el stock menos lo comprometido por las demás notas alcance: si no, 409 STOCK_INSUFICIENTE_NOTA con todos los faltantes en detalles[] ({ itemId, varianteId, bodegaId, pedido, comprometido, disponible }). Dos confirmaciones simultáneas por el último stock no pasan las dos. No bloquea la emisión de un DTE.
  • Con bloquearEmisionPorComprometido, emitir un DTE que vende (por POST /dte o al convertir) exige que lo vendido por saldo no pase del stock de la bodega menos lo comprometido por notas confirmadas; la nota que se convierte no cuenta. Sin nada comprometido no bloquea (eso lo decide bloquearSinStock). Si no alcanza, 409 STOCK_COMPROMETIDO sin folio y con todos los faltantes en detalles[] ({ lineas, itemId, varianteId, bodegaId, pedido, stock, comprometido, disponible }); con otros errores del payload, el faltante va como texto en el mismo 400. NC, ND, guías de traslado y la 46 no se revisan. Es una revisión previa al folio, sin candado: dos emisiones simultáneas por lo último disponible pueden pasar.
  • GET /comprometido?itemId= dice qué notas comprometen un ítem: totales exactos por bodega y variante, y hasta 500 notas, las que vencen antes primero. En GET /inventario/stock, cada saldo trae comprometido y disponible; en una toma ciega, el emisor los recibe en null (en el 409, pedido queda: es lo que pide la misma nota; si no se puede saber qué bodegas están en toma ciega, se enmascaran todas). GET /inventario/stock lista saldos: lo comprometido de un ítem en una bodega donde no tiene saldo no aparece ahí; consúltalo con GET /comprometido.

Conversión a DTE

POST /documentos/:documentoId/convertir emite el DTE de una nota de venta confirmada o de una cotización aceptada (directo, sin pasar por nota). Exige ventas:escribir y dte:emitir, o un usuario emisor o admin (el contador no). Emite por el mismo camino de POST /dte: validación del payload y del inventario antes del folio (un error no consume folio y salen todos juntos en detalles[]), el ambiente pedido y su autorización, la key mk_cert_, el modo demo, la resolución por ambiente y las mismas respuestas de error. Cuenta en el mismo tope de emisiones por minuto de la empresa que POST /dte.

Una venta real no se convierte en un DTE de prueba

Con la empresa en producción (sin modo demo), una conversión que saldría en certificación (una key mk_cert_ o ambiente: certificacion) responde 409 CONVERSION_FUERA_DE_PRODUCCION sin tocar el documento ni pedir folio. Una empresa en certificación o en modo demo convierte en su ambiente.
Campo (opcional)Qué es
tipoDte33, 34, 39, 41 o 52. Por defecto, el tipoDteSugerido del documento.
formaPagoSolo 33/34. Por defecto, 2 (crédito) si el contacto tiene comercial.plazoDias mayor que 0, y 1 (contado) si no.
fechaVencimientoSolo 33/34. Con crédito y sin ella: emisión + plazoDias del contacto (o plazoPagoDefectoDias de la configuración).
fechaEmisionAAAA-MM-DD; por defecto, hoy.
ambiente, medioPago, sucursalIdComo en POST /dte.
indTraslado, transporteGuía 52 (Res. Ex. 144/2026): como en POST /dte, con sus mismas validaciones.
  • El receptor es el del documento y, lo que falte, el del contacto. Las líneas llevan su itemId y varianteId (el inventario las vincula) y su código como <CdgItem>. En 33/34 el descuento global va como descuentosRecargos; la 52 no lo admite. No lleva una referencia al documento comercial. Convertir a guía deja el documento convertido: la factura se emite después con POST /dte, con una referencia a la guía.
  • En boleta (39/41) cada precio neto de una línea afecta pasa a bruto (round(neto × 1,19), como la pantalla de emisión): el total puede diferir algunos pesos del documento, y la respuesta lo informa en redondeo sin fallar.
  • El 201 trae documento (con conversion), dte (el 201 de POST /dte, tal cual) y redondeo ({ totalDocumento, totalDte, diferencia }). Un error responde lo mismo que POST /dte, más documento.
  • El documento emitido guarda origenComercial ({ documentoVentaId, clase, numero }): no entra al XML ni al PDF y no aparece en GET /dte. La 46 emitida desde una orden de compra guarda { ordenCompraId, clase: "orden_compra", numero } (ver factura de compra desde la orden).
conversion.estadoQué pasóEl documento
emitiendoEn curso: otra conversión simultánea es 409 CONVERSION_EN_CURSO, y no se anula mientras tanto.Sigue en su estado; la nota ya no compromete stock.
emitidaEl DTE se emitió (emitidaId, folio).convertida.
inciertaEl envío quedó incierto (502 ENVIO_INCIERTO): nunca se reemite solo, consúltalo por folio.convertida; reconvertir es 409 DOCUMENTO_YA_CONVERTIDO.
errorNo hubo DTE (validación, folios, ambiente, stock); ultimoError dice por qué.Sigue convertible.
rechazadaEl SII rechazó el DTE después.Vuelve a confirmada (y a comprometer) o a aceptada, y se puede volver a convertir.
revisarLa conversión se cortó a medias sin registro local del DTE: el envío pudo salir. Nunca se libera sola; convertir, cambiar de estado o reemitir es 409 CONVERSION_EN_REVISION.Sigue en su estado; la nota no compromete stock.

Reemitir o volver a convertir, no las dos

Si el DTE rechazado se reemite, convertir el documento otra vez responde 409 CONVERSION_REEMITIDA: la venta saldría dos veces (también si entremedio un intento de conversión falló). Al revés, reemitir el DTE rechazado de un documento que ya se volvió a convertir (o se está convirtiendo) responde 409 CONVERSION_REEMPLAZADA sin tocar su folio. Pedidas exactamente a la vez, pueden pasar las dos: no las lances en paralelo.

Conversiones cortadas a medias. Cada 10 minutos una revisión periódica del servidor (sin hablar con el SII) mira las conversiones con más de 15 minutos en emitiendo. Si el DTE quedó registrado, la cierra según su estado (aceptado o en proceso, emitida; rechazado, rechazada; envío incierto, incierta). Si no, queda en revisar con una alerta a la plataforma; si la emisión estaba solo lenta y el DTE aparece después, se cierra sola. La resuelve un admin con sesión: POST /documentos/:documentoId/conversion/resolver { accion, emitidaId?, motivo }. Con liberar (el SII no tiene el DTE; solo una hora después de que empezó la conversión, si no 409 LIBERACION_PREMATURA con minutosRestantes) la conversión pasa a error y el documento vuelve a ser convertible y a comprometer stock, salvo que tenga un DTE registrado (409 CONVERSION_CON_DTE, con su emitidaId); con ligar se cierra con el DTE emitidaId, que tiene que ser de la misma empresa (si no, 404 DTE_NO_ENCONTRADO), emitido después de que empezó la conversión (409 DTE_ANTERIOR_A_LA_CONVERSION) y, con la empresa en producción, de producción y no demo (409 CONVERSION_FUERA_DE_PRODUCCION). Un documento en error con un DTE registrado de esa misma conversión no se vuelve a convertir (409 CONVERSION_CON_DTE, con su emitidaId): se liga con ligar, que desde error solo acepta ese DTE. motivo es obligatorio y queda en el historial; fuera de revisar responde 409 CONVERSION_NO_EN_REVISION, y un DTE que salió de otro documento o es de otro tipo, 409 DTE_DE_OTRO_DOCUMENTO o DTE_DE_OTRO_TIPO. La misma revisión devuelve a convertible lo que el SII rechazó por otra vía y recalcula las cuentas por cobrar de lo que cambió desde la pasada anterior.

PDF, envío por correo y aceptación pública

El PDF comercial (GET /documentos/:documentoId/pdf) no es la representación impresa de un DTE: no lleva timbre, ni PDF417, ni recuadro rojo, ni resolución, ni folio. Lleva el tipo y el número propios («COTIZACIÓN N° 15»), la leyenda «Documento sin validez tributaria» arriba y en el pie de cada hoja, el logo de la empresa, el cliente, el vendedor, las fechas, las líneas, los totales y las observaciones.

  • POST /documentos/:documentoId/enviar con { email?, mensaje? } manda el PDF adjunto al email pedido o, sin él, al correo del receptor (sin ninguno, 400). Una cotización en borrador pasa a enviada y una enviada se puede reenviar; una nota de venta no cambia de estado. Otro estado es 409 DOCUMENTO_NO_ENVIABLE. Techo de 10 correos por minuto por empresa.
  • Primero sale el correo y después se escriben, juntos, el estado, el enlace y el registro. Si el correo falla responde 503 CORREO_NO_ENVIADO y el estado no avanza. Cada envío queda en correos[] del documento, con su resultado.
  • El correo de una cotización trae el enlace https://app.miaplicacion.cl/cotizacion#t=<token>. El token va en el fragmento (el navegador no lo manda a ningún servidor), se guarda solo su sha256, vence con la cotización y cada envío lo reemplaza. La página lo manda a la API en el header X-Cotizacion-Token, nunca en la URL.
  • Sin sesión: GET /api/publico/cotizaciones (los datos que necesita el cliente), GET /api/publico/cotizaciones/pdf, y POST /api/publico/cotizaciones/aceptar o /rechazar con { nombre?, comentario? }. Repetir la misma respuesta es 200 con el estado actual; de una aceptación y un rechazo simultáneos pasa uno. Token que no sirve, 404 ENLACE_NO_VALIDO; vencido y todavía sin respuesta, 410 COTIZACION_VENCIDA (una ya cerrada se sigue viendo en solo lectura, 200); ya respondida de otra forma, anulada o convertida, 409 COTIZACION_CERRADA. El historial guarda el nombre, el comentario (con sus saltos de línea) y la IP de quien respondió; la IP solo la ven un admin o un superadmin con sesión, nunca una API key.
  • Aviso a la empresa: cuando el cliente acepta o rechaza, sale un correo al correo de la empresa y al del vendedor (si tiene uno), con el número, el cliente, el total, el nombre y el comentario de quien respondió (nunca su IP), además del webhook cotizacion.aceptada o cotizacion.rechazada con porElCliente: true. Sale una vez por respuesta: repetir la misma respuesta no vuelve a avisar, y si el correo no sale la respuesta igual queda registrada.

Cuentas por cobrar

Una cuenta por cobrar por cada documento que deja una deuda abierta. No la creas tú: se proyecta sola de los documentos que emites cuando el SII los acepta (solo con el módulo encendido), y se recalcula desde cero cada vez que el SII acepta una nota que la corrige.

Lo aceptado antes de encender el módulo, o mientras estuvo apagado, no queda afuera: al encenderlo, la API carga sola, en segundo plano, las cuentas de todo lo que el SII ya había aceptado, y pueden tardar unos segundos en aparecer. Si esa carga falla, queda el aviso en el registro del servidor y se repara con scripts/cxc-reconstruir.js --empresa <empresaId> --ejecutar, la misma reconstrucción (sin --ejecutar solo muestra las diferencias). Una carga que falla se reintenta sola hasta 5 veces, con una espera creciente (15 minutos, 30, 1 hora, 2 horas); después queda la alerta y ese script. Además, cada 10 minutos la API vuelve a calcular las cuentas de los documentos que cambiaron desde la pasada anterior (la primera vez, las últimas 6 horas; en orden y con tope, sin saltarse nada: una proyección que no alcanzó a correr, una nota rechazada después, una nota de débito aceptada antes que su factura al contado).

  • Una factura 33 o 34 a crédito (formaPago: 2). Al contado o sin costo se presume pagada y no deja cuenta. Vence en su fechaVencimiento; si no la mandaste, en la emisión más el plazo de pago del contacto o, si no tiene, más el plazoPagoDefectoDias del módulo. Ese vencimiento calculado se fija al crearse la cuenta: cambiar después el plazo del contacto no lo mueve.
  • Una nota de débito 56 suma a la cuenta del documento que referencia y hereda su vencimiento. Si ese documento es tuyo y no tiene cuenta (una venta al contado, que se presume pagada), la 56 tampoco crea una, igual que la 61. Solo tiene cuenta propia, que vence el día de su emisión, una 56 sin referencia o que referencia un documento que no está (no es tuyo, o el SII todavía no lo acepta: cuando lo acepta, la de la 56 pasa a ser parte de la suya).
  • Una nota de crédito 61: codRef 1 anula la cuenta (ajustado 0, anulada), 3 resta su total y 2 no cambia nada; sobre un documento sin cuenta no crea nada. Una 56 que anula una 61 revive lo que esa 61 quitó.
  • No dejan deuda las boletas (39/41), las guías (52), la factura de compra 46 (es por pagar) ni la exportación (110/111/112). Solo cuenta lo aceptado por el SII, de producción y que no es demo; una reemisión, en su intento aceptado.
  • En la contabilidad, con el módulo encendido, la centralización de ventas lleva a Clientes lo que estas cuentas cuentan y el resto a Caja (ver Contabilidad).

GET /api/empresas/:empresaId/cobranza/cuentas (cobranza:leer, cualquier rol) responde { cuentas, total, pagina, totalPaginas, hoy }, por vencimiento, con los filtros opcionales contactoId, rut, estado, vencidas=1, desde y hasta (fecha de emisión), pagina y limite (hasta 200). Un filtro inválido es 400 DATOS_INVALIDOS con detalles[]. GET .../cobranza/cuentas/:cuentaId responde { cuenta }:

json
{
  "cuenta": {
    "id": "671f0c2a9b1e4a0012ab34cd",
    "sentido": "cobrar",
    "origen": { "tipo": "emitido", "emitidaId": "671f0b119b1e4a0012ab3401" },
    "contraparte": { "rut": "76086428-5", "razonSocial": "Cliente SpA", "contactoId": "66aa01019b1e4a0012ab0001" },
    "tipoDte": 33,
    "folio": 1520,
    "fechaEmision": "2026-10-01",
    "fechaVencimiento": "2026-10-31",
    "montoOriginal": 119000,
    "ajustes": [
      { "emitidaId": "671f0d779b1e4a0012ab3499", "tipoDte": 61, "folio": 88, "codRef": 3, "monto": -19000, "fecha": "2026-10-05" }
    ],
    "montoAjustado": 100000,
    "montoPagado": 0,
    "saldo": 100000,
    "saldoAFavor": 0,
    "estado": "pendiente",
    "vencida": false,
    "huerfana": false,
    "creadaEn": "2026-10-01T15:02:11.000Z",
    "actualizadaEn": "2026-10-05T12:40:09.000Z"
  }
}

saldo es max(0, montoAjustado − montoPagado), lo que queda por cobrar, nunca negativo; lo que sobra va en saldoAFavor (max(0, montoPagado − montoAjustado)): una nota de crédito mayor que el total, que deja montoAjustado negativo, o un pago de más. montoPagado es la suma de los pagos recibidos vigentes imputados a la cuenta. El estado, en este orden: anulada (una nota de crédito la anuló, aunque tenga pagos); con saldo 0, pagada si recibió pagos o saldada si la cerraron notas de crédito sin pagos (una nota de crédito nunca la deja pagada); parcial; pendiente. El filtro estado acepta esos cinco. Vencida no es un estado sino vencida: true en una pendiente o parcial cuyo vencimiento ya pasó (nunca en una huérfana, ver abajo). Una cuenta de otra empresa o que no existe es 404 CUENTA_NO_ENCONTRADA; con el módulo apagado, 409 VENTAS_INACTIVO. El detalle trae además pagos[]: los pagos vigentes imputados a la cuenta ({ id, fecha, medioPago, referencia, cuentaDestino, monto, montoPago }).

Pagos recibidos

Un pago de un cliente imputado a una o más de sus cuentas por cobrar, en una sola transacción con el montoPagado de cada cuenta y el asiento de cobro: o queda todo o no queda nada. Lo registran y anulan el admin, el contador y el superadmin, o una key con cobranza:escribir; el emisor no (403). Lo leen todos los roles y cobranza:leer.

json
POST /api/empresas/:empresaId/cobranza/pagos   (Idempotency-Key opcional)
{
  "fecha": "2026-10-05",
  "medioPago": "transferencia",
  "referencia": "TRX-88231",
  "cuentaDestino": "banco",
  "monto": 150000,
  "imputaciones": [
    { "cuentaId": "671f0c2a9b1e4a0012ab34cd", "monto": 100000 },
    { "cuentaId": "671f0c2a9b1e4a0012ab34ce", "monto": 50000 }
  ]
}
  • fecha no posterior a hoy (es la del asiento); medioPago con el vocabulario de la emisión; cuentaDestino banco o caja; monto igual a la suma de las imputaciones; la fecha no anterior a la emisión de las cuentas; de 1 a 100 imputaciones, cada cuenta una vez, del mismo cliente, pendiente o parcial y sin superar su saldo. Todos los errores juntos: 400 DATOS_INVALIDOS con detalles[].
  • Responde 201 { pago, cuentas, repetido: false }. Dos pagos simultáneos sobre el mismo saldo no se pisan: el segundo responde 409 SOBREPAGO (o 400 si ya lo vio al validar) y el saldo nunca queda negativo; una cuenta que cambió de otra forma, 409 CUENTA_CAMBIO. Con la misma Idempotency-Key y el mismo cuerpo, 200 con el mismo pago; con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO.
  • Asiento de cobro (origen cobro): al debe Banco o Caja (los roles banco y caja de la regla de ventas; banco es 1.1.01.002 por defecto); al haber, por cada imputación, Clientes con el RUT del cliente o, si el mes de la venta se centralizó entero a Caja, Caja (un traspaso). Lo que cae en la misma cuenta se netea; si no queda nada, asientoId: null y motivoSinAsiento: "neteado". Sin plan de cuentas, "sin_plan_de_cuentas". Con el período contable cerrado, 409 PERIODO_CERRADO sin escribir nada; una cuenta del plan que no sirve, 409 CUENTA_CONTABLE_INVALIDA. Un pago sin plan de cuentas recibe su asiento después, si la empresa siembra su plan, con el script cobros-asientos-pendientes.js de la plataforma. El asiento de cobro no se anula a mano (409 ASIENTO_DE_COBRO): se anula con su pago. Si después el mes se centraliza de la otra forma, la centralización corta con 409 COBROS_ABONADOS_A_CLIENTES o COBROS_ABONADOS_A_CAJA.
  • La cuenta Banco (la de los cobros y la de los pagos a proveedores) es el rol banco de la regla centralizacion_ventas, que se configura en PUT /api/contabilidad/:empresaId/reglas-centralizacion (el PUT reemplaza el mapa completo: reenvía las demás cuentas propias). Una cuenta que no existe en el plan, está desactivada, es un título, no es de activo o es la de Clientes responde 422 CUENTA_BANCO_INVALIDA con detalles[] y no se guarda. Se lee al registrar: anular un pago anula el asiento que se guardó. La conciliación bancaria cruza la cartola con la cuenta contra la que se importó, así que los cobros calzan con la cartola importada contra la cuenta banco que tenían al registrarse.
  • POST .../cobranza/pagos/:pagoId/anular con { motivo }: el pago pasa a anulado, las cuentas recuperan lo imputado y el asiento se anula, en una transacción. Con el período cerrado, 409 PERIODO_CERRADO; repetirla, 409 PAGO_YA_ANULADO.
  • GET .../cobranza/pagos con contactoId, rut, estado, desde, hasta (fecha del pago), pagina y limite; GET .../cobranza/pagos/:pagoId responde { pago } o 404 PAGO_NO_ENCONTRADO.

Límite de crédito

Si el contacto tiene comercial.limiteCredito, confirmar una nota de venta revisa que la deuda abierta del cliente más el total de la nota no lo supere. La deuda abierta es el saldo de sus cuentas pendiente o parcial por RUT, sin las huérfanas (cuentas); sus otras notas confirmadas que todavía no son un DTE (notasConfirmadas); y sus notas convertidas en los últimos 7 días cuyo DTE todavía no tiene cuenta y puede tenerla, una factura a crédito de producción que el SII no ha aceptado o cuya cuenta todavía no se proyecta (notasEnConversion). Si lo supera, 409 LIMITE_CREDITO_EXCEDIDO con { limite, deuda, nota, cuentas, notasConfirmadas, notasEnConversion }. El 0 es sin crédito; sin el campo, no hay límite.

Antigüedad de saldos

GET .../cobranza/antiguedad (cobranza:leer, cualquier rol), con corte (por defecto, hoy en Chile), contactoId o rut, pagina y limite (clientes, hasta 500), todos opcionales. Reparte las cuentas con saldo, emitidas hasta el corte y no huérfanas, por días de atraso desde su vencimiento hasta el corte: por_vencer (vence el corte o después), 1-30, 31-60, 61-90 y +90. El saldo es el de hoy: un corte en el pasado reparte la deuda que sigue abierta. Por eso la respuesta trae siempre saldoAl: "hoy" y, con un corte anterior a hoy, una advertencia que lo dice (si no, null).

json
{
  "corte": "2026-10-09",
  "saldoAl": "hoy",
  "advertencia": null,
  "tramos": [
    { "tramo": "por_vencer", "etiqueta": "Por vencer", "cuentas": 1, "saldo": 10000 },
    { "tramo": "1-30", "etiqueta": "1 a 30 días", "cuentas": 2, "saldo": 50000 },
    { "tramo": "31-60", "etiqueta": "31 a 60 días", "cuentas": 1, "saldo": 35000 },
    { "tramo": "61-90", "etiqueta": "61 a 90 días", "cuentas": 1, "saldo": 50000 },
    { "tramo": "+90", "etiqueta": "Más de 90 días", "cuentas": 2, "saldo": 67000 }
  ],
  "total": { "cuentas": 7, "clientes": 2, "saldo": 212000, "vencido": 202000, "porVencer": 10000 },
  "clientes": [
    {
      "rut": "76086428-5", "razonSocial": "Cliente SpA", "contactoId": "66aa01019b1e4a0012ab0001",
      "cuentas": 6, "total": 205000, "vencido": 195000, "diasMaximoAtraso": 91,
      "tramos": { "por_vencer": 10000, "1-30": 50000, "31-60": 35000, "61-90": 50000, "+90": 60000 }
    }
  ],
  "totalClientes": 2,
  "pagina": 1,
  "totalPaginas": 1
}

Estado de cuenta

GET .../cobranza/estado-cuenta con contactoId o rut (uno de los dos) y desde y hasta opcionales responde { cliente, desde, hasta, hoy, saldoInicial, movimientos, saldoFinal, resumen, huerfanas }. Los movimientos van en orden cronológico con su saldo corrido: los cargos (cada documento por su monto original, en su emisión), los ajustes (cada nota, con su signo, en su fecha) y los abonos (cada imputación de un pago vigente, en la fecha del pago; un pago anulado no aparece). Cada uno trae monto con signo y cargo y abono sin signo. saldoInicial suma lo anterior a desde; sin hasta, saldoFinal es exactamente la suma de saldo − saldoAFavor de las cuentas del cliente. resumen trae deudaTotal, vencida, porVencer, saldoAFavor, limiteCredito (o null) y pagadoEnHuerfanas. Sin cliente, con los dos o con fechas inválidas, 400 con detalles[]; un contacto de otra empresa, 404 CONTACTO_NO_ENCONTRADO.

Cuentas huérfanas

Una cuenta queda huérfana (huerfana: true) cuando ya no es deuda propia pero tiene pagos y no se puede borrar: por ejemplo, la de una nota de débito que el SII aceptó antes que la factura a la que suma, y que alguien pagó; al llegar la factura, su monto pasa a la cuenta de la factura. No entra a la antigüedad, al límite de crédito ni a vencidas=1, y no recibe pagos nuevos (400 DATOS_INVALIDOS; si queda huérfana mientras se registra el pago, 409 CUENTA_CAMBIO); el estado de cuenta la muestra aparte en huerfanas[] con { cuenta, cuentaDuena, pagos, advertencia }, y la plataforma recibe una alerta. La resolución es manual: anula sus pagos y vuelve a registrarlos contra la cuenta correcta. Sin pagos, la revisión periódica la borra.

Recordatorios de cobranza

Correos automáticos a los clientes con documentos por cobrar, unos días antes y después del vencimiento. Doble opt-in: el servidor tiene que tener su cron encendido (COBRANZA_RECORDATORIOS_CRON=true, apagado por defecto) y la empresa los enciende en recordatorios.activo de la configuración (también apagado por defecto), con el módulo encendido. Corre una vez al día, a las 09:15 de Chile, solo en empresas vigentes. No se dispara por la API: el admin los enciende en Configuración › Módulos › Ventas y cobranza.

  • Hitos: por cada d de diasAntes, las cuentas que vencen dentro de d días (con 0, el mismo día); por cada d de diasDespues, las que vencieron hace d días. «Hoy» es el día en Chile: con los valores por defecto, una cuenta que vence el 20-10-2026 recibe un aviso el 17 y otros el 21 y el 27 de octubre y el 4 y el 19 de noviembre.
  • Si el servidor no corrió un día: cada corrida revisa también los hitos de los 3 días anteriores. Los que quedaron sin aviso (el servidor estuvo caído, o los recordatorios se encendieron hace poco) salen en la corrida siguiente, con la situación de ese día; los que ya tienen aviso no se repiten, y un hito de hace más de 3 días ya no sale.
  • Qué cuentas: solo las pendiente o parcial con saldo; nunca las pagadas, saldadas, anuladas ni las huérfanas.
  • Un correo por cliente y día (por RUT), con sus documentos (tipo y folio, emisión, vencimiento, monto, saldo y situación), el total pendiente y los datos de la empresa emisora. El destinatario es el correo del contacto o, si no tiene, el del receptor del DTE; sin correo no se manda y queda registrado. Si el contacto está desactivado, el correo del DTE no se usa de respaldo y el aviso se descarta: desactivar un contacto detiene sus recordatorios. copiaA recibe copia oculta.
  • Registro persistente: cada aviso queda guardado por cuenta y hito, con un índice único, y se reserva antes de mandar el correo: un reinicio o dos corridas a la vez nunca repiten un aviso. Si el servidor se cae justo mientras manda, ese aviso no se repite (como máximo una vez).
  • Reintentos: un correo que el proveedor rechaza se reintenta en las corridas siguientes, hasta 3 intentos en total, sin repetir los ya enviados; si la cuenta se pagó entremedio, ya no se manda. Un correo caído no rompe nada. El registro se lee por la API (ver abajo).

Leer el registro: GET .../cobranza/recordatorios (cobranza:leer, cualquier rol) responde { recordatorios, total, pagina, totalPaginas }, los más nuevos primero (por fecha, el día de la corrida que reservó el aviso). Filtros opcionales: cuentaId, rut (del cliente, con o sin puntos), estado (reservado, enviado, fallido, sin_correo o descartado), hito (antes:N o despues:N), desde y hasta (AAAA-MM-DD, inclusive), pagina y limite (50 por defecto, hasta 200). Un filtro inválido responde 400 DATOS_INVALIDOS con todos los errores juntos en detalles. Cada recordatorio trae id, cuentaId, hito, cliente, fecha, fechaVencimiento, estado, intentos, enviadoEn, destinatario y motivo (sin_correo, contacto_desactivado o cuenta_sin_saldo). El mensaje de error del proveedor de correo no se expone. Es solo lectura: los avisos los escribe el cron.

json
{
  "recordatorios": [
    {
      "id": "6710c0ffee0000000000a001",
      "cuentaId": "6710c0ffee0000000000c001",
      "hito": "antes:3",
      "cliente": "76086428-5",
      "fecha": "2026-10-17",
      "fechaVencimiento": "2026-10-20",
      "estado": "enviado",
      "intentos": 1,
      "enviadoEn": "2026-10-17T12:15:04.000Z",
      "destinatario": "pagos@cliente.cl",
      "motivo": null
    }
  ],
  "total": 1,
  "pagina": 1,
  "totalPaginas": 1
}

Ventas por vendedor

GET .../ventas/reportes/vendedores (ventas:leer, cualquier rol), con desde y hasta opcionales, responde { desde, hasta, vendedores, total }. Por vendedor (nombre del usuario; sin vendedor, id: null): las cotizaciones ofrecidas (todas menos borrador y anulada), las aceptadas y la tasa de aceptación; las notas de venta confirmadas y convertidas; y los DTE emitidos desde una conversión, aceptados por el SII, de producción y sin el folio anulado. Cada métrica va por la fecha de su documento y los montos son el total con IVA.

json
{
  "vendedor": { "id": "66aa01019b1e4a0012ab0101", "nombre": "Ana Pérez" },
  "cotizaciones": { "cantidad": 4, "monto": 10000, "aceptadas": 2, "montoAceptado": 5000, "tasaAceptacion": 0.5 },
  "notasVenta": { "confirmadas": { "cantidad": 1, "monto": 7000 }, "convertidas": { "cantidad": 1, "monto": 8000 } },
  "dte": { "cantidad": 1, "monto": 8000 }
}

Despachos: facturar varias guías y lista de picking

POST .../ventas/facturar-guias (ventas:escribir y dte:emitir) factura varias guías 52 del mismo cliente en UNA factura 33 o 34, con una referencia por guía (TpoDocRef 52, folio y fecha), como pide el DL 825, art. 55. Emite por el camino de POST /dte y acepta Idempotency-Key.

  • Cada guía: de la empresa, aceptada por el SII, de venta (IndTraslado 1 o 2), no anulada ni facturada; todas del mismo RUT, ambiente y modo demo, hasta 40. Todo se valida antes del folio, con los errores juntos en detalles[]; una guía ya facturada o en facturación es 409 GUIAS_NO_FACTURABLES.
  • Las líneas son las de las guías (precio neto), sin itemId ni CdgItem: las guías ya sacaron el stock y la factura no lo vuelve a descontar.
  • Dos facturaciones simultáneas de la misma guía: pasa una (409 GUIA_EN_FACTURACION la otra). Si el SII rechaza la factura, sus guías quedan libres al aplicarse el veredicto; con el envío incierto, no. Reemitir esa factura con alguna guía ya facturada por otra es 409 GUIAS_YA_FACTURADAS, sin folio.
  • Una facturación cortada a medias la resuelve un admin con sesión (POST .../ventas/facturar-guias/resolver, pasados 15 minutos): la liga a la factura vigente que referencia la guía o, si no hay ninguna, la libera.
  • avisos[] trae el plazo del art. 55 (la factura de las guías de un mes se puede postergar hasta el día 10 del mes siguiente, con fecha de ese período). No bloquean.

GET .../ventas/documentos/:documentoId/picking (ventas:leer): la lista de picking de una nota de venta confirmada, en JSON o en PDF con ?formato=pdf. Con el inventario encendido trae la bodega y los lotes sugeridos en orden FEFO (sin vencidos) o las series disponibles, con faltante si no alcanzan. Es solo lectura y una sugerencia: no reserva lotes ni series. Fuera de esta versión: el despacho parcial de una nota y los couriers.

Facturación recurrente

Suscripciones de un cliente a una factura periódica (33 o 34): mensual, trimestral, semestral o anual. Se leen con ventas:leer: GET .../ventas/suscripciones, .../suscripciones/:suscripcionId y .../suscripciones/:suscripcionId/emisiones (un registro por período, con el estado del SII). Crear, editar, pausar, reanudar, terminar, reactivar (POST .../suscripciones/:suscripcionId/reactivar) y emitir un período (POST .../emisiones/:emisionId/emitir) son solo de un admin con sesión: una API key no programa facturas que se emiten solas.

  • Borrador por defecto: cada período queda como un borrador SIN folio que una persona revisa y emite. En modo: automatico se emite solo, por el camino del lote, con validarPayload antes del folio y idempotencyKey recurrente:<suscripcionId>:<periodo>.
  • Precios NETOS, en pesos enteros o en UF (hasta 4 decimales). La UF es la guardada del día de emisión; sin ella el período queda sin_uf y se reintenta. Cada precio en pesos es Math.round(precioUf × UF).
  • Fecha: la del día de emisión y solo dentro del mes del período (DL 825, art. 55); si el mes termina sin emitirse, el período queda omitida. Una factura emitida antes del pago adelanta el IVA (Oficio SII 2147/2016).
  • Ambiente: el de la empresa; una suscripción creada con una key mk_cert_ emite siempre en certificación.
  • Reintentos: sin_folios y sin_uf se reintentan y avisan a la empresa una sola vez por período, en el primero, para alcanzar a timbrar o cargar la UF dentro del mes; un rechazo del SII o una emisión interrumpida quedan para revisión humana, con aviso a la empresa, y nunca se reemiten solos. El correo al cliente sale solo con el veredicto ACEPTADO.
  • Fin por N emisiones: cuentan los períodos debidos, también los omitidos o rechazados; los meses en pausa no cuentan. Con N=6, si se emite marzo, se pausa abril y mayo y se reanuda en junio, salen junio a octubre: seis facturas.
  • Reactivar (POST .../reactivar, responde { suscripcion }): solo una terminada, la haya terminado una persona o su fin; si no, 409 ESTADO_INVALIDO. Retoma como reanudar, en el período que corresponde hoy: los meses en que estuvo terminada no se emiten ni cuentan para fin.emisiones, y nunca vuelve a un período que ya tiene registro en el historial (uno omitido al terminarla no se reemite). Limpia terminadaEn y motivoTermino, anota reactivadaEn y deja el modo, las líneas, el cliente y el calendario como estaban. Sin períodos por delante, 409 SUSCRIPCION_SIN_PERIODOS sin tocar nada.
  • Errores juntos: un cliente desactivado o un ítem del catálogo borrado se suman a los errores de validarPayload en el mismo errores[], sin folio.
json
{
  "nombre": "Soporte mensual",
  "contactoId": "6650f1c2a1b2c3d4e5f60718",
  "tipoDte": 33,
  "items": [{ "nombre": "Plan soporte", "cantidad": 1, "precio": 10000 }],
  "moneda": "CLP",
  "periodicidad": "mensual",
  "diaEmision": 5,
  "fechaInicio": "2026-11-01",
  "fin": { "tipo": "emisiones", "emisiones": 12 },
  "formaPago": 2,
  "diasVencimiento": 30,
  "modo": "borrador",
  "correo": { "enviar": true, "para": ["pagos@cliente.cl"] }
}

CRM liviano: oportunidades y tareas

Un embudo de ventas por etapas y tareas de seguimiento, dentro del módulo de ventas: se leen con ventas:leer (todos los roles) y se escriben con ventas:escribir (emisor y admin; el contador solo lee). Ninguna ruta toca un folio ni el SII. Bajo .../ventas/oportunidades: listar (el kanban, con resumen por etapa: cantidad, monto y monto ponderado), crear, leer (con bitacora, cotizaciones y tareas), editar, POST .../transiciones, POST .../reabrir y POST/DELETE .../cotizaciones. Bajo .../ventas/tareas: listar, crear y editar.

  • Etapas: prospecto → contactado → cotizado → negociacion → ganada | perdida. Entre las abiertas se avanza, se salta y se vuelve atrás; una ganada o perdida se reabre con POST .../reabrir (409 OPORTUNIDAD_CERRADA si se intenta mover). Perder exige motivo (400 DATOS_INVALIDOS).
  • Probabilidad: 10, 20, 50, 75, 100 y 0 % por etapa; una abierta puede traer la suya, que se borra al cambiar de etapa. montoEstimado es NETO y montoPonderado es monto × probabilidad.
  • Cotizaciones vinculadas: una cotización está en una sola oportunidad (dos vinculaciones simultáneas a oportunidades distintas dejan una y la otra responde 409 COTIZACION_YA_VINCULADA; repetir la misma es idempotente). Vincular una ya aceptada (o convertida) gana la oportunidad en la misma respuesta; una rechazada, anulada o vencida se vincula sin mover la etapa. Si una vinculada se acepta, la oportunidad abierta pasa sola a ganada; si se rechaza y no le queda otra abierta ni aceptada, a perdida con «cotización rechazada». La respuesta de la cotización no cambia.
  • Tareas: de una oportunidad o de un contacto; vence en hora de Chile, "2026-10-20T09:30" o "2026-10-20" (todo el día). Sin filtros, GET .../tareas trae las pendientes de quien pregunta, las vencidas primero; PATCH con { "hecha": true } la marca hecha.
json
{
  "contactoId": "6650f1c2a1b2c3d4e5f60718",
  "titulo": "Renovación de equipos",
  "montoEstimado": 1000000,
  "fechaCierreEsperada": "2026-12-15"
}

Compras y cuentas por pagar

Órdenes de compra, recepción de mercadería y cuentas por pagar sobre los documentos que recibes. Se está construyendo por partes: hoy existen la configuración del módulo, sus dos scopes, el plazo de pago del proveedor en el contacto, las cuentas por pagar que salen del RCV de compras y de las facturas de compra 46 que emites, los pagos a proveedores, la compensación de un saldo a favor, la cesión de una factura como deudor, los reportes (antigüedad, estado de cuenta de un proveedor y calendario de pagos), las órdenes de compra y la recepción de mercadería contra ellas, y el vínculo de las cuentas por pagar con su orden, con la conciliación de 3 vías, la factura de compra 46 desde una orden ya recibida y la carga del XML de un documento recibido.

Opt-in por empresa, y aparte de ventas

Encender compras no enciende ventas ni al revés. Con el módulo apagado (el estado de toda empresa hasta que un admin lo enciende) ninguna respuesta cambia.

Viene en todos los planes de MiAplicación ERP, sin topes. Encender el módulo exige un plan ERP que lo habilite (la contratación vigente, pagada y sin vencer, el plan asignado por la plataforma a una empresa que nunca pagó o una cortesía vigente); sin él responde 403 PLAN_SIN_COMPRAS sin escribir nada, con el ERP de entrada en planSugerido. Un módulo ya encendido no se bloquea si la contratación ERP vence: solo se frena volver a encenderlo después de apagarlo. Bajar a un plan de la API deja sus datos en solo lectura.

json
{
  "error": "La empresa no tiene una contratación vigente, así que no puede encender compras y cuentas por pagar: MiAplicación ERP incluye compras y cuentas por pagar, desde el plan ERP Pyme.",
  "code": "PLAN_SIN_COMPRAS",
  "requiere": "erp",
  "plan": null,
  "planSugerido": { "clave": "erp_pyme", "nombre": "ERP Pyme" }
}

Configuración de compras

GET /api/empresas/:empresaId/compras/configuracion (compras:leer, cualquier rol de la empresa):

json
{
  "configuracion": {
    "id": "6705f2c1a1b2c3d4e5f60720",
    "activo": true,
    "plazoPagoProveedorDias": 30,
    "montoAprobacionOc": null
  },
  "plan": { "clave": "negocio", "nombre": "Negocio" },
  "puedeActivar": true
}
CampoQué es
idnull si la empresa nunca guardó su configuración (son los valores por defecto).
activoEl módulo está encendido.
plazoPagoProveedorDiasPlazo de pago a un proveedor que no tiene el suyo: el vencimiento de una cuenta por pagar será la emisión más este plazo. Entero de 0 a 365 (0 = contado); por defecto 30.
montoAprobacionOcMonto neto más exento (sin IVA), en pesos enteros, desde el cual una orden de compra pide aprobación. null = sin umbral (por defecto): solo un admin emite.
plan{ clave, nombre } del plan que habilita (contratación vigente, plan asignado o cortesía), o null sin uno.
puedeActivarSi la barrera del plan dejaría encender el módulo a quien pregunta. No dice nada del rol: encender es de admin.

PUT /api/empresas/:empresaId/compras/configuracion es solo con sesión (solo admin; la cuenta demo compartida recibe 403 CUENTA_DEMO_RESTRINGIDA). Acepta 3 campos, todos opcionales (manda al menos uno): activo, plazoPagoProveedorDias y montoAprobacionOc. Cualquier otra clave se ignora. Valida todo antes de escribir y responde 400 DATOS_INVALIDOS con todos los errores juntos en detalles[]; los números van como número entero, no como texto. Apagar no borra nada. Con alguna orden de compra cuya factura 46 esté emitiendo o revisar, apagar responde 409 COMPRAS_FACTURAS_EN_VUELO con las órdenes en detalles[] y no apaga: se espera a que terminen o un admin las resuelve (el resolver de la 46 funciona aunque compras esté apagado). Si una factura quedó en vuelo de todas formas, la revisión periódica de compras la sigue procesando con el módulo apagado.

Plazo de pago del proveedor

El contacto (/api/empresas/:empresaId/contactos, solo con sesión) acepta un bloque opcional compras, aparte de comercial: las condiciones que le das a un cliente no son las que te da un proveedor, y un mismo contacto puede ser las dos cosas.

json
{ "compras": { "plazoDias": 45 } }
  • plazoDias: días que el proveedor te da para pagarle. Entero de 0 a 365, o null. Sin él, vale el plazoPagoProveedorDias del módulo. El contacto tiene que tener el rol proveedor (los roles del mismo cuerpo o, si no vienen, los guardados); si no, 400 COMPRAS_INVALIDO.
  • Sin el bloque, el contacto es exactamente el de siempre: la respuesta no trae la clave compras. Con él, la trae al final. Se acepta aunque el módulo esté apagado.
  • Solo un admin lo escribe. Cualquier otro rol que lo mande (también como compras.plazoDias, o compras: null) recibe 403 COMPRAS_SOLO_ADMIN sin que se escriba nada.
  • El bloque se reemplaza completo: compras: null, {} o { "plazoDias": null } lo quitan; quitarlo no exige el rol proveedor.
  • Un contacto que deja de ser proveedor conserva su bloque compras (a diferencia de la lista de precios de un cliente): un plazo que nadie usa es inofensivo, y si vuelve a ser proveedor lo recupera.
  • Datos inválidos: 400 COMPRAS_INVALIDO con todos los errores juntos en detalles[]. Si en el mismo cuerpo también falla comercial, sale un solo 400 COMERCIAL_INVALIDO con los errores de los dos bloques.

Cuentas por pagar del RCV de compras

Con el módulo encendido, cada documento que recibes y que el SII deja en tu Registro de Compras y Ventas (RCV) tiene su cuenta por pagar. Es una proyección: no se teclea, se recalcula sola cuando la sincronización con el SII baja las compras, y al encender el módulo se cargan todas las compras ya sincronizadas. Un documento es una cuenta aunque el SII lo haya movido de período: manda la fila de un estado definitivo (REGISTRO, RECLAMADO o NO_INCLUIR) antes que una PENDIENTE o desconocida de cualquier período, y entre las del mismo rango, la del período más reciente. Un RUT con o sin puntos es el mismo proveedor.

Estado en el RCVCuenta por pagar
REGISTROFacturas 33, 34 y 43: deuda por su total. Nota de débito 56: deuda propia (el RCV no trae la referencia).
REGISTRONota de crédito 61: cuenta de monto negativo, un saldo a favor con el proveedor (saldo 0, saldoAFavor = su monto, estado saldada). No se descuenta sola de ninguna factura.
RECLAMADOCuenta anulada (monto ajustado 0).
PENDIENTE, NO_INCLUIR o desconocidoSin cuenta: se listan aparte, en GET .../compras/documentos-sin-cuenta.
Factura de compra 46Sin cuenta desde el RCV: su cuenta sale de la 46 que emites (ver abajo).
  • Vencimiento: la emisión más el plazo del proveedor (compras.plazoDias del contacto con ese RUT) o, si no lo tiene, el plazoPagoProveedorDias del módulo. Una vez calculado se conserva: cambiar el plazo no mueve lo ya cargado. La 61 vence el día de su emisión.
  • Al contado: si el proveedor marcó el documento pagado al contado, la cuenta trae contado: true. Igual es deuda: el pago se registra.
  • Una cuenta que deja de ser deuda (el documento pasó a NO_INCLUIR, por ejemplo) se borra; si ya tenía pagos, queda con huerfana: true.

GET /api/empresas/:empresaId/compras/cuentas (compras:leer, cualquier rol de la empresa) lista las cuentas por pagar con los mismos filtros y la misma forma que las cuentas por cobrar (?contactoId=&rut=&estado=&vencidas=&desde=&hasta=&pagina=&limite=), más ordenId, que deja las cuentas vinculadas a esa orden de compra (ver Vincular con la orden de compra y conciliación):

json
{
  "cuentas": [
    {
      "id": "6706a1c2b3d4e5f601234567",
      "sentido": "pagar",
      "origen": {
        "tipo": "recibido",
        "emitidaId": null,
        "documento": { "rutEmisor": "76086428-5", "tipoDte": 33, "folio": 1520 }
      },
      "contraparte": { "rut": "76086428-5", "razonSocial": "PROVEEDOR SPA", "contactoId": "6705f2c1a1b2c3d4e5f60801" },
      "tipoDte": 33,
      "folio": 1520,
      "fechaEmision": "2026-09-10",
      "fechaVencimiento": "2026-10-25",
      "montoOriginal": 119000,
      "ajustes": [],
      "montoAjustado": 119000,
      "montoPagado": 0,
      "saldo": 119000,
      "saldoAFavor": 0,
      "estado": "pendiente",
      "vencida": false,
      "huerfana": false,
      "creadaEn": "2026-10-09T13:05:11.204Z",
      "actualizadaEn": "2026-10-09T13:05:11.204Z"
    }
  ],
  "total": 1,
  "pagina": 1,
  "totalPaginas": 1,
  "hoy": "2026-10-09"
}

GET .../compras/cuentas/:cuentaId devuelve { cuenta } con sus pagos vigentes en cuenta.pagos y sus compensaciones vigentes en cuenta.compensaciones. Toda cuenta por pagar trae además contado, cedida, cesion (null sin ceder), historialCesion (las cesiones que se quitaron o reemplazaron) y ordenCompra ({ ordenId, numero } de la orden de compra vinculada, o null); las cuentas por cobrar no traen esas claves. Una cuenta de otra empresa, una cuenta por cobrar o un id que no existe responden 404 CUENTA_NO_ENCONTRADA. GET .../compras/documentos-sin-cuenta?estadoRcv=&pagina=&limite= lista los documentos del RCV que no son deuda (estadoRcv: PENDIENTE, NO_INCLUIR o DESCONOCIDO; sin él, los tres), cada uno con rutEmisor, razonSocial, tipoDte, folio, fechaEmision, montoTotal, estadoRcv, periodo y contado. Con el módulo apagado, las tres rutas responden 409 COMPRAS_INACTIVO.

Una empresa ajena responde 403 Solo puedes acceder a las compras de tu propia empresa.

Cuenta por pagar de la factura de compra 46 que emites

La factura de compra (46) la emites tú a un vendedor que no factura (y le retienes el IVA): es una deuda tuya con él. Con el módulo encendido, cada 46 con monto (montoTotal mayor que 0), aceptada por el SII (o con reparos), de producción, que no es del modo demo y cuyo folio no se anuló en el SII, tiene su cuenta por pagar, cualquiera sea su forma de pago. Se proyecta sola con el veredicto del SII, en segundo plano (nunca demora la emisión), y al encender el módulo se cargan las 46 ya aceptadas.

  • origen: { "tipo": "emitido", "emitidaId": "<id del documento emitido>" }, sin documento. contraparte: el vendedor, el receptor de la 46.
  • Monto: el montoTotal de la 46, que ya descuenta la retención de IVA (con retención total es el neto).
  • Vencimiento: la fechaVencimiento de la 46; si no la trae, la emisión más el plazo del vendedor (compras.plazoDias de su contacto) o el plazoPagoProveedorDias del módulo. El que sale de un plazo se conserva una vez calculado.
  • Las notas que emites sobre tu 46 la corrigen, con las mismas reglas que las cuentas por cobrar: una 61 con CodRef 1 la anula, con CodRef 3 resta, con CodRef 2 no cambia nada; una 56 suma, y la 56 que anula esa 61 la revive. Cada nota queda en ajustes[] con su emitidaId. Las notas no tienen cuenta propia, ni por pagar ni por cobrar.
  • Forma de pago: toda 46 con monto tiene cuenta, sea a crédito, al contado, sin costo o sin formaPago. La de contado (formaPago: 1) queda marcada contado: true: igual es deuda, y su pago al contado (por Caja) la salda. La 46 está en el registro de compras del SII y la centralización de compras abona Proveedores por ella, así que sin su cuenta no habría contra qué registrar ese pago. Las notas que emitas sobre cualquier 46 la corrigen. Una 46 de monto 0 no tiene cuenta.
  • Una 46 rechazada, de certificación o del modo demo no tiene cuenta. Si deja de contar después (rechazo tardío, folio anulado en el SII), su cuenta se borra; si ya tenía pagos, queda con huerfana: true.

Reconciliación de las cuentas por pagar

  • Cada 10 minutos (minutos 9, 19, 29…, hora de Chile) un proceso revisa, en las empresas con el módulo encendido, lo que cambió desde su pasada anterior: las filas del RCV de compras y las 46 con sus notas (un rechazo tardío, un folio anulado). Recalcula sus cuentas y retoma la carga inicial si quedó a medias. No habla con el SII. En una instalación propia se apaga con COMPRAS_RECONCILIADOR_CRON=false (y con CRONS_ENABLED=false, junto a los demás).
  • A mano, node scripts/cxp-reconstruir.js --empresa <empresaId> recalcula todas las cuentas por pagar de la empresa (RCV y 46) y muestra las diferencias con lo guardado, sin escribir nada; con --ejecutar las corrige. Nunca toca lo pagado.
  • Las cuentas que quedaron huérfanas con pagos o compensaciones se revisan en la misma pasada: si su alerta de plataforma falló, se reintenta; si ya no tienen pagos ni compensaciones, se borran.

Pagos a proveedores

POST /api/empresas/:empresaId/compras/pagos (compras:escribir, o admin, contador y superadmin con sesión; el emisor recibe 403), con Idempotency-Key opcional. Mismo contrato que los pagos recibidos de cobranza: fecha (no futura ni anterior a la emisión), medioPago, referencia opcional, cuentaDestino (banco o caja), monto e imputaciones a cuentas por pagar pendientes o parciales del mismo proveedor, sin pagarles más que su saldo; además confirmarCesion opcional. Responde 201 { pago, cuentas, repetido: false }; los errores van todos juntos en detalles[] (400). Dos pagos simultáneos sobre el mismo saldo no lo dejan negativo.

  • El asiento (pago_proveedor, tipo egreso): al debe, Proveedores (2.1.01.001 en la plantilla) por cada imputación con el RUT del proveedor; al haber, Banco o Caja (los mismos de los cobros: los roles banco y caja de la regla de ventas) por el total. Sin plan de cuentas, el pago va sin asiento (motivoSinAsiento: sin_plan_de_cuentas); con el período cerrado, 409 PERIODO_CERRADO. Desde Contabilidad no se anula (409 ASIENTO_DE_PAGO_PROVEEDOR): se anula con su pago.
  • POST .../compras/pagos/:pagoId/anular ({ motivo }) devuelve los saldos y anula el asiento; GET .../compras/pagos y GET .../compras/pagos/:pagoId los leen con compras:leer. ?beneficiario= (un RUT) deja solo los pagos que fueron a ese cesionario; un RUT inválido es 400.
  • Webhooks: registrar un pago a proveedor emite cxp.pago_registrado y anularlo, cxp.pago_anulado, solo con el módulo de compras encendido (Webhooks). Nunca los cxc.*, que son de ventas.

Compensación con saldo a favor

Una nota de crédito 61 recibida sin referencia es un saldo a favor con el proveedor. Se aplica a una factura pendiente o parcial del mismo proveedor con POST .../compras/cuentas/:cuentaId/compensar, donde :cuentaId es la cuenta de la 61, con { contraCuentaId, monto } (solo con sesión, admin o contador; Idempotency-Key opcional). Responde 201 { compensacion, cuentas: [la 61, la factura], repetido: false }. No hay asiento: la centralización de compras ya rebajó Proveedores con la 61. La factura suma el monto a su montoPagado y la 61 lo resta del suyo (queda negativo). POST .../compras/compensaciones/:compensacionId/anular la deshace.

Cesión de una factura por pagar (factoring)

Si el proveedor cedió una factura, márcalo con PUT .../compras/cuentas/:cuentaId/cesion { cesionario: { rut, razonSocial }, fecha, nota? } (solo con sesión y solo admin; { cesionario: null } la quita). Un pago que imputa una cuenta cedida exige confirmarCesion: true (si no, 409 CUENTA_CEDIDA) y guarda al cesionario en beneficiario; la glosa del asiento dice que es un factoring. Quitar o reemplazar una cesión deja la anterior en historialCesion (accion quitada o reemplazada, el cesionario, cuándo y quién; las 20 más recientes). Si otra persona la cambió mientras tanto, 409 CUENTA_CAMBIO sin escribir nada.

Límite contable de la cesión

El asiento sigue rebajando Proveedores con el RUT del proveedor (el del documento), aunque la plata fue al cesionario: no hay una cuenta de acreedores por factoring. Para conciliar con la cartola, usa beneficiario.

Reportes de cuentas por pagar

Tres lecturas con compras:leer (cualquier rol de la empresa); con el módulo apagado, 409 COMPRAS_INACTIVO, y los errores de forma, todos juntos en detalles[] (400).

  • Antigüedad: GET .../compras/antiguedad?corte=&contactoId=&rut=&pagina=&limite=. La misma forma y los mismos tramos que la de cobranza, sobre lo que debes. La lista se llama clientes también aquí, y son tus proveedores. Solo muestra saldos: una factura saldada con una compensación no se cuenta como plata pagada.
  • Estado de cuenta de un proveedor: GET .../compras/estado-cuenta?contactoId=|rut=&desde=&hasta=. Trae proveedor (cliente sigue igual). Cada compensación vigente es un movimiento compensacion en sus dos cuentas (abono en la factura, cargo en la nota de crédito) y todo movimiento trae compensacionId; una cuenta reclamada en el RCV lleva su ajuste. Así el saldo final cuadra con la suma de saldo − saldoAFavor. El resumen separa pagado (plata) de compensado.
  • Calendario de pagos: GET .../compras/calendario?desde=&hasta= (fechas de vencimiento; sin ellas, ocho semanas desde el lunes de esta; a lo más 26). Las semanas de lunes a domingo con sus vencimientos y totales (cedidas y contado aparte), los totales por proveedor y anteriores, lo vencido antes del rango que sigue abierto. Entran las cuentas pendientes o parciales con saldo y no huérfanas. Cada vencimiento separa pagado (plata) de compensado. Los totales siempre son completos; el detalle, hasta 1.000 cuentas (truncado).

Órdenes de compra

El pedido que le haces a un proveedor. No es un documento tributario: no tiene folio del SII ni se envía al SII. Su número es un correlativo interno por empresa (sin saltos ni repetidos) y su PDF dice «Documento sin validez tributaria». La mercadería se recibe contra la orden (ver Recepción de mercadería).

MétodoRuta (prefijo /api/empresas/:empresaId/compras)ScopeQuién, con sesión
GET/ordenescompras:leerTodos los roles
POST/ordenescompras:escribirAdmin y emisor
GET/ordenes/:ordenIdcompras:leerTodos los roles
PATCH/ordenes/:ordenIdcompras:escribirAdmin y emisor
POST/ordenes/:ordenId/transicionescompras:escribirAdmin y emisor (cada acción exige lo suyo)
GET/ordenes/:ordenId/pdfcompras:leerTodos los roles

El contador solo lee (403 al escribir). Todo exige el módulo encendido (409 COMPRAS_INACTIVO). Crear una orden, con Idempotency-Key opcional:

json
POST /api/empresas/:empresaId/compras/ordenes
{
  "contactoId": "6705f2c1a1b2c3d4e5f60801",
  "bodegaId": "6705f2c1a1b2c3d4e5f60900",
  "fechaEntregaEsperada": "2026-10-20",
  "referenciaProveedor": "COT-778",
  "lineas": [
    { "itemId": "6705f2c1a1b2c3d4e5f60a01", "cantidad": 100, "costoUnitario": 150, "descuento": { "tipo": "porcentaje", "valor": 10 } },
    { "nombre": "Flete", "cantidad": 1, "costoUnitario": 20000, "exento": true }
  ],
  "descuentoGlobal": { "tipo": "monto", "valor": 1000 }
}

201 { "orden": { "id": "6706b2c3d4e5f60712345678", "numero": 12, "estado": "borrador",
  "proveedor": { "contactoId": "6705f2c1a1b2c3d4e5f60801", "rut": "76086428-5", "razonSocial": "FERRETERÍA EL PERNO SPA", … },
  "plazoPagoDias": 45, "tipoDteSugerido": 33,
  "lineas": [ { "id": "6706b2c3d4e5f60712345679", "costoUnitario": 150, "montoNeto": 13097, "cantidadRecibida": 0, "cantidadPendiente": 100, … }, … ],
  "totales": { "neto": 13097, "exento": 19403, "iva": 2488, "total": 34988 }, … },
  "repetido": false }
  • contactoId es obligatorio: un contacto de tu empresa, activo y con el rol proveedor. La orden guarda una copia de sus datos (proveedor) que se refresca al editarla en borrador. bodegaId es opcional (de tu empresa, activa; no exige el inventario encendido).
  • fechaEmision (por defecto hoy en Chile) y fechaEntregaEsperada (opcional, no anterior) van como AAAA-MM-DD. plazoPagoDias (0 a 365) sale, si no lo mandas, del proveedor o del módulo. referenciaProveedor hasta 40 caracteres; nota hasta 500.
  • lineas: de 1 a 60, con itemId?, varianteId?, codigo?, nombre (obligatorio sin ítem), unidad?, cantidad (hasta 6 decimales), costoUnitario, descuento? y exento?. costoUnitario es un COSTO neto en pesos enteros: nunca se toma el precio de venta del ítem. Un ítem pack es 400 (pide sus componentes); un ítem con variantes lleva la variante.
  • Los totales los calcula siempre el servidor con la misma función que arma el detalle de una factura (33, o 34 si todo es exento). Un contacto, ítem o bodega de otra empresa responde igual que uno que no existe. Los errores van todos juntos en detalles[] (400 DATOS_INVALIDOS).
  • Con la misma Idempotency-Key y el mismo cuerpo, 200 con la misma orden (repetido: true), también si los dos pedidos llegan a la vez; con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO.
  • PATCH .../ordenes/:ordenId acepta los mismos campos, solo en borrador (409 OC_NO_EDITABLE); lineas las reemplaza todas. El listado (?estado=&contactoId=&rut=&desde=&hasta=&q=) no trae líneas; q busca el número o un trozo de la razón social, como texto literal. El PDF dice «PROVEEDOR» y lleva la leyenda arriba y en el pie. Se puede bajar en cualquier estado, pero una orden que todavía no sale hacia el proveedor lo dice en una banda bajo el encabezado: «BORRADOR: NO ENVIAR AL PROVEEDOR», «PENDIENTE DE APROBACIÓN: NO ENVIAR AL PROVEEDOR» o «ANULADA».

Estados y transiciones: POST .../ordenes/:ordenId/transiciones con { "accion": "emitir", "motivo": "…" } devuelve { orden }.

accionDesdePasa aQuién
solicitar_aprobacionborradorpor_aprobarAdmin, emisor o una API key
aprobarpor_aprobaremitidaSolo admin; el proveedor tiene que seguir activo y con el rol proveedor
rechazarpor_aprobarborradorSolo admin, con motivo
emitirborradoremitidaAdmin siempre; emisor o API key solo bajo el monto de aprobación. El proveedor tiene que seguir activo y con el rol proveedor
anularborrador, por_aprobar o emitidaanuladaSolo admin, con motivo, y si no se ha recibido nada (una recibida parcial se cierra con cerrar)
cerrarrecibida_parcialcerradaSolo admin, con motivo: cierra lo que faltaba recibir

recibida_parcial y recibida los pone la recepción de mercadería. El emisor y una API key con compras:escribir emiten solo si la configuración tiene montoAprobacionOc y el neto de la orden (afecto más exento, sin IVA) es menor que ese monto; sin monto (el valor por defecto) solo el admin emite. Si no, 403 OC_REQUIERE_APROBACION: envíala a aprobación. Aprobar, rechazar, anular y cerrar son del admin con sesión (403 OC_SOLO_ADMIN). Al emitir o aprobar, el contacto tiene que seguir activo y con el rol proveedor; si no, 409 OC_PROVEEDOR_NO_VALIDO y no se escribe nada.

codeHTTPCuándo
OC_NO_ENCONTRADA404La orden no existe o es de otra empresa.
OC_NO_EDITABLE409Editar una orden que no está en borrador.
OC_CONFLICTO_DE_EDICION409Otro cambio llegó entremedio: vuelve a leerla y repite.
OC_TRANSICION_INVALIDA409La acción no corresponde al estado (también la segunda de dos simultáneas).
OC_SOLO_ADMIN403Aprobar, rechazar, anular o cerrar sin ser admin con sesión.
OC_REQUIERE_APROBACION403Un emisor o una API key emite sin monto de aprobación o sobre él.
OC_CON_RECEPCIONES409Anular una orden con mercadería recibida, también en recibida_parcial (se cierra con cerrar) o recibida.
OC_PROVEEDOR_NO_VALIDO409Emitir o aprobar con un proveedor desactivado, sin el rol proveedor o que ya no existe.

Recepción de mercadería

Registra lo que llegó del proveedor contra una orden emitida o recibida_parcial, en una o varias entregas. Cada recepción tiene su número correlativo por empresa y, si el inventario está encendido, entra al stock en la misma operación.

MétodoRuta (prefijo /api/empresas/:empresaId/compras)ScopeQuién, con sesión
POST/ordenes/:ordenId/recepcionescompras:escribirAdmin y emisor
GET/ordenes/:ordenId/recepcionescompras:leerTodos los roles
GET/recepcionescompras:leerTodos los roles
GET/recepciones/:recepcionIdcompras:leerTodos los roles
POST/recepciones/:recepcionId/anularsolo con sesiónSolo admin

El contador solo lee (403 al recibir). Todo exige el módulo encendido (409 COMPRAS_INACTIVO). Recibir, con Idempotency-Key opcional; cada línea nombra la línea de la orden por su id:

json
POST /api/empresas/:empresaId/compras/ordenes/:ordenId/recepciones
{
  "fecha": "2026-10-09",
  "documentoProveedor": { "tipoDte": 52, "folio": 881 },
  "nota": "Llegó la primera entrega",
  "lineas": [ { "lineaId": "6706b2c3d4e5f60712345679", "cantidad": 40 } ]
}

201 { "recepcion": { "id": "6707c3d4e5f6071234567890", "numero": 5, "estado": "vigente",
  "ordenId": "6706b2c3d4e5f60712345678", "ordenNumero": 12, "bodegaId": "6705f2c1a1b2c3d4e5f60900",
  "documentoProveedor": { "tipoDte": 52, "folio": 881 },
  "lineas": [ { "lineaOrdenId": "6706b2c3d4e5f60712345679", "cantidad": 40, "costoUnitario": 130.97, "movioStock": true, … } ],
  "operacionInventarioId": "6707c3d4e5f6071234567891", "sinInventario": false, … },
  "orden": { "estado": "recibida_parcial",
    "lineas": [ { "id": "6706b2c3d4e5f60712345679", "cantidadRecibida": 40, "cantidadPendiente": 60, … }, … ], … },
  "repetido": false }
  • lineas: de 1 a 60, con lineaId (una línea de ESTA orden, sin repetir), cantidad (hasta 6 decimales) y, según el ítem, lotes o series. bodegaId es opcional: sin ella, la de la orden y, si no tiene, la bodega por defecto del inventario. fecha (AAAA-MM-DD, no posterior a hoy), documentoProveedor ({ tipoDte: 33 | 34 | 46 | 52, folio }) y nota (hasta 500) son opcionales.
  • Nunca más que lo pendiente (cantidad − cantidadRecibida de la línea): pasarse es 400 DATOS_INVALIDOS, con todos los errores juntos en detalles[], y no se escribe nada. Sin nada pendiente en ninguna línea la orden pasa a recibida; si no, a recibida_parcial. Una orden en otro estado no se recibe (409 OC_TRANSICION_INVALIDA). Mientras su factura de compra 46 se emite (o quedó en revisión), 409 OC_FACTURA_EN_VUELO; con la 46 ya emitida sí se recibe más, y eso queda sin facturar.
  • Costo: la mercadería entra al costo neto efectivo de la línea: su montoNeto (con el descuento de la línea y su parte del global) dividido por la cantidad pedida, con hasta 6 decimales (13.097 / 100 = 130,97). Recalcula el costo promedio.
  • Inventario: con el inventario encendido, cada línea cuyo ítem controla stock entra como una entrada con motivo compra, en una operación de tipo recepcion_compra. La recepción, el stock, el kardex y la orden se escriben juntos o no se escribe nada. Un ítem por lote exige lotes que sumen la cantidad; uno por serie, series (una por unidad, sin repetir).
  • Inventario apagado, servicios y líneas sin ítem: se registran con su cantidad y movioStock: false, sin tocar el stock, y cuentan igual para el estado. Si ninguna línea movió stock, sinInventario: true.
  • Con la misma Idempotency-Key y el mismo cuerpo, 200 con la misma recepción (repetido: true), también si llegan a la vez; con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO. De dos recepciones simultáneas por lo mismo pasa una; la otra recibe 409 y el stock sube una sola vez.
  • Leer: GET .../recepciones/:recepcionId (con líneas), GET .../ordenes/:ordenId/recepciones (las de la orden, completas) y GET .../recepciones?ordenId=&estado=&desde=&hasta= (sin líneas; estado es vigente o anulada).

Anular: POST .../recepciones/:recepcionId/anular con { "motivo": "…" } (obligatorio), solo un admin con sesión, devuelve { recepcion, orden, advertencias }. En una sola operación marca la recepción anulada, deshace su entrada de inventario y descuenta lo recibido de la orden, que vuelve a recibida_parcial o a emitida. Si alguna serie que entró ya salió de su bodega (vendida, de baja o trasladada), 409 RECEPCION_CON_SERIES_USADAS y no se anula nada; lo mismo con una serie que al entrar cubrió una venta anterior (stock negativo), y su detalle lo dice así. Las cantidades sin serie no se bloquean por stock: si el saldo queda negativo, advertencias lo dice (STOCK_NEGATIVO). Una serie es única por ítem: la misma en dos variantes del mismo ítem es 400 junto con los demás errores.

codeHTTPCuándo
RECEPCION_NO_ENCONTRADA404La recepción no existe o es de otra empresa.
RECEPCION_YA_ANULADA409La recepción ya estaba anulada.
RECEPCION_CON_SERIES_USADAS409Anular con series que ya no están en su bodega (salieron, o cubrieron una venta anterior al entrar): no se anuló nada.
OC_CERRADA409Anular una recepción de una orden cerrada.
OC_CONFLICTO_DE_EDICION409Otra recepción se llevó lo pendiente entremedio: vuelve a leer la orden.
OC_FACTURADA409Anular una recepción de una orden que ya tiene su 46 (o que se está emitiendo): no se anula; una devolución se registra como merma y, si corresponde, la 46 se corrige con una nota de crédito.
OC_FACTURA_EN_VUELO409Recibir mientras la 46 de la orden se emite o está en revisión.

Vincular con la orden de compra y conciliación

Cada cuenta por pagar (una factura recibida del RCV o una 46 que emites) se puede vincular a una orden de compra; una orden puede tener muchos documentos. Con el vínculo, la orden se concilia en 3 vías: lo ordenado, lo recibido y lo facturado.

MétodoRuta (prefijo /api/empresas/:empresaId/compras)ScopeQuién, con sesión
PUT/cuentas/:cuentaId/ordencompras:escribirAdmin y emisor
GET/ordenes/:ordenId/conciliacioncompras:leerTodos los roles

Vincular: { "ordenId": "<id de la orden>" } devuelve { cuenta } con ordenCompra: { ordenId, numero }; { "ordenId": null } la desvincula (también una cuenta que nunca se vinculó, que así queda fuera del vínculo automático; la primera vez responde accion: "desvinculada" y repetirlo, "sin_cambios"). El contador solo lee (403 al vincular) y todo exige el módulo encendido (409 COMPRAS_INACTIVO).

  • La orden tiene que ser de tu empresa (404 OC_NO_ENCONTRADA) y estar emitida, recibida_parcial, recibida o cerrada (409 OC_NO_VINCULABLE); su proveedor, el de la cuenta por RUT (409 OC_PROVEEDOR_DISTINTO): en un documento recibido, su emisor; en una 46, el vendedor.
  • Una cuenta anulada o huérfana no se vincula (409 CUENTA_NO_VINCULABLE). Con la misma orden otra vez, 200 sin cambios; con otra orden, 409 CUENTA_YA_VINCULADA: primero desvincula. Dos pedidos simultáneos no se pisan.
  • Vínculo automático: una recepción con documentoProveedor 33, 34 o 46 (la guía 52 no es deuda) vincula sola la cuenta de ese documento; si dos órdenes anotan el mismo documento, queda la de la primera recepción. Si la factura 33 o 34 aparece después (el RCV llega más tarde), la revisión periódica parte de las cuentas sin vínculo de los últimos 120 días, busca la recepción vigente con ese documento y la vincula; si hay varias, gana la más reciente. Nunca reemplaza un vínculo ni vuelve a vincular una cuenta que desvinculaste a mano, y las proyecciones de las cuentas no lo tocan. La 46 que emites desde una orden (factura de compra desde la orden) se vincula sola a esa orden cuando su cuenta nace (con el veredicto ACEPTADO), y la revisión periódica lo reintenta.
  • GET .../cuentas?ordenId= deja solo las cuentas vinculadas a esa orden.

La conciliación es solo informativa: nunca reclama un documento, nunca bloquea un pago y nunca escribe nada. Las cifras van en pesos netos (neto + exento, sin IVA):

json
GET /api/empresas/:empresaId/compras/ordenes/:ordenId/conciliacion

200 { "orden": { "id": "6706b2c3d4e5f60712345678", "numero": 12, "estado": "recibida_parcial", "lineas": 2, … },
  "ordenado": 150000, "recibido": 72000, "facturado": 82000, "estimado": false, "truncado": false, "tolerancia": 150,
  "diferencias": { "recibidoMenosOrdenado": -78000, "facturadoMenosRecibido": 10000, "facturadoMenosOrdenado": -68000 },
  "alertas": [ { "code": "facturado_mayor_que_recibido", "diferencia": 10000, "detalle": "…" } ],
  "documentos": [ { "cuentaId": "6706a1c2b3d4e5f601234567", "origen": "recibido", "tipoDte": 33, "folio": 1520,
    "neto": 72000, "netoNotas": 0, "netoFacturado": 72000, "total": 81880, "saldo": 81880, "estado": "pendiente",
    "cuenta": true, "estimado": false, "notas": [], … }, … ],
  "recepciones": [ { "id": "6707c3d4e5f6071234567890", "numero": 5, "fecha": "2026-10-09", "valor": 72000,
    "documentoProveedor": { "tipoDte": 33, "folio": 1520 } } ] }
CifraDe dónde sale
ordenadoLos totales de la orden: neto + exento.
recibidoΣ, en las recepciones vigentes, de cantidad × costoUnitario (el costo neto efectivo), redondeado por línea.
facturadoΣ del neto + exento de los documentos vinculados (la fila del RCV o la 46 emitida), con sus notas: la 56 suma y la 61 resta. Sin neto, el total y estimado: true. Una cuenta anulada o huérfana no suma (cuenta: false).

diferencias trae recibido − ordenado, facturado − recibido y facturado − ordenado, con signo. La tolerancia es max(líneas de la orden, round(0,1 % de lo ordenado)) pesos: una diferencia dentro de ella no genera alerta. La conciliación lee a lo más 500 documentos vinculados: con más, la respuesta trae truncado: true y la alerta documentos_truncados, y los demás se revisan con GET .../cuentas?ordenId=.

alertas[].codeCuándo
facturado_mayor_que_recibidoHay recepciones y documentos, y lo facturado supera lo recibido.
facturado_mayor_que_ordenadoLo facturado supera lo ordenado.
recibido_menor_que_ordenadoSolo con la orden recibida o cerrada: lo recibido quedó bajo lo ordenado.
sin_facturaHay recepciones y ningún documento vinculado que cuente.
sin_recepcionHay documentos vinculados y ninguna recepción vigente.
documentos_truncadosLa orden tiene más de 500 documentos vinculados: lo facturado cuenta solo los primeros 500.

Por línea (porLinea): si algún documento vinculado que cuenta (o una nota que lo ajusta) tiene su XML cargado con líneas, la respuesta trae además cada línea de la orden contra lo recibido y lo facturado en los XML. Sin XML la respuesta es la de antes, sin la clave. Una línea del XML calza con la de la orden cuyo codigo es igual (mayúsculas incluidas) a cualquiera de sus CdgItem/VlrCodigo, nunca por el nombre; si apunta a más de una línea, no se adivina y va a sinCalce. Una factura suma su QtyItem y su MontoItem; una nota con CodRef 1 (anula) también, con su signo (la 61 resta); con CodRef 3 (corrige montos), solo el monto (soloMonto: true); una nota sin CodRef 1 ni 3 va a sinCalce. montoOrdenado es el de la línea tras su descuento y antes del global; diferenciaMonto = montoFacturado − round(montoOrdenado × facturado / pedido), con tolerancia max(1, round(0,1 % de montoOrdenado)) pesos. Un documento que cuenta sin XML (o una 46 emitida) va a documentosSinDetalle con parcial: true.

json
"porLinea": { "parcial": false, "documentosSinDetalle": [],
  "lineas": [ { "lineaOrdenId": "6706b2c3d4e5f60712345679", "codigo": "T-01", "nombre": "Tornillo", "unidad": "UN",
    "cantidadPedida": 10, "cantidadRecibida": 10, "cantidadFacturada": 10, "montoOrdenado": 10000, "precioOrden": 1000,
    "montoFacturado": 10500, "precioFacturado": 1050, "montoEsperado": 10000, "diferenciaMonto": 500, "tolerancia": 10,
    "estado": "con_diferencias", "alertas": [ { "code": "precio_distinto", "detalle": "…" } ],
    "aportes": [ { "cuentaId": "6706a1c2b3d4e5f601234567", "tipoDte": 33, "folio": 1520, "nroLinDet": 1, "cantidad": 5,
      "monto": 5000, "soloMonto": false }, … ] } ],
  "sinCalce": [] }
porLineaValores
lineas[].estadocalza, con_diferencias (tiene alertas), sin_facturar, sin_codigo (la línea de la orden no tiene código) o codigo_repetido.
lineas[].alertas[].codefacturado_mayor_que_recibido, facturado_mayor_que_pedido, recibido_menor_que_pedido (solo con la orden recibida o cerrada) o precio_distinto (fuera de la tolerancia).
sinCalce[].motivosin_codigo, codigo_no_esta_en_la_orden, codigo_ambiguo, nota_sin_codref o sin_monto.
codeHTTPCuándo
OC_NO_VINCULABLE409La orden no está emitida, recibida_parcial, recibida ni cerrada.
OC_PROVEEDOR_DISTINTO409La orden es de otro proveedor (por RUT).
CUENTA_YA_VINCULADA409La cuenta ya está vinculada a otra orden: primero desvincúlala.
CUENTA_NO_VINCULABLE409La cuenta está anulada o huérfana (ya no es deuda).
CUENTA_CAMBIO409El vínculo de la cuenta cambió mientras se desvinculaba: vuelve a leerla.

Factura de compra desde la orden

POST .../compras/ordenes/:ordenId/factura-compra emite la factura de compra 46 de una orden ya recibida, por el mismo camino de POST /dte tipo 46: el servidor arma el documento con lo recibido. Exige compras:escribir y dte:emitir; con sesión, el admin y el emisor (el contador no, 403). Cuenta en el mismo tope de emisiones por minuto que POST /dte.

bash
curl -X POST "https://api.miaplicacion.cl/api/empresas/$EMPRESA/compras/ordenes/$ORDEN/factura-compra" \
  -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{ "formaPago": 2, "fechaVencimiento": "2026-11-09", "codRetencion": 15, "retencionTotal": true }'
Campo del cuerpoQué es (como en POST /dte tipo 46)
formaPagoObligatorio: 1 contado, 2 crédito, 3 sin costo.
fechaVencimientoOpcional, AAAA-MM-DD.
codRetencionOpcional; sin él, 15 (retención total del IVA).
retencionTotalOpcional, true o false.
fechaOpcional: la fecha de emisión; sin ella, hoy.
sucursalIdOpcional: la sucursal desde la que se emite.
ambienteOpcional, con las reglas de ambiente de POST /dte.

Lo demás del cuerpo se ignora. Lo que arma el servidor:

  • Receptor: el proveedor del snapshot de la orden. Si le falta el giro, la dirección o la comuna, el 400 lo dice junto con los demás errores, antes del folio.
  • Líneas: la cantidad recibida de cada línea al costo neto efectivo (con su descuento y el global prorrateado). PrcItem va en pesos enteros: si el costo tiene decimales, el precio sube al peso siguiente y la diferencia va como descuento de la línea, así el monto de cada línea es exactamente lo recibido valorizado.
  • Referencia: la orden de compra (TpoDocRef 801, su número y su fecha).
  • Una línea exenta recibida responde 400 con un mensaje claro, sin folio: la 46 retiene IVA y no admite líneas exentas. Tampoco una línea sin monto (costo efectivo 0, o tan bajo que lo recibido vale $0).
  • Mientras la 46 se emite no se recibe mercadería en la orden (409 OC_FACTURA_EN_VUELO), y con la orden facturada no se anula una recepción (409 OC_FACTURADA).
  • Stock: la 46 no lo mueve, aunque el inventario esté encendido y el ítem tenga código. La recepción ya lo movió; por eso las líneas van sin itemId ni codigos.

Una 46 por orden, y el ambiente

Se factura una orden recibida_parcial, recibida o cerrada con algo recibido. Con una factura en curso, en revisión, emitida o incierta responde 409; dos pedidos simultáneos dan una 46 y un 409, con un solo folio. Si el SII la rechaza, la orden vuelve a ser facturable: emítela de nuevo desde la orden o reemite el rechazado, nunca las dos (409 OC_FACTURA_REEMITIDA o CONVERSION_REEMPLAZADA).

Con la empresa en producción (sin modo demo), una 46 que saldría en certificación (key mk_cert_ o "ambiente": "certificacion") responde 409 OC_FACTURA_FUERA_DE_PRODUCCION sin tocar la orden ni consumir folio, como la conversión de ventas. Con la empresa en certificación se emite en certificación.

El 201 trae orden (con factura46) y dte (el 201 de POST /dte, tal cual). Un error responde lo mismo que POST /dte, más orden. Cuando el SII acepta la 46, su cuenta por pagar nace vinculada a la orden. El documento guarda { ordenCompraId, clase: "orden_compra", numero } en origenComercial.

json
201 { "orden": { "id": "6706b2c3d4e5f60712345678", "numero": 12, "estado": "recibida",
    "factura46": { "estado": "emitida", "emitidaId": "6707d4e5f607123456789abc", "folio": 41, "rechazadaId": null,
      "intentos": 1, "ultimoError": null, "en": "2026-10-10T14:03:11.000Z" }, … },
  "dte": { "success": true, "folio": 41, "tipoDTE": 46, "emitidaId": "6707d4e5f607123456789abc", … } }
factura46.estadoQué pasó¿Se vuelve a facturar?
emitidaLa 46 salió (o la reemisión de una rechazada).No: una por orden.
inciertaEl envío al SII quedó sin respuesta: en revisión.No: consúltala por folio.
errorNo hubo documento (validación, folios, ambiente).Sí.
rechazadaEl SII la rechazó (rechazadaId).Sí, o reemite el rechazado (no las dos).
emitiendoLa emisión está en curso.No (409).
revisarSe cortó a medias sin registro local; la revisión periódica avisa a la plataforma y nunca la libera sola: la resuelve un admin.No (409).

Resolver una factura en revisión: POST .../ordenes/:ordenId/factura-compra/resolver con { "accion": "ligar" | "liberar", "emitidaId"?, "motivo" }, solo un admin con sesión (una API key recibe 403; funciona aunque compras esté apagado), después de revisar en el SII si tiene la 46. ligar resuelve una factura revisar o una incierta sin 46 ligada (el registro local falló); liberar, solo una revisar. Responde { orden, accion, resultado } y queda en el historial de la orden. La revisión periódica también mira las incierta: si su 46 terminó aceptada (con o sin reparos), pasa a emitida; si terminó rechazada, a rechazada; si sigue en proceso, queda ligada a esa 46.

accionCuándoQué hace
ligarEl SII tiene la 46 (emitidaId: una 46 de tu empresa emitida desde esta orden, después de que empezó la factura).La factura se cierra con ella. Otra 46 es 409 DTE_DE_OTRA_ORDEN; una inexistente, 404 DTE_NO_ENCONTRADO.
liberarEl SII no la tiene.Pasa a error con tu motivo y la orden vuelve a ser facturable. Con una 46 registrada de esa factura, 409 OC_FACTURA_CON_DTE (se liga); antes de una hora, 409 OC_FACTURA_LIBERACION_PREMATURA.
codeHTTPCuándo
OC_NO_FACTURABLE409La orden no está recibida_parcial, recibida ni cerrada.
OC_SIN_RECEPCIONES409La orden no tiene mercadería recibida.
OC_FACTURA_EN_CURSO409La 46 de la orden se está emitiendo.
OC_FACTURA_EN_REVISION409La 46 se cortó a medias y está en revisión.
OC_YA_FACTURADA409La orden ya tiene su 46 (emitida o incierta).
OC_FACTURA_REEMITIDA409La 46 rechazada ya se reemitió: no se factura de nuevo.
OC_FACTURA_CON_DTE409Un intento anterior dejó un documento registrado.
OC_FACTURA_FUERA_DE_PRODUCCION409Empresa en producción y la 46 saldría en certificación (o se liga una 46 de certificación o demo).
OC_FACTURA_NO_EN_REVISION409Liberar una factura que no está en revisión, o ligar una que no está en revisión ni incierta sin 46 ligada.
COMPRAS_FACTURAS_EN_VUELO409Apagar compras con órdenes cuya factura 46 está emitiendo o revisar (las trae en detalles[]). No se apagó.
OC_FACTURA_LIBERACION_PREMATURA409Liberar antes de una hora desde que empezó la factura.
DTE_DE_OTRA_ORDEN409Ligar a un documento que no es una 46 emitida desde esa orden.
DTE_ANTERIOR_A_LA_FACTURA409Ligar a una 46 emitida antes de que empezara la factura.
DTE_NO_ENCONTRADO404Ligar a un documento que no existe en la empresa.

Cargar el XML de un documento recibido

El RCV no trae el vencimiento, la forma de pago, las referencias ni las líneas de lo que recibes. Si tienes el XML que te mandó el proveedor (el EnvioDTE de intercambio, o un <DTE> suelto), cárgalo con POST .../compras/documentos-xml (compras:escribir; con sesión, el admin y el emisor; el contador no, 403) y la cuenta por pagar lo usa. Se lee con compras:leer: GET .../documentos-xml (con ?rut=&tipoDte=&folio=&desde=&hasta=, sin el XML), GET .../documentos-xml/:documentoId (con sus líneas y referencias) y GET .../documentos-xml/:documentoId/xml (el bloque <DTE> como application/xml). El de otra empresa es 404 XML_NO_ENCONTRADO.

El archivo va como multipart/form-data en el campo archivo, o como cuerpo text/xml o application/xml, hasta 2 MB (413 XML_DEMASIADO_GRANDE). Se decodifica con el encoding de su declaración: ISO-8859-1 (el del SII), UTF-8, windows-1252 o UTF-16 con su BOM; sin declaración, UTF-8 (otro, 400 XML_ENCODING_NO_SOPORTADO). Tiene que estar bien formado, con un EnvioDTE (hasta 500 documentos) o un DTE de raíz; si no, 400 con el motivo en detalles[]. Un <!DOCTYPE o un <!ENTITY se rechaza siempre (400 XML_NO_PERMITIDO).

bash
curl -X POST "https://api.miaplicacion.cl/api/empresas/$EMPRESA/compras/documentos-xml" \
  -H "X-Api-Key: $API_KEY" \
  -F "archivo=@EnvioDTE_76086428-5_33_4512.xml;type=application/xml"
  • Cada <DTE> va por su cuenta (el archivo no es atómico). Se cargan los tipos 33, 34, 43, 46 (de un tercero), 56 y 61; una 46 que emitiste tú se ignora (sin_cambios, factura_compra_propia).
  • El RCV es la autoridad: RUTRecep tiene que ser tu empresa, el documento tiene que estar en tu registro de compras y MntTotal tiene que ser el mismo (y MntNeto y MntExe si el RCV trae el desglose). Si algo no cuadra, ese DTE se rechaza con todas las diferencias en detalles[] y no se guarda. La firma electrónica no se verifica en esta versión (firmaVerificada: false).
  • Se guarda solo el bloque <DTE>, con el xmlns del sobre si no lo declara (así su firma sigue verificando fuera del sobre). El mismo XML otra vez responde sin_cambios sin escribir ni volver a calcular la cuenta (la reconstrucción la recalcula); otro XML del mismo documento lo reemplaza (reemplazado: true).

200 si al menos un DTE se aceptó o quedó sin cambios; si ninguno, 422 XML_SIN_DOCUMENTOS_VALIDOS con las mismas claves y los detalles[] de todos (409 CONCURRENCIA si fue solo una carga simultánea):

json
{
  "resultados": [
    { "indice": 1, "documento": { "rutEmisor": "76086428-5", "tipoDte": 33, "folio": 4512 }, "resultado": "aceptado",
      "documentoId": "6707e5f6071234567890abcd", "reemplazado": false, "motivo": null, "code": null, "detalles": [], "advertencias": [],
      "cuenta": { "id": "6707a1b2c3d4e5f601234567", "fechaVencimiento": "2026-11-30", "contado": false, "estado": "pendiente",
        "montoAjustado": 11900, "saldo": 11900, "saldoAFavor": 0, "referenciaPendiente": null }, "ajusta": null,
      "verificacionTed": { "resultado": "valido", "motivo": "firma_valida", "detalle": "…" } },
    { "indice": 2, "documento": { "rutEmisor": "76086428-5", "tipoDte": 33, "folio": 4513 }, "resultado": "rechazado",
      "documentoId": null, "motivo": null, "code": "NO_CUADRA_CON_RCV",
      "detalles": ["MntTotal: el XML dice $10710 y el registro de compras $11900.", "MntNeto: el XML dice $9000 y el registro de compras $10000."],
      "advertencias": [], "cuenta": null, "ajusta": null,
      "verificacionTed": { "resultado": "invalido", "motivo": "firma_no_calza", "detalle": "…" } }
  ],
  "aceptados": 1, "sinCambios": 0, "rechazados": 1, "firmaVerificada": false
}
code de un DTECuándo
DTE_INCOMPLETOLe falta el tipo, el folio, la emisión, un RUT o el total.
TIPO_NO_ADMITIDONo es 33, 34, 43, 46, 56 ni 61.
RECEPTOR_DISTINTORUTRecep no es tu empresa.
NO_ESTA_EN_RCVNo está en tu registro de compras: sincroniza el RCV.
NO_CUADRA_CON_RCVEl total (o el neto o el exento) no es el del RCV.
CONCURRENCIAOtra carga del mismo documento lo cambió mientras se guardaba.

El timbre (TED) sí se verifica, solo como información: cada DTE trae verificacionTed: { resultado, motivo, detalle } (también uno rechazado) y, si se guarda, queda en el documento con verificadoEn; el listado y el detalle lo traen (null en los XML cargados antes). No bloquea nada: un timbre inválido se carga igual si cuadra con el RCV. Se verifica la firma FRMT (RSA-SHA1) sobre el DD aplanado con la RSAPK del CAF que viene en el mismo DD, y que el timbre sea de este documento (RE, TD, F, FE, RR, MNT y el rango del CAF). La firma del SII sobre el CAF (FRMA) no se verifica. Se toleran espacios entre etiquetas, prefijos de espacio de nombres y el sobre EnvioDTE.

resultadomotivoCuándo
validofirma_validaLa firma calza y el timbre es de este documento.
invalidofirma_no_calzaLa firma no corresponde al DD con la clave del CAF.
invalidotimbre_de_otro_documentoLa firma calza, pero el DD o el CAF no son de este documento.
no_verificablesin_tedEl DTE no trae TED.
no_verificableted_incompletoFalta el DD, el FRMT, el CAF o su RSAPK.
no_verificablealgoritmo_no_soportadoEl FRMT no es SHA1withRSA.
no_verificableclave_invalidaLa RSAPK no es base64 o pasa de 4096 bits.
no_verificableted_ilegibleEl timbre no se puede leer (mal formado, una entidad ajena, demasiado grande o anidado).

Qué cambia en la cuenta por pagar (la proyección lee el XML siempre, también al reconstruir):

  • FchVenc pisa el vencimiento; una anterior a la emisión se ignora, con una advertencia. FmaPago 1 marca la cuenta contado.
  • Una 61 (o 56) sin referencia en el RCV cuyo XML referencia un documento del mismo proveedor (33, 34, 46, 56 o 61) con CodRef 1 o 3, y con cuenta por pagar, deja de ser un saldo suelto y ajusta esa cuenta (ajustes[] con su documento, y ajusta en el resultado), con las reglas de las notas de ventas. Un CodRef 2 o ausente no mueve nada, y una nota nunca ajusta un documento reclamado en el RCV (queda con su propia cuenta). Si la nota y el documento son de meses distintos, cada mes de la centralización de compras queda corrido en el monto de la nota, con signo contrario; la suma de los dos cuadra.
  • Una nota que ya tenía pagos o compensaciones no se mueve sola: queda marcada referenciaPendiente, con una advertencia y una alerta. Anula sus compensaciones y pagos y la revisión periódica la aplica.
  • Las líneas no cambian la cuenta: la conciliación de la orden usa el neto del XML (estimado: false), trae lineasXml y concilia línea por línea en porLinea. El detalle de la cuenta trae xml: { documentoId, cargadoEn } o null.
codeHTTPCuándo
XML_AUSENTE400Sin el campo archivo ni un cuerpo text/xml o application/xml.
XML_ARCHIVO_INVALIDO400Otro campo que archivo, o más de un archivo.
XML_DEMASIADO_GRANDE413El XML supera los 2 MB.
XML_ENCODING_NO_SOPORTADO400El encoding no es ISO-8859-1, UTF-8, windows-1252 ni UTF-16.
XML_NO_PERMITIDO400Trae un <!DOCTYPE o un <!ENTITY.
XML_MALFORMADO400Está mal formado (el motivo en detalles[]).
XML_SIN_DTE400La raíz no es EnvioDTE ni DTE, o no trae ningún DTE.
XML_DEMASIADOS_DTE400Más de 500 documentos en el archivo.
XML_SIN_DOCUMENTOS_VALIDOS422Ningún DTE se pudo cargar.
EMPRESA_SIN_RUT409La empresa no tiene un RUT válido para revisar el receptor.
XML_NO_ENCONTRADO404El XML cargado no existe o es de otra empresa.

Importaciones con costeo

Una importación es una carpeta con una o más órdenes de compra a un proveedor extranjero: su moneda, el tipo de cambio, el FOB de cada línea y los costos para dejar la mercadería en bodega. Al recibir una orden de la carpeta, la mercadería entra al inventario con el costo de la importación. Se lee con compras:leer (GET .../compras/importaciones, GET .../importaciones/:importacionId con su costeo y GET .../importaciones/tipo-cambio?moneda=&fecha=) y se crea, edita (PATCH), descarta (DELETE, solo un borrador) y abre (POST .../abrir) con compras:escribir: con sesión, solo el admin (el emisor y el contador, 403). Cerrarla (POST .../cerrar) es solo del admin con sesión.

Qué es costo: la Ley sobre Impuesto a la Renta, art. 30, considera costo directo de las mercaderías internadas «el valor CIF, los derechos de internación, los gastos de desaduanamiento y optativamente el flete y seguros hasta las bodegas del importador». El IVA de la importación no es costo: es crédito fiscal (DL 825, art. 23 N° 1). Va en ivaDin solo como dato, y un costo con concepto: "iva" responde 400.
bash
curl -X POST "https://api.miaplicacion.cl/api/empresas/$EMPRESA/compras/importaciones" \
  -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "proveedorId": "66f0c2a1b2c3d4e5f6a7b8c9",
    "ordenIds": ["66f0c2a1b2c3d4e5f6a7b8d0"],
    "moneda": "DOLAR USA",
    "tipoCambio": { "valor": 900, "fecha": "2026-10-14" },
    "lineas": [
      { "lineaId": "66f0c2a1b2c3d4e5f6a7b8d1", "fob": 1000, "peso": 50 },
      { "lineaId": "66f0c2a1b2c3d4e5f6a7b8d2", "fob": 3000, "peso": 150 }
    ],
    "costos": [
      { "concepto": "flete", "monto": 400, "moneda": "DOLAR USA" },
      { "concepto": "seguro", "monto": 120000, "moneda": "PESO CL", "criterio": "cantidad" },
      { "concepto": "derechos", "monto": 216000, "moneda": "PESO CL" },
      { "concepto": "otros", "descripcion": "Agente de aduana", "monto": 200000, "moneda": "PESO CL", "criterio": "peso" }
    ],
    "ivaDin": { "monto": 854240, "numeroDin": "1234567890" }
  }'
  • El costo unitario de cada línea es (FOB × tipo de cambio + el prorrateo de cada costo) / la cantidad pedida, a 6 decimales. Cada costo se reparte por valor (el FOB en pesos, por defecto), cantidad o peso (exige el peso de todas las líneas). En el ejemplo, la línea de 10 unidades queda en 113.400 y la de 20 en 168.100.
  • El tipo de cambio es manual ({ "valor": 900 }) o el cargado para una fecha exacta ({ "sugerido": true, "fecha": "2026-10-14" }); sin valor cargado, 400.
  • borrador → abierta → cerrada. En borrador sus órdenes no se reciben (409 IMPORTACION_EN_BORRADOR); abrir exige el costeo completo y las órdenes emitidas. Una orden sin importación se recibe exactamente igual que antes.
  • Los costos que llegan después de recibir no reescriben el costo promedio: el detalle muestra por línea lo que entró al kardex, el costo final y la diferencia, y el cierre la deja fija.
codeHTTPCuándo
IMPORTACION_NO_ENCONTRADA404La importación no existe o es de otra empresa.
IMPORTACION_EN_BORRADOR409Recibir una orden de una importación en borrador.
IMPORTACION_INCOMPLETA409Abrir, cerrar o recibir con el costeo incompleto u órdenes pendientes (detalles[]).
IMPORTACION_NO_EDITABLE409Editar una cerrada, o la orden, el proveedor o la moneda de una abierta.
IMPORTACION_TRANSICION_INVALIDA409La acción no corresponde al estado de la importación.
IMPORTACION_CERRADA409Recibir o anular una recepción de una importación cerrada.
IMPORTACION_CONFLICTO409La importación cambió entremedio (otra edición o una recepción).
OC_EN_OTRA_IMPORTACION409La orden de compra ya está en otra importación.

Punto de venta y caja

Un punto de venta para el mesón: cajas, sesiones de caja con su arqueo y venta rápida con boleta o factura. Se está construyendo por partes: hoy existen la configuración del módulo, sus dos scopes, los puntos de venta (cajas), las sesiones de caja con su libro de movimientos y su arqueo, el precio de venta bruto opcional del ítem, la venta con sus pagos y su vuelto, las ventas en espera, el escáner, la emisión de la boleta o factura de cada venta, la devolución total de una venta y el reporte Z de la sesión, con los listados y sus CSV.

Requiere MiAplicación ERP

A una empresa sin ERP, sus rutas le responden 403 PLAN_SIN_ERP; una que lo tuvo conserva la lectura (GET) de sus datos. Ver MiAplicación API y ERP.

Opt-in por empresa

Con el módulo apagado (el estado de toda empresa hasta que un admin lo enciende) ninguna respuesta cambia.

Viene en los planes de MiAplicación ERP, con un tope de puntos de venta activos por plan. Encender el módulo exige un plan ERP que lo habilite (la contratación vigente, pagada y sin vencer, el plan asignado por la plataforma a una empresa que nunca pagó o una cortesía vigente); sin él responde 403 PLAN_SIN_POS sin escribir nada, con el ERP de entrada en planSugerido. Crear o reactivar un punto de venta con el tope alcanzado responde 409 PLAN_LIMITE_PUNTOS_VENTA (antes del 14-10-2026, 403), con el plan ERP que permite más. Un módulo ya encendido no se bloquea si la contratación ERP vence, y ningún punto de venta se desactiva si la empresa baja a un plan ERP menor. Bajar a un plan de la API deja sus datos en solo lectura.

PlanPuntos de venta activos
ERP Pyme1
ERP Negocio3
ERP Full10
ERP CorporativoSin tope
Planes de la API0 (el módulo es del ERP)
json
{
  "error": "La empresa ya tiene 1 punto de venta activo y el plan ERP Pyme permite 1 punto de venta. Desactiva uno que no uses o contrata el plan ERP Negocio (hasta 3 puntos de venta) o uno superior.",
  "code": "PLAN_LIMITE_PUNTOS_VENTA",
  "plan": {
    "clave": "erp_pyme",
    "nombre": "ERP Pyme"
  },
  "planSugerido": {
    "clave": "erp_negocio",
    "nombre": "ERP Negocio",
    "puntosVentaMax": 3
  },
  "puntosVentaMax": 1,
  "puntosVentaActivos": 1
}

Configuración del punto de venta

GET /api/empresas/:empresaId/pos/configuracion (pos:leer, cualquier rol de la empresa):

json
{
  "configuracion": {
    "id": "6707a1c2a1b2c3d4e5f60801",
    "activo": true,
    "descuentoMaximoPct": 10,
    "horasVentaEnEspera": 24,
    "tipoDtePorDefecto": 39
  },
  "plan": { "clave": "negocio", "nombre": "Negocio" },
  "puedeActivar": true,
  "puntosVentaMax": 3,
  "puntosVentaActivos": 1
}
CampoQué es
idnull si la empresa nunca guardó su configuración (son los valores por defecto).
activoEl módulo está encendido.
descuentoMaximoPctDescuento máximo por línea que el cajero puede aplicar, en porcentaje: de 0 a 100, con hasta 2 decimales. Por defecto 0, que significa sin descuentos.
horasVentaEnEsperaHoras que una venta en espera sigue vigente antes de vencer. Entero de 1 a 168; por defecto 24.
tipoDtePorDefectoEl documento con que parte cada venta: 39 (boleta, por defecto) o 41 (boleta exenta).
plan{ clave, nombre } del plan que habilita (contratación vigente, plan asignado o cortesía), o null sin uno.
puedeActivarSi la barrera del plan dejaría encender el módulo a quien pregunta. No dice nada del rol: encender es de admin.
puntosVentaMaxPuntos de venta activos que permite el plan: null = sin tope; 0 = sin un plan ERP que lo habilite.
puntosVentaActivosLos puntos de venta activos de la empresa.

PUT .../pos/configuracion es solo con sesión (solo admin; la cuenta demo compartida recibe 403). Acepta activo, descuentoMaximoPct, horasVentaEnEspera y tipoDtePorDefecto, todos opcionales (manda al menos uno). Valida todo antes de escribir y responde 400 DATOS_INVALIDOS con todos los errores juntos en detalles[]. Apagar no borra nada. Con alguna venta cuya emisión esté emitiendo o revisar, apagar responde 409 POS_EMISIONES_EN_VUELO con las ventas en detalles[] y no apaga: se espera a que terminen o un admin las resuelve (el resolver funciona aunque el módulo esté apagado). Si una emisión quedó en vuelo de todas formas, la revisión periódica del punto de venta la sigue procesando con el módulo apagado.

Puntos de venta

Cada punto de venta es una caja: un nombre, la sucursal desde la que emite y, con el inventario encendido, la bodega de la que descuenta el stock. GET .../pos/puntos-venta (pos:leer, cualquier rol; ?activo=true o false filtra) devuelve { puntosVenta, cupo }, y GET .../pos/puntos-venta/:puntoVentaId devuelve { puntoVenta }; uno de otra empresa responde 404 PUNTO_VENTA_NO_ENCONTRADO. Con el módulo apagado, 409 POS_INACTIVO.

Crear (POST, nace activo) y editar (PATCH) son solo con sesión y solo del admin: el emisor y el contador leen, y una API key, aunque tenga pos:escribir, recibe 403. No hay DELETE: un punto de venta se desactiva con { "activo": false } y se puede reactivar, pasando por el tope del plan. Una caja con una sesión de caja abierta no se desactiva: responde 409 PUNTO_VENTA_CON_SESION_ABIERTA (cierra la caja antes). Si se desactiva justo mientras alguien abre una sesión, gana una de las dos y la otra recibe su 409.

CampoReglas
nombreObligatorio al crear. Hasta 40 caracteres, único en la empresa sin distinguir mayúsculas ni espacios repetidos.
sucursalIdEl id de una sucursal activa de tu configuración de emisión; null = casa matriz.
bodegaIdEl id de una bodega activa de tu empresa; null = sin bodega.
activoSolo al editar: false desactiva, true reactiva.

Todos los errores salen juntos en detalles[] con 400 DATOS_INVALIDOS: la forma, una sucursal o bodega que no es de tu empresa (responde lo mismo que una que no existe) o está desactivada, y un nombre repetido.

Sesiones de caja y arqueo

Cada caja trabaja por sesiones: se abre con el efectivo inicial, recibe los movimientos de su libro y se cierra con el arqueo por medio de pago. Una caja tiene a lo más una sesión abierta. Con el módulo apagado, todas estas rutas responden 409 POS_INACTIVO.

QuéRuta (prefijo .../pos)Quién
AbrirPOST /puntos-venta/:puntoVentaId/sesionespos:escribir; admin y emisor
La sesión abierta de una cajaGET /puntos-venta/:puntoVentaId/sesion-abiertapos:leer; todos los roles
ListarGET /sesiones?puntoVentaId=&estado=&desde=&hasta=&formato=pos:leer; todos los roles
DetalleGET /sesiones/:sesionIdpos:leer; todos los roles
Reporte ZGET /sesiones/:sesionId/reporte?formato=pos:leer; todos los roles (con la sesión abierta, completo solo el admin)
LibroGET /sesiones/:sesionId/movimientospos:leer; todos los roles
Ingreso, retiro o gastoPOST /sesiones/:sesionId/movimientospos:escribir; admin y emisor
Anular un movimientoPOST /movimientos/:movimientoId/anularSolo con sesión; solo admin
Cerrar con arqueoPOST /sesiones/:sesionId/cerrarpos:escribir; admin y emisor

El contador solo lee. Una API key con pos:escribir opera la caja como un emisor y nunca anula un movimiento; sus escrituras cuentan en el tope de escrituras por minuto de la key.

Cierre ciego. Mientras la sesión está abierta, las lecturas de esta tabla no le entregan montos a quien no es admin (el emisor, el contador y toda API key): el detalle y la sesión abierta de la caja llegan con vista: "ciega" y en null el montoApertura, el esperado, el monto de cada fila del resumen y el total de cada emisionesPendientes; el libro, con el monto de cada movimiento en null; el listado, con el montoApertura de la sesión abierta en null. Con la sesión cerrada, todos ven todo (vista: "completa").

Abrir. POST .../puntos-venta/:puntoVentaId/sesiones con { "montoApertura": 20000, "nota": "Turno mañana" }: el efectivo con que parte la caja, en pesos enteros, 0 o más (nota es opcional). La caja tiene que estar activa: si no, 409 PUNTO_VENTA_INACTIVO. Si ya tiene una sesión abierta, 409 SESION_YA_ABIERTA con el sesionId de esa sesión; con dos aperturas simultáneas, una abre y la otra recibe ese 409. Cada caja numera sus sesiones desde 1 (numero). Un monto mayor que 0 queda en el libro como el movimiento apertura. Responde 201 { sesion }:

json
{
  "sesion": {
    "id": "6707a1c2a1b2c3d4e5f60830",
    "puntoVentaId": "6707a1c2a1b2c3d4e5f60810",
    "numero": 12,
    "estado": "abierta",
    "abiertaEn": "2026-10-10T12:00:00.000Z",
    "abiertaPor": { "usuarioId": "6707a1c2a1b2c3d4e5f60801", "apiKeyId": null },
    "montoApertura": 20000,
    "notaApertura": "Turno mañana",
    "cerradaEn": null,
    "cerradaPor": null,
    "notaCierre": null,
    "arqueo": null,
    "vista": "completa",
    "esperado": { "efectivo": 20000, "debito": 0, "credito": 0, "transferencia": 0, "otro": 0 },
    "resumen": {
      "vigentes": [{ "tipo": "apertura", "medio": "efectivo", "cantidad": 1, "monto": 20000 }],
      "anulados": []
    }
  }
}

El libro. Cada movimiento tiene un tipo, un medio (efectivo, debito, credito, transferencia u otro) y un monto en pesos enteros mayor que 0. El monto siempre es positivo; el tipo dice si suma o resta:

tipoEfectoMedioCómo nace
aperturaSumaEfectivoAl abrir, con un monto mayor que 0.
ventaSumaEl de su línea de pagoAl registrar una venta: uno por medio de pago, y el del efectivo neto del vuelto.
devolucionRestaEl del reembolsoAl devolver una venta: uno por medio del reembolso, en la sesión donde se paga.
ingresoSumaEfectivoPOST .../movimientos.
retiroRestaEfectivoPOST .../movimientos, con motivo obligatorio.
gastoRestaEfectivoPOST .../movimientos, con motivo obligatorio.

POST .../sesiones/:sesionId/movimientos acepta tipo (ingreso, retiro o gasto), monto y motivo (hasta 200 caracteres), y responde 201 { movimiento, repetido: false }:

json
{
  "movimiento": {
    "id": "6707a1c2a1b2c3d4e5f60840",
    "sesionId": "6707a1c2a1b2c3d4e5f60830",
    "puntoVentaId": "6707a1c2a1b2c3d4e5f60810",
    "tipo": "retiro",
    "medio": "efectivo",
    "monto": 50000,
    "motivo": "Depósito al banco",
    "actor": { "usuarioId": null, "apiKeyId": "6707a1c2a1b2c3d4e5f60850" },
    "ventaId": null,
    "anulado": null,
    "createdAt": "2026-10-10T15:30:00.000Z"
  },
  "repetido": false
}

Acepta la cabecera Idempotency-Key (opcional, de 1 a 128 caracteres): la misma clave con el mismo cuerpo devuelve 200 con el MISMO movimiento (repetido: true), aunque la sesión ya se haya cerrado; con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO sin registrar nada. Úsala: un reintento por un corte de red no registra dos retiros.

El libro solo se agrega: un movimiento no se edita ni se borra. Anular (POST .../movimientos/:movimientoId/anular con { "motivo": "Doble registro" }, obligatorio) es solo del admin con sesión, solo con la sesión abierta y solo para ingreso, retiro y gasto. La apertura no se anula (409 MOVIMIENTO_NO_ANULABLE: se cierra la sesión y se abre otra), y una venta se revierte con su devolución. El anulado sigue en el libro con anulado: { en, por, motivo } y deja de contar en el esperado. Anularlo otra vez responde 409 MOVIMIENTO_YA_ANULADO.

Cerrar con arqueo. POST .../sesiones/:sesionId/cerrar lleva lo que contó el cajero por medio de pago (efectivo es obligatorio; un medio que no viene se toma como 0) y una nota opcional:

json
{ "declarado": { "efectivo": 64500, "debito": 31000 }, "nota": "Faltan $500" }

Responde { sesion } cerrada, con cerradaEn, cerradaPor y su arqueo por medio de pago:

json
"arqueo": {
  "esperado": { "efectivo": 65000, "debito": 31000, "credito": 0, "transferencia": 1500, "otro": 0 },
  "declarado": { "efectivo": 64500, "debito": 31000, "credito": 0, "transferencia": 0, "otro": 0 },
  "diferencia": { "efectivo": -500, "debito": 0, "credito": 0, "transferencia": -1500, "otro": 0 }
}
  • esperado de cada medio es la suma de los movimientos no anulados de ese medio, cada uno con su signo. Se calcula del libro al cerrar (y en vivo en el detalle de una sesión abierta); no es un saldo guardado aparte, así que siempre cuadra con el libro.
  • diferencia = declarado − esperado, medio por medio: negativa es un faltante y positiva, un sobrante. Los medios nunca se mezclan en un solo número.

Concurrencia

Cada movimiento, anulación y cierre corre en una transacción que escribe la sesión, así que no pueden pisarse. Un movimiento que compite con el cierre termina de una de dos maneras: entra y el cierre lo cuenta en su esperado, o recibe 409 SESION_CAJA_CERRADA sin registrar nada. Ningún movimiento queda en una sesión cerrada. Cerrar dos veces, o registrar o anular en una sesión cerrada, también responde 409 SESION_CAJA_CERRADA. Si una sesión recibe tantas operaciones a la vez que una no logra escribirse después de sus reintentos, responde 409 SESION_CAJA_EN_CONFLICTO (o CIERRE_EN_CONFLICTO al cerrar) sin registrar nada: reintenta en unos segundos; el arqueo se recalcula.

Leer. GET .../sesiones/:sesionId devuelve { sesion } con esperado (en vivo si está abierta; el del arqueo si está cerrada) y resumen: la cantidad y el monto (sin signo) por tipo y medio, los vigentes y los anulados por separado. GET .../puntos-venta/:puntoVentaId/sesion-abierta devuelve lo mismo para la sesión abierta de la caja, o { "sesion": null }. GET .../sesiones lista de la más nueva a la más vieja ({ sesiones, total, pagina, totalPaginas }, sin el resumen; desde y hasta son días de Chile AAAA-MM-DD sobre la apertura; hasta 200 por página). GET .../sesiones/:sesionId/movimientos es el libro del más viejo al más nuevo, con los anulados marcados. Una sesión, caja o movimiento de otra empresa responde 404, igual que uno que no existe. Todos los errores de forma salen juntos en detalles[] con 400 DATOS_INVALIDOS.

Contabilidad de la caja. Las ventas del punto de venta son documentos como cualquier otro y se centralizan igual, una vez al mes. Lo que entra o sale de la caja sin una venta genera su propio asiento (origen caja_pos) si el movimiento trae categoria y la empresa tiene plan de cuentas, siempre contra la Caja de la regla de ventas: ingreso (Debe Caja / Haber la cuenta de origen), retiro (Debe la cuenta de destino / Haber Caja), pago_proveedor (tipo gasto: Debe Proveedores con el rutProveedor, obligatorio / Haber Caja) y gasto_sin_documento (tipo gasto: Debe la cuenta de gasto / Haber Caja). La cuenta sale de cuentaCodigo o de cuentasCaja de la configuración (el pago a proveedor no elige: va a Proveedores).

Un gasto con factura ya entra por el registro de compras: se registra como pago_proveedor, que solo salda la deuda con el proveedor; como gasto quedaría contado dos veces. gasto_sin_documento es solo para gastos menores sin factura. Con Compras encendido, un pago_proveedor desde la caja responde 409 PAGO_PROVEEDOR_EN_COMPRAS sin registrar nada: registra el pago en Compras → Cuentas por pagar (medio efectivo), así rebaja la factura y Proveedores no se debita dos veces. Al cerrar, la diferencia de efectivo genera su asiento: faltante (Debe cuentasCaja.faltante / Haber Caja) o sobrante (Debe Caja / Haber cuentasCaja.sobrante), en asientoArqueo de la sesión. El asiento se escribe en la misma transacción: sin categoria, sin asiento (sin_categoria); sin plan de cuentas, se registra marcado sin_plan_de_cuentas; con el período contable cerrado, 409 PERIODO_CERRADO sin registrar, anular ni cerrar; una cuenta que no sirve, 409 CUENTA_CONTABLE_INVALIDA con detalles[]. Anular el movimiento anula su asiento; a mano, 409 ASIENTO_DE_CAJA_POS. Las cifras del arqueo y del reporte Z no cambian.

El reembolso de una devolución no tiene asiento propio, a propósito: su contrapartida es la nota de crédito 61, que la centralización de ventas propias (cuando el SII la acepta) resta de Caja, Ventas e IVA. La venta del punto de venta es al contado (boleta 39 o 41, o factura 33 con formaPago: 1): entró a Caja y no deja una cuenta por cobrar que rebajar, así que un asiento del reembolso rebajaría la Caja dos veces. Los movimientos devolucion quedan sin categoria ni asiento. Si el SII rechaza la nota cuando el reembolso ya se pagó, el documento de la venta sigue vigente y el efectivo salió sin contrapartida contable hasta que se emite la nota de reemplazo: esa nota, cuando el SII la acepta, es la contrapartida. Pasados seis meses desde la venta no se emite desde el punto de venta (ya no rebaja el débito fiscal) y el ajuste lo resuelve el contador. Una devolución incierta no se reembolsa hasta resolverla.

Venta del punto de venta

POST /api/empresas/:empresaId/pos/sesiones/:sesionId/ventas (pos:escribir; admin y emisor) registra una venta cobrada en una sesión de caja abierta. No emite el DTE: la venta nace registrada con emision.estado: "pendiente" y su boleta o factura se emite después, con Emitir la venta. Pero antes de escribir nada valida el documento como lo hará la emisión (ver Errores): nunca se cobra una venta que la emisión rechazaría. La cabecera Idempotency-Key es obligatoria (de 1 a 128 caracteres, una por venta).

json
{
  "lineas": [
    { "itemId": "6707a1c2a1b2c3d4e5f60901", "cantidad": 2 },
    { "itemId": "6707a1c2a1b2c3d4e5f60902", "cantidad": 1, "descuentoPct": 10 }
  ],
  "pagos": [
    { "medio": "debito", "monto": 2000 },
    { "medio": "efectivo", "monto": 5000 }
  ],
  "nota": "Mesa 4"
}

Responde 201 { venta, repetido: false } (el primer ítem tiene precioVentaBruto 1.500; el segundo es exento, con precio 800):

json
{
  "venta": {
    "id": "6707a1c2a1b2c3d4e5f60950",
    "numero": 128,
    "estado": "registrada",
    "puntoVentaId": "6707a1c2a1b2c3d4e5f60810",
    "sesionId": "6707a1c2a1b2c3d4e5f60830",
    "tipoDte": 39,
    "bodegaId": "6707a1c2a1b2c3d4e5f60820",
    "sucursalId": null,
    "receptor": null,
    "totales": { "neto": 2521, "exento": 720, "iva": 479, "total": 3720 },
    "pagos": [{ "medio": "debito", "monto": 2000 }, { "medio": "efectivo", "monto": 5000 }],
    "vuelto": 3280,
    "emision": { "estado": "pendiente", "folio": null },
    "actor": { "usuarioId": "6707a1c2a1b2c3d4e5f60801", "apiKeyId": null },
    "nota": "Mesa 4",
    "expiraEn": null,
    "createdAt": "2026-10-10T16:05:00.000Z",
    "updatedAt": "2026-10-10T16:05:00.000Z",
    "lineas": [
      { "itemId": "6707a1c2a1b2c3d4e5f60901", "varianteId": null, "codigo": "CAF-1", "nombre": "Café", "cantidad": 2, "exento": false, "precioUnitario": 1500, "descuentoPct": null, "descuentoMonto": 0, "montoLinea": 3000 },
      { "itemId": "6707a1c2a1b2c3d4e5f60902", "varianteId": null, "codigo": null, "nombre": "Libro", "cantidad": 1, "exento": true, "precioUnitario": 800, "descuentoPct": 10, "descuentoMonto": 80, "montoLinea": 720 }
    ]
  },
  "repetido": false
}
CampoReglas
lineasDe 1 a 60. Una línea del catálogo es { itemId, varianteId?, cantidad, descuentoPct? }: el nombre, la exención y el precio salen del ítem (mandar precioUnitario, nombre o exento en ella es 400). Una línea libre, sin itemId, es { nombre, precioUnitario, cantidad, exento? } y solo la crea el admin con sesión. La cantidad es mayor que 0, con hasta 6 decimales.
descuentoPctPorcentaje de la línea, con hasta 2 decimales y a lo más el descuentoMaximoPct de la configuración (con 0, ningún descuento). Se lleva a pesos sobre round(cantidad × precio).
pagosDe 1 a 5 pagos { medio, monto }: efectivo, debito, credito, transferencia u otro, cada medio una sola vez, con el monto en pesos enteros mayor que 0 y de a lo más 10^12.
tipoDte39, 41 o 33. Sin él, el tipoDtePorDefecto de la configuración. Una factura (33) necesita al menos una línea afecta: una venta toda exenta va en boleta exenta (41).
receptor{ contactoId } o { rut, razonSocial, giro?, direccion?, comuna?, email? }. Obligatorio en la factura (33), con giro, dirección y comuna; opcional en la boleta.
ventaEnEsperaIdLa venta en espera que se cobra: queda usada.
notaHasta 500 caracteres.

Precios: los pone el servidor. El cliente no manda el precio de un ítem del catálogo.

  • Boleta (39/41): el precio unitario va con IVA. Si la variante tiene precio propio (neto), es ese con IVA; si no, el precioVentaBruto del ítem; si no lo tiene, round(precio × 1,19), y un ítem exento cobra su neto (no lleva IVA).
  • Factura (33): el precio neto, el de la variante o el del ítem.
  • Una variante con precio 0 no tiene precio propio: vale el del ítem. Una línea del catálogo que queda en $0 (un ítem sin precio cargado) es un error.
  • Las listas de precio de ventas no se aplican en el punto de venta.

Tipo de documento. Sin tipoDte va el por defecto. Una boleta (39) con todas sus líneas exentas sale como boleta exenta (41), y en la 41 una línea afecta es un error.

Totales. totales (neto, exento, iva y total) los calcula el servidor con las mismas funciones con que la emisión arma el documento: el DTE dará exactamente estos montos. En la boleta, el neto sale del bruto afecto (round(bruto / 1,19)) y el IVA es la diferencia; en la factura, el IVA es round(neto × 19 %). El montoLinea de cada línea es round(cantidad × precioUnitario) − descuentoMonto.

Pagos y vuelto. La suma de los pagos tiene que alcanzar el total. vuelto = Σ pagos − total, y sale solo del efectivo: un vuelto mayor que el efectivo pagado es un error, porque los demás medios no pueden pasarse del total. Cada medio con monto queda en el libro de la sesión como un movimiento venta (con el ventaId de la venta), y el del efectivo va neto del vuelto (en el ejemplo, 1.720): así el esperado del arqueo es lo que quedó en la caja.

Stock. Con el inventario encendido y bloquearSinStock, si el documento va a mover stock (empresa en producción y no demo), la venta revisa la bodega de la caja antes de registrar, con la misma lectura de la emisión. Si falta, responde 409 STOCK_INSUFICIENTE con detalles[] y no registra nada. Es una revisión previa: la reserva del stock la hace la emisión antes de tomar el folio, y entre las dos otra venta puede llevarse el último. Si pasa, la emisión responde 409 STOCK_INSUFICIENTE sin tomar folio y la venta queda registrada con su emisión en error.

Idempotencia. La misma clave con el mismo cuerpo devuelve 200 con la MISMA venta (repetido: true), aunque la sesión ya se haya cerrado; con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO. Dos pedidos con la misma clave a la vez registran una sola venta y un solo juego de movimientos.

Errores. Todos salen juntos en detalles[] con 400 DATOS_INVALIDOS: la forma, un ítem o una variante de otra empresa o desactivados, el descuento, el tipo, el receptor (también un contacto de otra empresa), los pagos y la falta de Idempotency-Key. Con la venta ya calculada, y todavía sin escribir nada, el documento pasa por la misma validación que POST /dte hace antes del folio (con la UF del día): la regla de las 135 UF de la boleta (sobre ese monto exige el RUT y la razón social del receptor), el receptor completo de la factura y la sucursal de la caja. Esos errores salen juntos en otro 400 DATOS_INVALIDOS. Con la empresa en producción, una API key de certificación (mk_cert_) recibe 409 POS_FUERA_DE_PRODUCCION sin registrar nada; si la empresa no tiene configurada la emisión con el SII, 422 POS_SIN_EMISION_CONFIGURADA (la venta no se podría emitir); si no se puede leer esa configuración, 503 CONFIG_EMISION_NO_DISPONIBLE. La venta guarda la bodega y la sucursal de la caja con que se validó (bodegaId y sucursalId, null si la caja no tiene): la emisión usa esas, aunque la caja cambie después.

json
{
  "error": "Datos inválidos",
  "code": "DATOS_INVALIDOS",
  "detalles": [
    "lineas[1].descuentoPct: 15 % supera el descuento máximo de la configuración (10 %).",
    "pagos[1].medio: tiene que ser uno de efectivo, debito, credito, transferencia, otro."
  ]
}

Los pagos no cuadran con el total. Cuando la suma de los pagos no alcanza el total que calcula el servidor, o el vuelto es mayor que el efectivo pagado, el mismo 400 trae además, en la raíz, motivo: "POS_PAGOS_NO_CUADRAN" y los totales del servidor. Los mensajes de detalles[] son los de siempre. Es el caso típico de un precio que cambió en el catálogo mientras la caja tenía el carro armado: la caja compara sus totales con los del servidor y vuelve a cobrar. Detecta el caso por motivo, no por el texto de detalles[], que puede cambiar. motivo puede venir junto con otros errores del mismo pedido: detalles[] sigue siendo la lista completa de los errores, y motivo solo avisa que uno de ellos es el de los pagos. Un 400 sin este caso no trae motivo ni totales.

json
{
  "error": "Datos inválidos",
  "code": "DATOS_INVALIDOS",
  "detalles": ["pagos: suman $1.000 y el total de la venta es $1.500: faltan $500."],
  "motivo": "POS_PAGOS_NO_CUADRAN",
  "totales": { "neto": 1261, "exento": 0, "iva": 239, "total": 1500 }
}

Una línea libre de un emisor o de una API key responde 403 POS_LINEA_LIBRE_SOLO_ADMIN. Una sesión cerrada, 409 SESION_CAJA_CERRADA; una de otra empresa, 404. Una caja desactivada con su sesión abierta sigue vendiendo hasta cerrarla.

Leer. GET .../pos/ventas (pos:leer, todos los roles) lista de la más nueva a la más vieja, sin las líneas (trae cantidadLineas). Sus filtros y su CSV están en Reporte Z y listados. GET .../pos/ventas/:ventaId devuelve { venta } completa. Una venta de otra empresa responde 404 VENTA_NO_ENCONTRADA.

Emitir la venta

POST /api/empresas/:empresaId/pos/ventas/:ventaId/emitir (pos:escribir y dte:emitir; admin y emisor, nunca el contador) emite la boleta (39/41) o la factura (33) de una venta ya registrada, por el mismo camino de POST /dte: las mismas validaciones antes del folio, el mismo inventario y el mismo tope de emisiones por minuto de la empresa (60 por defecto). No lleva cuerpo: el documento sale entero de la venta.

Dos pasos. La caja registra la venta (el dinero y sus movimientos quedan en el libro, en una transacción) y enseguida pide su emisión. Si la emisión falla, la venta sigue registrada y su emisión queda en error, reintentable: el dinero ya se recibió. El panel espera la emisión con un aviso de unos 20 segundos; si tarda más, la emisión sigue en el servidor y la caja la consulta con GET .../pos/ventas/:ventaId.

  • Los ítems de la venta con su precio y su descuento (brutos en la boleta, netos en la factura), su código (CdgItem) y, para el inventario, el ítem y la variante: el DTE da exactamente los totales de la venta.
  • El receptor de la venta (en la factura, obligatorio y completo).
  • medioPago según los pagos: efectivo, pago_electronico (débito y crédito) o transferencia; con varios medios, otro.
  • La factura va al contado (formaPago: 1). La sucursal y la bodega son las guardadas en la venta al registrarla (las que se validaron), no las de la caja al emitir.
  • El documento guarda de qué venta salió (origenComercial: { clase: "venta_pos", ventaPosId, numero }); no entra al XML ni al PDF.
Estado (venta.emision.estado)Qué significa
pendienteRegistrada, sin emitir.
emitiendoSe está emitiendo ahora. Otro pedido a la vez recibe 409 POS_EMISION_EN_CURSO.
emitidaTiene su documento (emision.folio, emision.tipoDte y emision.emitidaId).
errorNo hubo documento (validación, stock, sin folios, el SII rechazó la subida): se puede volver a emitir. emision.ultimoError dice por qué.
inciertaEl envío al SII quedó sin respuesta y el SII puede tener el documento. No se vuelve a emitir: se consulta por folio.
rechazadaEl SII rechazó el documento: la venta se puede volver a emitir (o reemitir ese documento, no las dos).
revisarLa emisión se cortó a medias (más de 15 minutos emitiendo) sin registro local: la resuelve un admin.

emision trae además, solo si existen, tipoDte, emitidaId, rechazadaId, ultimoError, intentos, en (el último cambio) y resolucion. Responde 201 { venta, dte }, con dte igual a la respuesta de POST /dte. Cualquier otro resultado responde el status y el cuerpo de la emisión, más venta con su estado: un 400 de validación, un 409 sin folios o STOCK_INSUFICIENTE, un 502 de envío incierto.

json
{
  "venta": {
    "id": "6707a1c2a1b2c3d4e5f60950",
    "numero": 128,
    "estado": "registrada",
    "tipoDte": 39,
    "totales": { "neto": 2521, "exento": 720, "iva": 479, "total": 3720 },
    "emision": { "estado": "emitida", "folio": 1043, "tipoDte": 39, "emitidaId": "6707a1c2a1b2c3d4e5f60990", "intentos": 1, "en": "2026-10-10T16:05:02.000Z" }
  },
  "dte": { "success": true, "emitidaId": "6707a1c2a1b2c3d4e5f60990", "tipoDTE": 39, "folio": 1043, "total": 3720 }
}

Una emisión a la vez. La toma de la venta es atómica: con dos pedidos a la vez, uno emite y el otro recibe 409 POS_EMISION_EN_CURSO (o POS_VENTA_YA_EMITIDA), con un solo folio.

Stock. Con el inventario encendido, la emisión reserva el stock en la bodega de la caja antes de tomar el folio. Con bloquearSinStock, si otra venta se llevó el último entre el registro y la emisión, responde 409 STOCK_INSUFICIENTE sin folio y la emisión queda en error: se vuelve a emitir con el stock repuesto, o se devuelve la venta.

Ambiente. La venta sale en el ambiente de la empresa: el punto de venta no acepta ambiente. Con la empresa en producción, una API key de certificación (mk_cert_) recibe 409 POS_FUERA_DE_PRODUCCION al registrar y al emitir, sin folio. Con la empresa en certificación o en modo demo, la venta se emite en certificación (sirve para probar).

Rechazo del SII. Con el veredicto RECHAZADO, la emisión pasa a rechazada (con rechazadaId) y la venta se puede volver a emitir: el nuevo documento toma un folio (el rechazado vuelve al pool, salvo el código 101, folio ya usado en el SII, que no vuelve nunca). Reemitir o volver a emitir, nunca las dos: si se reemite el documento rechazado (POST .../sii-emision/documentos/:id/reemitir), volver a emitir la venta es 409 POS_EMISION_REEMITIDA; si se volvió a emitir la venta, reemitir el rechazado es 409 CONVERSION_REEMPLAZADA, sin tocar su folio.

Revisión. Una emisión que queda emitiendo más de 15 minutos (el proceso se cortó) la revisa el reconciliador, cada 5 minutos: si encuentra su documento, la cierra con él; si no, la deja en revisar con una alerta y nunca la libera sola, porque el SII puede tener el documento. El mismo reconciliador mira las incierta: si su documento (el de emitidaId o, sin él, el que salió de la venta desde que empezó la emisión) terminó ACEPTADO o ACEPTADO_REPAROS, la emisión pasa a emitida; si terminó RECHAZADO, a rechazada; si sigue en proceso, queda incierta pero ligada a ese documento. Una revisar, o una incierta sin documento ligado, la resuelve un admin con sesión, con POST .../pos/ventas/:ventaId/emision/resolver (solo con sesión; funciona aunque el módulo esté apagado):

json
{ "accion": "ligar", "emitidaId": "6707a1c2a1b2c3d4e5f60990", "motivo": "El SII tiene la boleta folio 1043" }
  • ligar (una revisar, o una incierta sin emitidaId): el documento existe. Tiene que ser de la empresa (404 DTE_NO_ENCONTRADO), del tipo de la venta y emitido desde ella (409 DTE_DE_OTRA_VENTA), posterior al inicio de la emisión (409 DTE_ANTERIOR_A_LA_EMISION) y, con la empresa en producción, de producción (409 POS_FUERA_DE_PRODUCCION).
  • liberar (solo una revisar, sin emitidaId): el SII no lo tiene. La emisión vuelve a error y la venta se puede emitir. Solo una hora después del inicio de la emisión (antes, 409 POS_EMISION_LIBERACION_PREMATURA con minutosRestantes) y si no hay un documento local de esa emisión (409 POS_EMISION_CON_DTE con su emitidaId: se liga, no se libera).

Responde { venta, accion, resultado } (resultado: liberada, emitida, incierta o rechazada) y la decisión queda en emision.resolucion. Una emisión que no está en revisión: 409 POS_EMISION_NO_EN_REVISION. motivo es obligatorio (hasta 500 caracteres); los errores del cuerpo salen juntos en un 400 DATOS_INVALIDOS.

Cierre de caja. Con una venta de la sesión emitiendo, el cierre responde 409 VENTAS_EN_VUELO con detalles[] (y ventas): se espera a que termine. Una venta pendiente, error, rechazada, incierta o revisar no bloquea el cierre: la sesión las lista en emisionesPendientes ({ id, numero, tipoDte, total, estado, folio, emitidaId }; emitidaId es el DTE ya ligado, o null: una incierta con documento no se resuelve). Una venta de una sesión ya cerrada se sigue emitiendo.

Errores antes del folio: 404 VENTA_NO_ENCONTRADA; 409 POS_VENTA_NO_EMITIBLE (la venta está anulada), POS_EMISION_EN_CURSO, POS_EMISION_EN_REVISION, POS_VENTA_YA_EMITIDA, POS_EMISION_REEMITIDA, POS_EMISION_CON_DTE o POS_FUERA_DE_PRODUCCION; 503 CONFIG_EMISION_NO_DISPONIBLE. Después, los de POST /dte.

Devolver una venta

POST /api/empresas/:empresaId/pos/ventas/:ventaId/devolver (solo con sesión y solo el admin: una devolución saca dinero de la caja y emite una nota de crédito, así que en v1 el emisor no devuelve y una API key nunca llega) devuelve la venta completa: emite la nota de crédito que anula su documento y registra el reembolso en una sesión de caja abierta. Para devolver solo una parte, ver Devolver una parte de una venta; después de una devolución parcial, esta misma ruta devuelve el saldo (lo que queda) con una nota CodRef 3, nunca con la que anula. Lleva Idempotency-Key (obligatoria) y el mismo tope de emisiones por minuto de la empresa que POST /dte.

json
{
  "sesionId": "6707a1c2a1b2c3d4e5f60700",
  "reembolso": [{ "medio": "efectivo", "monto": 2000 }, { "medio": "debito", "monto": 1720 }],
  "motivo": "Producto fallado"
}
  • sesionId: la sesión abierta donde se paga el reembolso. Puede ser otra caja u otro día: la caja de hoy, no necesariamente la de la venta.
  • reembolso: un monto por medio de pago (efectivo, debito, credito, transferencia u otro), sin repetir medios, que suma exactamente el total de la venta. Cada línea es un movimiento devolucion en esa sesión: resta en el esperado de su medio.
  • motivo: obligatorio, hasta 90 caracteres. Va en la referencia de la nota de crédito (RazonRef).

Los errores del cuerpo salen juntos en un 400 DATOS_INVALIDOS. La misma clave con el mismo cuerpo responde 200 con la venta como está (repetido: true); con otro cuerpo, 409 IDEMPOTENCIA_CONFLICTO. Una devolución en error se vuelve a pedir con la misma clave o con otra.

venta.emision.estadoDevolución
emitidaNota de crédito 61 CodRef 1 sobre su documento, por el mismo camino de POST /dte/:id/anular: sus cortes antes del folio, la protección contra la doble anulación y el inventario (la nota repone el stock con las reglas de la 61 CodRef 1). Con la nota emitida, el reembolso y la venta anulada se escriben en una transacción.
pendiente, error o rechazadaNo hay un documento válido: solo el reembolso, sin nota, sin folio y sin stock (la emisión nunca ocurrió).
emitiendo, revisar o incierta409 POS_EMISION_EN_VUELO (trae estado): primero se resuelve la emisión.

Una venta anulada no se emite (409 POS_VENTA_NO_EMITIBLE) ni se devuelve otra vez (409 POS_VENTA_YA_ANULADA). Emitir y devolver a la vez una venta sin documento nunca terminan las dos: gana una. Si el SII ya rechazó el documento de una venta emitida, no se anula: la venta vuelve a rechazada y la devolución es solo el reembolso. Responde 201:

json
{
  "venta": {
    "id": "6707a1c2a1b2c3d4e5f60950",
    "numero": 128,
    "estado": "anulada",
    "totales": { "neto": 2521, "exento": 720, "iva": 479, "total": 3720 },
    "devolucion": {
      "estado": "completada",
      "sinDocumento": false,
      "motivo": "Producto fallado",
      "sesionId": "6707a1c2a1b2c3d4e5f60700",
      "reembolso": [{ "medio": "efectivo", "monto": 2000 }, { "medio": "debito", "monto": 1720 }],
      "ncEmitidaId": "6707a1c2a1b2c3d4e5f60995",
      "ncTipoDte": 61,
      "folio": 311,
      "ncRechazadaEn": null,
      "intentos": 1,
      "ultimoError": null,
      "reclamadaEn": "2026-10-10T18:20:01.000Z",
      "en": "2026-10-10T18:20:03.000Z",
      "completadaEn": "2026-10-10T18:20:03.000Z",
      "solicitadaPor": { "usuarioId": "6707a1c2a1b2c3d4e5f60010", "apiKeyId": null },
      "por": { "usuarioId": "6707a1c2a1b2c3d4e5f60010", "apiKeyId": null },
      "resolucion": null,
      "ncRechazoMotivo": null,
      "notasRechazadas": [],
      "reemplazo": null
    }
  },
  "notaCredito": { "emitidaId": "6707a1c2a1b2c3d4e5f60995", "tipoDte": 61, "folio": 311, "existente": false },
  "repetido": false
}

(Abreviado: venta es la venta completa.) notaCredito es null en una devolución sin documento, y trae existente: true cuando el documento ya estaba anulado por fuera. La devolución nunca expone el token de su reclamo ni sus claves de idempotencia. ncRechazoMotivo, notasRechazadas y reemplazo son de la nota de reemplazo (ver Nota de reemplazo); vienen siempre, también en cada parcial.

Estado (venta.devolucion.estado)Qué significa
anulandoSe está emitiendo la nota de crédito. Otro pedido recibe 409 POS_DEVOLUCION_EN_CURSO.
nc_emitidaLa nota existe y falta el reembolso (la sesión se cerró entremedio).
completadaNota y reembolso registrados; la venta está anulada.
inciertaEl SII puede tener la nota: su envío quedó sin respuesta, o el SII la recibió y su registro local falló (el folio queda en devolucion.folio). No hay reembolso automático: la resuelve un admin.
errorNo hubo nota (un corte antes del folio, sin folios, otra anulación en curso), o el SII rechazó la nota antes del reembolso: se puede volver a pedir. ultimoError dice por qué. Un registro local fallido nunca queda en error: queda incierta.

devolucion es null mientras nadie la pide. Nota emitida, reembolso pendiente. Si la sesión se cerró entre la nota y el reembolso, la respuesta es 409 POS_DEVOLUCION_REEMBOLSO_PENDIENTE (con causa, venta y notaCredito) y la devolución queda nc_emitida. El reembolso se registra en cualquier sesión abierta con POST .../pos/ventas/:ventaId/devolucion/reembolsar (admin con sesión, Idempotency-Key obligatoria):

json
{ "sesionId": "6707a1c2a1b2c3d4e5f60701", "reembolso": [{ "medio": "efectivo", "monto": 3720 }] }

Sin reembolso, va el que se pidió al devolver. Responde 201 { venta, notaCredito, repetido: false }; la misma clave y el mismo cuerpo, 200 con repetido: true. Una devolución que no está nc_emitida responde 409 POS_DEVOLUCION_NO_PENDIENTE; una ya completada, 409 POS_VENTA_YA_ANULADA. Si el SII rechazó la nota mientras tanto, no se reembolsa: 409 NC_RECHAZADA y la devolución vuelve a error (una nota rechazada no anuló nada; al pedirla de nuevo sale otra).

Nota rechazada después de pagar. Si el SII rechaza la nota de una devolución ya completada, la devolución no cambia ni se toca el dinero: queda la marca devolucion.ncRechazadaEn, lo que dijo el SII en devolucion.ncRechazoMotivo y una alerta. El documento de la venta sigue vigente: se corrige con la nota de reemplazo.

Ya anulada por fuera. Si el documento ya tenía su nota de crédito (alguien lo anuló desde Emisión), no se emite otra ni se toma otro folio: la devolución toma esa nota (notaCredito.existente: true) y sigue con el reembolso. Si esa nota quedó con el envío incierto, la devolución queda incierta.

Nota incierta. Con un envío incierto (502), un error interno después de pedir la nota, o una nota que el SII recibió y cuyo registro local falló (la anulación responde un 422 que no lo dice; la devolución lo sabe y guarda el folio y el trackid en devolucion.folio y devolucion.ultimoError), la devolución queda incierta, la venta sigue registrada y no hay reembolso. Pedirla otra vez es 409 POS_DEVOLUCION_EN_CURSO: un segundo intento sacaría otra nota. Cada devolución incierta deja una alerta para la plataforma. La respuesta trae el status y el cuerpo de la anulación, más venta (lo mismo con cualquier otro resultado que no es 201). La resuelve un admin con sesión, con POST .../pos/ventas/:ventaId/devolucion/resolver (funciona aunque el módulo esté apagado):

json
{ "accion": "ligar", "ncEmitidaId": "6707a1c2a1b2c3d4e5f60995", "motivo": "El SII tiene la nota folio 311" }
  • ligar: la nota existe. Tiene que ser de la empresa (404 NC_NO_ENCONTRADA), la nota CodRef 1 que anula el documento de la venta, en su ambiente (409 NC_DE_OTRO_DOCUMENTO), y no rechazada (409 NC_RECHAZADA). La devolución pasa a nc_emitida: después se registra el reembolso. Con un registro local fallido no hay nota que ligar: responde 404 NC_NO_ENCONTRADA mientras nadie reconstruya el registro local de esa nota.
  • liberar: el SII no tiene ninguna nota. Con una nota local vigente que anula el documento, 409 POS_DEVOLUCION_CON_NC con su ncEmitidaId (se liga, no se libera); con el folio de una nota que el SII recibió y sin su registro local, 409 POS_DEVOLUCION_NC_SIN_REGISTRO con folio (liberar reabriría el reintento y saldría una segunda nota). Lo mismo si la devolución no tiene folio pero la anulación se cortó a medias: la reserva de anulación del documento quedó tomada desde que empezó la devolución y nunca se soltó (la respuesta trae folio: null y reserva: true). Hay que revisar el SII y el log por el folio de la nota. Antes de una hora desde que empezó la devolución, 409 POS_DEVOLUCION_LIBERACION_PREMATURA con minutosRestantes. Vuelve a error: la venta se puede devolver de nuevo.

También resuelve una devolución que quedó anulando más de 15 minutos (el proceso se cortó). Responde { venta, accion, resultado } (resultado: nc_emitida o liberada) y la decisión queda en devolucion.resolucion. Fuera de esos casos, 409 POS_DEVOLUCION_NO_EN_REVISION. motivo es obligatorio (hasta 500 caracteres); los errores del cuerpo salen juntos en un 400 DATOS_INVALIDOS.

Cierre de caja. Mientras se emite la nota de una devolución (anulando, hasta 15 minutos), el cierre de la sesión donde se paga responde 409 VENTAS_EN_VUELO, con la venta en ventas y operacion: "devolucion". El reembolso entra al libro solo con la sesión abierta: si se cierra igual, la devolución queda nc_emitida.

Errores antes de la nota: 400 DATOS_INVALIDOS; 403 (no es admin); 404 VENTA_NO_ENCONTRADA o SESION_NO_ENCONTRADA; 409 SESION_CAJA_CERRADA, IDEMPOTENCIA_CONFLICTO, POS_VENTA_YA_ANULADA, POS_DEVOLUCION_EN_CURSO, POS_EMISION_EN_VUELO, POS_DEVOLUCION_CON_DOCUMENTO (una venta sin documento emitido que sí lo tiene: un rechazado ya reemitido o un documento de un intento anterior) o POS_DEVOLUCION_SIN_DTE. Después, los de POST /dte/:id/anular.

Devolver una parte de una venta

POST /api/empresas/:empresaId/pos/ventas/:ventaId/devoluciones (solo con sesión y solo el admin, como la total; Idempotency-Key obligatoria y el mismo tope de emisiones por minuto que POST /dte) devuelve PARTE de una venta emitida: emite una nota de crédito 61 con CodRef 3 («corrige montos») sobre el documento de la venta, por el mismo camino de POST /dte, y registra el reembolso en una sesión de caja abierta.

json
{
  "sesionId": "6707a1c2a1b2c3d4e5f60700",
  "lineas": [{ "indice": 0, "cantidad": 1 }, { "indice": 1, "cantidad": 1 }],
  "reembolso": [{ "medio": "efectivo", "monto": 1000 }, { "medio": "debito", "monto": 1095 }],
  "motivo": "Cliente devuelve una parte"
}
  • lineas: una por línea devuelta. indice es la posición de la línea en venta.lineas (desde 0) y cantidad lo que se devuelve (mayor que 0, hasta 6 decimales). El tope es lo vendido menos lo devuelto por las parciales en curso o completadas (lineas[].cantidadDevuelta de la venta).
  • El monto de cada línea es su parte del montoLinea de la venta: devolver una línea entera, en una o en varias veces, suma exacto lo que costó. El reembolso suma EXACTAMENTE lo que el cliente pagó por lo devuelto: en una boleta, la suma de esas partes (brutas); en una factura, su neto más el IVA (round(neto × 19 %)) más lo exento, medido como diferencia sobre lo ya devuelto. Devolver todo, en varias veces, suma exacto el total de la venta.
  • La nota viaja con precios netos (en una boleta, el bruto de cada línea se lleva a neto con la misma aritmética de la anulación). El IVA de la nota lo calcula la emisión sobre su neto, así que su total puede diferir en $1 del reembolso cuando un precio bruto no tiene un neto entero exacto (por ejemplo $1.500: neto $1.261 e IVA $240).
  • El receptor de la nota es el del documento; en una boleta al público sin RUT, el genérico 66666666-6 («Consumidor final»), la misma regla de la anulación. Con el inventario encendido, la nota lleva inventario.devolucion y repone exactamente lo devuelto.
  • Plazo: dentro de los seis meses desde la venta (DL 825, art. 21 N° 2 y art. 70: pasado ese plazo el IVA de lo restituido no se rebaja del débito). Fuera de plazo es un error más de detalles[].
  • Devolver la venta entera sin parciales previas no es una parcial: es POST .../devolver (la nota CodRef 1 que anula el documento).

Todo se valida antes del folio y sale junto en un 400 DATOS_INVALIDOS: la forma del cuerpo, las líneas y el tope, el plazo, la suma del reembolso, el motivo (hasta 90 caracteres) y lo que POST /dte le diría a la nota (con el prefijo nota de crédito:). Responde 201 { venta, devolucion, notaCredito, repetido: false }: devolucion es la parcial (id, estado, saldo, lineas, total, sesionId, reembolso, la nota y las fechas). Una venta con parciales trae devolucionesParciales[] y lineas[].cantidadDevuelta; sin parciales queda idéntica a la de antes. Con todo devuelto, la venta pasa a anulada.

Una sola devolución en curso por venta: mientras una parcial emite su nota, espera su reembolso o quedó incierta, otra parcial (o la total) es 409 POS_DEVOLUCION_EN_CURSO con devolucionId; dos pedidos a la vez nunca pasan de lo vendido. Después de parciales, POST .../devolver devuelve el saldo con una 61 CodRef 3 (devolucion.saldo: true) y su reembolso suma lo que queda, no el total de la venta: la CodRef 1 anula el documento completo y volvería a acreditar lo ya devuelto. La misma clave y el mismo cuerpo devuelven la venta como está (200, repetido: true), salvo una parcial en error, que se vuelve a intentar.

Con la nota emitida y la sesión cerrada entremedio, 409 POS_DEVOLUCION_REEMBOLSO_PENDIENTE: la paga POST .../pos/ventas/:ventaId/devoluciones/:devolucionId/reembolsar ({ sesionId, reembolso? } con su Idempotency-Key; si el SII rechazó la nota, 409 NC_RECHAZADA y la parcial vuelve a error). Con un envío incierto, un error interno después del folio o un registro local fallido, queda incierta, sin reembolso y con una alerta; la resuelve un admin con POST .../pos/ventas/:ventaId/devoluciones/:devolucionId/resolver (ligar a la 61 CodRef 3 de esta venta, o liberar recién una hora después y sin una nota local ni un folio sin registro). Nunca se libera sola. Reembolsar y resolver funcionan con el módulo apagado. Si el SII rechaza la nota de una parcial ya completada, la parcial queda con ncRechazadaEn y una alerta (el estado y el reembolso no cambian) y se corrige con la nota de reemplazo.

Errores antes de la nota: los de la total, más POS_DEVOLUCION_PARCIAL_SIN_DTE (la venta no tiene su documento emitido), POS_DEVOLUCION_DTE_RECHAZADO, POS_DEVOLUCION_DTE_INCIERTO, POS_DEVOLUCION_DOCUMENTO_ANULADO, POS_DEVOLUCION_OTRO_AMBIENTE y, al reembolsar o resolver, POS_DEVOLUCION_NO_ENCONTRADA (404). Una venta con parciales no se vuelve a emitir. En el reporte Z cada parcial pagada en la sesión es una fila de devoluciones.detalle con parcial: true, devolucionId y su total (lo reembolsado), y entra a la cuadratura.

Nota de reemplazo

Si el SII rechaza la nota de crédito de una devolución (total o parcial) después de pagar el reembolso, la devolución sigue completada y el dinero no se toca: queda la marca ncRechazadaEn, lo que dijo el SII en ncRechazoMotivo (estadoSobre, glosa y detalleRepRech, tal como quedó en la nota) y una alerta para la empresa y la plataforma (el gancho del veredicto o, si no corrió, el reconciliador del punto de venta, que revisa las totales y las parciales). El documento de la venta sigue vigente: se corrige emitiendo una nota de reemplazo, una 61 nueva igual a la rechazada, sin volver a pagar el reembolso.

DevoluciónRuta
TotalPOST /api/empresas/:empresaId/pos/ventas/:ventaId/devolucion/nota-reemplazo
ParcialPOST /api/empresas/:empresaId/pos/ventas/:ventaId/devoluciones/:devolucionId/nota-reemplazo

Solo con sesión y solo el admin, como devolver; con el módulo encendido (si no, 409 POS_INACTIVO), el mismo tope de emisiones por minuto que POST /dte e Idempotency-Key obligatoria. El cuerpo va vacío ({}): la nota replica la rechazada. La total sale por el mismo camino de POST /dte/:id/anular (la 61 CodRef 1 sobre el documento de la venta); la parcial, por el de POST /dte (la 61 CodRef 3 con las mismas líneas, montos y motivo, validada antes del folio como al devolver). La nota lleva la misma instrucción de inventario que la rechazada: el rechazo ya revirtió la reposición de la primera, así que el stock queda repuesto una sola vez en total. No hay movimiento de caja ni asiento: el reembolso ya se pagó.

Antes del folio, sin emitir nada ni consumir folio:

  • La devolución tiene que estar completada y con su nota vigente rechazada por el SII. Si no, 409 POS_NC_NO_RECHAZADA (con estado o estadoSii): sin devolución, no completada, sin nota (una venta sin documento solo se reembolsa) o con la nota aceptada («la devolución ya está corregida y no se emite otra»).
  • Ningún reemplazo en curso: 409 POS_NC_REEMPLAZO_EN_CURSO. Si un pedido se está emitiendo o su envío quedó incierto, trae estado (emitiendo o incierta), folio (el de esa nota, o null) y atascado: true si quedó emitiendo más de 15 minutos sin registrar su resultado y sin ninguna nota registrada localmente desde ese pedido (el proceso se cortó y el SII pudo recibirla: el mensaje pide revisar en el SII si tiene una nota sobre el documento de la venta antes de seguir; no se suelta solo), false en los demás casos. Si la nota de reemplazo todavía no tiene veredicto del SII, trae estadoSii. Si la devolución cambió mientras se pedía (otro pedido ganó el reclamo), trae solo estado (el del último pedido, o null).
  • El plazo del IVA: pasados seis meses desde la venta (la entrega, en fecha de Chile; el último día cuenta), 422 POS_NC_FUERA_DE_PLAZO_IVA con fechaVenta, plazoHasta y notaRechazada. La nota sigue siendo obligatoria (art. 57 del DL 825), pero ya no rebaja el débito fiscal (art. 21 N° 2 y art. 70 inc. 2° del DL 825, seis meses desde la Ley 21.398): no se emite desde el punto de venta y la resuelve el contador.
  • El documento de la venta, aceptado (o aceptado con reparos) por el SII: si no, 409 POS_DOCUMENTO_VENTA_NO_ACEPTADO con estadoSii, tipoDte, folio y notaRechazada. Una nota sobre un documento que el SII no recibió o no aceptó vuelve a ser rechazada.
  • En las dos: 400 DATOS_INVALIDOS sin Idempotency-Key o con un cuerpo que no está vacío, 404 VENTA_NO_ENCONTRADA y 409 POS_DEVOLUCION_SIN_DTE (el documento de la venta no está registrado). En la parcial, además, 404 POS_DEVOLUCION_NO_ENCONTRADA, 409 POS_DEVOLUCION_DOCUMENTO_ANULADO (el documento ya tiene una nota que lo anula entero), 409 POS_DEVOLUCION_OTRO_AMBIENTE y los 400 DATOS_INVALIDOS de la nota (con el prefijo nota de crédito:).

Responde 201 (abreviado: venta es la venta completa; en la parcial viene además devolucion, la parcial como quedó):

json
{
  "venta": {
    "id": "6707a1c2a1b2c3d4e5f60950",
    "numero": 128,
    "estado": "anulada",
    "devolucion": {
      "estado": "completada",
      "ncEmitidaId": "6707a1c2a1b2c3d4e5f60996",
      "ncTipoDte": 61,
      "folio": 311,
      "ncRechazadaEn": null,
      "ncRechazoMotivo": null,
      "notasRechazadas": [
        {
          "ncEmitidaId": "6707a1c2a1b2c3d4e5f60995",
          "ncTipoDte": 61,
          "folio": 311,
          "rechazadaEn": "2026-10-11T09:02:00.000Z",
          "motivoRechazo": {
            "estadoSobre": "EPR",
            "glosa": "Envío procesado",
            "detalleRepRech": [{ "tipo": 61, "folio": 311, "estado": "RCH", "error": [{ "codigo": "REF-3-750", "descripcion": "Documento de referencia no recibido" }] }]
          },
          "reemplazadaEn": "2026-10-12T15:40:02.000Z"
        }
      ],
      "reemplazo": {
        "estado": "emitida",
        "intentos": 1,
        "reclamadaEn": "2026-10-12T15:40:00.000Z",
        "en": "2026-10-12T15:40:02.000Z",
        "ncEmitidaId": "6707a1c2a1b2c3d4e5f60996",
        "folio": 311,
        "ultimoError": null,
        "solicitadoPor": { "usuarioId": "6707a1c2a1b2c3d4e5f60010", "apiKeyId": null }
      }
    }
  },
  "notaCredito": { "emitidaId": "6707a1c2a1b2c3d4e5f60996", "tipoDte": 61, "folio": 311, "existente": false },
  "notaRechazada": {
    "emitidaId": "6707a1c2a1b2c3d4e5f60995",
    "tipoDte": 61,
    "folio": 311,
    "rechazadaEn": "2026-10-11T09:02:00.000Z",
    "motivoRechazo": {
      "estadoSobre": "EPR",
      "glosa": "Envío procesado",
      "detalleRepRech": [{ "tipo": 61, "folio": 311, "estado": "RCH", "error": [{ "codigo": "REF-3-750", "descripcion": "Documento de referencia no recibido" }] }]
    }
  },
  "repetido": false
}

La devolución pasa a apuntar a la nota nueva (ncEmitidaId, folio), la rechazada queda en notasRechazadas[] con rechazadaEn, motivoRechazo y reemplazadaEn, y se borran ncRechazadaEn y ncRechazoMotivo. La nota nueva puede llevar el mismo folio que la rechazada: un folio rechazado vuelve al pool y se usa primero. reemplazo es el último pedido (emitiendo, emitida, incierta o error, con intentos, folio, ultimoError y quién lo pidió) y nunca expone su token ni sus claves. notaCredito.existente: true si se ligó una nota que ya existía (alguien reemitió la rechazada desde Emisión): no sale otra. La misma clave devuelve la devolución como está (200, repetido: true), con notaCredito en la nota vigente o en null si la vigente sigue rechazada (una clave de un pedido que terminó sin nota). Hay dos excepciones: un reemplazo en error con esa clave se vuelve a intentar, y con un reemplazo emitiendo o incierta la clave no cuenta: responde lo mismo que sin ella (el 409 POS_NC_REEMPLAZO_EN_CURSO o, si apareció su nota, el 201 que la liga), nunca un 200.

Nunca dos notas. El pedido se reclama de forma atómica sobre la devolución: de dos pedidos a la vez sale una nota y el otro recibe 409 POS_NC_REEMPLAZO_EN_CURSO. Si la emisión termina sin nota (un corte antes del folio, sin folios), la respuesta trae el status y el cuerpo de la emisión más venta y notaRechazada (y devolucion en la parcial); el reemplazo queda en error y se puede pedir de nuevo. Con el envío incierto y sin la nota registrada, reemplazo.estado queda incierta con una alerta, y otro pedido es 409 hasta que aparezca su registro local (entonces se liga); si no aparece, se revisa a mano en el SII por ese folio. Lo mismo con un pedido que quedó emitiendo más de 15 minutos (atascado: true). Si la nota sale pero la devolución cambió mientras tanto y no quedó ligada, 409 POS_NC_REEMPLAZO_EN_CURSO con notaCredito, notaRechazada y venta (y devolucion en la parcial): revisa la venta antes de pedir otra. Si el SII también rechaza la nota de reemplazo, la devolución vuelve a quedar con ncRechazadaEn y su alerta, y se puede pedir otra.

En el listado de ventas (GET .../pos/ventas), cada devolución trae además ncEstadoSii, el estado SII de su nota vigente: así se distingue una nota de reemplazo en revisión de una aceptada. En Documentos emitidos, la nota rechazada de una devolución parcial del punto de venta sale reemitible: false con motivoNoReemitible (reemitirla siempre respondía 409 CONVERSION_REEMPLAZADA: saldría desligada de su devolución); se corrige acá si el reembolso ya se pagó y, si el SII la rechazó antes del reembolso, pidiendo de nuevo la devolución (el motivo dice cuál). La de una devolución total se puede seguir reemitiendo desde Emisión: la devolución sigue marcada hasta pedir la nota de reemplazo, que entonces liga esa nota sin emitir otra.

Ventas en espera

Un carro guardado en la caja para cobrarlo después: sin pagos, sin movimientos, sin número y sin sesión.

QuéRuta (prefijo .../pos)Quién
GuardarPOST /puntos-venta/:puntoVentaId/ventas-en-esperapos:escribir; admin y emisor
Las de la cajaGET /puntos-venta/:puntoVentaId/ventas-en-esperapos:leer; todos los roles
DetalleGET /ventas-en-espera/:ventaIdpos:leer; todos los roles
BorrarDELETE /ventas-en-espera/:ventaIdpos:escribir; admin y emisor

Guardar acepta { lineas, tipoDte?, receptor?, nota? } con las reglas de la venta (los precios y los totales los calcula el servidor; la factura todavía no exige el receptor) y responde 201 { ventaEnEspera }, con estado: "en_espera", numero: null y expiraEn = ahora + horasVentaEnEspera. Una vencida ya no se lista ni se lee (404 VENTA_EN_ESPERA_NO_ENCONTRADA) y se borra sola.

Para cobrarla se registra la venta con ventaEnEsperaId: en la misma transacción queda usada, y solo una vez. Con dos cobros a la vez, uno registra y el otro recibe 409 VENTA_EN_ESPERA_NO_DISPONIBLE sin registrar nada; lo mismo si venció o es de otra caja. La venta lleva las líneas, el tipo, el receptor y los pagos que manda el cobro, no los guardados: la venta en espera solo queda usada (la caja la carga, puede cambiarla y manda lo que cobra). DELETE la borra solo si sigue en espera ({ "eliminada": true, "id": "…" }); una ya usada responde 409 VENTA_EN_ESPERA_NO_DISPONIBLE.

Escáner y búsqueda

El escáner funciona como un teclado: la caja manda el código leído a GET .../pos/puntos-venta/:puntoVentaId/codigos/:codigo (pos:leer, todos los roles). El código se compara sin espacios en los bordes y sin distinguir mayúsculas, en este orden: los códigos del inventario (el SKU y el código de barras de las variantes, y los de los ítems que controlan stock), el código de barras del ítem y su código.

json
{
  "item": { "id": "6707a1c2a1b2c3d4e5f60903", "nombre": "Polera", "codigo": "POL", "exento": false, "tipo": "producto" },
  "variante": { "id": "6707a1c2a1b2c3d4e5f60910", "sku": "POLERA-M", "codigoBarras": "7800000000024", "atributos": [{ "nombre": "Talla", "valor": "M" }] },
  "precioBruto": 2380,
  "precioNeto": 2000,
  "stock": 12
}
  • precioBruto y precioNeto son lo que cobran la boleta y la factura, con las reglas de arriba.
  • variante es null si el código es del ítem.
  • stock es el saldo de la bodega de la caja (la de la caja; si no tiene, la de su sucursal o la por defecto) si el inventario está encendido y el ítem lo controla, y null si no aplica: un servicio, un pack o un ítem con variantes sin la variante. A un emisor con sesión, durante una toma ciega de esa bodega, no se le muestra: stock: null y enTomaCiega: true.
  • Un código que no existe, o de un ítem o una variante desactivados, responde 404 CODIGO_NO_ENCONTRADO.

GET .../pos/puntos-venta/:puntoVentaId/items?q= es la búsqueda manual: por nombre, código o código de barras (el texto se busca literal, sin distinguir mayúsculas), solo ítems activos, hasta 20 por nombre, en { resultados } con la misma forma (sin variante). Una caja de otra empresa responde 404 PUNTO_VENTA_NO_ENCONTRADO.

Precio de venta bruto del ítem

El ítem (POST y PUT .../items, solo con sesión) acepta un campo opcional precioVentaBruto: el precio con IVA que cobra el punto de venta en una boleta, en pesos enteros mayores que cero. Existe porque hay precios con IVA que ningún neto entero produce: $1.500 / 1,19 es 1.260,5, y ni 1.260 ($1.499) ni 1.261 ($1.501) vuelven a dar $1.500. Sin él, el punto de venta cobra el neto + IVA redondeado. precio sigue siendo el neto y la emisión no cambia. La respuesta del ítem lo trae solo si existe; null en un PUT lo quita.

Reporte Z y listados

GET /api/empresas/:empresaId/pos/sesiones/:sesionId/reporte (pos:leer; todos los roles) devuelve { reporte }: el reporte de cierre (Z) de una sesión de caja, abierta o cerrada. Con ?formato=csv, el mismo contenido en CSV. Una sesión de otra empresa, o un id inválido, responde 404 SESION_NO_ENCONTRADA.

Sucursal de la caja. sesion.sucursal es { id, nombre } de la sucursal ACTUAL de la caja (no la que tenía al abrir la sesión; una caja sin sucursal es de la casa matriz), o null si la empresa no tiene sucursales; también en la vista ciega. Cada sesión de GET .../pos/sesiones trae el mismo campo y, solo si la empresa tiene sucursales, su CSV agrega al final la columna «Sucursal» (sin ellas, el CSV es el de siempre). Ningún total cambia.

Cuadra con el libro. Con la sesión abierta, el esperado de cada medio de pago es la suma de los movimientos no anulados del libro, en vivo. Con la sesión cerrada, arqueo es el que se guardó al cerrar (esa misma suma en ese momento). Las ventas y las devoluciones se suman desde las ventas mismas, y la cuadratura comprueba contra el libro que todo calza.

BloqueQué trae
sesionLa caja (puntoVenta), el número, el estado y la apertura y el cierre: cuándo, quién (usuarioId o apiKeyId, con su nombre), el monto de apertura y las notas. cierre es null con la sesión abierta.
arqueoPor medio de pago. Con la sesión cerrada, el arqueo que se guardó al cerrar: esperado, declarado y diferencia = declarado − esperado (la cuadratura lo compara con el libro). Con la sesión abierta, solo el esperado en vivo, del libro (declarado y diferencia en null).
ventasLas ventas registradas y anuladas de la sesión (el dinero entró en ella): cantidad, total, vuelto, porMedio (lo cobrado, con el efectivo neto del vuelto), porTipoDte (39, 41 y 33: cantidad, neto, exento, IVA y total), porEstadoEmision (emitida, pendiente, emitiendo, error, rechazada, incierta y revisar, cada uno con su cantidad, su total y sus ventas con el folio) y anuladas (las devueltas).
devolucionesLas devoluciones completadas cuyo reembolso se pagó en esta sesión (la venta puede ser de otra caja o de otro día): cantidad, total, por medio y el detalle con el folio de la nota de crédito.
movimientosManualesIngresos, retiros y gastos vigentes (cantidad y monto) y el detalle de cada uno con su motivo, quién lo registró y su anulación, si la tuvo (un anulado se lista pero no suma). Sus asientos, si los tienen, no cambian estas cifras.
emisionesPendientesLas ventas registradas sin su DTE emitido, como en el detalle de la sesión.
devolucionesEnCursoLas devoluciones anulando, nc_emitida o incierta de las ventas de la sesión o que se pagan en ella.
cuadraturaLa verificación interna de abajo.

Las sumas son siempre completas. Los listados de ventas, devoluciones y movimientos llegan hasta 1.000 elementos cada uno; listadoCompleto: false avisa que se cortó. Una sesión cerrada (en el ejemplo, porEstadoEmision omite los estados sin ventas; la respuesta los trae siempre los siete, con 0, y se omitieron el detalle de las devoluciones y de los movimientos):

json
{
  "reporte": {
    "generadoEn": "2026-10-10T23:05:00.000Z",
    "vista": "completa",
    "sesion": {
      "id": "6707a1c2a1b2c3d4e5f60830",
      "numero": 12,
      "estado": "cerrada",
      "puntoVenta": { "id": "6707a1c2a1b2c3d4e5f60810", "nombre": "Mesón 1" },
      "apertura": { "en": "2026-10-10T12:00:00.000Z", "por": { "usuarioId": "6707a1c2a1b2c3d4e5f60801", "apiKeyId": null, "nombre": "Ana Pérez" }, "monto": 20000, "nota": "Turno mañana" },
      "cierre": { "en": "2026-10-10T23:00:00.000Z", "por": { "usuarioId": "6707a1c2a1b2c3d4e5f60801", "apiKeyId": null, "nombre": "Ana Pérez" }, "nota": "Faltan $420" }
    },
    "arqueo": {
      "esperado": { "efectivo": 21420, "debito": 2000, "credito": 0, "transferencia": 2301, "otro": 0 },
      "declarado": { "efectivo": 21000, "debito": 2000, "credito": 0, "transferencia": 2301, "otro": 0 },
      "diferencia": { "efectivo": -420, "debito": 0, "credito": 0, "transferencia": 0, "otro": 0 }
    },
    "ventas": {
      "cantidad": 4,
      "total": 9821,
      "vuelto": 5280,
      "porMedio": { "efectivo": 5520, "debito": 2000, "credito": 0, "transferencia": 2301, "otro": 0 },
      "porTipoDte": [
        { "tipoDte": 39, "cantidad": 2, "neto": 5042, "exento": 720, "iva": 958, "total": 6720 },
        { "tipoDte": 41, "cantidad": 1, "neto": 0, "exento": 800, "iva": 0, "total": 800 },
        { "tipoDte": 33, "cantidad": 1, "neto": 1261, "exento": 800, "iva": 240, "total": 2301 }
      ],
      "porEstadoEmision": [
        { "estado": "emitida", "cantidad": 2, "total": 6720, "ventas": [
          { "id": "6707a1c2a1b2c3d4e5f60950", "numero": 128, "tipoDte": 39, "folio": 1041, "total": 3000, "anulada": false },
          { "id": "6707a1c2a1b2c3d4e5f60951", "numero": 129, "tipoDte": 39, "folio": 1042, "total": 3720, "anulada": false }
        ] },
        { "estado": "pendiente", "cantidad": 1, "total": 800, "ventas": [
          { "id": "6707a1c2a1b2c3d4e5f60953", "numero": 131, "tipoDte": 41, "folio": null, "total": 800, "anulada": true }
        ] },
        { "estado": "error", "cantidad": 1, "total": 2301, "ventas": [
          { "id": "6707a1c2a1b2c3d4e5f60952", "numero": 130, "tipoDte": 33, "folio": null, "total": 2301, "anulada": false }
        ] }
      ],
      "anuladas": { "cantidad": 1, "total": 800 },
      "listadoCompleto": true
    },
    "devoluciones": {
      "cantidad": 1,
      "total": 800,
      "porMedio": { "efectivo": 800, "debito": 0, "credito": 0, "transferencia": 0, "otro": 0 },
      "detalle": [],
      "listadoCompleto": true
    },
    "movimientosManuales": {
      "ingresos": { "cantidad": 1, "monto": 2000 },
      "retiros": { "cantidad": 1, "monto": 5000 },
      "gastos": { "cantidad": 1, "monto": 300 },
      "detalle": [],
      "listadoCompleto": true
    },
    "emisionesPendientes": [
      { "id": "6707a1c2a1b2c3d4e5f60952", "numero": 130, "tipoDte": 33, "total": 2301, "estado": "error", "folio": null, "emitidaId": null }
    ],
    "devolucionesEnCurso": [],
    "cuadratura": {
      "cuadra": true,
      "efectivo": { "apertura": 20000, "ventas": 5520, "devoluciones": 800, "ingresos": 2000, "retiros": 5000, "gastos": 300, "calculado": 21420, "libro": 21420, "diferencia": 0 },
      "porMedio": {
        "efectivo": { "calculado": 21420, "libro": 21420, "diferencia": 0 },
        "debito": { "calculado": 2000, "libro": 2000, "diferencia": 0 },
        "credito": { "calculado": 0, "libro": 0, "diferencia": 0 },
        "transferencia": { "calculado": 2301, "libro": 2301, "diferencia": 0 },
        "otro": { "calculado": 0, "libro": 0, "diferencia": 0 }
      },
      "arqueoGuardado": { "coincide": true }
    }
  }
}

Cuadratura. Es una verificación interna. Recalcula el esperado de cada medio sin los movimientos de venta ni de devolución del libro:

  • Efectivo = apertura + lo cobrado en efectivo por las ventas (neto del vuelto) − lo reembolsado en efectivo por las devoluciones + ingresos − retiros − gastos.
  • Los demás medios = lo cobrado por las ventas − lo reembolsado por las devoluciones.

Después lo compara con el libro (porMedio: calculado, libro y diferencia = libro − calculado). Con la sesión cerrada compara además el esperado que se guardó al cerrar (arqueoGuardado.coincide). cuadra: true es lo normal: la venta y sus movimientos se escriben en la misma transacción. cuadra: false indica un libro que no calza con las ventas. El servidor lo registra como error: avísale al soporte. Las cifras se leen en una sola lectura consistente, así que una venta que entra mientras se arma el reporte de una sesión abierta no produce un descuadre falso.

Cierre ciego en la API

Con la sesión abierta, el reporte completo es solo para el admin (o el superadmin) con sesión. El emisor, el contador y una API key (que actúa como un emisor) reciben vista: "ciega": el reporte sin ningún monto desde el que se pueda calcular el esperado por medio. Van en null el esperado del arqueo, la cuadratura, el monto de apertura, los totales y los montos por medio de las ventas y las devoluciones, los montos por tipo de documento y por estado de emisión, el total de cada venta, devolución, emisión pendiente y devolución en curso listada, y los montos de los ingresos, retiros y gastos. Quedan la cabecera, las cantidades, los estados, los números de venta, los folios, los medios de un reembolso y los motivos. El CSV deja esas celdas vacías y no trae la sección de cuadratura. Así el cajero declara lo que contó sin ver lo esperado. Una sesión cerrada la ven completa (vista: "completa") todos los roles con acceso, también el contador.

El cierre ciego saca los montos de los listados y del esperado: con la sesión abierta, la API no le entrega montos de esa sesión a quien no es admin en ninguna de estas rutas, con la misma regla que el reporte. Lo que no impide es reconstruirlos venta por venta: GET .../ventas/:ventaId sigue entregando los montos de cada venta (el cajero necesita ver la que cobra) y los documentos emitidos muestran los suyos. Es un resguardo del arqueo, no un control de acceso a los montos.

  • GET .../sesiones/:sesionId y GET .../puntos-venta/:puntoVentaId/sesion-abierta: vista: "ciega", sin esperado, con montoApertura: null, el monto de cada fila del resumen y el total de cada emisión pendiente en null.
  • GET .../sesiones/:sesionId/movimientos: el monto de cada movimiento en null.
  • GET .../sesiones y su CSV: el monto de apertura de la sesión abierta en null (en el CSV, también los totales de ventas, anuladas y devoluciones quedan vacíos; las cantidades quedan).
  • GET .../pos/ventas y su CSV: una venta cuya sesión, o la sesión donde se paga su devolución, sigue abierta llega con totales, el monto de cada pago, el vuelto y el monto de cada medio del reembolso en null (en el CSV, esas celdas vacías). Un listado que mezcla sesiones abiertas y cerradas ciega solo esas ventas.

No se ciega lo que el cajero acaba de hacer: la respuesta de abrir la caja, registrar un movimiento, registrar o emitir una venta y cerrar. Tampoco GET .../pos/ventas/:ventaId: el cajero necesita ver la venta que cobró y su ticket.

CSV. Con ?formato=csv responde text/csv; charset=utf-8 como descarga (reporte-z-<caja>_sesion-<número>.csv):

  • Con BOM UTF-8, para que Excel en Chile lea los acentos.
  • Con ; como separador, porque en Chile la coma es el separador decimal.
  • Las secciones van una debajo de otra, rotuladas: arqueo, ventas, devoluciones, movimientos manuales, emisiones pendientes, devoluciones en curso y cuadratura.
  • Los montos son enteros sin separador de miles, las mismas cifras del JSON.
  • Un listado que llegó al tope (listadoCompleto: false) lleva al final la fila «Listado parcial (primeras 1000)».
  • Las fechas van en hora de Chile, AAAA-MM-DD HH:mm:ss.
  • Un texto libre que empieza con =, +, - o @ va con un apóstrofo delante, para que la planilla no lo tome como una fórmula.

Otro formato que no sea json ni csv responde 400 DATOS_INVALIDOS.

Listado de ventas. GET .../pos/ventas (pos:leer, todos los roles) lista de la más nueva a la más vieja, sin las líneas. Todos los errores de los filtros salen juntos en un 400 DATOS_INVALIDOS.

FiltroValores
sesionIdLa sesión de la venta.
puntoVentaIdLa caja de la venta.
estadoregistrada o anulada (devuelta).
estadoEmisionpendiente, emitiendo, emitida, incierta, rechazada, error o revisar.
tipoDte39, 41 o 33.
conDevoluciontrue: con una devolución pedida, en cualquier estado; false: sin ninguna.
desde, hastaDías de Chile AAAA-MM-DD sobre el registro, inclusivos.
pagina, limiteHasta 200 por página.
formatocsv: las mismas ventas en CSV, sin paginar.

El CSV de ventas lleva una fila por venta con estas columnas: número, fecha, caja, número de sesión, tipo, folio, estado de emisión, estado, devolución, folio de la nota de crédito, receptor, neto, exento, IVA, total, el pago de cada medio y el vuelto.

En el JSON del listado (no en el CSV ni en GET .../pos/ventas/:ventaId), la devolución total y cada parcial traen además ncEstadoSii, de solo lectura: el estado SII de su nota de crédito vigente (ACEPTADO, ACEPTADO_REPAROS, RECHAZADO, ENVIO_INCIERTO o el código del SII mientras no hay veredicto), o null sin nota. Distingue una nota de reemplazo en revisión de una aceptada (ver Nota de reemplazo).

Resumen de sesiones. GET .../pos/sesiones?formato=csv, con los mismos filtros del listado, da una fila por sesión:

  • la caja, el número, el estado, la apertura y el cierre;
  • el monto de apertura;
  • las ventas (cantidad y total, con las anuladas, como ventas del reporte), las anuladas aparte (cantidad y total) y las devoluciones pagadas en ella;
  • el esperado, el declarado y la diferencia de cada medio y la nota de cierre, solo de las sesiones cerradas.

Una sesión abierta deja el arqueo vacío: su esperado en vivo está en el reporte Z, con el cierre ciego. Los dos CSV llegan hasta 5.000 filas. Un filtro que alcanza más responde 400 DATOS_INVALIDOS con total y limite antes de leer nada. error dice cuántas filas alcanza el filtro y detalles[] trae solo cómo acotarlo, según el CSV: las ventas de una sesión se filtran por estado, emisión, tipo o devolución; las demás ventas y las sesiones, además por fechas (desde y hasta). Los encabezados nombran los medios con tilde (Pago débito, Esperado crédito) y el reporte Z los rotula con mayúscula inicial (Efectivo, Débito).

Códigos del punto de venta

codeHTTPCuándo
PLAN_SIN_ERP403La empresa no tiene MiAplicación ERP.
PLAN_SIN_POS403Encender el módulo, o crear o reactivar un punto de venta, sin un plan ERP que lo habilite. Trae requiere: erp y planSugerido.
PLAN_LIMITE_PUNTOS_VENTA409Crear o reactivar un punto de venta con los activos en el tope del plan (trae plan, planSugerido, puntosVentaMax y puntosVentaActivos). Antes del 14-10-2026 era 403.
POS_INACTIVO409Leer o escribir puntos de venta, sesiones de caja o ventas con el módulo apagado.
PUNTO_VENTA_NO_ENCONTRADO404El punto de venta no existe, es de otra empresa o el id no es válido.
PUNTO_VENTA_INACTIVO409Abrir una sesión en un punto de venta desactivado.
PUNTO_VENTA_CON_SESION_ABIERTA409Desactivar un punto de venta que tiene una sesión de caja abierta: cierra la caja antes.
BODEGA_DE_OTRA_SUCURSAL422Crear un punto de venta, o cambiarle la sucursal o la bodega, con una bodega de OTRA sucursal (null y la matriz son la misma; sin sucursales, todo es matriz). Todos los errores en detalles[]; no se escribió nada.
SESION_YA_ABIERTA409Abrir una caja que ya tiene una sesión abierta (trae su sesionId).
SESION_NO_ENCONTRADA404La sesión no existe, es de otra empresa o el id no es válido.
SESION_CAJA_CERRADA409Registrar o anular un movimiento, registrar una venta, pagar el reembolso de una devolución, o cerrar, en una sesión cerrada. No se registró nada.
SESION_CAJA_EN_CONFLICTO409La sesión recibió demasiadas operaciones a la vez y esta no se pudo escribir. No se registró nada: reintenta en unos segundos.
CIERRE_EN_CONFLICTO409Lo mismo al cerrar: la caja siguió recibiendo movimientos. No se cerró: vuelve a cerrarla (el arqueo se recalcula).
MOVIMIENTO_NO_ENCONTRADO404El movimiento no existe, es de otra empresa o el id no es válido.
MOVIMIENTO_NO_ANULABLE409Anular una apertura, una venta o una devolución.
MOVIMIENTO_YA_ANULADO409Anular un movimiento que ya está anulado.
IDEMPOTENCIA_CONFLICTO409La misma Idempotency-Key con otro cuerpo al registrar un movimiento o una venta, al devolver una venta o al registrar su reembolso.
POS_LINEA_LIBRE_SOLO_ADMIN403Una línea libre (sin ítem del catálogo) de un emisor o de una API key. No se registró nada.
STOCK_INSUFICIENTE409Con bloquearSinStock, falta stock en la bodega de la caja para la venta. Al registrar, no se registró nada; al emitir (la carrera perdida), no se tomó folio y la emisión queda en error.
POS_FUERA_DE_PRODUCCION409Con la empresa en producción, una venta que saldría en certificación (API key mk_cert_), al registrar o al emitir; o ligar una emisión a un documento de certificación o demo. No se registró ni se emitió nada.
POS_VENTA_NO_EMITIBLE409Emitir una venta anulada, o con una devolución en curso.
POS_EMISION_EN_CURSO409Emitir una venta que se está emitiendo en este momento (o que cambió mientras se emitía).
POS_EMISION_EN_REVISION409Emitir una venta cuya emisión quedó en revisión: la resuelve un admin.
POS_VENTA_YA_EMITIDA409Emitir una venta ya emitida, o con el envío al SII incierto.
POS_EMISION_REEMITIDA409Volver a emitir una venta cuyo documento rechazado ya se reemitió.
POS_EMISION_CON_DTE409Emitir o liberar una emisión que tiene un documento registrado (trae su emitidaId).
POS_EMISION_NO_EN_REVISION409Liberar una emisión que no está en revisión, o ligar una que no está en revisión ni incierta sin documento.
POS_EMISIONES_EN_VUELO409Apagar el módulo con ventas cuya emisión está emitiendo o revisar (las trae en detalles[]). No se apagó.
POS_SIN_EMISION_CONFIGURADA422Registrar una venta en una empresa sin la emisión con el SII configurada. No se registró nada.
POS_EMISION_LIBERACION_PREMATURA409Liberar una emisión antes de una hora desde que empezó (trae minutosRestantes).
DTE_NO_ENCONTRADO404Ligar una emisión a un documento que no existe en la empresa.
DTE_DE_OTRA_VENTA409Ligar una emisión a un documento que no salió de esa venta o es de otro tipo.
DTE_ANTERIOR_A_LA_EMISION409Ligar una emisión a un documento anterior a ella.
VENTAS_EN_VUELO409Cerrar una sesión con una venta que se está emitiendo, o con una devolución que se paga en ella y está emitiendo su nota (trae detalles[] y ventas; la devolución con operacion: "devolucion").
CONVERSION_REEMPLAZADA409Reemitir el documento rechazado de una venta que ya se volvió a emitir, que está anulada o que tiene una devolución en curso, o la nota de crédito de una devolución parcial (se corrige con la nota de reemplazo). No se tocó su folio.
POS_VENTA_YA_ANULADA409Devolver una venta ya anulada, o reembolsar una devolución ya completada.
POS_DEVOLUCION_EN_CURSO409Devolver una venta con una devolución anulando, nc_emitida o incierta (trae estado), o que cambió mientras se devolvía.
POS_EMISION_EN_VUELO409Devolver una venta cuya emisión está emitiendo, revisar o incierta (trae estado): primero se resuelve la emisión.
POS_DEVOLUCION_CON_DOCUMENTO409Devolver como venta sin documento una que sí lo tiene: un rechazado ya reemitido o un documento de un intento anterior (trae emitidaId).
POS_DEVOLUCION_SIN_DTE409La venta figura emitida, pero su documento no está registrado: no se anula.
POS_DEVOLUCION_REEMBOLSO_PENDIENTE409La nota de crédito se emitió, pero el reembolso no entró (la sesión se cerró entremedio). Trae causa, venta y notaCredito; el reembolso se registra con .../devolucion/reembolsar.
POS_DEVOLUCION_NO_PENDIENTE409Reembolsar una devolución que no está nc_emitida (trae estado).
POS_DEVOLUCION_NO_EN_REVISION409Resolver una devolución que no está incierta ni quedó anulando más de 15 minutos.
POS_DEVOLUCION_CON_NC409Liberar una devolución cuyo documento tiene una nota de crédito local vigente (trae ncEmitidaId): se liga, no se libera.
POS_DEVOLUCION_LIBERACION_PREMATURA409Liberar una devolución antes de una hora desde que empezó (trae minutosRestantes).
POS_DEVOLUCION_NC_SIN_REGISTRO409Liberar una devolución con el folio de una nota que el SII recibió pero sin su registro local (trae folio), o sin folio pero con la reserva de anulación del documento sin soltar (trae reserva: true): un reintento sacaría una segunda nota.
NC_NO_ENCONTRADA404Ligar una devolución a una nota que no existe en la empresa (también la de un registro local fallido, mientras nadie lo reconstruya).
NC_DE_OTRO_DOCUMENTO409Ligar una devolución a una nota que no es la CodRef 1 que anula el documento de la venta en su ambiente.
NC_RECHAZADA409Ligar una devolución a una nota que el SII rechazó, o reembolsar una nc_emitida cuya nota el SII rechazó (la devolución vuelve a error).
POS_NC_NO_RECHAZADA409Pedir la nota de reemplazo de una devolución que no está completada, no tiene nota o cuya nota vigente no está rechazada por el SII (trae estado o estadoSii). Sin folio.
POS_NC_REEMPLAZO_EN_CURSO409Pedir la nota de reemplazo mientras otra se emite, quedó con el envío incierto o no tiene veredicto del SII (trae estado y folio, o estadoSii). Sin folio.
POS_NC_FUERA_DE_PLAZO_IVA422Nota de reemplazo pasados seis meses desde la venta: sigue siendo obligatoria, pero ya no rebaja el débito fiscal; la resuelve el contador (trae fechaVenta, plazoHasta y notaRechazada). Sin folio.
POS_DOCUMENTO_VENTA_NO_ACEPTADO409Nota de reemplazo sobre un documento de la venta que el SII no aceptó (trae estadoSii, tipoDte, folio y notaRechazada). Sin folio.
POS_DEVOLUCION_PARCIAL_SIN_DTE409Devolver una parte de una venta sin su documento emitido: se emite primero, o se devuelve entera.
POS_DEVOLUCION_DTE_RECHAZADO409Devolver una parte de una venta cuyo documento el SII rechazó: no hay nada que corregir.
POS_DEVOLUCION_DTE_INCIERTO409Devolver una parte de una venta cuyo documento está en ENVIO_INCIERTO.
POS_DEVOLUCION_DOCUMENTO_ANULADO409Devolver una parte de una venta cuyo documento ya tiene una nota que lo anula entero.
POS_DEVOLUCION_OTRO_AMBIENTE409El documento es de modo demo y hoy la empresa no lo está, o al revés: la nota no lo corregiría.
POS_DEVOLUCION_NO_ENCONTRADA404Reembolsar o resolver una devolución parcial que no es de esa venta.
VENTA_NO_ENCONTRADA404La venta no existe, es de otra empresa o el id no es válido.
VENTA_EN_ESPERA_NO_ENCONTRADA404La venta en espera no existe, venció, ya se usó, es de otra empresa o el id no es válido.
VENTA_EN_ESPERA_NO_DISPONIBLE409Cobrar una venta en espera que ya se usó, venció o es de otra caja, o borrar una ya usada.
CODIGO_NO_ENCONTRADO404El escáner no encontró un ítem activo con ese código.
DATOS_INVALIDOS400Datos inválidos de la configuración, un punto de venta, una apertura, un movimiento, un cierre, una venta, una devolución o su reembolso, una sucursal o bodega ajena o desactivada, o un nombre repetido (todos en detalles[]). También un filtro o un formato inválido de los listados y del reporte, o un CSV de más de 5.000 filas (trae total y limite).
POS_PAGOS_NO_CUADRAN400No es un code: es el motivo del 400 DATOS_INVALIDOS de una venta cuyos pagos no alcanzan el total del servidor o cuyo vuelto supera el efectivo. Trae los totales del servidor.
CUENTA_DEMO_RESTRINGIDA403La cuenta demo compartida no configura el módulo ni sus puntos de venta.

Canales de venta

Para que una tienda en línea o un marketplace (tu WooCommerce, tu Shopify, Mercado Libre o una tienda hecha a la medida) venda contra esta API: lea el catálogo con el stock disponible para su canal, envíe sus órdenes con los precios brutos que pagó el cliente y reciba la boleta o factura sin emitirla dos veces. Se está construyendo por partes: hoy existen la configuración del módulo, sus dos scopes, los canales, el catálogo de cada canal con su stock disponible, la recepción de las órdenes, idempotente y con el total pagado cuadrado contra las líneas, el envío y los descuentos, y la emisión de las órdenes: la boleta o factura emitida sola al llegar pagada, sin emitirla dos veces, su cancelación (POST .../ordenes/:ordenId/cancelar: sin documento si no se emitió, con su nota de crédito si se emitió) y los eventos de los canales: un webhook por cada cambio de estado de una orden y uno por canal, cada minuto, con lo que cambió de su stock disponible.

Requiere MiAplicación ERP

A una empresa sin ERP, sus rutas le responden 403 PLAN_SIN_ERP; una que lo tuvo conserva la lectura (GET) de sus datos. Ver MiAplicación API y ERP.

Opt-in por empresa

Con el módulo apagado (el estado de toda empresa hasta que un admin lo enciende) ninguna respuesta cambia.

Viene en los planes de MiAplicación ERP, con un tope de canales activos por plan. Encender el módulo exige un plan ERP que lo habilite (la contratación vigente, pagada y sin vencer, el plan asignado por la plataforma a una empresa que nunca pagó o una cortesía vigente); sin él responde 403 PLAN_SIN_CANALES sin escribir nada, con el ERP de entrada en planSugerido. Crear o reactivar un canal con el tope alcanzado responde 409 PLAN_LIMITE_CANALES (antes del 14-10-2026, 403), con el plan ERP que permite más. Un módulo ya encendido no se bloquea si la contratación ERP vence, y ningún canal se desactiva si la empresa baja a un plan ERP menor. Bajar a un plan de la API deja sus datos en solo lectura.

PlanCanales activos
ERP Pyme1
ERP Negocio3
ERP Full10
ERP CorporativoSin tope
Planes de la API0 (el módulo es del ERP)
json
{
  "error": "La empresa ya tiene 1 canal activo y el plan ERP Pyme permite 1 canal. Desactiva uno que no uses o contrata el plan ERP Negocio (hasta 3 canales) o uno superior.",
  "code": "PLAN_LIMITE_CANALES",
  "plan": {
    "clave": "erp_pyme",
    "nombre": "ERP Pyme"
  },
  "planSugerido": {
    "clave": "erp_negocio",
    "nombre": "ERP Negocio",
    "canalesMax": 3
  },
  "canalesMax": 1,
  "canalesActivos": 1
}

Configuración de los canales de venta

GET /api/empresas/:empresaId/canales/configuracion (canales:leer, cualquier rol de la empresa):

json
{
  "configuracion": { "id": "6707a1c2a1b2c3d4e5f60901", "activo": true },
  "plan": { "clave": "negocio", "nombre": "Negocio" },
  "puedeActivar": true,
  "canalesMax": 3,
  "canalesActivos": 1
}
CampoQué es
idnull si la empresa nunca guardó su configuración.
activoEl módulo está encendido.
plan{ clave, nombre } del plan que habilita (contratación vigente, plan asignado o cortesía), o null sin uno.
puedeActivarSi la barrera del plan dejaría encender el módulo a quien pregunta. No dice nada del rol: encender es de admin.
canalesMaxCanales activos que permite el plan: null = sin tope; 0 = sin un plan ERP que lo habilite.
canalesActivosLos canales activos de la empresa.

PUT .../canales/configuracion es solo con sesión (solo admin; la cuenta demo compartida recibe 403). Acepta { "activo": true | false }; cualquier otra clave se ignora, y un cuerpo sin activo responde 400 DATOS_INVALIDOS. Apagar no borra nada: al volver a encenderlo, los canales están igual.

Canales

Cada canal es una tienda en línea o un marketplace: un nombre, de qué bodega sale su stock, cuántas unidades se le esconden (el colchón) y desde qué sucursal emite. GET .../canales (canales:leer, cualquier rol; ?activo=true o false filtra) devuelve { canales, cupo }, y GET .../canales/:canalId devuelve { canal }; uno de otra empresa responde 404 CANAL_NO_ENCONTRADO. Con el módulo apagado, 409 CANALES_INACTIVO.

json
{
  "canales": [
    {
      "id": "6707a1c2a1b2c3d4e5f60910",
      "nombre": "Tienda web",
      "tipo": "woocommerce",
      "bodegaId": "6707a1c2a1b2c3d4e5f60930",
      "colchon": 2,
      "sucursalId": null,
      "emitirAutomatico": true,
      "activo": true,
      "createdAt": "2026-10-10T15:00:00.000Z",
      "updatedAt": "2026-10-10T15:00:00.000Z"
    }
  ],
  "cupo": { "plan": { "clave": "negocio", "nombre": "Negocio" }, "canalesMax": 3, "canalesActivos": 1 }
}

Crear (POST .../canales, nace activo) y editar (PATCH .../canales/:canalId) son solo con sesión y solo del admin: el emisor y el contador leen, y una API key, aunque tenga canales:escribir, recibe 403. No hay DELETE: un canal se desactiva con { "activo": false } y se puede reactivar, pasando por el tope del plan; así sus órdenes siguen rastreables.

CampoReglas
nombreObligatorio al crear. Hasta 60 caracteres, único en la empresa sin distinguir mayúsculas ni espacios repetidos.
tipoUna etiqueta informativa: woocommerce, shopify, jumpseller, mercadolibre, tienda_propia u otro (por defecto). No cambia ningún comportamiento.
bodegaIdEl id de una bodega activa de tu empresa: de ahí sale el stock que ve el canal. null = sin bodega.
colchonUnidades que se le esconden al canal de su disponible. Entero de 0 a 1.000.000; por defecto 0.
sucursalIdEl id de una sucursal activa de tu configuración de emisión; null = casa matriz.
emitirAutomaticoSi una orden pagada emite su documento sola al llegar. Por defecto true.
activoSolo al editar: false desactiva, true reactiva.

Los números van como número y los booleanos como true/false, no como texto. Todos los errores salen juntos en detalles[] con 400 DATOS_INVALIDOS: la forma, una sucursal o bodega que no es de tu empresa (responde lo mismo que una que no existe) o está desactivada, y un nombre repetido.

El documento de cada orden no se configura en el canal: sale de la orden misma. Sin receptor completo va en boleta (39), o en boleta exenta (41) si todas sus líneas son exentas; con receptor completo (RUT, razón social, giro, dirección y comuna), en factura (33). El campo tipoDtePorDefecto de las primeras versiones ya no existe: si lo mandas, se ignora.

Catálogo de un canal

GET /api/empresas/:empresaId/canales/:canalId/catalogo (canales:leer, cualquier rol de la empresa) devuelve lo que el canal puede vender: los ítems activos con su precio y el stock disponible en la bodega del canal. Nunca trae costos (ni el costo promedio, ni un precio de compra, ni proveedores): cada entrada lleva exactamente los campos de la tabla de abajo. Un canal de otra empresa, o un id inválido, responde 404 CANAL_NO_ENCONTRADO; un canal desactivado, 409 CANAL_INACTIVO.

QueryQué es
modificadoDesdeOpcional. Solo lo que cambió en o después de esa fecha. ISO 8601 con zona horaria (2026-10-10T15:00:00.000Z) o solo la fecha (2026-10-10, medianoche UTC). Una hora sin zona es ambigua y se rechaza. En la URL, el + de un offset va codificado como %2B (sin codificar se lee como un espacio y responde 400); lo más simple es usar Z, como generadoEn.
cursorOpcional. El siguienteCursor de la página anterior, tal cual (es opaco).
limiteOpcional. Entradas por página: entero de 1 a 500; por defecto 100.

Un query inválido responde 400 DATOS_INVALIDOS con todos los errores juntos en detalles[].

json
{
  "canal": { "id": "6707a1c2a1b2c3d4e5f60910", "nombre": "Tienda web" },
  "bodega": { "id": "6707a1c2a1b2c3d4e5f60930", "nombre": "Bodega web" },
  "inventarioActivo": true,
  "completo": true,
  "generadoEn": "2026-10-10T15:00:00.000Z",
  "items": [
    {
      "itemId": "6707a1c2a1b2c3d4e5f60a01",
      "varianteId": null,
      "sku": "TAZA-1",
      "codigo": "TAZA-1",
      "codigoBarras": "7800000000017",
      "nombre": "Taza",
      "descripcion": "Taza de loza",
      "tipo": "producto",
      "exento": false,
      "precioNeto": 1261,
      "precioBruto": 1500,
      "controlaStock": true,
      "disponible": 6,
      "actualizadoEn": "2026-10-10T14:58:12.000Z"
    },
    {
      "itemId": "6707a1c2a1b2c3d4e5f60a02",
      "varianteId": "6707a1c2a1b2c3d4e5f60b01",
      "sku": "POL-M-R",
      "codigo": "POL",
      "codigoBarras": null,
      "nombre": "Polera (M, Rojo)",
      "descripcion": null,
      "tipo": "producto",
      "exento": false,
      "precioNeto": 10000,
      "precioBruto": 11900,
      "controlaStock": true,
      "disponible": 4,
      "actualizadoEn": "2026-10-09T20:10:00.000Z"
    }
  ],
  "siguienteCursor": "NjcwN2ExYzJhMWIyYzNkNGU1ZjYwYTAyLjY3MDdhMWMyYTFiMmMzZDRlNWY2MGIwMQ"
}
Campo de cada entradaQué es
itemId, varianteIdEl ítem y, si tiene variantes, la variante (si no, null). Un ítem con variantes no va como vendible: va una entrada por cada variante activa.
skuEl de la variante; en un ítem sin variantes, su código. null si no tiene.
codigo, codigoBarrasEl código del ítem y el código de barras de la variante (o del ítem sin variantes); null si no hay.
nombreEl del ítem y, en una variante, los valores de sus atributos entre paréntesis.
descripcion, tipoLa descripción (null si no hay) y producto o servicio.
exento, precioNeto, precioBrutoEl bruto es el que cobra el canal: el precioVentaBruto del ítem si lo tiene, si no round(precioNeto × 1,19), y en un ítem exento el bruto es el neto. Una variante con precio propio usa el suyo. Es la misma regla del punto de venta.
controlaStockSi el ítem lleva stock en el inventario (un servicio nunca).
disponibleLo que el canal puede vender (abajo), o null si el ítem no controla stock, el inventario está apagado o no hay bodega.
actualizadoEnLa fecha más reciente entre el ítem, la variante y su stock en la bodega del canal (en un pack, el de sus componentes).

Cómo se calcula disponible. En la bodega del canal (su bodegaId; si no tiene, o la suya se desactivó, la bodega por defecto del inventario; solo cuenta una bodega activa): stock − lotes vencidos − comprometido − colchón, con piso 0 y hasta 6 decimales.

  • Stock: el saldo del ítem o de la variante en esa bodega. Lo de otras bodegas no cuenta, y las unidades de lotes vencidos no se ofrecen.
  • Comprometido: lo que reservan las notas de venta confirmadas y vigentes (con los módulos de ventas e inventario encendidos) y las órdenes pagadas que todavía no se emiten (de cualquier canal que reserve en esa bodega).
  • Colchón: el colchon del canal, unidades que se le esconden.
  • Packs: un pack no tiene stock propio. Su disponible es cuántos packs completos se arman con el disponible de sus componentes: el mínimo de floor(disponible del componente / cantidad por pack).
  • Con el inventario apagado, inventarioActivo: false, bodega: null y todo disponible: null. Sin bodega activa (ni la del canal ni la por defecto), bodega: null y todo disponible: null.

Sincronización incremental. La primera vez, y una vez al día, pide el catálogo completo sin modificadoDesde, página por página. Guarda el generadoEn de la primera página de esa corrida: va 2 minutos antes del inicio de la consulta, así que una escritura que se estaba confirmando mientras leías, y lo que cambie mientras paginas, entran en la corrida siguiente. Las siguientes corridas van con modificadoDesde igual a ese generadoEn (el mismo en todas sus páginas), y guardan el generadoEn de su primera página para la próxima.

Por ese margen, una corrida puede repetir entradas de los últimos 2 minutos de la anterior: aplícalas de forma idempotente (por itemId/varianteId, la última que llega manda).

Un ítem entra si, en o después de modificadoDesde, cambió el ítem, una de sus variantes, su stock en la bodega del canal, una nota de venta que lo compromete ahí (también si la nota se anuló o se convirtió) o una orden de canal que lo reserva ahí (al recibirla, pagarla o emitirla); un pack entra si cambió cualquiera de sus componentes. Con variantes entra el ítem completo. Si cambió algo que mueve el catálogo entero (el canal, su colchón o su bodega; la bodega, también si se desactivó; o la configuración del inventario o de ventas), la respuesta es el catálogo completo con completo: true.

Lo que modificadoDesde no detecta

Una reserva de nota de venta que vence sola, un lote que vence y un ítem o una variante que se desactiva (sale de la lista, no viene marcado): ninguno escribe nada. Por eso la sincronización completa diaria no es opcional: un ítem que estaba en tu tienda y no viene en la completa ya no se vende.

Paginación. Por entrada y en un orden estable: una página trae a lo más limite entradas, aunque un ítem tenga muchas variantes, y puede traer menos sin ser la última. Sigue pidiendo con cursor hasta que siguienteCursor venga en null. Un emisor con sesión en el panel no ve el stock de una bodega con una toma de inventario ciega en curso (todo disponible: null y enTomaCiega: true); a una API key no se le oculta.

Órdenes

Una orden es lo que tu tienda ya vendió, con los precios brutos (con IVA) que pagó el cliente. La API la recibe, la valida y, cuando está pagada, emite su boleta o factura (ver Emisión de las órdenes). Enviarla, confirmar su pago y emitirla piden canales:escribir (o un admin o un emisor con sesión); leerlas, canales:leer (cualquier rol de la empresa).

  • Lee el catálogo del canal y guarda el itemId y el varianteId de cada producto (o usa tu SKU: la orden también se resuelve por código).
  • Cuando el cliente paga, envía la orden con pagada: true a POST /api/empresas/:empresaId/canales/:canalId/ordenes. La ordenExterna (el número de la orden en tu tienda) es la clave de idempotencia: una por canal.
  • Si no recibes respuesta (un timeout, un 5xx), reintenta con el mismo cuerpo: devuelve la orden que ya existe (200, repetido: true), nunca una segunda, también si llegan dos a la vez y también si el canal se desactivó después (solo una orden nueva en un canal desactivado responde 409 CANAL_INACTIVO). Con otro cuerpo, 409 ORDEN_CANAL_CONFLICTO y no cambia nada. Las claves que la API no lee (un metadata, el updated_at de tu tienda) no cuentan para comparar el cuerpo.
  • Registrada antes del pago (pagada: false), queda pendiente_pago: no compromete stock ni se emitirá. Al pagarse, POST .../canales/:canalId/ordenes/:ordenId/pagar con { "medioPago"? }, o reenvía la misma orden con pagada: true (pagada y medioPago no cuentan para comparar el cuerpo). Pagar una ya pagada responde 200 con repetido: true. Pagar una cancelada con /pagar responde 409 ORDEN_CANAL_CANCELADA; reenviarla con pagada: true, también, si nunca se pagó. Si se pagó y después se canceló, el reintento del envío original (un webhook atrasado de «pagada») recibe lo mismo que el original: la orden, ahora cancelada (200, repetido: true). Un reenvío que no pide el pago también devuelve la orden cancelada.
json
POST /api/empresas/:empresaId/canales/:canalId/ordenes
{
  "ordenExterna": "WC-10521",
  "lineas": [
    { "itemId": "66f1c2d3a1b2c3d4e5f60101", "varianteId": "66f1c2d3a1b2c3d4e5f60102", "cantidad": 2, "precioBruto": 12990 },
    { "sku": "TAZA-ROJA", "nombre": "Taza roja", "cantidad": 1, "precioBruto": 4990, "descuento": 500 }
  ],
  "envio": 3990,
  "descuentoPedido": 1000,
  "totalPagado": 33460,
  "medioPago": "pago_electronico",
  "pagada": true
}

Respuesta 201 (la primera vez; un reintento igual responde 200 con repetido: true):

json
{
  "orden": {
    "id": "6708a1c2a1b2c3d4e5f60501",
    "canalId": "6707a1c2a1b2c3d4e5f60a01",
    "ordenExterna": "WC-10521",
    "estado": "pagada",
    "pagadaEn": "2026-10-10T15:04:05.000Z",
    "tipoDte": 39,
    "receptor": null,
    "envio": 3990,
    "envioExento": false,
    "envioNombre": null,
    "descuentoPedido": 1000,
    "totalPagado": 33460,
    "totales": { "neto": 28118, "exento": 0, "iva": 5342, "total": 33460 },
    "diferenciaRedondeo": 0,
    "medioPago": "pago_electronico",
    "bodegaId": "6707a1c2a1b2c3d4e5f60301",
    "sucursalId": null,
    "mueveStock": true,
    "emision": { "estado": "pendiente", "folio": null },
    "origen": { "tipo": "apikey", "apiKeyId": "6707a1c2a1b2c3d4e5f60c01", "apiKeyNombre": "WooCommerce", "proyecto": "mitienda.cl", "usuarioId": null },
    "createdAt": "2026-10-10T15:04:05.000Z",
    "updatedAt": "2026-10-10T15:04:05.000Z",
    "lineas": [
      {
        "itemId": "66f1c2d3a1b2c3d4e5f60101", "varianteId": "66f1c2d3a1b2c3d4e5f60102", "vinculada": true,
        "sku": null, "codigo": null, "codigoBarras": null, "nombre": "Polera (M, Rojo)",
        "cantidad": 2, "precioBruto": 12990, "descuento": 0, "exento": false, "descuentoAsignado": 853, "montoLinea": 25127
      },
      {
        "itemId": null, "varianteId": null, "vinculada": false,
        "sku": "TAZA-ROJA", "codigo": null, "codigoBarras": null, "nombre": "Taza roja",
        "cantidad": 1, "precioBruto": 4990, "descuento": 500, "exento": false, "descuentoAsignado": 147, "montoLinea": 4343
      }
    ],
    "reservaStock": [
      { "linea": 0, "itemId": "66f1c2d3a1b2c3d4e5f60101", "varianteId": "66f1c2d3a1b2c3d4e5f60102", "bodegaId": "6707a1c2a1b2c3d4e5f60301", "cantidad": 2, "packItemId": null }
    ]
  },
  "repetido": false,
  "sinVincular": [
    { "linea": 1, "sku": "TAZA-ROJA", "codigo": null, "codigoBarras": null, "nombre": "Taza roja" }
  ]
}
CampoQué es
ordenExternaObligatorio. El número o código de la orden en tu tienda (texto o entero, 1 a 100 caracteres). Clave de idempotencia por canal.
lineasObligatorio, 1 a 60 (el tope de un documento del SII; el despacho ocupa una).
lineas[].itemId, varianteIdEl producto del catálogo. Una variante va con el itemId de su ítem; un ítem con variantes, con su variante. Un id de otra empresa es 400.
lineas[].sku, codigo, codigoBarrasSin itemId, el producto se busca por estos, en ese orden (sin distinguir mayúsculas).
lineas[].nombreObligatorio sin itemId, hasta 80 caracteres. En una línea vinculada, si no viene, el del catálogo.
lineas[].cantidadMayor que 0, hasta 6 decimales.
lineas[].precioBrutoPrecio unitario con IVA que pagó el cliente, en pesos enteros mayores que 0. Tu precio es la verdad: no se recalcula con el del catálogo.
lineas[].descuentoDescuento de la línea, con IVA, en pesos enteros; no más que la línea.
lineas[].exentoSolo cuenta en una línea libre. En una línea vinculada se ignora: manda la exención del ítem del catálogo.
envioEl despacho, con IVA, en pesos enteros (0 = sin despacho). Va al documento como una línea «Despacho» (o envioNombre), sin producto.
envioExentotrue si el despacho no lleva IVA.
descuentoPedidoDescuento de toda la orden (un cupón), con IVA.
totalPagadoObligatorio. Lo que pagó el cliente, con IVA.
receptorPara una factura: { rut, razonSocial, giro, direccion, comuna, ciudad?, correo? }, completo. Sin él, boleta. Uno a medias es 400.
medioPagoefectivo, pago_electronico, transferencia, cheque u otro. Sobre 135 UF la boleta lo exige (ver abajo).
pagadaObligatorio: true o false.

La identidad de montos. El total tiene que cuadrar, con el mismo redondeo de línea del documento:

texto
Σ (round(cantidad × precioBruto) − descuento) + envio − descuentoPedido = totalPagado

Si no cuadra, 422 ORDEN_CANAL_MONTOS con los errores en detalles[] y la suma en montos (subtotalLineas, envio, descuentoPedido, esperado, totalPagado), sin escribir nada. El descuentoPedido se reparte entre las líneas de productos (nunca en el despacho) en proporción a su monto, por el método del resto mayor, y queda en descuentoAsignado de cada línea: así el documento lleva el descuento dentro de sus líneas y su total es exacto. No puede superar el subtotal de los productos.

El documento se deriva de la orden, no se pide:

La ordenDocumento
Con receptor completoFactura 33. Cada línea va en neto, derivado del bruto ya descontado. El IVA se calcula desde el neto, así que el total puede diferir del pagado en un peso: diferenciaRedondeo = total del documento − totalPagado (a lo más uno por línea). Necesita al menos una línea afecta con monto (más de $0 después de los descuentos).
Sin receptor y todas las líneas exentas (el despacho, según envioExento)Boleta exenta 41.
Sin receptorBoleta 39, con los precios brutos: su total es exactamente totalPagado.

Sobre 135 UF. La Ley 21.713 exige que una boleta de más de 135 UF lleve el medio de pago y el RUT y la razón social reales del comprador. En esta API una orden con receptor es siempre una factura 33, así que una orden sobre 135 UF sin receptor responde 422 ORDEN_CANAL_DOCUMENTO_INVALIDO (con lo que falta en detalles[]): mándala con el receptor completo (rut, razonSocial, giro, direccion y comuna) y sale factura. Pide esos datos en tu checkout para las compras grandes.

Las líneas sin vincular. Una línea con itemId se vincula a ese ítem; sin él, se busca por sku, codigo o codigoBarras. Un ítem desactivado se vincula igual (ya se vendió). Lo que no se encuentra es una línea libre: va al documento con su nombre y su exento, no mueve stock y aparece en sinVincular[] de la respuesta. Revísalas: lo normal es que falte el producto o su código en el catálogo.

Todo se valida antes de escribir, con los errores juntos en detalles[]: la forma (400 DATOS_INVALIDOS), los montos (422 ORDEN_CANAL_MONTOS), las líneas en $0 (422 ORDEN_CANAL_LINEA_EN_CERO) y el documento, con las mismas reglas de la emisión (422 ORDEN_CANAL_DOCUMENTO_INVALIDO: el RUT del receptor, la sucursal del canal, la regla de las 135 UF, una factura sin monto afecto…). Una orden rechazada no deja nada escrito. Ninguna línea puede quedar en $0, ni por su propio descuento ni porque el descuento del pedido la absorba: no está confirmado que el SII acepte una línea de monto 0. En una factura, además, una línea de muy pocos pesos puede quedar en $0 al pasar a neto (el neto se reparte entre sus líneas en proporción a su monto: con cinco líneas de $1 y una de $5, a una de las de $1 no le alcanza ni un peso neto), y también se rechaza. Un regalo va con un precio mínimo o fuera de la orden; lo revisaremos cuando se confirme contra el SII. El stock no se revisa: tu tienda ya vendió y la orden se registra igual. Con la empresa en producción, una API key de certificación (mk_cert_…) recibe 409 CANAL_FUERA_DE_PRODUCCION: ese documento no tendría valor tributario.

Stock comprometido. Con el inventario encendido y la empresa emitiendo en producción, la orden congela al recibirse lo que reserva en la bodega del canal (reservaStock; un pack, en sus componentes; un servicio o una línea libre, nada). Esa reserva baja el disponible del catálogo de todos los canales que venden de esa bodega mientras la orden está pagada y su documento no se emite. Una pendiente_pago no compromete.

Leer las órdenes. GET .../canales/ordenes lista las de la empresa, de la más nueva a la más vieja y sin sus líneas (cantidadLineas), con los filtros canalId, estado (pendiente_pago, pagada, cancelada), emision (el estado de la emisión), cancelacion (el estado de la cancelación, ver Cancelación de las órdenes), desde/hasta (AAAA-MM-DD, días de Chile), ordenExterna (exacta) y limite (hasta 200, por defecto 50). Devuelve { ordenes, siguienteCursor }: pide con cursor hasta que venga null. GET .../canales/:canalId/ordenes/:ordenId devuelve { orden } completa; una orden de otro canal o de otra empresa responde 404 ORDEN_CANAL_NO_ENCONTRADA.

Emisión de las órdenes

La boleta (39, o 41 si todo es exento) o la factura (33, con receptor) de una orden pagada sale por el mismo camino que POST /dte: el documento se valida otra vez antes de pedir el folio (la configuración, la UF o el stock pudieron cambiar desde que la recibiste), con el inventario, el modo demo y el ambiente de siempre. El documento sale entero de la orden guardada: sus líneas, su receptor, su medio de pago y la bodega y la sucursal que quedaron congeladas al recibirla. Una factura de un canal va al contado: no abre una cuenta por cobrar.

Automática. Si el canal tiene emitirAutomatico (por defecto true), la orden se emite sola en la misma llamada que la deja pagada:

  • POST .../ordenes con una orden nueva y pagada: true;
  • el reenvío con pagada: true que paga una orden pendiente_pago;
  • POST .../ordenes/:ordenId/pagar.

La orden se guarda primero y la emisión va después, fuera de esa escritura: si la emisión falla, la orden queda registrada igual. Por eso el código HTTP es el de la recepción (201 una orden nueva, 200 un reenvío o /pagar) aunque la emisión falle, y el resultado va en emision: estado (el de la emisión de la orden) y, con el documento emitido, documento (el mismo cuerpo del 201 de POST /dte); si no, error (el status y el cuerpo del error, con su code cuando lo tiene). Si el documento sí se emitió pero algo posterior falló (un 500 después del folio), estado es emitida, documento trae emitidaId, tipoDte y folio, y lo que falló va en aviso (nunca en error): la orden tiene su documento. La orden de la respuesta ya trae la emisión al día.

json
{
  "orden": {
    "id": "6708a1c2a1b2c3d4e5f60501",
    "ordenExterna": "WC-10521",
    "estado": "pagada",
    "emision": { "estado": "emitida", "folio": 1043, "tipoDte": 39, "emitidaId": "6708a1c2a1b2c3d4e5f60990", "intentos": 1, "en": "2026-10-10T15:04:06.000Z" },
    "…": "…"
  },
  "repetido": false,
  "sinVincular": [],
  "emision": {
    "estado": "emitida",
    "documento": { "success": true, "emitidaId": "6708a1c2a1b2c3d4e5f60990", "tipoDTE": 39, "folio": 1043, "total": 33460, "…": "…" }
  }
}

Si la emisión no se pudo hacer, la respuesta sigue siendo 201 (o 200):

json
{
  "orden": { "id": "6708a1c2a1b2c3d4e5f60502", "estado": "pagada", "emision": { "estado": "error", "folio": null, "intentos": 1, "…": "…" }, "…": "…" },
  "repetido": false,
  "sinVincular": [],
  "emision": {
    "estado": "error",
    "error": { "status": 400, "error": "Payload inválido", "detalles": ["Stock insuficiente de «Taza» en la bodega…"] }
  }
}

emision solo viene cuando esa llamada intentó emitir. Un reenvío que no cambió nada (repetido: true sobre una orden ya pagada) no vuelve a emitir: devuelve la orden como está, con orden.emision al día. Con emitirAutomatico: false la orden pagada queda con emision.estado: "pendiente" hasta que la emitas.

A pedido: POST .../canales/:canalId/ordenes/:ordenId/emitir (sin cuerpo; canales:escribir, o un admin o un emisor con sesión). Emite una orden pagada con su emisión pendiente, error o rechazada. Responde 201 { orden, dte } con el documento emitido; si no, el status y el cuerpo de la emisión (los mismos de POST /dte) más orden; los 409 de antes de empezar (la orden no se puede emitir ahora) traen su code, sin orden. No hay reintento automático: una emisión en error o rechazada la reintentas tú con /emitir (o el panel). Dos /emitir a la vez sobre la misma orden emiten uno: el otro recibe 409 ORDEN_CANAL_EMISION_EN_CURSO (o ORDEN_CANAL_YA_EMITIDA).

Los estados de orden.emision.estado, y qué hacer en cada uno:

EstadoQué significaQué hacer
pendienteTodavía no se emite (canal sin emitirAutomatico, la emisión automática se cortó antes de empezar, o se agotó el tope de emisiones por minuto: 429 LIMITE_EMISION).POST .../emitir.
emitiendoLa emisión está en curso.Esperar y leer la orden. /emitir responde 409.
emitidaTiene su boleta o factura (folio, tipoDte, emitidaId).Nada. /emitir responde 409 ORDEN_CANAL_YA_EMITIDA con el documento.
inciertaEl envío al SII quedó sin respuesta clara (ENVIO_INCIERTO): el SII puede tener el documento.No la reemitas. Se cierra sola cuando el SII da su veredicto (aceptado: emitida; rechazado: rechazada).
revisarLa emisión se cortó a medias y no hay registro local: el envío pudo salir.No la reemitas. La resuelve un admin en el panel (ligar o liberar); si su documento aparece, el reconciliador la cierra solo.
errorNo hubo documento (validación, stock, sin folios, el SII rechazó la subida…; el detalle en ultimoError).Corrige lo que dice el error y POST .../emitir. Si quedó un documento registrado de ese intento, 409 ORDEN_CANAL_EMISION_CON_DTE (con su emitidaId): ese documento ya existe y no se emite otro.
rechazadaEl SII rechazó el documento (rechazadaId).POST .../emitir (un documento nuevo; puede reusar el folio rechazado si volvió al pool), o reemite ese documento desde Emisión: una de las dos, nunca las dos (la otra responde 409).

No reemitas desde el panel una orden que tu integración reintenta

El corte de «una de las dos» se revisa antes de pedir el folio, pero una reemisión desde Emisión y un /emitir que llegan al mismo tiempo pueden pasar los dos (la ventana incluye el envío al SII): la orden quedaría con dos documentos válidos. El reconciliador lo detecta y avisa a la plataforma una vez por orden («quedó con dos documentos válidos (folio A y folio B): anula uno con nota de crédito»), pero no lo corrige solo. Si tu integración reintenta las órdenes rechazada con /emitir, deja que lo haga ella.

Un caso borde. Una orden recibida con la empresa en certificación y emitida cuando ya está en producción se valida con las reglas de producción (por ejemplo, el inventario exige la variante de un producto con variantes): puede responder 400 en cada intento. No quema folio; la orden queda en error hasta que la canceles.

Una emisión que quedó emitiendo más de 15 minutos la revisa el reconciliador (cada 5 minutos): si encuentra su documento la cierra con él; si no, la deja en revisar y avisa a la plataforma. Nunca la libera sola.

Resolver una emisión en revisión: POST .../canales/:canalId/ordenes/:ordenId/resolver con { "accion": "ligar", "emitidaId": "…", "motivo": "…" } (el SII tiene el documento: la orden queda ligada a él) o { "accion": "liberar", "motivo": "…" } (el SII no lo tiene: vuelve a error y se puede emitir). Solo un admin con sesión, también con el módulo apagado. ligar también sirve para una incierta sin documento ligado. liberar exige una hora desde que empezó la emisión (409 ORDEN_CANAL_EMISION_LIBERACION_PREMATURA, con minutosRestantes) y que no haya un documento local de ella (409 ORDEN_CANAL_EMISION_CON_DTE, con su emitidaId: se liga, no se libera). Responde { orden, accion, resultado }.

Ambiente. Manda quien dispara la emisión, no quien recibió la orden: con la empresa en producción, una API key de certificación (mk_cert_…) que emite (con /emitir, o pagando por reenvío) recibe 409 CANAL_FUERA_DE_PRODUCCION, sin folio. Con la empresa en certificación, o en modo demo, se emite en certificación.

Límite. Recibir una orden y confirmar su pago no consumen el tope de emisiones por minuto de la empresa (solo el techo de escrituras de tu API key). Lo que emite sí: la emisión automática (una vez, solo cuando de verdad va a emitir) y /emitir, en el mismo tope que POST /dte, el punto de venta y el panel (60 por defecto, SII_MAX_EMISIONES_POR_MINUTO). Si el tope está agotado, la emisión automática no emite: la orden queda registrada (y pagada) con emision.estado: "pendiente", y la respuesta trae emision: { "estado": "pendiente", "error": { "status": 429, "code": "LIMITE_EMISION", … } }. Emítela con /emitir en unos segundos. Un 429 de /emitir se reintenta igual.

Cancelación de las órdenes

POST /api/empresas/:empresaId/canales/:canalId/ordenes/:ordenId/cancelar con { "motivo": "…" } (canales:escribir; con sesión, solo un admin: el emisor y el contador reciben 403). El motivo es obligatorio, de 1 a 90 caracteres: va en la referencia de la nota de crédito. En la v1 la cancelación es total: no hay devoluciones parciales.

Sin documento. Una orden pendiente_pago, o pagada sin ningún documento vivo (su emisión pendiente, error o rechazada), pasa a cancelada sin emitir nada y sin pedir folio. Antes se busca cualquier documento de la orden, no solo su emision.estado: una orden en error que dejó un documento registrado (el 409 ORDEN_CANAL_EMISION_CON_DTE de /emitir) se cancela con nota de crédito, nunca sin documento.

Con documento. Una orden emitida se cancela con una nota de crédito 61 CodRef 1 sobre su boleta o factura, por el mismo camino que POST /dte/:id/anular: sus cortes antes del folio, la anulación única (si el documento ya se anuló desde Emisión, se toma esa nota: nota.existente: true) y el ambiente del documento (una API key mk_cert_… que cancela un documento de producción recibe el 403 AMBIENTE_NO_AUTORIZADO de la anulación, sin folio). La orden pasa a cancelada cuando la nota queda registrada.

Modo demo. Una orden emitida en modo demo no se puede cancelar con nota por la API si la empresa ya salió de demo: la anulación responde 422 CONFIG_DISTINTA_DEL_DOCUMENTO (la nota saldría en otro modo que el documento), sin folio, y la cancelación queda en error. Es la misma limitación del punto de venta: se anula recién con la configuración de vuelta en el modo del documento.

Stock. Una orden pagada sin documento deja de comprometer stock apenas se cancela: el disponible del catálogo sube. Con el inventario encendido, la nota de crédito CodRef 1 repone el stock que descontó la boleta o factura.

El dinero lo devuelve tu tienda

Cancelar no registra ningún movimiento de dinero: la devolución al cliente la haces tú, por tu pasarela de pago.

Responde 201 { orden, nota, repetido: false }: nota es null sin documento; con nota, { emitidaId, tipoDte, folio, existente }.

json
{
  "orden": {
    "id": "6708a1c2a1b2c3d4e5f60501",
    "ordenExterna": "WC-10521",
    "estado": "cancelada",
    "canceladaEn": "2026-10-11T13:20:44.000Z",
    "emision": { "estado": "emitida", "folio": 1043, "tipoDte": 39, "emitidaId": "6708a1c2a1b2c3d4e5f60990", "…": "…" },
    "cancelacion": {
      "estado": "emitida",
      "motivo": "Cliente devolvió el pedido",
      "intentos": 1,
      "documento": { "emitidaId": "6708a1c2a1b2c3d4e5f60990", "tipoDte": 39, "folio": 1043 },
      "nota": { "emitidaId": "6708a1c2a1b2c3d4e5f60a11", "tipoDte": 61, "folio": 88 },
      "ultimoError": null,
      "…": "…"
    },
    "…": "…"
  },
  "nota": { "emitidaId": "6708a1c2a1b2c3d4e5f60a11", "tipoDte": 61, "folio": 88, "existente": false },
  "repetido": false
}

Una orden ya cancelada responde 200 con repetido: true y su nota: reintentar es seguro, nunca sale otra. Si la nota no se pudo emitir, la respuesta es el status y el cuerpo de la anulación (los mismos de POST /dte/:id/anular) más orden.

Los estados de orden.cancelacion.estado, y qué hacer en cada uno:

EstadoQué significaQué hacer
sin_documentoCancelada sin nota: no había documento.Nada.
emitiendoLa nota de crédito se está emitiendo.Esperar y leer la orden. /cancelar responde 409.
emitidaLa nota quedó registrada (nota) y la orden está cancelada.Nada.
inciertaEl envío de la nota quedó sin respuesta clara, o el SII la recibió y su registro local falló: el SII puede tener la nota.No la vuelvas a pedir. La resuelve un admin; si su nota aparece aceptada, el reconciliador la cierra solo (la orden queda cancelada), y si el SII la rechazó, la orden vuelve a pagada.
revisarLa nota quedó emitiéndose más de 15 minutos sin registro local: el proceso se cortó. O la orden se canceló sin nota mientras se reemitía su documento rechazado desde Emisión, y la reemisión quedó vigente (ver «En vuelo»).No la vuelvas a pedir. La resuelve un admin; si su nota aparece, el reconciliador la cierra solo.
errorNo hubo nota (un corte antes del folio, sin folios, el 403 del ambiente…; el detalle en ultimoError), o el SII rechazó la nota (ncRechazadaEn: la orden volvió a pagada).Corrige lo que dice el error y POST .../cancelar de nuevo (sale otra nota).

cancelacion trae además motivo, intentos, documento (el que la nota anula: { emitidaId, tipoDte, folio }), nota, ncRechazadaEn, ultimoError, reclamadaEn, en, solicitadaPor y resolucion; la orden trae canceladaEn.

En vuelo. /cancelar responde 409 ORDEN_CANAL_EMISION_EN_CURSO sin tocar la orden ni consumir cupo (primero se resuelve la emisión) en dos casos: con la emisión emitiendo, revisar o incierta (también incierta con su documento), y cuando el documento que la nota anularía está en ENVIO_INCIERTO, en un estado del SII que no conocemos o sin estado: sin veredicto del SII no se anula (trae estado: "incierta" y documento). Un documento que el SII ya recibió y está procesando, o que aceptó, sí se anula, como en POST /dte/:id/anular. Con una cancelación emitiendo, revisar o incierta, 409 ORDEN_CANAL_CANCELACION_EN_CURSO. Dos /cancelar a la vez emiten una nota. /cancelar y /emitir a la vez nunca terminan los dos: o la orden queda cancelada sin documento (y /emitir responde 409 ORDEN_CANAL_CANCELADA), o gana la emisión (/cancelar responde 409) y la cancelas después, con su nota. Mientras una cancelación está en curso, /emitir responde 409 ORDEN_CANAL_CANCELACION_EN_CURSO.

Cancelar mientras se reemite

Lo anterior vale para /emitir, no para una reemisión desde Emisión de su documento rechazada: si alguien la reemite desde el panel mientras tu integración cancela la orden, la cancelación puede salir sin_documento (la reemisión todavía no existía) y la reemisión quedar vigente, sin nota. No se previene, se detecta: el reconciliador (cada 5 minutos) no liga la orden a la reemisión en silencio. La orden vuelve a pagada con su emision en la reemisión y su cancelacion en revisar sobre ella (documento, ultimoError), y avisa a la plataforma una vez («la orden X fue cancelada sin nota, pero la reemisión Y quedó vigente: anúlala con nota de crédito»). Nada sale solo al SII. Se cierra sola cuando aparece la nota que anula la reemisión (anulada desde Emisión); un admin la libera con el resolver, sin esperar la hora, y la vuelves a cancelar (sale la nota); y si el SII rechaza la reemisión, la orden vuelve sola a cancelada sin documento. Si la orden ya estaba cancelada con una nota de otro documento suyo, solo se avisa. No reemitas desde el panel una orden que tu integración puede cancelar.

Si el SII rechaza la nota, no anuló nada: la orden vuelve a pagada, su cancelación a error (con ncRechazadaEn) y se avisa a la plataforma. Cancélala de nuevo: sale otra nota.

Resolver una cancelación en revisión: POST .../canales/:canalId/ordenes/:ordenId/cancelacion/resolver con { "accion": "ligar", "notaId": "…", "motivo": "…" } (el SII tiene la nota: la orden queda cancelada con ella) o { "accion": "liberar", "motivo": "…" } (el SII no la tiene: vuelve a error y se puede cancelar de nuevo). Solo un admin con sesión, también con el módulo apagado. Se resuelve una incierta, una revisar o una emitiendo de más de 15 minutos. ligar exige la nota CodRef 1 que anula ESE documento, en su ambiente y no rechazada. liberar exige una hora desde el reclamo, salvo en la revisar por una reemisión vigente (409 ORDEN_CANAL_CANCELACION_LIBERACION_PREMATURA), que no haya una nota local vigente (409 ORDEN_CANAL_CANCELACION_CON_NC: se liga, no se libera) y que no haya una nota que el SII recibió sin su registro local (409 ORDEN_CANAL_CANCELACION_NC_SIN_REGISTRO: liberar sacaría una segunda nota). Responde { orden, accion, resultado }.

Límite. Cancelar sin documento no consume el tope de emisiones por minuto de la empresa. La nota de crédito sí, una vez y recién con la cancelación reclamada, justo antes de emitirla: dos /cancelar a la vez gastan un cupo, no dos. Con el tope agotado responde 429 LIMITE_EMISION sin nota ni folio, y la cancelación queda en error. Reintenta en unos segundos.

Eventos de los canales

Seis webhooks del módulo, con la misma firma, los mismos reintentos y la misma deduplicación que todos los demás. Salen solo con el módulo encendido y solo a las suscripciones que los escuchan (una suscripción creada antes de ellos no los recibe hasta que se agregan desde el panel).

EventoCuándo sale
orden_canal.recibidaSe registró una orden nueva (codigo ORDEN_NUEVA), o se confirmó el pago de una pendiente_pago con /pagar o con el reenvío pagada: true (codigo PAGO_CONFIRMADO). Un reenvío repetido no lo repite.
orden_canal.emitidaLa orden quedó con su boleta o factura: al emitirla, cuando el reconciliador cierra una emisión cortada o una incierta que el SII aceptó, cuando un admin la liga a su documento, o cuando queda ligada a la reemisión de su documento rechazado. Una emisión incierta no avisa nada hasta su veredicto.
orden_canal.rechazadaEl SII rechazó el documento de la orden (codigo DTE_RECHAZADO): si la orden sigue pagada, vuelve a ser emitible.
orden_canal.canceladaLa orden quedó cancelada: sin documento (SIN_DOCUMENTO), con su nota de crédito registrada (NOTA_DE_CREDITO), o de vuelta sin documento porque el SII rechazó la reemisión que la había reabierto (REEMISION_RECHAZADA). Una nota sin veredicto (incierta) no avisa, salvo cuando un admin la liga en el resolver: ahí avisa aunque siga en ENVIO_INCIERTO; si el SII la rechaza después, llega orden_canal.cancelacion_revertida.
orden_canal.cancelacion_revertidaLa orden salió de cancelada y volvió a pagada: el SII rechazó la nota que la canceló (NOTA_DE_CREDITO_RECHAZADA; se cancela de nuevo), o se canceló sin nota mientras se reemitía su documento y la reemisión quedó vigente (REEMISION_VIGENTE). Ya se te había respondido cancelada: este evento te dice que no lo está.
canal.stock_cambiadoCada minuto, uno por cada canal que tuvo cambios, con lo que cambió de su disponible. Ver abajo.

Una vez por transición. Cada evento de una orden sale después de que el cambio quedó guardado, y solo desde la escritura que lo hizo: dos pedidos a la vez dejan una transición y un evento. Pero una orden puede pasar varias veces por el mismo estado (emitida, rechazada y emitida otra vez; cancelada y revertida), y cada vez avisa: concilia por datos.id y quédate con el de ocurridoEn mayor (no con el último que llega). Los eventos no llegan necesariamente en orden, y el estado es el de la orden cuando se armó el aviso: orden_canal.rechazada puede llegar con estado: "cancelada" (una orden cancelada con nota cuyo documento el SII rechaza después, o la reemisión de una orden reabierta que el SII rechaza mientras el reconciliador la devuelve a cancelada, en cualquier orden). Los datos de un evento de orden:

json
{
  "id": "6707b1c2d3e4f5a6b7c8d901",
  "canalId": "6707a0b1c2d3e4f5a6b7c801",
  "ordenExterna": "WOO-10234",
  "estado": "cancelada",
  "emision": { "estado": "emitida" },
  "cancelacion": { "estado": "emitida" },
  "documento": { "id": "6707b2c3d4e5f6a7b8c9d012", "tipo": 39, "folio": 1043, "ambiente": "produccion" },
  "notaCredito": { "id": "6707b3c4d5e6f7a8b9c0d123", "tipo": 61, "folio": 88, "ambiente": "produccion" },
  "motivo": "Cliente desistió",
  "codigo": "NOTA_DE_CREDITO"
}
  • estado, emision.estado y cancelacion.estado son los que dejó la transición (cancelacion es null si nunca se canceló).
  • documento: el DTE del evento (el emitido, el rechazado, el que la nota anula o el que sigue vigente); null en recibida y en una cancelación sin documento. Su id es el de los eventos dte.*. notaCredito: la nota de la cancelación, o la nota rechazada en una revertida.
  • motivo: en cancelada, el que mandaste al cancelar; en rechazada y cancelacion_revertida, qué pasó. Nunca viajan montos, costos, el receptor, las líneas, el PDF ni el XML: lee la orden si los necesitas.

canal.stock_cambiado. Un cron (cada minuto) recorre los canales activos de las empresas que lo escuchan y, por canal, mira qué cambió desde la corrida anterior con la misma consulta y la misma fórmula del catálogo (modificadoDesde): el stock en su bodega, lo comprometido por notas de venta y por órdenes pagadas sin emitir, y los ítems y variantes. Si cambió el canal (cualquier dato suyo: su colchón, su bodega, su nombre…), la bodega o la configuración del inventario o de ventas, cuenta el catálogo entero (completo: true). Sin cambios no hay evento; con cambios, uno por canal por corrida:

json
{
  "canalId": "6707a0b1c2d3e4f5a6b7c801",
  "bodegaId": "6707a0b1c2d3e4f5a6b7c802",
  "modificadoDesde": "2026-10-10T15:00:00.000Z",
  "generadoEn": "2026-10-10T15:01:00.000Z",
  "completo": false,
  "truncado": false,
  "items": [
    { "itemId": "6707a1b2c3d4e5f6a7b8c901", "varianteId": null, "sku": "TAZA-01", "disponible": 7 }
  ]
}
  • items trae a lo más 100 entradas, solo de lo que controla stock, con el mismo disponible del catálogo. Con más, truncado: true: aplica las que vienen y sincroniza con GET .../catalogo?modificadoDesde= (el modificadoDesde del evento), con su cursor hasta el final.
  • Puede repetirse. Cada corrida mira desde 120 segundos antes del inicio de la anterior (el margen del catálogo): un cambio llega en dos o tres eventos seguidos. Aplica disponible de forma idempotente, por itemId/varianteId, y manda el evento de generadoEn mayor, no el último que llega: un reintento de la cola de webhooks puede llegar después de un evento más nuevo con un disponible viejo.
  • La primera corrida de cada canal solo fija desde dónde mirar: parte de tu sincronización completa. Si dejas de escuchar el evento y vuelves, el canal sigue desde donde quedó: el primer evento puede venir completo o truncado. Lo que el catálogo incremental no detecta (una reserva que vence sola, un lote que vence, un ítem que se desactiva) tampoco sale acá: la sincronización completa diaria sigue.

Scopes de los canales

  • canales:leer: la configuración, los canales, el catálogo de cada canal y sus órdenes.
  • canales:escribir: el permiso del integrador de un canal: enviar sus órdenes, confirmar su pago, emitir su boleta o factura (/emitir) y cancelarlas (/cancelar, con su nota de crédito si se emitieron). Configurar el módulo, crear o editar canales y resolver una emisión o una cancelación en revisión siguen siendo solo con sesión.

Una key con canales:escribir emite boletas y facturas de las órdenes de sus canales, y sus notas de crédito al cancelarlas (sin pedir además dte:emitir ni dte:anular, a propósito): dásela solo a la integración de la tienda.

Ninguno de los dos viene en una key nueva: se conceden a propósito.

Códigos de los canales de venta

codeHTTPCuándo
PLAN_SIN_ERP403La empresa no tiene MiAplicación ERP.
PLAN_SIN_CANALES403Encender el módulo, o crear o reactivar un canal, sin un plan ERP que lo habilite. Trae requiere: erp y planSugerido. No se escribió nada.
PLAN_LIMITE_CANALES409Crear o reactivar un canal con los canales activos en el tope del plan (trae plan, planSugerido, canalesMax y canalesActivos). Antes del 14-10-2026 era 403.
CANALES_INACTIVO409Cualquier ruta de canales que no es la configuración, con el módulo apagado.
CANAL_NO_ENCONTRADO404El canal no existe, es de otra empresa o el id no es válido.
BODEGA_DE_OTRA_SUCURSAL422Crear un canal, o cambiarle la sucursal o la bodega, con una bodega de OTRA sucursal (null y la matriz son la misma; sin sucursales, todo es matriz). Todos los errores en detalles[]; no se escribió nada.
CANAL_INACTIVO409Leer el catálogo de un canal desactivado o enviarle una orden nueva (el reintento de una ya registrada la devuelve).
DATOS_INVALIDOS400La configuración o un canal traen datos inválidos, una sucursal o bodega ajena o desactivada, o un nombre repetido; el query del catálogo o del listado de órdenes es inválido; o una orden trae una forma inválida o un producto de otra empresa (todos en detalles[]).
ORDEN_CANAL_CONFLICTO409La misma ordenExterna ya se recibió en ese canal con otro cuerpo (trae ordenId). No cambió nada.
ORDEN_CANAL_MONTOS422El total pagado no cuadra con las líneas, el envío y el descuento, o el descuento del pedido supera el subtotal (trae montos). No se escribió nada.
ORDEN_CANAL_DOCUMENTO_INVALIDO422La boleta o factura de la orden no se podría emitir (el RUT del receptor, la sucursal, una boleta sobre 135 UF sin receptor, una factura sin monto afecto…; todo en detalles[]). No se escribió nada.
ORDEN_CANAL_NO_ENCONTRADA404La orden no existe, es de otro canal o de otra empresa, o el id no es válido.
ORDEN_CANAL_CANCELADA409Pagar una orden cancelada con /pagar, reenviarla con pagada: true si nunca se pagó (trae ordenId), o emitirla.
ORDEN_CANAL_LINEA_EN_CERO422Una línea queda en $0 por su descuento, por el descuento del pedido o, en una factura, al pasar a neto. No se escribió nada.
CANAL_FUERA_DE_PRODUCCION409Enviar una orden, o emitirla, con una API key de certificación (mk_cert_…) a una empresa que emite en producción; o ligar una emisión en revisión a un documento de certificación o demo. No se escribió ni se emitió nada.
CANAL_SIN_EMISION_CONFIGURADA422Enviar o emitir una orden en una empresa sin la emisión configurada (certificado, CAF y datos del emisor).
CONFIG_EMISION_NO_DISPONIBLE503No se pudo leer la configuración de emisión al recibir o emitir una orden. Reintenta con el mismo cuerpo.
ORDEN_CANAL_NO_PAGADA409Emitir una orden pendiente_pago: se emite cuando se confirma el pago.
ORDEN_CANAL_NO_EMITIBLE409La orden o su emisión están en un estado que no se emite.
ORDEN_CANAL_EMISION_EN_CURSO409La orden se está emitiendo (otro /emitir a la vez, o una emisión automática en curso), o se pidió cancelarla con su emisión emitiendo, revisar o incierta, con o sin documento (trae estado), o con el documento que se anularía sin veredicto del SII: ENVIO_INCIERTO, un estado desconocido o ninguno (trae estado: "incierta" y documento). No se tocó la orden ni se consumió cupo. Espera y léela.
ORDEN_CANAL_EMISION_EN_REVISION409La emisión quedó en revisar: no se emite hasta que un admin la resuelva.
ORDEN_CANAL_YA_EMITIDA409La orden ya tiene su documento, o quedó incierta (trae documento: { estado, emitidaId, tipoDte, folio }). No la reemitas.
ORDEN_CANAL_EMISION_REEMITIDA409El documento rechazado de la orden ya se reemitió: no se emite otra vez desde la orden.
ORDEN_CANAL_EMISION_CON_DTE409La emisión anterior dejó un documento registrado (trae emitidaId, tipoDte y folio): no se vuelve a emitir ni se libera; se liga.
ORDEN_CANAL_EMISION_NO_EN_REVISION409Resolver una emisión que no está en revisión (o una incierta ya ligada a su documento).
ORDEN_CANAL_EMISION_LIBERACION_PREMATURA409Liberar una emisión en revisión antes de una hora desde que empezó (trae minutosRestantes).
DTE_NO_ENCONTRADO404Ligar a un documento que no existe en la empresa.
DTE_DE_OTRA_ORDEN409Ligar a un documento que no es el de esa orden (otro tipo u otra orden).
DTE_ANTERIOR_A_LA_EMISION409Ligar a un documento emitido antes de que empezara esa emisión.
CONVERSION_REEMPLAZADA409Reemitir (desde Emisión) el documento rechazado de una orden que ya se volvió a emitir: la orden saldría dos veces. No se tocó el folio.
CANALES_EMISIONES_EN_VUELO409Apagar el módulo con órdenes cuya emisión está emitiendo o revisar (las nombra detalles[]).
LIMITE_EMISION429Dentro de emision.error de la emisión automática: el tope de emisiones por minuto de la empresa estaba agotado; la orden quedó registrada con su emisión pendiente: emítela con /emitir. Al cancelar con nota de crédito, como respuesta directa: no salió nota ni se pidió folio, y la cancelación quedó en error; reintenta en unos segundos.
ORDEN_CANAL_CANCELACION_EN_CURSO409Cancelar una orden con su cancelación emitiendo, revisar o incierta (trae estado), emitirla mientras se cancela, o la orden cambió mientras se cancelaba.
ORDEN_CANAL_CON_DOCUMENTO409Cancelar una orden cuyo documento rechazado ya se reemitió (trae emitidaId, tipoDte y folio): tiene documento. El reconciliador la liga en unos minutos; después se cancela con su nota.
ORDEN_CANAL_VARIOS_DOCUMENTOS409La orden tiene más de un documento vivo sin anular (trae documentos): una cancelación anula uno. Anula los demás desde Emisión y vuelve a cancelarla.
ORDEN_CANAL_SIN_DTE409La orden figura emitida pero su documento no está registrado: no se puede anular.
ORDEN_CANAL_CANCELACION_NO_EN_REVISION409Resolver una cancelación que no está incierta, revisar ni emitiendo hace más de 15 minutos.
ORDEN_CANAL_CANCELACION_LIBERACION_PREMATURA409Liberar una cancelación antes de una hora desde su reclamo (trae minutosRestantes). No aplica a la revisar por una reemisión vigente.
ORDEN_CANAL_CANCELACION_CON_NC409Liberar una cancelación cuyo documento tiene una nota de crédito local vigente (trae notaId): se liga, no se libera.
ORDEN_CANAL_CANCELACION_NC_SIN_REGISTRO409Liberar una cancelación cuya nota el SII recibió sin registro local, o cuya anulación se cortó a medias (trae folio): liberar sacaría una segunda nota.
NC_NO_ENCONTRADA404Ligar una cancelación a una nota que no existe en la empresa.
NC_DE_OTRO_DOCUMENTO409Ligar a una nota que no es la 61 CodRef 1 que anula el documento de la orden, en su ambiente.
NC_RECHAZADA409Ligar a una nota que el SII rechazó.
CUENTA_DEMO_RESTRINGIDA403La cuenta demo compartida no configura el módulo ni sus canales.

Una empresa ajena responde 403 Solo puedes acceder a los canales de venta de tu propia empresa.

Errores

Los errores no son uniformes

Hay tres formas según el módulo, y es un hecho del sistema, no una simplificación de esta documentación: los módulos vienen de orígenes distintos y unificarlos rompería a los consumidores existentes. Tu manejador de errores tiene que reconocer las tres.

Forma A — { error, detalles[] }

Emisión (/dte), configuración y listados (/sii-emision), contabilidad.

json
{
  "error": "Payload inválido",
  "detalles": [
    "El DTE 33 exige el giro del receptor.",
    "items[0]: \"cantidad\" debe ser un número > 0."
  ]
}

detalles puede ser null cuando el error no tiene desglose. La emisión agrega errorType ("NO_FOLIOS", "CAF_VENCIDO", "ENVIO_INCIERTO" o null). Los dos primeros van con 409 y con tipoDte, y en los dos no se consumió ningún folio: el error salta al pedirlo. El tercero va con 502, emitidaId, folio y tipoDte, y es el caso contrario: el folio se consumió y el SII puede tener el documento, así que no se reintenta (ver Envío incierto).

Los tres endpoints que emiten (POST /dte, POST /dte/:id/anular y la reemisión desde el panel) usan esta misma forma y este mismo errorType: un solo manejador sirve para los tres.

Los cortes de anulación, y la consulta de estado de un envío incierto, agregan code a esta misma forma (con error, no con message). En ninguno se consumió folio:

codeHTTPQué significa¿Reintentar?
DOCUMENTO_YA_ANULADO409El documento ya tiene una nota que lo anula no rechazada (61 CodRef 1; o 56 CodRef 1 si es una nota de crédito). notaCredito —o notaDebito— trae id, folio y estadoSii.No. Solo si el SII rechaza esa nota (o, si está en ENVIO_INCIERTO, cuando se resuelva como no recibida), o si esa nota es una 61 y el SII acepta una nota de débito 56 que la anula.
ANULACION_EN_CURSO409Otra petición está anulando ese documento ahora.No a ciegas: consulta el documento; si esa anulación falló sin nota, vuelve a intentarlo.
CONFIG_DISTINTA_DEL_DOCUMENTO422La nota (al anular) o la reemisión saldría en otro modo (demo / folios propios) que el documento. Un ambiente distinto ya no corta: sale en el del documento. No sale en POST /dte ni en el lote.No: primero vuelve la configuración al modo del documento.
AMBIENTE_NO_AUTORIZADO403Se pidió producción (en el payload, o por el ambiente del documento que se anula o se reemite) con la empresa en certificación, y la credencial no es una key mk_prod_ ni un usuario admin/superadmin. O la credencial es una key mk_cert_, que no escribe en producción aunque la empresa esté en producción (desde el 29-09-2026).No con la misma credencial: usa una key mk_prod_ o un usuario admin/superadmin.
AMBIENTE_MODO_DEMO422La empresa está en modo demo y se pidió producción.No: quita ambiente o manda certificacion.
RESOLUCION_DEL_AMBIENTE_INVALIDA422Falta (o no sirve) la resolución del SII del ambiente pedido; detalles[] dice qué falta y cómo cargarla.Después de cargarla.
LOTE_AMBIENTE_NO_DISPONIBLE422En un lote, algún documento pide un ambiente en el que no se puede emitir (demo o resolución); detalles[] va indexado y no se creó el lote.Después de corregir el lote.
CONFIG_EMISION_INVALIDA422La configuración de emisión no sirve para emitir (no existe, desactivada, sin certificado, emisor demo no disponible). El texto es el de la configuración.No: primero corrige la configuración.
CONFIG_EMISION_NO_DISPONIBLE503No se pudo leer la configuración de emisión (base de datos no disponible). POST /dte, el lote y la emisión masiva la leen siempre antes de validar; al anular, sin ella no se verifica la doble anulación.Sí, en unos minutos.
LISTAS_PRECIO_NO_DISPONIBLES503Solo con una línea con itemId y sin precio en un documento que vende: no se pudieron leer las listas de precios de ventas. Con otros errores en el payload, es el 400 con todos. No se consumió folio.Sí, en unos minutos.
DTE_CON_DEVOLUCIONES_PARCIALES409Al anular (POST /dte/:id/anular, o POST /dte y el lote con una 61 CodRef 1) el documento de una venta del punto de venta con devoluciones parciales vigentes: anularlo entero acreditaría otra vez lo devuelto. No se consumió folio.No: lo que queda se devuelve con «Devolver el resto» del punto de venta.
STOCK_INSUFICIENTE409Inventario con bloquearSinStock: otra venta se llevó el stock entre la validación y la reserva. detalles[] trae objetos.Sí, con menos cantidad o después de reponer.
INVENTARIO_INVALIDO400Inventario: la revalidación dentro de la reserva encontró un problema (una serie que otro documento tomó).Después de corregir el payload.
INVENTARIO_NO_REVERTIDO503Reemisión con inventario: no se pudo revertir lo que movió el documento rechazado.Sí, en unos minutos.
ENVIO_INCIERTO_SIN_TRACKID422GET /dte/:id/estado de un documento en ENVIO_INCIERTO: no hay trackid, pero el SII puede tenerlo.No lo reemitas: consúltalo por folio mientras se resuelve.

En un lote, los códigos de anulación llegan en el errorType del documento fallido, sin folio. El lote, además, usa code propios en su respuesta: LOTE_INVALIDO, LOTE_PAYLOAD, LOTE_ID_INVALIDO, LOTE_NO_ENCONTRADO y LOTE_ERROR_INTERNO. El timbraje también usa esta forma con code (TIMBRAJE_*, ver Quedarse sin folios): el texto va en error, no en message.

Forma B — { code, message, detalle }

Auditoría del SII (/auditoria-tributaria).

json
{
  "code": "SII_AUTH_CHALLENGE",
  "message": "El SII pidió una verificación adicional que no podemos resolver automáticamente.",
  "detalle": { "endpointId": "rcv_resumen" }
}

El code mapea a un HTTP fijo:

codeHTTPQué significa¿Reintentar?
SII_AUTH401El SII rechazó RUT o clave tributaria.No: hay que corregir la credencial.
SII_AUTH_CHALLENGE409El SII pidió ClaveÚnica, captcha, SMS o cambio de clave.Nunca: el SII bloquea la cuenta tras varios intentos.
SII_RATE_LIMIT429Rate limiting no documentado del portal.Más tarde.
SII_MAX_SESIONES429Demasiadas sesiones abiertas para ese RUT.Sí, tras cerrar sesión o esperar.
SII_SCHEMA_CHANGED502La respuesta del SII no calza con el schema esperado.No: cambió el portal.
SII_NETWORK504Red, DNS o timeout contra el portal.Sí: el único reintentable por diseño.
SII_CIRCUIT_OPEN503Circuit breaker abierto tras fallos consecutivos.Más tarde.
SII_CONFIG400Falta configuración (RUT, clave o clave maestra).No.
SII_CLIENTE_NO_IMPLEMENTADO501Ese endpoint del portal aún no está habilitado.No.
SII_ERROR502Error genérico del módulo.—
ERROR_INTERNO500Bug nuestro.—

Ningún error de este módulo lleva la clave tributaria, cookies ni el HTML completo de la respuesta del SII.

Forma C — { msg }

Solo la autenticación. Ver Autenticación.

json
{ "msg": "API key inválida" }

Errores internos (500) y valores inválidos (400)

Un 500 es, por lo general, un error nuestro: la base de datos no respondió, un bug. El cuerpo trae un texto genérico, en error (o en message en auditoría, forma B con code: "ERROR_INTERNO"), que no trae el detalle técnico: ese detalle queda en nuestro registro y nunca llega en la respuesta, así que el cuerpo no te dice si reintentar sirve.

  • Reconoce el 500 por el status, no por el texto. El texto cambia según la ruta y no sigue un patrón único. Un error que no atrapa ningún controlador (por ejemplo, uno que salta antes de llegar a la ruta) responde { "error": "Error interno del servidor" }. Algunos 500 traen además un code propio (por ejemplo LOTE_ERROR_INTERNO en el lote o TIMBRAJE_PERSISTENCIA en el timbraje).
  • No reintentes a ciegas, y menos una escritura: consulta primero el estado real (el documento, el lote o el listado incremental) y, si se repite, repórtalo.
  • Una excepción: GET /dte/:id/estado también responde 500 cuando falla la configuración de emisión o la consulta al SII, y en ese caso sí conserva el texto de la causa (por ejemplo, que la emisión directa está desactivada).

En la mayoría de las rutas de /dte y /sii-emision (y en banco/… y cierre de contabilidad), un valor que la base de datos no puede convertir al tipo del campo (un CastError: un id que no es id, un número que llega como texto imposible de convertir) no es un 500: es un 400 que nombra el campo, sin el texto interno. Si no se sabe qué campo fue, el texto es Uno de los campos tiene un valor inválido.

json
{ "error": "El campo \"empresaId\" tiene un valor inválido." }

Las excepciones responden ese mismo caso (un CastError que sale de la base de datos) con su 500: la configuración (GET /sii-emision), los libros IECV, el lote, GET /api/me, auditoría y las rutas de contabilidad que no son banco/… ni cierre. En banco/movimientos, banco/resumen y cierre/:anio, además, un rechazo que no es interno sale como 400 con su propio mensaje.

En contabilidad, un :empresaId malformado no llega a la base: se revisa antes, en todas sus rutas, y responde 400 { "error": "El campo \"empresaId\" tiene un valor inválido." }. La excepción del 500 aplica solo a los demás valores.

X-Request-Id: anótalo junto a cada error

Toda respuesta, éxito o error (también un 404 o un 429), trae la cabecera X-Request-Id: un UUID distinto por petición. Guárdalo en tu log junto al status y el cuerpo del error: con él ubicamos esa petición exacta en el registro de peticiones cuando nos escribas. El id lo genera la API: si mandas tu propio X-Request-Id, se ignora. El SDK de Node lo deja en error.requestId.

http
X-Request-Id: 3f1c9a52-7d0e-4b8a-9c41-2e6f0b7d5a13

Cómo manejarlas en una sola función

javascript
function describirError(status, cuerpo) {
  if (cuerpo?.msg) return cuerpo.msg;                             // forma C
  // forma B, o forma A con `code` (anulación, lote): el texto va en `message` o en `error`
  if (cuerpo?.code) return `[${cuerpo.code}] ${cuerpo.message ?? cuerpo.error}`;
  const base = cuerpo?.error ?? `HTTP ${status}`;                 // forma A
  return cuerpo?.detalles?.length ? `${base}: ${cuerpo.detalles.join(' ')}` : base;
}

Límites de tasa

Todos con ventana de un minuto, salvo el del timbraje y el del precheck de la cesión, que son por hora.

LímiteCuenta porDefaultAplica a
GlobalIP300/minTodo /api.
Escritura por keyAPI key60/min, o el de tu planLos POST con scope: emitir, emitir por lote, anular, enviar correo y timbrar (POST /sii-emision/timbraje, que además tiene el suyo).
Lectura por keyAPI key240/min, o el de tu planLos GET con scope, incluido /api/me.
Emisiónempresa60/min, o el de tu planPOST /dte y POST /dte/:id/anular.
Lotesempresa3/minPOST /dte/lote, aparte del de emisión: una petición de lote compromete hasta SII_LOTE_MAX_DOCUMENTOS folios, así que el techo de folios por minuto es SII_MAX_LOTES_POR_MINUTO × SII_LOTE_MAX_DOCUMENTOS (300 con los defaults). El lote no descuenta del cupo de emisión ni al revés; el 429 dice cuál se agotó.
Correoempresa10/minPOST /dte/:docId/enviar-correo.
Correo de ventasempresa10/minPOST …/ventas/documentos/:documentoId/enviar, con su propio contador.
TimbrajeAPI key10/horaPOST /sii-emision/timbraje, además del cupo de escritura. Por hora y no por minuto porque timbrar es una operación de cada varios días: lo que protege es tu cuota de folios en el SII, que es finita y no se devuelve. El dry: true también descuenta.
Precheck de la cesiónempresa (sus API keys)30/horaGET …/cesiones/precheck/:emitidaId y GET …/cesiones/recibidas/:tenenciaId/precheck, con un solo contador, además del cupo de escritura (SII_MAX_PRECHECKS_CESION_POR_HORA). Cada precheck consulta al SII con el certificado de la empresa. Con soloDeclaracion=1 no cuenta.
Consulta públicaIP30/min/api/publico/boletas/… (la consulta y su PDF).
Verificación por enlace/QRIP30/minGET /api/publico/documentos/verificar/:token. Contador aparte del de la consulta de boletas.
Catálogo de planesIP30/minGET /api/publico/planes.
CotizaciónIP60/minPOST /api/publico/cotizar.
Registro del SIIIP10/minGET /api/publico/sii/empresa/:rut.
Cotización pública (ver)IP30/minGET /api/publico/cotizaciones y su PDF.
Cotización pública (responder)IP10/minPOST /api/publico/cotizaciones/aceptar y /rechazar.
Página de estadoIP30/minGET /api/publico/estado (RATE_LIMIT_ESTADO), con contador propio: un monitor que la consulta seguido no le gasta la cuota a la consulta de boletas. La respuesta se guarda 60 s, así que más de una consulta por minuto no trae nada nuevo.
DocumentaciónIP30/minGET /api/docs, GET /api/docs/openapi.json y GET /api/docs/miaplicacion.postman_collection.json, con un solo contador. Contador aparte del de la consulta pública a propósito: leer el manual no puede gastarle cuota a la consulta de boletas que el SII exige.

Los limitadores por credencial existen para que un integrador descontrolado no se coma la cuota de la empresa entera: si un POS entra en bucle, el techo de su propia key lo frena antes de tocar el contador compartido, y el e-commerce que factura con la misma razón social sigue trabajando. No aplican a usuarios humanos con JWT: una persona haciendo clic en el panel no es un bucle.

Por plan

Desde el 15-10-2026, la escritura y la lectura por key y la emisión por empresa dependen del plan efectivo de la empresa: el de la contratación vigente o, si venció, el de la última pagada. Por minuto:

PlanLectura por keyEscritura por keyEmisión por empresa
API Emprende · ERP Pyme2406060
API Negocio · ERP Negocio3609090
API Crecimiento · ERP Full480120120
API Alto volumen960240180
API Corporativo · ERP Corporativo1.200300240
Sin plan2406060
  • Los mismos números vienen en limitesDeTasa de cada plan del catálogo público (GET /api/publico/planes).
  • Ningún plan baja los topes de antes: la fila «Sin plan» es el piso.
  • Si no se puede leer el plan de la empresa, se aplica la fila «Sin plan». Nunca queda sin límite.
  • Un cambio de plan tarda hasta un minuto en notarse.
  • El techo Global por IP (300/min, todo /api) corre antes que estos y cuenta todas las peticiones que salen de tu IP.
  • No hace falta adivinar: RateLimit-Policy dice en cada respuesta el cupo que te aplica.

Cabeceras

Cada respuesta que pasa por un limitador trae las cabeceras de draft-ietf-httpapi-ratelimit-headers-11, con un elemento por limitador, en el orden en que corrieron:

http
RateLimit-Policy: "apikey-escritura";q=60;w=60, "emision";q=60;w=60
RateLimit: "apikey-escritura";r=57;t=43, "emision";r=59;t=43
  • RateLimit-Policy: el cupo de cada limitador, q peticiones cada w segundos.
  • RateLimit: lo que queda de cada uno, r peticiones y t segundos hasta que su contador vuelve a cero.
  • Los nombres: apikey-lectura, apikey-escritura y apikey-timbraje (por key); emision, lote, masiva, correo, correo-masivo, zip, ventas-correo, estado-reclamo, reclamo-accion, carga-stock y cesion-precheck (por empresa).

Siguen además las tres de antes, con los números del último limitador de la cadena (en POST /dte, el de emisión):

http
RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 43

Retry-After aparece solo al exceder un límite, junto al 429, y manda sobre RateLimit: espera esos segundos. El mensaje del 429 dice cuál cupo se agotó, porque desde la misma key ves varios techos distintos. Respétalo: reintentar antes solo suma al contador.

http
HTTP/1.1 429 Too Many Requests
Retry-After: 43
RateLimit-Policy: "apikey-escritura";q=60;w=60
RateLimit: "apikey-escritura";r=0;t=43

{ "error": "Esta API key superó su límite de escrituras por minuto (emitir, anular, ceder, timbrar folios y las demás operaciones que escriben). Reintenta en unos segundos." }

En el navegador, X-Request-Id, RateLimit, RateLimit-Policy y Retry-After se pueden leer desde otro origen permitido. El techo Global todavía responde en el formato anterior (RateLimit-Policy: 300;w=60), pero en una ruta con limitador con nombre ese queda reemplazado por la lista de arriba.

Webhooks

En vez de encuestar el estado de cada documento, recibe un POST cuando el SII entrega su veredicto.

La gestión de webhooks se hace desde el panel

Crear, editar, revocar, probar y ver el historial de entregas exige un usuario humano: una API key no puede administrar suscripciones. Lo que sigue describe cómo recibir las entregas.

Los 20 eventos

EventoCuándo
dte.aceptadoEl SII aceptó el documento.
dte.aceptado_reparosAceptado con reparos.
dte.rechazadoRechazado por el SII.
dte.reemitidoEl documento se reemitió (folio nuevo tras un rechazo).
folios.bajosLos folios disponibles de un tipo bajaron del umbral. Sale en una revisión horaria, no en el momento.
inventario.stock_bajoUn saldo de inventario quedó bajo el stock mínimo del ítem (una vez por cruce).
inventario.lote_por_vencerUn lote con stock vence dentro de los días de aviso de la empresa.
inventario.lote_vencidoUn lote venció con stock.
cxc.pago_registradoSe registró un pago recibido.
cxc.pago_anuladoSe anuló un pago recibido.
nota_venta.confirmadaUna nota de venta pasó a confirmada.
nota_venta.convertidaUna nota de venta se convirtió a DTE (trae el DTE).
cotizacion.aceptadaUna cotización quedó aceptada: por el cliente desde el enlace o por alguien de la empresa.
cotizacion.rechazadaUna cotización quedó rechazada, igual.
orden_canal.recibidaSe registró una orden de un canal de venta, o se confirmó su pago.
orden_canal.emitidaLa orden de un canal quedó con su boleta o factura.
orden_canal.rechazadaEl SII rechazó el documento de una orden de un canal.
orden_canal.canceladaUna orden de un canal quedó cancelada (sin documento o con su nota de crédito).
orden_canal.cancelacion_revertidaUna orden cancelada volvió a pagada (la nota fue rechazada, o una reemisión quedó vigente).
canal.stock_cambiadoCambió el stock disponible de un canal (uno por canal por minuto, coalescido).
cxp.pago_registradoSe registró un pago a un proveedor.
cxp.pago_anuladoSe anuló un pago a un proveedor.

Los tres de inventario solo existen con el módulo encendido; su datos, en Inventario. Los seis de ventas y cobranza, solo con el módulo de ventas encendido; su datos, más abajo. Los seis de los canales de venta, solo con ese módulo encendido; su datos, en Eventos de los canales. Los dos cxp.*, solo con el módulo de compras encendido; su datos, más abajo. Una suscripción creada antes de los de canales o de los cxp.* conserva su lista de eventos: para recibirlos, agrégalos desde el panel (una nueva sin eventos escucha todos).

El botón «probar» del panel manda un evento sintético webhook.prueba, que no representa ningún hecho de negocio.

Simular eventos (estados forzables)

POST /api/empresas/:empresaId/webhooks/simular con { "evento": "dte.rechazado" } (y opcional suscripcionId) encola ese evento con datos de ejemplo a las suscripciones activas de la empresa que lo escuchan. Sale por la misma cola, con los mismos reintentos y la misma firma que un evento real; datos trae la forma del real más "simulado": true. Nunca toca un documento.

  • Quién: una empresa sandbox (su admin en el panel o sus keys) o una key mk_cert_. Con un JWT o una key mk_prod_ de una empresa que no es sandbox, 403 SIMULACION_NO_DISPONIBLE. Scope dte:emitir; 10 por minuto por empresa y credencial.
  • Un evento fuera del catálogo (o webhook.prueba): 400 con eventos[]. Una suscripción de otra empresa o revocada: 404; una que no escucha el evento: 422.
  • Respuesta 202: { evento, simulado: true, encoladas, entregas: [{ entregaId, suscripcionId }], mensaje }.

Cuerpo y cabeceras

json
{
  "evento": "dte.aceptado",
  "entregaId": "66f0b3c4d5e6f70819203040",
  "ocurridoEn": "2026-09-04T18:31:02.881Z",
  "empresaId": "66e0000000000000000000a1",
  "datos": {
    "id": "66f0a1b2c3d4e5f607182930",
    "tipo": 33,
    "folio": 1042,
    "estado": "ACEPTADO",
    "trackid": "1234567890",
    "ambiente": "certificacion",
    "fechaEmision": "2026-09-04",
    "montoTotal": 119000,
    "receptor": { "rut": "76123456-0" }
  }
}

En folios.bajos, datos es { tipoDte, disponibles, umbral }. El payload lleva lo justo para identificar el documento: el correo y el teléfono del receptor están guardados pero no viajan.

Datos de los eventos de ventas y cobranza

Salen después de que el cambio quedó guardado (nunca desde una transacción que después se deshizo) y una sola vez por cambio: repetir un pedido idempotente no los repite. Del cliente viaja solo el RUT; nunca su razón social, correo ni teléfono, ni la referencia o el motivo de un pago, ni el nombre, el comentario o la IP de quien respondió una cotización. cxc.pago_registrado (en cxc.pago_anulado va lo mismo con "estado": "anulado" y anuladoEn):

json
{
  "id": "6706a1b2c3d4e5f607182931",
  "fecha": "2026-10-05",
  "medioPago": "transferencia",
  "cuentaDestino": "banco",
  "monto": 50000,
  "estado": "vigente",
  "cliente": { "rut": "76086428-5", "contactoId": "6705f2c1a1b2c3d4e5f60720" },
  "imputaciones": [
    { "cuentaId": "6705f9a1b2c3d4e5f6071801", "emitidaId": "6705f8a1b2c3d4e5f6071701", "tipoDte": 33, "folio": 1042, "monto": 50000 }
  ]
}

cxp.pago_registrado (en cxp.pago_anulado va lo mismo con "estado": "anulado" y anuladoEn). Salen después de que el pago quedó guardado, solo si el módulo de compras sigue encendido, y una sola vez. Del proveedor viaja solo el RUT; beneficiario es el cesionario de una factura cedida (solo su RUT) o null; nunca la razón social, la referencia ni el motivo. emitidaId va solo en la cuenta de una factura de compra 46 emitida:

json
{
  "id": "6706b2c3d4e5f60718293a41",
  "fecha": "2026-10-05",
  "medioPago": "transferencia",
  "cuentaDestino": "banco",
  "monto": 119000,
  "estado": "vigente",
  "proveedor": { "rut": "76543210-3", "contactoId": null },
  "beneficiario": null,
  "imputaciones": [
    { "cuentaId": "6705faa1b2c3d4e5f6071901", "emitidaId": null, "tipoDte": 33, "folio": 1520, "monto": 119000 }
  ]
}

nota_venta.confirmada:

json
{
  "id": "6705fa11b2c3d4e5f6071901",
  "numero": 18,
  "fechaEmision": "2026-10-09",
  "contactoId": "6705f2c1a1b2c3d4e5f60720",
  "vendedorId": "6705f2c1a1b2c3d4e5f60730",
  "cliente": { "rut": "76086428-5" },
  "tipoDteSugerido": 33,
  "total": 119000,
  "reserva": true,
  "reservaHasta": "2026-10-16"
}

nota_venta.convertida lleva los mismos campos de la nota (sin reserva ni reservaHasta) y el DTE: "dte": { "id", "tipo": 33, "folio": 1043, "estado": "emitida" }. estado es el de la conversión: emitida, o incierta si el envío al SII quedó sin veredicto. Si el SII rechaza ese DTE la nota vuelve a confirmada sin evento propio (escucha dte.rechazado), y una nueva conversión manda otro nota_venta.convertida con el DTE nuevo. Por eso puede llegar más de un nota_venta.convertida para la misma nota: concílialos por dte.id (no por el id de la nota); el vigente es el del último DTE no rechazado. cotizacion.aceptada y cotizacion.rechazada llevan los mismos campos de la nota (sin reserva), más fechaVencimiento y porElCliente: true si la respondió el cliente desde el enlace público, false si la marcó alguien de la empresa.

http
Content-Type: application/json
X-MiAplicacion-Firma: t=1788556262,v1=9f86d081884c7d659a2feaa0c55ad015…
X-MiAplicacion-Evento: dte.aceptado
X-MiAplicacion-Evento-Id: 66f0b3c4d5e6f70819203040
X-MiAplicacion-Intento: 1

Una entrega simulada (Simular eventos) trae además X-MiAplicacion-Simulado: 1, fuera de la firma, para descartarla sin parsear el cuerpo. Un evento real nunca la lleva.

Verificar la firma

HMAC-SHA256 sobre t + "." + cuerpo, donde cuerpo es el cuerpo crudo tal cual llegó (no lo vuelvas a serializar: un cambio de orden de claves rompe la verificación) y t son los segundos unix de la cabecera. El timestamp va dentro de lo firmado justamente para poder rechazar reenvíos.

javascript
const crypto = require('crypto');

function firmaValida(cabecera, cuerpoCrudo, secreto, toleranciaSegundos = 300) {
  const partes = Object.fromEntries(
    String(cabecera).split(',').map((p) => p.split('=').map((s) => s.trim()))
  );
  if (!partes.t || !partes.v1) return false;

  const edad = Math.abs(Math.floor(Date.now() / 1000) - Number(partes.t));
  if (!Number.isFinite(edad) || edad > toleranciaSegundos) return false;

  const esperado = crypto
    .createHmac('sha256', secreto)
    .update(partes.t + '.' + cuerpoCrudo)
    .digest('hex');

  const a = Buffer.from(esperado, 'hex');
  const b = Buffer.from(partes.v1, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

En Express, el cuerpo crudo se obtiene con express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }). El prefijo v1 deja lugar a rotar el algoritmo: ignora los esquemas que no conozcas en vez de fallar.

Deduplicación: obligatoria

Deduplica por X-MiAplicacion-Evento-Id

Ese id es estable entre los reintentos de la misma entrega: si el primer POST se entregó pero tu respuesta se perdió, el segundo trae el mismo id. Sin deduplicación, un reintento te duplica el asiento contable, el correo al cliente o el descuento de stock.

Reintentos

IntentoCuándo
1Inmediato
2+1 min
3+5 min
4+15 min
5+1 h
6+6 h

Seis intentos en total, hasta unas 7 horas después del hecho. Agotados, la entrega queda agotada y no vuelve.

  • Responde 2xx rápido. El timeout es de 10 segundos. Encola y procesa después; no hagas el trabajo pesado dentro del handler.
  • Los 3xx cuentan como fallo. Las redirecciones no se siguen: un 302 a una IP interna sería un bypass del guard SSRF.
  • 410 Gone desactiva la suscripción de inmediato. Es la única semántica HTTP que significa «no vuelvas». Un 403 o un 404 se reintentan: pueden ser un WAF o un despliegue a medias.
  • Tu URL tiene que ser https y pública. Una URL http se rechaza al registrarla («La URL del webhook debe usar https. El secreto de firma y el contenido del documento no viajan en claro.»). Una IP literal de un rango interno se rechaza nombrando el motivo. Un dominio que no resuelve, o que resuelve a un rango interno, se rechaza con un texto genérico, sin IP ni motivo: «La URL no es un destino permitido para webhooks: debe ser un dominio público alcanzable por HTTPS.».
  • Al entregar se vuelve a revisar el destino. Si en ese momento el DNS no resuelve (o apunta a un rango interno), la entrega no se descarta: cuenta como un intento fallido y se reintenta según la tabla de arriba, porque un fallo de DNS puede ser pasajero. Si el problema sigue, termina agotada como cualquier otra.

Los webhooks son un canal de conveniencia, no una garantía. Si una entrega se agota, barre con el listado por cursor desde tu última posición conocida: es exactamente para eso que existe.

Referencia de endpoints

Los 215 endpoints alcanzables con una API key, más los públicos. Todos cuelgan de https://api.miaplicacion.cl.

Identidad (1)

MétodoRutaScope
GET/api/medte:leer

Emisión (18)

MétodoRutaScope
GET/api/dte/tiposdte:leer
POST/api/empresas/:empresaId/dtedte:emitir
POST/api/empresas/:empresaId/dte/:id/anulardte:anular
POST/api/empresas/:empresaId/dte/lotedte:emitir
GET/api/empresas/:empresaId/dte/lotedte:leer
GET/api/empresas/:empresaId/dte/lote/:loteIddte:leer
GET/api/empresas/:empresaId/dte/masiva/plantilladte:leer
POST/api/empresas/:empresaId/dte/masiva/previsualizardte:emitir
POST/api/empresas/:empresaId/dte/masiva/emitirdte:emitir
GET/api/empresas/:empresaId/dte/masiva/:masivaIddte:leer
GET/api/empresas/:empresaId/dte/masiva/:masivaId/resultadodte:leer
GET/api/empresas/:empresaId/dtedte:leer
GET/api/empresas/:empresaId/dte/por-folio/:tipoDte/:foliodte:leer
GET/api/empresas/:empresaId/dte/por-folio/:tipoDte/:folio/pdfdte:leer
POST/api/empresas/:empresaId/dte/:docId/enviar-correodte:enviar_correo
GET/api/empresas/:empresaId/dte/:id/estadodte:leer
GET/api/empresas/:empresaId/dte/:id/xmldte:leer
GET/api/empresas/:empresaId/foliosfolios:leer

Las rutas del panel de ese módulo (descarga en ZIP, correo masivo, uso del plan y catálogos de exportación) exigen un usuario humano.

Consulta y configuración (12)

MétodoRutaScope
GET/api/empresas/:empresaId/sii-emisionconfig:leer
GET/api/empresas/:empresaId/sii-emision/autorizacionesdte:leer
GET/api/empresas/:empresaId/sii-emision/documentosdte:leer
GET/api/empresas/:empresaId/sii-emision/documentos/exportardte:leer
GET/api/empresas/:empresaId/sii-emision/documentos/proyectosdte:leer
GET/api/empresas/:empresaId/sii-emision/documentos/:id/pdfdte:leer
GET/api/empresas/:empresaId/sii-emision/libro-ventasdte:leer
GET/api/empresas/:empresaId/sii-emision/resumendte:leer
GET/api/empresas/:empresaId/sii-emision/librosdte:leer
GET/api/empresas/:empresaId/sii-emision/libros/:iddte:leer
GET/api/empresas/:empresaId/sii-emision/timbraje/disponibilidadfolios:leer
POST/api/empresas/:empresaId/sii-emision/timbrajefolios:timbrar

El resto de ese módulo (guardar config, subir certificado, subir CAF, logo, probar conexión, reemitir, acuse, RCOF, actualizar veredictos, y el envío del libro IECV con su resolución manual y su poller) exige un usuario humano. Una API key sí puede cambiar el logo, pero solo con logoUrl al emitir (ver Logo de la empresa por URL).

Cesión de facturas (9)

MétodoRutaScope
GET/api/empresas/:empresaId/cesionesdte:leer
GET/api/empresas/:empresaId/cesiones/:iddte:leer
GET/api/empresas/:empresaId/cesiones/:id/aecdte:leer
GET/api/empresas/:empresaId/cesiones/precheck/:emitidaIdcesion:emitir
POST/api/empresas/:empresaId/cesionescesion:emitir
POST/api/empresas/:empresaId/cesiones/recibidascesion:emitir
GET/api/empresas/:empresaId/cesiones/recibidasdte:leer
GET/api/empresas/:empresaId/cesiones/recibidas/:tenenciaIddte:leer
GET/api/empresas/:empresaId/cesiones/recibidas/:tenenciaId/precheckcesion:emitir

El resto de ese módulo (actualizar estados y resolver una cesión incierta) exige un usuario humano.

Auditoría tributaria (9)

Prefijo /api/auditoria-tributaria/:empresaId. El detalle de cada uno está en Configuración, auditoría y contabilidad.

Boletas de honorarios (4)

MétodoRutaScope
GET/api/empresas/:empresaId/bhe/recibidassii:leer
GET/api/empresas/:empresaId/bhe/recibidas/resumensii:leer
GET/api/empresas/:empresaId/bhe/emitidasbhe:leer
GET/api/empresas/:empresaId/bhe/emitidas/:idbhe:leer

POST /bhe/recibidas/sincronizar, el PDF oficial de una recibida (GET /bhe/recibidas/:id/pdf), el mandato, el estado de la emisión, la emisión (validar, preparar y confirmar) y la anulación exigen un usuario humano (confirmar y anular hoy responden 501).

Contabilidad (19)

Prefijo /api/contabilidad/:empresaId, todos GET y todos con contabilidad:leer. Todas las escrituras contables exigen un usuario humano.

Inventario (29)

Prefijo /api/empresas/:empresaId/inventario. Dieciocho GET con inventario:leer(configuración, bodegas, variantes, stock, kardex, lotes, series, valorizado, fotos, operaciones y su detalle, tomas y su detalle, alertas, recetas y su detalle, órdenes de producción y su detalle) y once escrituras con inventario:escribir (entradas, traslados, ajustes, mermas y consumos; crear, editar y activar o desactivar una receta; crear, confirmar y anular una orden de producción). El resto de las escrituras del inventario exigen un usuario humano. Ver Inventario.

Ventas y cobranza (45)

Prefijo /api/empresas/:empresaId/ventas. Diecisiete GET con ventas:leer (la configuración, las listas de precios, una lista, sus precios, el precio de un ítem para un cliente, las cotizaciones y notas de venta, en listado, una por una y en PDF, la lista de picking de una nota, el stock que comprometen las notas de venta, las ventas por vendedor, las suscripciones de facturación recurrente, una por una y con su historial, y del CRM las oportunidades, una por una, y las tareas) y diecinueve escrituras con ventas:escribir (crear y editar una lista, guardar y quitar sus precios; crear, editar, cambiar de estado, convertir a nota de venta y mandar por correo un documento, y convertirlo a DTE o facturar varias guías en una factura, que exigen además dte:emitir; del CRM, crear, editar, mover de etapa y reabrir una oportunidad, vincularle y desvincularle cotizaciones, y crear y editar tareas). El PUT de la configuración, resolver una conversión en revisión y todo lo que escribe en las suscripciones exigen un usuario humano. Además, siete GET con cobranza:leer bajo /api/empresas/:empresaId/cobranza: las cuentas por cobrar, una cuenta, los pagos recibidos, un pago, la antigüedad de saldos, el estado de cuenta y el registro de los recordatorios, y dos escrituras con cobranza:escribir: registrar un pago y anularlo. Ver Ventas y cobranza.

Compras y cuentas por pagar (35)

Prefijo /api/empresas/:empresaId/compras. Veintidós GET con compras:leer: la configuración, las cuentas por pagar (/cuentas y /cuentas/:cuentaId), los documentos del RCV sin cuenta (/documentos-sin-cuenta), los reportes (/antiguedad, /estado-cuenta y /calendario), los pagos a proveedores (/pagos y /pagos/:pagoId) y las órdenes de compra (/ordenes, /ordenes/:ordenId y /ordenes/:ordenId/pdf) y sus recepciones (/ordenes/:ordenId/recepciones, /recepciones y /recepciones/:recepcionId), su conciliación (/ordenes/:ordenId/conciliacion) y los XML cargados de documentos recibidos (/documentos-xml, /documentos-xml/:documentoId y /documentos-xml/:documentoId/xml) y las importaciones (/importaciones, /importaciones/tipo-cambio y /importaciones/:importacionId); y doce escrituras con compras:escribir: registrar un pago a proveedor y anularlo, crear, editar (PATCH) y transicionar una orden de compra, recibir mercadería contra ella (POST /ordenes/:ordenId/recepciones), vincular una cuenta por pagar con su orden (PUT /cuentas/:cuentaId/orden), cargar el XML de un documento recibido (POST /documentos-xml) y crear, editar, descartar y abrir una importación (POST /importaciones, PATCH y DELETE /importaciones/:importacionId y POST /importaciones/:importacionId/abrir); y emitir la factura de compra 46 de una orden ya recibida (POST /ordenes/:ordenId/factura-compra), que exige además dte:emitir. El PUT de la configuración, compensar un saldo a favor, anular una compensación, marcar una cesión, anular una recepción, resolver una factura 46 en revisión y cerrar una importación exigen un usuario humano. Ver Compras y cuentas por pagar.

Punto de venta y caja (21)

Prefijo /api/empresas/:empresaId/pos. Catorce GET con pos:leer: la configuración (/configuracion), los puntos de venta (/puntos-venta y /puntos-venta/:puntoVentaId), la sesión abierta de una caja (/puntos-venta/:puntoVentaId/sesion-abierta), las sesiones de caja (/sesiones, /sesiones/:sesionId, /sesiones/:sesionId/reporte y /sesiones/:sesionId/movimientos), las ventas (/ventas y /ventas/:ventaId), las ventas en espera (/puntos-venta/:puntoVentaId/ventas-en-espera y /ventas-en-espera/:ventaId), el escáner (/puntos-venta/:puntoVentaId/codigos/:codigo) y la búsqueda (/puntos-venta/:puntoVentaId/items); y seis escrituras con pos:escribir: abrir una sesión (POST /puntos-venta/:puntoVentaId/sesiones), registrar un ingreso, retiro o gasto (POST /sesiones/:sesionId/movimientos), cerrarla con el arqueo (POST /sesiones/:sesionId/cerrar), registrar una venta (POST /sesiones/:sesionId/ventas) y guardar o borrar una venta en espera (POST /puntos-venta/:puntoVentaId/ventas-en-espera y DELETE /ventas-en-espera/:ventaId); y emitir el DTE de una venta (POST /ventas/:ventaId/emitir), con pos:escribir y dte:emitir. El PUT de la configuración, crear o editar un punto de venta, anular un movimiento, resolver una emisión en revisión (POST /ventas/:ventaId/emision/resolver) y devolver una venta (POST /ventas/:ventaId/devolver, POST /ventas/:ventaId/devolucion/reembolsar, POST /ventas/:ventaId/devolucion/resolver, POST /ventas/:ventaId/devoluciones, POST /ventas/:ventaId/devoluciones/:devolucionId/reembolsar, POST /ventas/:ventaId/devoluciones/:devolucionId/resolver, y la nota de reemplazo: POST /ventas/:ventaId/devolucion/nota-reemplazo y POST /ventas/:ventaId/devoluciones/:devolucionId/nota-reemplazo) exigen un usuario humano. Ver Punto de venta y caja.

Canales de venta (10)

Prefijo /api/empresas/:empresaId/canales. Seis GET con canales:leer: la configuración (/configuracion), los canales (/ y /:canalId), el catálogo de un canal (/:canalId/catalogo) y las órdenes (/ordenes y /:canalId/ordenes/:ordenId). Cuatro POST con canales:escribir: enviar una orden (/:canalId/ordenes), confirmar su pago (/:canalId/ordenes/:ordenId/pagar), emitir su boleta o factura (/:canalId/ordenes/:ordenId/emitir) y cancelarla (/:canalId/ordenes/:ordenId/cancelar). El PUT de la configuración, crear o editar un canal y resolver una emisión o una cancelación en revisión (/:canalId/ordenes/:ordenId/resolver y /:canalId/ordenes/:ordenId/cancelacion/resolver) exigen un usuario humano. Ver Canales de venta.

Reportes (2)

Prefijo /api/empresas/:empresaId/reportes. Dos GET con contabilidad:leer: el margen (/margen) y el flujo de caja (/flujo-caja). Ver Reportes: margen y flujo de caja.

Webhooks (1)

POST /api/empresas/:empresaId/webhooks/simular con dte:emitir: la única ruta de webhooks abierta a API keys. Ver Simular eventos.

Públicos, sin autenticación

MétodoRutaQué hace
GET/api/healthSeñal de operación para el balanceador y el monitor de uptime.
GET/api/docsLa referencia en text/markdown, sincronizada con esta página. 30 peticiones por minuto y por IP.
GET/api/docs/openapi.jsonLa especificación OpenAPI 3.1 de la superficie para API keys (JSON), generada desde el código. Mismo contador que /api/docs.
GET/api/docs/miaplicacion.postman_collection.jsonLa colección de Postman v2.1, como descarga (Content-Disposition: attachment). Mismo contador.
GET/api/publico/boletas/:rutEmisor/:folioVerificación de una boleta. Exige fecha y monto como query.
GET/api/publico/boletas/:rutEmisor/:folio/pdfLa misma boleta, en PDF.
GET/api/publico/documentos/verificar/:tokenVerificación de cualquier documento por el token de su enlace o QR; nunca trae al receptor. 30 por minuto y por IP.
GET/api/publico/planesCatálogo de planes y certificaciones de la contratación. 30 por minuto y por IP.
POST/api/publico/cotizarCotiza una contratación (el servidor siempre recotiza). 60 por minuto y por IP.
GET/api/publico/sii/empresa/:rutFicha pública de una empresa en el SII (resolución y documentos autorizados). 10 por minuto y por IP.
GET/api/publico/cotizacionesLa cotización del enlace del correo, con el token en el header X-Cotizacion-Token. 30 por minuto y por IP.
GET/api/publico/cotizaciones/pdfSu PDF comercial (mismo header).
POST/api/publico/cotizaciones/aceptar{ nombre?, comentario? }: el cliente la acepta. 10 por minuto y por IP.
POST/api/publico/cotizaciones/rechazar{ nombre?, comentario? }: el cliente la rechaza. 10 por minuto y por IP.
GET/api/publico/estadoLa página de estado: estado actual y uptime de cada componente, e incidentes. 30 por minuto y por IP. Ver abajo.

GET /api/docs sirve la referencia en markdown por HTTP, sin autenticación, para leerla desde una terminal en vez de con un navegador (esta página es una SPA y un fetch contra ella devuelve el index.html). Es un archivo aparte, que se mantiene sincronizado con esta página:

bash
curl https://api.miaplicacion.cl/api/docs

GET /api/health y los envíos inciertos

Además del estado general, trae dos campos de operación sobre los envíos inciertos: inciertosSinConsultar (número o null) e inciertosSinConsultarEsPiso (booleano).

  • inciertosSinConsultar es cuántos documentos en ENVIO_INCIERTO, de tipos que se consultan por folio (33, 34, 46, 52, 56, 61, 110, 111 y 112; nunca boletas), llevan más de la gracia más el margen (15 + 180 min por defecto) sin una respuesta útil del SII registrada para su folio, o con la última más vieja que el margen. Es una señal de toda la plataforma: no trae ids, empresas ni folios, y no dice si alguno es tuyo ni por qué no avanza.
  • null significa que no se pudo calcular (base de datos no disponible), no que sea cero. Si inciertosSinConsultarEsPiso es true, se llegó al tope de lectura y el número es un mínimo: el real puede ser mayor.
  • Si sube, los envíos inciertos no se están resolviendo solos: no reemitas; lista los tuyos con GET /api/empresas/:empresaId/sii-emision/documentos?estado=ENVIO_INCIERTO y pide a un admin que los resuelva desde el panel.

estadoDetalle.alertaSinConsulta (en GET .../sii-emision/documentos, que devuelve estadoDetalle completo) es una marca interna de esa alerta (consultaVista, alertadaAt). No es contrato: no la uses para lógica. Si el documento traía estadoDetalle: null, después de la alerta pasa a ser un objeto con solo esa marca.

La consulta pública es la URL que el SII exige para habilitar a un emisor de boletas. Hay que acertar los cuatro datos impresos: con solo RUT y folio se podrían enumerar las ventas del emisor, así que un dato equivocado devuelve un 404 neutro, indistinguible de «no existe». El RUT se acepta con o sin puntos y con o sin guion; el monto acepta $ 12.990. La versión web de esta consulta vive en /consulta-boleta; si la URL trae los cuatro datos (?rut=78287987-1&folio=1042&fecha=2026-09-04&monto=12990), la página los rellena y consulta sola una vez.

bash
curl "https://api.miaplicacion.cl/api/publico/boletas/78287987-1/1042?fecha=2026-09-04&monto=12990"

Verificación de cualquier documento por enlace o QR

GET /api/publico/documentos/verificar/:token, sin autenticación y para cualquier tipo de DTE, no solo boletas. Es lo que abre el enlace https://app.miaplicacion.cl/v/<token> y su QR: quien tenga el documento en papel confirma que existe y su estado ante el SII. El token es <id>.<firma> y lo genera la plataforma; no se arma a mano ni se puede adivinar. Un token incompleto, alterado o de un documento que no existe responde el mismo 404, sin decir cuál de los tres fue.

json
{
  "emisor": {
    "rut": "78287987-1",
    "razonSocial": "MI APLICACION SPA"
  },
  "tipoDte": 33,
  "nombreTipo": "Factura electrónica",
  "folio": 1042,
  "fechaEmision": "2026-09-04",
  "montoTotal": 119000,
  "estadoSii": "aceptado",
  "ambiente": "produccion",
  "esPrueba": false,
  "anulado": false,
  "verificadoEn": "2026-10-04T16:20:00.000Z"
}
  • estadoSii va agrupado: aceptado, aceptado_con_reparos, rechazado, en_proceso, envio_sin_confirmar o desconocido (sin estado todavía, o un código del SII que no reconocemos: no se afirma nada).
  • esPrueba es true si el documento es de certificación o del modo demo: no tiene validez tributaria.
  • Si una nota aceptada por el SII lo anuló, anulado: true y notaCredito: { folio, fecha } (si el documento es una nota de crédito, la que la anula es una nota de débito: notaDebito).

Nunca trae datos del receptor (RUT, razón social, dirección, correo), ni el XML, el timbre o el PDF. Límite: 30 verificaciones por minuto y por IP, con un contador aparte del de la consulta de boletas.

GET /api/publico/estado: página de estado

Sin autenticación. Es lo que muestra la página pública /estado del panel (https://app.miaplicacion.cl/estado). Trae solo estados, porcentajes, fechas y los incidentes que publica la plataforma: nada de empresas.

  • componentes[]: api, emision, sii_certificacion y sii_produccion, cada uno con su estado actual (operativo, degradado, caido o sin_datos), su uptime de las últimas 24 horas, 7 días y 90 días, y las barras diarias de 90 días.
  • Un latido mide los componentes cada minuto. Un minuto sin latido cuenta como caída en la API y en la emisión; en los componentes del SII cuenta como «sin datos», que no entra al cálculo.
  • objetivo: el objetivo de disponibilidad de la API, 99,5 % por defecto (ESTADO_UPTIME_OBJETIVO). Es un objetivo de servicio, no un SLA, y no incluye la disponibilidad del SII.
  • incidentes[]: los abiertos y los terminados en los últimos 90 días.
  • historialDisponible: false si el historial no se pudo leer: el estado actual sale igual, sin historial, en vez de un 500.

La respuesta se guarda 60 s; consultarla más de una vez por minuto no trae nada nuevo (límite: 30 por minuto y por IP).

Lo que todavía no existe

Honestidad por delante: si tu integración depende de algo de esta lista, no lo construyas contra esta API todavía.

  • Boletas de honorarios (BHE) emitidas: emitirlas y anularlas en el SII no existe; confirmar y anular responden 501 sin enviar nada. Depende del dueño de la plataforma: la consulta legal sobre la cláusula 4 de los términos del sitio del SII, y su autorización para capturar el formulario real del portal y para emitir una primera boleta real. Con eso se construye el cliente que la envía. Las recibidas sí se leen (ver Boletas de honorarios recibidas), y lo previo a emitir ya está: mandato, habilitación, ensayo con el líquido estimado, motivos y plazos de anulación (ver Boletas de honorarios emitidas).
  • Cesión de facturas en producción: responde 501. Lo que pide el código ya está (el cupo del precheck, la habilitación empresa por empresa y la hora de la cesión); falta una primera cesión real autorizada y decidir si se valida la cadena de confianza de los certificados de un AEC recibido (hoy se verifica su integridad). En certificación funciona, también volver a ceder como cesionario (ver Cesión de facturas).
  • Aceptar o reclamar en producción un DTE recibido (Ley 19.983): responde 501 a propósito, porque es irreversible (8 días de plazo, y un reclamo quita crédito fiscal y mérito ejecutivo). Falta un documento recibido en producción y la autorización del dueño para una llamada al servicio de producción del SII. En certificación funciona y está verificado: las cinco acciones y los rechazos 7, 8, 11 y 12, el 22-10-2026 (ver Configuración, auditoría y contabilidad).
  • Exportación (110, 111 y 112), que existe solo donde el servidor la habilita (ver Documentos de exportación): falta el SET11, la certificación de exportación que cada empresa hace con el SII antes de emitir en producción (generarlo anula el SET72); el veredicto del SII sobre una 111 con codRef 1 sobre una 110 (la API la emite); el tipo de cambio automático, que espera la cuenta del Banco Central (hoy va en el payload); y probar el resumen del período del libro de ventas con exportación, que solo va en un envío que cierra el período (el envío parcial de prueba ya quedó aceptado y cuadrado).

Y dos formas que no son contrato estable, aunque las veas en las respuestas: rawResponse en la emisión y estado en GET /dte/:id/estado son JSON crudo del SII, sin normalizar.

Cambios de la API

Los cambios del contrato con fecha, del más nuevo al más antiguo. El detalle de cada uno está en su sección.

03-11-2026: reactivar una suscripción terminada

  • Ruta nueva POST .../ventas/suscripciones/:suscripcionId/reactivar (solo un admin con sesión; no cambia la superficie para API keys): una suscripción terminada vuelve a activa y retoma en el período que corresponde hoy, sin volver a un período que ya tiene registro (Facturación recurrente).
  • Código nuevo SUSCRIPCION_SIN_PERIODOS (409): su calendario ya no tiene períodos. ESTADO_INVALIDO (409) también responde al reactivar una que no está terminada. La suscripción agrega reactivadaEn.

03-11-2026: totales del registro de compras y ventas

  • GET /auditoria-tributaria/:empresaId/documentos: en totales (neto, iva y total) las notas de crédito (61 y 112) ahora restan, igual que en el IVA del F29. Antes se sumaban: una factura y la nota de crédito que la anula daban el doble en vez de 0.
  • Los montos de cada documento del listado no cambian: siguen en positivo, como los entrega el SII.

30-10-2026: un documento rechazado no se anula

  • POST /api/empresas/:empresaId/dte/:id/anular sobre un documento RECHAZADO responde 422 DOCUMENTO_RECHAZADO antes de pedir el folio de la nota: el SII no tiene ese documento. Ver Anular un documento.
  • GET /api/empresas/:empresaId/sii-emision/documentos agrega rechazoResoluble y, en un rechazado que se marcó como resuelto desde el panel, rechazoResuelto (en, motivo y reemplazo); ese documento sale reemitible: false.

22-10-2026: recordatorios de cobranza, ceder con una API key, listas de precio en el lote, exportación y nota de reemplazo en el punto de venta

  • Ruta nueva GET /api/empresas/:empresaId/cobranza/recordatorios (scope cobranza:leer): el registro de los recordatorios de cobranza, paginado y con filtros. Solo lectura. Ver Recordatorios de cobranza.
  • Scope nuevo cesion:emitir (no viene por defecto): abre a las API keys el precheck (GET .../cesiones/precheck/:emitidaId) y ceder (POST .../cesiones). La cesión creada con una key guarda declaracionJurada.aceptadaPorApiKey y creadoPorApiKey. Actualizar y resolver una cesión incierta siguen siendo solo con sesión; en producción, ceder sigue respondiendo 501. Ver Cesión de facturas.
  • Volver a ceder como cesionario: cuatro rutas nuevas bajo /api/empresas/:empresaId/cesiones/recibidas (recibir el AEC con cesion:emitir, listar y leer con dte:leer, y el precheck con cesion:emitir), y POST .../cesiones acepta documentoTenenciaId en vez de emitidaId. GET .../cesiones filtra por documentoTenenciaId; las cesiones nuevas traen rutEmisor y las de un documento en tenencia, documentoTenenciaId y seqCesion de 2 a 40. Cada documento en tenencia trae verificacion: sus firmas prueban integridad, no quién firmó ni que el Registro anotó las cesiones. POST .../cesiones de un documento emitido responde igual que antes. Verificado en certificación; en producción, ceder sigue respondiendo 501. Ver Volver a ceder como cesionario.
  • La emisión masiva por archivo (/api/empresas/:empresaId/dte/masiva/*, sus cinco rutas) se abre a las API keys con los scopes del lote: dte:emitir para la vista previa y la emisión, dte:leer para la plantilla, el avance y el resultado. Los lotes quedan a nombre de la key (una mk_cert_ emite en certificación); la cuenta demo y el sandbox siguen sin emitir por archivo. Para un usuario con sesión nada cambia. Ver Emisión masiva (lote).
  • El lote (POST /dte/lote) y la emisión masiva por archivo aplican la lista de precios del receptor a una línea con itemId y sin precio, como POST /dte; el precio queda guardado en el lote. En la masiva, itemPrecio deja de ser obligatoria (el encabezado necesita itemPrecio o itemId) y hay columnas itemId e itemVarianteId. Con las listas caídas, 503 LISTAS_PRECIO_NO_DISPONIBLES sin crear nada. Ver La lista de precios en la emisión.
  • Exportación, donde el servidor la habilita: el lote y la emisión masiva por archivo emiten 110, 111 y 112, con fecha y tipo de cambio explícitos en cada una (la masiva, con columnas nuevas en su plantilla: ver Exportación en la emisión masiva). Anular una 111 emite una 112 con codRef 1 y una sola referencia, a la 111, y anular una 112 emite una 111 con codRef 1 y una sola referencia, a la 112 (las dos respondían 422); POST /dte acepta esas notas, y una 111 que referencia una 112 con otro codRef es 400 con su propio mensaje. La verificación pública de una 112 anulada trae notaDebito. Una 110, 111 o 112 en ENVIO_INCIERTO se consulta por folio en el SII con el total en la moneda de venta, y su 422 ENVIO_INCIERTO_SIN_TRACKID trae el texto de las facturas (antes, el de las boletas). Los estados MMD, MMC, AND y ANC del SII (documento recibido con una nota encima) cuentan como recibido al resolver un envío incierto. Una línea de exportación sin cantidad sale ahora con cantidad 1 (XML, documento guardado y PDF). El libro IECV incluye la exportación en pesos y ya no deja el período incompleto. Ver Documentos de exportación.
  • Cesión: los dos prechecks (GET .../cesiones/precheck/:emitidaId y GET .../cesiones/recibidas/:tenenciaId/precheck) tienen con API key un cupo propio de 30 por hora por empresa, además del de escritura (429 con RateLimit-Policy "cesion-precheck"; soloDeclaracion=1 no cuenta; el panel no pasa por él). Cuando la cesión en producción se habilite, solo cederán las empresas habilitadas una por una (si no, 409 CESION_NO_PERMITIDA con detalle.motivo: "produccion_no_habilitada"); hoy producción sigue en 501. El TmstCesion del AEC se declara 5 minutos antes de la hora del servidor. Una API key sin id recibe 403 al hacer el precheck, ceder o recibir. Ver Cesión de facturas.
  • Punto de venta: si el SII rechaza la nota de crédito de una devolución ya reembolsada, se corrige con dos rutas nuevas, solo con sesión y solo el admin: POST .../pos/ventas/:ventaId/devolucion/nota-reemplazo y POST .../pos/ventas/:ventaId/devoluciones/:devolucionId/nota-reemplazo, con el cuerpo vacío e Idempotency-Key. Emiten una 61 igual a la rechazada sin volver a pagar el reembolso; antes del folio exigen el documento de la venta aceptado por el SII (409 POS_DOCUMENTO_VENTA_NO_ACEPTADO) y el plazo de seis meses del IVA (422 POS_NC_FUERA_DE_PLAZO_IVA). La devolución total y cada parcial traen siempre ncRechazoMotivo, notasRechazadas y reemplazo, y en el JSON de GET .../pos/ventas, ncEstadoSii. En Documentos emitidos, la nota de crédito de una devolución parcial del punto de venta sale reemitible: false y, rechazada, con motivoNoReemitible (reemitirla siempre respondía 409). Ver Nota de reemplazo.
  • Boletas de honorarios emitidas: GET .../bhe/estado-emision agrega anulacionEnElSii (si la empresa puede anular en el SII, con su motivo) y motivosAnulacion (los tres motivos oficiales del SII, con el codigo que se manda al anular). La boleta (al prepararla, en el listado, en el detalle y en el 501) y la vistaPrevia de POST .../bhe/emitidas/validar agregan montoLiquidoEstimado. El listado y el detalle pasan a incierta una boleta que lleva más de 30 minutos enviando (una anulando igual de vieja queda con solicitudAnulacion.incierta: true), y confirmar y anular revisan los requisitos otra vez justo antes de enviar (hoy el 501 sale antes). En el PDF de las recibidas, 409 SII_AUTH_CHALLENGE, 429 SII_MAX_SESIONES y 422 SII_AUTH también pueden salir sin ingresar al portal, por un ingreso fallido reciente. Emitir y anular en el SII siguen en 501. Ver Boletas de honorarios emitidas.
  • Aceptar o reclamar documentos recibidos: POST .../documentos/accion (solo con sesión) tiene un tope de 10 peticiones por minuto y por empresa, con 429 RECLAMO_ACCION_LIMITE, y GET .../configuracion agrega escrituraReclamo (si aceptar o reclamar sale hoy en cada ambiente). Las cinco acciones y los rechazos 7, 8, 11 y 12 del SII quedaron verificados en certificación, con sus fuentes oficiales guardadas; en producción, aceptar o reclamar sigue respondiendo 501. Ver Configuración, auditoría y contabilidad.
  • Dos cambios alcanzan también a quien no usa nada de lo anterior: una línea de exportación sin cantidad sale con cantidad 1, y el 429 del cupo de escritura de las API keys (el cuerpo es solo { error }) cambió de texto para todas las keys. Antes nombraba solo emitir, anular y reenviar por correo; ahora dice «Esta API key superó su límite de escrituras por minuto (emitir, anular, ceder, timbrar folios y las demás operaciones que escriben). Reintenta en unos segundos.». Fuera de esos dos, de los campos nuevos de la devolución del punto de venta, de las boletas de honorarios emitidas y de GET .../configuracion de la auditoría (se agregan, no cambia ninguno), del tope de aceptar o reclamar, del cupo del precheck de la cesión con API key, del texto del 422 ENVIO_INCIERTO_SIN_TRACKID de una 110, 111 o 112, y de reemitible: false en la nota de crédito de una devolución parcial del punto de venta, ninguna ruta, respuesta ni scope existente cambia para quien no los usa.

20-10-2026: tipos autorizados por el SII

  • Ruta nueva GET /api/empresas/:empresaId/sii-emision/autorizaciones (scope dte:leer): los 12 tipos de DTE con autorizado (true, false o null = no se sabe) y desde, desde la última lectura guardada del registro del SII. No consulta al SII durante la petición. Ver Tipos autorizados por el SII.
  • Ninguna ruta, respuesta ni scope existente cambia.

15-10-2026: permisos por área (solo usuarios con sesión)

  • Un administrador puede restringir a un usuario emisor o contador a ciertas áreas del ERP (areas en POST y PATCH /api/empresas/:empresaId/usuarios, solo con sesión). Fuera de sus áreas, una ruta del ERP responde 403 AREA_NO_PERMITIDA con area; si el acceso no se pudo verificar, 503 ACCESO_NO_VERIFICADO. Ver La compuerta del ERP, párrafo «Permisos por área».
  • Las API keys no cambian: las siguen gobernando sus scopes. Un administrador, el titular y el superadmin nunca se restringen.
  • Aceptar o reclamar facturas recibidas (POST .../documentos/accion y .../reclamo/*) es del área compras.

15-10-2026: usuarios asignados a sucursales (solo usuarios con sesión)

  • Un administrador puede asignar a un usuario emisor o contador a una o más sucursales (sucursalIds en POST y PATCH /api/empresas/:empresaId/usuarios, solo con sesión). Si ese usuario emite, anula, reemite u opera una caja en una sucursal que no es suya, responde 403 SUCURSAL_NO_PERMITIDA; si tiene varias y el documento no trae sucursalId, 422 SUCURSAL_REQUERIDA. Los dos, antes de pedir el folio. Ver La compuerta del ERP, párrafo «Sucursales».
  • Sus listados y reportes solo muestran sus sucursales. Las API keys no se restringen por sucursal.

15-10-2026: sucursales en reportes, punto de venta y bodegas

  • Margen por sucursal: agrupar=sucursal y el filtro sucursalId (el id de una sucursal o matriz) en GET .../reportes/margen.
  • sucursal ({ id, nombre } de la sucursal ACTUAL de la caja, o null si la empresa no tiene sucursales) en el reporte Z (sesion.sucursal) y en cada sesión de GET .../pos/sesiones. En el CSV del reporte Z, la fila Caja agrega Sucursal;<nombre>; el CSV de sesiones suma la columna Sucursal al final solo si la empresa tiene sucursales. Sin sucursales, los dos CSV son los de siempre. Ningún total cambia (ver Reporte Z y listados).
  • Códigos nuevos, los dos con detalles[] y sin escribir nada: 422 BODEGA_DE_OTRA_SUCURSAL (crear una caja o un canal, o cambiarle la sucursal o la bodega, con una bodega de otra sucursal) y 422 SUCURSAL_INACTIVA (crear una bodega en una sucursal inactiva).
  • En el listado de documentos, ?sucursalId=matriz (o el id de la sucursal matriz) trae además lo emitido sin sucursal (ver Configuración y listados del panel).

15-10-2026: texto del corte sin ERP

  • El mensaje (error) de los 403 PLAN_SIN_INVENTARIO, PLAN_SIN_VENTAS, PLAN_SIN_COMPRAS, PLAN_SIN_POS y PLAN_SIN_CANALES cambió de redacción: ahora termina en «MiAplicación ERP incluye …, desde el plan …» (por ejemplo, «MiAplicación ERP incluye el punto de venta, desde el plan ERP Pyme»). code, requiere, plan y planSugerido no cambian: distingue por code, no por el texto.

15-10-2026: alertas de la empresa

  • Rutas nuevas solo para el panel (con JWT; una API key recibe 403) bajo /api/empresas/:empresaId/alertas: listar, marcar una y marcar todas. La superficie para API keys no cambia.
  • Las alertas internas de punto de venta, ventas, compras, cobranza, canales y órdenes de trabajo, y los avisos de la facturación recurrente, llegan además al buzón de la empresa (la campana del panel). El emisor ve solo las de punto de venta y ventas.
  • Códigos nuevos: MODULO_NO_PERMITIDO (403) y ALERTA_NO_ENCONTRADA (404).

15-10-2026: CRM liviano (oportunidades y tareas)

  • Rutas nuevas para API keys bajo .../ventas/oportunidades y .../ventas/tareas, con ventas:leer y ventas:escribir: la superficie suma 11 endpoints (ventas pasa de 33 a 44). Ver CRM liviano.
  • Aceptar o rechazar una cotización vinculada mueve su oportunidad abierta a ganada o perdida; la respuesta de la cotización no cambia.
  • Códigos nuevos: OPORTUNIDAD_NO_ENCONTRADA, TAREA_NO_ENCONTRADA, COTIZACION_NO_VINCULADA, OPORTUNIDAD_CERRADA, COTIZACION_YA_VINCULADA, COTIZACION_DE_OTRO_CONTACTO, TOPE_COTIZACIONES y CONFLICTO_DE_EDICION.

15-10-2026: sandbox gratis y eventos de webhooks simulados

  • POST /api/auth/registro acepta contratacion: { plan: "sandbox" }: la empresa nace vigente sin pago, en modo demo y solo certificación, con una key mk_cert_. Ver Sandbox gratis.
  • GET /api/publico/planes suma sandbox; ruta nueva para API keys POST .../webhooks/simular (dte:emitir) y, para el panel, GET /api/empresas/:empresaId/sandbox.
  • El tope diario reserva de forma atómica y devuelve la unidad si la respuesta sale antes del folio; la entrega simulada trae X-MiAplicacion-Simulado: 1.
  • Códigos nuevos: SANDBOX_TOPE_DIARIO, SANDBOX_LIMITE_REGISTROS, SANDBOX_NO_DISPONIBLE, SANDBOX_SOLO_CERTIFICACION, SANDBOX_NO_VERIFICADO y SIMULACION_NO_DISPONIBLE. Una empresa que no es sandbox no ve los del sandbox.

15-10-2026: asientos de la caja del punto de venta

  • POST .../pos/sesiones/:sesionId/movimientos acepta los opcionales categoria, cuentaCodigo y rutProveedor: con categoría y plan de cuentas, el movimiento genera su asiento (origen nuevo caja_pos). Sin categoría, todo sigue como antes.
  • El movimiento suma categoria, cuentaCodigo, rutProveedor, asientoId y motivoSinAsiento; la sesión, asientoArqueo; la configuración, cuentasCaja.
  • Códigos nuevos: 409 PERIODO_CERRADO y 409 CUENTA_CONTABLE_INVALIDA en el movimiento, su anulación y el cierre; 409 PAGO_PROVEEDOR_EN_COMPRAS (con Compras encendido); 409 ASIENTO_DE_CAJA_POS. La superficie para API keys no cambia.

15-10-2026: órdenes de trabajo (servicio técnico)

  • .../ordenes-trabajo: módulo opcional del ERP con estados en una sola tabla, presupuesto que el cliente aprueba o rechaza desde un enlace (/api/publico/ordenes-trabajo, token en el header X-Orden-Trabajo-Token), stock comprometido al aprobar y conversión a boleta 39 o factura 33/34 por el camino de POST /dte.
  • Solo desde el panel (soloJwt): la superficie para API keys no cambia. origenComercial.clase suma el valor orden_trabajo.

15-10-2026: la cuenta Banco de cobros y pagos a proveedores se configura

  • La regla centralizacion_ventas trae el rol banco (por defecto 1.1.01.002): es la cuenta Banco del asiento de cobro y del de pago a proveedor, que iba fija. Sin configurarlo, los asientos no cambian (Ventas y cobranza).
  • PUT /reglas-centralizacion con banco lo revisa contra el plan de cuentas: 422 CUENTA_BANCO_INVALIDA con detalles[]. GET /reglas-centralizacion lo trae en cuentas y cuentasPorDefecto.

15-10-2026: producción (recetas y órdenes de producción)

  • .../inventario/recetas y .../inventario/producciones: leer con inventario:leer; escribir con inventario:escribir (recetas, confirmar y anular: solo admin). Una receta por producto, con versiones (Inventario).
  • Confirmar una orden saca los componentes y entra el terminado al costo de lo consumido, sin dejar stock negativo. Motivos nuevos del kardex: produccion_consumo y produccion. La superficie para API keys pasa de 170 a 180.

15-10-2026: despachos

  • POST .../ventas/facturar-guias (ventas:escribir y dte:emitir): varias guías 52 del mismo cliente en UNA factura con una referencia por guía, sin volver a descontar stock (Despachos). Códigos nuevos: 409 GUIAS_NO_FACTURABLES y GUIA_EN_FACTURACION.
  • GET .../ventas/documentos/:documentoId/picking (ventas:leer): la lista de picking de una nota de venta confirmada, en JSON o PDF. Código nuevo: 409 PICKING_NO_DISPONIBLE. La superficie para API keys pasa de 188 a 190.

15-10-2026: facturación recurrente

  • GET .../ventas/suscripciones, .../suscripciones/:suscripcionId y .../suscripciones/:suscripcionId/emisiones (ventas:leer): las suscripciones de facturación recurrente y su historial por período (Facturación recurrente).
  • Crear, editar, pausar, reanudar, terminar y emitir un período son solo de un admin con sesión. El modo por defecto es borrador: ningún período pide folio sin que una persona lo emita. La superficie para API keys pasa de 167 a 170.

15-10-2026: devoluciones parciales en el punto de venta

  • POST .../pos/ventas/:ventaId/devoluciones (solo admin con sesión): devuelve parte de una venta emitida con una nota de crédito 61 CodRef 3 y el reembolso en una sesión abierta; más .../devoluciones/:devolucionId/reembolsar y .../resolver (Devolver una parte de una venta).
  • Después de una parcial, POST .../devolver devuelve el saldo (61 CodRef 3) y su reembolso suma lo que queda. Sin parciales, la devolución total no cambia.
  • La venta trae devolucionesParciales[] y lineas[].cantidadDevuelta solo si tiene parciales; el reporte Z suma sus reembolsos (parcial: true). Códigos nuevos: 409 POS_DEVOLUCION_PARCIAL_SIN_DTE, POS_DEVOLUCION_DTE_RECHAZADO, POS_DEVOLUCION_DTE_INCIERTO, POS_DEVOLUCION_DOCUMENTO_ANULADO, POS_DEVOLUCION_OTRO_AMBIENTE y 404 POS_DEVOLUCION_NO_ENCONTRADA.
  • POST /dte/:id/anular (y POST /dte o el lote con una 61 CodRef 1) sobre el documento de una venta con devoluciones parciales vigentes responde 409 DTE_CON_DEVOLUCIONES_PARCIALES antes del folio. La nota parcial sobre una boleta cuadra al peso con lo devuelto. Si el SII rechaza la nota de una parcial ya pagada, la parcial queda con ncRechazadaEn y una alerta; el reembolso no cambia.
  • En POST /dte, la lista de precios solo completa líneas de un documento que vende (33, 34, 39, 41 y la 52 con IndTraslado 1 o 2); con las listas sin poder leerse y otros errores en el payload, el 400 con todos ellos.

15-10-2026: conciliación por línea y timbre del XML recibido

  • GET .../compras/ordenes/:ordenId/conciliacion trae porLinea si algún documento vinculado que cuenta tiene su XML cargado con líneas: cada línea de la orden con lo pedido, recibido y facturado, emparejada por código, con su tolerancia, estado, alertas y las líneas sin calce. Sin XML, la respuesta no cambia. Solo informativa.
  • POST .../compras/documentos-xml trae verificacionTed en cada DTE, y el listado y el detalle lo traen guardado (null en los XML cargados antes). No bloquea la carga; firmaVerificada sigue en false.

15-10-2026: reportes de margen y flujo de caja

  • Rutas nuevas, con contabilidad:leer y MiAplicación ERP: GET /reportes/margen?desde&hasta&agrupar=producto|vendedor|canal|sucursal y GET /reportes/flujo-caja?semanas=13, con formato=csv|xlsx para el archivo (Reportes: margen y flujo de caja).
  • Código nuevo: 403 REPORTES_SIN_PERMISO (rol emisor). La superficie para API keys pasa de 165 a 167 endpoints.

15-10-2026: POST /dte aplica la lista de precios del cliente

  • Con el módulo de ventas encendido (y ERP), una línea con itemId y sin precio toma el de la lista del receptor: neto, o bruto en la línea afecta de una boleta 39 (La lista de precios en la emisión). Sin lista aplicable, el 400 de siempre más un detalle. Un precio que mandas gana siempre.
  • Código nuevo: 503 LISTAS_PRECIO_NO_DISPONIBLES (sin folio). Sin cambios para quien ya manda precio ni con el módulo apagado; el lote y la emisión masiva siguieron exigiendo precio hasta el 22-10-2026.

15-10-2026: activo fijo vinculado a su compra y a su venta

  • Rutas nuevas: POST /activos-fijos/:id/vincular-compra, POST /activos-fijos/:id/desvincular-compra (solo JWT) y GET /activos-fijos/documento-compra (contabilidad:leer) (Activo fijo).
  • La centralización de compras lleva el valor de los activos vinculados a su cuenta y solo el resto a gasto (resumen.gasto sin lo vinculado, más activoFijo); en ventas, lo mismo con las bajas vinculadas a su factura (documentoVenta en la baja). Sin vínculos, el asiento es el de siempre.
  • compra en POST /activos-fijos ahora se valida: el documento tiene que estar en tu RCV o en un XML cargado, ser 33, 34 o 46 y caber en lo que lleva a gasto (si no, 422). Con la compra vinculada no se editan valor ni cuenta (409 ACTIVO_CON_COMPRA).
  • Orígenes nuevos reclasificacion_compra_activo_fijo y reclasificacion_venta_activo_fijo (409 ASIENTO_DE_RECLASIFICACION a mano); anular una centralización de compras o ventas anula las de su período. Códigos nuevos: PERIODO_CERRADO, ACTIVO_SIN_COMPRA, DOCUMENTO_EN_VARIOS_PERIODOS, COMPRA_VINCULADA_EXCEDE_DOCUMENTO, VENTA_VINCULADA_EXCEDE_DOCUMENTO, CENTRALIZACION_SIN_CUENTA, CENTRALIZACION_SIN_DOCUMENTOS y DOCUMENTO_COMPRA_INVALIDO.
  • Una reclasificación solo se registra si la centralización vigente del período sumó ese documento (las centralizaciones guardan desde ahora qué documentos sumaron); con una anterior, 409 CENTRALIZACION_SIN_DOCUMENTOS. El prellenado informa rcv.incluidoEnCentralizacion y los asientos de vincular, desvincular y crear con compra traen id.

15-10-2026: Programa Aliados

  • Descuento por cantidad de empresas activas de un mismo titular: Aliado (3 o más) 20 %, Aliado Pro (10 o más) 35 % y Aliado Elite (50 o más) 60 % sobre el plan; no se acumula con el de pago adelantado (Programa Aliados).
  • GET /api/publico/planes trae programaAliados; POST /api/publico/cotizar no cambia. Las cotizaciones de un titular con tramo traen porcentajePrepago, aliado y descuentoAplicado; sin tramo, la respuesta es la de siempre.

15-10-2026: webhooks de pagos a proveedores y nota de venta desde cotización

  • Webhooks nuevos cxp.pago_registrado y cxp.pago_anulado: registrar o anular un pago a proveedor, solo con el módulo de compras encendido (Webhooks). Una suscripción que ya existía no los recibe hasta que los marques en el panel. Los cxc.* no cambian.
  • POST /documentos/:documentoId/nota-venta revisa las líneas de la cotización como el alta de una nota de venta: un ítem desactivado o un insumo de uso interno responde 409 ITEM_INACTIVO / ITEM_USO_INTERNO con todo en detalles[], sin crear la nota. Antes la nota se creaba igual.
  • Un pago registrado sin plan de cuentas puede recibir su asiento después con el script cobros-asientos-pendientes.js de la plataforma (no hay endpoint): el pago pasa a traer asientoId y el abono de cada imputación.

15-10-2026: límites por plan y registro de peticiones

  • Los cupos de escritura y lectura por key y el de emisión por empresa salen del plan de la empresa, nunca por debajo de los de antes (Por plan). El catálogo público trae limitesDeTasa en cada plan.
  • Si leías RateLimit-Policy, cambió su formato: pasa de 60;w=60 a "apikey-escritura";q=60;w=60, con un elemento por limitador, y se suma RateLimit (Límites de tasa). RateLimit-Limit, -Remaining, -Reset y Retry-After siguen igual.
  • Toda respuesta trae X-Request-Id (X-Request-Id).
  • Nueva, solo JWT (admin o superadmin): GET /api/empresas/:empresaId/api-keys/peticiones, el registro de las peticiones de las keys, con resumen por key (Registro de peticiones).

15-10-2026: activo fijo

  • GET /activos-fijos responde id (string) en vez de _id: si leías _id, cambia a id. advertencia pasó a ser advertencias[], y un filtro inválido es 400 FILTRO_INVALIDO (Activo fijo).
  • POST /activos-fijos responde { activo, asiento? } (antes, el activo suelto); la depreciación acelerada sin nuevo: true es 422.
  • Nuevas, solo con sesión de un admin: POST /activos-fijos/:id/trasladar, POST /activos-fijos/:id/situacion, POST /activos-fijos/:id/alta y POST /activos-fijos/importar (carga masiva inicial por archivo).
  • Nuevas con contabilidad:leer: GET /activos-fijos/etiquetas (PDF), GET /activos-fijos/exportar (Excel o CSV con el valor libro a una fecha) y GET /activos-fijos/alertas (garantía por vencer).

14-10-2026: líneas API y ERP

  • POST /dte acepta la cabecera opcional Idempotency-Key: la misma clave con el mismo cuerpo devuelve la misma respuesta, sin otra emisión ni otro folio (Reintentos seguros).
  • Dos líneas de producto, MiAplicación API y MiAplicación ERP. Las rutas del ERP responden 403 PLAN_SIN_ERP a una empresa sin ERP; una que lo tuvo conserva la lectura (MiAplicación API y ERP).
  • Los topes de puntos de venta y de canales responden 409 (antes 403), como el de bodegas. Los PLAN_SIN_* traen requiere: "erp" y sugieren un plan ERP.
  • Crear una API key con scopes del ERP en una empresa sin ERP responde 422 SCOPES_SIN_ERP.
  • El contador queda en solo lectura en la contabilidad: 403 CONTABILIDAD_SOLO_ADMIN (en activo fijo, ACTIVO_FIJO_SOLO_ADMIN).
  • Depreciación acelerada según la Res. Ex. SII N°43/2002: un tercio de la vida útil normal en años enteros; bajo tres años de vida normal, 422 ACTIVO_FIJO_INVALIDO (Activo fijo).
  • La especificación OpenAPI 3.1 y la colección de Postman se descargan sin autenticación (GET /api/docs/openapi.json y GET /api/docs/miaplicacion.postman_collection.json).

10-10-2026: canales de venta

Empieza el módulo de canales de venta, opt-in por empresa: configuración, canales, catálogo de cada canal con su stock disponible, recepción idempotente de las órdenes, su emisión sin doble emisión, su cancelación y dos scopes nuevos.

10-10-2026: punto de venta y caja

Empieza el módulo de punto de venta, opt-in por empresa: configuración, puntos de venta, sesiones de caja con arqueo por medio de pago, venta con pagos y vuelto, su emisión, ventas en espera, escáner, reporte Z con su CSV y dos scopes nuevos.

09-10-2026: compras y cuentas por pagar

Empieza el módulo de compras, opt-in por empresa y aparte de ventas: cuentas por pagar del RCV de compras, pagos a proveedores con su asiento, compensación, cesión como deudor, reportes, órdenes de compra con Idempotency-Key, recepción de mercadería, conciliación de 3 vías, factura de compra 46 desde la orden y carga del XML de un documento recibido.

09-10-2026: ventas y cobranza

Empieza el módulo de ventas y cobranza, opt-in por empresa: listas de precios, cotizaciones y notas de venta con PDF, envío por correo y aceptación pública, cuentas por cobrar, pagos recibidos con su asiento, límite de crédito y reportes, con cuatro scopes nuevos.

08-10-2026: inventario

El inventario es opt-in por empresa; con él apagado, la emisión no cambia. Encendido, POST /dte acepta campos nuevos, puede responder 400/409 de inventario sin consumir folio y el 201 trae un bloque inventario. Además, POST /dte lee siempre la configuración de emisión antes de validar: si no puede, 503 CONFIG_EMISION_NO_DISPONIBLE.

07-10-2026

GET /auditoria-tributaria/:empresaId/documentos y las corridas de GET .../sync/estado y de GET .../panel traen id en vez de _id, y la referencia de una nota 56/61 se valida estricta antes del folio (La referencia de una nota 56/61).

06-10-2026: cambio incompatible

formaPago es obligatoria en las facturas 33, 34 y 46: sin ella, POST /dte, el lote y la emisión masiva responden 400 antes de pedir el folio.

29-09-2026

Una API key mk_cert_ escribe siempre en certificación, aunque la empresa esté en producción, y pedir producción con ella es 403 AMBIENTE_NO_AUTORIZADO. Antes, una mk_cert_ sin ambiente emitía en el ambiente de la empresa.