API docs by Redocly

NinfaDTE API (1.0.0)

Download OpenAPI specification:

License: Propietario

Contrato publico de la API de facturacion electronica NinfaDTE (dteapi.ninfasolutions.com).

Es la fuente unica de verdad: de aqui se generan el cliente TypeScript del panel, las tools del servidor MCP y la referencia de API del sitio publico.

La API real es Rust stdlib artesanal; este spec se mantiene a mano y un test de contrato (npm run validate) valida los ejemplos contra sus schemas para detectar drift.

Convenciones

  • Base path: /v1.
  • Tenant siempre en el path: /v1/tenants/{tenant_id}.
  • Ambiente: header obligatorio X-DTE-Environment: certification | production | sandbox en las mutaciones que lo requieren. sandbox nunca contacta al SII y no emite documentos legales.
  • Auth: Authorization: Bearer <api_key> en todas las rutas /v1/tenants/{tenant_id}/.... La key se guarda como SHA-256 y queda asociada a un tenant.
  • Montos: enteros en pesos chilenos. Fechas: YYYY-MM-DD. Timestamps: ISO 8601 UTC.
  • Errores: envelope plano { "error": "codigo" }; algunos agregan reason y/o preflight.

Transparencia SII (el diferenciador)

Cada documento expone su estado REAL ante el SII: firmado -> enviado (trackid) -> aceptado / rechazado / con reparos, con la glosa oficial como evidencia (GET /v1/tenants/{tenant_id}/documents/{document_id}/sii-status).

Estado del servicio y tipos de documento soportados

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "document_types": [
    ]
}

Catalogo de tipos DTE soportados

Responses

Response samples

Content type
application/json
{
  • "document_types": [
    ]
}

Verificador SII

Sondas publicas contra datos del SII (sin secretos del tenant).

Verificador N0: ¿puede una empresa emitir DTE?

Consulta publica del registro del SII (ee_empresa_rut), sin certificado ni token. No expone datos de ningun tenant. Requiere DTE_SII_ENABLE_REAL_HTTP=1 en el servidor.

query Parameters
rut
required
string
Example: rut=78427717-8
environment
string
Default: "certification"
Enum: "certification" "production"

Responses

Response samples

Content type
application/json
Example
{
  • "authorized": true,
  • "environment": "certification",
  • "rut": "78427717-8",
  • "legal_name": "TENGO CITA SPA",
  • "resolution": {
    },
  • "documents": [
    ]
}

Tenant

Metadatos y resumen del tenant autenticado.

Metadatos del tenant autenticado

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "demo",
  • "status": "active",
  • "created_at": "2026-06-25T12:00:00Z"
}

Resumen operativo del tenant

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1

Responses

Response samples

Content type
application/json
{
  • "tenant_id": 1,
  • "counts": {
    },
  • "drafts_by_status": {
    },
  • "documents_by_status": {
    }
}

Contribuyentes

Emisores (taxpayers) dentro del tenant.

Listar contribuyentes del tenant

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1

Responses

Response samples

Content type
application/json
{
  • "taxpayers": [
    ]
}

Crear contribuyente (emisor) en el tenant

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
Request Body schema: application/json
required
rut
required
string
legal_name
required
string
activity_code
string
address
string

Responses

Request samples

Content type
application/json
{
  • "rut": "76192083-9",
  • "legal_name": "Demo SpA",
  • "activity_code": "620200",
  • "address": "Direccion 123"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "rut": "76192083-9",
  • "legal_name": "Demo SpA",
  • "status": "active"
}

Ver un contribuyente

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
taxpayer_id
required
integer <int64>
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "rut": "76192083-9",
  • "legal_name": "Demo SpA",
  • "status": "active",
  • "activity_code": "620200",
  • "address": "Direccion 123"
}

Certificados

Carga y listado de certificados P12 (cifrados; nunca se devuelven).

Listar certificados (solo metadatos)

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
query Parameters
taxpayer_id
required
integer <int64>
Example: taxpayer_id=1

Responses

Response samples

Content type
application/json
{
  • "certificates": [
    ]
}

Cargar certificado P12 (cifrado)

Valida que el PKCS#12 cargue con la password antes de guardar. La respuesta nunca incluye P12 ni password.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
Request Body schema: application/json
required
taxpayer_id
required
integer <int64>
subject_rut
string
valid_from
string <date>
valid_to
string <date>
pkcs12_base64
required
string

P12 en base64. Nunca se devuelve.

pkcs12_password
required
string

Password del P12. Nunca se devuelve ni loguea.

Responses

Request samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "subject_rut": "76192083-9",
  • "valid_from": "2026-01-01",
  • "valid_to": "2027-01-01",
  • "pkcs12_base64": "base64-del-p12",
  • "pkcs12_password": "password-del-p12"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "taxpayer_id": 1,
  • "subject_rut": "76192083-9",
  • "valid_from": "2026-01-01",
  • "valid_to": "2027-01-01",
  • "pkcs12_sha256": "hex...",
  • "status": "active"
}

