๋„์ž… ๋ฌธ์˜
๋„์ž… ๋ฌธ์˜

๊ฐœ๋ฐœ์ž ยท ๊ณต๊ฐœ API v1

ํŒ€์‚ฌ์ด๋“œ ๊ณต๊ฐœ API ์„ค๋ช…์„œ

๊ทธ๋ฃน์›จ์–ดยทERPยท์ธ์‚ฌ ์‹œ์Šคํ…œ์ด ํŒ€์‚ฌ์ด๋“œ์˜ ๊ตฌ์„ฑ์›ยท๊ณต๊ฐ„(๋ถ€์„œ)ยท๊ทผํƒœ๋ฅผ ์ฝ์–ด ๊ฐ€๋Š” REST API์ž…๋‹ˆ๋‹ค. ์ฝ๊ธฐ ์ „์šฉ์ด๋ฉฐ ๋“ฑ๋กยท์ˆ˜์ •ยท์‚ญ์ œ ์ฐฝ๊ตฌ๋Š” ์—†์Šต๋‹ˆ๋‹ค. ์—…๋ฌด ์•Œ๋ฆผ์„ ๋ฐ›๋Š” ์›นํ›…๊ณผ AI ๋„๊ตฌ์šฉ MCP๋„ ํ•จ๊ป˜ ์ •๋ฆฌํ–ˆ์Šต๋‹ˆ๋‹ค.

๋ฐฉ์‹HTTPS ยท GET ยท JSON(UTF-8)
์ธ์ฆAPI ํ‚ค (X-API-Key)
๋ฐ์ดํ„ฐ ๋ฒ”์œ„ํ‚ค ํ•˜๋‚˜ = ์›Œํฌ์ŠคํŽ˜์ด์Šค ํ•˜๋‚˜
์š”์ฒญ ํ•œ๋„ํ‚ค๋‹น ๊ธฐ๋ณธ ๋ถ„๋‹น 60ํšŒ
์˜ˆ์‹œ ์ฃผ์†Œ
https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1

1. ํ•œ๋ˆˆ์— ๋ณด๊ธฐ

ํ•ญ๋ชฉ๋‚ด์šฉ
๊ธฐ๋ณธ ์ฃผ์†Œ (๊ตฌ์ถ•ํ˜•)https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1
๋ฐฉ์‹HTTPS ยท GET ์ „์šฉ ยท JSON(UTF-8)
์ธ์ฆAPI ํ‚ค (X-API-Key ํ—ค๋” ๋˜๋Š” Authorization: Bearer)
๋ฐ์ดํ„ฐ ๋ฒ”์œ„ํ‚ค๊ฐ€ ๋ฐœ๊ธ‰๋œ ์›Œํฌ์ŠคํŽ˜์ด์Šค ํ•œ ๊ณณ์˜ ๋ฐ์ดํ„ฐ๋งŒ
์š”์ฒญ ํ•œ๋„ํ‚ค ํ•˜๋‚˜๋‹น ๊ธฐ๋ณธ ๋ถ„๋‹น 60ํšŒ

์ฃผ์†Œ์— /serv ๊ฐ€ ๋“ค์–ด๊ฐ‘๋‹ˆ๋‹ค. /serv ์—†์ด ๋ถ€๋ฅด๋ฉด API๊ฐ€ ์•„๋‹ˆ๋ผ ์›น์‚ฌ์ดํŠธ์˜ 404 ํŽ˜์ด์ง€๊ฐ€ ๋Œ์•„์˜ต๋‹ˆ๋‹ค.

์ œ๊ณต ์ฐฝ๊ตฌ๋Š” ๋‹ค์Œ ๋‹ค์„ฏ ๊ฐ€์ง€์ž…๋‹ˆ๋‹ค.

๋ฉ”์„œ๋“œ๊ฒฝ๋กœํ•„์š”ํ•œ ๊ถŒํ•œ ๋ฒ”์œ„์„ค๋ช…
GET/health์—†์Œ (ํ‚ค ๋ถˆํ•„์š”)์„œ๋ฒ„ ์ƒํƒœ ํ™•์ธ
GET/membersmembers:read์›Œํฌ์ŠคํŽ˜์ด์Šค ๊ตฌ์„ฑ์› ๋ชฉ๋ก (๊ฒŒ์ŠคํŠธ ์ œ์™ธ)
GET/spacesspaces:read๊ณต๊ฐ„(๋ถ€์„œยท๋ฐฉ) ๋ชฉ๋ก
GET/spaces/{id}spaces:read๊ณต๊ฐ„ 1๊ฑด
GET/attendancesattendances:read๊ธฐ๊ฐ„๋ณ„ ๊ทผํƒœ ๊ธฐ๋ก

2. ์ฒซ ํ˜ธ์ถœ

โ‘  ์ƒํƒœ ํ™•์ธ (ํ‚ค ์—†์ด)

bash
curl -s https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/health
์‘๋‹ต
{"success":true,"data":{"status":"UP","time":"2026-10-19T14:43:46.414+09:00","build":"unknown"}}

โ‘ก ๊ตฌ์„ฑ์› ์กฐํšŒ (ํ‚ค ํ•„์š”)

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/members?limit=50"

โ‘ข ๊ทผํƒœ ์กฐํšŒ (๊ธฐ๊ฐ„ ํ•„์ˆ˜)

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/attendances?from=2026-10-01&to=2026-10-31"

$JC_API_KEY ์—๋Š” ๋ฐœ๊ธ‰๋ฐ›์€ ํ‚ค(jc_ ๋กœ ์‹œ์ž‘)๋ฅผ ๋„ฃ์Šต๋‹ˆ๋‹ค. ํ‚ค๋ฅผ ์ฝ”๋“œยท์ €์žฅ์†Œยท๋ฉ”์‹ ์ €์— ๋‚จ๊ธฐ์ง€ ๋งˆ์„ธ์š”.

3. ์ธ์ฆ

์•„๋ž˜ ๋‘ ๋ฐฉ์‹ ์ค‘ ํ•˜๋‚˜๋กœ ํ‚ค๋ฅผ ๋ณด๋ƒ…๋‹ˆ๋‹ค. ๋‘˜ ๋‹ค ๋ณด๋‚ด๋ฉด X-API-Key ๊ฐ€ ์šฐ์„ ํ•ฉ๋‹ˆ๋‹ค.

X-API-Key: jc_xxxxxxxxxxxxxxxx
Authorization: Bearer jc_xxxxxxxxxxxxxxxx
  • ํ‚ค๋Š” ํ•ญ์ƒ jc_ ๋กœ ์‹œ์ž‘ํ•ฉ๋‹ˆ๋‹ค. Authorization: Bearer ๋กœ ๋ณด๋‚ธ ๊ฐ’์ด jc_ ๋กœ ์‹œ์ž‘ํ•˜์ง€ ์•Š์œผ๋ฉด ํ‚ค๊ฐ€ ์—†๋Š” ๊ฒƒ์œผ๋กœ ๋ณด๊ณ  401 ์„ ๋Œ๋ ค์ค๋‹ˆ๋‹ค.
  • ํ‚ค๋Š” ๋ฐœ๊ธ‰ํ•  ๋•Œ ํ•œ ๋ฒˆ๋งŒ ์›๋ฌธ์œผ๋กœ ๋ณด์ž…๋‹ˆ๋‹ค. ์„œ๋ฒ„์—๋Š” ๋˜๋Œ๋ฆด ์ˆ˜ ์—†๋Š” ํ˜•ํƒœ(ํ•ด์‹œ)๋กœ๋งŒ ์ €์žฅ๋˜๋ฏ€๋กœ ์žƒ์–ด๋ฒ„๋ฆฌ๋ฉด ๋‹ค์‹œ ๋ฐœ๊ธ‰๋ฐ›์•„์•ผ ํ•ฉ๋‹ˆ๋‹ค.
  • ํ‚ค ์—†์Œ ยท ๋ชจ๋ฅด๋Š” ํ‚ค ยท ํ๊ธฐ๋œ ํ‚ค ยท ๋งŒ๋ฃŒ๋œ ํ‚ค ยท ์—ฐ๋™ ๊ณ„์•ฝ ์ค‘์ง€๋Š” ๋ชจ๋‘ ๊ฐ™์€ 401(JC-4001)์ž…๋‹ˆ๋‹ค. ์–ด๋А ๊ฒฝ์šฐ์ธ์ง€๋Š” ์ผ๋ถ€๋Ÿฌ ์•Œ๋ ค ๋“œ๋ฆฌ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.
  • /health ๋„ ํ‹€๋ฆฐ ํ‚ค๋ฅผ ๋ถ™์—ฌ ๋ณด๋‚ด๋ฉด 401 ์ž…๋‹ˆ๋‹ค. ํ‚ค ์—†์ด ๋ถ€๋ฅด๋ฉด 200์ž…๋‹ˆ๋‹ค.
  • ํ‚ค๊ฐ€ ๊ฐ€๋ฆฌํ‚ค๋Š” ์›Œํฌ์ŠคํŽ˜์ด์Šค๋Š” ๋ฐ”๊ฟ€ ์ˆ˜ ์—†๊ณ , ์š”์ฒญ์— ์›Œํฌ์ŠคํŽ˜์ด์Šค ๋ฒˆํ˜ธ๋ฅผ ๋„ฃ๋Š” ๋งค๊ฐœ๋ณ€์ˆ˜๋„ ์—†์Šต๋‹ˆ๋‹ค.

