> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Emisión masiva

> Crea hasta 200 documentos en una sola llamada. La respuesta incluye información completa de cada documento creado, incluyendo PDF cuando está disponible. Los resultados también se enviarán por webhook si está configurado.

**Permisos requeridos:** La API Key debe tener el permiso `document:create` o permisos completos (`*`). Además, la entidad emisora debe tener credenciales SII válidas configuradas.

Emite un lote de documentos al SII con el motor batch de la plataforma.


## OpenAPI

````yaml POST /documents/batch
openapi: 3.0.0
info:
  title: API de Abacco
  version: 1.0.0
  description: API publica de Abacco (Api-Key).
servers:
  - url: https://api.abacco.ai/v1
    description: Produccion
security:
  - apiKeyAuth: []
paths:
  /documents/batch:
    post:
      summary: Envío de documentos en lote
      description: >-
        Crea hasta 200 documentos en una sola llamada. La respuesta incluye
        información completa de cada documento creado, incluyendo PDF cuando
        está disponible. Los resultados también se enviarán por webhook si está
        configurado.


        **Permisos requeridos:** La API Key debe tener el permiso
        `document:create` o permisos completos (`*`). Además, la entidad emisora
        debe tener credenciales SII válidas configuradas.
      operationId: createDocumentsBatch
      parameters:
        - name: Idempotency-Key
          in: header
          description: Previene lotes duplicados (≤ 256 caracteres, expira después de 24 h)
          required: false
          schema:
            type: string
        - name: X-Use-Defaults
          in: header
          description: >-
            Si se establece como true, el sistema usará valores por defecto para
            campos no proporcionados:

            - Fecha actual para date_issued

            - Datos del emisor según configuración de la plataforma o primera
            actividad/dirección disponible

            - Datos del receptor según configuración del cliente o primera
            actividad/dirección disponible

            - Payment method = '2' (crédito) en el header del documento
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        description: Lote de documentos a crear
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentBatch'
            example:
              documents:
                - dte_type:
                    code: '33'
                  date_issued: '2024-01-15'
                  document_issuer:
                    rut: 12345678-9
                    business_name: Mi Empresa SpA
                  document_receiver:
                    rut: 98765432-1
                    business_name: Cliente Importante Ltda
                  details:
                    - item_name: Servicio de Consultoría
                      quantity: 1
                      unit_price: 100000
        required: true
      responses:
        '202':
          description: >-
            Solicitud de creación de documentos aceptada. Los resultados se
            enviarán por webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              example:
                batch_id: 550e8400-e29b-41d4-a716-446655440000
                status: processing
                created_at: '2024-01-15T10:30:00Z'
                documents:
                  - index: 0
                    status: created
                    document:
                      id: 12345
                      folio: '1'
                      date_issued: '2024-01-15'
                      amount_with_iva: 119000
                      receiver_id: 456
                      is_draft: false
                      can_be_issued: true
                      dte_type:
                        code: '33'
                        description: Factura Electrónica
                      sender:
                        id: 123
                        name: Mi Empresa SpA
                        tax_id: 12345678-9
                      receiver:
                        id: 456
                        name: Cliente Importante Ltda
                        tax_id: 98765432-1
                      items:
                        - item_name: Servicio de Consultoría
                          item_description: null
                          quantity: 1
                          unit_price: 100000
                          unit: UN
                          item_code: null
                          item_type_code: null
                          discount_percent: null
                          other_tax: null
                      document_total:
                        net_amount: 100000
                        iva_rate: 19
                        iva_amount: 19000
                        total_amount: 119000
                      pdf_url: >-
                        https://s3.amazonaws.com/bucket/documento_12345.pdf?signature=...
                      pdf_download_url: /api/master-entities/123/documents/12345/file/
        '403':
          description: >-
            Sin permisos para crear documentos. La API Key debe tener el permiso
            'document:create' o permisos completos ('*'). Además, la entidad
            emisora debe tener credenciales SII válidas configuradas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Esta entidad no tiene credenciales SII válidas configuradas
        '413':
          description: Más de 200 documentos en el array
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Cuerpo malformado o fallo de validación
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    DocumentBatch:
      type: object
      required:
        - documents
      properties:
        documents:
          type: array
          description: Array de documentos a crear (máximo 200)
          items:
            $ref: '#/components/schemas/Document'
    BatchResponse:
      type: object
      properties:
        batch_id:
          type: string
          format: uuid
          description: Identificador único del lote
        status:
          type: string
          description: Estado del batch
          enum:
            - created
            - processing
            - completed
            - failed
          example: processing
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del batch
        documents:
          type: array
          description: Array de documentos procesados en el batch
          items:
            type: object
            properties:
              index:
                type: integer
                description: Índice del documento en el array original
              status:
                type: string
                enum:
                  - created
                  - processing
                  - success
                  - invalid
                  - temporary_error
                  - permanent_error
                  - incomplete
                description: Estado de procesamiento del documento
              document:
                type: object
                nullable: true
                description: >-
                  Información completa del documento (solo presente si status
                  permite tener documento)
                properties:
                  id:
                    type: integer
                    description: ID único del documento creado
                  folio:
                    type: string
                    nullable: true
                    description: Número de folio del documento
                  date_issued:
                    type: string
                    format: date
                    description: Fecha de emisión del documento
                  amount_with_iva:
                    type: number
                    format: float
                    description: Monto total con IVA
                  receiver_id:
                    type: integer
                    nullable: true
                    description: ID de la entidad receptora
                  is_draft:
                    type: boolean
                    description: Indica si el documento es un borrador
                  can_be_issued:
                    type: boolean
                    description: Indica si el documento puede ser emitido
                  dte_type:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Código del tipo de DTE
                      description:
                        type: string
                  sender:
                    type: object
                    nullable: true
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      tax_id:
                        type: string
                  receiver:
                    type: object
                    nullable: true
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      tax_id:
                        type: string
                  items:
                    type: array
                    description: Array de productos/servicios del documento
                    items:
                      type: object
                      properties:
                        item_name:
                          type: string
                        item_description:
                          type: string
                          nullable: true
                        quantity:
                          type: number
                          nullable: true
                        unit_price:
                          type: number
                          nullable: true
                        unit:
                          type: string
                          nullable: true
                        item_code:
                          type: string
                          nullable: true
                        item_type_code:
                          type: integer
                          nullable: true
                        discount_percent:
                          type: number
                          nullable: true
                        other_tax:
                          type: number
                          nullable: true
                  document_total:
                    type: object
                    nullable: true
                    properties:
                      net_amount:
                        type: number
                        nullable: true
                      iva_rate:
                        type: number
                        nullable: true
                      iva_amount:
                        type: number
                        nullable: true
                      total_amount:
                        type: number
                        nullable: true
                  pdf_url:
                    type: string
                    format: uri
                    nullable: true
                    description: URL presignada al PDF del documento (válida por 2 horas)
                  pdf_download_url:
                    type: string
                    nullable: true
                    description: URL de descarga del PDF
                  retention_type:
                    type: string
                    nullable: true
                    description: Tipo de retención para boletas de honorarios (DTE 80, 90)
                    enum:
                      - RETRECEPTOR
                      - RETCONTRIBUYENTE
                  export_data:
                    type: object
                    nullable: true
                    description: >-
                      Datos de exportación para facturas internacionales (DTE
                      110, 111, 112)
              errors:
                type: object
                nullable: true
                description: Errores de validación si el estado es 'invalid' o hay errores
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
          description: Código de error
          example: VALIDATION_ERROR
          enum:
            - VALIDATION_ERROR
            - AUTHENTICATION_ERROR
            - AUTHORIZATION_ERROR
            - NOT_FOUND
            - SII_ERROR
            - INTERNAL_ERROR
        message:
          type: string
          description: Mensaje de error
    Document:
      type: object
      required:
        - dte_type
        - document_issuer
        - document_receiver
        - details
      properties:
        date_issued:
          type: string
          format: date
          description: >-
            Fecha de emisión (YYYY-MM-DD). Si X-Use-Defaults es true y no se
            proporciona, se usa la fecha actual.
        folio:
          type: string
          description: >-
            Folio del documento. Si X-Use-Defaults es true y no se proporciona,
            se genera automáticamente.
        dte_type:
          $ref: '#/components/schemas/DteType'
        document_issuer:
          $ref: '#/components/schemas/DocumentIssuer'
        document_receiver:
          $ref: '#/components/schemas/DocumentReceiver'
        details:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/DetailItem'
        header:
          $ref: '#/components/schemas/DocumentHeader'
        references:
          type: array
          items:
            $ref: '#/components/schemas/ReferenceItem'
        json_param:
          type: object
          additionalProperties: true
          description: JSON arbitrario almacenado textualmente
        export_data:
          $ref: '#/components/schemas/ExportData'
        transport_data:
          $ref: '#/components/schemas/TransportData'
    DteType:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: |-
            Código del tipo de documento:
            - 33: Factura Electrónica
            - 34: Factura Exenta Electrónica
            - 39: Boleta Electrónica
            - 41: Boleta Exenta Electrónica
            - 46: Factura de Compra Electrónica
            - 52: Guía de Despacho Electrónica
            - 61: Nota de Crédito Electrónica
            - 80: Boleta de Honorarios Electrónica
            - 90: Boleta de Honorarios a Terceros Electrónica
            - 110: Factura de Exportación Electrónica
          enum:
            - '33'
            - '34'
            - '39'
            - '41'
            - '46'
            - '52'
            - '61'
            - '80'
            - '90'
            - '110'
    DocumentIssuer:
      type: object
      required:
        - rut
      properties:
        rut:
          type: string
          description: >-
            RUT sin puntos y con guion, ej: 76543210-K. Si X-Use-Defaults es
            true, los demás campos se rellenarán automáticamente según la
            configuración.
          pattern: ^[0-9]{7,8}-[0-9K]$
        business_name:
          type: string
          description: Razón social
        phone_number:
          type: string
          description: Número de teléfono
        email:
          type: string
          description: Correo electrónico
        business_activity:
          type: string
          description: Giro comercial
        activity_code:
          type: integer
          description: Código de actividad económica
        sii_branch_code:
          type: string
          description: Código de sucursal SII
        address:
          type: string
          description: Dirección
        district:
          type: string
          description: Comuna
        city:
          type: string
          description: Ciudad
    DocumentReceiver:
      type: object
      required:
        - rut
      properties:
        rut:
          type: string
          description: >-
            RUT sin puntos y con guion, ej: 76543210-K. Si X-Use-Defaults es
            true, los demás campos se rellenarán automáticamente según la
            configuración.
          pattern: ^[0-9]{7,8}-[0-9K]$
        business_name:
          type: string
          description: Razón social
        contact:
          type: string
          description: Contacto
        business_activity:
          type: string
          description: Giro comercial
        address:
          type: string
          description: Dirección
        district:
          type: string
          description: Comuna
        city:
          type: string
          description: Ciudad
    DetailItem:
      type: object
      required:
        - item_name
        - quantity
        - unit_price
      properties:
        item_name:
          type: string
          description: Nombre del ítem
        quantity:
          type: number
          description: Cantidad
        unit_price:
          type: number
          format: float
          minimum: 0
          description: Precio unitario sin IVA (no puede ser negativo)
        item_description:
          type: string
          description: Descripción del ítem
        discount_percent:
          type: number
          format: float
          description: Porcentaje de descuento
        item_code:
          type: string
          description: Código del ítem
        unit:
          type: string
          description: Unidad de medida
        other_tax:
          type: number
          format: float
          description: Otros impuestos
        item_type_code:
          type: integer
          description: Código de tipo de ítem
    DocumentHeader:
      type: object
      properties:
        purchase_transaction_type:
          type: string
          description: Tipo de transacción de compra
          nullable: true
        sale_transaction_type:
          type: string
          description: Tipo de transacción de venta
          nullable: true
        payment_method:
          type: string
          description: Método de pago
          enum:
            - '1'
            - '2'
            - '3'
          nullable: true
        due_date:
          type: string
          format: date
          description: Fecha de vencimiento
          nullable: true
        vat_withheld:
          type: boolean
          description: >-
            Indica si el IVA está retenido. Solo aplicable para facturas de
            compra (DTE 46) y notas de crédito que referencian facturas de
            compra.
          example: false
          nullable: true
        retention_type:
          type: string
          description: >-
            Tipo de retención obligatorio para boletas de honorarios (DTE 80,
            90). Define quién retiene el 14,5% legal.
          enum:
            - RETRECEPTOR
            - RETCONTRIBUYENTE
          example: RETRECEPTOR
          nullable: true
        purchase_type:
          type: string
          description: Tipo de compra para facturas recibidas en el SII
          enum:
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
          example: '1'
          nullable: true
    ReferenceItem:
      type: object
      required:
        - reference_folio
        - reference_date
        - dte_type_code
      properties:
        reference_folio:
          type: integer
          description: Folio de referencia
        reference_date:
          type: string
          format: date
          description: Fecha de referencia
        reference_reason:
          type: string
          description: >-
            Razón de referencia. Para notas de crédito totales debe ser 'ANULA
            DOCUMENTO DE LA REFERENCIA'.
          example: ANULA DOCUMENTO DE LA REFERENCIA
        dte_type_code:
          type: string
          description: Código del tipo de DTE del documento referenciado
    ExportData:
      type: object
      description: >-
        Datos específicos para facturas de exportación (DTE 110) y notas de
        crédito de exportación (DTE 112). Solo requerido cuando se selecciona
        uno de estos tipos de documento.
      properties:
        tax_id_receptor:
          type: string
          description: Identificación tributaria del receptor en el país de destino
        destination_country_code:
          type: string
          description: >-
            Código de país del SII del destino (tabla de Aduana). No es código
            ISO 3166-1. Ver /user-guide/export-countries
          example: '225'
        currency_code:
          type: string
          description: >-
            Código de moneda del SII (tabla de Aduana). No es código ISO 4217.
            Ver /user-guide/export-currencies
          example: '13'
        exchange_rate:
          type: string
          description: Tipo de cambio aplicado
          example: '800.50'
        departure_port_code:
          type: string
          description: Código del puerto de embarque
        arrival_port_code:
          type: string
          description: Código del puerto de desembarque
        departure_port_name:
          type: string
          description: Nombre del puerto de embarque
        arrival_port_name:
          type: string
          description: Nombre del puerto de desembarque
        total_packages:
          type: string
          description: Número total de bultos
        sale_mode_code:
          type: string
          description: Código de modalidad de venta
        export_type:
          type: string
          description: Tipo de exportación
          default: '0'
    TransportData:
      type: object
      description: >-
        Transport details for electronic dispatch guides (DTE 52) and related
        flows. When `timber_enabled` is true, include CONAF timber origin fields
        as required by SII for wood products.
      required:
        - transport_type
      properties:
        transport_type:
          type: string
          description: Transfer type code per SII (1–9).
          enum:
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
          example: '1'
        transport_rut:
          type: string
          nullable: true
          description: Tax ID (RUT) of the transport company, format 12345678-9.
          example: 76123456-7
        transport_plate:
          type: string
          nullable: true
          description: Vehicle license plate.
          example: ABCD12
        driver_rut:
          type: string
          nullable: true
          description: Driver tax ID (RUT).
          example: 12345678-9
        driver_name:
          type: string
          nullable: true
          description: Driver full name.
          example: Juan Pérez
        timber_enabled:
          type: boolean
          description: When true, the dispatch includes timber origin data for CONAF.
          default: false
          example: false
        comuna_rol:
          type: string
          nullable: true
          description: SII commune code for the origin property roll (rol de origen).
          example: '13101'
        manzana_rol:
          type: string
          nullable: true
          description: Block (manzana) of the origin property roll.
          example: '12'
        predio_rol:
          type: string
          nullable: true
          description: Lot (predio) of the origin property roll.
          example: '345'
        geo_ref_system:
          type: string
          nullable: true
          description: Geographic reference system code (e.g. 1 = WGS84).
          example: '1'
        latitude:
          type: string
          nullable: true
          description: >-
            Timber origin latitude as string (typically two decimal places per
            SII).
          example: '-33.45'
        longitude:
          type: string
          nullable: true
          description: >-
            Timber origin longitude as string (typically two decimal places per
            SII).
          example: '-70.65'
        conaf_plan_code:
          type: string
          nullable: true
          description: CONAF forest management plan code.
          example: PM-2024-001
  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)

````