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

# Create invoice batch

> Creates a batch and accepts up to 1000 invoices.
Requires bearer auth and Idempotency-Key header (UUID).
Successful requests are rate-limited for 60 seconds per organization.




## OpenAPI

````yaml /openapi.json post /api/v1/invoice_batches
openapi: 3.1.0
info:
  title: YoFacturo API v1
  version: 1.0.0
  summary: API for authentication and invoice batch ingestion and status
  description: |
    API v1 operational endpoints.

    Authentication flow:
    1. Exchange organization api_key for a session token.
    2. Use Authorization: Bearer <session_token> for protected endpoints.
servers:
  - url: https://app.yofacturo.es
security: []
tags:
  - name: Auth
  - name: Invoice Batches
  - name: Batch Invoices
paths:
  /api/v1/invoice_batches:
    post:
      tags:
        - Invoice Batches
      summary: Create invoice batch
      description: |
        Creates a batch and accepts up to 1000 invoices.
        Requires bearer auth and Idempotency-Key header (UUID).
        Successful requests are rate-limited for 60 seconds per organization.
      operationId: createInvoiceBatch
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceBatchRequest'
      responses:
        '201':
          description: >-
            Batch created. Response may include per-invoice validation errors
            for partial success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInvoiceBatchResponse'
              examples:
                created:
                  value:
                    data:
                      id: 123
                      external_batch_id: batch-f4ac4fcf-2db2-4dc5-9f6b-9a0f9f38ec10
                      status: received
                      invoices_count: 1
                      received_at: '2026-03-26T10:30:00Z'
                      processed_at: null
                partialSuccess:
                  value:
                    data:
                      id: 124
                      external_batch_id: batch-5c7c8f66-c7f9-4ff7-8d0e-7dcfab88cbee
                      status: received
                      invoices_count: 1
                      received_at: '2026-03-26T10:31:00Z'
                      processed_at: null
                    errors:
                      inv-bad:
                        - Issued on cannot be blank
                        - Invoice number cannot be blank
        '401':
          description: Missing, invalid, or expired bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation or idempotency header errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingIdempotency:
                  value:
                    error:
                      code: missing_idempotency_key
                      message: Idempotency-Key header is required
                invalidIdempotency:
                  value:
                    error:
                      code: invalid_idempotency_key
                      message: Idempotency-Key must be a valid UUID
                tooManyInvoices:
                  value:
                    error:
                      code: validation_failed
                      message: Batch cannot contain more than 1000 invoices
        '429':
          description: >-
            Rate limit exceeded for repeated successful batch creation requests
            within 60 seconds
          headers:
            Retry-After:
              description: Seconds until the next batch creation request is allowed
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: UUID key used to make POST invoice_batches idempotent.
      schema:
        type: string
        format: uuid
  schemas:
    CreateInvoiceBatchRequest:
      type: object
      additionalProperties: false
      required:
        - invoice_batch
      properties:
        invoice_batch:
          type: object
          additionalProperties: false
          required:
            - invoices
          properties:
            external_batch_id:
              type: string
              nullable: true
            invoices:
              type: array
              minItems: 1
              maxItems: 1000
              items:
                $ref: '#/components/schemas/InvoiceInput'
    CreateInvoiceBatchResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/InvoiceBatch'
        errors:
          type: object
          description: Map external_invoice_id to validation errors.
          additionalProperties:
            type: array
            items:
              type: string
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    InvoiceInput:
      type: object
      additionalProperties: false
      properties:
        external_invoice_id:
          type: string
          nullable: true
        issuer_nif:
          type: string
          nullable: true
        number_serie:
          type: string
          nullable: true
        issuer_name:
          type: string
          nullable: true
        invoice_type:
          description: >-
            "F1" for Factura normal. Factura (art. 6, 7.2 y 7.3 del RD
            1619/2012).
          type: string
          nullable: true
        operation_description:
          type: string
          nullable: true
        operation_date:
          type: string
          format: date
          nullable: true
        due_date:
          type: string
          format: date
          nullable: true
        rectified_invoice_id:
          type: integer
          nullable: true
        has_unidentified_recipient:
          type: boolean
          nullable: true
        recipient_legal_name:
          type: string
          nullable: true
        recipient_document_type:
          type: string
          nullable: true
          description: >
            Type of identification document for the recipient.

            - `nif`: Spanish tax identification number for residents.

            - `nie`: Foreigner identification number in Spain.

            - `passport`: Passport number.

            - `international_vat_number`: VAT number for EU or international
            entities.
        recipient_document_number:
          type: string
          nullable: true
        recipient_billing_address:
          type: string
          nullable: true
        recipient_billing_postal_code:
          type: string
          nullable: true
        recipient_billing_city:
          type: string
          nullable: true
        contact_id:
          type: integer
          nullable: true
          description: Id of the contact (unsupported right now).
        invoiceable_serie_id:
          type: integer
          nullable: true
        payment_method:
          type: string
          nullable: true
          description: |
            Method of payment.
            - `cash_on_delivery`: Cash on delivery. 
            - `cash`: Cash payment.
            - `credit_card`: Payment by credit card.
            - `bank_transfer`: Bank transfer.
            - `bizum`: Payment by Bizum.
            - `bank_remittance`: Payment via bank remittance.
            - `others`: Other payment methods.
        payment_method_info:
          type: string
          nullable: true
        operation_type:
          type: string
          nullable: true
          description: >
            Type of operation (usually `domestic_operations_deductible_vat`).

            - `domestic_operations_deductible_vat`: "Domestic operations in
            Spain with deductible VAT (art. 78 and 79 of RD 1619/2012)."

            - `agricultural_compensation`: "Agricultural, livestock, and fishing
            compensation regime (art. 31 of RD 1619/2012)."

            - `intra_community_acquisition_goods`: "Intra-community acquisition
            of goods (art. 14 of RD 1619/2012)."

            - `intra_community_acquisition_services`: "Intra-community
            acquisition of services (art. 14 of RD 1619/2012)."

            - `reverse_charge_tax`: "Reverse charge tax (art. 84 of RD
            1619/2012)."

            - `imports`: "Imports (art. 21 of RD 1619/2012)."

            - `non_deductible_vat`: "Non-deductible VAT (art. 80 of RD
            1619/2012)."
        recipient_country_code:
          type: string
          nullable: true
        footer_note:
          type: string
          nullable: true
        total_reimbursable_expenses_amount:
          type: number
          nullable: true
          description: >-
            Total amount of reimbursable expenses (suplidos) included in the
            invoice.
        paid:
          type: boolean
          nullable: true
        lines:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineInput'
    InvoiceBatch:
      type: object
      additionalProperties: false
      required:
        - id
        - external_batch_id
        - status
        - invoices_count
        - received_at
      properties:
        id:
          type: integer
        external_batch_id:
          type: string
          nullable: true
        status:
          type: string
        invoices_count:
          type: integer
        received_at:
          type: string
          format: date-time
        processed_at:
          type: string
          format: date-time
          nullable: true
    InvoiceLineInput:
      type: object
      additionalProperties: false
      properties:
        position:
          type: integer
          nullable: true
          description: >-
            Line position in the invoice. Lines will be ordered by this field in
            ascending order.
        concept:
          type: string
          nullable: true
        units:
          type: number
          nullable: true
        unit_price:
          type: number
          nullable: true
        discount_percent:
          type: number
          nullable: true
        notes:
          type: string
          nullable: true
        tax_type:
          type: string
          nullable: true
          description: |
            Type of tax applied to the line.
            - `iva`: Value Added Tax (VAT) in Spain.
            - `psi`: Ceuta and Melilla Special Indirect Tax.
            - `igic`: Canary Islands General Indirect Tax.
            - `others`: Other types of taxes.
        tax_regime:
          type: string
          nullable: true
          description: >
            Tax regime applied to the line (only for `iva` tax type).

            - `01`: Operación de régimen general.

            - `02`: Exportación.

            - `03`: Operaciones a las que se aplique el régimen especial de
            bienes usados, objetos de arte, antigüedades y objetos de colección.

            - `04`: Régimen especial del oro de inversión.

            - `05`: Régimen especial de las agencias de viajes.

            - `06`: Régimen especial grupo de entidades en IVA (Nivel Avanzado)

            - `07`: Régimen especial del criterio de caja.

            - `08`: Operaciones sujetas al IPSI/IGIC (Impuesto sobre la
            Producción, los Servicios y la Importación/Impuesto General
            Indirecto Canario).

            - `09`: Facturación de las prestaciones de servicios de agencias de
            viaje que actúan como mediadoras en nombre y por cuenta ajena
            (D.A.4.a RD1619/2012)

            - `10`: Cobros por cuenta de terceros de honorarios profesionales o
            de derechos derivados de la propiedad industrial, de autor u otros
            por cuenta de sus socios, asociados o colegiados efectuados por
            sociedades, asociaciones, colegios profesionales u otras entidades
            que realicen estas funciones de cobro.

            - `11`: Operaciones de arrendamiento de local de negocio.

            - `14`: Factura con IVA pendiente de devengo en certificaciones de
            obra cuyo destinatario sea una Administración Pública.

            - `15`: Factura con IVA pendiente de devengo en operaciones de
            tracto sucesivo.

            - `17`: Operación acogida a alguno de los regímenes previstos en el
            capítulo XI del título IX (OSS e IOSS)

            - `18`: Recargo de equivalencia.

            - `19`: Operaciones de actividades incluidas en el Régimen Especial
            de Agricultura, Ganadería y Pesca (REAGYP)

            - `20`: Régimen simplificado
        tax_operation_key:
          type: string
          nullable: true
          description: >
            Key of the tax operation applied to the line (only for `iva` tax
            type and `01` tax regime).

            - `S1`: Operación Sujeta y No exenta - Sin inversión del sujeto
            pasivo.

            - `S2`: Operación Sujeta y No exenta - Con Inversión del sujeto
            pasivo.

            - `N1`: Operación No Sujeta artículo 7, 14, otros.

            - `N2`: Operación No Sujeta por Reglas de localización.
        tax_exemption_code:
          type: string
          nullable: true
          description: >
            Code of the tax exemption applied to the line (only for `iva` tax
            type).

            - `E1`: E1 Exenta por el artículo 20.

            - `E2`: Exenta por el artículo 21. Artículo 21 Exenciones en las
            exportaciones de bienes.

            - `E3`: Exenta por el artículo 22. Artículo 22 Exenciones en las
            operaciones asimiladas a las exportaciones.

            - `E4`: Exenta por los artículos 23 y 24.

            - `E5`: Exenta por el artículo 25.

            - `E6`: Exenta por otros.
        tax_rate:
          type: number
          nullable: true
        income_tax_withholding_rate:
          type: number
          nullable: true
          description: >-
            Withholding tax rate applied to the line (only for professional
            services subject to income tax withholding).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token

````