4. ๊ถŒํ•œ ๋ฒ”์œ„ (scope)

ํ‚ค๋งˆ๋‹ค ํ—ˆ์šฉ๋œ ๋ฒ”์œ„์˜ ์ฐฝ๊ตฌ๋งŒ ๋ถ€๋ฅผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ฒ”์œ„๊ฐ€ ์—†์œผ๋ฉด 403(JC-4003)์ด๋ฉฐ ๋ฉ”์‹œ์ง€์— ํ•„์š”ํ•œ ๋ฒ”์œ„๊ฐ€ ์ ํ˜€ ์˜ต๋‹ˆ๋‹ค.

scope์—ด๋ฆฌ๋Š” ์ฐฝ๊ตฌ
members:readGET /members
spaces:readGET /spaces ยท GET /spaces/{id}
attendances:readGET /attendances

ํ•„์š”ํ•œ ๋ฒ”์œ„๋งŒ ์‹ ์ฒญํ•˜์„ธ์š”(์ตœ์†Œ ๊ถŒํ•œ). ๋ฒ”์œ„๋ฅผ ๋”ํ•˜๋ ค๋ฉด ํ‚ค๋ฅผ ๋‹ค์‹œ ๋ฐœ๊ธ‰๋ฐ›์•„์•ผ ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

5. ์‘๋‹ต ๊ผด

์„ฑ๊ณต

json
{
  "success": true,
  "data": [ ],
  "meta": { "cursor": "bzo1MA", "hasMore": true }
}
  • ๋ชฉ๋ก ์ฐฝ๊ตฌ(membersยทspacesยทattendances)๋Š” data ๊ฐ€ ๋ฐฐ์—ด์ด๊ณ  meta ๊ฐ€ ๋ถ™์Šต๋‹ˆ๋‹ค.
  • ๋‹จ๊ฑด(spaces/{id})ยทhealth ๋Š” meta ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค.
  • ๊ฐ’์ด ์—†๋Š” ํ•„๋“œ๋Š” null ๋กœ ์˜ค์ง€ ์•Š๊ณ  ํ‚ค ์ž์ฒด๊ฐ€ ๋น ์ง‘๋‹ˆ๋‹ค. ยซํ‚ค๊ฐ€ ์—†์œผ๋ฉด ๊ฐ’ ์—†์Œยป์œผ๋กœ ์ฒ˜๋ฆฌํ•˜์„ธ์š”.
  • ์•ž์œผ๋กœ ํ•„๋“œ๊ฐ€ ๋”ํ•ด์งˆ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ชจ๋ฅด๋Š” ํ•„๋“œ๋Š” ๋ฌด์‹œํ•˜์„ธ์š”.

์‹คํŒจ

json
{
  "success": false,
  "error": { "code": "JC-4001", "message": "์œ ํšจํ•œ API ํ‚ค๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค." }
}
  • ํ”„๋กœ๊ทธ๋žจ์ด ๋ถ„๊ธฐํ•  ๋•Œ๋Š” error.code ๋ฅผ ์“ฐ์„ธ์š”. error.message ๋Š” ์‚ฌ๋žŒ์ด ์ฝ๋Š” ์„ค๋ช…์ด๋ผ ๋ฌธ๊ตฌ๊ฐ€ ๋‹ค๋“ฌ์–ด์งˆ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
  • error.detail ์€ ์žˆ์„ ๋•Œ๋งŒ ์˜ต๋‹ˆ๋‹ค(์ฃผ๋กœ ๋งค๊ฐœ๋ณ€์ˆ˜ ๋ˆ„๋ฝยทํ˜•์‹ ์˜ค๋ฅ˜). ์‹คํŒจ ์‘๋‹ต์—๋Š” dataยทmeta ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค.
  • ์ฝ”๋“œ ์ „์ฒด ๋ชฉ๋ก์€ 10. ์˜ค๋ฅ˜ ์ฝ”๋“œ๋ฅผ ๋ณด์„ธ์š”.

6. ์ชฝ ๋‚˜๋ˆ„๊ธฐ

  • ๋ชฉ๋ก์€ limit(ํ•œ ๋ฒˆ์— ๋ฐ›์„ ๊ฐœ์ˆ˜)์™€ cursor(๋‹ค์Œ ์ชฝ ํ‘œ์ง€)๋กœ ๋‚˜๋ˆ  ๋ฐ›์Šต๋‹ˆ๋‹ค.
  • limit ์€ ๊ธฐ๋ณธ 50, ์ตœ๋Œ€ 200์ž…๋‹ˆ๋‹ค. 200๋ณด๋‹ค ํฌ๋ฉด 200์œผ๋กœ, 1๋ณด๋‹ค ์ž‘์œผ๋ฉด 1๋กœ ๋งž์ถฐ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค(์˜ค๋ฅ˜๊ฐ€ ์•„๋‹™๋‹ˆ๋‹ค). ์ˆซ์ž๊ฐ€ ์•„๋‹ˆ๋ฉด 400 ์ž…๋‹ˆ๋‹ค.
  • meta.hasMore ๊ฐ€ true ์ด๋ฉด meta.cursor ๋ฅผ ๊ทธ๋Œ€๋กœ ๋‹ค์Œ ์š”์ฒญ์˜ ?cursor= ์— ๋„ฃ์Šต๋‹ˆ๋‹ค. false ์ด๋ฉด ๋งˆ์ง€๋ง‰ ์ชฝ์ด๊ณ  cursor ํ‚ค๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค.
  • cursor ๋Š” ์†์„ ์•Œ ์ˆ˜ ์—†๋Š” ๋ฌธ์ž์—ด์ž…๋‹ˆ๋‹ค. ํ•ด์„ํ•˜๊ฑฐ๋‚˜ ์ง์ ‘ ๋งŒ๋“ค์ง€ ๋งˆ์„ธ์š”. ํ˜•์‹์ด ํ‹€๋ฆฌ๋ฉด 400 ์ž…๋‹ˆ๋‹ค.
  • ์ •๋ ฌ์€ ๊ณ ์ •์ž…๋‹ˆ๋‹ค. members ๋Š” ๋‹‰๋„ค์ž„์ˆœ(๊ฐ™์œผ๋ฉด memberSeq ์ˆœ), spaces ๋Š” spaceSeq ์ˆœ, attendances ๋Š” attendanceSeq ์ˆœ์ž…๋‹ˆ๋‹ค. ์ชฝ์„ ๋„˜๊ธฐ๋Š” ์‚ฌ์ด์— ๋ฐ์ดํ„ฐ๊ฐ€ ๋ฐ”๋€Œ๋ฉด ์ผ๋ถ€๊ฐ€ ๊ฒน์น˜๊ฑฐ๋‚˜ ๋น ์งˆ ์ˆ˜ ์žˆ์œผ๋‹ˆ, ์ „์ฒด ๋™๊ธฐํ™”๋Š” ๋๊นŒ์ง€ ๋ฐ›์€ ๋’ค ๋ฒˆํ˜ธ๋กœ ์ค‘๋ณต์„ ์ง€์šฐ์„ธ์š”.
