API ouverte des communautés

1. Le forfait de la communauté doit inclure l'accès API

C'est la personne propriétaire de la communauté qui décide, pas celle qui intègre. Le forfait doit comporter la fonctionnalité d'accès API — sinon chaque appel renvoie 22203 — et un quota journalier non nul, faute de quoi chaque appel renvoie 22204.

Inutile de le découvrir en collectionnant les erreurs : /capabilities/get y répond directement, et fonctionne encore dans ces deux cas.

2. Créez une clé dans la console d'administration de la communauté

Administration de la communauté → Intégrations → API Keys → Créer. Une clé, c'est mfk_ suivi de 64 caractères hexadécimaux, et la valeur complète n'est affichée qu'une seule fois : ensuite, seul le préfixe reste visible.

Les portées cochées à la création déterminent les endpoints que la clé peut appeler. Elles ne sont pas modifiables ensuite ; pour en changer, créez une nouvelle clé et révoquez l'ancienne.

Vous pouvez restreindre une clé à une liste d'IP autorisées (adresses seules ou plages CIDR). Les requêtes venues d'ailleurs échouent avec 10007 — le même code qu'une clé invalide, ce qui mérite d'être gardé en tête quand une clé qui marchait hier cesse de fonctionner depuis une nouvelle machine.

Portées

Une ancienne clé ne peut donc pas appeler les nouveaux endpoints — espaces, membres et lecture d'URL signées. Émettez une nouvelle clé avec ces portées cochées. C'est délibéré : personne ne devrait livrer son annuaire de membres parce que la plateforme a sorti une nouvelle fonctionnalité.

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

La clé est à elle seule l'identifiant : gardez-la côté serveur. Elle n'a sa place ni dans du code navigateur ni dans un bundle mobile, où quiconque peut la lire et publier à la place de vos membres.

• Tous les endpoints sont en POST. Il n'y a ni GET, ni PUT, ni DELETE — les lectures aussi sont des POST.
• Envoyez Content-Type: application/json. Les endpoints sans paramètre attendent quand même un corps JSON vide.
• Tous les identifiants sont des chaînes hashid comme "kZ3mQ9x" — communauté, utilisateur, publication, espace et média compris. Les identifiants numériques sont rejetés.
• Les horodatages sont renvoyés en RFC3339, par exemple 2026-08-18T10:00:00Z.
• Les montants sont des entiers dans la plus petite unité monétaire (centimes).
• Un en-tête Accept-Language facultatif (zh, en, ja, ko, es, fr, de, pt) localise les messages d'erreur.
• La communauté est déduite de votre clé d'API. N'envoyez pas d'identifiant de site, ni dans le chemin ni dans le corps.

Succès et échec partagent la même enveloppe

{
  "code": 0,
  "msg": "success",
  "data": { }
}

curl -X POST https://api.mateflow.com/site_open_api/v1/capabilities/get \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" -d '{}'

# → data: {
#     "api_version": "v1",
#     "site_id": "kZ3mQ9x",
#     "scopes": ["site.read", "content.read"],
#     "api_access": true,
#     "quota_limit": 5000,     // -1 means unlimited
#     "quota_used": 128,
#     "quota_reset_at": "2026-09-15T00:00:00Z"
#   }

• Les lectures qui prennent une liste d'identifiants plafonnent à 50, et limit plafonne aussi à 50 sur tous les endpoints paginés.
• Sur /space/feed/list, l'encodage du curseur suit sort : changer de tri impose donc de reprendre la pagination. Les espaces questions-réponses ignorent sort et s'ordonnent selon qa_sort. Les nouvelles intégrations devraient utiliser /space/feed/list avec sort=top plutôt que /space/feed/top.
• Les réponses membre sont une projection étroite : id, username, display_name, avatar_url, status, role et created_at. L'e-mail n'est jamais renvoyé, même quand c'est par lui que vous avez cherché — vous détenez déjà cette adresse, et renvoyer celle de chaque membre transformerait /member/get en export de carnet d'adresses. La recherche est strictement exacte, et ne rien trouver est un succès normal et non une erreur : les résultats trouvés et non trouvés sont indiscernables, tant par le code de statut que par le temps de réponse. C'est aussi la limite de débit la plus stricte de l'API.

• author_user_id

  Le membre au nom duquel la nouvelle publication paraît. Il doit déjà appartenir à cette communauté, sinon 20303.

• actor_user_id

  Qui effectue une modification ou une suppression. Les droits sont évalués sur ce membre — quelqu'un qui n'est ni l'auteur ni administrateur obtient 10004.

• viewer_user_id

  Facultatif en lecture. Renvoie les résultats tels que ce membre les voit : espaces privés, état des mentions j'aime et des favoris. Omettez-le pour la vue anonyme, publique uniquement.

• Les fils et les listes renvoient leurs éléments accompagnés de next_cursor. Renvoyez next_cursor tel quel pour obtenir la page suivante ; un next_cursor vide signifie que vous êtes arrivé au bout.
• limit plafonne à 50 partout.
• Sur /space/feed/list, le curseur encode le tri en cours. Changer sort en cours de liste l'invalide — repartez de la première page.

• idempotency_key est obligatoire sur chaque écriture et plafonné à 190 caractères. Le réutiliser ne crée jamais de deuxième publication.
• Sa portée, c'est la communauté, le type de requête et la clé pris ensemble, indépendamment de la clé d'API utilisée : deux clés distinctes d'une même communauté qui envoient le même idempotency_key au même endpoint, et le second appel rejoue le résultat du premier.
• La même clé avec un corps différent renvoie une erreur de conflit stable, au lieu de passer silencieusement pour une nouvelle tentative réussie.
• Quand une requête expire, réessayez avec la même clé — n'en générez jamais une nouvelle.

