Cambiar tema
Idioma
German English Spanish French Japanese Korean Russian Chinese (Simplified)

Documentación de la API

Reglas de integración de la API de plataformas

Una referencia breve de integración: envía la clave de API correctamente, elige una estructura de respuesta, haz la primera solicitud, gestiona los errores y valida los datos de prueba.

Referencia de la API V2 Plataformas Referencia de la API V1
Por dónde empezar

Qué fija esta página

Esta página reúne las reglas que no dependen de un método de API concreto: autenticación, versión de la respuesta, manejo de errores, reintentos, uso de la API de prueba y comprobaciones de lanzamiento.

Usa la referencia de la API para los parámetros, los esquemas y los ejemplos específicos de cada método. Usa las páginas de plataformas para comparar la cobertura y los grupos de métodos.

Toma esta página como base del equipo para nuevas integraciones. Complementa la referencia de la API en lugar de repetirla.
Una clave en cada solicitud

Autenticación

Envía tu clave de API en la cabecera `X-API-Key` en cada solicitud a la API de plataformas.

La clave no se hereda de una sesión del panel. Los servicios backend, los workers y las tareas en segundo plano deben adjuntar esta cabecera de forma explícita.

  • Guarda la clave en un almacén de secretos y rótala cuando cambie el acceso o sospeches que se ha expuesto.
  • No pongas la clave en código del navegador, repositorios públicos, bundles del cliente ni registros.
  • Limita el acceso a la clave por entorno y por servicio siempre que sea posible.
Versión de la respuesta

Elige una estructura de respuesta

V1 y V2 ofrecen el mismo catálogo de métodos de API, pero devuelven estructuras de datos diferentes. Elige la versión antes de construir el cliente y mantenla fija en la configuración de la integración.

No mezcles V1 y V2 en el mismo flujo de procesamiento. Complica el mapeo, la caché, las pruebas y el mantenimiento.

V1
Respuesta original V1

Conserva la forma de la respuesta de la plataforma de origen con cambios mínimos por parte de ScrapeStorm.

Úsala cuando

Migraciones, compatibilidad con versiones anteriores y clientes que ya dependen de los campos nativos de la plataforma.

V2
Respuesta normalizada V2

Ofrece un contrato de datos más estable para el código de producto, la analítica y los servicios internos.

Úsala cuando

Nuevas integraciones, nuevos servicios y cualquier código que no necesite la forma de los datos de la plataforma de origen.

Usa V2 por defecto. Mantén V1 solo por compatibilidad o para migrar clientes existentes.
Comprobación del transporte

Haz tu primera solicitud real a la API

Después de elegir la versión, verifica la integración con un método de API en vivo: URL base, cabeceras, parámetros de consulta, tiempo de espera y manejo de errores.

Método HTTP GET
Endpoint /api/v2/youtube.com/profile/about-by-user-identifier
Parámetro de consulta de ejemplo user_identifier=mkbhd
Cabecera X-API-Key

Este ejemplo usa el método de API `profile/about-by-user-identifier` de YouTube. Sustituye `user_identifier` por un identificador de prueba de tu propio escenario.

Una respuesta correcta solo demuestra que el transporte y la estructura de primer nivel funcionan. Valida cada método de API que vayas a lanzar, junto con los límites, los precios y el manejo de fallos.
Envoltorio de la respuesta

Valida la forma de la respuesta

Los métodos públicos de la API de plataformas en V1 y V2 usan el mismo envoltorio externo: `success`, `status` y `data`. Los métodos de colección también pueden incluir `pagination` en el primer nivel.

La elección de versión cambia el esquema dentro de `data`, no el envoltorio de transporte. Consulta la referencia de la API para ver los campos exactos del método que elegiste.

Caso de respuesta Campos de primer nivel Qué leer primero
Respuesta correcta success, status, data `data` contiene los datos del método.
Respuesta correcta paginada success, status, pagination, data `pagination` queda en el primer nivel; los datos del método siguen en `data`.
Respuesta de error success, status, error, meta Ramifica según el estado HTTP y `error.code`.
No deduzcas V1 o V2 a partir del envoltorio. Fija la versión en la URL y en la configuración del cliente y luego interpreta el esquema del método según la referencia de esa versión.
Errores y reintentos

Gestiona los errores por código, no por texto

