Inicio con la API de datos unificada: del directorio de capacidades al primer resultado disponible

Conectar una plataforma suele ser sencillo al escribir un fragmento de código de solicitud. El verdadero desafío surge al integrar la segunda: los nombres de los parámetros cambian, los identificadores de usuarios y contenidos varían, algunas interfaces devuelven datos de inmediato y otras crean tareas primero. Cuando el programa comienza a ejecutarse de forma programada, los reintentos por fallo, la deduplicación de resultados y la conciliación de facturas generan cada uno su propia capa de lógica.

La API de datos unificada resuelve este trabajo de integración repetitivo. En EveryInfra de EveryData, usas el mismo esquema de autenticación Bearer, seleccionas la plataforma mediante platform, la capacidad mediante action y pasas los parámetros de dicha capacidad mediante params. Lo que se unifica es el punto de entrada de la llamada y el modo de procesamiento general, no la conversión de los datos de todas las plataformas en un único objeto de negocio.

Este tutorial demuestra una solicitud mínima utilizando la búsqueda de notas de Xiaohongshu y explica cómo expandirla a otras capacidades. El objetivo no es emitir una única solicitud HTTP, sino permitir que el programa sepa qué datos ha obtenido, qué resultados siguen pendientes y cómo coordinar la siguiente ejecución. Los ejemplos se basan en los directorios públicos y las implementaciones verificadas de 2026-09-04; los POST de negocio son plantillas de llamada para que las adaptes en escenarios autorizados, no mediciones de éxito recién realizadas en esta ronda.

Distingue primero: necesitas extraer datos, o buscar y generar

Si ya conoces la plataforma a la que pertenece el objeto (por ejemplo, una nota específica, un producto o una ubicación) y deseas leer sus campos estructurados, la API de datos constituye un punto de partida adecuado. Si aún te preguntas dónde encontrar estos materiales en la web, debes realizar una búsqueda web primero; si ya posees el material y requieres resumirlo, clasificarlo o redactar un informe, corresponde al procesamiento por modelos.

Tomando como ejemplo el análisis de comentarios, la recolección se encarga de responder qué son dichos comentarios y de dónde provienen, mientras que el modelo responde qué problemas aparecieron en los textos. Lo segundo no puede inventar registros cuya recolección haya fallado, ni interpretar como cero la cantidad de comentarios no devueltos. Separar ambas fases te permite volver a la evidencia original cuando una conclusión sea debatible, sin necesidad de adivinar de nuevo toda la cadena de llamadas.

Paso 1: Confirma la capacidad con el directorio, sin adivinar interfaces por el nombre de la plataforma

El directorio de capacidades se puede leer sin una API Key. Utiliza primero la versión compact para conocer las plataformas y acciones disponibles, y luego lee el contrato completo para la plataforma seleccionada. La versión compact se emplea para el descubrimiento y omite algunos parámetros y descripciones de campos; no utilices el directorio resumido como un validador de solicitudes completo.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?compact=1' \
  | jq '.capabilities[] | {platform, action, required_params, mode, available}'

Por ejemplo, si necesitas hallar un conjunto de notas de Xiaohongshu relacionadas con palabras clave de investigación, debes revisar primero search; si ya posees el enlace de una nota específica y quieres leer sus detalles o comentarios, debes elegir el valor correspondiente note o comments. Que los nombres sean similares no implica que sean intercambiables: el parámetro keyword de la búsqueda no puede usarse directamente como la URL de una solicitud de detalles.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=xiaohongshu' \
  | jq -e '.capabilities[] | select(.action == "search") | {
      platform, action, required_params, optional_params,
      param_meanings, mode, returns_list,
      default_limit, max_limit, response_fields, available
    }'

En esta verificación del directorio, el parámetro obligatorio para xiaohongshu.search es keyword, con mode establecido en sync y returns_list en true; el recuento predeterminado es 20 y el límite máximo es 50. Estos dos últimos valores describen la configuración de cantidad de esta capacidad, no garantizan que se entregue siempre esa cantidad por vez, y mucho menos constituyen un límite universal entre plataformas. El directorio también enumera sort y content_type; cuando necesites filtrar, rellena los campos según los valores permitidos en param_meanings y no copies enumeraciones de otra plataforma.

