Facturación masiva en lotes

La facturación en lotes te permite emitir múltiples facturas electrónicas en una sola operación asincrónica. Es ideal para e-commerce, facturación mensual recurrente, sistemas ERP y cualquier caso donde necesitás procesar muchas facturas juntas.

Lotes desde el dashboard (CSV)

Si cargás comprobantes con archivo CSV desde la web (sin armar integración propia), el flujo, las columnas y el archivo de ejemplo están detallados en Facturación por lotes desde la app. Incluye la columna opcional cbte_fch, correlatividad de fechas dentro del lote y contra ARCA.

Fecha del comprobante (`cbteFch`) en la API

En cada ítem que envíes al batch (mismo cuerpo que una factura suelta en /api/invoices), podés incluir el campo opcional cbteFch en formato YYYYMMDD. Si no lo enviás, Facturear usa la fecha actual al ejecutar el trabajo contra ARCA. Reglas que aplican igual que en ARCA:

Por CUIT + punto de venta + tipo de comprobante, la fecha del nuevo comprobante no puede ser menor que la del último comprobante autorizado en ese circuito.
Orden dentro del lote: para el mismo circuito, las fechas efectivas deben ser no decrecientes en el orden en que se procesan los ítems.

Para facturación retroactiva (por ejemplo cerrar un mes anterior), solo es coherente si no emitiste después con fechas más nuevas en ese mismo punto de venta y tipo.

¿Cuándo usar lotes?

Caso de uso	Sin lotes	Con lotes
Emitir 500 facturas fin de mes	500 requests individuales	1 batch con 500 items
E-commerce con picos de ventas	Posibles timeouts	Procesamiento asincrónico
Facturación recurrente SaaS	Script secuencial lento	Procesamiento paralelo
Migración de facturas históricas	Inviable	Ideal

Los lotes procesan las facturas de forma asincrónica. Enviás el lote, Facturear lo procesa con ARCA y podés consultar el estado cuando quieras. No necesitás esperar a que termine para continuar con otras operaciones.

Flujo de trabajo con lotes

Crear un lote

POST /invoices/batches

const response = await fetch('https://api.facture.ar/invoices/batches', {
  method: 'POST',
  headers: {
    'x-api-key': 'tu_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cuitId: 'id-de-tu-cuit',
    descripcion: 'Facturación mensual Mayo 2025'
  })
})

const batch = await response.json()
console.log('Batch ID:', batch.id)  // "batch_xyz789"

Respuesta:

{
  "id": "batch_xyz789",
  "estado": "creado",
  "cuitId": "id-de-tu-cuit",
  "descripcion": "Facturación mensual Mayo 2025",
  "createdAt": "2025-05-01T10:00:00Z",
  "totalItems": 0,
  "procesados": 0,
  "exitosos": 0,
  "fallidos": 0
}

Agregar facturas al lote

PATCH /invoices/batches/{batchId}

Podés agregar facturas de a una o en grupos:

const items = [
  {
    receptor: {
      razonSocial: 'Cliente Uno S.A.',
      cuit: '30-11111111-1',
      condicionIva: 'RI'
    },
    tipo: 1,  // Factura A
    puntoVenta: 1,
    cbteFch: '20260505', // opcional, YYYYMMDD; si omitís, fecha del día al procesar
    items: [
      {
        descripcion: 'Suscripción Pro - Mayo 2025',
        cantidad: 1,
        precioUnitario: 25000,
        alicuotaIva: 21
      }
    ]
  },
  {
    receptor: {
      razonSocial: 'Consumidor Final',
      condicionIva: 'CF'
    },
    tipo: 6,  // Factura B
    puntoVenta: 1,
    items: [
      {
        descripcion: 'Suscripción Basic - Mayo 2025',
        cantidad: 1,
        precioUnitario: 8000,
        alicuotaIva: 21
      }
    ]
  }
  // ... más facturas
]