bash ยท ๋๊นŒ์ง€ ๋ฐ›๊ธฐ (jq ํ•„์š”)
URL="https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/members?limit=200"
CURSOR=""
while : ; do
  RES=$(curl -s -H "X-API-Key: $JC_API_KEY" "$URL${CURSOR:+&cursor=$CURSOR}")
  echo "$RES" | jq -c '.data[]'
  [ "$(echo "$RES" | jq -r '.meta.hasMore')" = "true" ] || break
  CURSOR=$(echo "$RES" | jq -r '.meta.cursor')
done

7. ์š”์ฒญ ํ•œ๋„

  • ํ•œ๋„๋Š” API ํ‚ค ํ•˜๋‚˜๋‹น ๋ถ„๋‹น ์š”์ฒญ ์ˆ˜์ž…๋‹ˆ๋‹ค. ๊ธฐ๋ณธ๊ฐ’์€ 60ํšŒ/๋ถ„์ด๊ณ  ํ‚ค๋งˆ๋‹ค ๋‹ค๋ฅด๊ฒŒ ์ •ํ•ด์งˆ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.
  • ๋ถ„ ๋‹จ์œ„ ๊ณ ์ • ๊ตฌ๊ฐ„์œผ๋กœ ์…‰๋‹ˆ๋‹ค(์‹œ๊ณ„์˜ ๋ถ„์ด ๋ฐ”๋€Œ๋ฉด 0๋ถ€ํ„ฐ). ์ธ์ฆ์„ ํ†ต๊ณผํ•œ ์š”์ฒญ์€ ๊ฒฐ๊ณผ์™€ ์ƒ๊ด€์—†์ด ์…‰๋‹ˆ๋‹ค. ์ธ์ฆ ์ „์— ๊ฑฐ์ ˆ๋œ ์š”์ฒญ๊ณผ ํ‚ค ์—†์ด ๋ถ€๋ฅธ health ๋Š” ์„ธ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.
  • ๋„˜์œผ๋ฉด 429 + JC-4029 ์™€ ์‘๋‹ต ํ—ค๋” Retry-After: 60 ์ด ์˜ต๋‹ˆ๋‹ค. ์ด ๊ฐ’์€ ๋Š˜ 60์ด๋ฉฐ ยซ๋‚จ์€ ์ดˆยป๊ฐ€ ์•„๋‹™๋‹ˆ๋‹ค.
  • 429๋ฅผ ๋ฐ›์œผ๋ฉด Retry-After ๋งŒํผ ์‰ฌ๊ณ , ๊ทธ ๋ฐ–์˜ ์žฌ์‹œ๋„๋Š” ๊ฐ„๊ฒฉ์„ ์ง€์ˆ˜์ ์œผ๋กœ ๋ฒŒ๋ฆฌ์„ธ์š”.
HTTP/1.1 429
Retry-After: 60

{"success":false,"error":{"code":"JC-4029","message":"๋ถ„๋‹น ์š”์ฒญ ํ•œ๋„(60)๋ฅผ ์ดˆ๊ณผํ–ˆ์Šต๋‹ˆ๋‹ค."}}

8. ์‹œ๊ฐ„๊ณผ ๋‚ ์งœ

  • ์š”์ฒญ์˜ ๋‚ ์งœ ๋งค๊ฐœ๋ณ€์ˆ˜๋Š” yyyy-MM-dd ์ด๋ฉฐ ํ•œ๊ตญ ํ‘œ์ค€์‹œ(KST, UTC+9)์˜ ๋‚ ๋กœ ํ•ด์„ํ•ฉ๋‹ˆ๋‹ค.
  • ์‘๋‹ต์˜ ์‹œ๊ฐ์€ ISO-8601์ด๊ณ  ๋Š˜ +09:00 ์ด ๋ถ™์Šต๋‹ˆ๋‹ค. ์˜ˆ: 2026-10-19T09:01:00+09:00. ๋ฐ€๋ฆฌ์ดˆ ์†Œ์ˆ˜๋ถ€๊ฐ€ ๋ถ™์„ ์ˆ˜ ์žˆ์œผ๋‹ˆ ๊ณ ์ • ๊ธธ์ด๋กœ ์ž๋ฅด์ง€ ๋ง๊ณ  ISO-8601 ํŒŒ์„œ๋ฅผ ์“ฐ์„ธ์š”.

9. ์ฐฝ๊ตฌ๋ณ„ ๋ช…์„ธ

GET

/health

ํ‚ค ๋ถˆํ•„์š”

์„œ๋ฒ„ ์ƒํƒœ๋ฅผ ํ™•์ธํ•ฉ๋‹ˆ๋‹ค. ํ‹€๋ฆฐ ํ‚ค๋ฅผ ๋ถ™์ด๋ฉด 401์ž…๋‹ˆ๋‹ค.

์‘๋‹ต ํ•„๋“œํ˜•์‹์„ค๋ช…
status๋ฌธ์ž์—ด์ •์ƒ์ด๋ฉด "UP"
time๋ฌธ์ž์—ด(ISO-8601)์„œ๋ฒ„ ํ˜„์žฌ ์‹œ๊ฐ(KST)
build๋ฌธ์ž์—ด์ง€๊ธˆ ๋„๋Š” ํŒ์˜ ์‹๋ณ„๊ฐ’. ๋ชจ๋ฅด๋Š” ํ™˜๊ฒฝ์ด๋ฉด "unknown". ํ˜•์‹์€ ์•ฝ์†ํ•˜์ง€ ์•Š์œผ๋‹ˆ ํ‘œ์‹œยท๊ธฐ๋ก์šฉ์œผ๋กœ๋งŒ ์“ฐ์„ธ์š”
GET

/members

members:read

๊ตฌ์„ฑ์› ๋ชฉ๋ก์ž…๋‹ˆ๋‹ค. ๊ฒŒ์ŠคํŠธ์™€ ํƒˆํ‡ดํ•œ ๊ตฌ์„ฑ์›์€ ๋น ์ง‘๋‹ˆ๋‹ค. ๋‹‰๋„ค์ž„์ˆœ์ž…๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜์œ„์น˜ํ•„์ˆ˜์„ค๋ช…
limit์ฟผ๋ฆฌ์•„๋‹ˆ์˜ค1~200, ๊ธฐ๋ณธ 50
cursor์ฟผ๋ฆฌ์•„๋‹ˆ์˜ค์ด์ „ ์‘๋‹ต์˜ meta.cursor
์‘๋‹ต ํ•„๋“œํ˜•์‹์„ค๋ช…
memberSeq์ •์ˆ˜๊ตฌ์„ฑ์› ๋ฒˆํ˜ธ(์›Œํฌ์ŠคํŽ˜์ด์Šค ์•ˆ์—์„œ ๊ณ ์œ ). ๊ทผํƒœ์˜ memberSeq ์™€ ๊ฐ™์€ ๊ฐ’
account๋ฌธ์ž์—ด๋กœ๊ทธ์ธ ๊ณ„์ •(์ด๋ฉ”์ผ ๊ผด). ์™ธ๋ถ€ ์‹œ์Šคํ…œ์˜ ์ง์›๊ณผ ๋งž์ถœ ๋•Œ ์“ฐ๋Š” ํ‚ค
name๋ฌธ์ž์—ด์ด๋ฆ„
nickname๋ฌธ์ž์—ด์›Œํฌ์ŠคํŽ˜์ด์Šค์—์„œ ์“ฐ๋Š” ํ‘œ์‹œ ์ด๋ฆ„
jobGrade๋ฌธ์ž์—ด์ง๊ธ‰ (์—†์œผ๋ฉด ๋น ์ง)
spaceName๋ฌธ์ž์—ด์†Œ์† ๊ณต๊ฐ„(๋ถ€์„œ) ์ด๋ฆ„ (์—†์œผ๋ฉด ๋น ์ง)
status๋ฌธ์ž์—ดํ˜„์žฌ ์ƒํƒœ ์ด๋ฆ„(์˜ˆ: ์˜จ๋ผ์ธยท์˜คํ”„๋ผ์ธยท๋ถ€์žฌ์ค‘). ์ข…๋ฅ˜๊ฐ€ ๋Š˜ ์ˆ˜ ์žˆ์œผ๋‹ˆ ๋ชจ๋ฅด๋Š” ๊ฐ’๋„ ๊ทธ๋Œ€๋กœ ๋ฐ›์œผ์„ธ์š”

