> ## Documentation Index > Fetch the complete documentation index at: https://docs.tupana.ai/llms.txt > Use this file to discover all available pages before exploring further. # Crear solicitud de sincronización > Crea una solicitud de sincronización a demanda para una entidad. Es un **recurso asíncrono**: la API crea el objeto, responde 201 de inmediato con `status: "pending"` y el scrape corre en segundo plano — la llamada nunca bloquea esperando al SII. Luego puedes hacer polling con `GET /sync-requests/{id}` o registrar un `webhook_url` para que te avisemos al terminar. Disponible **solo para entidades en el plan de 24 horas**. Si la entidad ya está en un plan de 12 h o 3 h, responde 400: su cartera ya se sincroniza sola con mayor frecuencia y no necesita solicitudes a demanda. ## ¿Para qué se usa? Permite **pedir una sincronización a demanda** de una entidad, sin esperar el próximo ciclo automático de 24 horas. Casos típicos: un cliente recién conectado del que quieres los datos altiro, o necesitas la cartera al día antes de operar cobranza o cesiones. ## Qué hace * Es un **recurso asíncrono** (estilo Stripe/Plaid): crea el objeto, responde **201 de inmediato** con `status: "pending"` y el scrape corre en segundo plano. La llamada nunca bloquea esperando al SII. * Con `scrape_types` eliges qué tipos sincronizar; si lo omites, se sincronizan **todos los tipos habilitados** para la entidad. * Si mandas `webhook_url`, al completar hacemos un **POST a esa URL** con `{id, status, results}` (best effort, timeout 5 s). Si no, haz polling con [`GET /sync-requests/{id}`](/api-reference/sync/request-get). * Disponible **solo para el plan de 24 horas**: si la entidad ya está en un plan de 12 h o 3 h responde 400 — su cartera ya se sincroniza sola con mayor frecuencia. ## Ejemplos de uso * Onboarding: el cliente conectó su empresa hace 5 minutos y quieres mostrarle sus facturas sin esperar al ciclo nocturno. * Cobranza/cesiones: antes de calcular la cartera cedible, fuerza `ISSUED_DOCS` para trabajar con los folios más recientes. ## OpenAPI ````yaml POST /sync-requests openapi: 3.0.0 info: title: Tupana API description: API para integración con el sistema Tupana - Facturación Electrónica version: 1.0.0 servers: - url: https://api.tupana.ai/v1 description: Servidor de producción security: - apiKeyAuth: [] paths: /sync-requests: post: tags: - Sincronización summary: Crear solicitud de sincronización a demanda description: >- Crea una solicitud de sincronización a demanda para una entidad. Es un **recurso asíncrono**: la API crea el objeto, responde 201 de inmediato con `status: "pending"` y el scrape corre en segundo plano — la llamada nunca bloquea esperando al SII. Luego puedes hacer polling con `GET /sync-requests/{id}` o registrar un `webhook_url` para que te avisemos al terminar. Disponible **solo para entidades en el plan de 24 horas**. Si la entidad ya está en un plan de 12 h o 3 h, responde 400: su cartera ya se sincroniza sola con mayor frecuencia y no necesita solicitudes a demanda. operationId: createSyncRequest requestBody: required: true content: application/json: schema: type: object required: - master_entity_id properties: master_entity_id: type: string description: >- ID de la entidad maestra. Acepta el id opaco (`eid_...`, campo `opaque_id` de `/master-entities?rut=`) o el id entero. example: eid_NDgyMTM6c2lnbmF0dXJl scrape_types: type: array description: >- Tipos de scrape a ejecutar. Si se omite o va vacío, se sincronizan todos los tipos habilitados para la entidad. items: type: string enum: - ISSUED_DOCS - RECEIVED_DOCS - RECEIVED_HONORARY_BILLS - THIRD_PARTY_HONORARY - EMITTED_HONORARY_BILLS - PURCHASE_BOOK - SALE_BOOK - BOOK_SUMMARY example: - ISSUED_DOCS - RECEIVED_DOCS webhook_url: type: string format: uri description: >- URL opcional. Al completarse la solicitud hacemos un POST (best effort, timeout 5 s) con el payload `{id, status, results}`. example: https://miapp.cl/webhooks/tupana-sync responses: '201': description: Solicitud creada; el scrape corre en segundo plano content: application/json: schema: $ref: '#/components/schemas/SyncRequest' example: id: 1042 master_entity_id: 48213 requested_types: - ISSUED_DOCS - RECEIVED_DOCS status: pending webhook_url: https://miapp.cl/webhooks/tupana-sync results: {} completed_at: null created_at: '2026-07-20T14:30:00Z' '400': description: >- Body inválido (master_entity_id faltante, scrape_type desconocido) o la entidad está en un plan de 12 h / 3 h (la sincronización a demanda es solo para el plan de 24 horas) content: application/json: schema: type: object properties: error: type: string example: >- La actualización a demanda está disponible solo para el plan de 24 horas; tu plan ya sincroniza cada 12 horas. '403': description: Sin acceso a la entidad indicada content: application/json: schema: type: object properties: detail: type: string example: No tienes acceso a esta entidad. security: - apiKeyAuth: [] components: schemas: SyncRequest: type: object description: Solicitud de sincronización a demanda (recurso asíncrono) properties: id: type: string description: >- ID de la solicitud Id opaco (eid_...); la entrada acepta también el entero. example: eid_NDgyMTM6c2lnbmF0dXJl master_entity_id: type: string description: >- ID entero de la entidad sincronizada Id opaco (eid_...); la entrada acepta también el entero. example: eid_NDgyMTM6c2lnbmF0dXJl requested_types: type: array description: >- Tipos de scrape pedidos. Lista vacía = todos los tipos habilitados para la entidad. items: type: string enum: - ISSUED_DOCS - RECEIVED_DOCS - RECEIVED_HONORARY_BILLS - THIRD_PARTY_HONORARY - EMITTED_HONORARY_BILLS - PURCHASE_BOOK - SALE_BOOK - BOOK_SUMMARY example: - ISSUED_DOCS - RECEIVED_DOCS status: type: string enum: - pending - processing - completed - failed description: >- Estado de la solicitud: pending (creada, en cola), processing (scrapes corriendo), completed (todos los tipos terminaron OK), failed (al menos un tipo falló). example: pending webhook_url: type: string description: >- URL registrada para notificar al completar. String vacío si no se registró webhook. example: https://miapp.cl/webhooks/tupana-sync results: type: object description: >- Resultado por tipo de scrape al terminar. Las claves son los scrape_type ejecutados y cada valor es un objeto con `success` (boolean) más contadores como `new_documents`, o `error` si falló. Objeto vacío mientras la solicitud está pending/processing. additionalProperties: type: object example: ISSUED_DOCS: success: true new_documents: 3 RECEIVED_DOCS: success: true new_documents: 0 completed_at: type: string format: date-time nullable: true description: >- Fecha/hora en que terminó de procesarse. null mientras está pending/processing. example: '2026-07-20T14:34:12Z' created_at: type: string format: date-time description: Fecha/hora de creación de la solicitud example: '2026-07-20T14:30:00Z' securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: >- API Key para autenticación. Debe proporcionarse en el header Authorization con el formato: 'Api-Key YOUR-API-KEY' (incluye el prefijo 'Api-Key ' seguido de tu API key) ````