API de publication SosoAPI : authentification, requêtes et résultats

1. S’authentifier depuis votre serveur

Créez une clé API dans SosoAPI App → Settings → Agents & API Access. Stockez-la sous SOSOAPI_API_KEY dans l’environnement du serveur. Les requêtes utilisent Authorization: Bearer <your-key> et Content-Type: application/json. N’intégrez jamais la clé à un site, un bundle mobile, une URL ou un dépôt public.

Tous les points d’accès ci-dessous utilisent POST avec un corps JSON. Les clés et autorisations déléguées des agents sont limitées par leurs capacités, espaces autorisés et l’appartenance actuelle du propriétaire. Les lectures nécessitent agent:operate et au moins viewer ; les écritures de publication nécessitent agent:publish et au moins editor. Une autorisation ne peut élargir les droits du propriétaire.

Utilisez l’espace de travail actuel et les comptes connectés de l’application, ou appelez /identity-api/workspace/list et /identity-api/user/social-accounts/list pour trouver les identifiants autorisés. Ne devinez pas l’identifiant d’espace ou de compte d’un client.

// Node.js 20+; run only on your server.
const apiKey = process.env.SOSOAPI_API_KEY;
if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server");
const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1";

async function sosoPost(path, body) {
  const response = await fetch(apiBase + path, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) {
    const requestId = result.request_id ?? response.headers.get("x-request-id");
    // Handler errors use code/message; schema-validation 400s instead use
    // success:false and error:{name:"ZodError",message:...}.
    // Preserve status, available code and requestId in server diagnostics.
    // Never log the key or an Authorization header.
    throw new Error("SosoAPI " + response.status + " (" +
      (requestId ?? "no request id") + ")");
  }
  return result;
}

2. Carte des points d’accès de publication

Ces chemins sont relatifs à la base API du helper serveur. Récupérez les détails du Scheduled Post pour obtenir sa version actuelle, les actions disponibles et le résultat de publication.

3. Lister et paginer en conservant le périmètre

limit vaut 50 par défaut et accepte 1–200. status facultatif prend une valeur parmi scheduled, publishing, published, failed, expired, needs_reschedule, cancelled ou deleted. scheduled_from et scheduled_to doivent être fournis ensemble comme instants ISO-8601 avec décalage ; la fin doit suivre le début.

next_cursor vaut null ou est un objet contenant scheduled_at et id. Renvoyez cet objet entier comme cursor avec les mêmes espace de travail et filtres. Ce point d’accès n’accepte pas les filtres page, offset, platform ou social_account_id.

await sosoPost("/studio-api/scheduled-posts/list", {
  "workspace_id": "<workspace-uuid>",
  "limit": 50
});

const first = await sosoPost("/studio-api/scheduled-posts/list", {
  workspace_id: "<workspace-uuid>", limit: 50
});
if (first.next_cursor) {
  const next = await sosoPost("/studio-api/scheduled-posts/list", {
    workspace_id: "<workspace-uuid>", limit: 50, cursor: first.next_cursor
  });
  // Consume next.posts; continue only while next_cursor is not null.
}

4. Valider et créer une publication relue

Remplacez chaque valeur de remplacement par des valeurs de votre périmètre autorisé et une heure future. Cet exemple programme une véritable publication texte Threads à l’exécution. Obtenez la confirmation du compte, du contenu et de l’heure par la personne avant l’appel de création.

Définissez provider_payload.platform et les publish_options de cette plateforme. Le serveur vérifie leur correspondance avec le compte sélectionné. Vous pouvez inclure project_id pour enregistrer la provenance de la publication ; le projet n’accorde aucun accès de publication et ne contrôle pas la programmation.

await sosoPost("/studio-api/scheduled-posts/eligibility", {
  "workspace_id": "<workspace-uuid>",
  "include_quota": true,
  "targets": [
    {
      "social_account_id": "<threads-account-uuid>",
      "media": [],
      "provider_payload": {
        "platform": "threads",
        "publish_options": {
          "post_type": "TEXT"
        }
      },
      "draft": {
        "caption": "A reviewed update from our team.",
        "hashtags": [],
        "scheduled_at": "<future-ISO-8601-instant-with-offset>",
        "display_timezone": "Asia/Hong_Kong"
      }
    }
  ]
});