์ „ํ™”๋ฒˆํ˜ธยท์ฃผ์†Œยท์œ„์น˜ยท์ƒ๋…„์›”์ผยท์‚ฌ์—…์ž ์ •๋ณด๋Š” ์ œ๊ณตํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/members?limit=2"
์‘๋‹ต (์˜ˆ์‹œ ๋ฐ์ดํ„ฐ)
{
  "success": true,
  "data": [
    { "memberSeq": 1021, "account": "gildong.hong@example.com", "name": "ํ™๊ธธ๋™",
      "nickname": "๊ธธ๋™", "jobGrade": "๊ณผ์žฅ", "spaceName": "๊ฐœ๋ฐœํŒ€", "status": "์˜จ๋ผ์ธ" },
    { "memberSeq": 1034, "account": "chulsoo.kim@example.com", "name": "๊น€์ฒ ์ˆ˜",
      "nickname": "์ฒ ์ˆ˜", "status": "์˜คํ”„๋ผ์ธ" }
  ],
  "meta": { "cursor": "bzoy", "hasMore": true }
}
GET

/spaces

spaces:read

์‚ฌ์šฉ ์ค‘์ธ ๊ณต๊ฐ„(๋ถ€์„œยท๋ฐฉ) ๋ชฉ๋ก์ž…๋‹ˆ๋‹ค. spaceSeq ์ˆœ์ž…๋‹ˆ๋‹ค. ๋งค๊ฐœ๋ณ€์ˆ˜๋Š” limitยทcursor(์œ„์™€ ๊ฐ™์Œ)์ž…๋‹ˆ๋‹ค.

์‘๋‹ต ํ•„๋“œํ˜•์‹์„ค๋ช…
spaceSeq์ •์ˆ˜๊ณต๊ฐ„ ๋ฒˆํ˜ธ
name๋ฌธ์ž์—ด๊ณต๊ฐ„ ์ด๋ฆ„
topSpaceSeq์ •์ˆ˜์ƒ์œ„ ๊ณต๊ฐ„ ๋ฒˆํ˜ธ. ์ตœ์ƒ์œ„ ๊ณต๊ฐ„์ด๋ฉด ๋น ์ง
์‘๋‹ต (์˜ˆ์‹œ ๋ฐ์ดํ„ฐ)
{
  "success": true,
  "data": [
    { "spaceSeq": 301, "name": "๋ณธ์‚ฌ" },
    { "spaceSeq": 305, "name": "๊ฐœ๋ฐœํŒ€", "topSpaceSeq": 301 }
  ],
  "meta": { "hasMore": false }
}
GET

/spaces/{id}

spaces:read

๊ณต๊ฐ„ 1๊ฑด์ž…๋‹ˆ๋‹ค. id(๊ฒฝ๋กœ, ์ •์ˆ˜)๊ฐ€ ์ •์ˆ˜๊ฐ€ ์•„๋‹ˆ๋ฉด 400 ์ž…๋‹ˆ๋‹ค. ์‘๋‹ต data ๋Š” ์œ„ ๋ชฉ๋ก์˜ ํ•ญ๋ชฉ ํ•˜๋‚˜์™€ ๊ฐ™์Šต๋‹ˆ๋‹ค.

bash
curl -s -H "X-API-Key: $JC_API_KEY" "https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/spaces/305"
์‘๋‹ต
{ "success": true, "data": { "spaceSeq": 305, "name": "๊ฐœ๋ฐœํŒ€", "topSpaceSeq": 301 } }

์—†๋Š” ๊ณต๊ฐ„, ์ง€์›Œ์ง„ ๊ณต๊ฐ„, ๋‹ค๋ฅธ ์›Œํฌ์ŠคํŽ˜์ด์Šค์˜ ๊ณต๊ฐ„์€ ๋ชจ๋‘ ๊ฐ™์€ 404(JC-4004)์ž…๋‹ˆ๋‹ค. ๋‚จ์˜ ๋ฐ์ดํ„ฐ๊ฐ€ ์žˆ๋Š”์ง€ ์•Œ ์ˆ˜ ์—†๊ฒŒ ํ•˜๋ ค๋Š” ๊ฒƒ์ž…๋‹ˆ๋‹ค.

GET

/attendances

attendances:read

๊ธฐ๊ฐ„ ์•ˆ์— ์ถœ๊ทผ ๊ธฐ๋ก์ด ์žˆ๋Š” ๊ทผํƒœ๋ฅผ ๋Œ๋ ค์ค๋‹ˆ๋‹ค.

๋งค๊ฐœ๋ณ€์ˆ˜์œ„์น˜ํ•„์ˆ˜์„ค๋ช…
from์ฟผ๋ฆฌ์˜ˆ์‹œ์ž‘์ผ yyyy-MM-dd (KST, ๊ทธ๋‚  00:00๋ถ€ํ„ฐ)
to์ฟผ๋ฆฌ์˜ˆ์ข…๋ฃŒ์ผ yyyy-MM-dd (KST, ๊ทธ๋‚  ๋๊นŒ์ง€ ํฌํ•จ)
memberSeq์ฟผ๋ฆฌ์•„๋‹ˆ์˜ค์ด ๊ตฌ์„ฑ์›์˜ ๊ทผํƒœ๋งŒ. ์—†๋Š” ๋ฒˆํ˜ธ๋ฉด ๋นˆ ๋ชฉ๋ก
limit์ฟผ๋ฆฌ์•„๋‹ˆ์˜ค1~200, ๊ธฐ๋ณธ 50
cursor์ฟผ๋ฆฌ์•„๋‹ˆ์˜ค์ด์ „ ์‘๋‹ต์˜ meta.cursor
  • fromยทto ๋Š” ๋‘˜ ๋‹ค ํ•„์ˆ˜์ž…๋‹ˆ๋‹ค. ๋น ์ง€๊ฑฐ๋‚˜ ํ˜•์‹์ด ํ‹€๋ฆฌ๊ฑฐ๋‚˜ to ๊ฐ€ from ๋ณด๋‹ค ์•ž์„œ๋ฉด 400 ์ž…๋‹ˆ๋‹ค.
  • ์กฐํšŒ ๊ธฐ๊ฐ„์€ ์ตœ๋Œ€ 92์ผ์ž…๋‹ˆ๋‹ค(์–‘ ๋ ๋‚  ํฌํ•จ, ์˜ˆ: 2026-07-01 ~ 2026-09-30). ๋” ๊ธด ๊ธฐ๊ฐ„์€ ๋‚˜๋ˆ  ๋ฐ›์œผ์„ธ์š”.
  • ๊ธฐ๊ฐ„์€ ์ฒ˜์Œ ์ฐํžŒ ์ถœ๊ทผ ์‹œ๊ฐ ๊ธฐ์ค€์œผ๋กœ ๊ฑฐ๋ฆ…๋‹ˆ๋‹ค. ๊ด€๋ฆฌ์ž๊ฐ€ ์ถœ๊ทผ ์‹œ๊ฐ์„ ๊ณ ์นœ ๊ธฐ๋ก๋„ ์ฒ˜์Œ ์ฐํžŒ ๋‚ ์ด ๊ธฐ๊ฐ„ ์•ˆ์ด๋ฉด ๋‚˜์˜ค๋ฉฐ, ์ด๋•Œ clockIn ์—๋Š” ๊ณ ์นœ ๊ฐ’์ด ์˜ต๋‹ˆ๋‹ค.
