# Carpeta tributaria puntual

> Solicita el PDF original del SII mediante el widget y recibe el resultado por API o webhook.



Esta capacidad está en piloto y requiere habilitación de tu organización. El receptor se configura en el servidor. Quien abre el enlace no puede cambiarlo.

El widget conserva cuatro pantallas: autorización, credenciales de la empresa, verificación y confirmación. La confirmación significa que Connect aceptó la solicitud; el PDF se obtiene en segundo plano.

## Crear una solicitud [#crear-una-solicitud]

La API key necesita `sii:carpeta_tributaria:generar`. Usa una `Idempotency-Key` estable: reutilizarla con contenido distinto devuelve un conflicto. El enlace dura 24 horas y es secreto; no lo publiques ni lo registres en logs.

```ts
const { data } = await connect.collections.create({
  collection: {
    kind: 'sii_tax_folder', mode: 'once', folder_type: 'credit',
    expected_rut: '76123456-0',
    purpose: 'Evaluación comercial solicitada por el cliente',
    external_reference: 'application_42',
  },
  allowed_origins: ['https://tu-aplicacion.example'],
  redirect_uri: 'https://tu-aplicacion.example/solicitud',
}, { idempotencyKey: 'application_42_carpeta_v1' });
// Abre data.url con el enlace o el widget hosted actual.
```

Equivale a `POST /api/v1/connect_sessions` con `mode: "create"`, `connector_code: "sii"` y el bloque `collection`. No admite conexión existente ni `reauth`.

## Consultar y descargar [#consultar-y-descargar]

```ts
const { data: result } = await connect.collections.get(data.collection_request_id);
if (result.status === 'ready' && result.document?.available) {
  const { data: download } = await connect.collections.download(result.document.id);
  // download.url vence en download.expires_in segundos (300).
}
```

Endpoints: `GET /api/v1/collection_requests/:id` y `GET /api/v1/collection_documents/:id/download`. La descarga devuelve una URL firmada al PDF original privado. El resultado incluye SHA-256, tamaño, fecha de generación y retención. El archivo se elimina a los 30 días; los metadatos sensibles se purgan a los 90 días.

Estados: `awaiting_authorization`, `queued`, `processing`, `ready`, `failed`, `inconclusive`, `expired`, `canceled`. `inconclusive` significa que pudo ocurrir una emisión cuya respuesta no se pudo confirmar: Connect no repite automáticamente ese POST.

`POST /api/v1/collection_requests/:id/cancel` cancela solicitudes que no están ejecutándose. Si hay trabajo activo devuelve `connection_busy`. Cancelar no revoca una carpeta emitida por el SII.

## Webhooks [#webhooks]

Suscribe `collection_request.ready` y `collection_request.failed` mediante la configuración de webhooks existente. Usan la firma y los reintentos habituales. Deduplica por ID de evento y consulta la API para recuperar el estado si el webhook no llega.

El evento contiene los identificadores de solicitud, sesión, conexión y documento, `external_reference`, estado, `identity_verified` y `error_code`. No lleva PDF, RUT, contraseña, código/clave del repositorio SII ni URL firmada. Solo `ready` habilita la descarga.

La conexión temporal sirve exclusivamente para esta solicitud. No permite RCV, emisión de DTE, sincronizaciones programadas ni renovar credenciales. El acceso vence a los 15 minutos; cerrar y purgar las credenciales precede al resultado terminal y su evento.