API do cliente FastDDNS

Visão geral

A API de Cliente FastDDNS permite que qualquer dispositivo compatível com HTTP — roteadores, câmeras IP, scripts ou softwares dedicados de atualização — mantenha seu hostname apontado para o endereço IP atual. A API segue um design simples de requisições GET: o cliente envia as credenciais e um hostname, 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 o IP.

Autenticação

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

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

As credenciais são incorporadas à URL usando o formato padrão user:password@host. Esse formato é amplamente compatível com 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 query string

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

Exemplo usando autenticação por query string:

Realizar atualização

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

Endpoint

Formato da URL — Método 1: HTTP Basic Auth

Formato da URL — Método 2: Query String

Parâmetros da query

Exemplos de solicitações

Método 1 — HTTP Basic Auth via HTTPS:

Método 2 — String de consulta via HTTPS:

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

Códigos de retorno

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

Resumo da resposta

Obter IP do cliente

O FastDDNS fornece um endpoint utilitário simples que retorna o endereço IP público conforme detectado pelo servidor. Isso é útil para depuração, para verificar de qual IP seu dispositivo está enviando dados 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

# 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 do 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

Solução de problemas

Recebo badauth

O user_name ou user_pass fornecidos não correspondem às credenciais atribuídas a esse hostname. Cada hostname tem suas próprias credenciais independentes — encontre-as no seu painel, em Hostnames → Details. Observe que essas credenciais são específicas do hostname e não podem ser usadas para fazer login no portal de gerenciamento do FastDDNS. Se você redefiniu as credenciais recentemente, atualize todos os dispositivos que usam esse hostname.

Recebo nohost

O hostname no parâmetro hostname não existe ou não pertence à conta identificada pelas credenciais fornecidas. Verifique se há erros de digitação no hostname, confirme se ele está listado no seu painel e verifique se o user_name e o user_pass correspondem a esse hostname específico.

O servidor está detectando o IP incorreto

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

Recebo 911

Isso indica um problema temporário no servidor. Aguarde pelo menos 5 minutos antes de tentar novamente. Não repita as solicitações rapidamente — isso pode acionar a limitação de taxa. Consulte a página de status do FastDDNS para verificar se há incidentes ativos.

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

Recomendamos verificar se houve alterações no IP a cada 5 minutos. Quando o IP não tiver mudado, o servidor retornará nochg, que é uma operação leve sem efeito. Não é recomendável consultar o endpoint mais de uma vez por minuto, pois isso pode resultar em limitação de taxa.