• scheduled_at est un horodatage Unix i64 en secondes — et non la chaîne RFC3339 qu'utilisent toutes les autres dates.
• Sur /post/update, omettre scheduled_at laisse la programmation existante intacte. Ce n'est pas un effacement.

1. Échangez votre clé d'API contre un jeton d'envoi de courte durée via /media/get_token.
2. Envoyez le fichier en multipart au service de médias, avec le jeton dans un en-tête littéralement nommé "token" et file_cate valant Media, Avatar, Header, Audio ou File.
3. Passez l'identifiant de média renvoyé dans media_ids au moment de créer la publication.

# 1. Exchange the API key for a short-lived upload token.
#    Since 2026-09 a token with no explicit scope is upload-only.
curl -X POST https://api.mateflow.com/site_open_api/v1/media/get_token \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id": "kZ3mQ9x", "scope": "upload"}'

# 2. Upload the file to the media service (token goes in a "token" header)
curl -X POST https://media.mateflow.com/api/v1/media/upload \
  -H "token: <token from step 1>" \
  -F "file_cate=Media" -F "file=@photo.jpg"

# 3. Attach the media id when creating the post
curl -X POST https://api.mateflow.com/site_open_api/v1/post/create \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id":"kZ3mQ9x","idempotency_key":"6f1c...","body":"Hi","media_ids":["m8Yq2Lp"]}'

Les médias privés se lisent via /media/get_signed_urls, qui prend les items et un access_level valant 1 (public), 2 (semi-privé) ou 3 (privé) et renvoie des URL avec expiration. Demandez-les à la demande plutôt que de les stocker, sinon elles finiront par renvoyer 403.

Joindre des médias à une publication

• Envoyez soit medias — une liste de paires media_id et alt — soit media_ids, une simple liste d'identifiants. Envoyer les deux renvoie 10005.
• alt est facultatif. Une chaîne vide efface le texte alternatif existant ; omettre le champ le laisse tel quel.

Les réponses d'erreur portent un request_id. Citez-le quand vous signalez un problème : c'est ainsi que nous retrouvons votre appel exact dans les journaux.

Les erreurs de forfait portent des métadonnées structurées

Les deux erreurs de forfait reviennent avec assez de détails pour dire à la personne propriétaire quoi faire, ce qui vous permet d'afficher un vrai message plutôt qu'un « une erreur est survenue ».

// The plan does not include API access
{
  "code": 22203,
  "msg": "...",
  "request_id": "00de5640-8ae5-4a71-aef8-2f2cab0ce8a7",
  "data": {
    "error_code": "feature_not_available",
    "feature": "api_access",
    "required_plan": "Growth"
  }
}

// The community is out of daily quota
{
  "code": 22204,
  "data": {
    "error_code": "quota_exceeded",
    "resource": "api_requests_per_day",
    "current": "5001",
    "limit": "5000",
    "required_plan": "Business"
  }
}

Le quota journalier compte les requêtes qui passent l'authentification, se réinitialise à 00:00 UTC, et indique dans data.limit le plafond réellement en vigueur — y compris une enveloppe relevée spécifiquement pour cette communauté. Quand le backend du compteur se comporte mal, la requête passe au lieu d'être rejetée : un comptage occasionnellement bas ne signifie donc pas que le quota a cessé de fonctionner.

Budget de rafale par clé (nouveau en septembre 2026)

Auparavant, le seul seau était par IP : plusieurs clients derrière une même adresse de sortie se disputaient la place, tandis qu'un appelant réparti sur de nombreuses adresses n'était presque pas contraint. Le budget est désormais échelonné par clé — la chose qu'une personne propriétaire émet, peut faire tourner, et dont elle répond.

member/lookup est nettement plus strict pour des raisons de sécurité, pas de capacité. Ses autres contraintes limitent ce qu'une seule réponse révèle ; celle-ci limite le nombre de fois où vous pouvez poser la question — et c'est précisément l'étape qui transforme une recherche en moisson d'annuaire. Pour l'usage prévu, résoudre au rythme humain des adresses que vous détenez déjà, dix par minute suffisent largement.

• Un dépassement renvoie HTTP 429 avec code 10202, plus Retry-After et les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.
• Prenez ces chiffres comme un point de départ et non comme une mesure : ils sont ajustés d'après le trafic observé. Ne les figez pas dans votre logique de réessai ; respectez le 429 et Retry-After. Toute la couche de limitation est désactivée par défaut et tourne un moment en mode observation avant d'être appliquée.
• Implémentez de toute façon un backoff sur 429, et maintenez le trafic de lecture à environ dix requêtes par seconde au plus.

Dédupliquez sur event_id. Une livraison que vous avez traitée correctement mais à laquelle vous avez répondu trop lentement revient avec un nouveau delivery_id et le même event_id. Quand un même événement part à la fois vers un webhook maison et vers un Zap, les deux côtés voient le même event_id : vous pouvez donc les rapprocher.

La livraison est au moins une fois et peut arriver dans le désordre. Les doublons comme les arrivées tardives d'événements anciens sont normaux ; c'est au récepteur d'être idempotent.

• La communauté est déduite de votre clé d'API. N'envoyez pas d'identifiant de site, ni dans le chemin ni dans le corps.
• Les portées sont figées à la création de la clé. Pour en changer, créez une nouvelle clé et révoquez l'ancienne.
• Gardez vos clés d'API côté serveur. Une clé dans du code client permet à quiconque la lit de publier à la place de vos membres.
• Le contrat OpenAPI couvre chaque chemin et chaque schéma. Une réserve : le générateur dont il provient n'émet pas required sur les corps de requête, prenez donc les champs obligatoires sur cette page plutôt que dans le contrat.