API aberta de comunidades

1. O plano da comunidade precisa incluir acesso à API

Quem controla isso é a pessoa dona da comunidade, não quem integra. O plano precisa do recurso de acesso à API — caso contrário toda chamada devolve 22203 — e de uma cota diária diferente de zero; senão toda chamada devolve 22204.

Você não precisa descobrir isso acumulando erros: /capabilities/get responde diretamente e continua funcionando nesses dois estados.

2. Crie uma chave no console de administração da comunidade

Administração da comunidade → Integrações → API Keys → Criar. Uma chave é mfk_ seguido de 64 caracteres hexadecimais, e o valor completo aparece exatamente uma vez — depois só o prefixo fica visível.

Os escopos marcados na criação decidem quais endpoints a chave pode chamar. Não é possível editá-los depois; para mudar, crie uma nova chave e revogue a antiga.

Opcionalmente restrinja uma chave a uma lista de IPs permitidos (endereços isolados ou faixas CIDR). Requisições de qualquer outro lugar falham com 10007 — o mesmo código de uma chave inválida, o que vale lembrar quando uma chave que funcionava ontem para de funcionar a partir de outro host.

Escopos

Por isso uma chave antiga não consegue chamar os endpoints mais novos — espaços, membros e leitura de URLs assinadas. Emita uma chave nova com esses escopos marcados. É deliberado: ninguém deveria entregar seu diretório de membros só porque a plataforma lançou um recurso.

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

A chave por si só é a credencial — guarde-a no servidor. Ela não pertence nem ao código do navegador nem a um pacote móvel, onde qualquer pessoa pode lê-la e publicar como se fosse seus membros.

• Todos os endpoints são POST. Não há GET, PUT nem DELETE — as leituras também são POST.
• Envie Content-Type: application/json. Os endpoints que não recebem parâmetros ainda assim esperam um corpo JSON vazio.
• Todo id é uma string hashid como "kZ3mQ9x" — comunidade, usuário, publicação, espaço e mídia igualmente. Ids numéricos são rejeitados.
• Os carimbos de tempo voltam em RFC3339, por exemplo 2026-08-18T10:00:00Z.
• Os valores monetários são inteiros na menor unidade da moeda (centavos).
• Um cabeçalho Accept-Language opcional (zh, en, ja, ko, es, fr, de, pt) traduz as mensagens de erro.
• A comunidade é deduzida da sua chave de API. Não envie um id de site nem no caminho nem no corpo.

Sucesso e falha compartilham um mesmo envelope

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

• As leituras que recebem uma lista de ids param em 50, e o limit de todos os endpoints paginados também para em 50.
• Em /space/feed/list a codificação do cursor acompanha o sort, então trocar a ordenação significa reiniciar a paginação. Espaços de perguntas e respostas ignoram sort e ordenam por qa_sort. Integrações novas devem usar /space/feed/list com sort=top em vez de /space/feed/top.
• As respostas de membro são uma projeção estreita: id, username, display_name, avatar_url, status, role e created_at. O e-mail nunca é devolvido, mesmo quando foi por ele que você pesquisou — você já tem esse endereço, e devolver o de cada membro transformaria /member/get em uma exportação de contatos. A busca é apenas por correspondência exata, e não achar nada é um sucesso normal, não um erro, de modo que acertos e falhas não se distinguem nem pelo código de status nem pelo tempo de resposta. É também o limite de taxa mais rígido da API.

• author_user_id

  O membro em nome de quem a nova publicação sai. Precisa já pertencer a esta comunidade; caso contrário, 20303.

• actor_user_id

  Quem executa uma edição ou exclusão. A permissão é avaliada sobre esse membro — quem não é autor nem administrador recebe 10004.

• viewer_user_id

  Opcional nas leituras. Devolve os resultados como esse membro os vê: espaços privados, estado de curtidas e favoritos. Omita para a visão anônima, apenas pública.

• Feeds e listas devolvem seus itens junto com next_cursor. Envie next_cursor de volta sem alterações para buscar a próxima página; um next_cursor vazio significa que você chegou ao fim.
• limit para em 50 em todo lugar.
• Em /space/feed/list o cursor codifica a ordenação atual. Mudar sort no meio da listagem o invalida — volte para a primeira página.

