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. El lote es multi-sector: acepta facturas de cualquier sector que tu empresa tenga autorizado, y al cerrarlo se arma un paquete por cada combinacion de sector y tipo de documento. Un solo lote alcanza para emitir de todos tus sectores.

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

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",
    "status": "OPEN",
    "closedAt": null
  }
}

El lote no lleva sector. El sector lo trae cada factura al emitirse, y ahi es donde se valida: si no esta soportado o tu empresa no lo tiene autorizado ante el SIN, el 422 (SECTOR_NOT_SUPPORTED / SECTOR_NOT_AUTHORIZED) lo devuelve POST /api/v1/invoices, no la apertura del lote.

Hasta la version anterior el lote fijaba sector e invoiceType al abrirse y todo el lote viajaba a ese sector. Si los seguis mandando en el body, se ignoran.

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
`repeticiones`	Body	integer	No	Veces que se manda cada paquete (1-10). Por defecto `1`

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.

Repeticiones (certificacion)

repeticiones manda el mismo paquete N veces al SIAT: el archivo se arma una sola vez y se reenvia tal cual. Es lo que pide Impuestos para certificar la modalidad masiva, igual que en el reenvio del paquete de contingencia. No cambia el resultado fiscal: cada repeticion recibe su propio codigoRecepcion y las facturas se marcan una sola vez. Decide la primera repeticion que valida, y el paquete se queda con su codigoRecepcion: las siguientes rebotan con [1000] EL CUF ENVIADO YA EXISTE EN LA BASE DE DATOS DEL SIN, que es lo esperado (el SIAT ya ingesto el paquete) y no un rechazo. En operacion normal se omite.

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,
    "packsPendientes": 0,
    "facturasAceptadas": 1250,
    "facturasRechazadas": 0,
    "paquetes": [
      {
        "packageId": "c1a2b3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sequence": 1,
        "sector": 1,
        "invoiceType": 1,
        "invoiceCount": 500,
        "status": "VALIDATED",
        "receptionCode": "1899274638201",
        "errorDetail": null
      },
      {
        "packageId": "d2b3c4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "sequence": 2,
        "sector": 23,
        "invoiceType": 1,
        "invoiceCount": 500,
        "status": "VALIDATED",
        "receptionCode": "1899274638455",
        "errorDetail": null
      }
    ]
  }
}

El message distingue cuatro desenlaces que no hay que confundir:

Sin facturas — el lote se cerro vacio, no habia nada que enviar.
Todo aceptado — facturasRechazadas, packsRechazados y packsPendientes en 0.
Pendiente de validacion — packsPendientes mayor a 0 y sin rechazos: el SIAT recibio los paquetes pero todavia los esta procesando (codigo 901).
Con rechazos — parte del lote quedo REJECTED; hay que rectificar.

Un paquete pendiente no es un rechazo: no lo rectifiques. Con paquetes grandes el SIAT suele contestar 901 a la validacion inmediata porque todavia esta procesando. El paquete queda en SENT, sus facturas en ACCEPTED, y el reconciliador las valida por CUF en los minutos siguientes. /massive/rectify les regeneraria el CUF a facturas que el SIAT ya tiene, y las duplicaria.

Mira siempre paquetes[]: con un lote multi-sector, “2 de 13 paquetes rechazados” no te dice que sectores no entraron. Cada entrada trae su sector, su estado y el motivo del SIAT si lo hubo.

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,
        "sector": 1,
        "invoiceType": 1,
        "invoiceCount": 500,
        "receptionCode": "1899274638201",
        "status": "VALIDATED",
        "errorDetail": null
      },
      {
        "packageId": "d2b3c4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "sequence": 2,
        "sector": 23,
        "invoiceType": 1,
        "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 (o contesto `901`, todavia procesando). No se rectifica
`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
Sectores por lote	Sin limite
Lotes abiertos por punto de venta	1

Al cerrar, las facturas se agrupan primero por sector y tipo de documento — un paquete SIAT tiene que ser homogeneo en esa combinacion — y cada grupo se parte despues en tantos paquetes de 500 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

Repeticiones (certificacion)

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

​Repeticiones (certificacion)

​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

Repeticiones (certificacion)

Ver el lote

Rectificar rechazos

Estados de la factura en masiva

Limites