์‘๋‹ต ํ•„๋“œํ˜•์‹์„ค๋ช…
attendanceSeq์ •์ˆ˜๊ทผํƒœ ๊ธฐ๋ก ๋ฒˆํ˜ธ
memberSeq์ •์ˆ˜๊ทผ๋ฌด์ž ๊ตฌ์„ฑ์› ๋ฒˆํ˜ธ
memberName๋ฌธ์ž์—ด๊ทผ๋ฌด์ž ๋‹‰๋„ค์ž„
clockIn๋ฌธ์ž์—ด(ISO-8601)์ถœ๊ทผ ์‹œ๊ฐ. ๊ด€๋ฆฌ์ž๊ฐ€ ๊ณ ์นœ ๊ฐ’์ด ์žˆ์œผ๋ฉด ๊ทธ ๊ฐ’
clockOut๋ฌธ์ž์—ด(ISO-8601)ํ‡ด๊ทผ ์‹œ๊ฐ. ์•„์ง ํ‡ด๊ทผํ•˜์ง€ ์•Š์•˜์œผ๋ฉด ๋น ์ง
outside๋ฌธ์ž์—ด(HH:mm)๊ทธ๋‚  ยซ์™ธ๊ทผ์ค‘ยป์ด์—ˆ๋˜ ์‹œ๊ฐ„. ์—†์œผ๋ฉด "00:00"
missed๋ฌธ์ž์—ด(HH:mm)๊ทธ๋‚  ยซ๋ถ€์žฌ์ค‘ยป์ด์—ˆ๋˜ ์‹œ๊ฐ„. ์—†์œผ๋ฉด "00:00"

๊ทผํƒœ์˜ ๋น„๊ณ (๋ฉ”๋ชจ)๋Š” ๊ฐœ์ธ์ •๋ณด๊ฐ€ ์„ž์ผ ์ˆ˜ ์žˆ์–ด ์ œ๊ณตํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์˜ค๋Š˜ ๊ธฐ๋ก์˜ outsideยทmissed ๋Š” ์ง€๊ธˆ๊นŒ์ง€๋กœ ์„ธ๋ฏ€๋กœ ๋‹ค์‹œ ๋ฐ›์œผ๋ฉด ๋Š˜์–ด๋‚  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

bash
curl -s -H "X-API-Key: $JC_API_KEY" \
  "https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/attendances?from=2026-10-19&to=2026-10-19&memberSeq=1021"
์‘๋‹ต (์˜ˆ์‹œ ๋ฐ์ดํ„ฐ)
{
  "success": true,
  "data": [
    { "attendanceSeq": 88123, "memberSeq": 1021, "memberName": "๊ธธ๋™",
      "clockIn": "2026-10-19T08:57:12+09:00", "clockOut": "2026-10-19T18:03:40+09:00",
      "outside": "01:20", "missed": "00:00" }
  ],
  "meta": { "hasMore": false }
}
์˜ค๋ฅ˜ ์˜ˆ
{ "success": false, "error": { "code": "JC-4000", "message": "์กฐํšŒ ๊ธฐ๊ฐ„์€ ์ตœ๋Œ€ 92์ผ๊นŒ์ง€ ๊ฐ€๋Šฅํ•ฉ๋‹ˆ๋‹ค." } }

{ "success": false, "error": { "code": "JC-4000",
  "message": "์š”์ฒญ ํŒŒ๋ผ๋ฏธํ„ฐ๊ฐ€ ์˜ฌ๋ฐ”๋ฅด์ง€ ์•Š์Šต๋‹ˆ๋‹ค.", "detail": "'from' ์นธ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค." } }

10. ์˜ค๋ฅ˜ ์ฝ”๋“œ

์ฝ”๋“œHTTP๋œป๋Œ€ํ‘œ ์ƒํ™ฉ๋‹ค์‹œ ํ•˜๋ฉด?
JC-4000400์ž˜๋ชป๋œ ์š”์ฒญ๊ทผํƒœ from/to ๋ˆ„๋ฝยทํ˜•์‹ ์˜ค๋ฅ˜ยท92์ผ ์ดˆ๊ณผ, cursor ํ•ด์„ ๋ถˆ๊ฐ€, ์ˆซ์ž ์ž๋ฆฌ์— ์ˆซ์ž๊ฐ€ ์•„๋‹˜์š”์ฒญ์„ ๊ณ ์ณ์•ผ ํ•จ
JC-4001401์ธ์ฆ ์‹คํŒจํ‚ค ์—†์Œยท๋ชจ๋ฅด๋Š” ํ‚คยทํ๊ธฐยท๋งŒ๋ฃŒยท์—ฐ๋™ ์ค‘์ง€, health ์— ํ‹€๋ฆฐ ํ‚คํ‚ค ํ™•์ธ ๋˜๋Š” ์žฌ๋ฐœ๊ธ‰
JC-4003403๊ถŒํ•œ ๋ฒ”์œ„ ๋ถ€์กฑํ‚ค์— ๊ทธ ์ฐฝ๊ตฌ์˜ scope ๊ฐ€ ์—†์Œ(๋ฉ”์‹œ์ง€์— ํ•„์š”ํ•œ scope: โ€ฆ)๋ฒ”์œ„ ์ถ”๊ฐ€ ์‹ ์ฒญ
JC-4004404์ฐพ์„ ์ˆ˜ ์—†์Œ์—†๋Š”ยท์ง€์›Œ์ง„ ๊ณต๊ฐ„, ๋˜๋Š” ๋‹ค๋ฅธ ์›Œํฌ์ŠคํŽ˜์ด์Šค์˜ ๊ณต๊ฐ„๋ฒˆํ˜ธ ํ™•์ธ
JC-4029429์š”์ฒญ ํ•œ๋„ ์ดˆ๊ณผํ‚ค ํ•˜๋‚˜์˜ ๋ถ„๋‹น ํ•œ๋„ ์ดˆ๊ณผ ยท Retry-After: 6060์ดˆ ๋’ค
JC-5000500์„œ๋ฒ„ ๋‚ด๋ถ€ ์˜ค๋ฅ˜์˜ˆ๊ธฐ์น˜ ๋ชปํ•œ ์˜ค๋ฅ˜(์‘๋‹ต์—๋Š” ์ผ๋ฐ˜ ๋ฌธ๊ตฌ๋งŒ)์ž ์‹œ ๋’ค ์žฌ์‹œ๋„, ๊ณ„์†๋˜๋ฉด ๋ฌธ์˜
  • 401์€ ์›์ธ์„ ๋‚˜๋ˆ„์ง€ ์•Š๊ณ , 403์€ scope ๋ถ€์กฑ ํ•œ ๊ฐ€์ง€์ž…๋‹ˆ๋‹ค. ๋‚จ์˜ ์›Œํฌ์ŠคํŽ˜์ด์Šค ๋ฐ์ดํ„ฐ๋Š” 403์ด ์•„๋‹ˆ๋ผ 404์ž…๋‹ˆ๋‹ค.
  • 4xxx ๋Š” ์š”์ฒญํ•˜๋Š” ์ชฝ, 5xxx ๋Š” ์„œ๋ฒ„ ์ชฝ ์ฑ…์ž„์ž…๋‹ˆ๋‹ค. ํ‘œ์— ์—†๋Š” ์ฝ”๋“œ๋ฅผ ๋ฐ›์œผ๋ฉด HTTP ์ƒํƒœ๋ฅผ ๊ธฐ์ค€์œผ๋กœ ์ฒ˜๋ฆฌํ•˜๊ณ  ์•Œ๋ ค ์ฃผ์„ธ์š”.
  • ์„œ๋ฒ„ ์•ž๋‹จ(๋ฐฉํ™”๋ฒฝยทCDN)์ด ๊ฑฐ์ ˆํ•œ ๊ฒฝ์šฐ(502ยท503ยท504 ๋“ฑ)์™€ ์ •์˜๋˜์ง€ ์•Š์€ ๊ฒฝ๋กœ๋Š” ์œ„ ๊ผด์ด ์•„๋‹ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ณธ๋ฌธ์ด JSON์ด ์•„๋‹ˆ๋ฉด ์ฃผ์†Œ๋ถ€ํ„ฐ ํ™•์ธํ•˜์„ธ์š”.

11. ์›นํ›… ๋ฐ›๊ธฐ (์•Œ๋ฆผ ๋‚ด๋ณด๋‚ด๊ธฐ)

ํŒ€์‚ฌ์ด๋“œ๊ฐ€ ์—…๋ฌด ์•Œ๋ฆผ์„ ๊ณ ๊ฐ์ด ์ •ํ•œ ์ฃผ์†Œ๋กœ ๋ณด๋‚ด๋Š” ๊ธฐ๋Šฅ์ž…๋‹ˆ๋‹ค. ์œ„์˜ ์ฝ๊ธฐ API์™€ ๋‹ฌ๋ฆฌ ยซ๋ฐ›๋Š” ์ชฝยป์„ ๊ฐœ๋ฐœํ•  ๋•Œ์˜ ์„ค๋ช…์ž…๋‹ˆ๋‹ค.