Generar un P12 sandbox de desarrollo (demo)

Genera server-side un P12 de desarrollo (CA local) y lo registra como certificado activo. Solo demo; nunca contacta al SII.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
Request Body schema: application/json
required
taxpayer_id
required
integer <int64>
rut
string
legal_name
string

Responses

Request samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "rut": "76.192.083-9",
  • "legal_name": "Demo SpA"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "taxpayer_id": 0,
  • "subject_rut": "string",
  • "valid_from": "string",
  • "valid_to": "string",
  • "pkcs12_sha256": "string",
  • "status": "active"
}

Autorizaciones SII

Resolucion/autorizacion SII por contribuyente y ambiente.

Listar autorizaciones SII

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
query Parameters
taxpayer_id
required
integer <int64>
Example: taxpayer_id=1

Responses

Response samples

Content type
application/json
{
  • "authorizations": [
    ]
}

Registrar autorizacion/resolucion SII

No consulta SII. sandbox no usa autorizacion y se rechaza aqui.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
Request Body schema: application/json
required
taxpayer_id
required
integer <int64>
environment
required
string (Environment)
Enum: "certification" "production" "sandbox"
resolution_number
required
string
resolution_date
required
string <date>

Responses

Request samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "resolution_number": "0",
  • "resolution_date": "2020-01-01"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "resolution_number": "0",
  • "resolution_date": "2020-01-01"
}

CAF y folios

Carga de CAF (cifrado) y estado de folios.

Listar CAF (solo metadatos)

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
query Parameters
taxpayer_id
required
integer <int64>
Example: taxpayer_id=1

Responses

Response samples

Content type
application/json
{
  • "caf_files": [
    ]
}

Cargar CAF (cifrado)

Guarda el CAF cifrado e inicializa el contador de folios. sandbox se rechaza. La respuesta nunca incluye el XML crudo.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
Request Body schema: application/json
required
taxpayer_id
required
integer <int64>
environment
required
string (Environment)
Enum: "certification" "production" "sandbox"
authorized_at
string <date>
caf_xml_base64
required
string

CAF (contiene RSASK = secreto). Nunca se devuelve.

Responses

Request samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "authorized_at": "2026-01-01",
  • "caf_xml_base64": "base64-del-caf"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "doc_type": 33,
  • "folio_from": 1,
  • "folio_to": 50,
  • "caf_sha256": "hex..."
}

Estado de folios por contribuyente/ambiente/tipo

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
query Parameters
taxpayer_id
required
integer <int64>
Example: taxpayer_id=1
environment
required
string (Environment)
Enum: "certification" "production" "sandbox"
doc_type
required
integer
Example: doc_type=33

Responses

Response samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "doc_type": 33,
  • "next_folio": 1,
  • "available_until": 50,
  • "remaining": 50,
  • "active_caf_files": [
    ]
}

Onboarding

Checklist de habilitacion para emitir.

Checklist de habilitacion para emitir

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
taxpayer_id
required
integer <int64>
Example: 1
query Parameters
environment
required
string (Environment)
Enum: "certification" "production" "sandbox"
doc_type
required
integer
Example: doc_type=33

Responses

Response samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "doc_type": 33,
  • "status": "ready_for_issue",
  • "checks": {
    }
}

Documentos

Drafts, emision, documentos emitidos y su timeline SII.

Listar drafts (metadatos, sin payload)

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
query Parameters
taxpayer_id
required
integer <int64>
Example: taxpayer_id=1

Responses

Response samples

Content type
application/json
{
  • "drafts": [
    ]
}

Crear draft de documento

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
Request Body schema: application/json
required
taxpayer_id
required
integer <int64>
doc_type
required
integer
issue_date
string <date>
required
object (DraftRecipient)
required
Array of objects (DraftItem)
Array of objects (DraftReference)
object

Responses

Request samples

Content type
application/json
{
  • "taxpayer_id": 1,
  • "doc_type": 33,
  • "issue_date": "2026-06-25",
  • "recipient": {
    },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "draft",
  • "taxpayer_id": 1,
  • "doc_type": 33,
  • "totals": {
    },
  • "created_at": "2026-06-25T12:00:00Z"
}

Ver un draft (incluye payload rehidratable)

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
draft_id
required
integer <int64>
Example: 1

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "status": "draft",
  • "taxpayer_id": 0,
  • "doc_type": 0,
  • "totals": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

Emitir un draft

En certification/production responde 501 (emision legal aun no habilitada por API), con preflight no destructivo si hay Idempotency-Key y DB. En sandbox crea un documento de laboratorio sin valor legal. Idempotency-Key obligatorio en sandbox.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
draft_id
required
integer <int64>
Example: 1
header Parameters
X-DTE-Environment
string (Environment)
Enum: "certification" "production" "sandbox"
Idempotency-Key
string
Example: issue-2026-07-15-0001

Obligatorio en sandbox y en emision legal. Un retry con la misma key nunca duplica un envio.

