API pública: claves, scopes y escenarios
La API pública te permite gestionar la promoción desde tu sistema: crear proyectos, añadir páginas, lanzar cascadas, obtener informes, así como trabajar con comprobaciones de posiciones, auditorías y escaneos de seguridad.
Documentación
La guía completa con parámetros y ejemplos de solicitudes está disponible en una página aparte y siempre corresponde a la versión actual. Aquí solo encontrarás una visión general.
Claves y permisos
- La clave se emite en el panel, en la sección "API para desarrolladores", y se envía en el encabezado de autorización.
- La clave tiene scopes: conjuntos de permisos. Hay cuatro: promotion, rank, audit, shield. Emite solo lo que realmente necesites.
- La clave se puede revocar en cualquier momento; las solicitudes antiguas con ella dejarán de funcionar de inmediato.
- Existe un límite en la frecuencia de solicitudes; las estadísticas de llamadas y gastos por clave se ven en el panel.
Qué está disponible por API
| Grupo | Funciones | Scope |
|---|---|---|
| Cuenta | Perfil, saldo, descuento personal, información de la clave | no se requiere |
| Proyectos y enlaces | Creación de proyectos, adición y eliminación de páginas | promotion |
| Promoción | Tarifas, precálculo, lanzamiento de una cascada, estado y lista de publicaciones | promotion |
| Informes y marca | Informe en JSON o PDF, ajustes de marca blanca (solo Pro) | promotion |
| Rank Tracker | Proyectos, palabras clave, configuración de comprobaciones de posiciones | rank |
| SEO Audit | Estimación del tamaño del sitio, rastreo exprés y completo, resultados con Health Score | audit |
| Shield | Verificación de dominio, lanzamiento de escaneos, veredicto | shield |
La personalización de marca en los informes no es un scope aparte: está incluida en promotion y requiere una suscripción Pro activa.
Escenario típico
- Crea un proyecto y añade páginas.
- Solicita el cálculo del costo para la configuración de cascada que desees.
- Lanza la promoción y guarda el ID del lanzamiento.
- Consulta el estado periódicamente y, al finalizar, solicita un informe con las publicaciones.
El precálculo devuelve el importe con descuento y el saldo actual, por lo que el precio se puede mostrar antes del cargo; cómo se compone se explica en el artículo tarifas y precio. El informe solo devuelve las publicaciones confirmadas, igual que en el panel: los valores de los estados se explican en el artículo informe y estados.
Límites y códigos de respuesta
| Situación | Respuesta | Qué hacer |
|---|---|---|
| Clave no proporcionada, no encontrada o revocada | 401 | Revisa el encabezado de autorización y la clave |
| La clave no tiene el scope necesario | 403 | Emite una clave con los permisos necesarios |
| Fondos insuficientes para el lanzamiento | 402 | La respuesta incluirá el importe requerido, el saldo, el faltante y un enlace para recargar |
| Error en los parámetros o dominio ajeno en el enlace | 422 | En la respuesta se indica el campo con el error |
| Demasiadas solicitudes | 429 | Reintenta después del número de segundos indicado en la respuesta; el límite se cuenta por clave |
| Servicio desactivado temporalmente | 503 | Reintenta más tarde: el lanzamiento no se realizó y no se descontó dinero |
Las listas se devuelven paginadas: no más de 100 elementos por página. La lista completa de códigos está disponible en la guía.
Errores comunes de integración
- Relanzar el mismo enlace. Mientras haya una cascada activa en curso, no se crea una nueva: la respuesta indicará "already active". Esto no es un fallo, no hace falta repetir la solicitud en bucle.
- Auditoría completa sin express, análisis de Shield sin verificación del dominio. Ambas acciones requieren un paso previo, de lo contrario se devolverá un error.
- Consultas de estado demasiado frecuentes. La cascada dura horas: preguntar más de una vez cada pocos minutos no tiene sentido, y es fácil alcanzar el límite de frecuencia.
- Saldo vacío en el momento del lanzamiento. Es posible que el precálculo se haya hecho ayer y que el dinero se haya destinado a otros lanzamientos: mantén una reserva, consulta saldo y recargas.
White-label mediante API
Los suscriptores Pro pueden configurar un logotipo, el nombre de la empresa y un color: así los informes obtenidos mediante la API llevarán tu marca. Más detalles en el artículo sobre White-label.
El servidor solo almacena el hash de la clave, no es posible mostrar de nuevo la clave emitida: guárdala de inmediato. Si la perdiste o quedó expuesta en un repositorio: revoca la anterior y emite una nueva, esto no afecta a las cascadas ya lanzadas.
