Ligue os seus sistemas ao Marcomm AI

1. 1
   Peça acesso

   Descreva o seu sistema e escolha os dados de que precisa. Cada pedido é analisado.

2. 2
   Crie uma chave

   Depois da aprovação, crie uma chave em Definições > API. A chave é mostrada uma única vez, por isso guarde-a no seu sistema.

3. 3
   Envie um pedido

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

Exemplo de pedido

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

Envie a sua chave como token Bearer em cada pedido. Uma chave pessoal atua como a pessoa que a criou, pelo que 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 rodadas: depois da rotação, a chave antiga continua a funcionar durante 24 horas.

Cada chave tem apenas os âmbitos para os quais a sua aplicação foi aprovada.

news

Resumo de notícias, artigos e meios de comunicação.

crisis

Notícias críticas e incidentes de crise.

approvals

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

content

Leitura de comunicados de imprensa e artigos de blogue.

Os caminhos começam por /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 da aplicação e do Slack e fica registada em nome do dono da chave. Quando o texto contém expressões que exigem confirmação, recebe 409 confirmation_required com os avisos e pode enviar o pedido 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 incluem os cabeçalhos abaixo. Ao exceder o limite, recebe 429 com Retry-After. Para aumentar um limite, peça o aumento em Definições > API. A nossa equipa analisa o pedido.

X-RateLimit-Limit

Pedidos permitidos por minuto.

X-RateLimit-Remaining

Pedidos restantes no minuto atual.

X-RateLimit-Reset

Hora Unix em que a janela do minuto é reposta.

X-RateLimit-Day-Limit

Pedidos permitidos por dia.

X-RateLimit-Day-Remaining

Pedidos restantes hoje.

Retry-After

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

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

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

Cada pedido é assinado. Calcule o HMAC-SHA256 do corpo em bruto do pedido com o seu segredo de assinatura e compare com o cabeçalho X-Marcomm-Signature, no formato sha256=<hex>. Rejeite os pedidos que não coincidam.

A verificar 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);
}