Plantillas

Introducción

Las plantillas son configuraciones reutilizables para scraping, crawl o búsqueda. En lugar de repetir las mismas opciones en cada llamada a la API, las defines una vez en una plantilla (o obtienes una del AnyCrawl Template Store) y la referencias con template_id.

Ventajas:

• Simplicidad: llama a las APIs solo con template_id y entradas mínimas
• Coherencia: estandariza el comportamiento en tu equipo o proyectos
• Seguridad: las plantillas pueden restringir dominios permitidos y exponer solo las variables necesarias
• Potencia: manejadores personalizados opcionales para transformaciones avanzadas

Tipos admitidos:

• scrape: extracción de una sola página vía /v1/scrape
• crawl: crawl multipágina vía /v1/crawl
• search: resultados de buscadores vía /v1/search

Marketplace de plantillas

Explora plantillas listas para usar en anycrawl.dev/template.

Cómo usarlas:

1. Explora el marketplace y elige una plantilla que encaje con tus necesidades
2. Copia el template_id desde la página de detalle
3. Llama a la API con ese template_id y las entradas requeridas

Ejemplo:

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "content-extractor",
    "url": "https://example.com"
  }'

Uso de plantillas en llamadas a la API

Parámetros de la solicitud

Al usar template_id, solo se permiten campos mínimos:

Notas importantes:

• url o query pueden ser opcionales si la plantilla los define por adelantado. Consulta la descripción de la plantilla.
• variables pasa entradas dinámicas que la plantilla espera (véase la sección Variables).
• Otros campos (como engine, formats, timeout, etc.) provienen de la plantilla y no se pueden sobrescribir.
• Enviar campos no permitidos devuelve un error de validación 400.

Scrape con plantilla

curl -X POST "https://api.anycrawl.dev/v1/scrape" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-scrape-template",
    "url": "https://example.com",
    "variables": { "category": "tech" }
  }'

Crawl con plantilla

curl -X POST "https://api.anycrawl.dev/v1/crawl" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-crawl-template",
    "url": "https://docs.example.com",
    "variables": { "maxPages": 50 }
  }'

Search con plantilla

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "my-search-template",
    "query": "machine learning tutorials",
    "variables": { "lang": "en" }
  }'

Variables

Las plantillas pueden declarar variables para aceptar entradas dinámicas en el momento de la llamada.

• Cada variable tiene un type: string, number, boolean o url
• Las variables pueden ser required u opcionales con defaultValue
• Consulta la descripción de la plantilla para ver qué variables espera

Ejemplo de solicitud con variables:

{
    "template_id": "blog-scraper",
    "url": "https://example.com/blog/post-123",
    "variables": {
        "author": "john-doe",
        "includeComments": true,
        "maxComments": 50
    }
}

Si omites una variable obligatoria o el tipo es incorrecto, obtendrás un error de validación 400.

Formato de respuesta

Las respuestas con plantilla siguen el mismo formato que las llamadas estándar a la API:

{
    "success": true,
    "data": {
        "url": "https://example.com",
        "markdown": "# Page Title\n\nContent...",
        "metadata": { ... },
        // Additional fields from custom handlers (if any)
        "extractedData": { ... }
    }
}

Las plantillas con manejadores personalizados pueden añadir campos extra a la respuesta.

Manejo de errores

Errores habituales al usar plantillas:

Ejemplo de respuesta de error:

{
    "success": false,
    "error": "Validation error",
    "message": "When using template_id, only template_id, url, variables are allowed. Invalid fields: engine, formats",
    "data": {
        "type": "validation_error",
        "issues": [
            {
                "field": "engine",
                "message": "Field 'engine' is not allowed when using template_id",
                "code": "invalid_field"
            }
        ],
        "status": "failed"
    }
}

Buenas prácticas

Para quien llama a la API

• Revisa siempre la descripción de la plantilla: variables obligatorias y dominios/palabras clave permitidos
• Usa plantillas del marketplace cuando existan para ahorrar tiempo
• Gestiona errores 404 (la plantilla puede haberse eliminado o archivado)
• No intentes sobrescribir la configuración de la plantilla (engine, formats, etc.): fallará