await fetch(`https://api.facture.ar/invoices/batches/${batchId}`, {
  method: 'PATCH',
  headers: {
    'x-api-key': 'tu_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ items })
})

Podés agregar ítems en múltiples llamadas al mismo batch. Esto es útil si tenés que armar el lote de forma incremental o si querés agregar facturas desde diferentes partes de tu sistema.

Consultar el estado del lote

GET /invoices/batches/{batchId}

const batch = await fetch(`https://api.facture.ar/invoices/batches/${batchId}`, {
  headers: { 'x-api-key': 'tu_api_key' }
}).then(r => r.json())

console.log(`Total: ${batch.totalItems}`)
console.log(`Procesados: ${batch.procesados}`)
console.log(`Exitosos: ${batch.exitosos}`)
console.log(`Fallidos: ${batch.fallidos}`)

Respuesta:

{
  "id": "batch_xyz789",
  "estado": "procesando",
  "totalItems": 150,
  "procesados": 87,
  "exitosos": 85,
  "fallidos": 2,
  "items": [
    {
      "id": "item_001",
      "estado": "exitoso",
      "invoiceId": "inv_abc123",
      "cae": "71234567890123"
    },
    {
      "id": "item_002",
      "estado": "fallido",
      "error": {
        "codigo": "10013",
        "descripcion": "CUIT receptor no válido"
      }
    }
    // ...
  ]
}

Manejar errores y reintentos

Los ítems fallidos se pueden reintentar individualmente después de corregir el problema:

POST /invoices/batches/{batchId}/items/{itemId}/retry

// Corregí el CUIT incorrecto y reintentá
await fetch(
  `https://api.facture.ar/invoices/batches/${batchId}/items/${itemId}/retry`,
  {
    method: 'POST',
    headers: {
      'x-api-key': 'tu_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      // Datos corregidos del ítem
      receptor: {
        cuit: '30-22222222-2',  // CUIT corregido
        razonSocial: 'Cliente Corregido S.A.',
        condicionIva: 'RI'
      }
    })
  }
)

Listar todos los lotes

GET /invoices/batches

const batches = await fetch('https://api.facture.ar/invoices/batches?page=1&limit=20', {
  headers: { 'x-api-key': 'tu_api_key' }
}).then(r => r.json())

Parámetros de filtrado disponibles:

estado: creado, procesando, completado, con_errores
desde / hasta: filtro por fecha de creación
page / limit: paginación

Ejemplo completo: facturación mensual de un SaaS

Este script procesa todos los clientes activos de un SaaS y emite una factura mensual para cada uno:

async function facturacionMensual(clientes, mes) {
  const apiKey = process.env.FACTUREAR_API_KEY
  const cuitId = process.env.FACTUREAR_CUIT_ID
  const BASE_URL = 'https://api.facture.ar'
  
  // 1. Crear el lote
  const { id: batchId } = await fetch(`${BASE_URL}/invoices/batches`, {
    method: 'POST',
    headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ cuitId, descripcion: `Facturación ${mes}` })
  }).then(r => r.json())

  console.log(`Lote creado: ${batchId}`)

  // 2. Agregar facturas en chunks de 50
  const CHUNK_SIZE = 50
  for (let i = 0; i < clientes.length; i += CHUNK_SIZE) {
    const chunk = clientes.slice(i, i + CHUNK_SIZE)
    
    const items = chunk.map(cliente => ({
      receptor: {
        razonSocial: cliente.razonSocial,
        cuit: cliente.cuit,
        condicionIva: cliente.condicionIva
      },
      tipo: cliente.condicionIva === 'RI' ? 1 : 6,  // A o B
      puntoVenta: 1,
      items: [{
        descripcion: `Suscripción ${cliente.plan} - ${mes}`,
        cantidad: 1,
        precioUnitario: cliente.montoPlan,
        alicuotaIva: 21
      }]
    }))

    await fetch(`${BASE_URL}/invoices/batches/${batchId}`, {
      method: 'PATCH',
      headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ items })
    })

    console.log(`Procesado chunk ${i / CHUNK_SIZE + 1}`)
  }

  // 3. Polling hasta que el lote termine
  let completado = false
  while (!completado) {
    await new Promise(r => setTimeout(r, 5000))  // Esperar 5 segundos
    
    const batch = await fetch(`${BASE_URL}/invoices/batches/${batchId}`, {
      headers: { 'x-api-key': apiKey }
    }).then(r => r.json())

    console.log(`Progreso: ${batch.procesados}/${batch.totalItems}`)
    completado = batch.estado === 'completado' || batch.estado === 'con_errores'
    
    if (completado) {
      console.log(`Exitosos: ${batch.exitosos}, Fallidos: ${batch.fallidos}`)
      return batch
    }
  }
}

