Emitir facturas por lote

POST/api/v1/facturas/lotes

Emite de 1 a 30 facturas en el orden recibido mediante POST /api/v1/facturas/lotes. Requiere X-API-Key con permiso facturas.crear.

Header requerido X-API-KeyVer operaciones de Emisión por lote y masiva

Contrato de la operación

Emite de 1 a 30 facturas en el orden recibido mediante POST /api/v1/facturas/lotes. Requiere X-API-Key con permiso facturas.crear.

Cada factura usa el mismo contrato de POST /api/v1/facturas. El correlativo se reserva atómicamente por punto de venta; no se asignan números duplicados aunque existan solicitudes concurrentes. El proceso continúa si un elemento es rechazado: revisa resultados antes de repetir una solicitud, porque no se usa una clave de idempotencia.

Ante una falla temporal de SIAT, el sistema crea o reutiliza una contingencia automática para el punto de venta. La factura se guarda con estado pendiente_envio, XML firmado y CUF de emisión offline. Un worker consulta cada minuto estos eventos automáticos: cuando SIAT responde, registra y finaliza el evento, y la cola PostgreSQL envía los XML agrupados en paquetes. Los rechazos fiscales del SIAT no ingresan a contingencia. Responde 200 con los resultados individuales, 400 si el lote no tiene entre uno y treinta elementos, 401, 403 y 429 si se supera el límite por minuto. Configura actividadEconomica y codigoProductoSin con códigos habilitados para tu empresa.

Ejemplo

Solicitud de ejemplo

Clave ficticia; no se ejecuta desde esta página

cURL · POST

export FALMUS_API_URL='https://staging-api.falmus.com/api/v1'
export FALMUS_API_KEY='flm_test_REEMPLAZA_CON_TU_CLAVE'

curl --request POST \
  --url "$FALMUS_API_URL/facturas/lotes" \
  --header "X-API-Key: $FALMUS_API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "facturas": [
    {
      "codigoDocumentoSector": 1,
      "puntoVentaId": "{{puntoVentaId}}",
      "cliente": {
        "codigoTipoDocumento": 5,
        "numeroDocumento": "99001",
        "razonSocial": "CLIENTE DE DEMOSTRACIÓN",
        "codigoCliente": "CLIENTE-99001"
      },
      "pago": {
        "codigoMetodoPago": 1
      },
      "datosSector": {
        "codigoMoneda": 1,
        "tipoCambio": 1
      },
      "detalles": [
        {
          "actividadEconomica": "{{actividadEconomica}}",
          "codigoProductoSin": 1003914,
          "descripcion": "Servicio de desarrollo - lote 1",
          "cantidad": 1,
          "codigoUnidadMedida": 58,
          "precioUnitario": 100,
          "datosSector": {}
        }
      ]
    },
    {
      "codigoDocumentoSector": 1,
      "puntoVentaId": "{{puntoVentaId}}",
      "cliente": {
        "codigoTipoDocumento": 5,
        "numeroDocumento": "99002",
        "razonSocial": "CLIENTE DE DEMOSTRACIÓN",
        "codig...'

Respuesta

Ejemplo de respuesta

200 OKapplication/json

JSON

{
  "message": "emisión por lote finalizada",
  "data": {
    "totalSolicitadas": 2,
    "totalEmitidas": 1,
    "totalContingencia": 1,
    "totalFallidas": 0,
    "resultados": [
      {
        "factura": {
          "id": "00000000-0000-4000-8000-000000000001",
          "numeroFactura": 42,
          "cuf": "A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0",
          "codigoRecepcion": "00000000-0000-4000-8000-000000000042",
          "codigoEstado": 908,
          "estado": "aceptado",
          "ambiente": "pruebas",
          "fechaEmision": "2026-08-30T16:10:00-04:00",
          "montoTotal": 500,
          "codigoPuntoVenta": 0,
          "codigoDocumentoSector": 1,
          "urlQr": "https://pilotosiat.impuestos.gob.bo/consulta/QR?nit=123456789&cuf=A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0&numero=42&t=2",
          "urlXml": "https://api.example.test/api/v1/public/facturas/A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0/xml",
          "urlPdf": "https://api.example.test/api/v1/public/facturas/A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0/pdf"
        }
      },
      {
        "factura": {
          "id": "00000000-0000-4000-8000-000000000001",
          "numeroFactura": 43,
          "cuf": "A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0",
          "codigoRecepcion": "00000000-0000-4000-8000-000000000042",
          "codigoEstado": 908,
          "estado": "pendiente_envio",
          "ambiente": "pruebas",
          "fechaEmision": "2026-08-30T16:10:00-04:00",
          "montoTotal": 500,
          "codigoPuntoVenta": 0,
          "codigoDocumentoSector": 1,
          "urlQr": "https://pilotosiat.impuestos.gob.bo/consulta/QR?nit=123456789&cuf=A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0&numero=42&t=2",
          "urlXml": "https://api.example.test/api/v1/public/facturas/A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0/xml",
          "urlPdf": "https://api.example.test/api/v1/public/facturas/A1B2C3D4E5F60718293A4B5C6D7E8F90123456789ABCDEF0123456789ABCDEF0/pdf"
        }
      }
    ]
  }
}

Datos ficticios; los identificadores y valores cambian en cada respuesta.

Volver a Emisión por lote y masiva