Facturador Pulsando — API de Facturación Electrónica SII (1.5.0)

Antes de emitir, cada centro debe estar habilitado como emisor electrónico ante el SII. Es un trámite del contribuyente (no del software) y depende de su situación tributaria:

• Inicio de actividades vigente en el SII (primera categoría, afecto a IVA).
• Certificado digital propio (.p12) del representante legal — con él se firman sus DTE. Es obligatorio e intransferible entre empresas.
• Habilitación como emisor de DTE ante el SII, con los usuarios autorizados para firmar y enviar documentos.

Según el historial del centro:

La carga del certificado y de los CAF (folios) se realiza una sola vez por centro desde el portal web (no por esta API). Esta API es para emitir y consultar: una vez que el centro está habilitado y cuenta con folios, tu integración puede emitir y consultar sin restricciones.

Puesta en marcha asistida (servicio Pulsando). Dejamos a cada centro listo para emitir —acompañamiento en la postulación/certificación ante el SII y carga inicial de certificado y folios— como un servicio de onboarding. Escríbenos a contacto@pulsandotech.cl para coordinarlo.

Hay tres ambientes. Dos de ellos hablan con el SII; el de desarrollo no.

En certificación y producción, el ambiente lo determina tu API Key:

• sk_test_… → certificación (maullin) — documentos de prueba, sin validez tributaria.
• sk_live_… → producción (palena) — documentos reales con validez tributaria.

Puedes usar una key sk_test_ aunque tu empresa ya esté en producción, para probar sin emitir documentos reales. Los listados y reportes quedan acotados al ambiente de la key (los documentos de prueba nunca se mezclan con los reales).

Al registrarte se crea automáticamente una empresa gemela en ambiente de desarrollo, que copia la identidad de tu empresa (razón social, giro, dirección, tipos de documento habilitados) sobre un RUT de prueba del rango 88.8xx.xxx, para no chocar con el RUT real de ningún contribuyente. La API Key sk_test_ de esa empresa llega por correo al email de contacto del registro.

Qué hace y qué no:

• Emite de verdad: asigna folio, firma el XML (XMLDSig), genera el TED y el PDF417, y produce el PDF. El flujo que ejercitas es el mismo código de producción.
• No envía nada al SII. No hay TrackID real ni respuesta del SII.
• Folios sintéticos para los 12 tipos soportados (33, 34, 39, 41, 43, 46, 52, 56, 61, 110, 111, 112), así que no necesitas CAF ni certificado digital para probar.
• El PDF lleva el sello SIN VALIDEZ TRIBUTARIA.

La empresa de desarrollo es dominante: aunque uses una key sk_live_ contra ella, el ambiente sigue siendo mock. Un documento de desarrollo no puede convertirse en uno real por equivocación.

Cuota y vigencia. El ambiente admite 200 documentos; superado el tope, la emisión responde 429 con el conteo (cuota.usados / cuota.limite) y un contacto para ampliarlo o pasar a producción. Un ambiente sin uso durante 30 días se da de baja, con aviso por correo a los 23 días.

Webhooks. Se disparan igual que en producción, con la misma firma HMAC. Distínguelos por el cuerpo del evento: livemode es false y ambiente vale mock (ver el esquema WebhookEvent). livemode es true solo en producción.

Probar el rechazo. La aceptación del SII es asíncrona y en desarrollo no hay SII, así que ningún documento se rechaza solo. Para ejercitar esa rama usa POST /dte/{id}/simular-estado, que fuerza el estado final y dispara los mismos webhooks y notificaciones. Solo existe en desarrollo: en certificación y producción responde 403.

Toda petición al canal de integradores va con tu API Key en el header X-Api-Key:

X-Api-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• sk_live_… → producción (palena) · sk_test_… → certificación (maullin). El prefijo decide el ambiente del DTE (ver Ambientes).

Antes de tener certificado y folios: el ambiente de desarrollo. Al registrarte recibes por correo una key sk_test_ de una empresa gemela en ambiente de desarrollo, que emite, firma y genera PDF sin tocar el SII y sin exigirte certificado digital ni CAF. Se usa igual que cualquier otra key, en el mismo header. Ver Ambientes.

