> ## 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.

# Estado de sincronización

> Devuelve la frecuencia de sincronización contratada para la entidad (`sync_frequency_hours`: 24, 12 o 3) y la última actualización por tipo de scrape. Cada fila de `types` indica cuándo fue la última carga exitosa (`last_success_at`) y el estado de la última ejecución (`last_status`). Solo aparecen los tipos que se han sincronizado al menos una vez para la entidad.

## ¿Para qué se usa?

Permite saber **cuándo fue la última sincronización de cada tipo de dato** de una entidad, y qué frecuencia de sincronización tiene contratada (`sync_frequency_hours`: 24, 12 o 3).

## Qué hace

* Devuelve una fila por tipo de scrape en `types`, con `scrape_type`, `last_success_at` (última carga exitosa) y `last_status` (`in_progress`, `completed` o `failed`).
* Solo aparecen los tipos que se han sincronizado al menos una vez para la entidad.
* La entidad se indica con el query param `master_entity_id`, igual que en `/documents`. Acepta el **id opaco** (`eid_...`, campo `opaque_id` de `/master-entities?rut=`) o el id entero.

## Ejemplos de uso

* Mostrar en tu producto "datos actualizados hace X horas" para cada empresa conectada.
* Antes de operar cobranza o cesiones, verificar que `last_success_at` de `ISSUED_DOCS` sea reciente; si no, crear una [solicitud de sincronización a demanda](/api-reference/sync/request-create).
* Detectar tipos con `last_status: "failed"` y alertar (por ejemplo, credenciales SII vencidas).


## OpenAPI

````yaml GET /sync-status
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-status:
    get:
      tags:
        - Sincronización
      summary: Estado de sincronización de una entidad
      description: >-
        Devuelve la frecuencia de sincronización contratada para la entidad
        (`sync_frequency_hours`: 24, 12 o 3) y la última actualización por tipo
        de scrape. Cada fila de `types` indica cuándo fue la última carga
        exitosa (`last_success_at`) y el estado de la última ejecución
        (`last_status`). Solo aparecen los tipos que se han sincronizado al
        menos una vez para la entidad.
      operationId: getSyncStatus
      parameters:
        - name: master_entity_id
          in: query
          required: true
          description: >-
            ID de la entidad maestra. Acepta el id opaco (`eid_...`, campo
            `opaque_id` de `/master-entities?rut=`) o el id entero.
          schema:
            type: string
            example: eid_NDgyMTM6c2lnbmF0dXJl
      responses:
        '200':
          description: Estado de sincronización de la entidad
          content:
            application/json:
              schema:
                type: object
                properties:
                  master_entity_id:
                    type: integer
                    description: ID entero de la entidad
                    example: 48213
                  sync_frequency_hours:
                    type: integer
                    enum:
                      - 24
                      - 12
                      - 3
                    description: >-
                      Frecuencia de sincronización contratada, en horas. 24 es
                      el plan por defecto; 12 y 3 (casi tiempo real) son planes
                      de mayor frecuencia.
                    example: 24
                  types:
                    type: array
                    description: Última actualización por tipo de scrape
                    items:
                      $ref: '#/components/schemas/SyncStatusType'
              example:
                master_entity_id: 48213
                sync_frequency_hours: 24
                types:
                  - scrape_type: ISSUED_DOCS
                    last_success_at: '2026-07-20T06:12:41Z'
                    last_status: completed
                  - scrape_type: RECEIVED_DOCS
                    last_success_at: '2026-07-20T06:15:03Z'
                    last_status: completed
                  - scrape_type: PURCHASE_BOOK
                    last_success_at: '2026-07-19T06:14:10Z'
                    last_status: failed
        '400':
          description: master_entity_id faltante o inválido
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: master_entity_id es requerido.
        '403':
          description: Sin acceso a la entidad consultada
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: No tienes acceso a esta entidad.
        '404':
          description: La entidad no existe
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: No encontrado.
      security:
        - apiKeyAuth: []
components:
  schemas:
    SyncStatusType:
      type: object
      description: Última actualización de un tipo de scrape para la entidad
      properties:
        scrape_type:
          type: string
          enum:
            - ISSUED_DOCS
            - RECEIVED_DOCS
            - RECEIVED_HONORARY_BILLS
            - THIRD_PARTY_HONORARY
            - EMITTED_HONORARY_BILLS
            - PURCHASE_BOOK
            - SALE_BOOK
            - BOOK_SUMMARY
          description: >-
            Tipo de scrape: ISSUED_DOCS (facturas emitidas), RECEIVED_DOCS
            (facturas recibidas), RECEIVED_HONORARY_BILLS (boletas de honorarios
            recibidas), THIRD_PARTY_HONORARY (boletas de honorarios de
            terceros), EMITTED_HONORARY_BILLS (boletas de honorarios emitidas),
            PURCHASE_BOOK (libro de compras), SALE_BOOK (libro de ventas),
            BOOK_SUMMARY (resumen de libro de compras/ventas).
          example: ISSUED_DOCS
        last_success_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Fecha/hora de la última sincronización exitosa de este tipo. null si
            nunca ha cargado con éxito.
          example: '2026-07-20T06:12:41Z'
        last_status:
          type: string
          enum:
            - in_progress
            - completed
            - failed
          description: Estado de la última ejecución de este tipo de scrape
          example: completed
  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)

````