Seguridad y errores - Social media studio

Proteger las claves de socio

Las claves de socio autorizan operaciones a nivel de proyecto. Guárdalas en un gestor de secretos del lado del servidor o en una variable de entorno cifrada, e inyéctalas solo en procesos de backend de confianza.

Nunca envíes una clave de socio a tu frontend como configuración, respuesta de API, parámetro de consulta o variable de entorno renderizada. Tu backend debe exponer endpoints acotados que autoricen al cliente con sesión iniciada antes de llamar a Social media studio.

Usa claves pk_test_ durante el desarrollo y claves pk_live_ solo en producción. Mantén separados los proyectos de prueba y de producción, rota las claves periódicamente y revoca una clave de inmediato si pudo haberse expuesto.

Autorizar cada operación de cliente

El SDK autentica a tu aplicación, no al cliente que usa tu producto. Antes de cada llamada al SDK:

Autentica al cliente en tu aplicación.
Resuelve en tu servidor el endUserId de Social media studio almacenado para ese cliente.
Verifica que los ID de conexión y de publicación solicitados pertenecen a ese cliente.
Llama al SDK con esos ID resueltos en el servidor.

Nunca aceptes un endUserId arbitrario desde un navegador ni lo pases sin comprobar la propiedad en tu base de datos.

Ámbitos de las claves

Las claves de socio pueden restringirse a las capacidades que necesita un servicio:

Recurso	Ámbito de lectura	Ámbito de escritura
Usuarios finales	`end_users:read`	`end_users:write`
Conexiones	`connections:read`	`connections:write`
Sesiones de conexión	`connect_sessions:read`	`connect_sessions:write`
Publicaciones	`posts:read`	`posts:write`
Multimedia	—	`media:write`
Webhooks	`webhooks:read`	`webhooks:write`

Siempre que sea posible, usa claves distintas y con los mínimos privilegios para servicios independientes.

Gestionar los errores del SDK

Toda solicitud de API fallida lanza SoMePlatformError:

import {
  SoMePlatformError,
  SoMePlatformClient,
} from "@social-media-scheduler/sdk";

try {
  await soMe.posts.get(endUserId, postId);
} catch (error) {
  if (error instanceof SoMePlatformError) {
    logger.error("Social media studio request failed", {
      status: error.status,
      details: error.details,
    });
  }
  throw error;
}

Estado	Significado	Gestión recomendada
`0`	Error de red, fallo de DNS o tiempo de espera agotado	Reintenta con espera creciente cuando sea seguro
`400`	Entrada no válida, plataforma que no coincide o URL de retorno no permitida	Corrige la solicitud; no la reintentes sin cambios
`401`	Clave de socio ausente, no válida, caducada o revocada	Detente y rota o sustituye la clave
`403`	La clave carece de un ámbito necesario	Usa una clave con los ámbitos correctos
`404`	El recurso no existe en este proyecto o usuario final	Concilia los ID almacenados
`409`	El espacio de trabajo del cliente no está listo	Reintenta tras resolver el estado indicado
`429`	Se alcanzó el límite de solicitudes	Respeta la indicación de reintento y usa espera exponencial
`5xx`	Fallo temporal del servicio de Social media studio	Reintenta con espera exponencial acotada

En la creación de publicaciones, los reintentos son seguros solo si reutilizas la misma clave de idempotencia. No reintentes a ciegas otras operaciones de escritura a menos que tu aplicación pueda confirmar su resultado.

Registro

Registra el contexto de la solicitud, como el ID de tu cliente, el ID del usuario final, la operación, el estado HTTP y la clave de idempotencia. No registres claves de socio completas, secretos de webhook, tokens de OAuth, URL de subida prefirmadas ni metadatos sensibles de clientes.

​Proteger las claves de socio

​Autorizar cada operación de cliente

​Ámbitos de las claves

​Gestionar los errores del SDK

​Registro

Proteger las claves de socio

Autorizar cada operación de cliente

Ámbitos de las claves

Gestionar los errores del SDK

Registro