> ## 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.

# Cargar el token delegado del SIN

> Reemplazo del token delegado del SIN de tu empresa: se valida, se prueba contra el SIN antes de guardarlo y el CUIS de tus puntos de venta sale solo.

El token delegado es el JWT que el portal del SIN genera para que el sistema de CUCU facture a nombre de tu empresa. Vence una vez al año y es distinto en piloto (sandbox) y en producción.

## Cargar o rotar el token

`PUT /api/v3/admin/company/{companyId}/siat-token`

| Parametro | Ubicacion | Tipo | Req | Descripcion |
| - | - | - | - | - |
| `X-API-Key` | Header | string | Si | Tu API Key (`sk_live_...` o `sk_test_...`) |
| `companyId` | Path | UUID | Si | ID de la empresa |
| `token` | Body | string | Si | El JWT delegado tal como lo da el portal del SIN |

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT https://sandbox.cucu.bo/api/v3/admin/company/COMPANY_ID/siat-token \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJ0eXAiOiJKV1Qi..."}'
```

Qué pasa, en orden. Hasta el último paso no se guarda nada:

1. Si es el mismo token que ya está cargado, responde `200` con `changed: false` y no guarda nada. Si algún punto de venta quedó sin CUIS (un pedido anterior falló), se lo vuelve a pedir y aparece en `pointsOfSale`. Si el guardado tenía espacios alrededor o una empresa hermana tiene otro, se corrige y responde `changed: true`.
2. Se leen los datos del token (los espacios y saltos de línea alrededor se ignoran; adentro, no): que no esté vencido ni por vencer, que sea de un sistema de CUCU, que esté delegado a CUCU y que el NIT sea el de tu empresa.
3. Se prueba contra el SIN del mismo ambiente (piloto en sandbox, producción en producción) con una consulta real de CUIS, sin guardar nada.
4. Se guarda el token cifrado, también en las empresas del mismo tenant con el mismo NIT y el mismo sistema (comparten la credencial), y se pide el CUIS de cada punto de venta de todas ellas que no tenga uno vigente.

Con tu API Key podés **rotar** el token del mismo sistema. Si el token es de **otro sistema** que el de tu empresa, el cambio lo hace CUCU (pedilo a soporte).

**Respuesta:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "message": "Token delegado actualizado",
  "data": {
    "companyId": "34895a68-06de-47a2-bcac-ce5723b0b92b",
    "nit": "1021293022",
    "systemCode": "3745FCF9685ABD712697",
    "previousSystemCode": "3745FCF9685ABD712697",
    "expiresAt": "2027-11-21T17:51:23Z",
    "tokenSource": "db",
    "changed": true,
    "siblingCompanies": [],
    "pointsOfSale": [
      { "posId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "companyId": "34895a68-06de-47a2-bcac-ce5723b0b92b",
        "branchCode": 0, "posCode": 0, "result": "SOLICITADO", "message": "CUIS vigente hasta 2027-11-20T23:59:59" },
      { "posId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "companyId": "34895a68-06de-47a2-bcac-ce5723b0b92b",
        "branchCode": 0, "posCode": 1, "result": "YA_VIGENTE", "message": "CUIS vigente hasta 2027-05-02T23:59:59" }
    ]
  }
}
```

| Campo | Descripcion |
| - | - |
| `systemCode` | Sistema del SIN del token (`codigoSistema`) |
| `expiresAt` | Vencimiento del token |
| `changed` | `false` si el token ya estaba cargado |
| `pointsOfSale[].result` | `SOLICITADO` (CUIS nuevo), `RECUPERADO_980` (el SIN ya tenía uno y se tomó), `YA_VIGENTE`, `RECHAZADO` (con el mensaje del SIN), `NO_ADMITIDO` (empresa o punto de venta inactivo), `ERROR` (el SIN no respondió; la renovación automática de CUIS lo reintenta, o volvé a llamar con el mismo token) |

Un punto de venta rechazado no deshace la carga: el token ya pasó la prueba contra el SIN. El `message` dice qué contestó el SIN para ese punto de venta.

