Skip to main content
Aquí registramos cada cambio de la API de Tupana que se nota desde tu integración: endpoints nuevos, campos, eventos de webhook, tipos de documento, límites y cambios de comportamiento. Las fechas son las de salida a producción. Suscríbete por RSS para enterarte de cada novedad.
​
SDKs, MCP y documentación
​
MCP y documentos programados
  • Servidor MCP: create_sale_invoice deja la factura como borrador y la emisión pasa por revisar su vista previa (get_document_preview y luego emit_document). La herramienta acepta referencias (orden de compra 801, HES), forma de pago y vencimiento (payment_method, due_date, due_days). get_document_link entrega el PDF oficial del SII. Ver Servidor MCP.
  • Documentos programados: cada línea puede llevar su propia currency; si no la envías, se usa la moneda del documento.
​
Guía de despacho y libros del SII
  • Guía de despacho (DTE 52): campos de la Resolución Exenta N°154 del SII, con avisos en la respuesta de la API hasta la fecha de entrada en vigencia. Ver Documentos.
  • Anulación de guías con motivo: POST /v2/documents/{id}/states/ con event_code ANNULLED y reason.
  • Con el facturador gratuito del SII, el destino y el tipo de despacho de la guía se aceptan y se imprimen como texto en el detalle, en vez de rechazar el documento.
  • Nuevo endpoint de detalle del libro de compras y ventas (/v1/book-documents/ y /v2/book-documents/): una fila por documento del Registro de Compras y Ventas con sus montos e impuestos.
​
Webhooks
  • Si no eliges api_version al crear un webhook, se usa la de la ruta: los creados por /v1/webhooks/ nacen en versión 1 (ids enteros) y los creados por /v2/webhooks/ en versión 2 (ids públicos docu_…, ment_…).
  • Nuevos GET, PATCH y DELETE sobre /v2/webhooks/{id}/. Con PATCH subes un webhook existente a api_version: 2.
​
Exportación
  • País y nacionalidad del receptor en facturas de exportación, separados del país de destino. Ver Países de exportación.
​
Idempotencia
  • Al reenviar un lote con el mismo Idempotency-Key, la respuesta incluye el batch_id del lote original.
  • El header Idempotency-Key se puede enviar desde el navegador (permitido en CORS).
​
Webhooks
  • Nuevo campo environment en los webhooks: production, sandbox o both (por defecto). Así un mismo endpoint recibe sólo los eventos del ambiente que elijas. Ver Webhooks.
​
Conexiones y consola de developers
  • Nuevos endpoints de conexiones: listar y desactivar las empresas conectadas. /v2/connections/ acepta API key y sesión de usuario.
  • La conexión de un banco por Tupana Link se da por activa cuando el banco entrega las cuentas, y en ese momento se envía el webhook connection.active (o connection.requires_action).
  • Consola de developers en developers.tupana.ai/console: crea tu cuenta y tus API keys.
​
Bases de datos gratuitas y MCP
​
Tupana Link y emisión v2
  • Tupana Link: el widget hospedado con el que tus usuarios conectan su empresa (SII y bancos). En v2 reemplaza la creación de credenciales por API. Nuevos eventos de webhook connection.active y connection.requires_action.
  • additional_info en documentos (creación, detalle, listado y webhooks). Se imprime en el PDF y queda fija cuando el documento tiene folio.
  • Emisión v2: ya no es necesario enviar master_entity_id; el emisor se toma de document_issuer. En sandbox no se exige credencial del SII y la vista previa del borrador funciona igual que en producción.
​
Sandbox y documentos
  • Con una API key de sandbox, el listado de documentos devuelve los documentos de producción y los de sandbox de la empresa.
  • Las respuestas v2 de documentos vuelven a incluir el json_param que enviaste al crear.
​
Cesiones
  • Un lote de cesión lo puede pedir quien tiene hoy la factura, no sólo su emisor original.
​
API v2
​
Guía de despacho y validación
  • Emisión de guías de despacho (DTE 52) con transporte, destino, despacho, datos de Aduana y líneas exentas. Las guías de exportación aceptan el código de traslado excepcional (transfer_issuer_code) y su resolución. Ver Códigos de transporte y Aduana.
  • El lote de emisión avisa los campos desconocidos en warnings. Las API keys nuevas validan en modo estricto y responden 422 antes de crear el lote; las existentes quedan en modo aviso.
  • El detalle de un lote acepta el id público o el UUID.
  • La API v1 mantiene sus ids enteros: las integraciones existentes no cambian.
​
API v2
  • Lanzamiento de la API v2: ids públicos con prefijo (docu_…, ment_…), listas paginadas uniformes, selección de campos y taxonomía de errores con códigos estables (parameter_*, resource_missing y códigos propios de cesiones y recaudación).
  • Las respuestas v2 no exponen estado interno del servidor (trazas crudas del SII, registros de actualización).
  • Reenviar un lote con un Idempotency-Key ya procesado devuelve el lote original (200) sin volver a emitir al SII.
​
Exportación
  • Forma de pago de exportación por API.
​
Exportación
​
Boletas
  • Boleta de espectáculo por cuenta de terceros: la línea de detalle acepta show_item_type, principal_rut y un bloque ticket, en POST /v1/documents/batch/ y en v2.
​
Exportación y folios
  • Facturas de exportación: el tipo de cambio se alinea con la fecha de emisión del DTE y los puertos de embarque y desembarque se completan desde el país de destino.
  • Los errores de folios traen error_code (vocabulario cerrado para decidir si reintentar) y sii_code. Ver Códigos de error de folios.
​
Límites
  • La búsqueda por folio en el listado de documentos tiene un límite de 30 consultas por hora por API key. Al superarlo, la API responde 429.
