Emision Masiva

La emision masiva es la tercera modalidad de emision del SIAT. Abris un lote sobre un punto de venta, emitis normalmente, y al cerrar el lote todas las facturas viajan juntas al SIAT comprimidas en uno o mas paquetes. Sirve cuando emitis mucho volumen y no necesitas la confirmacion del SIAT factura por factura: en vez de una llamada por documento, se hace una por paquete.

No confundir con /invoices/batch. Ese endpoint manda hasta 20 facturas en un request, pero cada una se envia al SIAT por separado y en linea. La emision masiva es otra modalidad ante el SIAT, con su propio codigo de emision y su propio ciclo.

Las tres modalidades

Modalidad	Codigo	Cuando	Evento significativo
En linea	`1`	Emision normal, una por una	No
Fuera de linea	`2`	Contingencia — el SIAT no responde	Si, y admite CAFC
Masiva	`3`	Volumen alto, con SIAT disponible	No

La masiva se emite en linea: necesita el SIAT operativo. Si el punto de venta entra en contingencia, las facturas nuevas salen como contingencia aunque haya un lote abierto; las que ya entraron al lote quedan intactas y se envian cuando lo cierres. Para contingencia, ver Contingencia.

Ciclo de un lote

Abrir el lote

POST /api/v1/massive sobre el punto de venta.

Emitir normalmente

Las facturas se crean con POST /api/v1/invoices como siempre. Mientras el lote este abierto quedan en estado MASSIVE_PENDING — con su CUF definitivo, listas para imprimir y entregar — pero todavia no viajaron al SIAT.

Cerrar el lote

POST /api/v1/massive/end. Se arman los paquetes, se envian y se validan. Cada factura queda ACCEPTED o REJECTED con su motivo.

Rectificar, si hubo rechazos

POST /api/v1/massive/rectify regenera las rechazadas y las devuelve a la cola. Despues volves a cerrar.

Abrir un lote

POST /api/v1/massive

Parametro	Ubicacion	Tipo	Req	Descripcion
`X-API-Key`	Header	string	Si	Tu API Key
`posId`	Body	string	Si	UUID del punto de venta
`sector`	Body	integer	No	Sector documental del lote. Por defecto, el del punto de venta
`invoiceType`	Body	integer	No	Tipo de documento SIAT. Por defecto `1` (factura)

Es idempotente: si el punto de venta ya tiene un lote abierto, la llamada devuelve ese lote en vez de crear otro. Un punto de venta no puede tener dos lotes abiertos a la vez.

curl -X POST https://sandbox.cucu.bo/api/v1/massive \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "posId": "660e8400-e29b-41d4-a716-446655440004"
  }'

const response = await fetch('https://sandbox.cucu.bo/api/v1/massive', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    posId: '660e8400-e29b-41d4-a716-446655440004'
  })
});

Respuesta 201

{
  "success": true,
  "message": "Lote masivo abierto: las facturas que emitas ahora entran al lote hasta que lo cierres",
  "data": {
    "batchId": "8f14e45f-ceea-467a-9575-4c4d0a8f4c23",
    "batchCode": "K3M9PQZ7XR2WNB4TV",
    "posId": "660e8400-e29b-41d4-a716-446655440004",
    "sector": 1,
    "invoiceType": 1,
    "status": "OPEN",
    "closedAt": null
  }
}

Si el sector no esta soportado o la empresa no lo tiene autorizado ante el SIN, la respuesta es 422 con SECTOR_NOT_SUPPORTED o SECTOR_NOT_AUTHORIZED. La validacion se hace al abrir a proposito: descubrirlo al cerrar significaria tener el lote entero ya emitido.

Cerrar el lote

POST /api/v1/massive/end

Parametro	Ubicacion	Tipo	Req	Descripcion
`X-API-Key`	Header	string	Si	Tu API Key
`posId`	Body	string	Si	UUID del punto de venta

En lotes grandes esta llamada puede tardar varios minutos: envia y valida cada paquete contra el SIAT. Configura el timeout de tu cliente HTTP en consecuencia.

Es reentrante. Si un cierre se corta a mitad, volver a llamarlo retoma donde quedo: los paquetes ya validados no se reenvian.

Respuesta 200

