DEV Community

Cover image for ¿Cómo usar las APIs de Cloudflare?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Cómo usar las APIs de Cloudflare?

#api #cloud #networking #tutorial

TL;DR

Las API de Cloudflare permiten gestionar DNS, zonas, Workers, seguridad y analíticas de forma programática. Autentícate con tokens de API (recomendado) o claves globales, llama a api.cloudflare.com/client/v4 y gestiona los límites de velocidad con prudencia. Para realizar pruebas, utiliza Apidog para validar cambios de DNS, probar despliegues de Workers y automatizar la configuración en diferentes entornos.

Prueba Apidog hoy

Introducción

Cloudflare está delante de millones de sitios web y gestiona DNS, CDN, protección DDoS, WAF, funciones sin servidor (Workers) y más. Administrar todo esto desde el panel funciona para configuraciones pequeñas, pero si trabajas a escala, necesitas automatización.

La API de Cloudflare replica toda la funcionalidad del panel: crear zonas, actualizar registros DNS, configurar reglas de página, desplegar Workers, gestionar SSL y extraer analíticas, todo de forma programática.

Implementa la API de Cloudflare en:

  • Infraestructura como código (Terraform, Pulumi)
  • Pipelines CI/CD
  • Gestión de múltiples zonas
  • Actualizaciones automáticas de DNS
  • Despliegues de Workers

💡 Tip: Si desarrollas sobre Cloudflare, Apidog te ayuda a probar llamadas API, validar respuestas y documentar tu integración. Guarda configuraciones de zona como solicitudes reutilizables y compártelas con tu equipo.

Prueba las APIs de Cloudflare con Apidog - gratis.

Al final de esta guía podrás:

  • Autenticarte con tokens de API de Cloudflare
  • Gestionar zonas y registros DNS
  • Desplegar y gestionar Workers
  • Configurar ajustes de seguridad
  • Extraer analíticas y logs

Autenticación

Cloudflare ofrece dos métodos de autenticación. Para producción, usa tokens de API (no claves globales).

Método 1: Tokens de API (recomendado)

Los tokens de API tienen permisos específicos. Si se comprometen, el alcance del daño es limitado.

Cómo crear un token:

  1. Ve a Cloudflare Dashboard → Mi Perfil → Tokens de API
  2. Crear Token
  3. Elige una plantilla (Editar DNS de zona, despliegue de Workers, etc.) o selecciona permisos personalizados
  4. Establece zonas específicas o permite todas las zonas
  5. Copia el token

Cómo usar el token:

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

Método 2: Clave API global (no recomendado)

La clave global da acceso total a la cuenta. Evita este método cuando sea posible.

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"
Enter fullscreen mode Exit fullscreen mode

Formato de respuesta

Todas las respuestas siguen esta estructura:

{
  "result": { ... },
  "success": true,
  "errors": [],
  "messages": []
}
Enter fullscreen mode Exit fullscreen mode

Verifica success antes de procesar el campo result.

Gestión de zonas

Las zonas representan dominios gestionados en Cloudflare.

Listar zonas 

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

Respuesta:

{
  "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
}
Enter fullscreen mode Exit fullscreen mode

Crear una 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Obtener detalles de zona 

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

Gestión de registros DNS

Los registros DNS mapean nombres de dominio a IPs y servicios.

Listar registros DNS 

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

Crear un 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
  }'
Enter fullscreen mode Exit fullscreen mode

Tipos de registro:

  • A - Dirección IPv4
  • AAAA - Dirección IPv6
  • CNAME - Alias
  • MX - Correo
  • TXT - Texto (SPF, DKIM, etc.)
  • NS - Nameserver

Actualizar un 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
  }'
Enter fullscreen mode Exit fullscreen mode

Eliminar un registro DNS 

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

Cloudflare Workers

Workers ejecutan JavaScript en el edge, cerca de los usuarios.

Listar Workers 

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

Subir un 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
Enter fullscreen mode Exit fullscreen mode

Ejemplo 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)
  }
}
Enter fullscreen mode Exit fullscreen mode

Vincular una ruta 

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Espacio de nombres KV de Worker

Almacena datos accesibles desde 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Seguridad y WAF

Reglas 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"
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Reglas 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Limitación de velocidad 

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
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Analíticas y logs

Analíticas 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"
Enter fullscreen mode Exit fullscreen mode

Respuesta:

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

Logs de zona (Logpush)

Habilita Logpush para enviar logs a tu almacenamiento:

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Pruebas con Apidog

Los cambios de Cloudflare impactan producción. Prueba todo antes.

Captura de pantalla de la interfaz de Apidog mostrando una configuración de prueba para Cloudflare API.

1. Configuración del entorno 

CLOUDFLARE_API_TOKEN: tu_token
CLOUDFLARE_ACCOUNT_ID: abc123
ZONE_ID: xyz789
BASE_URL: https://api.cloudflare.com/client/v4
Enter fullscreen mode Exit fullscreen mode