์„ค์ •๊ณผ ์ „์ œ

  • ์›Œํฌ์ŠคํŽ˜์ด์Šค์˜ ์†Œ์œ ์žยท๊ด€๋ฆฌ์ž๊ฐ€ ์„ค์ • ํ™”๋ฉด์—์„œ ๋ฐ›๋Š” ์ฃผ์†Œ๋ฅผ ๋“ฑ๋กํ•ฉ๋‹ˆ๋‹ค(์›Œํฌ์ŠคํŽ˜์ด์Šค๋‹น ์ตœ๋Œ€ 20๊ณณ). API ํ‚ค๋กœ๋Š” ๋“ฑ๋กํ•˜์ง€ ๋ชปํ•ฉ๋‹ˆ๋‹ค.
  • ๋ฐ›๋Š” ๊ณณ๋งˆ๋‹ค ๋ฐ›์„ ์•Œ๋ฆผ ์ข…๋ฅ˜(๋˜๋Š” ยซ์ „๋ถ€ยป)ยท๋ฒ”์œ„(์›Œํฌ์ŠคํŽ˜์ด์Šค ์ „์ฒด / ํŠน์ • ํ”„๋กœ์ ํŠธ / ํŠน์ • ๊ฒฐ์žฌ ์–‘์‹)ยท์ œ๋ชฉ ์ˆจ๊ธฐ๊ธฐ๋ฅผ ๊ณ ๋ฆ…๋‹ˆ๋‹ค. ์ œ๋ชฉ ์ˆจ๊ธฐ๊ธฐ๋ฅผ ์ผœ๋ฉด ๋ณธ๋ฌธ์—์„œ ์ œ๋ชฉ์ด ์•„์˜ˆ ๋น ์ง‘๋‹ˆ๋‹ค.
  • ์ฃผ์†Œ๋Š” ์ธํ„ฐ๋„ท์—์„œ ๋‹ฟ์•„์•ผ ํ•ฉ๋‹ˆ๋‹ค. ์‚ฌ๋‚ด ์‚ฌ์„ค๋ง ์ฃผ์†Œ๋Š” ๋“ฑ๋กํ•  ์ˆ˜ ์—†๊ณ , ๋ณด๋‚ด๊ธฐ ์ง์ „์—๋„ ๋‹ค์‹œ ๊ฒ€์‚ฌํ•ฉ๋‹ˆ๋‹ค. ๋ฆฌ๋‹ค์ด๋ ‰ํŠธ(3xx)๋Š” ๋”ฐ๋ผ๊ฐ€์ง€ ์•Š์œผ๋‹ˆ ์ตœ์ข… ์ฃผ์†Œ๋ฅผ ๋“ฑ๋กํ•˜์„ธ์š”.
  • ๋ณด๋‚ด๊ธฐ ๊ธฐ๋Šฅ์€ ์„œ๋ฒ„ ์šด์˜์ž๊ฐ€ ์ผœ์•ผ ๋™์ž‘ํ•ฉ๋‹ˆ๋‹ค. ๋„์ž…ํ•  ๋•Œ ์ผœ์ ธ ์žˆ๋Š”์ง€ ํ™•์ธํ•˜์„ธ์š”.

๋ณด๋‚ด๋Š” ๋ฐฉ์‹

  • POST ยท Content-Type: application/json ยท UTF-8 JSON ๋ณธ๋ฌธ.
  • ์—ฐ๊ฒฐ 3์ดˆยท์‘๋‹ต 10์ดˆ ์•ˆ์— 2xx ๋กœ ๋‹ตํ•ด์•ผ ๋ฐ›์€ ๊ฒƒ์œผ๋กœ ์นฉ๋‹ˆ๋‹ค. ์˜ค๋ž˜ ๊ฑธ๋ฆฌ๋Š” ์ฒ˜๋ฆฌ๋Š” ๋ฐ›์€ ๋’ค ๋”ฐ๋กœ ํ•˜์„ธ์š”.
  • ์„œ๋ช… ํ‚ค๋ฅผ ๋“ฑ๋กํ•œ ๊ณณ์—๋Š” ํ—ค๋” X-JC-Signature: sha256=<์†Œ๋ฌธ์ž hex> ๊ฐ€ ๋ถ™์Šต๋‹ˆ๋‹ค.
  • ๊ฐ™์€ ๊ณณ์— ๋ณด๋‚ธ ์‹œ๊ฐ์ด ๋“  ํ—ค๋” X-JC-Signature-V2: t=<์œ ๋‹‰์Šค ์ดˆ>,v1=<์†Œ๋ฌธ์ž hex> ๋„ ํ•จ๊ป˜ ๋ถ™์Šต๋‹ˆ๋‹ค(2026-11-08~). ๊ฐ€๋กœ์ฑˆ ์š”์ฒญ์„ ๋‚˜์ค‘์— ๋‹ค์‹œ ๋ณด๋‚ด๋Š” ๊ฒƒ์„ ๋ง‰์œผ๋ ค๋ฉด ์ด์ชฝ์„ ํ™•์ธํ•˜์„ธ์š”.
  • ์žฌ์‹œ๋„ ๋•Œ๋ฌธ์— ๊ฐ™์€ ๋ณธ๋ฌธ์ด ๋‘ ๋ฒˆ ์ด์ƒ ์˜ฌ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. eventยทalarmSeq(์—†์œผ๋ฉด occurredAt+subject)๋กœ ์ค‘๋ณต์„ ๊ฑฐ๋ฅด์„ธ์š”.

์„œ๋ช… ๊ฒ€์ฆ

์„œ๋ช…์€ ๋ฐ›์€ ๋ณธ๋ฌธ ๋ฐ”์ดํŠธ ๊ทธ๋Œ€๋กœ(๋‹ค์‹œ ์ง๋ ฌํ™”ํ•˜์ง€ ์•Š์€ ์›๋ฌธ)์— ๋Œ€ํ•œ HMAC-SHA256์ด๊ณ , ์—ด์‡ ๋Š” ๋“ฑ๋กํ•œ ์„œ๋ช… ํ‚ค์ž…๋‹ˆ๋‹ค. ๋น„๊ต๋Š” ์‹œ๊ฐ„์ฐจ๊ฐ€ ๋“œ๋Ÿฌ๋‚˜์ง€ ์•Š๋Š” ๋ฐฉ์‹์œผ๋กœ ํ•˜์„ธ์š”.

node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
python
import hmac, hashlib
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or '')

๋ณด๋‚ธ ์‹œ๊ฐ์ด ๋“  ์„œ๋ช…(V2) ๊ฒ€์ฆ

v1 ์€ t + . + ๋ฐ›์€ ๋ณธ๋ฌธ ๋ฐ”์ดํŠธ ๊ทธ๋Œ€๋กœ์— ๋Œ€ํ•œ HMAC-SHA256์ž…๋‹ˆ๋‹ค. t ๊ฐ€ ์ง€๊ธˆ๊ณผ 5๋ถ„ ๋„˜๊ฒŒ ์ฐจ์ด ๋‚˜๋ฉด ๋ฒ„๋ฆฌ์„ธ์š”. ์žฌ์‹œ๋„ ๋•Œ๋Š” ๊ทธ๋•Œ ์‹œ๊ฐ์œผ๋กœ ๋‹ค์‹œ ์„œ๋ช…ํ•ด ๋ณด๋ƒ…๋‹ˆ๋‹ค. ์˜› X-JC-Signature ๋„ ๊ณ„์† ๋ถ™์œผ๋‹ˆ ์ด๋ฏธ ๋งŒ๋“  ๊ฒ€์ฆ์€ ๊ทธ๋Œ€๋กœ ๋‘ฌ๋„ ๋ฉ๋‹ˆ๋‹ค.

node.js
const crypto = require('crypto');
// header ์˜ˆ: "t=1700000000,v1=2f65โ€ฆ" ยท 5๋ถ„(300์ดˆ)๋ณด๋‹ค ์˜ค๋ž˜๋œ ๊ฒƒ์€ ๋ฒ„๋ฆฐ๋‹ค
function verifyV2(rawBody, header, secret, nowSec = Math.floor(Date.now() / 1000)) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m || Math.abs(nowSec - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody, 'utf8').digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

