Claves de API y guía rápida del SDK

La API de Elido es REST + JSON, está documentada con OpenAPI 3.1 y tiene límite de tasa por clave. Ofrecemos SDK propios para TypeScript, Go y Python que la envuelven. El servidor MCP de @elido/mcp-server expone la misma superficie a los agentes de IA.

Emitir una clave de API

1. Settings → API keys → Create key.
2. Elige un nombre (recomendamos el del sistema que la va a usar: zapier, internal-billing, marketing-cli).
3. Elige los scopes. Los cuatro habituales:
   • links:read: listar e inspeccionar enlaces.
   • links:write: crear, actualizar y eliminar enlaces.
   • analytics:read: consultar eventos de clic.
   • webhooks:write: gestionar suscripciones de webhooks.
4. Pulsa Create. La clave se muestra una sola vez: solo guardamos un hash.

Si pierdes una clave, revócala desde la misma página y emite una nueva. Las claves revocadas se rechazan en un plazo de 60 segundos en todas las regiones.

Guía rápida con el SDK de TypeScript

import { ElidoClient } from "@elido/sdk";

const client = new ElidoClient({ apiKey: process.env.ELIDO_API_KEY! });

const link = await client.links.create({
  destination: "https://acme.com/spring-sale",
  slug: "spring-2026",
});

console.log(link.short_url);

Los SDK de Go y Python siguen la misma forma. Referencia completa en /api.

Guía rápida con curl

curl -X POST https://api.elido.app/v1/links \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://acme.com/spring-sale","slug":"spring-2026"}'

Límites de tasa

El plan gratuito tiene 60 peticiones por minuto por clave. Pro: 600/min. Business: 6000/min. El burst es 2 veces el límite en régimen estable; la cabecera de respuesta X-RateLimit-Remaining indica cuánto te queda.

Si alcanzas el límite, la API devuelve 429 con Retry-After. Los SDK implementan por defecto reintentos con backoff exponencial: desactívalo si tu aplicación gestiona su propia política de reintentos.

Idempotencia

Los endpoints que modifican datos aceptan una cabecera Idempotency-Key. Pasa un UUID por cada escritura prevista; guardamos la respuesta en caché durante 24 horas para que los reintentos (errores de red, timeouts ambiguos) no creen duplicados.

Los SDK añaden la cabecera automáticamente. Si usas curl directamente, genera la clave en el cliente e inclúyela en cada reintento.

Webhooks

Para recibir notificaciones en tiempo real en lugar de hacer polling, configura webhooks en Settings → Webhooks: entregamos eventos como link.created, link.updated y domain.verified con firmas HMAC. Los eventos por clic todavía no están disponibles; consulta la guía de webhooks para ver la lista completa.