Facturear Lotes API

openapi: 3.2.0
info:
  title: Facturear Lotes API
  description: 'API para emitir facturas electrónicas de ARCA (Argentina) desde tu sistema: facturas, notas de crédito y débito, lotes, PDF y XML, envío por email, borradores desde documentos, webhooks y reportes. Autenticación con API Key en el header x-api-key: la key de testing opera en homologación y la de producción emite comprobantes reales.'
  version: 1.0.0
  contact:
    name: Facturear Support
    email: support@facture.ar
    url: https://facture.ar
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://www.facture.ar/api
  description: Servidor de producción
security:
- apiKey: []
tags:
- name: Lotes
  description: 'El resultado de cada emisión: toda factura se procesa en un lote'
paths:
  /invoices/batches:
    get:
      summary: Listar lotes de facturas
      description: Obtiene la lista de lotes de facturas con paginación.
      tags:
      - Lotes
      parameters:
      - name: page
        in: query
        description: Número de página
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Elementos por página
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      responses:
        '200':
          description: Lista de lotes obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  batches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Batch'
                  pagination:
                    $ref: '#/components/schemas/Meta'
      operationId: getInvoicesBatches
      x-operation-id-source: derived
  /invoices/batches/{batchId}:
    get:
      summary: Obtener lote por ID
      description: Obtiene los detalles completos de un lote específico, incluyendo todos sus items.
      tags:
      - Lotes
      parameters:
      - name: batchId
        in: path
        description: ID del lote
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Lote obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchDetail'
        '404':
          description: Lote no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getInvoicesBatchesByBatchId
      x-operation-id-source: derived
    patch:
      summary: Agregar facturas a lote
      description: Agrega facturas adicionales a un lote existente que aún no ha sido completado. Con `Idempotency-Key`, reenviar el mismo agregado no suma las facturas dos veces, aunque el lote ya haya terminado.
      tags:
      - Lotes
      parameters:
      - name: batchId
        in: path
        description: ID del lote
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 500
              items:
                $ref: '#/components/schemas/InvoiceRequest'
              description: Facturas a agregar al lote
      responses:
        '200':
          description: Facturas agregadas al lote exitosamente
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch:
                    type: boolean
                  message:
                    type: string
                  count:
                    type: integer
                    description: Cantidad de facturas agregadas
                  status:
                    type: string
                    enum:
                    - processing
                  batchId:
                    type: string
                  addedToExistingBatch:
                    type: boolean
        '400':
          description: Datos inválidos o lote ya completado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          $ref: '#/components/responses/IdempotencyInProgress'
        '422':
          $ref: '#/components/responses/IdempotencyKeyReused'
      operationId: patchInvoicesBatchesByBatchId
      x-operation-id-source: derived
  /invoices/batches/{batchId}/items/{itemId}/retry:
    post:
      summary: Reintentar item de lote
      description: Reintenta el procesamiento de un item específico que falló en un lote. Solo items en estado error, hasta 5 reintentos manuales por item.
      tags:
      - Lotes
      parameters:
      - name: batchId
        in: path
        description: ID del lote
        required: true
        schema:
          type: string
      - name: itemId
        in: path
        description: ID del item del lote
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Item reintentado exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    description: Mensaje de confirmación
                  itemId:
                    type: string
                    description: ID del item
                  newStatus:
                    type: string
                    enum:
                    - pending
                    description: Nuevo estado del item
                  manualRetryCount:
                    type: integer
                    description: Reintentos manuales hechos (máximo 5)
        '400':
          description: El item no está en estado error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Lote o item no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: El item cambió de estado mientras se reintentaba (por ejemplo, otro reintento simultáneo ya lo volvió a encolar)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: El item ya tuvo 5 reintentos manuales. Contactá soporte
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postInvoicesBatchesByBatchIdItemsByItemIdRetry
      x-operation-id-source: derived
