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

# Resumen de libro de compras/ventas

> Obtiene el resumen de libro de compras y ventas (getResumen del SII) para una entidad y período. Es data agregada por tipo de documento y operación (COMPRA/VENTA), no el detalle línea a línea. Solo devuelve datos para entidades habilitadas explícitamente para este scrape (ver `is_enabled` en la respuesta); si la entidad no está habilitada, `results` viene vacío.

## ¿Para qué se usa?

Permite **obtener el resumen agregado del libro de compras y ventas** (getResumen del SII) de una entidad para un período determinado. Cada ítem representa un total por tipo de documento (factura, nota de crédito, etc.) y operación (COMPRA o VENTA), no el detalle línea a línea de cada documento.

## Qué hace

* Devuelve los totales del libro (`total_docs`, `net_amount`, `exempt_amount`, `vat_amount`, `total_amount`) agrupados por `dte_type_code` y `operation` para el `period` (YYYYMM) indicado.
* 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.
* Puedes filtrar por **operación** (`COMPRA` o `VENTA`); si se omite, devuelve ambas.
* El campo **is\_enabled** indica si la entidad tiene habilitado el scrape de este resumen. Si es `false`, `results` viene vacío aunque el período sea válido — la entidad necesita ser habilitada primero (ver [Introducción](/api-reference/book-summaries/introduction)).

## Ejemplos de uso

* Conciliar el IVA débito/crédito declarado por el SII contra tu propia contabilidad.
* Mostrar en un dashboard los totales mensuales de compras y ventas de una entidad sin tener que descargar el detalle documento por documento.


## OpenAPI

````yaml GET /book-summaries
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:
  /book-summaries:
    get:
      tags:
        - Resumen de Libros
      summary: Listar resumen de libro de compras/ventas SII
      description: >-
        Obtiene el resumen de libro de compras y ventas (getResumen del SII)
        para una entidad y período. Es data agregada por tipo de documento y
        operación (COMPRA/VENTA), no el detalle línea a línea. Solo devuelve
        datos para entidades habilitadas explícitamente para este scrape (ver
        `is_enabled` en la respuesta); si la entidad no está habilitada,
        `results` viene vacío.
      operationId: listBookSummaries
      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
        - name: period
          in: query
          required: true
          description: Período a consultar, formato YYYYMM.
          schema:
            type: string
            example: '202603'
        - name: operation
          in: query
          required: false
          description: 'Filtra por operación: COMPRA o VENTA. Si se omite, devuelve ambas.'
          schema:
            type: string
            enum:
              - COMPRA
              - VENTA
      responses:
        '200':
          description: Resumen de libro para la entidad y período consultado
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total de filas en results
                  is_enabled:
                    type: boolean
                    description: >-
                      true si la entidad tiene habilitado el scrape de resumen
                      de libros (BOOK_SUMMARY). Si es false, results estará
                      vacío aunque el período sea válido.
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BookSummaryItem'
        '400':
          description: >-
            master_entity_id faltante o inválido, o period faltante o con
            formato inválido
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: period is required in YYYYMM format.
        '403':
          description: >-
            Sin acceso a la entidad, o la API key no tiene el permiso
            book_summary:access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Access denied.
      security:
        - apiKeyAuth: []
components:
  schemas:
    BookSummaryItem:
      type: object
      properties:
        id:
          type: integer
          description: ID de la fila de resumen
        period:
          type: string
          description: Período YYYYMM
          example: '202603'
        operation:
          type: string
          enum:
            - COMPRA
            - VENTA
        dte_type_code:
          type: integer
          nullable: true
          description: Código de tipo de documento SII (33, 34, 46, 61, etc.)
        dte_type_name:
          type: string
          description: Nombre del tipo de documento
        total_docs:
          type: integer
          description: Cantidad de documentos en esta línea del resumen
        net_amount:
          type: integer
          description: Monto neto
        exempt_amount:
          type: integer
          description: Monto exento
        vat_amount:
          type: integer
          description: Monto IVA
        total_amount:
          type: integer
          description: Monto total
        scraped_at:
          type: string
          format: date-time
          description: Fecha/hora en que se obtuvo este resumen desde el SII
  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)

````