> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Contingencia

> Gestiona eventos de contingencia cuando el SIAT no esta disponible.

Cuando el SIAT no responde, puedes activar un evento de contingencia para seguir emitiendo facturas offline. Las facturas emitidas en contingencia se envian al SIAT cuando el servicio se restablece.

## Iniciar Evento de Contingencia

`POST /api/v1/events/start`

| Parametro | Ubicacion | Tipo | Req | Descripcion |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Si | Tu API Key |
| `posId` | Body | string | Si | UUID del punto de venta |
| `branchId` | Body | string | Si | UUID de la sucursal |
| `codigoMotivo` | Body | integer | Si | Codigo de motivo: `1` = Corte de internet, `2` = Falla SIAT, `3` = Virus informatico, `4` = Otro |
| `descripcion` | Body | string | Si | Descripcion del evento |

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://sandbox.cucu.bo/api/v1/events/start \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "posId": "660e8400-e29b-41d4-a716-446655440004",
      "branchId": "660e8400-e29b-41d4-a716-446655440003",
      "codigoMotivo": 2,
      "descripcion": "SIAT no responde desde las 10:00"
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://sandbox.cucu.bo/api/v1/events/start', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      posId: '660e8400-e29b-41d4-a716-446655440004',
      branchId: '660e8400-e29b-41d4-a716-446655440003',
      codigoMotivo: 2,
      descripcion: 'SIAT no responde desde las 10:00'
    })
  });
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      'https://sandbox.cucu.bo/api/v1/events/start',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': 'YOUR_API_KEY'
      },
      json={
          'posId': '660e8400-e29b-41d4-a716-446655440004',
          'branchId': '660e8400-e29b-41d4-a716-446655440003',
          'codigoMotivo': 2,
          'descripcion': 'SIAT no responde desde las 10:00'
      }
  )
  ```
</CodeGroup>

**Respuesta (200):**

```json theme={"system"}
{
  "success": true,
  "data": {
    "id": "event-uuid-123",
    "posId": "660e8400-e29b-41d4-a716-446655440004",
    "codigoMotivo": 2,
    "descripcionMotivo": "Falla SIAT",
    "fechaInicio": "2026-02-11T10:00:00",
    "fechaFin": null,
    "cufdEvento": "BQW5FZ...",
    "codigoEventoSiat": 12345,
    "finalizado": false,
    "createdAt": "2026-02-11T10:00:00"
  }
}
```

***

## Finalizar Evento de Contingencia

`POST /api/v1/events/end`

| Parametro | Ubicacion | Tipo | Req | Descripcion |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Si | Tu API Key |
| `posId` | Body | string | Si | UUID del punto de venta |
| `branchId` | Body | string | Si | UUID de la sucursal |
| `eventoId` | Body | string | Si | UUID del evento a finalizar |
| `fechaFin` | Body | string | No | Cierre retroactivo: fecha/hora ISO-8601 en que termino la facturacion manual (posterior al inicio). Omitir para usar la fecha/hora actual |
| `repeticiones` | Body | integer | No | **Solo certificacion.** Cuantas veces mandar el MISMO paquete al SIAT (1-10, default 1). Ver [Repeticiones](#repeticiones-para-certificar) |

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://sandbox.cucu.bo/api/v1/events/end \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "posId": "660e8400-e29b-41d4-a716-446655440004",
      "branchId": "660e8400-e29b-41d4-a716-446655440003",
      "eventoId": "event-uuid-123"
    }'
  ```
</CodeGroup>

**Respuesta (200):**

```json theme={"system"}
{
  "success": true,
  "message": "Evento cerrado: 3/3 paquete(s) aceptados por SIAT",
  "data": {
    "id": "event-uuid-123",
    "posId": "660e8400-e29b-41d4-a716-446655440004",
    "codigoMotivo": 2,
    "descripcionMotivo": "Falla SIAT",
    "fechaInicio": "2026-02-11T10:00:00",
    "fechaFin": "2026-02-11T14:30:00",
    "cufdEvento": "BQW5FZ...",
    "codigoEventoSiat": 12345,
    "finalizado": true,
    "paquetes": [
      {
        "sector": 1,
        "tipoFactura": 1,
        "facturas": 120,
        "estado": "VALIDATED",
        "codigoRecepcion": "1234567890123",
        "detalle": null,
        "facturasMarcadas": 120,
        "facturasSinMarcar": 0,
        "repeticiones": 1,
        "repeticionesExitosas": 1
      }
    ]
  }
}
```