components:
  schemas:
    BatchItem:
      type: object
      required:
      - id
      - status
      - order
      - createdAt
      - updatedAt
      - requestBody
      properties:
        id:
          type: string
          description: ID del item
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - error
          description: Estado del item
        order:
          type: integer
          description: Posición del item en su cola
        createdAt:
          type: string
          format: date-time
          description: Fecha de creación
        updatedAt:
          type: string
          format: date-time
          description: Fecha de última actualización
        requestBody:
          type: object
          description: 'Factura encolada: los campos de InvoiceRequest ya completados con los valores por defecto del CUIT'
        responseBody:
          type:
          - object
          - 'null'
          description: Resultado del procesamiento (la factura emitida o el detalle del error)
    InvoiceRequest:
      type: object
      description: 'Una factura. Todos los campos son opcionales salvo el importe: enviá impTotal (o amount, deprecado). Si no enviás cuitId ni cuit se usa el CUIT por defecto de la cuenta; lo que no envíes se completa con los valores por defecto del CUIT.'
      properties:
        cuitId:
          type: string
          description: ID del CUIT emisor. Alternativa a cuit
        cuit:
          type: string
          example: 20-12345678-9
          description: Número de CUIT emisor, con o sin guiones. Alternativa a cuitId
        invoiceType:
          type: integer
          description: Tipo de comprobante (código de ARCA, por ejemplo 1 Factura A, 6 Factura B, 11 Factura C). Por defecto, el del CUIT; si no tiene, 11 para monotributistas y 6 para responsables inscriptos
          example: 11
        ptoVta:
          type: integer
          description: Punto de venta. Por defecto, el del CUIT (o 1)
          example: 1
        concepto:
          type: integer
          enum:
          - 1
          - 2
          - 3
          description: 'Concepto: 1 productos, 2 servicios, 3 productos y servicios. Por defecto, el del CUIT (o 2 para monotributistas y 1 para el resto)'
        docTipo:
          type: integer
          default: 99
          description: 'Tipo de documento del receptor (código de ARCA: 80 CUIT, 86 CUIL, 96 DNI, 99 consumidor final)'
        docNro:
          type: integer
          minimum: 0
          default: 0
          description: Número de documento del receptor (0 para consumidor final)
        condicionIVAReceptorId:
          type: integer
          enum:
          - 1
          - 4
          - 5
          - 6
          - 7
          - 8
          - 9
          - 10
          - 13
          - 15
          - 16
          description: 'Condición frente al IVA del receptor (obligatoria para ARCA desde el 1/12/2026). Si no se envía: 5 (Consumidor Final) para receptores sin identificar o con DNI; para CUIT/CUIL se toma del padrón de ARCA, y si no se puede determinar la API responde 400. Debe corresponder a la clase del comprobante (A/M: 1, 6, 13, 16; B: 4, 5, 7, 8, 9, 10, 15; C: todas). Ver /es/guides/condicion-iva-receptor.'
        monId:
          type: string
          default: PES
          description: Moneda (código de ARCA, por ejemplo PES o DOL)
        monCotiz:
          type: number
          exclusiveMinimum: 0
          default: 1
          description: Cotización de la moneda
        description:
          type: string
          default: Venta de servicios
          description: Descripción de la factura
        clientName:
          type: string
          maxLength: 200
          description: Nombre o razón social del receptor, impreso en la factura. Si el receptor tiene CUIT y no se envía, se toma del padrón de ARCA
        clientAddress:
          type: string
          maxLength: 250
          description: Domicilio del receptor, impreso en la factura
        condicionVenta:
          type: string
          enum:
          - contado
          - cuenta_corriente
          - tarjeta_debito
          - tarjeta_credito
          - transferencia
          - cheque
          - otra
          description: Condición de venta impresa en la factura (RG 1415, Anexo II, B). ARCA no la recibe
        emailTo:
          type: array
          items:
            type: string
            format: email
          minItems: 1
          maxItems: 5
          description: Direcciones a las que se manda el PDF de la factura apenas ARCA la autoriza. Mismos límites que POST /invoices/{invoiceId}/email
        fchServDesde:
          type: string
          description: Inicio del período facturado (servicios). Fecha en formato YYYYMMDD
        fchServHasta:
          type: string
          description: Fin del período facturado (servicios). Fecha en formato YYYYMMDD
        fchVtoPago:
          type: string
          description: Vencimiento del pago (servicios). Fecha en formato YYYYMMDD
        cbteFch:
          type: string
          pattern: ^[0-9]{8}$
          description: Fecha del comprobante. Fecha en formato YYYYMMDD. Por defecto, hoy
          example: '20260928'
        impNeto:
          type: number
          exclusiveMinimum: 0
          maximum: 10000000
          description: Importe neto gravado
        impTotal:
          type: number
          exclusiveMinimum: 0
          maximum: 10000000
          description: Importe total. Requerido si no enviás amount
          example: 1210
        impTotConc:
          type: number
          minimum: 0
          default: 0
          description: Importe neto no gravado
        impOpEx:
          type: number
          minimum: 0
          default: 0
          description: Importe exento
        impTrib:
          type: number
          minimum: 0
          default: 0
          description: Suma de los tributos
        impIVA:
          type: number
          minimum: 0
          default: 0
          description: Suma del IVA
        amount:
          type: number
          exclusiveMinimum: 0
          maximum: 10000000
          deprecated: true
          description: 'Importe total. Deprecado: usá impTotal'
        cbtesAsoc:
          type: array
          description: Comprobantes asociados (notas de crédito y débito)
          items:
            type: object
            required:
            - tipo
            - ptoVta
            - nro
            properties:
              tipo:
                type: integer
                description: Tipo de comprobante asociado
              ptoVta:
                type: integer
                description: Punto de venta del comprobante asociado
              nro:
                type: integer
                description: Número del comprobante asociado
              cuit:
                type: string
                description: CUIT emisor del comprobante asociado
              cbteFch:
                type: string
                description: Fecha del comprobante asociado. Fecha en formato YYYYMMDD
        tributos:
          type: array
          description: Tributos (percepciones, impuestos internos, etc.)
          items:
            type: object
            required:
            - id
            - desc
            - baseImp
            - alic
            - importe
            properties:
              id:
                type: integer
                description: Código del tributo (FEPARAMGETTIPOSTRIBUTOS)
              desc:
                type: string
                description: Descripción del tributo
              baseImp:
                type: number
                minimum: 0
                description: Base imponible
              alic:
                type: number
                minimum: 0
                maximum: 100
                description: Alícuota en porcentaje
              importe:
                type: number
                minimum: 0
                description: Importe del tributo
        iva:
          type: array
          description: Alícuotas de IVA
          items:
            type: object
            required:
            - id
            - baseImp
            - importe
            properties:
              id:
                type: integer
                description: Código de la alícuota (FEPARAMGETTIPOSIVA, por ejemplo 5 = 21%)
              baseImp:
                type: number
                minimum: 0
                description: Base imponible
              importe:
                type: number
                minimum: 0
                description: Importe de IVA
        opcionales:
          type: array
          description: Datos opcionales de ARCA
          items:
            type: object
            required:
            - id
            - valor
            properties:
              id:
                type: string
                description: Código del opcional
              valor:
                type: string
                description: Valor
        compradores:
          type: array
          description: Compradores (operaciones con varios compradores)
          items:
            type: object
            required:
            - docTipo
            - docNro
            - porcentaje
            properties:
              docTipo:
                type: integer
                description: Tipo de documento del comprador
              docNro:
                type: integer
                description: Número de documento del comprador
              porcentaje:
                type: number
                description: Porcentaje de titularidad
        periodoAsoc:
          type: object
          description: Período asociado (notas de crédito y débito)
          required:
          - fchDesde
          - fchHasta
          properties:
            fchDesde:
              type: string
              description: Desde. Fecha en formato YYYYMMDD
            fchHasta:
              type: string
              description: Hasta. Fecha en formato YYYYMMDD
        actividades:
          type: array
          description: Actividades del emisor
          items:
            type: object
            required:
            - id
            properties:
              id:
                type: integer
                description: Código de actividad
        items:
          type: array
          maxItems: 500
          description: Ítems de la factura (se muestran en el PDF)
          items:
            type: object
            required:
            - description
            - quantity
            - unitPrice
            - discount
            - ivaRate
            - subtotal
            properties:
              description:
                type: string
                description: Descripción del ítem
              quantity:
                type: number
                exclusiveMinimum: 0
                description: Cantidad
              unitPrice:
                type: number
                exclusiveMinimum: 0
                description: Precio unitario
              discount:
                type: number
                minimum: 0
                maximum: 100
                description: Descuento en porcentaje
              ivaRate:
                type: number
                minimum: 0
                maximum: 100
                description: Alícuota de IVA en porcentaje
              subtotal:
                type: number
                exclusiveMinimum: 0
                description: Subtotal del ítem
    Meta:
      type: object
      required:
      - page
      - limit
      - totalCount
      - totalPages
      - hasNextPage
      - hasPrevPage
      properties:
        page:
          type: integer
          example: 1
          description: Página actual
        limit:
          type: integer
          example: 10
          description: Elementos por página
        totalCount:
          type: integer
          example: 42
          description: Total de elementos
        totalPages:
          type: integer
          example: 5
          description: Total de páginas
        hasNextPage:
          type: boolean
          description: Hay una página siguiente
        hasPrevPage:
          type: boolean
          description: Hay una página anterior
    Batch:
      type: object
      required:
      - id
      - userId
      - environment
      - status
      - totalItems
      - processedItems
      - successfulItems
      - failedItems
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          description: ID del lote
        userId:
          type: string
          description: ID del usuario
        environment:
          type: string
          enum:
          - production
          - homologation
          description: Entorno
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - completed_with_errors
          - error
          description: Estado del lote
        totalItems:
          type: integer
          description: Total de items en el lote
        processedItems:
          type: integer
          description: Items procesados (con éxito o con error)
        successfulItems:
          type: integer
          description: Items procesados con éxito
        failedItems:
          type: integer
          description: Items que fallaron
        createdAt:
          type: string
          format: date-time
          description: Fecha de creación
        updatedAt:
          type: string
          format: date-time
          description: Fecha de última actualización
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/BatchItem'
          description: Items del lote
    Error:
      type: object
      description: Error de la API. Los errores de autenticación (401), validación (400), CUIT inexistente (404), conflicto (409) e internos (500) vienen como application/problem+json (RFC 9457) con code, message y resolution. Otros errores vienen como JSON con error y, a veces, details y code. En los dos casos está el campo error.
      required:
      - error
      properties:
        error:
          type: string
          description: Mensaje de error
        code:
          type: string
          description: 'Código estable: unauthorized, invalid_request, cuit_not_found, conflict, internal_error, o códigos propios como SUBSCRIPTION_LIMIT_EXCEEDED'
        message:
          type: string
          description: Qué pasó (problem+json)
        resolution:
          type: string
          description: Qué hacer para resolverlo (problem+json)
        type:
          type: string
          format: uri
          description: URI del tipo de problema (problem+json)
        title:
          type: string
          description: Título corto del problema (problem+json)
        status:
          type: integer
          description: Código HTTP (problem+json)
        detail:
          type: string
          description: Igual que message (problem+json)
        details:
          description: 'Detalle del error: un texto, o la lista de errores de validación'
    BatchDetail:
      type: object
      required:
      - id
      - status
      - totalItems
      - processedItems
      - successfulItems
      - failedItems
      - environment
      - createdAt
      - updatedAt
      - items
      properties:
        id:
          type: string
          description: ID del lote
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - completed_with_errors
          - error
          description: Estado del lote
        totalItems:
          type: integer
          description: Total de items en el lote
        processedItems:
          type: integer
          description: Items procesados (con éxito o con error)
        successfulItems:
          type: integer
          description: Items procesados con éxito
        failedItems:
          type: integer
          description: Items que fallaron
        environment:
          type: string
          enum:
          - production
          - homologation
          description: Entorno
        createdAt:
          type: string
          format: date-time
          description: Fecha de creación
        updatedAt:
          type: string
          format: date-time
          description: Fecha de última actualización
        items:
          type: array
          description: Items del lote
          items:
            allOf:
            - $ref: '#/components/schemas/BatchItem'
            - type: object
              properties:
                cuit:
                  type:
                  - object
                  - 'null'
                  description: CUIT emisor del item
                  properties:
                    id:
                      type: string
                    number:
                      type: string
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Clave que elegís vos (recomendado: un UUID nuevo por cada factura o lote). Si reenviás la misma solicitud con la misma clave —por un timeout, un error de red o un 5xx— recibís la respuesta original (mismo `batchId`, header `Idempotent-Replayed: true`) en vez de una factura nueva. Para una factura distinta, o después de que ARCA rechazó la anterior en forma definitiva, usá una clave nueva. Entre 1 y 255 caracteres ASCII imprimibles; se guarda 7 días. En un lote, el ítem `i` queda identificado como `<clave>:<i>`.'
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: 6f1c2b0e-8a43-4c5e-9d2a-3b7f1e0c9a11
  responses:
    IdempotencyInProgress:
      description: Ya hay una solicitud en curso con este `Idempotency-Key` (code `IDEMPOTENCY_KEY_IN_PROGRESS`). Esperá unos segundos y reintentá con la misma clave para recibir su resultado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyKeyReused:
      description: 'Este `Idempotency-Key` ya se usó con otra solicitud: otro cuerpo u otro endpoint (code `IDEMPOTENCY_KEY_REUSED`). Usá una clave nueva para una factura distinta.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    IdempotentReplayed:
      description: '`true` cuando la respuesta es la guardada de una solicitud anterior con el mismo `Idempotency-Key`: no se encoló nada nuevo.'
      schema:
        type: string
        enum:
        - 'true'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key para autenticación. Formato: test_sk_xxx para testing, prod_sk_xxx para producción.'