Como Usar APIs Cloudflare: Guia Completo

Resumo

As APIs do Cloudflare permitem gerenciar DNS, zonas, Workers, segurança e análises programaticamente. Autentique com tokens de API (recomendado) ou chaves globais, chame api.cloudflare.com/client/v4 e lide com limites de taxa de forma elegante. Para testes, use o Apidog para validar alterações de DNS, testar implantações de Workers e automatizar configurações entre ambientes.

Introdução

O Cloudflare está à frente de milhões de sites. Ele gerencia DNS, CDN, proteção contra DDoS, WAF, funções serverless Workers e muito mais. Gerenciar tudo isso pelo painel funciona para configurações pequenas. Mas em escala, você precisa de automação.

A API do Cloudflare cobre tudo o que o painel faz. Você pode criar zonas, atualizar registros DNS, configurar regras de página, implantar Workers, gerenciar configurações de SSL e extrair análises. Tudo programaticamente.

Os desenvolvedores usam a API do Cloudflare para:

Infraestrutura como código (Terraform, Pulumi)
Integração de pipeline de CI/CD
Gerenciamento de múltiplas zonas
Atualizações automatizadas de DNS
Implantações de Workers

💡

Se você está desenvolvendo no Cloudflare, o Apidog ajuda a testar chamadas de API, validar respostas e documentar sua integração. Você pode salvar configurações de zona como requisições reutilizáveis e compartilhá-las com sua equipe.

botão

Teste APIs do Cloudflare com Apidog - grátis

Ao final deste guia, você será capaz de:

Autenticar com tokens de API do Cloudflare
Gerenciar zonas e registros DNS
Implantar e gerenciar Workers
Configurar definições de segurança
Extrair análises e logs

Autenticação

O Cloudflare oferece dois métodos de autenticação. Use tokens de API, não chaves globais.

Método 1: Tokens de API (recomendado)

Tokens de API são restritos a permissões específicas. Se um token for comprometido, o dano é limitado.

Criar um token:

Vá para Painel do Cloudflare → Meu Perfil → Tokens de API
Criar Token
Escolha um modelo (Editar DNS da zona, Implantação de Workers, etc.) ou personalizado
Defina zonas específicas ou todas as zonas
Copie o token

Usar o token:

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Método 2: Chave de API global (não recomendado)

A chave global tem acesso total à conta. Evite usá-la.

curl -X GET "https://api.cloudflare.com/client/v4/user" \
  -H "X-Auth-Email: your-email@example.com" \
  -H "X-Auth-Key: YOUR_GLOBAL_API_KEY"

Formato da resposta

Todas as respostas da API do Cloudflare seguem esta estrutura:

{
  "result": { ... },
  "success": true,
  "errors": [],
  "messages": []
}

Sempre verifique success antes de processar result.

Gerenciamento de zonas

Zonas representam domínios no Cloudflare.

Listar zonas

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Resposta:

{
  "result": [
    {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com",
      "status": "active",
      "paused": false,
      "type": "full",
      "development_mode": 0,
      "name_servers": [
        "ns1.cloudflare.com",
        "ns2.cloudflare.com"
      ],
      "original_name_servers": [
        "ns1.example.com"
      ],
      "original_registrar": null
    }
  ],
  "success": true
}

Criar uma zona

curl -X POST "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "newdomain.com",
    "account": {
      "id": "ACCOUNT_ID"
    },
    "type": "full"
  }'

Obter detalhes da zona

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Gerenciamento de registros DNS

Registros DNS mapeiam nomes de domínio para endereços IP e serviços.

Listar registros DNS

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Criar um registro DNS

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.1",
    "ttl": 3600,
    "proxied": true
  }'

Tipos de registro:

A - Endereço IPv4
AAAA - Endereço IPv6
CNAME - Alias para outro domínio
MX - Servidor de e-mail
TXT - Registros de texto (SPF, DKIM, verificação)
NS - Servidor de nomes

Atualizar um registro DNS

curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.2",
    "ttl": 3600,
    "proxied": true
  }'

Excluir um registro DNS

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Cloudflare Workers

Workers executam JavaScript na edge, perto dos usuários.

Listar Workers

curl -X GET "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Fazer upload de um Worker

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts/my-worker" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/javascript" \
  --data-binary @worker.js

Exemplo de Worker:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({ message: 'Hello from the edge!' }), {
        headers: { 'Content-Type': 'application/json' }
      })
    }
    
    return fetch(request)
  }
}

Vincular uma rota

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/workers/routes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "example.com/api/*",
    "script": "my-worker"
  }'

Namespace KV do Worker

Armazene dados acessíveis a partir de Workers:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/storage/kv/namespaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "my-kv-namespace"
  }'

Segurança e WAF

Regras de página

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/pagerules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "example.com/*"
        }
      }
    ],
    "actions": [
      {
        "id": "ssl",
        "value": "flexible"
      },
      {
        "id": "cache_level",
        "value": "aggressive"
      }
    ]
  }'

Regras de firewall

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/firewall/rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "expression": "ip.geoip.country eq \"CN\"",
      "paused": false
    },
    "action": "block",
    "description": "Block traffic from China"
  }'

Limitação de taxa

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/rate_limits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "disabled": false,
    "description": "Rate limit API endpoints",
    "match": {
      "request": {
        "methods": ["POST"],
        "url_pattern": "*/api/*"
      }
    },
    "threshold": 100,
    "period": 60,
    "action": {
      "mode": "ban",
      "timeout": 600
    }
  }'

Análises e logs

Análises de zona

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/analytics/dashboard?since=-1440&continuous=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Resposta:

{
  "result": {
    "totals": {
      "requests": {
        "all": 1000000,
        "cached": 800000,
        "uncached": 200000
      },
      "bandwidth": {
        "all": 50000000000,
        "cached": 40000000000
      },
      "threats": {
        "all": 5000
      },
      "pageviews": {
        "all": 250000
      }
    }
  }
}

Logs de zona (Logpush)

Habilite o Logpush para enviar logs para seu armazenamento:

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/logpush/jobs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Logpush Job",
    "destination_conf": "s3://my-bucket/logs?region=us-east-1",
    "dataset": "http_requests",
    "logpull_options": "fields=ClientIP,ClientRequestPath,EdgeResponseStatus&timestamps=rfc3339"
  }'

Testando com Apidog

Alterações no Cloudflare afetam o tráfego de produção. Teste minuciosamente.

1. Configuração do ambiente

CLOUDFLARE_API_TOKEN: your_token
CLOUDFLARE_ACCOUNT_ID: abc123
ZONE_ID: xyz789
BASE_URL: https://api.cloudflare.com/client/v4

2. Validar respostas

pm.test('Requisição foi bem-sucedida', () => {
  const response = pm.response.json()
  pm.expect(response.success).to.be.true
  pm.expect(response.errors).to.be.empty
})

pm.test('Registro DNS criado corretamente', () => {
  const response = pm.response.json()
  pm.expect(response.result.type).to.eql('A')
  pm.expect(response.result.name).to.eql('www')
  pm.expect(response.result.proxied).to.be.true
})

3. Testar implantações de Workers

Salve scripts de Worker como arquivos no Apidog e teste uploads:

pm.test('Worker carregado', () => {
  const response = pm.response.json()
  pm.expect(response.result.id).to.eql('my-worker')
})

Teste APIs do Cloudflare com Apidog - grátis

Erros comuns e soluções

403 Proibido

Causa: O token não possui a permissão necessária.

Solução: Verifique as permissões do token no painel do Cloudflare. Edições de DNS precisam de Zona:DNS:Editar. Workers precisam de Conta:Workers:Editar.

1003: Zona inválida ou ausente

Causa: O ID da zona não existe ou o token não tem acesso a ela.

Solução: Verifique o ID da zona na URL e certifique-se de que o escopo do token inclui esta zona.