• required_params: qué entradas debes proporcionar obligatoriamente. Satisface esto primero y añade filtros de forma gradual.
• param_meanings: significado de los parámetros y valores permitidos ya declarados. No inventes tus propias enumeraciones para campos que no las tengan.
• mode y returns_list: determinan respectivamente si se requiere consulta de tareas y si los datos de negocio finales son una lista o un único objeto.
• response_fields: se usa para planificar el mapeo de campos; no representa una respuesta real ni garantiza que cada campo tenga un valor distinto de vacío.
• available: marca de disponibilidad a nivel de directorio; no demuestra de antemano que un enlace de destino específico vaya a devolver datos en este momento.

Las capacidades de tipo lista también admiten un limit general, el cual no aparece repetido obligatoriamente dentro de optional_params. Esta distinción ha sido comprobada por el código de validación de solicitudes. Al realizar la integración, revisa simultáneamente la declaración de la lista, los valores predeterminados y máximos, y la descripción completa; no elimines un limit válido solo por hacer una coincidencia de cadenas únicamente en optional_params.

Paso 2: Envía una solicitud lo suficientemente pequeña y fácil de inspeccionar

Prepara una API Key con los permisos de capacidad correspondientes y proporciónala en las variables de entorno del servidor. No la coloques en códigos frontend de navegadores, capturas de pantalla o archivos de ejemplo de descarga pública. A continuación, se asume que EVERYINFRA_API_KEY se ha configurado mediante tu propio método de gestión de claves; el comando envía una única solicitud sin reintentos automáticos.

: "${EVERYINFRA_API_KEY:?configura primero la API Key del servidor}"
curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "platform": "xiaohongshu",
    "action": "search",
    "params": {
      "keyword": "AI tools",
      "limit": 5
    }
  }'

El valor 5 aquí representa el tamaño de muestra pequeño que deseas inspeccionar, no una garantía de entrega; 180 segundos es el límite de espera del cliente para este ejemplo, no un SLA del servicio. Utiliza primero una cantidad reducida de resultados para confirmar los campos, el formato de hora y los enlaces de origen antes de ampliar el volumen de datos. En la depuración inicial, conserva la línea de estado HTTP y el cuerpo de respuesta para poder leer errores específicos al encontrar códigos 4xx o 5xx, en lugar de ver únicamente un mensaje de fallo de curl.

Tres campos de nivel superior deben mantenerse claros: platform y action se encargan de seleccionar la capacidad, mientras que todas las condiciones de negocio se colocan dentro de params. No eleves keyword al nivel superior ni adjuntes page, cursor o sort a todas las acciones. No puedes inferir que un parámetro es compatible basándote en que la mayoría de las API lo diseñan así, si el directorio no lo ha abierto.

OpenAPI ayuda a las personas y a los programas a describir cuerpos de solicitud, parámetros y respuestas, pero no exige que cada plataforma utilice el mismo modelo de negocio. Si necesitas generar tipos o desarrollar un invocador, puedes comprender el formato de descripción de la interfaz mediante la especificación y determinar los campos concretos utilizando el directorio y el contrato de respuesta del propio servicio.

Paso 3: Comprende las capas externa e interna de un resultado síncrono

Para xiaohongshu.search, seleccionado en este artículo, la implementación coloca la lista en results y proporciona además información de nivel superior como id, platform, action, count, billing y quota. id es el identificador de rastreo de esta solicitud; el id de cada registro dentro de results es el identificador del contenido. Ambos no deben confundirse: el primero se usa para la depuración y conciliación, y el segundo para la deduplicación de registros.

Tampoco escribas results como la única ruta de obtención de valores exclusiva del cliente. Otras acciones pueden devolver objetos de negocio con nombres diferentes; returns_list indica la forma del objeto y el diccionario de campos explica sus elementos internos, pero ninguno sustituye la confirmación de la estructura de nivel superior de la capacidad elegida. Al añadir una nueva capacidad, asignarle una configuración de adaptación de resultados explícita resulta más fiable que buscar recursivamente el primer vector en todas las respuestas.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=xiaohongshu&action=search' \
  | jq '{fields, undocumented}'

