Facturador Pulsando — API de Facturación Electrónica SII (1.3.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. Es la única ruta que no exige 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.

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 para todas las empresas de la cartera. El límite de peticiones por minuto, en cambio, se cuenta por 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 duran segundos; en la práctica observarás sobre todo los finales. 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:

El certificado vencido no da error inmediato: se detecta al firmar/enviar (asíncrono), así que aparece como el documento quedando en rechazado con el detalle del certificado, no en la respuesta del POST.

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 duran segundos; en la práctica observarás sobre todo los finales. 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:

El certificado vencido no da error inmediato: se detecta al firmar/enviar (asíncrono), así que aparece como el documento quedando en rechazado con el detalle del certificado, no en la respuesta del POST.

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:

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: listar_empresas, emitir_dte, consultar_dte, listar_dtes, consultar_contribuyente, estado_folios, documentos_recibidos, sincronizar_rcv, listar_rcv. El agente actúa con los permisos (scopes) de la API Key, así que el paywall y los scopes por empresa se respetan.

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 AI-INTEGRATION.md en el repositorio de la documentación.

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.

Emisión y consulta de documentos tributarios electrónicos

Consulta del padrón público del SII (razón social, giros/actividades) para autocompletar y validar el receptor. Requiere el scope dte:read.

Documentos que otros contribuyentes te emiten (intercambio). Léelos y acéptalos/recházalos comercialmente por API — la API deja de ser "solo emisión". Lectura con recepcion:read; aceptar/rechazar/ingesta con recepcion:write.

Sincroniza y consulta el Registro de Compras y Ventas que el SII mantiene (para conciliación contable). Scope rcv:read.

Estado de folios disponibles (CAF) con el scope caf:read, y solicitud de nuevos folios al SII (vía robot/RPA con tu certificado) con el scope caf:write.