Autenticación de la API
Cómo se autentican los programas en Notificado (un token de agente como Bearer en /v1 y en MCP), sus alcances, vigencias y límites.
Actualizado:
Notificado tiene dos puertas para programas, y una sola credencial abre ambas: un token de agente emitido en Cuenta → API (/cuenta/api).
| Puerta | Dónde | Para qué |
|---|---|---|
| API HTTP | https://www.notificado.co/v1/<operación> |
Sus propias integraciones: un sistema de procesos, un script, una cola. Documentada en la referencia. |
| MCP | POST https://www.notificado.co/mcp |
Asistentes de IA. Vea Conectar un asistente de IA. |
Ambas ven las mismas operaciones, con los mismos alcances y las mismas reglas: POST /v1/create-case y la herramienta MCP createCase son una sola operación.
Esta guía es para las firmas. Un afiliado del programa de referidos tiene sus propias puertas, https://www.notificado.co/v1/afiliados y https://www.notificado.co/mcp/afiliados, con un token de afiliado emitido en /afiliados; un token de firma no abre esas puertas ni uno de afiliado abre estas. Vea API para afiliados.
Enviar el token
Cada llamada a /v1 lo lleva en el encabezado Authorization:
curl 'https://www.notificado.co/v1/case-list?orgId=<orgId>' \
-H "authorization: Bearer $NOTIFICADO_TOKEN"const response = await fetch('https://www.notificado.co/v1/case-list?orgId=<orgId>', {
headers: { authorization: `Bearer ${process.env.NOTIFICADO_TOKEN}` },
});Sin cookie ni encabezado origin: el token es toda la credencial. Una cookie de sesión del panel no alcanza nada bajo /v1.
| Respuesta | Cuándo |
|---|---|
401 + WWW-Authenticate: Bearer |
Sin token. |
401 + WWW-Authenticate: Bearer error="invalid_token" |
Un token mal formado, desconocido, vencido o revocado; a propósito no se distinguen. |
404 X_ROUTE_NOT_FOUND |
La operación está fuera de los alcances del token: responde igual que si no existiera, como una herramienta MCP que el token no ve. |
403 X_FORBIDDEN |
El alcance la cubre, pero la persona detrás del token no puede hacerla (su rol, o un orgId que no es de su firma). |
Emitir un token
- Un propietario o abogado de la firma abre Cuenta → API (/cuenta/api).
- Le pone un nombre, elige sus alcances y una vigencia: 30, 60, 90, 180 o 365 días, una fecha exacta (vence al terminar ese día, hora de Colombia) o sin vencimiento. Un token sin vencimiento funciona hasta que alguien lo revoque; revoque los que ya no use. Quien lo emitió puede cambiar el vencimiento después, en la misma página, y un propietario puede cambiarlo en el token de cualquier miembro. Alargarlo o dejarlo sin vencimiento pide confirmar su identidad (su contraseña o el código de su autenticador), y a quien tiene el token le llega un correo con el cambio.
- El token se muestra una sola vez. Guardamos solo su huella; si lo pierde, revóquelo y emita otro.
El token actúa por quien lo emitió, en su firma y con su rol actual: si esa persona sale de la firma o baja de rol, el token pierde ese poder en la siguiente llamada. El prefijo (ult_prod_<id>) se puede mostrar y registrar; el resto es una contraseña. Guárdelo en un gestor de secretos o una variable de entorno, nunca en el código ni en un repositorio.
Alcances
| Alcance | Qué permite |
|---|---|
cases:read |
Listar y leer los procesos de la firma (case-list, get-case) y sus importaciones CSV. |
cases:write |
Crear y editar procesos y partes; cargar documentos (create-case, update-case, add-party, request-upload, confirm-upload); importar un CSV de procesos y borradores. |
notifications:read |
Leer notificaciones y sus memoriales, los problemas de entrega, los envíos que esperan la confirmación de un abogado, el saldo de créditos y verificar constancias. |
notifications:write |
Revisar una dirección antes de añadirla, preparar borradores, adjuntar documentos, generar el memorial para el juzgado y pedir un envío, que un abogado confirma en el panel. |
evidence:read |
Descargar la constancia firmada, el paquete de evidencia y los memoriales (cada descarga queda registrada), y leer su nombre, tamaño y SHA-256 antes (evidence-download-info, que no registra nada). Un asistente por MCP descarga por HTTP; vea Paquete para el perito. |
deadlines:read |
Leer los términos calculados por destinatario. |
billing:read |
Leer el extracto de créditos y las facturas electrónicas de la firma, y descargar una factura (cada descarga queda registrada). |
activity:read |
Leer el registro de actividad de la firma: quién redactó, juró, envió, confirmó, descargó o cambió miembros y tokens. |
webhooks:manage |
Registrar, cambiar, probar y eliminar los webhooks de la firma y leer su registro de entregas. Solo con el token de un propietario; vea Webhooks. |
Ningún alcance permite agregar o quitar destinatarios (el juramento del art. 8 es del abogado), confirmar un envío, comprar créditos ni nada de la consola interna de Notificado. Dé a cada integración los alcances mínimos que necesita.
Límites de frecuencia
Cada token puede hacer 120 solicitudes por minuto en /v1. Toda respuesta trae:
| Encabezado | Significado |
|---|---|
RateLimit-Limit |
La cuota por ventana. |
RateLimit-Remaining |
Lo que queda de ella. |
RateLimit-Reset |
Segundos hasta que la ventana se reinicia. |
Pasado el límite la respuesta es 429 X_RATE_LIMITED con Retry-After, los segundos que debe esperar: espere ese tiempo y repita la misma solicitud (con el mismo Idempotency-Key si era una creación; vea Reintentos idempotentes). Algunas operaciones tienen además un límite propio, por persona: las cargas, por ejemplo, admiten 30 por minuto. Más en Límites.
Las rutas propias del panel
Las operaciones bajo /api/… y /_x/query/… son las que el panel llama con una sesión iniciada. Aparecen en la referencia por completitud, no tienen promesa de compatibilidad y rechazan un token Bearer. Construya sus integraciones sobre /v1; sus cambios se anuncian en Cambios de la API.
Respuestas de error
Toda negativa trae code, cause y fix. Vea Errores y, código por código, el catálogo de errores.