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

# Detalle de solicitud de sincronización

> Devuelve el estado actual de una solicitud de sincronización. Úsalo para hacer polling después del `POST /sync-requests`: cuando `status` pase a `completed` (o `failed`), el campo `results` trae el resultado por cada tipo de scrape ejecutado.

## ¿Para qué se usa?

Permite **consultar el estado de una solicitud de sincronización** creada con `POST /sync-requests`. Es el endpoint de polling del flujo asíncrono.

## Qué hace

* Devuelve el objeto completo de la solicitud: `status` (`pending`, `processing`, `completed` o `failed`), `requested_types`, `completed_at` y `results`.
* Cuando la solicitud termina, `results` trae el **resultado por tipo de scrape**: cada clave es un `scrape_type` ejecutado y su valor incluye `success` más contadores como `new_documents`, o `error` si ese tipo falló.
* Solo puedes consultar solicitudes de entidades a las que tienes acceso (si no, responde 403).

## Ejemplos de uso

* Polling después del POST: consultar cada algunos segundos hasta que `status` sea `completed` o `failed`, y recién ahí leer `/documents`.
* Diagnóstico: si `status` es `failed`, revisar en `results` qué tipo falló y con qué error.


## OpenAPI

````yaml GET /sync-requests/{id}
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/{id}:
    get:
      tags:
        - Sincronización
      summary: Detalle de una solicitud de sincronización
      description: >-
        Devuelve el estado actual de una solicitud de sincronización. Úsalo para
        hacer polling después del `POST /sync-requests`: cuando `status` pase a
        `completed` (o `failed`), el campo `results` trae el resultado por cada
        tipo de scrape ejecutado.
      operationId: getSyncRequest
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            ID de la solicitud de sincronización (campo `id` de la respuesta del
            POST).
          schema:
            type: integer
            example: 1042
      responses:
        '200':
          description: Detalle de la solicitud, con resultados por tipo si ya terminó
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncRequest'
              example:
                id: 1042
                master_entity_id: 48213
                requested_types:
                  - ISSUED_DOCS
                  - RECEIVED_DOCS
                status: completed
                webhook_url: https://miapp.cl/webhooks/tupana-sync
                results:
                  ISSUED_DOCS:
                    success: true
                    new_documents: 3
                  RECEIVED_DOCS:
                    success: true
                    new_documents: 0
                completed_at: '2026-07-20T14:34:12Z'
                created_at: '2026-07-20T14:30:00Z'
        '403':
          description: Sin acceso a la entidad dueña de la solicitud
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: No tienes acceso a esta entidad.
        '404':
          description: La solicitud no existe
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: No encontrado.
      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)

````