Base
La API vive en https://api.activar.dev. Todas las respuestas son JSON. El body
máximo permitido es de 8 192 bytes y cada petición de CID tiene un límite de
90 segundos de proceso.
Autenticación
Todas las rutas /v1/* exigen tu clave en el header
Authorization: Bearer <clave>. Emites y gestionas tus claves en el bot de
Telegram (@cidiid_bot, comando /api);
cada clave se entrega una sola vez — guardamos solo su hash — y puede rotarse o revocarse cuando
quieras.
Identificador de petición
Cada respuesta exitosa lleva un request_id: guárdalo. Es la referencia exacta
en la bitácora si necesitas soporte o auditoría de un cobro.
POST /v1/cid
El endpoint principal: entra un ID de instalación (IID), sale el código de confirmación (CID) que activa Windows u Office por la vía telefónica de Microsoft, sin llamada y sin cuenta Microsoft.
# generar un CID
curl -X POST https://api.activar.dev/v1/cid \
-H "Authorization: Bearer gc_live_TU_CLAVE" \
-H "Content-Type: application/json" \
-d '{"iid":"00269538026695922170826852518480286383828529569486954"}'
Body
| Campo | Tipo | Notas |
|---|---|---|
| iid | string | El ID de instalación completo, con o sin guiones. Se valida su checksum; uno inválido se rechaza sin cobro. |
Respuesta 200
{
"ok": true,
"cid": "012345 678901 234567 890123 456789 012345 678901 234567",
"blocks": ["012345","678901","234567","890123","012345","678901","678901","234567"],
"cached": false,
"source": "soap",
"charged": 0.1,
"request_id": "uuid-de-la-peticion",
"balance": 4.90
}
| Campo | Qué significa |
|---|---|
| cid | El código de confirmación listo para teclear en el asistente de activación. |
| blocks | El mismo CID partido en bloques de 6, como lo pide el asistente. |
| cached | true si el CID ya se había generado antes — se entrega de inmediato y no se cobra de nuevo. |
| charged | Lo cobrado por esta petición, en USD. 0.0 en aciertos de cache. |
| balance | Tu saldo resultante, en USD. |
Tiempos
Un acierto de cache responde en milisegundos. Una generación nueva normalmente tarda
segundos; el límite duro del sistema es de 90 segundos — si se pasa, responde
503 TIMEOUT sin cobrar y puedes reintentar.
GET /v1/balance
Saldo actual, cap diario y gasto del día (UTC) de tu clave.
# consulta
curl https://api.activar.dev/v1/balance \
-H "Authorization: Bearer gc_live_TU_CLAVE"
{
"balance": 4.90,
"currency": "USD",
"cap_diario_cents": 500,
"gastado_hoy_cents": 10
}
GET /v1/usage
Bitácora de consumo de tu clave: las últimas peticiones con su resultado, cobro y duración.
Parámetro opcional limit (1–200, default 50).
curl "https://api.activar.dev/v1/usage?limit=20" \ -H "Authorization: Bearer gc_live_TU_CLAVE"
GET /healthz · GET /readyz
Monitoreo simple. /healthz confirma que el servicio vive;
/readyz confirma que la base responde y reporta los slots de generación libres.
Ambas públicas, sin autenticación.
Errores
Los errores son JSON estables: {"ok": false, "error": {"code", "message"}}.
Un 502/503 jamás viene con cobro — si hubo un cobro, la operación ya trae su CID.
La lista de códigos:
| HTTP | Código | Qué significa | ¿Se cobró? |
|---|---|---|---|
| 400 | IID_INVALID | El IID no tiene el formato de un ID de instalación | No |
| 400 | IID_CHECKSUM_INVALID | El IID no pasa la validación de dígito de control | No |
| 401 | KEY_MISSING | Falta el header Authorization | No |
| 401 | KEY_INVALID | La clave no existe o no coincide | No |
| 403 | KEY_PENDING | La clave se emitió pero aún no confirmas su entrega por DM en el bot | No |
| 403 | KEY_REVOKED | La clave fue revocada | No |
| 402 | NO_BALANCE | Saldo insuficiente para el precio del CID | No |
| 429 | CAP_DIARIO | Alcanzaste el tope diario de gasto de tu clave | No |
| 429 | RATE_LIMITED | Demasiadas peticiones seguidas — respeta el Retry-After | No |
| 409 | — | El IID ya está en proceso por otra petición; espera su resultado o el vencimiento | No |
| 502 | UPSTREAM_ERROR | Microsoft rechazó la generación; no reintentar en automático | No |
| 503 | BUSY | Sin slots libres ahora; reintenta con Retry-After | No |
| 503 | TIMEOUT | La generación rebasó 90 s; seguro reintentar | No |
| 503 | CACHE_UNAVAILABLE | El cache está temporalmente caído; reintenta | No |
| 413 | PAYLOAD_TOO_LARGE | Body mayor a 8 192 bytes | No |
El cobro es atómico con la entrega: cada petición queda registrada en tu bitácora
con su cobro exacto (charged) o con cobro cero si falló. Nunca hay un cobro sin
CID ni un CID sin su registro.
Próximamente
Estos endpoints están en el plan de integración del portal y de la API:
- POST /v1/checkkey — verificación de claves (gratis, con protección anti-abuso) para herramientas y el revisor web.
- Autenticación de sesión — login web por código de un uso, deep-link al bot.
- CRUD de claves desde el panel — crear, listar y revocar sin pasar por el bot.
- GET /v1/ledger — la bitácora completa de movimientos de saldo en la API.
Consigue tu clave de API en el bot
Manda /api en el bot: emites tu clave, la recibes por mensaje directo y
gestionas sus topes. Tu saldo de Telegram es el mismo que consume la API.