API abierta de comunidades

1. El plan de la comunidad tiene que incluir acceso a la API

Esto lo controla quien sea propietario de la comunidad, no quien integra. El plan necesita la función de acceso a la API — si no, cada llamada devuelve 22203 — y una cuota diaria distinta de cero; de lo contrario cada llamada devuelve 22204.

No hace falta descubrirlo acumulando errores: /capabilities/get lo responde directamente, y sigue funcionando en esos dos estados.

2. Crea una clave en la consola de administración de la comunidad

Administración de la comunidad → Integraciones → API Keys → Crear. Una clave es mfk_ seguido de 64 caracteres hexadecimales, y el valor completo se muestra exactamente una vez: después solo verás el prefijo.

Los ámbitos que marques al crearla deciden a qué endpoints puede llamar. No se pueden editar después; para cambiarlos, crea una clave nueva y revoca la anterior.

Opcionalmente puedes restringir una clave a una lista de IP permitidas (direcciones sueltas o rangos CIDR). Las peticiones desde cualquier otro sitio fallan con 10007, el mismo código que una clave inválida, algo que conviene recordar cuando una clave que ayer funcionaba deja de hacerlo desde otro host.

Ámbitos

Por eso una clave antigua no puede llamar a los endpoints nuevos: espacios, miembros y lectura de URL firmadas. Emite una clave nueva con esos ámbitos marcados. Es deliberado: nadie debería entregar su directorio de miembros porque la plataforma haya lanzado una función nueva.

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

La clave es la credencial en sí misma: guárdala en el servidor. No debe estar ni en código de navegador ni en un paquete móvil, donde cualquiera puede leerla y publicar como tus miembros.

• Todos los endpoints son POST. No hay GET, PUT ni DELETE: las lecturas también son POST.
• Envía Content-Type: application/json. Los endpoints que no reciben parámetros siguen esperando un cuerpo JSON vacío.
• Todos los id son cadenas hashid como "kZ3mQ9x": comunidad, usuario, publicación, espacio y medio por igual. Los id numéricos se rechazan.
• Las marcas de tiempo se devuelven en RFC3339, por ejemplo 2026-08-18T10:00:00Z.
• Los importes son enteros en la unidad monetaria más pequeña (céntimos).
• Una cabecera opcional Accept-Language (zh, en, ja, ko, es, fr, de, pt) traduce los mensajes de error.
• La comunidad se deduce de tu clave de API. No envíes un id de sitio ni en la ruta ni en el cuerpo.

El éxito y el fallo comparten un mismo sobre

{
  "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"
#   }

• Las lecturas que aceptan una lista de id se topan en 50, y el limit de todos los endpoints paginados también se topa en 50.
• En /space/feed/list la codificación del cursor sigue a sort, así que cambiar de orden implica reiniciar la paginación. Los espacios de preguntas y respuestas ignoran sort y ordenan por qa_sort. Las integraciones nuevas deberían usar /space/feed/list con sort=top en lugar de /space/feed/top.
• Las respuestas de miembro son una proyección estrecha: id, username, display_name, avatar_url, status, role y created_at. El correo nunca se devuelve, ni siquiera cuando has buscado por él: esa dirección ya la tienes, y devolver la de cada miembro convertiría /member/get en una exportación de contactos. La búsqueda es solo por coincidencia exacta, y no encontrar nada es un éxito normal, no un error, así que los aciertos y los fallos no se distinguen ni por código de estado ni por tiempo de respuesta. También tiene el límite de tasa más estricto de la API.

• author_user_id

  El miembro con el que se publica la nueva publicación. Debe pertenecer ya a esta comunidad; si no, 20303.

• actor_user_id

  Quién ejecuta una edición o un borrado. El permiso se evalúa contra este miembro: quien no sea autor ni administrador recibe 10004.

• viewer_user_id

  Opcional en las lecturas. Devuelve los resultados tal como los ve ese miembro: espacios privados, estado de «me gusta» y de guardado. Omítelo para la vista anónima, solo pública.

• Los feeds y las listas devuelven sus elementos junto a next_cursor. Devuelve next_cursor tal cual para pedir la página siguiente; un next_cursor vacío significa que has llegado al final.
• limit se topa en 50 en todas partes.
• En /space/feed/list el cursor codifica el orden actual. Cambiar sort a mitad del listado lo invalida: vuelve a la primera página.

• idempotency_key es obligatorio en cada escritura y se topa en 190 caracteres. Reutilizar uno nunca crea una segunda publicación.
• Su ámbito es la comunidad, el tipo de petición y la clave juntos, con independencia de qué clave de API uses: si dos claves distintas de la misma comunidad envían el mismo idempotency_key al mismo endpoint, la segunda llamada repite el resultado de la primera.
• La misma clave con un cuerpo distinto devuelve un error de conflicto estable en lugar de colar en silencio como un reintento correcto.
• Si una petición expira, reintenta con la misma clave; nunca generes una nueva.

• scheduled_at es una marca de tiempo Unix i64 en segundos, no la cadena RFC3339 que usan todas las demás fechas.
• En /post/update, omitir scheduled_at deja la programación existente intacta. No es un borrado.

1. Cambia tu clave de API por un token de subida de corta vida en /media/get_token.
2. Envía el archivo por POST como multipart al servicio de medios, con el token en una cabecera llamada literalmente "token" y file_cate con uno de estos valores: Media, Avatar, Header, Audio o File.
3. Pasa el id de medio devuelto en media_ids al crear la publicación.

# 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"]}'

Los medios privados se leen con /media/get_signed_urls, que recibe los items y un access_level de 1 (público), 2 (semiprivado) o 3 (privado) y devuelve URL con caducidad. Pídelas cuando las necesites en lugar de guardarlas, o empezarán a devolver 403.

Adjuntar medios a una publicación

• Envía o bien medias —una lista de pares media_id y alt— o bien media_ids, una lista simple de id. Enviar ambos devuelve 10005.
• alt es opcional. Una cadena vacía borra el texto alternativo existente; omitir el campo lo deja como estaba.

Las respuestas de error llevan un request_id. Cítalo al reportar un problema: es lo que nos permite encontrar exactamente tu llamada en los registros.

Los errores de plan llevan metadatos estructurados

Ambos errores de plan vuelven con detalle suficiente para decirle a la persona propietaria qué hacer, de modo que puedas mostrar un mensaje útil en lugar de «algo ha salido mal».

// 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"
  }
}