Existen dos detalles en el procesamiento de campos que afectan fácilmente las conclusiones. Primero, una métrica de interacción igual a null indica que no es pública o no está disponible, por lo que no puede rellenarse automáticamente con 0 para participar en un promedio. Segundo, la descripción pública de posted_at permite conservar la cadena de tiempo original de la plataforma; no asumas por defecto que todos los valores se pueden analizar directamente con el mismo formato ISO. Puedes guardar por separado la hora analizada y dejar un estado para los fallos de análisis, en lugar de rellenar una fecha errónea con el día de hoy.

Si la respuesta incluye partial o missed, debes registrar por separado los objetivos no entregados; HTTP 200 no garantiza que cada objetivo de este lote contenga datos. En el caso de un vector vacío, como máximo se puede concluir que no se devolvieron registros en esta ocasión, y no se debe determinar únicamente en función de esto que no existen datos en la plataforma original. Verificar si la solicitud cubrió el objeto correcto y si estuvo sujeta a restricciones de alcance es un asunto distinto.

Paso 4: Las capacidades asíncronas deben esperar al estado final, sin detenerse en job_id

Al cambiar a una capacidad con mode en async, la respuesta de envío puede ser HTTP 202 e incluir status, job_id y poll_url. Persiste primero estos campos antes de iniciar la consulta de la tarea. El código 202 en las especificaciones HTTP indica que la solicitud ha sido aceptada pero su procesamiento aún no ha concluido, por lo que no debe usarse para activar notificaciones de negocio como que el informe ha sido generado.

: "${EVERYINFRA_API_KEY:?configura primero la API Key para esta tarea: API Key}"
: "${EVERYINFRA_JOB_ID:?pega el job_id de la respuesta real de envío}"
curl --silent --show-error --include --max-time 30 \
  "https://api.everyinfra.com/api/v1/jobs/${EVERYINFRA_JOB_ID}" \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}"

La implementación de consulta actual busca la tarea según la clave asociada en el momento del envío. Utiliza la misma clave para consultar, sin asumir que cambiar a otra clave bajo la misma cuenta permitirá recuperar la tarea; tampoco crees inmediatamente otra tarea idéntica si no se encuentra. Puedes verificar primero el dominio de la API, el job_id y la clave empleada, y recurrir a la información de solicitud guardada si es necesario.

• running o finalizing: sigue siendo un estado en proceso. Conserva la tarea y continúa consultando a intervalos limitados.
• succeeded: la tarea entra en el estado final de éxito; a continuación, analiza el objeto de datos de dicha capacidad y verifica si cumple con tus necesidades de negocio.
• failed: entra en el estado final de error, lee error y conserva el registro de la tarea, sin tratarlo como un éxito de datos vacíos.
• Tiempo de espera de consulta agotado o estado desconocido: marca únicamente que no se ha confirmado en esta ocasión. Establece un presupuesto de espera total, déjaselo al flujo de recuperación posterior y no lo cambies arbitrariamente a éxito o fallo.

El sondeador debe contar con un tiempo máximo de espera y el intervalo puede alargarse de forma gradual para evitar un bucle ajustado. Tras reiniciar el programa, restablece la consulta a partir del job_id guardado en lugar de volver a enviar la tarea. Asimismo, guarda por separado el billing del momento del envío: la respuesta de consulta de resultados actual no vuelve a proporcionar el bloque de facturación completo, por lo que no debes deducir que no hubo cobros esta vez simplemente porque billing no aparezca en el resultado de la consulta.

El patrón de solicitud-respuesta asíncrona de Microsoft también separa la aceptación, la consulta de estados y el resultado final, y analiza las pistas de sondeaje. Es adecuado como referencia de diseño para flujos de cliente; las cabeceras Location, Retry-After y similares que contiene no son garantías de devolución de este artículo para EveryInfra, por lo que la consulta real sigue empleando el punto de entrada proporcionado por esta respuesta.

Paso 5: Gestiona las incidencias según su causa, evitando especialmente reintentar POST a ciegas

Los errores de negocio requieren leer simultáneamente el estado HTTP y error.code. La entrada de datos actual comprueba primero la autenticación, luego procesa las capacidades, permisos y parámetros, y solo después accede al flujo de cuotas y ejecución. Ver 401 en ausencia de una clave válida no permite determinar si tus parámetros de negocio ya han superado la validación.