๋ณธ๋ฌธ (์ผ๋ฐ˜ JSON ์ฃผ์†Œ)

json ยท ์˜ˆ์‹œ ๋ฐ์ดํ„ฐ
{
  "event": "approval.requested",
  "occurredAt": 1792382400000,
  "workspaceSeq": 12,
  "alarmSeq": 55012,
  "actor": "๊ธธ๋™",
  "recipients": [1034, 1050],
  "subject": { "requestSeq": 7001, "title": "10์›” ์ถœ์žฅ๋น„", "requestType": "๊ฒฝ๋น„์‹ ์ฒญ์„œ" }
}
ํ•„๋“œ์„ค๋ช…
event์‚ฌ๊ฑด ํ‚ค(์•„๋ž˜ ํ‘œ). ํ•œ ๋ฒˆ ์ •ํ•œ ์ด๋ฆ„์€ ๋ฐ”๊พธ์ง€ ์•Š์Šต๋‹ˆ๋‹ค
occurredAt์‚ฌ๊ฑด ์‹œ๊ฐ. epoch ๋ฐ€๋ฆฌ์ดˆ(์ˆซ์ž)
workspaceSeq์›Œํฌ์ŠคํŽ˜์ด์Šค ๋ฒˆํ˜ธ
alarmSeq์•Œ๋ฆผ ๋ฒˆํ˜ธ(์•Œ๋ฆผ ํ–‰์ด ์—†๋Š” ์‚ฌ๊ฑด์€ ๋น ์ง)
actor์‚ฌ๊ฑด์„ ์ผ์œผํ‚จ ์‚ฌ๋žŒ์˜ ํ‘œ์‹œ ์ด๋ฆ„
recipients์•Œ๋ฆผ์„ ๋ฐ›๋Š” ๊ตฌ์„ฑ์› ๋ฒˆํ˜ธ ๋ชฉ๋ก(์•Œ๋ฆผ ํ–‰์ด ์—†๋Š” ์‚ฌ๊ฑด์€ ๋น ์ง)
subject์‚ฌ๊ฑด ๋‚ด์šฉ. ์ข…๋ฅ˜๋งˆ๋‹ค ํ•„๋“œ๊ฐ€ ๋‹ค๋ฅด๊ณ  ๋Š˜์–ด๋‚  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ œ๋ชฉ ์ˆจ๊ธฐ๊ธฐ๋ฅผ ์ผ  ๊ณณ์—๋Š” ํ‚ค ์ž์ฒด๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค

์‚ฌ๋žŒ์ด ์ฝ๋Š” ๋ฌธ์žฅ์€ ์ผ๋ฐ˜ JSON์— ๋‹ด๊ธฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ์‚ฌ๊ฑด ํ‚ค๋กœ ์ง์ ‘ ๋ฌธ๊ตฌ๋ฅผ ๋งŒ๋“œ์„ธ์š”.

์‚ฌ๊ฑด ํ‚ค

๋ฌถ์Œ์‚ฌ๊ฑด ํ‚ค
๊ฒฐ์žฌapproval.requestedapproval.forwardedapproval.referencedapproval.approvedapproval.rejectedapproval.withdrawnapproval.canceledapproval.deletedapproval.commentedapproval.dueapproval.reminded
๊ทผํƒœยท์—ฐ์ฐจattendance.week.warnattendance.week.overvacation.promotion.urgedvacation.promotion.assigned
๋ฌธ์˜ยท๊ฒŒ์‹œยท์„ค๋ฌธinquiry.createdboard.postedsurvey.openedsurvey.reopened
ํšŒ์˜ยท์„ธ๋ฏธ๋‚˜ยท์ž์›meeting.scheduledmeeting.canceledmeeting.startedseminar.scheduledseminar.canceledseminar.startedresource.bookedresource.canceled
์นธ๋ฐ˜task.assignedtask.duetask.completed (ํ”„๋กœ์ ํŠธ๋ฅผ ๊ณ ๋ฅธ ๋ฐ›๋Š” ๊ณณ์—๋งŒ)
๊ตฌ์„ฑ์›member.joined (ยซ์ „๋ถ€ยป๋ฅผ ๊ณ ๋ฅธ ์ผ๋ฐ˜ JSON ์ฃผ์†Œ์—๋งŒ)

member.joined ๋Š” ยซ์ „๋ถ€ยป๋ฅผ ๊ณ ๋ฅธ ์ผ๋ฐ˜ JSON ์ฃผ์†Œ์—๋งŒ ๊ฐ€๋ฉฐ, ์ด ์‚ฌ๊ฑด์˜ occurredAt ์€ ์ˆซ์ž๊ฐ€ ์•„๋‹ˆ๋ผ ๋ฌธ์ž์—ด์ž…๋‹ˆ๋‹ค. event ๋กœ ๋จผ์ € ๋ถ„๊ธฐํ•˜์„ธ์š”.

TeamsยทSlack ์œผ๋กœ ๋ฐ›๊ธฐ

์ฃผ์†Œ์˜ ํ˜ธ์ŠคํŠธ๊ฐ€ hooks.slack.com, *.webhook.office.com, *.environment.api.powerplatform.com, *.logic.azure.com ์ด๋ฉด ๊ทธ ์„œ๋น„์Šค๊ฐ€ ๊ทธ๋ฆฌ๋Š” ๊ผด๋กœ ํ•œ ์ค„ ์•Œ๋ฆผ์„ ๋งŒ๋“ค์–ด ๋ณด๋ƒ…๋‹ˆ๋‹ค. ์ด๋•Œ๋Š” ์œ„์˜ ์ผ๋ฐ˜ JSONยท์„œ๋ช…์„ ์“ฐ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.

์‹คํŒจ์™€ ์žฌ์‹œ๋„

๋ฐ›์€ ์‘๋‹ต์ฒ˜๋ฆฌ
2xx์„ฑ๊ณต
408 ยท 429 ยท 5xx ยท 3xx ยท ์—ฐ๊ฒฐ ์‹คํŒจยท์‹œ๊ฐ„ ์ดˆ๊ณผ๋‹ค์‹œ ์‹œ๋„
๊ทธ ๋ฐ–์˜ 4xx๋ฐ”๋กœ ํฌ๊ธฐ

์ตœ์ดˆ 1ํšŒ์™€ ์žฌ์‹œ๋„ 4ํšŒ, ๋ชจ๋‘ 5ํšŒ๊นŒ์ง€ ์‹œ๋„ํ•˜๋ฉฐ ๊ฐ„๊ฒฉ์€ ์ ์  ๋ฒŒ์–ด์ง‘๋‹ˆ๋‹ค(์ตœ๋Œ€ 4๋ถ„ ์•ˆํŒŽ). 5ํšŒ ๋ชจ๋‘ ์‹คํŒจํ•œ ๊ฑด์€ ๋‹ค์‹œ ๋ณด๋‚ด์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๋ฐ›๋Š” ๊ณณ์„ ๋ˆ ๋™์•ˆ์˜ ์•Œ๋ฆผ์€ ์Œ“์ด์ง€ ์•Š์Šต๋‹ˆ๋‹ค.

12. AI ๋„๊ตฌ ์—ฐ๊ฒฐ (MCP)

ClaudeยทChatGPTยทGemini ๊ฐ™์€ AI ๋„๊ตฌ๊ฐ€ ๊ฐ™์€ API ํ‚ค๋กœ ํŒ€์‚ฌ์ด๋“œ๋ฅผ MCP ๋„๊ตฌ๋กœ ์“ธ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ๋ณ„๋„ ์„œ๋ฒ„ ์—†์ด ์ฃผ์†Œ ํ•˜๋‚˜์— ๋ถ™์Šต๋‹ˆ๋‹ค.

ํ•ญ๋ชฉ๊ฐ’
์ฃผ์†Œhttps://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/mcp
๋ฐฉ์‹MCP Streamable HTTP ยท ์ƒํƒœ ์—†์Œ
์ธ์ฆ3์žฅ๊ณผ ๊ฐ™์€ API ํ‚ค (Authorization: Bearer jc_โ€ฆ ๋˜๋Š” X-API-Key)

