API de Cliente FastDDNS

Visão geral

A API Cliente FastDDNS permite que qualquer dispositivo compatível com HTTP — roteadores, câmeras IP, scripts ou softwares dedicados de atualização — mantenha seu nome DNS apontado para seu endereço IP atual. A API segue um design simples de requisição GET: seu cliente envia credenciais e um nome de host, e o servidor responde com um breve código de status indicando o resultado.

O servidor detecta automaticamente o endereço IP público do cliente a partir da conexão recebida. Não são necessários parâmetros extras para especificar seu IP.

Autenticação

A API suporta dois métodos de autenticação. Ambos são aceitos igualmente — escolha o que for mais fácil de configurar no seu dispositivo ou roteador.

Método 1 — Autenticação Básica HTTP (URL-embedded)

As credenciais são incorporadas na URL usando o formato padrão user:password@host. Isso é amplamente suportado por roteadores, câmeras e bibliotecas de clientes HTTP. Use a Chave do Cliente do Atualizador do seu painel como senha.

Método 2 — Parâmetros de Sequência de Consulta

As credenciais são passadas como parâmetros de consulta simples junto com hostname. Isso é útil para dispositivos e firmwares, que não conseguem configurar cabeçalhos HTTP Basic Auth, mas permitem uma string de URL totalmente personalizada.

Exemplo usando autenticação de sequência de consulta:

Atualização de Perform

Envie uma única solicitação GET para atualizar o endereço IP de um nome de host registrado na sua conta. Cada solicitação atualiza um nome de host por vez.

Endpoint

Formato URL — Método 1: Autenticação Básica HTTP

Formato URL — Método 2: String de consulta

Parâmetros de consulta

Exemplos de Solicitações

Método 1 — Autenticação Básica HTTP sobre HTTPS:

Método 2 — Consultar a cadeia de caracteres sobre HTTPS:

Usando HTTP simples (apenas testes / redes confiáveis):

Códigos de retorno

Todas as respostas de atualização retornam o status HTTP 200 OK com texto simples. Seu cliente deve analisar esse corpo de texto para determinar o resultado real da atualização.

Resumo da Resposta

Obtenha IP do Cliente

O FastDDNS fornece um endpoint utilitário simples que retorna o endereço IP público conforme visto pelo servidor. Isso é útil para depuração, para verificar de qual IP seu dispositivo está enviando, ou para uso em scripts personalizados antes de chamar o endpoint de atualização.

Endpoint

Resposta

Retorna HTTP 200 OK com o endereço IP público detectado como texto simples no corpo da resposta.

# Example response body
203.0.113.45RESPONSE

Exemplos de Solicitações

Usando curl:

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

Exemplos de Código

Shell / cURL

# Method 1: HTTP Basic Auth (HTTPS, IP auto-detected)
curl "https://fastddnstest:[email protected]/?hostname=testhost.fastddns.org"
# Method 2: Query string credentials
curl "https://client.fastddns.net/?hostname=testhost.fastddns.org&user_name=fastddnstest&user_pass=569832"
# Check what IP the server sees from your device
curl "https://client.fastddns.net/dyndns/getip"SHELL

Python

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "fastddnstest"
USER_PASS = "569832"
# 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 = 'fastddnstest';
$user_pass = '569832';
// Method 1: HTTP Basic Auth embedded in URL
$url = "https://{$user_name}:{$user_pass}@client.fastddns.net/?hostname=" . urlencode($hostname);
// 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]]);
$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 / Roteador Script)

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="fastddnstest"
USER_PASS="569832"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s "https://${USER_NAME}:${USER_PASS}@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

Solução de problemas

Eu recebo badauth

Os user_name ou user_pass fornecidos não correspondem às credenciais atribuídas àquele nome de host. Cada nome de host tem suas próprias credenciais independentes — encontre-as no seu painel sob Nomes → Detalhes dos Hostnames . Note que essas credenciais são específicas para o nome do host e não podem ser usadas para fazer login no portal de gerenciamento FastDDNS. Se você redefinir as credenciais recentemente, atualize todos os dispositivos usando esse nome de host.

Recebo nohost

O nome de host no parâmetro hostname não existe ou não pertence à conta identificada pelas credenciais fornecidas. Verifique por erros de digitação no nome do host, confirme que está listado no seu painel e verifique se o user_name e o user_pass coincidem Esse nome de host específico .

O servidor está detectando o IP errado

O servidor usa o IP de origem da conexão TCP. Se seu dispositivo estiver atrás de um roteador NAT, o IP público do roteador será detectado — o que geralmente é o comportamento desejado. Se você estiver em uma VPN ou proxy, o servidor verá o IP de saída da VPN/proxy. Use o getip endpoint para verificar qual IP o servidor vê do seu dispositivo.

Recebo 911

Isso indica um problema temporário do lado do servidor. Espere pelo menos 5 minutos antes de tentar novamente. Não faça looping de solicitações rapidamente — isso pode desencadear limitação de taxa. Verifique a página de status do FastDDNS para quaisquer incidentes ativos.

Com que frequência devo consultar o endpoint de atualização?

Recomendamos verificar mudanças de IP a cada 5 minutos. Quando seu IP não mudou, o servidor retorna nochg, que é um no-op leve. Pesquisar com mais frequência de uma vez por minuto é desencorajado e pode resultar em limitação de taxas.