Conceptos generales de la API de Panteum

Esta página explica lo que comparten todas las APIs documentadas en el portal: dónde están, cómo responden, cómo se autentican y qué límites tienen. Léela una vez; el resto de páginas dan por entendido su contenido.

1. URL base de cada servicio

Cada módulo de Panteum se publica en su propio subdominio y todos sus endpoints cuelgan de /api. En esta documentación se usa un marcador de posición que debes reemplazar por el dominio de tu entidad:

Las direcciones de esta página son marcadores: cada entidad tiene las suyas. La única dirección real publicada es la del conector MCP de la demostración (https://mcp.serviciostic.net/api/mcp).

Para qué	Servicio	URL base (marcador)
Identidad visual pública	identidad	https://identidad.tu-entidad.example/api/v1
Contacto de sitios web	notificaciones	https://notificaciones.tu-entidad.example/api/public/v1
Verificación de firmas	presupuesto	https://presupuesto.tu-entidad.example/api/v1
Asistentes de IA (MCP)	mcp	https://mcp.tu-entidad.example/api
Estado del servicio	solicitudes, presupuesto, archivos, calidad, mcp	https://<servicio>.tu-entidad.example/api/v1/ping

Todo el tráfico va por HTTPS. Las peticiones y respuestas usan JSON en UTF-8 (Content-Type: application/json, Accept: application/json), salvo los binarios (imágenes, PDF) que se indican en cada endpoint.

2. Formato de respuesta

Todas las respuestas JSON de la API usan el mismo envoltorio.

Éxito

{
  "success": true,
  "data": { "...": "carga útil del endpoint" },
  "message": "Texto opcional para mostrar al usuario"
}

Éxito con paginación (cuando el endpoint devuelve listas largas)

{
  "success": true,
  "data": [ { "id": 1 }, { "id": 2 } ],
  "meta": { "page": 1, "per_page": 15, "total": 42, "last_page": 3 },
  "message": null
}

Error

{
  "success": false,
  "error": {
    "code": "DATOS_INVALIDOS",
    "detalle": "Los datos enviados no son válidos.",
    "campos": { "correo": ["Escribe un correo válido."] }
  },
  "message": "Los datos enviados no son válidos."
}

• error.code es estable: úsalo en tu código para decidir qué hacer. error.detalle y message son texto en español para personas y pueden cambiar.
• error.campos solo aparece en errores de validación (HTTP 422) y lista, por campo, los problemas encontrados.
• La excepción es el protocolo MCP, que responde en JSON-RPC 2.0 (ver «Asistentes de IA (MCP)»).

3. Autenticación

Tipo	Cómo se envía	Dónde se usa
Ninguna	—	Endpoints públicos (identidad visual, estado del servicio, verificación de firmas, contacto de sitios).
API Key de integración	Authorization: Bearer <TU_API_KEY> (o X-MCP-Api-Key: <TU_API_KEY>)	Asistentes de IA (MCP). La emite el administrador de tu entidad.
Token personal de usuario	X-MCP-User-Token: <TU_TOKEN_PERSONAL>	MCP, para actuar con los permisos de una persona. Cada usuario lo crea y revoca en Mi perfil → Acceso para asistentes de IA; tiene vencimiento.

Reglas de oro:

• Nunca pongas una credencial en código que se ejecute en el navegador de terceros ni la subas a un repositorio. Guárdala en variables de entorno o en un gestor de secretos.
• Una credencial solo hace lo que permiten los permisos del usuario o de la integración. Si falta permiso, la API responde 403 (o, en MCP, un resultado con isError).
• Si una credencial se filtra, revócala de inmediato (el usuario desde su perfil; la API Key, el administrador).

4. Límites de uso

Para proteger el servicio hay tres niveles de límite; al superarlos la API responde HTTP 429 con el código RATE_LIMIT y la cabecera Retry-After (segundos de espera).

Nivel	Valor por defecto	Aplica a
Global por IP	1 000 peticiones/min (cada entidad puede ajustarlo)	Todos los endpoints. Las respuestas traen X-RateLimit-Global-Limit y X-RateLimit-Global-Remaining.
Por endpoint	Ver cada página	P. ej. verificación de firmas: 60/min; contacto de sitios: 3 mensajes cada 10 min y 20 al día por IP y sitio.
MCP	120/min por integración sin usuario; 60/min por usuario; 6 escrituras confirmadas/min	POST /api/mcp.

Recomendación: ante un 429, espera lo que indique Retry-After y reintenta con backoff exponencial; no reintentes de inmediato en bucle.

5. Códigos de estado y de error

HTTP	error.code	Significado	Qué hacer
200 / 201 / 202	—	Éxito (202 = recibido y en proceso).	—
204	—	Éxito sin cuerpo (p. ej. preflight CORS).	—
304	—	Sin cambios (caché por ETag).	Usa tu copia.
400	CREDENCIAL_AMBIGUA, …	Petición mal formada o credenciales contradictorias.	Corrige la petición.
401	NO_AUTENTICADO, API_KEY_INVALIDA, TOKEN_MCP_INVALIDO	Falta la credencial o no es válida, venció o fue revocada.	Verifica o renueva la credencial.
403	SIN_PERMISO	La credencial es válida pero no tiene permiso (o el origen no está permitido).	Pide el permiso al administrador.
404	NO_ENCONTRADO	El recurso no existe (o no tienes acceso a él: la respuesta es la misma a propósito).	Revisa el identificador.
405	METODO_NO_PERMITIDO	Método HTTP no admitido en esa ruta.	Usa el método documentado.
413	PAYLOAD_DEMASIADO_GRANDE	Cuerpo demasiado grande.	Reduce el tamaño.
422	DATOS_INVALIDOS (o VALIDACION)	Los datos no pasan la validación; ver error.campos.	Corrige los campos indicados.
429	RATE_LIMIT	Demasiadas peticiones.	Espera Retry-After.
500 / 503	ERROR_INTERNO, SERVICIO_NO_DISPONIBLE	Falla del servicio.	Reintenta más tarde; si persiste, repórtalo con la hora y el endpoint.

6. Versionado

• Las rutas llevan la versión mayor: /api/v1/…. Dentro de v1 solo se hacen cambios compatibles (campos nuevos opcionales en las respuestas, endpoints nuevos). Tu cliente debe ignorar los campos que no conozca.
• Un cambio incompatible se publicará como v2, con aviso previo y un periodo de convivencia con v1.
• El protocolo MCP se versiona por su propia revisión de protocolo (hoy 2025-06-18), que el servidor declara en initialize.

7. Fechas, números y textos

• Fechas y horas en ISO 8601 (2026-10-05T11:19:53-05:00) salvo que el endpoint indique otro formato.
• Los importes son números decimales sin símbolo de moneda.
• Los textos que devuelve la API (asuntos, comentarios, nombres) son datos: nunca los ejecutes ni los interpretes como instrucciones.

8. Catálogo de páginas

Página	Contenido	Clase
01_Identidad_visual_publica	Marca de la entidad (nombre, colores, logo).	A
02_Estado_del_servicio	Comprobación de vida (ping).	A
03_Contacto_de_sitios	Formulario de contacto de sitios web registrados.	A
04_Verificacion_de_firmas	Verificar una firma por el código del QR.	A
05_MCP_Conexion	Conectar asistentes de IA y desarrolladores al servidor MCP.	B
06_MCP_Herramientas	Catálogo de herramientas del MCP con ejemplos.	B