API de cliente de FastDDNS

Descripción general

La API de cliente de FastDDNS permite que cualquier dispositivo compatible con HTTP — routers, cámaras IP, scripts o software dedicado de actualización — mantenga tu hostname DNS apuntando a tu dirección IP actual. La API sigue un diseño sencillo basado en solicitudes GET: tu cliente envía las credenciales y un hostname, y el servidor responde con un breve código de estado que indica el resultado.

El servidor detecta automáticamente la dirección IP pública del cliente a partir de la conexión entrante. No se necesitan parámetros adicionales para especificar tu IP.

Autenticación

La API admite dos métodos de autenticación. Ambos se aceptan por igual; elige el que sea más fácil de configurar en tu dispositivo o router.

Método 1 — Autenticación básica HTTP (incrustada en la URL)

Las credenciales se incrustan en la URL mediante el formato estándar user:password@host. Esto es compatible con routers, cámaras y bibliotecas de clientes HTTP. Usa la clave del cliente Updater de tu panel como contraseña.

Método 2 — Parámetros de cadena de consulta

Las credenciales se transmiten como parámetros de consulta junto con hostname. Esto es útil para dispositivos y firmware que no pueden configurar cabeceras HTTP Basic Auth, pero permiten una cadena de URL totalmente personalizada.

Ejemplo con autenticación mediante cadena de consulta:

Realizar actualización

Envía una única solicitud GET para actualizar la dirección IP de un hostname registrado en tu cuenta. Cada solicitud actualiza un hostname a la vez.

Endpoint

Formato de URL — Método 1: autenticación básica HTTP

Formato de URL — Método 2: cadena de consulta

Parámetros de consulta

Ejemplos de solicitudes

Método 1 — Autenticación básica HTTP sobre HTTPS:

Método 2 — Cadena de consulta sobre HTTPS:

Uso de HTTP simple (solo para pruebas o redes de confianza):

Códigos de retorno

Todas las respuestas de actualización devuelven el estado HTTP 200 OK con un cuerpo de texto plano. Tu cliente debe analizar este cuerpo de texto para determinar el resultado real de la actualización.

Resumen de la respuesta

Obtener la IP del cliente

FastDDNS proporciona un endpoint de utilidad sencillo que devuelve la dirección IP pública tal como la ve el servidor. Esto resulta útil para la depuración, para verificar desde qué IP envía datos tu dispositivo o para utilizarlo en scripts personalizados antes de llamar al endpoint de actualización.

Endpoint

Respuesta

Devuelve HTTP 200 OK con la dirección IP pública detectada como texto plano en el cuerpo de la respuesta.

# Example response body
203.0.113.45RESPONSE

Ejemplos de solicitudes

Usando curl:

curl https://client.fastddns.net/dyndns/getipSHELL

Ejemplos de código

Shell / cURL

# Recommended: let curl build the Authorization header (-u), so the
# credentials never appear in the URL.
HOSTNAME="myhome.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}"
# Legacy form, for devices that can only be given one URL field:
curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}"
# Check what IP the server sees from your device
curl -s "https://client.fastddns.net/dyndns/getip"SHELL

Python

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "YOUR_UPDATE_USERNAME"
USER_PASS = "YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
resp = requests.get(
    "https://client.fastddns.net/",
    auth=(USER_NAME, USER_PASS),
    params={"hostname": HOSTNAME}
)
# Method 2: Query string
# resp = requests.get("https://client.fastddns.net/", params={
#     "hostname": HOSTNAME, "user_name": USER_NAME, "user_pass": USER_PASS
# })
body = resp.text.strip()
if body.startswith("good"):
    print(f"Updated successfully: {body}")
elif body.startswith("nochg"):
    print(f"No change needed: {body}")
elif body == "badauth":
    print("Authentication failed. Check credentials.")
elif body == "nohost":
    print("Hostname not found.")
elif body == "911":
    print("Server error. Try again later.")PYTHON

PHP

