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

# Protección de credenciales

> Identifica el freno o la suspensión de lectura de documentos y reanuda una credencial con POST /api/v3/security/credentials/{kid}/resume.

cucu vigila, **por llave**, la lectura de documentos (PDF, XML, ZIP, links temporales), los listados y el detalle de
facturas. Si una llave lee de una forma que no es la suya (muchas facturas distintas en una hora contra su propio
historial, o muchas búsquedas de ids/CUF que no existen), se frena y, si insiste, se suspende **sólo su lectura**.

> [!NOTE]
>
> **Emitir, anular, `/status`, `by-idempotency-key` y el dashboard nunca se frenan.** Tu facturación sigue aunque la
> lectura de documentos esté suspendida.

| Situación | HTTP | `error.code` | Vuelve sola |
| - | - | - | - |
| Cupo fijo de documentos por minuto/día o de páginas de listado por día | `429` + `Retry-After` | [`RATE_LIMITED`](https://docs.cucu.bo/errors#rate_limited) | Sí |
| Patrón inusual: freno temporal | `429` + `Retry-After` | [`CREDENTIAL_THROTTLED`](https://docs.cucu.bo/errors#credential_throttled) | Sí, al cerrar la ventana |
| Insiste durante el freno o reincide | `403` | [`CREDENTIAL_SUSPENDED_DOCUMENTS`](https://docs.cucu.bo/errors#credential_suspended_documents) | No: rotar y reanudar |

Una llave frenada o suspendida tampoco puede **abrir ni redirigir un canal que exporta datos de compradores**: crear o
modificar un webhook, rotar su secreto o reenviar una entrega (REST y MCP) responde lo mismo (`429` o `403`). Listar y
ver webhooks, y eliminarlos, siguen permitidos.

Los [links temporales](https://docs.cucu.bo/api/get-invoice.md#link-temporal) que emitió una llave suspendida o revocada dejan de bajar en el acto
(`410 DOCUMENT_LINK_GONE`), igual que los de un tenant dado de baja. Esto rige en todos los ambientes.

## Avisos

Cuando de verdad se frena o suspende, se avisa por correo al contacto de la empresa y por webhook
([`security.credential_throttled` / `security.credential_suspended`](https://docs.cucu.bo/api/webhooks#catálogo-de-eventos)):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "credential_kid": "k7m2p9q4x1",
  "action": "suspended",
  "scope": "documents",
  "signal": "barrido",
  "resume_url": "https://sandbox.cucu.bo/api/v3/security/credentials/k7m2p9q4x1/resume",
  "occurred_at": "2026-11-18T16:00:00.000+0000"
}
```

`credential_kid` es el id **público** de la llave (nunca la llave). `signal`: `barrido` (muchas facturas distintas) o
`enumeracion` (ids/CUF inexistentes). `retry_after_seconds` sólo en `throttled`; `resume_url` sólo en `suspended`.

## Reanudar

1. **Rotá la llave** ([Rotación](https://docs.cucu.bo/authentication.md#rotación)). La llave nueva no hereda la suspensión.
2. Con la **llave nueva**, reanudá la suspendida:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://sandbox.cucu.bo/api/v3/security/credentials/k7m2p9q4x1/resume \
  -H "X-API-Key: YOUR_NEW_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "success": true, "data": { "kid": "k7m2p9q4x1", "resumed": true, "suspended": false }, "timestamp": "2026-11-18T12:00:00.000-04:00" }
```

Es idempotente: `resumed: false` si no estaba suspendida.

| HTTP | `error.code` | Causa |
| - | - | - |
| `404` | [`NOT_FOUND`](https://docs.cucu.bo/errors#not_found) | La llave no existe para tu tenant (una ajena responde igual) |
| `409` | [`CREDENTIAL_ROTATION_REQUIRED`](https://docs.cucu.bo/errors#credential_rotation_required) | Llamaste con la propia llave suspendida o una anterior a la suspensión |
| `403` | [`FORBIDDEN`](https://docs.cucu.bo/errors#forbidden) | Credencial de servicio (`ck_svc_`): reanuda sólo el dueño |

Revocar una llave del todo sigue siendo una acción de CUCU (`revocarApiKey`).


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