Referencia de la API

Forklink todavía no tiene API abierta. Esta es la API del producto de enlaces sobre el que se construye; la dirección pública de Forklink (prevista en api.forklink.co) no existe aún. Los nombres de rutas, campos y códigos de abajo son los del OpenAPI desplegado en staging y pueden cambiar antes del lanzamiento.

• Llave: cabecera Authorization: Bearer cl_live_… (en staging, cl_test_…). Las llaves se crean en el panel de Links del workspace, no por la API: una llave no puede crear llaves (probado: 403).
• Permisos: full, read (solo GET) y track (solo /track/*, para el servidor de tu sitio). Probado: una llave read lee (200) y no escribe (403).
• Ritmo: el OpenAPI declara 20 peticiones por segundo por llave con ráfaga de 40; al pasarse, 429 con retry-after. Observado en staging: con 300 peticiones paralelas, 140 recibieron 429 (retry-after 1).
• Cuentas nuevas: si la política de cuentas nuevas está activa (lo está en staging), no se pueden crear llaves ni dominios propios hasta verificar la cuenta (403 ACCOUNT_NOT_VERIFIED).
• Servidor base: /api sobre el host de la API.

Ejecutados el 2026-11-09 contra Links staging (OpenAPI versión 2026-09-18) con una llave cl_test_… de un tenant de pruebas: 17 de 18 comprobaciones correctas; las llaves y el enlace de prueba se borraron al terminar.

# Listar
curl -s "$BASE/links?limit=5" -H "Authorization: Bearer $KEY"

# Crear
curl -s -X POST "$BASE/links" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"destinationUrl":"https://example.com/launch","slug":"launch","title":"Launch","utmSource":"newsletter","utmMedium":"email","utmCampaign":"launch"}'

# Analítica de los últimos 7 días
curl -s "$BASE/links/$ID/analytics?days=7" -H "Authorization: Bearer $KEY"

# Borrar
curl -s -X DELETE "$BASE/links/$ID" -H "Authorization: Bearer $KEY"

Sustituye $BASE por el servidor de la API (https://<host>/api), $KEY por tu llave e $ID por el id devuelto al crear. Respuestas verificadas: el listado devuelve {items, limit, page, total}; crear devuelve el enlace (201) con id, slug, domain, destinationUrl, status, totalClicks…; la analítica devuelve totalClicks, uniqueClicks, timeseries, byCountry, byReferrer…; borrar responde 204.

Los errores son {"error": "…", "code": "…"}. Verificados en staging: 400 INVALID_BODY (con details), 401 MISSING_API_KEY, 403 FORBIDDEN (permiso insuficiente) y 429 con retry-after.

402 (límites del plan): construido, no verificado. Según el diseño de medidores, al llegar al tope de enlaces activos o dominios propios la API responde 402 con COMMERCIAL_LIMIT_REACHED (LINKS_ACTIVE_LIMIT_REACHED o CUSTOM_DOMAINS_LIMIT_REACHED, con limit y current); los enlaces ya publicados siguen redirigiendo. Ese código aterrizó pero el servicio desplegado en staging es anterior (el OpenAPI desplegado no lo lista): no lo pude probar. Al superar los clics del mes no hay 402: la redirección sigue y el detalle de analítica del exceso deja de guardarse. Los topes por plan no están aprobados para producción.

Eventos: link.created, link.updated, link.archived, link.clicked, link.click_limit_reached, link.expired, conversion.lead, conversion.sale, domain.verified, app.opened, app.installed. Firma estilo Svix (webhook-id, webhook-timestamp, webhook-signature: v1,<base64 HMAC-SHA256> sobre {id}.{ts}.{body}), hasta 8 reintentos con espera creciente; el endpoint se desactiva tras 50 fallos seguidos. Fuente: OpenAPI y código de Links; no los probé de extremo a extremo en esta entrega.

• GET /status.json figura como pública bajo /api, pero allí pide llave (401): la ruta pública es /status.json en la raíz del host.
• GET /links/{id}/qr respondió 500 INTERNAL_ERROR en staging el 2026-11-09: no lo incluyo en los ejemplos probados. El QR de la herramienta gratuita de este sitio no depende de la API.

Links

Analytics

Conversions

Domains

UTM presets

Tags

Groups

QR

Link-in-bio

Webhooks

Integrations

Mobile apps

Status

Deep links