Dos alcances de clave. Una API Key puede pertenecer a una empresa o a una organización (estudio contable, holding, partner) que administra varios RUT emisores:

Si tu clave administra varias empresas, lee Varias empresas (estudios contables y holdings).

Gestión de keys. Se crean desde el portal web (Configuración → API Keys) y se muestran una sola vez al crearlas — guárdalas de forma segura. Cada key puede tener uno o varios de estos permisos (scopes):

⚠️ Nunca pongas una API Key en el frontend, apps móviles ni en repositorios. Úsala solo desde tu backend. Si se filtra, revócala desde el portal y crea otra.

Las rutas de acceso por token para el receptor (/api/portal/…) son la única excepción: no usan API Key (ver Enlace para el receptor).

Sí: una sola cuenta puede emitir DTE para varios RUT emisores. Es el caso de un estudio contable que factura por sus empresas cliente, de un holding con varias sociedades, o de un SaaS que revende emisión.

Ese conjunto de RUT se llama cartera, y pertenece a una organización.

1. Una clave por empresa (recomendada para emitir)

Creas una sk_live para cada RUT. La clave es la empresa: no envías ningún header extra. Si una se filtra, el daño se limita a esa empresa.

X-Api-Key: sk_live_...clave_de_la_panaderia...
POST /dte     → emite por la Panadería

2. Una clave de organización (necesaria para el MCP / agentes de IA)

Una sola clave para toda la cartera. En cada llamada indicas por qué empresa operas, con el header X-Empresa-RUT:

X-Api-Key: sk_live_...clave_del_estudio...
X-Empresa-RUT: 76354771-K
POST /dte     → emite por la Panadería

X-Empresa-RUT: 78211386-0
POST /dte     → emite por la Ferretería, con la MISMA clave

El RUT se acepta con o sin puntos y con o sin dígito verificador (76354771, 76354771-K y 76.354.771-K son equivalentes).

Elige con criterio. Una clave de organización es cómoda, pero si se filtra expone toda la cartera, no una empresa. Para emitir desde tu ERP, preferimos claves por empresa. Reserva la de organización para orquestación y para el MCP, que necesita poder elegir la empresa en cada instrucción.

