# e-Boleta en beta

> Configura tu empresa, prepara por API o MCP, confirma en Connect y consulta cada intento sin reenviar.



La beta se habilita por organización. Permite intentar boletas 39 y 41 con sucursal explícita,
una línea, cantidad uno e importe entero en pesos. Cada tipo debe estar habilitado en el perfil
actual del SII. La cobertura del contrato público y las pruebas locales no acreditan una emisión
productiva anterior de tu empresa.

## Configura tu conexión [#configura-tu-conexión]

Un owner/admin entra en **Conexiones → tu conexión SII → Ajustes → e-Boleta del SII · Beta**:

1. Consulta el perfil, elige la sucursal y guarda el perfil vigente.
2. Confirma el uso exclusivo de e-Boleta del SII y concede el permiso propio de e-Boleta.
3. Activa la beta para la organización. El servicio verifica perfil, credencial y consentimiento.

Una organización ya habilitada completa esos pasos por su cuenta. Cada API key o agente que prepare
u ordene el envío también necesita `sii:boletas:write`; `sii:write` no lo sustituye.
El RUT de la empresa (`empresaRut`) y el de quien autentica (`loginRut`) tienen significados distintos.
No entregues la clave del SII a tu agente: Connect la resuelve en servidor.

## Prepara sin emitir [#prepara-sin-emitir]

Los ejemplos son sintéticos: no los envíes como una venta real. Usa el catálogo de tu conexión para
saber qué datos exige la configuración vigente. Los esquemas vienen del contrato generado de
[preparación](/docs/api/sii__boleta__previsualizar) y [emisión](/docs/api/sii__boleta__emitir).

Por REST, `POST /api/v1/tools/sii.boleta.previsualizar/execute` con bearer Connect,
`Content-Type: application/json`, `X-Connect-Connection: conn_ejemplo` y este body:

```json
{
  "input": {
    "candidato": { "tipoDte": "39", "montoTotal": 1200, "detalle": "Ejemplo sintético" }
  }
}
```

Por MCP, descubre la ficha con `search_docs` y usa la meta-tool indicada. La preparación admite
`execute_write` con estos argumentos:

```json
{
  "tool": "sii.boleta.previsualizar",
  "connectionId": "conn_ejemplo",
  "params": {
    "candidato": { "tipoDte": "39", "montoTotal": 1200, "detalle": "Ejemplo sintético" }
  }
}
```

Conserva `previewRef` en tu aplicación. Es una referencia cifrada ligada al candidato, al propietario,
a la conexión y a su configuración. No cambies los datos después de prepararlos.

## Confirma en Connect e inicia el envío [#confirma-en-connect-e-inicia-el-envío]

En el panel de e-Boleta, pulsa **Actualizar preparaciones**, abre la preparación y revisa monto,
receptor, detalle y medio de pago. **Confirmar esta preparación** es el acto humano sobre esos datos.
La confirmación no envía ni extiende el plazo: tienes como máximo 15 minutos desde la preparación
para iniciar la operación. Si vence o cambian las reglas o el perfil, prepara y confirma nuevamente.

Tu aplicación usa `POST /api/v1/tools/sii.boleta.emitir/execute`, la misma conexión y bearer,
`Idempotency-Key` con una UUID v4 nueva para esa operación y `{"input":{"previewRef":"<referencia>"}}`.
Guarda la clave y los argumentos originales antes de la llamada. Por MCP:

```json
{
  "tool": "sii.boleta.emitir",
  "connectionId": "conn_ejemplo",
  "idempotencyKey": "9a2fd694-b24d-4d07-9e62-d77a833ba10d",
  "params": { "previewRef": "<referencia confirmada>" }
}
```

La UUID del ejemplo solo ilustra el formato. Genera una propia por operación.

## SDK de TypeScript [#sdk-de-typescript]

El [SDK](/docs/sdk) está disponible en el repositorio; consulta esa página sobre su publicación.
El contrato tipado generado usa el mismo flujo:

```ts
const preparation = await connect.tools.sii.boleta.previsualizar(
  { candidato: { tipoDte: "39", montoTotal: 1200, detalle: "Ejemplo sintético" } },
  { connectionId: "conn_ejemplo" },
);
// Conserva preparation.previewRef y espera la confirmación humana en Connect.
const input = { previewRef: preparation.previewRef };
const options = { connectionId: "conn_ejemplo", idempotencyKey: crypto.randomUUID() };
// Guarda input y options antes de iniciar esta operación.
const response = await connect.tools.sii.boleta.emitir.withResponse(input, options);
// Conserva también response.meta?.operation_request_id.
```

## Consulta un resultado pendiente [#consulta-un-resultado-pendiente]

Connect guarda el compromiso antes de un único POST al SII. Un folio en la respuesta o HTTP 200
no acreditan aceptación: la reconciliación consulta la misma empresa, tipo y folio y exige un reporte
completo y concluyente.

Si recibes `resultado_desconocido`, `puedeReintentar:false` o una falla de transporte, conserva
`operation_request_id` cuando esté disponible, la UUID y los argumentos originales. Repite la misma
llamada de emisión con esa UUID para **consultar el intento guardado**. El replay del compromiso no
reenvía, no vuelve a preparar y funciona aunque la referencia ya haya vencido. Si la respuesta sigue
pendiente, espera la reconciliación automática; entrega a soporte el identificador de la operación
si no logra resolverse. Una UUID diferente puede representar otra emisión: no la uses para salir
de la incertidumbre.

Antes del compromiso, los códigos seguros distinguen perfil, configuración no soportada y datos
incompletos. El mensaje indica que la boleta no se envió y qué debes corregir. No compartas cuerpos,
credenciales, referencias cifradas ni respuestas privadas en mensajes de soporte.

## Revoca el permiso [#revoca-el-permiso]

**Revocar permiso e-Boleta** cierra la escritura de esa conexión. **Desactivar beta para la organización**
cierra nuevas preparaciones y emisiones de toda la organización. Ambas acciones siguen disponibles
fuera del flag beta. Un intento ya comprometido conserva su identidad y se consulta sin reenvío.