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_typeseliges 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 conGET /sync-requests/{id}. - 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_DOCSpara trabajar con los folios más recientes.
Authorizations
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)
Body
ID de la entidad maestra. Acepta el id opaco (eid_..., campo opaque_id de /master-entities?rut=) o el id entero.
"eid_NDgyMTM6c2lnbmF0dXJl"
Tipos de scrape a ejecutar. Si se omite o va vacío, se sincronizan todos los tipos habilitados para la entidad.
ISSUED_DOCS, RECEIVED_DOCS, RECEIVED_HONORARY_BILLS, THIRD_PARTY_HONORARY, EMITTED_HONORARY_BILLS, PURCHASE_BOOK, SALE_BOOK, BOOK_SUMMARY URL opcional. Al completarse la solicitud hacemos un POST (best effort, timeout 5 s) con el payload {id, status, results}.
"https://miapp.cl/webhooks/tupana-sync"
Response
Solicitud creada; el scrape corre en segundo plano
Solicitud de sincronización a demanda (recurso asíncrono)
ID de la solicitud Id opaco (eid_...); la entrada acepta también el entero.
"eid_NDgyMTM6c2lnbmF0dXJl"
ID entero de la entidad sincronizada Id opaco (eid_...); la entrada acepta también el entero.
"eid_NDgyMTM6c2lnbmF0dXJl"
Tipos de scrape pedidos. Lista vacía = todos los tipos habilitados para la entidad.
ISSUED_DOCS, RECEIVED_DOCS, RECEIVED_HONORARY_BILLS, THIRD_PARTY_HONORARY, EMITTED_HONORARY_BILLS, PURCHASE_BOOK, SALE_BOOK, BOOK_SUMMARY Estado de la solicitud: pending (creada, en cola), processing (scrapes corriendo), completed (todos los tipos terminaron OK), failed (al menos un tipo falló).
pending, processing, completed, failed "pending"
URL registrada para notificar al completar. String vacío si no se registró webhook.
"https://miapp.cl/webhooks/tupana-sync"
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.
Fecha/hora en que terminó de procesarse. null mientras está pending/processing.
"2026-07-20T14:34:12Z"
Fecha/hora de creación de la solicitud
"2026-07-20T14:30:00Z"