Límites y consideraciones

Parámetro	Límite
Ítems por lote	Sin límite (recomendado: máx. 10.000)
Ítems por PATCH	500 por llamada
Lotes concurrentes	Depende del plan
Tiempo de retención del lote	30 días

Aunque los lotes son asincrónicos, ARCA puede tener límites de tasa. Si procesás volúmenes muy altos, implementá backoff exponencial en los reintentos de errores de ARCA.

Preguntas frecuentes

¿Puedo cancelar un lote en proceso?

No se puede cancelar un lote que ya está siendo procesado. Los ítems que ya obtuvieron CAE están emitidos y son válidos. Si necesitás anularlos, debés emitir Notas de Crédito.

¿Los errores de ARCA en un ítem afectan al resto del lote?

No. Cada ítem del lote se procesa de forma independiente. Si un ítem falla por un error de ARCA (CUIT inválido, etc.), el resto sigue procesándose normalmente.

¿Cómo sé cuándo terminó el lote?

Podés hacer polling al endpoint GET /invoices/batches/ o configurar un webhook para que Facturear te notifique cuando el lote cambia de estado. Ver la documentación de webhooks.

¿Puedo agregar ítems a un lote que ya está procesando?

Sí, mientras el lote esté en estado “procesando” o “creado” podés seguir agregando ítems. Los nuevos ítems se encolan y se procesan.

¿Puedo enviar la fecha del comprobante (cbteFch / cbte_fch)?

Sí: en API usá cbteFch (YYYYMMDD) por ítem; en CSV del dashboard usá la columna cbte_fch (YYYYMMDD o YYYY-MM-DD). Si no lo definís, se usa la fecha actual al procesar. ARCA no permite fechas anteriores al último comprobante de ese punto de venta y tipo; dentro del lote, las fechas no pueden ir hacia atrás para el mismo circuito.

Recursos relacionados

Seguí estos pasos directamente en Facturear

Ir al dashboard de Facturear y gestionar tu facturación en lotes.

Inicio

Comenzar

Configuración

Fundamentos

Funcionalidades

Facturación masiva en lotes

Facturación masiva en lotes

Lotes desde el dashboard (CSV)

Fecha del comprobante (`cbteFch`) en la API

¿Cuándo usar lotes?

Flujo de trabajo con lotes

Crear un lote

Agregar facturas al lote

Consultar el estado del lote

Manejar errores y reintentos

Listar todos los lotes

Ejemplo completo: facturación mensual de un SaaS

Límites y consideraciones

Preguntas frecuentes

Recursos relacionados

Seguí estos pasos directamente en Facturear

​Facturación masiva en lotes

​Lotes desde el dashboard (CSV)

​Fecha del comprobante (cbteFch) en la API

​¿Cuándo usar lotes?

​Flujo de trabajo con lotes

​Crear un lote

​Agregar facturas al lote

​Consultar el estado del lote

​Manejar errores y reintentos

​Listar todos los lotes

​Ejemplo completo: facturación mensual de un SaaS

​Límites y consideraciones

​Preguntas frecuentes

​Recursos relacionados

Seguí estos pasos directamente en Facturear

Facturación masiva en lotes

Lotes desde el dashboard (CSV)

Fecha del comprobante (`cbteFch`) en la API

¿Cuándo usar lotes?

Flujo de trabajo con lotes

Crear un lote

Agregar facturas al lote

Consultar el estado del lote

Manejar errores y reintentos

Listar todos los lotes

Ejemplo completo: facturación mensual de un SaaS

Límites y consideraciones

Preguntas frecuentes

Recursos relacionados