​
Documentos y folios
  • Las referencias de notas de crédito y débito aceptan reference_code (CodRef del SII: 1 anula, 2 corrige texto, 3 corrige montos).
  • Documentos programados: reajuste del precio por IPC cada cierta cantidad de meses.
  • Las consultas de folios al SII pasan a ser un recurso propio: /v2/folio-queries/.
​
Folios, referencias y límites
  • API de folios: disponibilidad, timbraje de folios y retiro del CAF, con los webhooks folio_request.completed, folio_request.failed y folio_request.authorized_without_caf.
  • Las referencias aceptan un tipo de documento definido por tu empresa (hasta 3 caracteres, por ejemplo HES).
  • El detalle de un documento tiene un límite de 600 consultas por hora por API key y de 60 por hora sobre un mismo documento. Al superarlo, la API responde 429; para enterarte de cambios de estado usa webhooks.
​
Sandbox
  • Los documentos de sandbox se timbran con un XML de la misma estructura que en producción y un PDF real con marca de agua de vista previa.
​
Webhooks
  • Nuevo evento document.trace_updated: un aviso por cada evento nuevo de la traza del SII (acuses, reclamos, rechazos), tanto de documentos emitidos como recibidos. El payload trae role para saber de qué lado estás.
​
Documentos
  • Filtro json_param__<clave>=<valor> en el listado de documentos para buscar por los datos propios que enviaste al emitir.
​
Webhooks
  • Envío de webhooks más estable: se limita la cantidad de conexiones simultáneas a cada endpoint y las conexiones se reutilizan.
  • Un webhook se desactiva automáticamente sólo ante una caída sostenida de tu endpoint (100 fallos seguidos), no por un error puntual.
​
Cesiones
​
Cesiones
  • Parámetro document_type=issued|received en el listado de cesiones: consulta también las facturas de tus proveedores que fueron cedidas a un tercero.
​
Boletas de honorarios
​
Consultas al SII
​
Credenciales
​
Boletas
  • Boletas 39 y 41 aceptan gross_unit_price (precio con IVA incluido): el total emitido coincide al peso con el monto que cobraste.
​
Webhooks
  • document.issue_failed incluye data.error con message, code y type del último intento fallido.
​
Boletas
  • Boletas 39 y 41 aceptan líneas con monto negativo (descuentos por línea).
​
Boletas de honorarios
  • Anulación de boletas de honorarios (DTE 80) por API con PATCH /v1/documents/batch/ y patch: {"annulled": true}.
​
Webhooks
  • document.paid y el nuevo document.unpaid se envían en cada cambio del estado de pago, también en los cambios masivos.
​
Recaudación
​
Cesiones
​
Webhooks
  • Nuevo evento credential.invalid: te avisa cuando la clave de una empresa deja de funcionar en el SII.
​
Cesiones
​
Documentos y recaudación
  • ?include_trace_events=true en el listado de documentos devuelve la traza completa del SII de cada documento.
  • Las solicitudes de cobro suman el estado issued cuando se emite su documento.
​
MCP
  • Servidor MCP de Tupana con inicio de sesión OAuth 2.1: consulta documentos, clientes y libros, y emite facturas desde agentes de IA compatibles con MCP. Ver Servidor MCP.
​
Recaudación
  • API de Recaudación bajo /v1/ con API key: solicitudes de cobro con link de pago, datos bancarios de la empresa y emisión del documento al pagar.
  • Webhooks payment_request.paid, payment_request.document_issued y payment_request.expired. Ver Webhooks de recaudación.
​
Documentos
  • En el detalle de un borrador fuera de sandbox, pdf_url viene siempre presente y en null hasta que el documento se emite.
​
Emisión en lote
  • Los documentos de un lote que quedaron en error permanente se pueden reintentar con el mismo Idempotency-Key.
​
Documentos
  • Nuevos tipos de referencia: contrato y nota de pedido.
​
Documentos
  • Estado de pago por API: PATCH /v1/documents/batch/ con patch: {"payment_status": "paid" | "unpaid" | "partially_paid"} y paid_amount para pagos parciales. El estado se refleja en el detalle y el listado.
​
Webhooks y boletas de honorarios
  • Nuevos eventos document.issue_failed, document.updated y de documentos programados (scheduled_document.created, scheduled_document.updated, scheduled_document.run_started, scheduled_document.run_succeeded, scheduled_document.run_failed), más webhook.test para probar tu endpoint.
  • Usuarios autorizados para emitir boletas de honorarios por empresa. Ver Boletas de honorarios.
​
Documentos
​
Webhooks
  • Crea y lista webhooks por API con /v1/webhooks/. Ver Webhooks.
​
Cesiones
​
Exportación
  • Nota de débito de exportación (DTE 111).
​
Documentos programados y honorarios
  • API de documentos programados (/v1/scheduled-documents/): facturación recurrente con ajuste a días hábiles y tipo de cambio del día para exportación.
  • Boletas de honorarios (DTE 80 y 90) y nota de crédito de exportación (DTE 112).
​
Documentos
  • Guía de despacho (DTE 52) y nota de débito (DTE 56) en la emisión por API.
​
Sandbox
  • API keys de sandbox: emiten documentos simulados sin enviar nada al SII. Ver Autenticación.
​
Exportación y credenciales
​
Lanzamiento de la API v1
  • Emisión en lote con POST /v1/documents/batch/: asíncrona, con Idempotency-Key y consulta del lote por id. Incluye boletas 39 y 41.
  • Autenticación con el header Authorization: Api-Key <tu_key>. Ver Autenticación.
  • Webhooks de documentos: document.issued, document.delivered, document.rejected, document.paid y document.cancelled, con historial de entregas.
​
Primeros endpoints