Protección de credenciales
curl --request POST \
--url https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resumeimport requests
url = "https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyProtección de credenciales
Identifica el freno o la suspensión de lectura de documentos y reanuda una credencial con POST /api/v3/security/credentials//resume.
POST
/
api
/
v3
/
security
/
credentials
/
{kid}
/
resume
Protección de credenciales
curl --request POST \
--url https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resumeimport requests
url = "https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cucu.bo/api/v3/security/credentials/{kid}/resume")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodycucu 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.
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 (
Es idempotente:
Revocar una llave del todo sigue siendo una acción de CUCU (
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 | Sí |
| Patrón inusual: freno temporal | 429 + Retry-After | CREDENTIAL_THROTTLED | Sí, al cerrar la ventana |
| Insiste durante el freno o reincide | 403 | CREDENTIAL_SUSPENDED_DOCUMENTS | No: rotar y reanudar |
429 o 403). Listar y
ver webhooks, y eliminarlos, siguen permitidos.
Los links temporales 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):
{
"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
- Rotá la llave (Rotación). La llave nueva no hereda la suspensión.
- Con la llave nueva, reanudá la suspendida:
curl -X POST https://sandbox.cucu.bo/api/v3/security/credentials/k7m2p9q4x1/resume \
-H "X-API-Key: YOUR_NEW_API_KEY"
{ "success": true, "data": { "kid": "k7m2p9q4x1", "resumed": true, "suspended": false }, "timestamp": "2026-11-18T12:00:00.000-04:00" }
resumed: false si no estaba suspendida.
| HTTP | error.code | Causa |
|---|---|---|
404 | NOT_FOUND | La llave no existe para tu tenant (una ajena responde igual) |
409 | CREDENTIAL_ROTATION_REQUIRED | Llamaste con la propia llave suspendida o una anterior a la suspensión |
403 | FORBIDDEN | Credencial de servicio (ck_svc_): reanuda sólo el dueño |
revocarApiKey).