Request Body schema: application/json
optional
send_to_sii
boolean

Responses

Request samples

Content type
application/json
{
  • "send_to_sii": true
}

Response samples

Content type
application/json
{
  • "id": 123,
  • "draft_id": 2,
  • "status": "sandbox_issued",
  • "taxpayer_id": 1,
  • "environment": "sandbox",
  • "doc_type": 33,
  • "folio": 2,
  • "sii_track_id": null,
  • "xml_sha256": "hex...",
  • "totals": {
    },
  • "legal_value": false,
  • "signature": "SandboxSignature RSA-SHA256, not XMLDSig",
  • "created_at": "2026-06-26T12:01:00Z"
}

Listar documentos emitidos (metadatos, sin XML)

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
query Parameters
taxpayer_id
required
integer <int64>
Example: taxpayer_id=1

Responses

Response samples

Content type
application/json
{
  • "documents": [
    ]
}

Ver un documento emitido

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123

Responses

Response samples

Content type
application/json
{
  • "id": 123,
  • "status": "submitted",
  • "taxpayer_id": 1,
  • "environment": "certification",
  • "doc_type": 33,
  • "folio": 456,
  • "recipient_tax_id": "11111111-1",
  • "sii_track_id": "123456789",
  • "totals": {
    },
  • "created_at": "2026-06-25T12:01:00Z"
}

Descargar el XML firmado

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized"
}

Descargar la representacion impresa (PDF)

Implementado para documentos sandbox_issued. Para certification/production responde 501 hasta el renderer legal.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized"
}

SII

Envio, consulta de estado y autenticacion contra el SII.

Verificador N1: ¿puede tu certificado firmar POR tu empresa?

Sonda QueryEstUp con el RUT de la EMPRESA para distinguir "mi certificado sirve" de "puedo emitir por la empresa". Solo certification. Requiere token SII activo.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
taxpayer_id
required
integer <int64>
Example: 1
header Parameters
X-DTE-Environment
string (Environment)
Enum: "certification" "production" "sandbox"

Responses

Response samples

Content type
application/json
{
  • "authorized_signer": true,
  • "environment": "certification",
  • "taxpayer_rut": "78427717-8",
  • "signer_rut": "12345678-9",
  • "sii_state": "001",
  • "sii_glosa": "SEMILLA VALIDA"
}

Obtener/renovar token de autenticacion SII

Por defecto responde 501 con un preflight no destructivo. Con DTE_SII_ENABLE_REAL_HTTP=1 y preflight ready_for_auth, en certification pide semilla, firma XMLDSig con el P12 del certificado activo, pide token y lo cachea cifrado.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
taxpayer_id
required
integer <int64>
Example: 1
header Parameters
X-DTE-Environment
string (Environment)
Enum: "certification" "production" "sandbox"
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Timeline SII local del documento

Lee envios/eventos ya guardados; no consulta SII. No devuelve el XML de respuesta.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123

Responses

Response samples

Content type
application/json
{
  • "document_id": 123,
  • "current_status": "submitted",
  • "submissions": [
    ],
  • "events": [
    ]
}

Enviar el documento al SII (DTEUpload)

Por defecto responde 501 con preflight no destructivo (no expone signed_xml ni contacta SII). Con DTE_SII_ENABLE_REAL_HTTP=1, token activo y documento ready_for_upload, se habilita solo en certification: arma multipart, hace POST a maullin, parsea RECEPCIONDTE y persiste el recibo.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Consultar el estado del documento en el SII (QueryEstUp)

Por defecto responde 501 (con preflight en certification si hay DB). Con transporte real habilitado y preflight ready_for_refresh, consulta QueryEstUp en maullin y persiste el evento. Para documentos sandbox_issued devuelve el estado local sin consultar SII.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": 123,
  • "status": "accepted",
  • "sii_track_id": "123456789",
  • "sii": {
    },
  • "checked_at": "2026-06-25T12:10:00Z"
}

Entregas

Envio de DTE por email y su cola de entregas.

Encolar envio del DTE por email

Encola la entrega y declara el adjunto XML. El PDF se agregara cuando el renderer legal exista.

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123
Request Body schema: application/json
required
to
required
Array of strings <email> [ items <email > ]
cc
Array of strings <email> [ items <email > ]
bcc
Array of strings <email> [ items <email > ]
subject
string
message
string

Responses

Request samples

Content type
application/json
{
  • "to": [],
  • "cc": [ ],
  • "bcc": [ ],
  • "subject": "DTE 33 folio 456",
  • "message": "Adjuntamos XML."
}

Response samples

Content type
application/json
{
  • "delivery_id": 1,
  • "document_id": 123,
  • "status": "pending",
  • "to": [],
  • "attachments": [
    ]
}

Listar entregas del documento

Authorizations:
bearerApiKey
path Parameters
tenant_id
required
integer <int64>
Example: 1
document_id
required
integer <int64>
Example: 123

Responses

Response samples

Content type
application/json
{
  • "document_id": 123,
  • "deliveries": [
    ]
}