Los errores usan un envoltorio común. Ramifica según el estado HTTP y `error.code`. El campo `message` sirve para mostrarlo o registrarlo, pero no para controlar el flujo de la aplicación.

  • `401`, `402` y `422` no deben reintentarse hasta que cambie la causa.
  • `429 RATE_LIMIT_EXCEEDED` solo debe reintentarse después de `Retry-After` o `error.retry_after_seconds`.
  • `500` y `503` deben reintentarse con un backoff acotado y un límite estricto de intentos.
Estado HTTP Código de error Acción del cliente
401 No autorizado UNAUTHORIZED Revisa la clave de API y el entorno. No repitas en bucle la misma solicitud con la misma clave.
422 Validación fallida VALIDATION_FAILED Corrige los parámetros de la solicitud. La misma entrada devolverá el mismo error.
402 Créditos insuficientes INSUFFICIENT_CREDITS Detén el flujo hasta que se actualicen el saldo o los límites de la cuenta.
429 Se superaron las conexiones simultáneas CONCURRENT_CONNECTIONS_EXCEEDED Reduce el trabajo en paralelo por clave de API o pon las solicitudes en cola.
429 Límite de frecuencia superado RATE_LIMIT_EXCEEDED Espera el intervalo de reintento indicado y coordina los reintentos entre workers.
503 Endpoint no disponible ENDPOINT_UNAVAILABLE Aplica backoff a nivel de método en lugar de pausar toda la integración si los demás métodos funcionan.
500 Error interno del servidor INTERNAL_SERVER_ERROR Reintenta con un backoff acotado. Tras alcanzar el límite de intentos, registra el error y escálalo mediante la monitorización.
Para `RATE_LIMIT_EXCEEDED`, la única fuente fiable del momento del siguiente reintento es `Retry-After` o `error.retry_after_seconds`.
API de prueba

Valida la forma con datos de prueba

Los métodos de la API de prueba devuelven ejemplos JSON estáticos sin llamar a las plataformas de origen. Úsalos para desarrollar el cliente, la interfaz y las pruebas del parser.

La API de prueba no demuestra la disponibilidad del método, la frescura de los datos, los límites, los precios ni el comportamiento en producción. Repite el mismo escenario contra la API en vivo antes del lanzamiento.
  • No uses los datos de prueba para verificar la frescura de los datos.
  • No copies valores de prueba en la lógica de la integración en vivo.
  • Compara solo el envoltorio, los nombres de campo y la estructura básica de la respuesta.
API de prueba https://www.scrapestorm.net/api-mock
Ejemplo https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd
Referencia de la API
Referencia de la API de prueba V2 Referencia de la API de prueba V1
Antes del lanzamiento

Lista de comprobación para producción

Revisa estas comprobaciones antes del tráfico real y antes de aumentar la simultaneidad de los workers.

  1. 01

    La versión de la respuesta está fijada

    Los clientes nuevos usan V2. V1 solo se permite por compatibilidad o para migrar una integración existente.

  2. 02

    La clave de API se guarda como secreto

    La clave vive en un almacén de secretos y queda fuera del código frontend, los repositorios públicos, los bundles del cliente y los registros.

  3. 03

    El manejo de errores se basa en códigos legibles por máquina

    Las ramas del cliente dependen del estado HTTP y de `error.code`. `message` no se usa en la lógica de negocio.

  4. 04

    Los reintentos están acotados

    `RATE_LIMIT_EXCEEDED` espera a `Retry-After` o `error.retry_after_seconds`. `402` y `422` no se reintentan con la misma entrada. `500` y `503` tienen backoff y un límite de intentos.

  5. 05

    La simultaneidad se controla por clave de API

    Una cola o un limitador de frecuencia acota las solicitudes simultáneas de workers, tareas cron y procesos en segundo plano.

  6. 06

    Prueba y producción se validan por separado

    Los datos de prueba validan la forma de los datos. La API en vivo valida los parámetros reales, los límites, la disponibilidad y el consumo de créditos.

  7. 07

    Los precios de los métodos de API están confirmados

    Revisa el coste de los métodos de API que vas a usar antes de que aumente el tráfico.

Siguiente

Referencia de la API y plataformas

Abre la versión de la referencia de la API que necesites para ver parámetros, esquemas y ejemplos concretos de cada método. Usa Plataformas para elegir la fuente y el grupo de métodos.

En vivo Referencia de la API V2 con la respuesta normalizada En vivo Referencia de la API V1 con la respuesta original Prueba Referencia de la API de prueba V2 con ejemplos estáticos Prueba Referencia de la API de prueba V1 con ejemplos estáticos Plataformas Plataformas compatibles y grupos de métodos de API