API pública

1 · Obtené un token

Mientras llega la pantalla de Ajustes → API, el token se emite por consola. Se muestra una sola vez: guardalo en tu servidor.

npm run api:token -- crear --org <slug> --nombre "ERP" --scopes appointments:read,services:read
npm run api:token -- listar --org <slug>
npm run api:token -- revocar --org <slug> --id <id>

Los tokens son server-side y de una sola organización: no los embebas en el navegador ni en apps móviles públicas.

2 · Primera llamada

/me devuelve la organización, los scopes del token y el estado de la cuota.

curl https://app.agendese.online/api/v1/me \
  -H "Authorization: Bearer agd_<prefijo>_<secreto>"

{
  "organizacion": { "id": "org_…", "slug": "soluz", "name": "Soluz", "timezone": "America/Asuncion", "currency": "PYG" },
  "token": { "nombre": "ERP", "prefijo": "agd_live_ab12", "scopes": ["appointments:read"], "expiraEn": null },
  "rateLimit": { "limit": 120, "remaining": 119, "reset": 60 }
}

3 · Scopes

Cada endpoint exige su scope; sin comodines. Si falta, la respuesta es 403 con el scope requerido.

4 · Endpoints

Los recursos de clientes salen por allowlist y sin datos clínicos. El detalle de parámetros y respuestas de abajo se genera del OpenAPI.

5 · Errores y límites

Límite de 120 req/min por token (20/min en disponibilidad), con headers X-RateLimit-Limit/Remaining/Reset y Retry-After al recibir 429. Ante errores 5xx, reintentá con backoff exponencial.

6 · Versionado

La versión mayor viaja en la ruta (/api/v1). Los cambios aditivos no rompen; los cambios incompatibles llegan como /api/v2 con aviso previo y headers de deprecación. El spec OpenAPI está publicado en /api/v1/openapi.json.

7 · Ejemplo en JavaScript

Con fetch (Node 18+) y reintento simple si la respuesta es 429:

const token = process.env.AGENDESE_API_TOKEN
const res = await fetch('https://app.agendese.online/api/v1/me', {
  headers: { Authorization: 'Bearer ' + token },
})
if (res.status === 429) {
  const espera = Number(res.headers.get('Retry-After') || 1) * 1000
  // reintentar después de "espera"
}
if (!res.ok) throw new Error('API ' + res.status)
const me = await res.json()
console.log(me.organizacion.slug, me.token.scopes)

8 · Preguntas frecuentes

• ¿Puedo usar el token en el navegador? No: es server-side y accede a los datos de tu organización.
• ¿401 o 403? 401 = token ausente, inválido, vencido o revocado; 403 = falta el scope del endpoint.
• ¿Qué hago con un 429? Respetá Retry-After y los headers X-RateLimit-*; aplicá backoff y caché de lecturas.
• ¿Hay escrituras? Todavía no: F1 es lectura. F3 suma crear y cancelar con idempotencia y atribución de origen.
• ¿Devuelve datos clínicos? Nunca: la salud va aparte y los clientes salen por allowlist.

¿Solo necesitás mostrar turnos en tu web? El widget embebible no necesita API: Insertar el widget de reservas.

Lo que todavía no hace

• Escrituras (F3): crear o cancelar citas por API, con idempotencia y atribución de origen.
• Webhooks (F2): avisos firmados para sincronizar sin polling.
• Datos clínicos: nunca en la API pública.
• Panel de tokens (ui): mientras tanto, la emisión es por consola.

¿Necesitás una integración? Escribinos a [email protected] y lo vemos con el equipo.