La cuota diaria cuenta las peticiones que superan la autenticación, se reinicia a las 00:00 UTC e informa en data.limit del techo realmente vigente, incluida cualquier ampliación concedida a esa comunidad en concreto. Si el backend del contador falla, la petición pasa en lugar de rechazarse, así que un recuento bajo ocasional no significa que la cuota haya dejado de funcionar.

Presupuesto de ráfaga por clave (nuevo en septiembre de 2026)

Antes el único cubo era por IP, de modo que varios clientes tras una misma dirección de salida competían entre sí mientras que quien repartía sus llamadas entre muchas direcciones apenas tenía restricciones. Ahora el presupuesto se escalona por clave: lo que quien es propietario emite, puede rotar y de lo que responde.

member/lookup es mucho más estricto por seguridad, no por capacidad. Sus otras restricciones limitan cuánto revela una sola respuesta; esta limita cuántas veces puedes preguntar, y ese es justo el paso que convierte una búsqueda en una recolección de directorio. Usado como está pensado —resolver al ritmo de una persona direcciones que ya tienes—, diez por minuto sobran.

• Superarlo devuelve HTTP 429 con code 10202, además de Retry-After y las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.
• Toma estas cifras como punto de partida, no como una medición: se ajustan según el tráfico observado. No las fijes en tu lógica de reintentos; respeta el 429 y Retry-After. Toda la capa de límite de tasa está desactivada por defecto y funciona un tiempo en modo observación antes de aplicarse.
• Implementa el retroceso ante 429 en cualquier caso, y mantén el tráfico de lectura en torno a diez peticiones por segundo o menos.

Deduplica por event_id. Una entrega que procesaste bien pero contestaste demasiado tarde vuelve a llegar con un delivery_id nuevo y el mismo event_id. Cuando un evento va a la vez a un webhook propio y a un Zap, ambos lados ven el mismo event_id, así que puedes cuadrarlos.

La entrega es al menos una vez y puede llegar desordenada. Tanto los duplicados como la llegada tardía de eventos antiguos son normales; quien recibe tiene que ser idempotente.

• La comunidad se deduce de tu clave de API. No envíes un id de sitio ni en la ruta ni en el cuerpo.
• Los ámbitos se fijan al crear la clave. Para cambiarlos, crea una clave nueva y revoca la anterior.
• Guarda tus claves de API en el servidor. Una clave en código de cliente permite a cualquiera que la lea publicar como tus miembros.
• El contrato OpenAPI cubre cada ruta y cada esquema. Un matiz: el generador del que procede no emite required en los cuerpos de petición, así que toma los campos obligatorios de esta página y no del contrato.