¿Cómo usar las APIs de Cloudflare?

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.

Introducción

Cloudflare se encuentra delante de millones de sitios web. Gestiona DNS, CDN, protección DDoS, WAF, funciones sin servidor de Workers y mucho más. Administrar todo esto a través del panel funciona para configuraciones pequeñas. Pero a escala, se necesita automatización.

La API de Cloudflare cubre todo lo que hace el panel. Puedes crear zonas, actualizar registros DNS, configurar reglas de página, desplegar Workers, gestionar la configuración SSL y extraer analíticas. Todo de forma programática.

Los desarrolladores utilizan la API de Cloudflare para:

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

💡

Si estás desarrollando en Cloudflare, Apidog te ayuda a probar llamadas a la API, validar respuestas y documentar tu integración. Puedes guardar configuraciones de zona como solicitudes reutilizables y compartirlas con tu equipo.

button

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. Utiliza tokens de API, no claves globales.

Método 1: Tokens de API (recomendado)

Los tokens de API tienen permisos específicos. Si un token se ve comprometido, el daño es limitado.

Crear un token:

Ve a Cloudflare Dashboard → Mi Perfil → Tokens de API
Crear Token
Elige una plantilla (Editar DNS de zona, despliegue de Workers, etc.) o personalizada
Establece zonas específicas o todas las zonas
Copia el token

Usar el token:

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

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

La clave global tiene acceso completo a la cuenta. Evita usarla.

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 de respuesta

Todas las respuestas de la API de Cloudflare siguen esta estructura:

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

Siempre verifica success antes de procesar result.

Gestión de zonas

Las zonas representan dominios en Cloudflare.

Listar zonas

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

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
}

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"
  }'

Obtener detalles de zona

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

Gestión de registros DNS

Los registros DNS mapean nombres de dominio a direcciones IP 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"

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
  }'

Tipos de registro:

A - Dirección IPv4
AAAA - Dirección IPv6
CNAME - Alias a otro dominio
MX - Servidor de correo
TXT - Registros de texto (SPF, DKIM, verificación)
NS - Servidor de nombres

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
  }'

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"

Cloudflare Workers

Workers ejecutan JavaScript en el borde, 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"

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

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)
  }
}

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"
  }'

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"
  }'

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"
      }
    ]
  }'

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"
  }'

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
    }
  }'

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"

Respuesta:

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

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"
  }'

Pruebas con Apidog

Los cambios en Cloudflare afectan el tráfico de producción. Prueba exhaustivamente.

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

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
})

3. Probar despliegues de Workers

Guarda scripts de Worker como archivos en Apidog y prueba las cargas:

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

Prueba las APIs de Cloudflare con Apidog - gratis

Errores comunes y soluciones

403 Prohibido

Causa: El token carece del permiso requerido.

Solución: Verifica los permisos del token en el panel de control de Cloudflare. Las ediciones de DNS necesitan Zona:DNS:Editar. Los Workers necesitan Cuenta:Workers:Editar.

1003: Zona inválida o faltante

Causa: El ID de zona no existe o el token no puede acceder a ella.

Solución: Verifica el ID de zona en la URL y comprueba que el ámbito del token incluya esta zona.

81057: El registro ya existe

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

Solución: Usa PUT para actualizar en lugar de POST para crear, o elimina primero.

Límite de velocidad excedido

Causa: Demasiadas 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
      }
    }
  }
}

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 proporciona más flexibilidad que Lambda@Edge.

Casos de uso reales

SaaS multi-inquilino. Una plataforma crea zonas de Cloudflare automáticamente cuando los clientes añaden dominios personalizados. Workers gestionan el enrutamiento, los registros DNS se crean a través de la API y los certificados SSL se aprovisionan automáticamente.

Despliegues blue-green. Un equipo de ingeniería utiliza las actualizaciones de registros DNS para cambiar el tráfico entre entornos. La API actualiza los registros A durante el despliegue, con propagación instantánea a través de la red de Cloudflare.

Automatización de respuesta DDoS. Un equipo de seguridad monitorea el tráfico a través de la API de analíticas. Cuando surgen patrones de ataque, se añaden reglas de firewall a través de la API para bloquear IPs maliciosas, reduciendo el tiempo de respuesta de horas a segundos.

Conclusión

Esto es lo que has aprendido:

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

button

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 añades un dominio a Cloudflare, creas una zona. El ID de la zona se utiliza en las llamadas a la API para ese dominio.

¿Cómo encuentro mi ID de zona?Ve al panel de control de Cloudflare → selecciona tu dominio → Resumen → desplázate hacia abajo hasta la sección de API. El ID de la zona se muestra allí.

¿Puedo usar la API de Cloudflare sin un plan de pago?Sí. La mayoría de las características de la API funcionan en planes gratuitos. Workers tiene una generosa capa gratuita. Algunas características avanzadas (reglas WAF avanzadas, Logpush) requieren planes de pago.

¿Cuánto tiempo tardan los cambios de DNS?Los cambios a través de la API son inmediatos en el sistema de Cloudflare. La propagación a los servidores de nombres de Cloudflare toma segundos. La propagación global depende de TTL y de los resolvedores recursivos, típicamente minutos.

¿Cuál es el límite de velocidad?Por defecto: 1200 solicitudes por cada 5 minutos por token. Consulta el encabezado X-RateLimit-Remaining. Los planes Enterprise tienen límites más altos.

¿Puedo gestionar varias cuentas con un solo token?No. Los tokens tienen un alcance limitado a una sola cuenta. Para varias cuentas, crea tokens separados o usa tokens a nivel de usuario con acceso a varias cuentas.

¿En qué se diferencian los Workers de Lambda?Los Workers se ejecutan en las ubicaciones de borde de Cloudflare (más de 300 ciudades), no en regiones específicas. Los arranques en frío son mínimos. Son ideales para la manipulación de solicitudes/respuestas, no para procesos de larga duración.

¿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"]
  }'