Emitir facturas electrónicas ante el SII por API

Emite facturas y notas ante el SII desde tus agentes. La conexión se aprovisiona sola: no hay ninguna API key que crear ni pegar.

notta emite documentos tributarios electrónicos ante el SII: facturas afectas y exentas, y notas de débito y de crédito. Es el primer conector que escribe en un sistema externo, así que su tool de emisión es la primera del catálogo marcada como destructiva y la primera que pasa por el control de idempotencia.

Notta es producto de Emisso, y eso cambia el alta: en vez de pedirte una credencial que tendrías que ir a buscar a otro portal, Connect crea la empresa en Notta y su credencial por ti.

Qué necesitas para conectar

Tres datos, y ninguno es un secreto:

Campo	Qué es
RUT de la empresa	La empresa que va a emitir.
Razón social	Su nombre legal.
Email del responsable	Quien completará el certificado digital y los folios en Notta.

No hay ninguna API key que copiar. Connect llama a Notta, crea la organización, acuña la credencial y la guarda cifrada. Nadie la ve nunca, ni tú ni el agente.

Si el RUT ya tiene una cuenta en Notta, hay dos caminos. Cuando el email que declaras es dueño o administrador de esa cuenta, la conexión queda lista en el acto. Si no lo es, Notta le envía al dueño un enlace para autorizar la vinculación con un click, y la conexión queda esperando esa respuesta.

Antes de la primera factura

Emitir ante el SII exige dos cosas que solo puede conseguir una persona: el certificado digital de la empresa y los folios (CAF) del tipo de documento. Los dos se cargan en Notta, no en Connect.

Mientras falten, la conexión responde connector_onboarding_required y el mensaje dice qué falta. No es un error de tu integración: es el trámite que todavía no termina.

Las tools

Tool	Qué hace
`notta.dte.emitir`	Emite una factura o nota. Devuelve el folio asignado.
`notta.dte.consultar`	El estado de un documento, incluido el veredicto del SII.
`notta.dte.listar`	Los documentos recientes, con filtros.
`notta.dte.descargar`	El XML o el PDF, en base64, para uso programático.
`notta.dte.reenviar`	Reenvía el documento por correo al receptor.
`notta.conexion.verificar`	Prueba la credencial sin emitir nada.

Emitir

curl -X POST https://connect.emisso.ai/api/v1/tools/notta.dte.emitir/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Idempotency-Key: 7f3c1b90-2d4e-4a11-9c6f-5b8e0a2d13c7" \
  -H "Content-Type: application/json" \
  -d '{"input":{"tipo_dte":33,"receptor_rut":"76900600-1","items":[{"nombre":"Asesoría de septiembre","cantidad":1,"precio":450000}]}}'

Respuesta (recortada):

{
  "data": {
    "id": "dte_8sKq2mR4",
    "folio": 267,
    "tipo_dte": 33,
    "estado": "queued",
    "neto": 450000,
    "iva": 85500,
    "total": 535500
  },
  "meta": { "request_id": "req_...", "tool_id": "notta.dte.emitir", "plane": "action" }
}

El folio ya está asignado y es tuyo: ese número no se reutiliza. Lo que sigue (firmar, armar el sobre, subirlo al SII y esperar el veredicto) ocurre después, y por eso el estado dice queued. Para saber cómo terminó, consulta el documento.

Emitir dos veces por accidente

Una factura duplicada no se deshace: se corrige con una nota de crédito, que es otro documento con otro folio. Por eso emitir es la única tool del catálogo que trata la repetición como parte del contrato.

Manda tu propia Idempotency-Key en el header. Si repites la llamada con la misma key y el mismo contenido, Connect devuelve la respuesta guardada sin volver a tocar Notta. Si repites la key con un contenido distinto, responde idempotency_conflict: esa key ya nombra otra operación. Y si el primer intento sigue en curso, responde idempotency_in_progress, que se reintenta a los segundos, nunca con una key nueva.

El SDK no reintenta esta llamada por su cuenta, y es deliberado.

Consultar el resultado

curl -X POST https://connect.emisso.ai/api/v1/tools/notta.dte.consultar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"id":"dte_8sKq2mR4"}}'

Respuesta (recortada):

{
  "data": {
    "id": "dte_8sKq2mR4",
    "folio": 267,
    "tipo_dte": 33,
    "estado": "aceptado",
    "track_id": "1284455901",
    "sii_glosa": "Envio Aceptado"
  },
  "meta": { "request_id": "req_...", "tool_id": "notta.dte.consultar", "plane": "action" }
}

El SII se toma su tiempo en responder, así que un documento recién emitido puede seguir en camino por varios minutos.

Verdades operativas

El ambiente lo decide la credencial, no la llamada. Una conexión aprovisionada por Connect emite contra el ambiente de certificación del SII. El request no puede forzar producción: el dato viaja en la credencial guardada.

El plan de Notta es de Notta. La cuenta nace en el plan gratuito, con su cuota mensual de documentos. Al agotarla, la respuesta es connector_plan_limit y el mensaje lleva al lugar donde se cambia el plan, que es Notta y no Connect.

Para que la factura llegue, hay dos caminos. descargar te devuelve el PDF y el XML para que hagas lo tuyo con ellos. Si lo que quieres es que le lleguen al receptor, usa reenviar, o incluye su correo al emitir: Notta se lo manda cuando el SII acepta.

No hay caché que consultar. A diferencia del SII y los bancos, este conector no sincroniza nada al plano persistido: cada consulta pregunta en vivo, porque los documentos viven en Notta.

Notta