API de PUC Colombia

Quickstart (60 segundos)

1. Crea una cuenta e inicia sesión.
2. Genera tu API key en tu perfil → API. El plan gratuito da 3 solicitudes/día.
3. Llama a la API con la cabecera x-api-key:

curl 'https://puccol.com/api/v1/cuentas?q=caja&limit=5' \
  -H 'x-api-key: pucol_live_xxx'

Recursos

• Especificación OpenAPI 3.1: https://puccol.com/openapi.json — úsala para generar SDKs o para el function-calling de un LLM.
• Referencia interactiva: /api-docs (endpoints, parámetros y ejemplos).
• Servidor MCP (Model Context Protocol, Streamable HTTP): https://puccol.com/mcp — tools de solo lectura para Claude, ChatGPT y otros agentes.
• Autenticación para agentes: /auth.md — API key y OAuth 2.1 (PKCE).
• Skills: /.well-known/agent-skills/index.json.

Autenticación

Envía tu llave en la cabecera x-api-key o como Authorization: Bearer <token>. Además de las API keys, la API acepta tokens OAuth 2.1 emitidos por nuestro proveedor de identidad (flujo authorization code con PKCE). Los detalles y el descubrimiento están en /auth.md y en /.well-known/oauth-protected-resource. No expongas tu llave en código cliente público.

Planes y límites

La cuota se cuenta por día calendario UTC. Cada respuesta incluye las cabeceras RateLimit, RateLimit-Policy y X-RateLimit-*; un 429 incluye Retry-After. Precios en /pricing.

Entorno de pruebas (sandbox)

El plan Free funciona como sandbox: sirve exactamente los mismos datos que producción con una cuota reducida (3 req/día), sin operaciones de escritura (la API es de solo lectura), para que puedas probar una integración o un agente sin riesgo.

Versionado y deprecación

La versión va en la ruta (/api/v1). Un cambio incompatible estrena una versión nueva; una operación en retiro se anuncia con las cabeceras Deprecation y Sunset con al menos 6 meses de preaviso. Los errores usan el modelo común { "error": { "code", "message" } }.

Errores

• 400 parámetro inválido · 401 llave ausente/ inválida · 402 el plan no incluye API
• 404 no encontrado · 429 cuota superada (ver Retry-After) · 500 error interno

Soporte: contacto@puccol.com.