Carpeta tributaria puntual

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

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.

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

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

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.