Skip to main content
POST
Crear solicitud de sincronización 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}.
  • 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.

Authorizations

Authorization
string
header
required

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

application/json
master_entity_id
string
required

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
enum<string>[]

Tipos de scrape a ejecutar. Si se omite o va vacío, se sincronizan todos los tipos habilitados para la entidad.

Available options:
ISSUED_DOCS,
RECEIVED_DOCS,
RECEIVED_HONORARY_BILLS,
THIRD_PARTY_HONORARY,
EMITTED_HONORARY_BILLS,
PURCHASE_BOOK,
SALE_BOOK,
BOOK_SUMMARY
Example:
webhook_url
string<uri>

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"

Response

Solicitud creada; el scrape corre en segundo plano

Solicitud de sincronización a demanda (recurso asíncrono)

id
string

ID de la solicitud Id opaco (eid_...); la entrada acepta también el entero.

Example:

"eid_NDgyMTM6c2lnbmF0dXJl"

master_entity_id
string

ID entero de la entidad sincronizada Id opaco (eid_...); la entrada acepta también el entero.

Example:

"eid_NDgyMTM6c2lnbmF0dXJl"

requested_types
enum<string>[]

Tipos de scrape pedidos. Lista vacía = todos los tipos habilitados para la entidad.

Available options:
ISSUED_DOCS,
RECEIVED_DOCS,
RECEIVED_HONORARY_BILLS,
THIRD_PARTY_HONORARY,
EMITTED_HONORARY_BILLS,
PURCHASE_BOOK,
SALE_BOOK,
BOOK_SUMMARY
Example:
status
enum<string>

Estado de la solicitud: pending (creada, en cola), processing (scrapes corriendo), completed (todos los tipos terminaron OK), failed (al menos un tipo falló).

Available options:
pending,
processing,
completed,
failed
Example:

"pending"

webhook_url
string

URL registrada para notificar al completar. String vacío si no se registró webhook.

Example:

"https://miapp.cl/webhooks/tupana-sync"

results
object

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.

Example:
completed_at
string<date-time> | null

Fecha/hora en que terminó de procesarse. null mientras está pending/processing.

Example:

"2026-07-20T14:34:12Z"

created_at
string<date-time>

Fecha/hora de creación de la solicitud

Example:

"2026-07-20T14:30:00Z"