Ir al contenido
SEO Uptr
SEO UptrRegistrarse

Referencia

Referencia de la API de backlinks: acciones, costes y errores

Una página con los datos que necesita un monitor: cuánto cuesta cada acción, cómo funciona la paginación y qué hace la API cuando algo sale mal.

Puente de piedra sobre un río con un pequeño barco navegando debajo

Acciones por coste en créditos

1 crédito = $0.0001. Cada llamada se factura una sola vez independientemente del número de filas, hasta 1.000 filas por llamada.
CosteAccionesNotas
Gratis, sin clavedomain, overview, stats, suggestAdecuado para paneles de control y el comprobador de DR
1 créditobulk_dr, compare, top, dr_distribution, tld_breakdownbulk_dr acepta hasta 2.000 dominios (GET domains= o cuerpo POST); compare hasta 20
2 créditosrefdomains, backlinks, anchors, toppages, anchor_cloud, intersectintersect requiere de 2 a 10 dominios
3 créditossearch, keywordBúsqueda de texto completo en anclas, títulos y URLs; keyword encuentra quién está enlazado con una ancla exacta

Autenticación y códigos de estado

Pasa la clave como key= o como cabecera bearer. Comprueba el código HTTP antes de analizar el cuerpo.

bash
# header style
curl -s -H "Authorization: Bearer sk_live_..." \
  "https://seouptr.com/api.php?action=anchors&q=yourdomain.com&per=100"

# a cron-safe wrapper
code=$(curl -s -o out.json -w '%{http_code}' "$URL")
case "$code" in
  200) jq '._credits' out.json ;;      # cost and remaining balance
  401) echo 'bad or missing key' ;;
  402) echo 'out of credit: top up' ;;
  *)   echo "unexpected $code" ;;
esac

Parámetros y errores

ElementoValorSignificado
qun dominioEl objetivo de la búsqueda
page, perper de 10 a 5000Paginación; las filas por llamada están limitadas a 1.000, la paginación profunda a 50.000
sort, orderorder=asc o descOrdenación de las filas devueltas
oken cada respuestaIndica si la llamada tuvo éxito
_creditssolo en respuestas autenticadasCoste de la llamada y saldo restante
HTTP 401clave faltante o incorrectaComprueba la clave o la cabecera
HTTP 402créditos agotadosRecarga con USDT (TRC-20)
Carpintero midiendo madera y seleccionando herramientas en un banco de taller

Diseñar la llamada antes de programarla

La mayoría de los problemas de la API comienzan en la solicitud, no en la respuesta. Una integración de la API de backlinks de SEO es principalmente un conjunto de pequeñas decisiones tomadas antes de la primera llamada. Establece primero la clave, el tamaño de página y el orden de ordenación.

Mantén la clave fuera del script

Almacena la clave en una variable de entorno o en un almacén de secretos, no en un archivo que hagas commit. Pásala como el parámetro key o como una cabecera bearer. La cabecera mantiene la clave fuera de las direcciones que tienden a terminar en los registros.

No pegues una clave activa en un ticket o en un chat. Trata una que aparezca en un registro compartido como expuesta.

Elige el tamaño de página a propósito

El parámetro per va de 10 a 5000, pero una llamada se factura una sola vez por hasta 1.000 filas, por lo que páginas más grandes significan menos cargos. Digamos que necesitas 3.400 filas. Eso requiere cuatro llamadas de 1.000 filas, no 340 llamadas de 10.

Mantén el tamaño de página igual en todas las ejecuciones para que los archivos coincidan.

Fija el orden de ordenación

Establece sort y order explícitamente en lugar de confiar en un valor predeterminado. Parámetros idénticos hacen que la salida sea comparable de semana a semana, de modo que un diff muestre un cambio real y no filas reordenadas.

Un cambio en el orden es una forma fácil de crear una alarma falsa.

Lectura de los números

Los datos son nuestro propio grafo de enlaces: 181.132.097 dominios, 2.774.625.913 enlaces entre dominios y aproximadamente 798,5 mil millones de backlinks. Se actualiza aproximadamente una vez al mes. Cualquier dato más reciente que eso no estará en él, por lo que una seo backlinks api es mejor consultarla semanalmente.

DR es round(100 · log(ref_domains+1) / log(2·10^7)). Es un logaritmo. Debido a eso, 100 dominios de referencia puntúan 27, 1.000 puntúan 41 y 10.000 puntúan 55, por lo que duplicar tu conteo de enlaces añade solo unos pocos puntos. Usa DR para clasificar sitios entre sí y el conteo crudo para alertas, como hace la tabla de severidad.

La facturación es prepagada. No hay suscripción ni mínimo. El crédito de registro es $100, que equivale a 1.000.000 de créditos. Compara eso con las unidades de la API de Ahrefs, vendidas dentro de planes desde $129/mes por 200.000 unidades, con al menos 50 unidades por solicitud.

La planificación de costos es una simple multiplicación. Una llamada semanal a refdomains para un sitio son 2 créditos por 4, o 8 créditos al mes, lo que equivale a $0,0008. Diez sitios cuestan diez veces eso. La receta de enlaces perdidos y el trabajo de competidor usan solo acciones de la tabla anterior.

Lectura de un error sin adivinar

Un código de error te dice quién debe actuar. Léalo de esa manera. La respuesta se convierte entonces en una decisión de enrutamiento, no en un misterio. Los dos códigos que más importan para un monitor son 401 y 402.

401 y 402 son problemas diferentes