81057: Registro já existe

Causa: Um registro DNS com o mesmo nome e tipo já existe.

Solução: Use PUT para atualizar em vez de POST para criar, ou exclua primeiro.

Limite de taxa excedido

Causa: Muitas requisições (padrão 1200/5 minutos).

Solução: Implemente um backoff e operações em lote.

async function updateRecords(records) {
  for (const record of records) {
    try {
      await updateRecord(record)
      await sleep(100) // Buffer para limite de taxa
    } catch (error) {
      if (error.status === 429) {
        await sleep(60000) // Esperar um minuto
        await updateRecord(record) // Tentar novamente
      }
    }
  }
}

Alternativas e comparações

Recurso	Cloudflare	AWS Route 53	Fastly
API de DNS	✓	✓	✓
API de CDN	✓	API do CloudFront	✓
Funções de Edge	Workers	Lambda@Edge	Compute@Edge
API de WAF	✓	AWS WAF	✓
Camada gratuita	Generosa	Pague pelo uso	Limitada
Formato da resposta	JSON	XML/JSON	JSON

A API do Cloudflare é mais unificada do que os serviços fragmentados da AWS. Workers oferecem mais flexibilidade do que o Lambda@Edge.

Casos de uso reais

SaaS multi-tenant. Uma plataforma cria zonas Cloudflare automaticamente quando os clientes adicionam domínios personalizados. Workers lidam com o roteamento, registros DNS são criados via API, e certificados SSL são provisionados automaticamente.

Implantações blue-green. Uma equipe de engenharia usa atualizações de registros DNS para alternar o tráfego entre ambientes. A API atualiza registros A durante a implantação, com propagação instantânea pela rede do Cloudflare.

Automação de resposta a DDoS. Uma equipe de segurança monitora o tráfego via API de análises. Quando padrões de ataque surgem, regras de firewall são adicionadas via API para bloquear IPs maliciosos, reduzindo o tempo de resposta de horas para segundos.

Conclusão

Aqui está o que você aprendeu:

Autenticar com tokens de API para acesso restrito
Gerenciar zonas e registros DNS programaticamente
Implantar Workers para computação de borda
Configurar segurança com regras de firewall e limitação de taxa
Extrair análises e configurar o envio de logs
Testar com Apidog antes de aplicar em produção

botão

Perguntas Frequentes

Qual a diferença entre uma zona e um domínio?Uma zona é a representação de um domínio no Cloudflare. Quando você adiciona um domínio ao Cloudflare, você cria uma zona. O ID da zona é usado em chamadas de API para aquele domínio.

Como encontro o ID da minha zona?Vá para o Painel do Cloudflare → selecione seu domínio → Visão Geral → role para baixo até a seção de API. O ID da zona é exibido lá.

Posso usar a API do Cloudflare sem um plano pago?Sim. A maioria dos recursos da API funciona em planos gratuitos. Workers possuem uma camada gratuita generosa. Alguns recursos avançados (regras avançadas de WAF, Logpush) exigem planos pagos.

Quanto tempo levam as alterações de DNS?As alterações via API são imediatas no sistema do Cloudflare. A propagação para os nameservers do Cloudflare leva segundos. A propagação global depende do TTL e dos resolvedores recursivos, tipicamente minutos.

Qual é o limite de taxa?Padrão: 1200 requisições por 5 minutos por token. Verifique o cabeçalho X-RateLimit-Remaining. Planos Enterprise têm limites mais altos.

Posso gerenciar várias contas com um único token?Não. Tokens são restritos a uma única conta. Para várias contas, crie tokens separados ou use tokens de nível de usuário com acesso a várias contas.

Como os Workers diferem do Lambda?Workers executam nas localizações de edge do Cloudflare (mais de 300 cidades), não em regiões específicas. Cold starts são mínimos. Eles são ideais para manipulação de requisições/respostas, não para processos de longa duração.

Posso usar a API para purgar o cache?Sim:

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["https://example.com/style.css"]
  }'