2. Validar respuestas 

pm.test('La solicitud fue exitosa', () => {
  const response = pm.response.json()
  pm.expect(response.success).to.be.true
  pm.expect(response.errors).to.be.empty
})

pm.test('Registro DNS creado correctamente', () => {
  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
})
Enter fullscreen mode Exit fullscreen mode

3. Probar despliegues de Workers

Guarda tus scripts Worker como archivos y prueba la carga vía Apidog:

pm.test('Worker subido', () => {
  const response = pm.response.json()
  pm.expect(response.result.id).to.eql('my-worker')
})
Enter fullscreen mode Exit fullscreen mode

Prueba las APIs de Cloudflare con Apidog - gratis

Errores comunes y soluciones

403 Prohibido

Causa: El token carece de permisos necesarios.

Solución: Verifica los permisos del token en el panel de Cloudflare. Zona:DNS:Editar para editar DNS, Cuenta:Workers:Editar para Workers.

1003: Zona inválida o faltante

Causa: El ID de zona no existe o el token no tiene acceso.

Solución: Verifica el ID de zona en la URL y asegúrate de que el token incluye acceso a esa zona.

81057: El registro ya existe

Causa: Ya existe un registro DNS con el mismo nombre y tipo.

Solución: Usa PUT para actualizar, o elimina primero el registro existente.

Límite de velocidad excedido

Causa: Exceso de solicitudes (por defecto 1200/5 minutos).

Solución: Implementa backoff y operaciones por lotes.

async function updateRecords(records) {
  for (const record of records) {
    try {
      await updateRecord(record)
      await sleep(100) // Buffer para límite de velocidad
    } catch (error) {
      if (error.status === 429) {
        await sleep(60000) // Espera un minuto
        await updateRecord(record) // Reintenta
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternativas y comparaciones

Característica Cloudflare AWS Route 53 Fastly
API de DNS ✓ ✓ ✓
API de CDN ✓ API de CloudFront ✓
Funciones de borde Workers Lambda@Edge Compute@Edge
API de WAF ✓ AWS WAF ✓
Capa gratuita Generosa Pago por uso Limitada
Formato de respuesta JSON XML/JSON JSON

La API de Cloudflare es más unificada que los servicios fragmentados de AWS. Workers da más flexibilidad que Lambda@Edge.

Casos de uso reales

SaaS multi-inquilino: Automatiza la creación de zonas de Cloudflare cuando los clientes agregan dominios personalizados. Usa la API para registros DNS y despliegue de Workers; aprovisiona certificados SSL automáticamente.

Despliegues blue-green: Cambia tráfico entre entornos actualizando registros A vía la API durante el despliegue; la propagación es instantánea en la red de Cloudflare.

Automatización anti-DDoS: Monitorea el tráfico usando la API de analíticas y aplica reglas de firewall vía API en caso de ataque, reduciendo el tiempo de respuesta de horas a segundos.

Conclusión

En este artículo has aprendido a:

  • Autenticarte con tokens de API para acceso granular
  • Gestionar zonas y registros DNS programáticamente
  • Desplegar Workers para computación en el edge
  • Configurar seguridad con reglas de firewall y limitación de velocidad
  • Extraer analíticas y configurar el envío de logs
  • Probar todo con Apidog antes de aplicar en producción

Preguntas Frecuentes

¿Cuál es la diferencia entre una zona y un dominio?

Una zona es la representación de un dominio en Cloudflare. Cuando agregas un dominio, creas una zona. El ID de zona se usa en las llamadas API para ese dominio.

¿Cómo encuentro mi ID de zona?

En el panel de Cloudflare, selecciona tu dominio → Resumen → busca la sección de API para ver el ID de zona.

¿Puedo usar la API de Cloudflare sin plan de pago?

Sí, la mayoría de funcionalidades API están disponibles en el plan gratuito. Workers tiene una capa gratuita generosa; algunas funciones avanzadas requieren planes pagos.

¿Cuánto tardan los cambios de DNS?

Los cambios vía API son inmediatos en Cloudflare. La propagación a los nameservers toma segundos; globalmente, depende del TTL y los resolvers, normalmente minutos.

¿Cuál es el límite de velocidad?

Por defecto: 1200 solicitudes cada 5 minutos por token. Chequea el header X-RateLimit-Remaining. Planes Enterprise tienen límites más altos.

¿Puedo gestionar varias cuentas con un solo token?

No. Los tokens tienen alcance por cuenta. Para varias cuentas, crea tokens separados o usa tokens de usuario con acceso a múltiples cuentas.

¿En qué se diferencian los Workers de Lambda?

Los Workers corren en más de 300 ubicaciones edge; los arranques en frío son mínimos. Ideales para manipulación request/response, no para procesos largos.

¿Puedo usar la API para purgar la caché?

Sí:

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"]
  }'
Enter fullscreen mode Exit fullscreen mode

Top comments (0)