GET /empresas responde la cartera sin exigir haber elegido empresa (sería circular: es la llamada con la que la descubres). Sirve para los dos tipos de clave, con la misma forma de respuesta. Las lecturas de administración (GET /organizacion/*, abajo) tampoco llevan X-Empresa-RUT: son de toda la cartera.

Con una clave de organización que tenga el permiso organizacion:read, tu ERP o tu agente de IA lee lo mismo que el socio ve en el panel del estudio, sin X-Empresa-RUT (si lo envías, se ignora):

Ojo con el ambiente: el resumen, la salud y la actividad son los reales de la organización con cualquier clave, también con una sk_test_ (no hay cobro ni actividad «de prueba»). Sólo las ventas cambian con el ambiente de la clave. Si le das organizacion:read a una clave de pruebas, esa clave ve lo que paga el estudio.

Agregar o quitar empresas, usuarios, la suscripción y las claves NO se hace por API: se hace en el portal, con la cuenta del administrador. Una clave es una credencial de máquina que puede filtrarse, y no puede tocar ni el cobro ni la cartera. Una clave de empresa recibe 403 con codigo: "requiere_llave_de_organizacion".

El header selecciona la empresa; no la inventa. El RUT emisor, la razón social, el giro y el código de actividad del DTE se leen siempre del registro de esa empresa. Si mandas un bloque emisor en el cuerpo, se ignora. Así, una clave nunca puede facturar a nombre de un RUT que no le pertenece.

Idempotencia por empresa. Si tu ERP numera las facturas por empresa, vas a repetir F-1001 en dos de ellas. Está previsto: la clave de idempotencia es por empresa emisora. Ante una colisión entre empresas respondemos 409 antes que devolverte el documento equivocado.

El plan de organización trae un cupo de DTE compartido por toda la cartera (no un tope por empresa): las que facturan poco le prestan cupo a las que facturan mucho. Al agotarse, la emisión responde 429 con pool_dte y emitidos_este_mes para todas las empresas de la cartera, y no se reintenta hasta cambiar de plan o hasta el mes siguiente. El límite de peticiones por minuto, en cambio, se cuenta por llave y empresa: el peak de una no le consume la cuota a las demás.

Emitir un DTE es asíncrono: POST /dte responde 201 con el documento en estado pendiente y lo encola para envío al SII. El estado final llega después; consúltalo con GET /dte/{id} o suscríbete a webhooks.

Boletas y facturas se emiten sin esperar la validación del SII: ya son válidas con su folio y timbre (TED), y la aceptación del SII es posterior. La única excepción son las notas de crédito/débito, cuyo envío depende de que su documento referenciado exista en el SII (ver Notas de crédito y débito).

estado_local — el estado normalizado (úsalo para tu lógica)

Los estados en curso suelen durar segundos. Si el SII está caído, la plataforma reintenta el envío por su cuenta y un documento puede quedar horas en pendiente o enviando antes de llegar a un estado final o a error_envio: eso no indica un problema de tu lado. Para decidir en caja, aceptado y aceptado_con_reparos son ambos documento válido.

estado_sii — el código crudo del SII (trazabilidad)

Aparte va estado_sii, el código tal cual lo entrega el SII (no es una lista cerrada nuestra). Los que verás en producción: EPR (envío procesado), DOK (documento aceptado), RPR (reparo → aceptado_con_reparos) y RCT/RCH/RFR (rechazos). Para tu lógica usa estado_local; estado_sii es para trazabilidad.

Errores operativos de emisión (HTTP)

Distinguibles por código HTTP, para avisar claro en caja —no un "falló" genérico:

Errores del borde HTTP (cualquier endpoint)

Todo error es JSON con message en español y, en estos casos, un codigo estable para programar contra él. Ningún mensaje trae nombres de clases, rutas de archivo ni SQL.

Filtros con valores que no existen se ignoran. GET /dte?origen=xyz o ?tipo_dte=abc no responden 422: el filtro inválido no se aplica y la lista sale sin él. Es deliberado, para no romper integraciones que ya mandan valores de más; valida tus filtros de tu lado.

Certificado vencido, no cargado o ilegible: la emisión responde 422 con codigo: "certificado_no_utilizable" y no consume folio. Se corrige subiendo un .p12 vigente en Empresa → Certificado.

Límites de peticiones

Emite desde una cola con concurrencia acotada, no en ráfagas. Superar un límite responde 429 con el header Retry-After, codigo: "demasiadas_solicitudes" y retry_after en segundos.

El límite por llave cuenta por llave y empresa, no por IP: dos integraciones que salen por la misma IP (por ejemplo, todos los clientes del MCP hospedado) no comparten cupo, y una llave inválida no gasta el de nadie (responde 401 sin contar). Los límites por IP (sandbox, registro) usan la IP real del cliente; la cabecera X-Forwarded-For que envía el cliente no la cambia.

Tamaño del documento

Son los topes del esquema del SII: un documento con más filas lo rechazaría el SII. Superarlos responde 422 con el error en la lista (errors.items) y no consume folio. Si una venta tiene más líneas, divídela en más de un documento.

Emitir un DTE es asíncrono: POST /dte responde 201 con el documento en estado pendiente y lo encola para envío al SII. El estado final llega después; consúltalo con GET /dte/{id} o suscríbete a webhooks.

Boletas y facturas se emiten sin esperar la validación del SII: ya son válidas con su folio y timbre (TED), y la aceptación del SII es posterior. La única excepción son las notas de crédito/débito, cuyo envío depende de que su documento referenciado exista en el SII (ver Notas de crédito y débito).

estado_local — el estado normalizado (úsalo para tu lógica)

Los estados en curso suelen durar segundos. Si el SII está caído, la plataforma reintenta el envío por su cuenta y un documento puede quedar horas en pendiente o enviando antes de llegar a un estado final o a error_envio: eso no indica un problema de tu lado. Para decidir en caja, aceptado y aceptado_con_reparos son ambos documento válido.

estado_sii — el código crudo del SII (trazabilidad)

Aparte va estado_sii, el código tal cual lo entrega el SII (no es una lista cerrada nuestra). Los que verás en producción: EPR (envío procesado), DOK (documento aceptado), RPR (reparo → aceptado_con_reparos) y RCT/RCH/RFR (rechazos). Para tu lógica usa estado_local; estado_sii es para trazabilidad.

Distinguibles por código HTTP, para avisar claro en caja —no un "falló" genérico:

Todo error es JSON con message en español y, en estos casos, un codigo estable para programar contra él. Ningún mensaje trae nombres de clases, rutas de archivo ni SQL.

Filtros con valores que no existen se ignoran. GET /dte?origen=xyz o ?tipo_dte=abc no responden 422: el filtro inválido no se aplica y la lista sale sin él. Es deliberado, para no romper integraciones que ya mandan valores de más; valida tus filtros de tu lado.

Certificado vencido, no cargado o ilegible: la emisión responde 422 con codigo: "certificado_no_utilizable" y no consume folio. Se corrige subiendo un .p12 vigente en Empresa → Certificado.

Emite desde una cola con concurrencia acotada, no en ráfagas. Superar un límite responde 429 con el header Retry-After, codigo: "demasiadas_solicitudes" y retry_after en segundos.

El límite por llave cuenta por llave y empresa, no por IP: dos integraciones que salen por la misma IP (por ejemplo, todos los clientes del MCP hospedado) no comparten cupo, y una llave inválida no gasta el de nadie (responde 401 sin contar). Los límites por IP (sandbox, registro) usan la IP real del cliente; la cabecera X-Forwarded-For que envía el cliente no la cambia.

Son los topes del esquema del SII: un documento con más filas lo rechazaría el SII. Superarlos responde 422 con el error en la lista (errors.items) y no consume folio. Si una venta tiene más líneas, divídela en más de un documento.

Todo DTE tiene una representación impresa generada on-demand desde el XML firmado (no se almacena), con el timbre electrónico (TED) impreso como código PDF417:

• Boletas (39/41) → formato ticket 80mm (impresora de caja).
• Resto (factura, NC/ND, guía) → formato carta.

Dos formas de obtenerla:

• GET /dte/{id}/pdf → devuelve el PDF binario (application/pdf).
• POST /dte?incluir=pdf → el 201 de la emisión incluye pdf_base64 (sin segunda llamada).

POST /dte/{id}/portal-link genera un enlace de acceso directo mediante un token único que el receptor abre sin inicio de sesión ni API Key para ver y descargar el documento. No es un recurso abierto ni indexable: el acceso se controla por el token, que es opaco y no enumerable (64 caracteres aleatorios, nunca expone IDs secuenciales). El enlace lleva X-Robots-Tag: noindex y su vigencia está atada a la retención legal del XML del documento (6 años). Llamadas repetidas reutilizan el token vigente.

Antes de enviar al SII, validamos las referencias de una NC (61) o ND (56) a un documento propio ya emitido, para evitar rechazos del SII:

• Mismo receptor. Una NC/ND debe ir al mismo receptor que el documento que corrige. Si el RUT difiere, la emisión se rechaza con 422 antes de enviar al SII (previene el código SII REF-3-751).
• Timing automático. Si la NC/ND referencia un documento propio que el SII aún no ha recibido, el envío se retrasa automáticamente hasta que el SII lo registre (previene REF-3-750). Emites y el sistema gestiona el orden; no tienes que esperar.

Cuando el SII rechaza o repara un DTE, la respuesta de GET /dte/{id} (y GET /dte) trae el objeto detalle_sii con la causa traducida a lenguaje de negocio (codigo, glosa, causa, solucion). Códigos frecuentes:

Rechazos del SOBRE (distintos de los de arriba). Antes de mirar el contenido de un documento, el SII valida el envío que lo transporta. Si falla ahí, estado_sii trae uno de estos tres códigos y detalle_sii.codigo queda en null — el SII no emite un código granular para el sobre:

Los estados SOK, CRT, FOK y PDR no son rechazos: son etapas intermedias de un envío que va bien (CRT es "Carátula OK"). El cierre exitoso del sobre es EPR.

Esta API es AI-native: puedes conectar un agente de IA (Claude, Cursor, etc.) directamente a tu facturación mediante nuestro servidor MCP (Model Context Protocol), y darle contexto a cualquier LLM con llms.txt.

1) Servidor MCP — local (npx):

{
  "mcpServers": {
    "facturador-pulsando": {
      "command": "npx",
      "args": ["-y", "@facturador-mcp-sii.cl/mcp"],
      "env": { "PULSANDO_API_KEY": "sk_test_..." }
    }
  }
}

2) Servidor MCP — remoto (OAuth 2.1): agrega un conector remoto apuntando a https://mcp.facturador.pulsandotech.cl/mcp; el cliente descubre el OAuth y el usuario autoriza con su API Key.

Herramientas expuestas (26): listar_empresas, listar_sucursales, emitir_dte, consultar_dte, consultar_estado_sii, listar_dtes, consultar_contribuyente, estado_folios, estado_solicitud_folios, tipos_autorizados, documentos_recibidos, detalle_recibido, xml_recibido, sincronizar_rcv, listar_rcv, resumen_rcv, acciones_rcv, historial_rcv, reporte_ventas, top_receptores, mi_suscripcion, mis_facturas, resumen_organizacion, salud_cartera, actividad_cartera y ventas_cartera. Las cuatro últimas son de la administración de la organización: están siempre registradas, pero sólo responden con una clave de organización con organizacion:read (ventas_cartera, además, con dte:read); con otra clave responden 403. El agente actúa con los permisos (scopes) de la API Key, así que los scopes por empresa se respetan.

El canal de IA corresponde a los planes Profesional, Empresa, Estudio contable y Plataforma; con otro plan puede responder 403 con upgrade_required: true.

Varias empresas (estudios contables). Si la clave es de una organización, el agente puede operar toda la cartera: cada herramienta acepta un parámetro empresa con el RUT emisor, y listar_empresas le dice cuáles administra. Así funciona "emite la factura de este mes para la Panadería" sin que el agente tenga que adivinar el RUT.

→ listar_empresas
← Panadería Don Pedro (76354771-K) · Ferretería La Clave (78211386-0)

→ emitir_dte  empresa="76354771-K"  tipo_dte=33 …
← Folio 1042, estado pendiente — emitido por la Panadería

Requiere el paquete @facturador-mcp-sii.cl/mcp 0.3.0 o superior.

3) llms.txt: resumen de la API para LLMs en https://www.facturador.pulsandotech.cl/llms.txt. Pégalo como contexto o úsalo con herramientas que lo carguen automáticamente.

4) Prompt de integración listo para copiar en tu asistente: ver PROMPT-MAESTRO-INTEGRACION.md en el repositorio de la documentación (reemplaza al prompt anterior de AI-INTEGRATION.md).

Esta API procesa datos personales (RUT, razón social, direcciones, correos). Consulta la sección "Seguridad y cumplimiento" del README para tus obligaciones como responsable de datos y las medidas que aplicamos.

Prueba tu integración sin registrarte y sin API Key. Valida el payload con las mismas reglas que la emisión real, pero no crea nada ni envía al SII.

Qué empresas emisoras administra tu API Key. Punto de partida para las claves de organización (estudios contables, holdings): responde la cartera sin exigir que hayas elegido una empresa.

Lecturas de administración de un estudio contable u holding: resumen y cobro, salud y actividad de la cartera, y el consolidado de ventas. Sólo lectura: agregar o quitar empresas, usuarios, la suscripción y las claves se hace en el portal.

Requieren una clave de organización vigente con el permiso organizacion:read, que se elige al crear la clave (ninguna clave existente lo trae). GET /organizacion/ventas exige además dte:read: son documentos de cada empresa, y es el mismo permiso que GET /reportes/ventas. No llevan X-Empresa-RUT: la consulta es de toda la cartera vigente; las empresas retiradas de la cartera no aparecen.

No dependen del ambiente de la clave (salvo las ventas): una sk_test_ con organizacion:read lee el cobro, la salud y la actividad reales de la organización. Dale el permiso sólo a claves que puedan verlo.

GET /organizacion/ventas tiene además su propio límite: 10 peticiones por minuto por organización, sumando todas sus claves. Al pasarlo responde 429 con codigo: "demasiadas_solicitudes", retry_after y el header Retry-After.

Emisión y consulta de documentos tributarios electrónicos