• 401: verifica si la clave existe y es válida, así como si la cabecera Bearer es correcta. No intentes solucionar un fallo de autenticación modificando las palabras clave.
• 403: verifica si esta clave está autorizada para acceder al producto y capacidad de destino. Los problemas de permisos deben ser resueltos por personas con privilegios y no deben alternar cuentas automáticamente.
• 400 unknown_capability: comprueba si platform y action coinciden; vuelve a leer el directorio y revisa los nombres candidatos proporcionados por el servicio.
• 422: comprueba elementos obligatorios, parámetros desconocidos y enumeraciones no válidas. Corrige un punto basándote en la sugerencia de error antes de lanzar una nueva solicitud.
• 402: cuota insuficiente; requiere gestionar el problema de cuota de la cuenta, por lo que enviar repetidamente la misma solicitud no lo solucionará.
• 429, error temporal del servicio o interrupción de red: desacelera primero y determina el estado de la solicitud original. Realiza un reintento con límite de intentos solo cuando confirmes que es idóneo.

El aspecto que se pasa por alto con mayor facilidad es que el cliente se agote por tiempo de espera, pero el servidor ya haya aceptado la solicitud. La obtención de datos puede parecer de solo lectura a nivel de negocio, pero en realidad se inicia mediante POST, lo que podría crear una tarea y generar un cargo. Un identificador de negocio común facilita la correlación de múltiples intentos, pero no se convierte automáticamente en una garantía de idempotencia en el servidor. No añadas por tu cuenta un Idempotency-Key sin un soporte explícito de la interfaz para asumir que las solicitudes repetidas se ejecutarán una sola vez.

La norma RFC 9110 establece restricciones específicas para el reintento automático de solicitudes no idempotentes. Ante tales resultados desconocidos, se debe consultar primero las tareas existentes o verificar los registros de solicitudes; conservar unknown al no obtener información suficiente resulta más seguro que reproducir automáticamente todo el lote.

Paso 6: Almacena por separado los datos, el estado de recolección y la factura

La parte más valiosa de un punto de entrada unificado es permitir que los registros genéricos y el mapeo de campos de la plataforma tengan responsabilidades claras. Se recomienda conservar al menos tres tipos de registros: una tarea de negocio, un intento de API y un objeto de plataforma. De este modo, no solo se puede rastrear cuántos intentos ha experimentado una tarea, sino que también se permite que un mismo contenido se actualice en múltiples recolecciones sin que se cuente como varios objetos nuevos.

• Registro de tareas: tu propio task_id, rango de destino, campos previstos y condiciones de finalización. Dicha finalización está definida por el negocio y no se limita a un éxito HTTP.
• Registro de solicitudes: platform, action, resumen no sensible de parámetros, hora de inicio y fin, id de solicitud de API, job_id, estado y billing. Los intentos fallidos también deben conservarse.
• Registro de objetos: platform, tipo de objeto, id de objeto, enlace de origen, campos obtenidos de manera efectiva y observed_at; no fusiones IDs de diferentes plataformas que coincidan por casualidad.

Estas sugerencias corresponden al modelo de datos de tu aplicación y no a campos que EveryInfra devuelva adicionalmente. observed_at debe ser registrado por el programa de recolección para indicar cuándo observaste el resultado, mientras que posted_at indica la hora de publicación del contenido original. Utilizar ambos tiempos para responder respectivamente cuándo se publicó el contenido y cuándo lo supimos permite analizar datos retrasados y observaciones repetidas.

Al realizar comparaciones multiplataforma, mapea únicamente los campos que el negocio realmente requiera y cuyos significados sean comparables. Los “me gusta”, favoritos, puntuaciones de productos y conteos de comentarios pertenecen a métricas diferentes; renombrarlos unificadamente como score no les otorga la misma magnitud. Para los campos cuya explicación aún se desconoce, mantén el estado faltante o acude al diccionario de campos sin adivinar su unidad y sentido.