<Warning>
  **`finalizado: true` NO significa que tus facturas entraron al SIAT.** Solo dice que el
  evento se cerro y se registro. El envio del paquete es un paso aparte y puede fallar
  (timeout del SIAT, rechazo del paquete) dejando el evento igualmente finalizado.

  Para saber si las facturas entraron, revisa `paquetes`: cada entrada es un paquete
  (un sector + tipo de factura) y su `estado` final.

  | Estado | Que paso |
  | - | - |
  | `VALIDATED` | El SIAT acepto el paquete. Sus facturas quedan aceptadas. |
  | `REJECTED` | El SIAT rechazo el paquete por contenido. `detalle` trae el mensaje del SIAT. |
  | `SENT` | El paquete llego al SIAT pero no se pudo confirmar la validacion. |
  | `ERROR` | No se pudo hablar con el SIAT (timeout o caida). |

  Si algun paquete no quedo en `VALIDATED`, el `message` de la respuesta lo dice y podes
  reintentar SOLO el envio con `POST /api/v1/events/resend` (no re-registra el evento).

  `facturasSinMarcar` mayor a cero significa que el paquete SI entro al SIAT pero algunas
  facturas todavia no reflejan el estado nuevo en la consulta; el reconciliador las
  actualiza solo en los minutos siguientes.
</Warning>

### Repeticiones para certificar

Impuestos certifica la contingencia pidiendo ver **N recepciones distintas del mismo
paquete**. Para eso, `repeticiones` (1-10) en `/events/end`:

* El paquete se arma **una sola vez** y se envia N veces en la misma llamada. Cada envio
  recibe su propio codigo de recepcion.
* A partir del segundo envio el SIAT contesta `[1000] EL CUF ENVIADO YA EXISTE EN LA BASE
  DE DATOS DEL SIN`. Es lo esperado (el SIAT ya ingesto el paquete en el primero) y **no**
  es un rechazo: el paquete queda `VALIDATED` si **alguna** repeticion valido.
* Las facturas se marcan una sola vez, al final.
* `repeticiones` y `repeticionesExitosas` de cada paquete dicen cuantas se pidieron y
  cuantas acepto el SIAT.

<Tip>
  Usa `repeticiones` en el **cierre**, no en un `/events/resend` posterior: el resend vuelve
  a armar el paquete con las facturas que siguen pendientes, asi que una vez que el
  reconciliador las valida, las repeticiones llevarian menos facturas o ninguna.
</Tip>

En operacion normal no lo mandes: el default es 1.

***

## Reenviar Paquete de un Evento

`POST /api/v1/events/resend`

Reenvia el paquete de facturas offline de un evento **ya registrado** en el SIAT, sin
re-registrar el evento. Es el reintento para cuando `/events/end` cerro el evento pero
algun paquete no entro.

| Parametro | Ubicacion | Tipo | Req | Descripcion |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Si | Tu API Key |
| `posId` | Body | string | Si | UUID del punto de venta |
| `branchId` | Body | string | Si | UUID de la sucursal |
| `eventoId` | Body | string | Si | UUID del evento |
| `repeticiones` | Body | integer | No | **Solo certificacion.** Cuantas veces mandar el MISMO paquete al SIAT (1-10, default 1). Ver [Repeticiones](#repeticiones-para-certificar) |

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://sandbox.cucu.bo/api/v1/events/resend \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "posId": "660e8400-e29b-41d4-a716-446655440004",
      "branchId": "660e8400-e29b-41d4-a716-446655440003",
      "eventoId": "event-uuid-123"
    }'
  ```
</CodeGroup>

**Respuesta (200):**

```json theme={"system"}
{
  "success": true,
  "data": {
    "eventoId": "event-uuid-123",
    "facturasAntes": 120,
    "facturasDespues": 0,
    "repeticiones": 1,
    "mensaje": "Paquete reenviado: 120 factura(s) fueron aceptadas por SIAT"
  }
}
```

`facturasDespues` es cuantas siguen pendientes despues del reenvio: `0` es exito total.

***

## Consultar Eventos

`POST /api/v1/events`

| Parametro | Ubicacion | Tipo | Req | Descripcion |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Si | Tu API Key |
| `posId` | Body | string | Si | UUID del punto de venta |
| `branchId` | Body | string | Si | UUID de la sucursal |
| `fechaEvento` | Body | string | Si | Fecha a consultar (formato `YYYY-MM-DD`) |

***

## Evento Activo

`GET /api/v1/events/active/{posId}`

Obtiene el evento de contingencia activo (no finalizado) para un punto de venta.

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

***

## Verificar Conexion SIAT

`GET /api/v1/events/check-connection`

Verifica si el SIAT esta respondiendo. Util para decidir si iniciar contingencia.

| Parametro | Ubicacion | Tipo | Req | Descripcion |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Si | Tu API Key |

```json theme={"system"}
{
  "success": true,
  "data": true
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.