우리 시스템을 Marcomm AI 에 연결하세요

1. 1
   사용 신청

   연결할 시스템을 설명하고 필요한 데이터를 고릅니다. 신청은 하나씩 심사합니다.

2. 2
   키 만들기

   승인되면 설정 > API 에서 키를 만듭니다. 키는 한 번만 보이니 시스템에 보관하세요.

3. 3
   요청 보내기

   키를 Authorization 머리글에 실어 아래 엔드포인트를 부릅니다.

요청 예시

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

요청마다 키를 Bearer 토큰으로 보냅니다. 개인 키는 만든 사람으로 동작해 그 사람의 이름으로 읽고 승인 · 반려할 수 있고, 워크스페이스 키는 관리자가 만들며 읽기만 됩니다. 키에는 만료일과 허용 IP 를 둘 수 있고, 교체하면 옛 키가 24시간 더 동작합니다.

키는 신청이 승인된 범위만 가질 수 있습니다.

news

뉴스 다이제스트, 기사, 매체.

crisis

심각한 뉴스와 위기 사건.

approvals

승인 대기 목록, 그리고 개인 키로 승인 · 반려.

content

보도자료와 블로그 글 읽기.

모든 경로는 /api/v1 로 시작합니다. 읽기는 GET 이고 쿼리 문자열을 받습니다. 응답은 {"data": ...} 모양의 JSON 입니다.

항목에 {"decision": "approve"} 또는 {"decision": "reject", "comment": "..."} 를 보냅니다. 반려에는 사유가 필요합니다. 결정은 앱 · Slack 과 같은 규칙을 따르고 키 주인의 이름으로 기록됩니다. 확인이 필요한 표현이 있으면 경고와 함께 409 confirmation_required 가 오고, "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."}'

한도는 워크스페이스마다 분당 · 일별(UTC)로 정합니다. 모든 응답에 아래 머리글이 붙고, 한도를 넘으면 Retry-After 와 함께 429 가 옵니다. 한도를 올리려면 설정 > API 에서 상향을 요청하세요. 팀이 심사합니다.

X-RateLimit-Limit

분당 허용 호출 수.

X-RateLimit-Remaining

이번 분에 남은 호출 수.

X-RateLimit-Reset

이번 분 구간이 끝나는 Unix 시각.

X-RateLimit-Day-Limit

하루 허용 호출 수.

X-RateLimit-Day-Remaining

오늘 남은 호출 수.

Retry-After

다시 시도하기 전에 기다릴 초. 429 에만 붙습니다.

오류는 {"error": {"code": ..., "message": ...}} 모양의 JSON 으로 돌아옵니다.

알림, 승인 요청, 아침 브리핑을 회사 시스템으로 보낼 수도 있습니다. 설정 > API > 웹훅에서 받는 곳을 추가하세요. 요청은 event(alert · approval · briefing), workspace, title, text, url, data, sentAt 칸을 가진 JSON 입니다. 승인 요청에는 data.kind(press_release · blog · event)와 data.id 가 들어 있어, API 로 내용을 읽고 결정하는 데 쓸 수 있습니다.

요청에는 서명이 붙습니다. 받은 본문 원문에 서명 비밀로 HMAC-SHA256 을 계산해 X-Marcomm-Signature 머리글(sha256=<hex> 모양)과 맞춰 보고, 맞지 않으면 거절하세요.

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