📘

Documentación de la API

Esta página describe la API de ShortBoost para asistentes de IA y automatizaciones. Puedes crear una clave en Claves de API.

Fundamentos

Dirección: https://api.shortboost.one/api/v1
Autenticación: cabecera Authorization: Bearer sbo_live_… (nunca como parámetro de URL)
Formato: JSON; en POST/PATCH, con Content-Type: application/json
Límite: 60 solicitudes por minuto y clave
Primera llamada: GET /key-info muestra la cuenta, el plan, los permisos y el número de enlaces

curl -H "Authorization: Bearer sbo_live_…" https://api.shortboost.one/api/v1/key-info

Enlaces

Llamada	Permiso	Finalidad
`GET /links`	links.read	Lista. Parámetros: `page`, `limit` (máx. 100), `search`, `project_id`, `category_id` (`none` = sin), `favorite=true`, `sort` (`created_desc`, `created_asc`, `clicks_desc`, `clicks_asc`, `name_asc`, `name_desc`)
`GET /links/{id}`	links.read	un enlace
`GET /links/check-slug/{slug}`	links.read	¿está libre la dirección corta? `{"available":true}`
`GET /links/{id}/qr`	links.read	Código QR. Parámetros: `format=png\|svg`, `size` (100–1000), `color`, `bg` (hex sin #)
`POST /links`	links.write	crear. Obligatorio: `original_url`. Opcional: `slug`, `title`, `name`, `notes`, `tags` (lista), `project_id`, `category_id`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `expires_at`, `click_limit`, `password`, `smart_routing` (lista de reglas, ver abajo)
`PATCH /links/{id}`	links.write	modificar, los mismos campos que al crear, más `is_active`, `is_favorite`
`POST /links/bulk`	links.write (para `delete`, también links.delete)	`{"action":"activate\|deactivate\|move\|categorize\|favorite\|delete","link_ids":[…],"payload":{…}}`, máx. 500 enlaces
`DELETE /links/{id}`	links.delete	eliminar

curl -X POST https://api.shortboost.one/api/v1/links \
  -H "Authorization: Bearer sbo_live_…" \
  -H "Content-Type: application/json" \
  -d '{"original_url":"https://example.com/angebot","title":"Herbstangebot","utm_source":"newsletter"}'

Respuesta (abreviada):

{"link":{"id":"…","slug":"aB3xY9","short_url":"https://shlk.one/aB3xY9","original_url":"https://example.com/angebot","title":"Herbstangebot","click_count":0,"has_password":false,"smart_routing":[],"is_active":true,"created_at":"…"}}

Enrutamiento inteligente (`smart_routing`)

Con el enrutamiento inteligente, un enlace dirige a los visitantes a otro destino según el país, el idioma, el sistema operativo o el dispositivo. Las reglas se comprueban de arriba abajo y gana la primera que coincida. Si ninguna coincide, se aplica original_url. Más información en el artículo Enrutamiento inteligente. Solo en los planes Pro y Lifetime (si no, 402).

Campo por regla	Significado
`url`	Obligatorio. Destino de esta regla, `http://` o `https://`
`name`	opcional, máx. 60 caracteres (aparece en las estadísticas)
`country`	Países como código ISO en mayúsculas, p. ej. `["AT","DE","CH"]`
`language`	Idioma del navegador como código ISO en minúsculas, p. ej. `["de","en"]`
`os`	`ios`, `android`, `windows`, `macos`, `linux`
`device`	`mobile`, `tablet`, `desktop`
`id`	lo asigna el servidor. En reglas nuevas, omítelo; en las existentes, envíalo sin cambios; si no, las estadísticas de esa regla empiezan de nuevo

Cada regla necesita una url y al menos una condición. Entre condiciones rige Y, entre varios valores de una condición rige O. Una condición vacía significa "cualquiera".
Como máximo 10 reglas por enlace. El orden de la lista es el orden de comprobación.
PATCH con smart_routing sustituye todas las reglas. [] o null elimina todas las reglas. Sin el campo, permanecen sin cambios.
En las respuestas, smart_routing es siempre una lista; sin reglas aparece como [].

Ejemplo: un enlace de aplicación que envía los iPhone a la App Store y los dispositivos Android a Google Play. Todos los demás van a la página web.

curl -X PATCH https://api.shortboost.one/api/v1/links/{id}   -H "Authorization: Bearer sbo_live_…"   -H "Content-Type: application/json"   -d '{"original_url":"https://example.com/app",
       "smart_routing":[
         {"name":"iPhone","url":"https://apps.apple.com/app/id123456789","os":["ios"]},
         {"name":"Android","url":"https://play.google.com/store/apps/details?id=com.example.app","os":["android"]}
       ]}'

Estadísticas

Llamada	Finalidad
`GET /analytics/overview?days=30`	Clics totales, enlaces, enlaces con más clics
`GET /analytics/dashboard`	Métricas, clics por día, navegadores, fuentes, dispositivos, países. Parámetros `from`, `to` (fecha ISO)
`GET /analytics/links/{id}`	Análisis de un enlace, los mismos parámetros. Contiene `routing`: clics por regla de enrutamiento inteligente, p. ej. `[{"route_id":"a1b2c3d4e5","clicks":12},{"route_id":null,"clicks":40}]`. `route_id` es el `id` de la regla, `null` significa: ninguna regla coincidió (destino normal)
`GET /analytics/clicks?days=30`	Clics a lo largo del tiempo
`GET /analytics/geo?days=30`	Países y ciudades
`GET /analytics/devices?days=30`	Dispositivos, navegadores, sistemas operativos
`GET /analytics/utm?days=30`	Fuentes, medios y campañas UTM
`GET /analytics/heatmap`, `/analytics/heatmap/{id}`	Clics por día de la semana y hora

Todas las llamadas de estadísticas requieren stats.read.

Proyectos y categorías

Llamada	Permiso
`GET /projects`, `GET /categories` (opcional `?project_id=`)	projects.read
`POST /projects` `{"name":"…","color":"#1a56db"}`, `POST /categories` `{"name":"…","project_id":"…"}`	projects.write
`PATCH /projects/{id}`, `PATCH /categories/{id}`	projects.write
`DELETE /projects/{id}` (los enlaces pasan al proyecto predeterminado), `DELETE /categories/{id}`	projects.delete

Errores

Estado	Respuesta	Significado
401	`{"error":"invalid_key"}`	La clave es incorrecta, está revocada o caducada, o la llamada no es accesible a través de la API
402	`{"error":"plan_required"}`	La cuenta no tiene (o ya no tiene) un plan Pro o Lifetime
403	`{"error":"missing_scope","required":"links.write"}`	a la clave le falta este permiso
429	`{"error":"rate_limited"}`	más de 60 solicitudes por minuto; la cabecera `Retry-After` indica el tiempo de espera en segundos
400, 404, 409	`{"error":"…"}`	error funcional con texto en alemán, p. ej. "Slug bereits vergeben"

Instrucción para una IA

Controlas mi acortador de enlaces ShortBoost a través de la API https://api.shortboost.one/api/v1
con la cabecera "Authorization: Bearer <CLAVE>". Documentación: https://shortboost.one/help/api-dokumentation
1. Llama primero a GET /key-info y comprueba tus permisos.
2. Crea enlaces con POST /links y devuélveme la short_url.
3. No elimines nada sin mi confirmación expresa.
4. Si recibes un 429, espera los segundos indicados en la cabecera Retry-After.

‹ Volver al centro de ayuda