Un 401 significa que la clave falta o es incorrecta, y nada tendrá éxito hasta que alguien lo arregle. Un 402 significa que la cuenta se quedó sin crédito, y una recarga lo soluciona. Enruta ambos a diferentes propietarios para que la persona adecuada vea el mensaje.

Envía ambos a una persona. Un monitor que falla en silencio es peor que uno que nunca se ejecutó.

Verifica el estado antes del cuerpo

Lee el estado HTTP primero y el campo ok segundo. Una respuesta puede analizarse como JSON y aún así contener un fallo, por lo que la verificación está completa solo cuando ambas pasan. Registra el estado en cada ejecución, incluso las exitosas.

Reintenta solo lo que puede recuperarse

Reintentar un 401 desperdicia llamadas y llena los registros con el mismo fallo. Un tiempo de espera de red es diferente. Reinténtalo un número pequeño de veces con una pausa entre intentos, luego detente.

Una ejecución que se detiene y alerta es más útil que un bucle de reintento que oculta el fallo hasta que se agote el saldo.

Registra el estado en cada ejecución

Escribe el estado HTTP y el saldo en el registro en cada ejecución, incluyendo las exitosas. Cuando una ejecución falle tres semanas después, esa línea será lo primero que querrás ver.

Acciones gratuitas primero

domain, overview, stats y suggest no necesitan clave y cuestan cero. Úsalos para verificar la validez de un nombre de dominio, una ortografía exacta o un tamaño aproximado antes de gastar un solo crédito en una acción de pago.

Antes de poner una llamada en cron

  • El costo de la acción es conocido y se multiplica por las ejecuciones por mes.
  • Se verifican tanto el código de salida como el estado HTTP.
  • Un 402 envía una alerta a un humano.
  • Las respuestas se guardan ordenadas, para que los diffs se mantengan limpios.
  • La cadencia coincide con la actualización mensual.
Jardinero organizando plantas en filas ordenadas en un jardín

Notas sobre paginación

El orden importa. Usa per=1000 para instantáneas y mantén el mismo sort y order cada semana. Si el orden cambia entre ejecuciones, un diff mostrará ruido. Esa es una causa clásica de alarmas falsas.

Sitios más grandes? Para un sitio con más de 1.000 dominios de referencia, navega por las páginas con page=1, page=2 y así sucesivamente. Cada página es una llamada facturada por separado. La paginación profunda está limitada a 50.000 filas, lo que cubre casi todos los sitios ordinarios.

Preguntas sobre la referencia

¿Qué acción debo llamar primero cuando no estoy seguro de cómo se ve un dominio?
Comienza con overview o domain. Ambas son gratuitas y no necesitan clave, y muestran un tamaño aproximado y la forma básica de los datos. Gasta créditos en refdomains o anchors solo después de eso.
¿Cuánto cuesta una verificación completa de un dominio?
Suma los créditos de cada acción, luego multiplica por la frecuencia de ejecución. Imagina una llamada a refdomains, una llamada a anchors y una llamada a tld_breakdown en un dominio, semanalmente. Eso son 2 + 2 + 1 = 5 créditos por ejecución, o $0,0005. En cuatro semanas asciende a aproximadamente $0,002.
¿Por qué podrían no coincidir dos conteos para el mismo dominio?
Compara lo similar con lo similar: la misma acción, los mismos parámetros y el mismo período de actualización. Los conteos de diferentes acciones no son intercambiables, y un conteo tomado a mitad de una actualización puede diferir de uno tomado una semana después.
¿Cómo pruebo un trabajo cron sin gastar créditos?
Ejecuta primero las acciones gratuitas para verificar el cableado, el manejo de estados y el formato de salida. Luego haz una llamada pagada para demostrar los números, y limita el trabajo a una sola ejecución mientras pruebas.
¿Funciona la paginación para un sitio con más de 1.000 dominios de referencia?
Sí. Usa page con per. Cada página es una llamada facturada por separado, y la paginación profunda está limitada a 50.000 filas, lo que cubre la mayoría de los sitios ordinarios.

Un monitor que sobrevive a una semana mala

Un monitor gana confianza en las semanas cuando nada sale bien. Planifica para una respuesta lenta, un saldo cambiado y un resultado parcial antes de la primera ejecución. Esos son eventos ordinarios. Cada uno debe dejar una línea clara en el registro.

Timeouts y extracciones parciales

Establece un timeout en cada llamada, para que una respuesta lenta no pueda mantener abierto todo el trabajo. Si una página de una extracción de múltiples páginas falla, registra qué página fue y reinicia desde allí. Así evitas pagar dos veces por filas que ya tienes.

Marca un archivo parcial como parcial en lugar de guardarlo como una instantánea normal. De lo contrario, el próximo diff mostrará una pérdida que nunca ocurrió.

Verificaciones de saldo

Lee _credits en cada respuesta autenticada y escribe el saldo restante en el registro. Un pequeño script puede compararlo con un piso que elijas y enviar una advertencia antes de la próxima ejecución.

Digamos que el piso es 500 créditos. Una ejecución semanal que cuesta 40 créditos deja margen para recargar antes de que llegue un 402 en medio de la noche.

Mantén cada trabajo aburrido

Dale a cada trabajo un archivo y un horario. Una entrada cron que hace tres cosas puede fallar de tres maneras, y el registro no siempre puede decir cuál ocurrió. Dos trabajos pequeños son más fáciles de confiar que uno inteligente.

Ajusta el horario a la actualización

Ajusta el horario del trabajo a la actualización mensual en lugar de al reloj. Una ejecución diaria devuelve el mismo archivo la mayoría de los días, lo que añade costo y ruido sin añadir información. Semanalmente suele ser suficiente.