• idempotency_key é obrigatório em toda escrita e limitado a 190 caracteres. Reutilizar um nunca cria uma segunda publicação.
• Seu escopo é a comunidade, o tipo de requisição e a chave em conjunto, independentemente de qual chave de API você usou: duas chaves diferentes da mesma comunidade enviando o mesmo idempotency_key ao mesmo endpoint fazem a segunda chamada repetir o resultado da primeira.
• A mesma chave com um corpo diferente devolve um erro de conflito estável, em vez de passar silenciosamente como uma retentativa bem-sucedida.
• Quando uma requisição expira, tente de novo com a mesma chave — nunca gere uma nova.

• scheduled_at é um carimbo Unix i64 em segundos — não a string RFC3339 que todos os outros horários usam.
• Em /post/update, omitir scheduled_at deixa o agendamento existente intacto. Não é uma limpeza.

1. Troque sua chave de API por um token de envio de curta duração em /media/get_token.
2. Envie o arquivo por POST como multipart ao serviço de mídia, com o token em um cabeçalho literalmente chamado "token" e file_cate definido como Media, Avatar, Header, Audio ou File.
3. Passe o id de mídia devolvido em media_ids ao criar a publicação.

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

A mídia privada é lida por /media/get_signed_urls, que recebe os items e um access_level de 1 (público), 2 (semiprivado) ou 3 (privado) e devolve URLs com validade. Peça-as quando precisar em vez de armazená-las, ou elas passarão a devolver 403.

Anexar mídia a uma publicação

• Envie ou medias — uma lista de pares media_id e alt — ou media_ids, uma lista simples de ids. Enviar os dois devolve 10005.
• alt é opcional. Uma string vazia limpa o texto alternativo existente; omitir o campo o mantém como estava.

As respostas de erro trazem um request_id. Cite-o ao relatar um problema — é assim que encontramos exatamente a sua chamada nos registros.

Os erros de plano trazem metadados estruturados

Os dois erros de plano voltam com detalhe suficiente para dizer a quem é dono da comunidade o que fazer, para você mostrar uma mensagem de verdade em vez de «algo deu errado».

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

A cota diária conta as requisições que passam pela autenticação, reinicia às 00:00 UTC e informa em data.limit o teto realmente em vigor — incluindo qualquer folga concedida especificamente àquela comunidade. Quando o backend do contador falha, a requisição passa em vez de ser recusada, então uma contagem ocasionalmente baixa não significa que a cota parou de funcionar.

Orçamento de rajada por chave (novo em setembro de 2026)

Antes o único balde era por IP, então vários clientes atrás do mesmo endereço de saída disputavam espaço entre si, enquanto quem espalhava as chamadas por muitos endereços mal era restringido. Agora o orçamento é escalonado por chave — aquilo que quem é dono emite, pode rotacionar e por que responde.

member/lookup é bem mais rígido por segurança, não por capacidade. As outras restrições limitam quanto uma única resposta revela; esta limita quantas vezes você pode perguntar — e é justamente esse o passo que transforma a busca em coleta de diretório. Usado como foi pensado, resolvendo no ritmo de uma pessoa endereços que você já tem, dez por minuto sobram.

• Ultrapassar devolve HTTP 429 com code 10202, mais Retry-After e os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
• Trate esses números como ponto de partida, não como medição — eles são ajustados conforme o tráfego observado. Não os fixe na sua lógica de retentativa; respeite o 429 e o Retry-After. Toda a camada de limite de taxa vem desligada por padrão e roda um tempo em modo de observação antes de ser aplicada.
• Implemente recuo em 429 de qualquer forma, e mantenha o tráfego de leitura em cerca de dez requisições por segundo ou menos.

Deduplique pelo event_id. Uma entrega que você processou bem mas respondeu devagar demais chega de novo com um delivery_id novo e o mesmo event_id. Quando um evento vai ao mesmo tempo para um webhook próprio e para um Zap, os dois lados veem o mesmo event_id, então dá para cruzá-los.

A entrega é pelo menos uma vez e pode chegar fora de ordem. Tanto duplicatas quanto a chegada tardia de eventos antigos são normais; quem recebe precisa ser idempotente.

• A comunidade é deduzida da sua chave de API. Não envie um id de site nem no caminho nem no corpo.
• Os escopos ficam fixos quando a chave é criada. Para mudá-los, crie uma chave nova e revogue a antiga.
• Guarde suas chaves de API no servidor. Uma chave em código de cliente permite que qualquer pessoa que a leia publique como se fosse seus membros.
• O contrato OpenAPI cobre cada caminho e cada esquema. Uma ressalva: o gerador de onde ele vem não emite required nos corpos de requisição, então tire os campos obrigatórios desta página e não do contrato.