Rotar el token se puede aunque haya eventos de contingencia abiertos o sin registrar: suele ser justo lo que los provocó. El cierre del evento, su registro y el envío del paquete toman el token nuevo en su próximo intento.

El token nunca vuelve en una respuesta.

### Errores

| Código | HTTP | Cuándo |
| - | - | - |
| `TOKEN_SIAT_MALFORMADO` | 400 | No es un JWT del SIN legible, le falta `codigoSistema` o `exp`, o es demasiado largo |
| `TOKEN_SIAT_VENCIDO` | 400 | Venció o vence en los próximos días |
| `TOKEN_SIAT_OTRO_NIT` | 400 | Es de otro contribuyente |
| `TOKEN_SIAT_OTRO_PROVEEDOR` | 400 | No está delegado a CUCU |
| `TOKEN_SIAT_OTRO_SISTEMA` | 400 | El sistema no es de CUCU |
| `TOKEN_SIAT_SOLO_ADMIN` | 403 | El token es de otro sistema que el de tu empresa: el cambio lo hace CUCU |
| `NOT_FOUND` | 404 | La empresa no existe o no es tuya |
| `TOKEN_SIAT_EN_CURSO` | 409 | Otra carga del token de la misma empresa está en curso |
| `TOKEN_SIAT_OVERRIDE_BWS` | 409 | CUCU administra el token de tu empresa en su configuración: pedí el cambio a soporte |
| `TOKEN_SIAT_RECHAZADO` | 422 | El SIN no aceptó el token (por ejemplo `API KEY NO VALIDO`). Suele ser un token de otro ambiente (piloto o producción) o de otro sistema |
| `SIAT_UNAVAILABLE` | 503 | El SIN no respondió la prueba. No se guardó nada; reintentá en unos minutos |
| `TOKEN_SIAT_NO_CONFIGURADO` | 503 | El ambiente no tiene configurados los sistemas de CUCU. Avisá a soporte |

En todos los errores, el token anterior sigue cargado.

## Cambio de sistema (CUCU)

Cuando el token es de otro sistema, la administración de CUCU lo carga con el mismo endpoint. El SIN lo prueba igual, y la respuesta es `409 TOKEN_SIAT_CAMBIO_DE_SISTEMA` con `tokenRef` (el SHA-256 del token) y el `codigoSistema` nuevo en `error.details`. El cambio se hace con:

`PUT /api/v3/admin/company/{companyId}/siat-token/system-change`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "tokenRef": "9f2c…64 hex…", "codigoSistema": "374B30D7407DEEE0E697" }
```

Pide [confirmación humana](https://docs.cucu.bo/mcp/para-agentes.md#confirmación-humana). Al ejecutar valida y prueba el token de nuevo, guarda el token y el sistema en la empresa y en las empresas del mismo tenant con el mismo NIT y el mismo sistema anterior, y pide el CUIS de todos sus puntos de venta. Antes de guardar deja inactivos el CUIS y el CUFD del sistema anterior, así ninguna factura sale con códigos del sistema viejo. Con cada CUIS nuevo, el CUFD del punto de venta se pide enseguida, sin esperar a la primera factura. Con trabajo fiscal en curso (facturas que el SIN todavía no cerró, anulaciones en curso, eventos de contingencia abiertos o sin registrar, lotes masivos abiertos, paquetes enviándose) responde `409 TOKEN_SIAT_TRABAJO_PENDIENTE`. Antes de la aprobación sólo se consulta al SIN; el CUIS se pide después. La referencia vive lo que una confirmación más unos minutos; si la ejecución falla (por ejemplo el SIN no responde) se puede volver a aprobar mientras viva, y se gasta cuando el cambio se guarda.

Herramientas MCP gemelas: [`actualizarTokenSiat`](https://docs.cucu.bo/mcp/herramientas-admin#actualizartokensiat) y [`cambiarSistemaTokenSiat`](https://docs.cucu.bo/mcp/herramientas-admin#cambiarsistematokensiat).


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