La facturación tampoco puede deducirse en función del número de resultados. Las capacidades multiobjetivo facturan por objetivo, por lo que una solicitud HTTP no puede considerarse como una unidad de facturación única; un limit de muestra pequeña no implica necesariamente un descuento por los elementos devueltos. La sincronización actual gestiona las ramas de devolución de cuentas para resultados vacíos y objetivos parciales no entregados, pero tu cliente debe seguir conservando el billing real y los registros de facturación para su verificación; no declares cuentas saldadas por ti mismo basándote únicamente en 200 o en que el vector esté vacío.

Al registrar solicitudes, puedes tomar como referencia el diseño de identificadores de interacción de OWASP: permite relacionar eventos bajo una misma intención de negocio a la vez que excluyes contenidos sensibles como tokens de acceso. Preservar información investigable no equivale a copiar por completo las cabeceras de solicitud y los textos originales en los registros.

Al expandir al segundo platform, qué código vale la pena reutilizar

Puedes reutilizar la inyección de autenticación, la configuración de tiempos de espera, el registro de errores, la programación de consultas de tareas y los registros de seguridad. Las partes que deben conservarse de manera específica según la capacidad son los nombres y semánticas de los parámetros, las rutas de objetos de resultado, el mapeo de campos, las reglas de paginación y las condiciones de finalización. Mantener ambas partes separadas evita que añadir futuras capacidades se convierta en la duplicación de todo un cliente.

Conviene que el directorio admita una caché con tiempo de observación para volver a comprobarlo antes de integrar una nueva capacidad o lanzar una nueva versión. No utilices una caché antigua de forma indefinida ni descargues todo el directorio con cada registro obtenido; establece un ciclo de actualización según la tolerancia del negocio a los cambios, activando una revisión dirigida al encontrar unknown_capability o conflictos de contratos de parámetros.

La paginación y los incrementos exigen especial cautela. Solo debes avanzar según lo estipulado cuando una action específica proporcione claramente parámetros de paginación y señales de finalización; sin cursor, no es posible generar uno arbitrariamente en el lado del cliente. Las consultas repetidas programadas obtienen múltiples observaciones, lo que no equivale automáticamente a un historial completo o a todos los contenidos nuevos. En su primer versión, es preferible declarar explícitamente qué objetivos y ventanas de tiempo se han comprobado, en lugar de plasmar en un informe una cobertura total que no se puede demostrar.

Qué tareas no se adaptan directamente a esta solución

Si necesitas publicar contenidos en nombre de los usuarios, gestionar datos de comerciantes, procesar autorizaciones de cuentas o modificar datos de la plataforma, debes verificar previamente la API oficial y el flujo de autorización correspondientes a dicha plataforma, sin tratar el acceso de lectura de datos públicos como una interfaz de gestión de cuentas. Para contenidos privados, datos restringidos o usos sin autorización, la interfaz unificada no ampliará tus privilegios de acceso.

Incluso si los datos son visibles públicamente, su almacenamiento, análisis y reexposición aún deben evaluarse según las reglas específicas de la plataforma y los propósitos del negocio. Limita el ámbito de la investigación a los objetivos y campos necesarios, controla el tiempo de retención y evita exportar directamente perfiles de autor, enlaces con parámetros de acceso o textos originales a registros públicos. Tener la capacidad técnica de solicitar algo difiere de que el negocio permita usarlo de esa manera; son dos revisiones distintas.

Comienza a partir de un resultado explicable

¿Puedes plantearte cuatro preguntas al concluir la primera ronda de integración? ¿Puedo explicar con claridad la capacidad específica llamada? ¿Puedo rastrear cada dato hasta su origen? ¿Puedo distinguir entre éxito, procesamiento, entrega parcial y resultado desconocido? ¿Puedo explicar el registro y la factura correspondientes si la solicitud falla o se repite?

Una vez que estas cuatro preguntas tengan respuesta, expande las plataformas, incrementa la concurrencia e integra el análisis de modelos. El valor de la API de datos unificada no consiste en hacer desaparecer todas las diferencias, sino en permitirte escribir lógica especializada únicamente allí donde existan divergencias reales entre plataformas. Selecciona primero una capacidad del documento siguiente, revisa una muestra pequeña, guarda los resultados correctamente y da el siguiente paso.