<?php
$hostname  = 'testhost.fastddns.org';
$user_name = 'YOUR_UPDATE_USERNAME';
$user_pass = 'YOUR_UPDATE_PASSWORD';
// Recommended: Basic Auth in a request header, so the password is not
// part of the URL and cannot leak through logs or error messages.
$url = "https://client.fastddns.net/?hostname=" . urlencode($hostname);
$auth = 'Basic ' . base64_encode($user_name . ':' . $user_pass);
// Method 2: Query string credentials
// $url = "https://client.fastddns.net/?hostname=" . urlencode($hostname)
//      . "&user_name=" . urlencode($user_name)
//      . "&user_pass=" . urlencode($user_pass);
$ctx = stream_context_create(['http' => [
    'timeout' => 10,
    'header'  => "Authorization: {$auth}\r\n",
]]);
$body = trim(file_get_contents($url, false, $ctx));
switch (true) {
    case str_starts_with($body, 'good'):
        echo "Updated: {$body}\n"; break;
    case str_starts_with($body, 'nochg'):
        echo "No change: {$body}\n"; break;
    case $body === 'badauth':
        echo "Auth failed. Check hostname credentials.\n"; break;
    case $body === 'nohost':
        echo "Hostname not found.\n"; break;
    case $body === '911':
        echo "Server error, retry later.\n"; break;
}PHP

Bash (Cron / Script de router)

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="YOUR_UPDATE_USERNAME"
USER_PASS="YOUR_UPDATE_PASSWORD"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s -u "${USER_NAME}:${USER_PASS}" "https://client.fastddns.net/?hostname=${HOSTNAME}")
# Method 2: Query string (uncomment to use instead)
# RESULT=$(curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}")
case "$RESULT" in
  good*)   echo "[OK] $RESULT" ;;
  nochg*)  echo "[OK] $RESULT" ;;
  badauth) echo "[ERR] Bad credentials — check hostname user/pass"; exit 1 ;;
  nohost)  echo "[ERR] Hostname not found"; exit 1 ;;
  911)     echo "[ERR] Server error, retry later"; exit 1 ;;
  *)       echo "[WARN] Unknown response: $RESULT" ;;
esacBASH

Resolución de problemas

Recibo badauth

El user_name o user_pass proporcionados no coinciden con las credenciales asignadas a ese hostname. Cada hostname tiene sus propias credenciales independientes. Encuéntralas en tu panel de control, en Hostnames → Details. Ten en cuenta que estas credenciales son específicas del hostname y no pueden usarse para iniciar sesión en el portal de gestión de FastDDNS. Si has restablecido recientemente las credenciales, actualiza todos los dispositivos que usan ese hostname.

Recibo nohost

El hostname del parámetro hostname no existe o no pertenece a la cuenta identificada por las credenciales proporcionadas. Revisa si hay errores tipográficos en el hostname, confirma que aparece en tu panel de control y verifica que el user_name y el user_pass coincidan con ese hostname específico.

El servidor detecta la IP incorrecta

El servidor utiliza la IP de origen de la conexión TCP. Si tu dispositivo está detrás de un router NAT, se detectará la IP pública del router, que suele ser el comportamiento deseado. Si estás usando una VPN o un proxy, el servidor verá la IP de salida de la VPN o del proxy. Usa el getip endpointendpoint Get Client IP

Recibo 911

Esto indica un problema temporal en el servidor. Espera al menos 5 minutos antes de volver a intentarlo. No repitas las solicitudes rápidamente, ya que esto puede activar la limitación de velocidad. Consulta la página de estado de FastDDNS para comprobar si hay incidentes activos.

¿Con qué frecuencia debería consultar el endpoint de actualización?

Recomendamos comprobar si hay cambios de IP cada 5 minutos. Cuando tu IP no ha cambiado, el servidor devuelve nochg, que es una operación ligera sin efecto. No se recomienda consultar el endpoint más de una vez por minuto, ya que podría activarse la limitación de velocidad.