ํ‚ค์˜ ๊ถŒํ•œ ๋ฒ”์œ„์— ๋“  ์ฝ๊ธฐ ๋„๊ตฌ๋งŒ ๋ณด์ž…๋‹ˆ๋‹ค: list_members ยท list_spaces ยท get_space ยท list_attendances. ๊ทœ์น™(์ปค์„œยทlimitยท92์ผ)์€ REST ์ฐฝ๊ตฌ์™€ ๊ฐ™๊ณ , MCP ์š”์ฒญ ํ•œ ํ†ต๋งˆ๋‹ค ์š”์ฒญ ํ•œ๋„์—์„œ 1ํšŒ๋ฅผ ์…‰๋‹ˆ๋‹ค.

claude code
claude mcp add --transport http joycollab https://<์„ค์น˜ ๋„๋ฉ”์ธ>/serv/api/external/v1/mcp \
  --header "Authorization: Bearer ${JC_API_KEY}"

AI ๋„๊ตฌ๋กœ ์ฝ์€ ๊ตฌ์„ฑ์›ยท๊ทผํƒœ ์ •๋ณด๋Š” ๊ณ ๊ฐ์ด ๊ณ ๋ฅธ AI ์—…์ฒด๋กœ ๋„˜์–ด๊ฐ‘๋‹ˆ๋‹ค. ์“ฐ๊ธฐ ์ „์— ์‚ฌ๋‚ด ๊ฐœ์ธ์ •๋ณด ์ฒ˜๋ฆฌ ๊ธฐ์ค€(๊ตฌ์„ฑ์› ๋™์˜ยท์œ„ํƒ ๊ณ„์•ฝ ๋“ฑ)์„ ํ™•์ธํ•˜์„ธ์š”.

๋„๊ตฌ๋ณ„ ์—ฐ๊ฒฐ ์˜ˆ์‹œ๋Š” ๋„์ž… ์ƒ๋‹ด ๋•Œ ํ•จ๊ป˜ ๋“œ๋ฆฝ๋‹ˆ๋‹ค. MCP ์—ฐ๊ฒฐ์€ ์ฒ˜์Œ์—” ๊บผ์ ธ ์žˆ๊ณ , ํšŒ์‚ฌ๊ฐ€ ์ผค์ง€ ์ •ํ•ฉ๋‹ˆ๋‹ค.

13. ํ‚ค ๋ฐœ๊ธ‰๊ณผ ๊ด€๋ฆฌ

์›Œํฌ์ŠคํŽ˜์ด์Šค ์†Œ์œ ์žยท๊ด€๋ฆฌ์ž๋Š” ํŒ€์‚ฌ์ด๋“œ ์„ค์ • โ€บ ๊ด€๋ฆฌ์ž ์„ค์ • โ€บ ยซ์™ธ๋ถ€ ์—ฐ๋™ ํ‚คยป์—์„œ ํ‚ค๋ฅผ ์ง์ ‘ ๋งŒ๋“ค๊ณ  ๋Š์„ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ํ‚ค๋งˆ๋‹ค ์ฝ์„ ํ•ญ๋ชฉ(4์žฅ)์„ ๊ณ ๋ฅด๊ณ , ์›๋ฌธ์€ ๋งŒ๋“ค ๋•Œ ํ•œ ๋ฒˆ๋งŒ ๋ณด์ž…๋‹ˆ๋‹ค. ์‚ฌ์šฉ ์ค‘์ธ ํ‚ค๋Š” ์›Œํฌ์ŠคํŽ˜์ด์Šค๋‹น 10๊ฐœ๊นŒ์ง€์ž…๋‹ˆ๋‹ค.

์ง์ ‘ ๋งŒ๋“ค๊ธฐ ์–ด๋ ต๊ฑฐ๋‚˜ ํ•œ๋„ ์กฐ์ •์ด ํ•„์š”ํ•˜๋ฉด ์•„๋ž˜๋ฅผ ์ ์–ด ์‹ ์ฒญํ•ด ์ฃผ์„ธ์š”.

  1. ์—ฐ๋™ํ•  ์›Œํฌ์ŠคํŽ˜์ด์Šค(์ด๋ฆ„ ๋˜๋Š” ์ฃผ์†Œ)
  2. ํ•„์š”ํ•œ ๊ถŒํ•œ ๋ฒ”์œ„(4์žฅ)
  3. ์˜ˆ์ƒ ํ˜ธ์ถœ๋Ÿ‰(๋ถ„๋‹น ๋ช‡ ํšŒ, ๋™๊ธฐํ™” ์ฃผ๊ธฐ)
  4. ํ‚ค ๋งŒ๋ฃŒ์ผ ํฌ๋ง ์—ฌ๋ถ€
  5. AI ๋„๊ตฌ(MCP)๋กœ ์“ธ์ง€ ์—ฌ๋ถ€ โ€” ์“ด๋‹ค๋ฉด ์‚ฌ๋‚ด ๊ฐœ์ธ์ •๋ณด ์ฒ˜๋ฆฌ ๊ธฐ์ค€์„ ํ™•์ธํ–ˆ๋‹ค๋Š” ํ™•์ธ

ํ‚ค๋ฅผ ์žƒ์–ด๋ฒ„๋ ธ๊ฑฐ๋‚˜ ์ƒˆ์–ด ๋‚˜๊ฐ„ ๊ฒƒ ๊ฐ™์œผ๋ฉด ๋ฐ”๋กœ ์•Œ๋ ค ์ฃผ์„ธ์š”. ํ๊ธฐํ•˜๊ณ  ๋‹ค์‹œ ๋ฐœ๊ธ‰ํ•ด ๋“œ๋ฆฝ๋‹ˆ๋‹ค. ๊ตฌ์ถ•ํ˜•์€ ์„ค์น˜ ๋‹ด๋‹น์ž์—๊ฒŒ ์š”์ฒญํ•ฉ๋‹ˆ๋‹ค.

์—ฐ๋™ ๋ฒ”์œ„ยทํ˜ธ์ถœ๋Ÿ‰ ์ƒ๋‹ด์ด ํ•„์š”ํ•˜์‹œ๋ฉด ํŽธํ•˜๊ฒŒ ๋ฌธ์˜ํ•ด ์ฃผ์„ธ์š”.

API ํ‚ค ยท ์—ฐ๋™ ๋ฌธ์˜

14. ๋ฌธ์ œ ํ•ด๊ฒฐ

์ฆ์ƒํ™•์ธํ•  ๊ฒƒ
์›น์‚ฌ์ดํŠธ 404 HTML์ด ์˜ด์ฃผ์†Œ์— /serv ๊ฐ€ ๋น ์กŒ๋Š”์ง€
401ํ‚ค ์˜คํƒ€ยทjc_ ์ ‘๋‘๋ถ€ยทBearer ๋’ค ๊ณต๋ฐฑยท๋งŒ๋ฃŒยทํ๊ธฐ. health ์— ํ‹€๋ฆฐ ํ‚ค๋ฅผ ๋ถ™์ด์ง€ ์•Š์•˜๋Š”์ง€
403๋ฉ”์‹œ์ง€์˜ ํ•„์š”ํ•œ scope ๋ฅผ ์‹ ์ฒญ
400 + ๊ทผํƒœfromยทto ํ˜•์‹, 92์ผ ์ด๋‚ด, to โ‰ฅ from
404 + ๊ณต๊ฐ„๊ณต๊ฐ„ ๋ฒˆํ˜ธ๊ฐ€ ์ด ํ‚ค์˜ ์›Œํฌ์ŠคํŽ˜์ด์Šค ๊ฒƒ์ธ์ง€
429๋ถ„๋‹น ํ•œ๋„ ์ดˆ๊ณผ. 60์ดˆ ๋’ค ๋‹ค์‹œ
๋‚ด์šฉ์ด ๊ฒน์น˜๊ฑฐ๋‚˜ ๋น ์ง์ชฝ์„ ๋„˜๊ธฐ๋Š” ์‚ฌ์ด ๋ฐ์ดํ„ฐ๊ฐ€ ๋ฐ”๋€œ. 6์žฅ ์ฐธ๊ณ 

์ตœ์ข… ๊ฐฑ์‹  2026-11-06 ยท API v1