Conecte seus sistemas ao Marcomm AI

1. 1
   Peça acesso

   Descreva seu sistema e escolha os dados de que precisa. Cada pedido passa por análise.

2. 2
   Crie uma chave

   Depois da aprovação, crie uma chave em Configurações > API. A chave aparece uma única vez, então guarde-a no seu sistema.

3. 3
   Envie uma requisição

   Envie a chave no cabeçalho Authorization e chame um dos endpoints abaixo.

Exemplo de requisição

curl https://app.marcomm.works/api/v1/news/digest?days=7 \
  -H "Authorization: Bearer mc_live_..."

Envie sua chave como token Bearer em cada requisição. Uma chave pessoal age como a pessoa que a criou, então pode ler e decidir aprovações em nome dela. Uma chave do espaço de trabalho é criada por um administrador e só pode ler. As chaves podem expirar, ser limitadas a endereços IP e ser rotacionadas: depois da rotação, a chave antiga continua funcionando por 24 horas.

Cada chave carrega apenas os escopos para os quais seu aplicativo foi aprovado.

news

Resumo de notícias, artigos e veículos.

crisis

Notícias críticas e incidentes de crise.

approvals

Aprovações pendentes e a aprovação ou rejeição delas com uma chave pessoal.

content

Leitura de press releases e posts de blog.

Os caminhos começam com /api/v1. Os endpoints de leitura usam GET e aceitam parâmetros de consulta. A resposta é um JSON no formato {"data": ...}.

Envie {"decision": "approve"} ou {"decision": "reject", "comment": "..."} para o item. Rejeitar exige um comentário. A decisão segue as mesmas regras do app e do Slack e fica registrada em nome do dono da chave. Quando o texto contém expressões que exigem confirmação, você recebe 409 confirmation_required com os avisos, e pode enviar a requisição de novo com "force": true.

curl -X POST https://app.marcomm.works/api/v1/approvals/press-releases/<id> \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision":"reject","comment":"Please fix the headline."}'

Os limites são definidos por espaço de trabalho, por minuto e por dia (UTC). As respostas trazem os cabeçalhos abaixo. Ao passar do limite, você recebe 429 com Retry-After. Para aumentar um limite, peça o aumento em Configurações > API. Nossa equipe analisa o pedido.

X-RateLimit-Limit

Requisições permitidas por minuto.

X-RateLimit-Remaining

Requisições restantes no minuto atual.

X-RateLimit-Reset

Horário Unix em que a janela do minuto é reiniciada.

X-RateLimit-Day-Limit

Requisições permitidas por dia.

X-RateLimit-Day-Remaining

Requisições restantes hoje.

Retry-After

Segundos de espera antes de tentar de novo. Somente em 429.

Os erros retornam JSON no formato {"error": {"code": ..., "message": ...}}.

Alertas, pedidos de aprovação e o briefing da manhã também podem ser enviados ao seu sistema. Adicione um destino em Configurações > API > Webhooks. Cada requisição é um JSON com os campos event (alert, approval ou briefing), workspace, title, text, url, data e sentAt. Um pedido de aprovação traz data.kind (press_release, blog ou event) e data.id, que você pode usar para ler e decidir pela API.

Cada requisição é assinada. Calcule o HMAC-SHA256 do corpo bruto da requisição com seu segredo de assinatura e compare com o cabeçalho X-Marcomm-Signature, no formato sha256=<hex>. Rejeite as requisições que não coincidirem.

Verificando um webhook em Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

export function isFromMarcomm(rawBody: string, signature: string, secret: string) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}