Para autores de plantillas

• Mantén cada plantilla enfocada en un solo caso de uso
• Documenta todas las variables con descripciones claras
• Usa restricciones de dominio para evitar usos indebidos
• Define un precio adecuado según la complejidad
• Prueba las plantillas a fondo antes de publicar

Crear plantillas (avanzado)

Si creas tus propias plantillas, puedes configurar:

Restricciones de dominio

Limita dónde puede usarse tu plantilla:

{
    "allowedDomains": {
        "type": "glob",
        "patterns": ["*.example.com", "docs.mysite.com"]
    }
}

• type: "exact" (coincidencia exacta) o "glob" (patrón)
• patterns: array de dominios o patrones permitidos

Restricciones de palabras clave (plantillas de búsqueda)

Limita qué consultas pueden usarse con una plantilla de búsqueda:

{
    "allowedKeywords": {
        "type": "glob",
        "patterns": ["*tutorial*", "*documentation*"]
    }
}

• allowedKeywords se valida antes de ejecutar la consulta.
• type: "exact" o "glob"
• patterns: valores o patrones de palabras clave permitidos
• La validación de la consulta ocurre antes de aplicar queryTransform.

Precios

Define el coste en créditos por llamada:

{
    "pricing": {
        "perCall": 10,
        "currency": "credits"
    }
}

Manejadores personalizados

Escribe código JavaScript/TypeScript para:

• requestHandler: postprocesar resultados de scrape y añadir campos personalizados
• failedRequestHandler: gestionar fallos con lógica de reintento personalizada
• queryTransform (solo búsqueda): transformar consultas antes de buscar
• urlTransform (solo scrape/crawl): transformar URL antes de procesarlas

Ambas transformaciones admiten:

• Modo plantilla con marcadores de posición (query: {{query}}, url: {{url}})
• Modo append con prefix y suffix
• regexExtract opcional para extraer una subcadena antes de aplicar el modo

Ejemplo de extracción por regex para perfiles de TikTok:

{
    "customHandlers": {
        "urlTransform": {
            "enabled": true,
            "mode": "append",
            "prefix": "",
            "suffix": "",
            "regexExtract": {
                "pattern": "^(https?:\\/\\/www\\.tiktok\\.com\\/@[^\\/?#]+)",
                "flags": "i",
                "group": 1
            }
        }
    }
}

Esto extrae https://www.tiktok.com/@piperrockelle a partir de entradas como:

• https://www.tiktok.com/@piperrockelle?abb=ccc
• https://www.tiktok.com/@piperrockelle

Ejemplo de requestHandler:

// Extract structured data from page context
const title = context.data.title;
const content = context.data.markdown;

return {
    extractedTitle: title,
    wordCount: content.split(/\s+/).length,
    customMetric: calculateMetric(content),
};

Modelo de seguridad

• Plantillas no confiables: se ejecutan en un sandbox VM reforzado con limitaciones estrictas
• Plantillas confiables: pueden usar funciones asíncronas con acceso controlado a la página del navegador

Solo las plantillas revisadas y aprobadas por AnyCrawl pueden marcarse como confiables.

Preguntas frecuentes

¿Puedo sobrescribir ajustes de la plantilla como engine o formats?

No. Las plantillas son configuraciones inmutables. Solo puedes indicar url/query y variables.

¿Qué pasa si uso una plantilla del marketplace?

Las plantillas del marketplace son públicas. Pagas los créditos definidos por el autor.

¿Las plantillas pueden ver mi clave API?

No. Se ejecutan en sandboxes aisladas y no tienen acceso a tus credenciales.

¿Cómo creo mis propias plantillas?

Visita el playground de AnyCrawl para crear y probar plantillas. Tras publicarlas, podrás usarlas vía API.

Ver también

• Documentación de la API Scrape
• Documentación de la API Crawl
• Documentación de la API Search
• Marketplace de plantillas