Desarrolladores
API REST para emitir DTEs en Chile
Clave de API, idempotencia por header, paginación por cursor y webhooks firmados con HMAC. Referencia OpenAPI y colección Postman.
Quickstart
De cero a un DTE aceptado
1. Crea la organización y toma la clave
Un POST sin autenticación. Devuelve el apiKey, que se entrega una sola vez.
curl -X POST https://api.factit.cl/api/signup \
-H "Content-Type: application/json" \
-d '{
"organizationName": "ACME SpA",
"organizationSlug": "acme",
"email": "facturacion@acme.cl"
}'
# La respuesta trae el apiKey. Se entrega UNA sola vez:
# guárdalo en un secret store, nadie puede recuperarlo después.
# {
# "tenantId": "8b8d3c5c-…",
# "apiKey": "fct_8a1c…",
# "organizationSlug": "acme"
# }2. Emite el documento
El Idempotency-Key no es opcional en la práctica: sin él, cada llamada toma un folio nuevo, así que un timeout de red te cuesta un folio y una nota de crédito. Con él, repetir la llamada devuelve el documento que ya existe.
curl -X POST https://api.factit.cl/api/dtes \
-H "Authorization: Bearer fct_8a1c…" \
-H "Idempotency-Key: pedido-12345" \
-H "Content-Type: application/json" \
-d '{
"companyId": "11111111-…",
"dteType": 33,
"issueDate": "2026-08-27",
"receptor": {
"taxNumber": "55555555-5",
"legalName": "Cliente Real SpA",
"address": "Calle 1",
"district": "Las Condes",
"city": "Santiago"
},
"items": [
{ "lineNumber": 1, "name": "Asesoría agosto",
"quantity": 1, "unitPrice": 1000000, "lineAmount": 1000000 }
]
}'3. Presenta el sobre al SII
Emitir y presentar son dos pasos distintos porque el SII recibe sobres, no documentos: uno puede llevar varios DTE al mismo receptor.
# El DTE existe y está firmado, pero el SII todavía no lo vio.
# El sobre es el que se presenta:
curl -X POST https://api.factit.cl/api/envios \
-H "Authorization: Bearer fct_8a1c…" \
-H "Content-Type: application/json" \
-d '{
"companyId": "11111111-…",
"receiverTaxNumber": "55555555-5",
"dteIds": ["<id-del-dte>"]
}'
# Estados terminales esperados:
# envio.status = "processed" (EPR) → el SII procesó el sobre
# dte.status = "accepted" (DOK) → aceptó el documentoCobertura
Lo que cubre la API
Emisión
POST /api/dtes crea el documento, lo timbra y lo firma. Con Idempotency-Key, repetir la llamada no consume un folio extra.
Envío al SII
POST /api/envios arma el sobre y lo presenta. Devuelve el trackId del SII.
Seguimiento de estado
GET /api/dtes/:id trae el estado con la glosa del SII, y GET /api/envios/:id el del sobre.
PDF con timbre
GET /api/dtes/:id/pdf devuelve la representación impresa con el PDF417.
Envío al receptor
POST /api/dtes/:id/email despacha el XML firmado y el PDF a la casilla de intercambio del receptor.
Recepción
GET /api/inbound/dtes lista los documentos que te llegaron por intercambio, con su XML original.
Acuses
POST /api/inbound/dtes/:id/acknowledge y /recibo emiten el acuse y el recibo de mercaderías de la Ley 19.983.
Webhooks
POST /api/webhooks/subscriptions da de alta una suscripción, con secreto rotable y reenvío desde la cola de fallidos.
Boletas y libros
POST /api/boletas para el sobre de boletas, y /api/consumo-folios para el reporte diario de folios.
Webhooks
Los eventos, con su nombre exacto
Suscribes una URL, filtras los eventos que te interesan y recibes la entrega firmada con HMAC. Con reintentos, cola de fallidos y reenvío manual.
| Evento | Qué significa |
|---|---|
dte.issued | El DTE quedó timbrado y firmado. Todavía no se presentó al SII. |
dte.sent | El sobre que lo contiene se subió al SII y ya tiene trackId. |
dte.accepted | El SII aceptó el documento. |
dte.objected | Aceptado con reparos. El SII lo dio por bueno, con observaciones. |
dte.rejected | El SII rechazó el documento. |
inbound_dte.received | Llegó un DTE de compra por intercambio y quedó guardado. |
folios.low | Un tipo de documento llegó al umbral de folios disponibles. |
folios.exhausted | No quedan folios y una emisión falló por eso. |
integration.document_failed | Un documento del ERP quedó en la bandeja de errores del conector. |
integration.connection_paused | El motor pausó una conexión por credenciales o cambios de esquema. |
Los nombres son parte del contrato público: se agregan eventos nuevos, no se renombran los existentes. Y cada entrega lleva una clave de deduplicación, así que el mismo cambio de estado no llega dos veces aunque el poll lo observe varias veces.
Sandbox
Gratis e ilimitado
Una empresa de prueba completa, con certificado y folios, creada con un POST. Gratis, sin límite de documentos y sin necesidad de haber certificado.
Los documentos del sandbox recorren el pipeline completo —timbre electrónico, firma, validación contra el esquema del SII y PDF con PDF417—, así que lo que falla ahí es lo que habría fallado de verdad. Lo que no hacen es presentarse al SII: los folios son sintéticos y una empresa de sandbox no puede apuntar a producción, por restricción en la base de datos. Cuando quieras probar contra el SII de verdad, eso es el ambiente de certificación, y también va incluido.
Empresa completa
Con certificado y CAF sintéticos, creada con un POST.
Pipeline real
Timbre, firma, validación de esquema y PDF con PDF417.
Sin riesgo
Una empresa de sandbox no puede apuntar a producción, por restricción en la base de datos.
Referencias
Dónde seguir
Referencia OpenAPI
El esquema completo, con cada endpoint, cada campo y cada código de error. Es la fuente desde la que se generan los SDK.
Colección Postman
Todos los endpoints con su environment, para explorar la API sin armar
curls a mano. Se pide por contacto mientras no esté publicada.
Preguntas técnicas
¿Cómo evito emitir dos veces el mismo documento?
Con el header `Idempotency-Key` en `POST /api/dtes`. Repetir la llamada con la misma clave devuelve el documento que ya existe en vez de crear otro, así que un timeout de red no te consume un folio extra. Sin el header, cada llamada toma un folio nuevo.
¿Cómo me entero de que el SII aceptó un documento?
Con webhooks. Suscribes una URL a los eventos que te interesan y recibes la entrega firmada con HMAC, con reintentos y cola de fallidos. El polling a `GET /api/dtes/:id` funciona, pero no es el camino: para eso están los eventos.
¿El sandbox llega al SII?
No, y es a propósito. Los documentos del sandbox recorren el pipeline completo —timbre, firma, validación de esquema y PDF—, pero con folios sintéticos y sin presentarse al SII, así que puedes emitir todo lo que quieras sin quemar nada. Para probar de verdad contra el SII está el ambiente de certificación.
Toma una clave de API y prueba
El signup es un POST y el sandbox es gratis e ilimitado. No hay demo que agendar para escribir la primera integración.
Sin tarjeta de crédito. La certificación ante el SII va incluida.