{
  "success": true,
  "message": "Lote cerrado: 1250 factura(s) aceptadas por SIAT en 3 paquete(s)",
  "data": {
    "batchId": "8f14e45f-ceea-467a-9575-4c4d0a8f4c23",
    "batchCode": "K3M9PQZ7XR2WNB4TV",
    "facturasEnLote": 1250,
    "packsEnviados": 3,
    "packsValidados": 3,
    "packsRechazados": 0,
    "facturasAceptadas": 1250,
    "facturasRechazadas": 0
  }
}

El message distingue tres desenlaces que no hay que confundir:

Sin facturas — el lote se cerro vacio, no habia nada que enviar.
Todo aceptado — facturasRechazadas y packsRechazados en 0.
Con rechazos — parte del lote quedo REJECTED; hay que rectificar.

Ver el lote

GET /api/v1/massive/{posId} Devuelve el lote abierto del punto de venta con el detalle de cada paquete: cuantas facturas lleva, el receptionCode que devolvio el SIAT y su estado.

Respuesta 200

{
  "success": true,
  "data": {
    "batchId": "8f14e45f-ceea-467a-9575-4c4d0a8f4c23",
    "batchCode": "K3M9PQZ7XR2WNB4TV",
    "status": "CLOSED",
    "packs": [
      {
        "packageId": "c1a2b3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sequence": 1,
        "invoiceCount": 500,
        "receptionCode": "1899274638201",
        "status": "VALIDATED",
        "errorDetail": null
      },
      {
        "packageId": "d2b3c4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "sequence": 2,
        "invoiceCount": 250,
        "receptionCode": "1899274638455",
        "status": "REJECTED",
        "errorDetail": "[1009] LA FECHA DE EMISION ENVIADA EN EL XML NO ES VALIDA"
      }
    ]
  }
}

Estados de un paquete:

Estado	Significa
`PENDING`	Armado, todavia no enviado
`SENT`	El SIAT lo recibio y dio `receptionCode`; falta validar
`VALIDATED`	El SIAT lo dio por bueno
`REJECTED`	El SIAT rechazo facturas del paquete
`ERROR`	Fallo el armado o el envio

Rectificar rechazos

POST /api/v1/massive/rectify

Parametro	Ubicacion	Tipo	Req	Descripcion
`X-API-Key`	Header	string	Si	Tu API Key
`posId`	Body	string	Si	UUID del punto de venta

A las facturas que el SIAT rechazo se les regenera el CUF, el XML, la firma y el QR contra el CUFD vigente, y vuelven a la cola del lote. Despues hay que cerrar de nuevo con /massive/end para reenviarlas. Las facturas ya aceptadas no se tocan: su CUF esta validado por el SIAT y regenerarlo cambiaria un documento fiscal firme.

Respuesta 200

{
  "success": true,
  "message": "12 factura(s) regeneradas y devueltas al lote: cerrar de nuevo con /massive/end para reenviarlas",
  "data": {
    "batchId": "8f14e45f-ceea-467a-9575-4c4d0a8f4c23",
    "batchCode": "K3M9PQZ7XR2WNB4TV",
    "facturasRectificadas": 12
  }
}

Estados de la factura en masiva

Estado	Cuando
`MASSIVE_PENDING`	Emitida dentro del lote abierto; todavia no viajo al SIAT
`ACCEPTED`	El paquete se valido y esta factura no tuvo observaciones
`REJECTED`	El SIAT la observo; el motivo queda en la factura

Una factura en MASSIVE_PENDING ya tiene su CUF definitivo y su QR: podes entregarla e imprimirla. El SIAT validara ese mismo documento cuando cierres el lote.

Limites

Limite	Valor
Facturas por paquete	500
Paquetes por lote	Sin limite
Lotes abiertos por punto de venta	1

Si el lote tiene mas facturas que el limite por paquete, se parte solo en tantos paquetes como haga falta.

Información General

Endpoints Disponibles

Documentos Sector

Utilidades y Soporte

Las tres modalidades

Ciclo de un lote

Abrir un lote

Cerrar el lote

Ver el lote

Rectificar rechazos

Estados de la factura en masiva

Limites

​Las tres modalidades

​Ciclo de un lote

​Abrir un lote

​Cerrar el lote

​Ver el lote

​Rectificar rechazos

​Estados de la factura en masiva

​Limites

Las tres modalidades

Ciclo de un lote

Abrir un lote

Cerrar el lote

Ver el lote

Rectificar rechazos

Estados de la factura en masiva

Limites