await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});

5. Lire le résultat et annuler en sécurité

Create renvoie { post, deduped }. List renvoie { posts, next_cursor, returned_count }. Get renvoie { post, delivery, actions, attempts, outcomes }. Un post inclut id, status, version, destination, programmation et identité/permalien fournisseur disponibles ; delivery et actions expliquent la progression et les suites autorisées.

Une publication avec status scheduled ou publishing reste en attente. Un résultat final avec status published confirme la publication et inclut les preuves fournisseur disponibles ; le permalien peut manquer. Si le client se déconnecte ou si une réponse tarde, lisez la publication existante avant d’annoncer un résultat.

Avant d’annuler, récupérez les détails et fournissez la version numérique actuelle. Le résultat peut être cancellation_pending pendant que SosoAPI annule une programmation détenue par le fournisseur. Annuler une programmation ne supprime pas une publication déjà diffusée.

await sosoPost("/studio-api/scheduled-posts/get", {
  "id": "<scheduled-post-uuid>"
});

const detail = await sosoPost("/studio-api/scheduled-posts/get", {
  id: "<scheduled-post-uuid>"
});
// Run only after the person confirms cancelling this unpublished post.
await sosoPost("/studio-api/scheduled-posts/cancel", {
  id: detail.post.id, expected_version: detail.post.version
});

6. Idempotence, conflits et écritures incertaines

Utilisez la même idempotency_key pour répéter la même requête de création. Une répétition identique renvoie la publication existante avec deduped=true. Modifier le contenu avec la même clé crée un conflit. Cela empêche les créations en double dans SosoAPI ; cela ne garantit pas une diffusion exactement une fois par le fournisseur.

Pour les mises à jour et actions, fournissez expected_version depuis la dernière réponse détaillée. En cas de conflit, relisez la publication et confrontez votre modification à la nouvelle version. Une réponse perdue justifie de vérifier l’état existant, pas de créer une autre publication avec une nouvelle clé.

Le contrôle de contenu dupliqué peut rejeter une requête distincte ayant le même contenu public normalisé, le même compte et une heure proche. Consultez la référence de publication existante si vous y êtes autorisé et interrogez l’utilisateur avant de modifier la requête. Les lots renvoient un résultat par destination ; certaines peuvent réussir et d’autres échouer.

7. Erreurs, limites de débit et d’intégration

Les erreurs des gestionnaires utilisent une enveloppe avec error, message, code facultatif, retryable, request_id, details facultatif et retry_after_seconds. Les 400 de validation de schéma ont une autre forme : { success: false, error: { name: "ZodError", message: "…" } }. Le message contient actuellement les problèmes de champs sérialisés avec leurs chemins ; ne supposez pas la présence des champs de l’enveloppe du gestionnaire.

Pour diagnostiquer un échec, conservez le statut HTTP, le code d’erreur et l’identifiant de corrélation issu de result.request_id ?? response.headers.get("x-request-id"). Corrigez la requête grâce aux chemins des champs de validation. Pour les erreurs d’authentification ou d’autorisation, corrigez l’identifiant ou l’accès avant de réessayer.

La limite actuelle de studio-api est de 240 requêtes par minute par utilisateur humain et 480 par minute dans le compartiment distinct des identifiants machine de cet utilisateur. Ce sont des plafonds de requêtes, pas un débit de publication ni des quotas de forfait. Les autres points d’accès et fournisseurs ont leurs propres limites. Respectez l’en-tête Retry-After actuel sur 429 ou 503 réessayable ; pas de boucle intensive.

Lisez le statut à intervalles bornés pendant que l’utilisateur suit la publication, ou utilisez la vue d’état en direct de l’application. Cette API ne promet ni webhooks sortants, ni SLA d’abonné, ni fonctionnalités identiques entre plateformes, ni heure de publication fixe.

• Matrice des capacités des plateformes
• Configurer votre propre agent IA