1. æŠèŠ
| é ç® | å 容 |
|---|---|
| ããŒã¹URLïŒãªã³ãã¬ãã¹ïŒ | https://<å°å
¥ãã¡ã€ã³>/serv/api/external/v1 |
| æ¹åŒ | HTTPS · GETã®ã¿ · JSON(UTF-8) |
| èªèšŒ | APIããŒïŒX-API-Key ããããŒãŸã㯠Authorization: BearerïŒ |
| ããŒã¿ç¯å² | ããŒãçºè¡ããã¯ãŒã¯ã¹ããŒã¹1ã€ã®ããŒã¿ã®ã¿ |
| ãªã¯ãšã¹ãäžé | ããŒ1ã€ãããæ¢å®ã§æ¯å60å |
URLã«ã¯ /serv ãå
¥ããŸãã/serv ãªãã§åŒã³åºããšãAPIã§ã¯ãªãWebãµã€ãã®404ããŒãžãè¿ããŸãã
ãšã³ããã€ã³ãã¯æ¬¡ã®5ã€ã§ãã
| ã¡ãœãã | ãã¹ | å¿ èŠãªã¹ã³ãŒã | 説æ |
|---|---|---|---|
| GET | /health | ãªãïŒããŒäžèŠïŒ | ãµãŒããŒã®ç¶æ ç¢ºèª |
| GET | /members | members:read | ã¯ãŒã¯ã¹ããŒã¹ã®ã¡ã³ããŒäžèЧïŒã²ã¹ããé€ãïŒ |
| GET | /spaces | spaces:read | ã¹ããŒã¹ïŒéšçœ²ã»éšå±ïŒäžèЧ |
| GET | /spaces/{id} | spaces:read | ã¹ããŒã¹1ä»¶ |
| GET | /attendances | attendances:read | æéããšã®å€æ èšé² |
2. æåã®åŒã³åºã
â ç¶æ 確èªïŒããŒãªãïŒ
curl -s https://<å°å
¥ãã¡ã€ã³>/serv/api/external/v1/health{"success":true,"data":{"status":"UP","time":"2026-10-19T14:43:46.414+09:00","build":"unknown"}}â¡ ã¡ã³ããŒååŸïŒããŒãå¿ èŠïŒ
curl -s -H "X-API-Key: $JC_API_KEY" \
"https://<å°å
¥ãã¡ã€ã³>/serv/api/external/v1/members?limit=50"â¢ å€æ ååŸïŒæéã¯å¿ é ïŒ
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_xxxxxxxxxxxxxxxxAuthorization: Bearer jc_xxxxxxxxxxxxxxxx- ããŒã¯å¿
ã
jc_ã§å§ãŸããŸããBearerã§éã£ãå€ãjc_ã§å§ãŸããªãå Žåã¯ããŒãªããšã¿ãªãã401ãè¿ããŸãã - ããŒã®å šæã¯çºè¡æã«äžåºŠã ã衚瀺ãããŸãããµãŒããŒã«ã¯å ã«æ»ããªã圢ïŒããã·ã¥ïŒã§ã®ã¿ä¿åããããããçŽå€±ããå Žåã¯åçºè¡ãå¿ èŠã§ãã
- ããŒãªãã»äžæãªããŒã»å»æ¢ãããããŒã»æéåãã®ããŒã»é£æºå¥çŽã®åæ¢ã¯ããã¹ãŠåã
401ïŒJC-4001ïŒã§ããã©ãã«åœãããã¯ãããŠãç¥ããããŸããã /healthã誀ã£ãããŒãä»ãããš401ã§ããããŒãªããªã200ã§ãã- ããŒãæãã¯ãŒã¯ã¹ããŒã¹ã¯å€æŽã§ããããªã¯ãšã¹ãã§ã¯ãŒã¯ã¹ããŒã¹çªå·ãæå®ãããã©ã¡ãŒã¿ãŒããããŸããã
4. ã¹ã³ãŒã
ããŒããšã«èš±å¯ãããã¹ã³ãŒãã®ãšã³ããã€ã³ãã ããåŒã³åºããŸããã¹ã³ãŒãããªãå Žå㯠403ïŒJC-4003ïŒãšãªããã¡ãã»ãŒãžã«å¿
èŠãªã¹ã³ãŒããèšèŒãããŸãã
| scope | 䜿ãããšã³ããã€ã³ã |
|---|---|
members:read | GET /members |
spaces:read | GET /spaces · GET /spaces/{id} |
attendances:read | GET /attendances |
å¿ èŠãªã¹ã³ãŒãã ããç³è«ããŠãã ããïŒæå°æš©éïŒãã¹ã³ãŒãã远å ããã«ã¯ããŒã®åçºè¡ãå¿ èŠãªå ŽåããããŸãã
5. ã¬ã¹ãã³ã¹ã®åœ¢
æå
{
"success": true,
"data": [ ],
"meta": { "cursor": "bzo1MA", "hasMore": true }
}- äžèЧã®ãšã³ããã€ã³ãïŒ
membersã»spacesã»attendancesïŒã¯dataãé åã§ãmetaãä»ããŸãã - 1ä»¶ååŸïŒ
spaces/{id}ïŒã»healthã«ã¯metaããããŸããã - å€ã®ãªããã£ãŒã«ãã¯
nullã§ã¯ãªãããŒããšçç¥ãããŸãããããŒããªããã°å€ãªãããšããŠæ±ã£ãŠãã ããã - ä»åŸãã£ãŒã«ãã远å ãããããšããããŸããç¥ããªããã£ãŒã«ãã¯ç¡èŠããŠãã ããã
倱æ
{
"success": false,
"error": { "code": "JC-4001", "message": "ì íší API í€ê° íìí©ëë€." }
}- ããã°ã©ã ã§ã®åå²ã«ã¯
error.codeã䜿ã£ãŠãã ãããerror.messageã¯äººãèªãéåœèªã®èª¬æã§ãæèšã¯å€ããããšããããŸãã error.detailã¯ãããšãã ãä»ããŸãïŒäž»ã«ãã©ã¡ãŒã¿ãŒã®æ¬ èœã»åœ¢åŒãšã©ãŒïŒã倱ææã«ã¯dataã»metaã¯ãããŸããã- ã³ãŒãã®äžèŠ§ã¯ 10. ãšã©ãŒã³ãŒã ãã芧ãã ããã
6. ããŒãžã³ã°
- äžèЧã¯
limitïŒ1åã«åãåãä»¶æ°ïŒãš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é ã§ããããŒãžéãã®éã«ããŒã¿ãå€ãããšéè€ãæ¬ èœãèµ·ããåŸããããå šä»¶åæã¯æåŸãŸã§åãåã£ãŠããçªå·ã§éè€ãé€ããŠãã ããã
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')
done7. ãªã¯ãšã¹ãäžé
- äžéã¯APIããŒ1ã€ãããã®æ¯åãªã¯ãšã¹ãæ°ã§ããæ¢å®ã¯60å/åã§ãããŒããšã«ç°ãªãå ŽåããããŸãã
- 1ååäœã®åºå®åºéã§æ°ããŸãïŒæèšã®åãå€ãããš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. ãšã³ããã€ã³ã
/health
ããŒäžèŠãµãŒããŒã®ç¶æ ã確èªããŸãã誀ã£ãããŒãä»ãããš401ã§ãã
| ãã£ãŒã«ã | å | 説æ |
|---|---|---|
status | æåå | æ£åžžãªã "UP" |
time | æååïŒISO-8601ïŒ | ãµãŒããŒã®çŸåšæå»ïŒKSTïŒ |
build | æåå | 皌åäžã®ãã«ãã®èå¥å€ãäžæãªç°å¢ã§ã¯ "unknown"ã圢åŒã¯ä¿èšŒããªããã衚瀺ã»èšé²çšã«ã®ã¿äœ¿ã£ãŠãã ãã |
/members
members:readã¡ã³ããŒäžèЧã§ããã²ã¹ããšéäŒããã¡ã³ããŒã¯é€ããŸããããã¯ããŒã é ã§ãã
| ãã©ã¡ãŒã¿ãŒ | äœçœ® | å¿ é | 説æ |
|---|---|---|---|
limit | ã¯ãšãª | ããã | 1ïœ200ãæ¢å®50 |
cursor | ã¯ãšãª | ããã | ååã¬ã¹ãã³ã¹ã® meta.cursor |
| ãã£ãŒã«ã | å | 説æ |
|---|---|---|
memberSeq | æŽæ° | ã¡ã³ããŒçªå·ïŒã¯ãŒã¯ã¹ããŒã¹å
ã§äžæïŒã倿 ã® memberSeq ãšåãå€ |
account | æåå | ãã°ã€ã³ã¢ã«ãŠã³ãïŒã¡ãŒã«åœ¢åŒïŒãå€éšã·ã¹ãã ã®ç€Ÿå¡ãšçªãåãããã㌠|
name | æåå | æ°å |
nickname | æåå | ã¯ãŒã¯ã¹ããŒã¹ã§ã®è¡šç€ºå |
jobGrade | æåå | è·äœïŒãªããã°çç¥ïŒ |
spaceName | æåå | æå±ã¹ããŒã¹ïŒéšçœ²ïŒåïŒãªããã°çç¥ïŒ |
status | æåå | çŸåšã®ç¶æ
åãéåœèªã§è¿ããŸãïŒäŸ: ìšëŒìž ãªã³ã©ã€ã³ã»ì€íëŒìž ãªãã©ã€ã³ã»ë¶ì¬ì€ äžåšïŒãçš®é¡ã¯å¢ããããšããããããç¥ããªãå€ããã®ãŸãŸåãåã£ãŠãã ãã |
é»è©±çªå·ã»äœæã»äœçœ®ã»çå¹Žææ¥ã»äºæ¥è æ å ±ã¯æäŸããŸããã
curl -s -H "X-API-Key: $JC_API_KEY" \
"https://<å°å
¥ãã¡ã€ã³>/serv/api/external/v1/members?limit=2"{
"success": true,
"data": [
{ "memberSeq": 1021, "account": "[email protected]", "name": "å±±ç° å€ªé",
"nickname": "倪é", "jobGrade": "課é·", "spaceName": "éçºããŒã ", "status": "ìšëŒìž" },
{ "memberSeq": 1034, "account": "[email protected]", "name": "äœè€ è±å",
"nickname": "è±å", "status": "ì€íëŒìž" }
],
"meta": { "cursor": "bzoy", "hasMore": true }
}/spaces
spaces:read䜿çšäžã®ã¹ããŒã¹ïŒéšçœ²ã»éšå±ïŒäžèЧã§ããspaceSeq é ã§ãããã©ã¡ãŒã¿ãŒã¯ limitã»cursorïŒäžãšåãïŒã§ãã
| ãã£ãŒã«ã | å | 説æ |
|---|---|---|
spaceSeq | æŽæ° | ã¹ããŒã¹çªå· |
name | æåå | ã¹ããŒã¹å |
topSpaceSeq | æŽæ° | äžäœã¹ããŒã¹ã®çªå·ãæäžäœãªãçç¥ |
{
"success": true,
"data": [
{ "spaceSeq": 301, "name": "æ¬ç€Ÿ" },
{ "spaceSeq": 305, "name": "éçºããŒã ", "topSpaceSeq": 301 }
],
"meta": { "hasMore": false }
}/spaces/{id}
spaces:readã¹ããŒã¹1ä»¶ã§ããidïŒãã¹ã»æŽæ°ïŒãæŽæ°ã§ãªããã° 400 ã§ããdata ã¯äžã®äžèЧã®é
ç®1ã€ãšåã圢ã§ãã
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ïŒã§ããä»ç€Ÿã®ããŒã¿ã®æç¡ãæšæž¬ã§ããªãããã«ããããã§ãã
/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 ã¯çŸæç¹ãŸã§ã§æ°ãããããåååŸãããšå¢ããããšããããŸãã
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-4000 | 400 | äžæ£ãªãªã¯ãšã¹ã | 倿 ã® from/to ã®æ¬ èœã»åœ¢åŒãšã©ãŒã»92æ¥è¶
éãcursor ãè§£éã§ããªããæ°å€ã®äœçœ®ã«æ°å€ä»¥å€ | ãªã¯ãšã¹ãã®ä¿®æ£ãå¿ èŠ |
JC-4001 | 401 | èªèšŒå€±æ | ããŒãªãã»äžæã»å»æ¢ã»æéåãã»é£æºåæ¢ãhealth ã«èª€ã£ãã㌠| ããŒã®ç¢ºèªãŸãã¯åçºè¡ |
JC-4003 | 403 | ã¹ã³ãŒãäžè¶³ | ããŒã«ãã®ãšã³ããã€ã³ãã®ã¹ã³ãŒãããªãïŒã¡ãã»ãŒãžã«èšèŒïŒ | ã¹ã³ãŒãã®è¿œå ç³è« |
JC-4004 | 404 | èŠã€ãããªã | ååšããªãã»åé€ãããã¹ããŒã¹ããŸãã¯ä»ã®ã¯ãŒã¯ã¹ããŒã¹ã®ã¹ããŒã¹ | çªå·ãç¢ºèª |
JC-4029 | 429 | ãªã¯ãšã¹ãäžéè¶ é | ããŒ1ã€ã®æ¯åäžéãè¶
éã»Retry-After: 60 | 60ç§åŸ |
JC-5000 | 500 | ãµãŒããŒå éšãšã©ãŒ | äºæããªããšã©ãŒïŒã¬ã¹ãã³ã¹ã¯äžè¬çãªæèšã®ã¿ïŒ | ãã°ããããŠå詊è¡ãç¶ãå Žåã¯ãåãåãã |
- 401ã¯åå ãåºå¥ããã403ã¯ã¹ã³ãŒãäžè¶³ã®1çš®é¡ã ãã§ããä»ã®ã¯ãŒã¯ã¹ããŒã¹ã®ããŒã¿ã¯403ã§ã¯ãªã404ã§ãã
- 4xxxã¯åŒã³åºãåŽã5xxxã¯ãµãŒããŒåŽã®è²¬ä»»ã§ãã衚ã«ãªãã³ãŒããåãåã£ããHTTPã¹ããŒã¿ã¹ã§åŠçãããç¥ãããã ããã
- ãµãŒããŒå段ïŒãã¡ã€ã¢ãŠã©ãŒã«ã»CDNïŒã«ããæåŠïŒ502ã»503ã»504ãªã©ïŒãæªå®çŸ©ã®ãã¹ã§ã¯ããã®åœ¢ã«ãªããªãããšããããŸããæ¬æãJSONã§ãªããã°ããŸãURLã確èªããŠãã ããã
11. Webhookã®åä¿¡ïŒéç¥ã®éä¿¡ïŒ
teamsideãæ¥åéç¥ãã客æ§ãæå®ããURLãžéãæ©èœã§ããäžã®èªã¿åãAPIãšã¯ç°ãªãããåãåãåŽããéçºããå Žåã®èª¬æã§ãã
èšå®ãšåæ
- ã¯ãŒã¯ã¹ããŒã¹ã®ãªãŒããŒã»ç®¡çè ãèšå®ç»é¢ã§åä¿¡å URLãç»é²ããŸãïŒã¯ãŒã¯ã¹ããŒã¹ãããæå€§20ãæïŒãAPIããŒã§ã¯ç»é²ã§ããŸããã
- åä¿¡å ããšã«ãåãåãéç¥ã®çš®é¡ïŒãŸãã¯ããã¹ãŠãïŒã»ç¯å²ïŒã¯ãŒã¯ã¹ããŒã¹å šäœïŒç¹å®ã®ãããžã§ã¯ãïŒç¹å®ã®æ±ºè£æ§åŒïŒã»ã¿ã€ãã«é衚瀺ãéžã³ãŸããã¿ã€ãã«é衚瀺ããªã³ã«ãããšãæ¬æããã¿ã€ãã«ãå®å šã«é€ãããŸãã
- URLã¯ã€ã³ã¿ãŒãããããå°éã§ããå¿ èŠããããŸãã瀟å ã®ãã©ã€ããŒããããã¯ãŒã¯ã®ã¢ãã¬ã¹ã¯ç»é²ã§ãããéä¿¡çŽåã«ãå確èªããŸãããªãã€ã¬ã¯ãïŒ3xxïŒã¯è¿œè·¡ããªããããæçµURLãç»é²ããŠãã ããã
- éä¿¡æ©èœã¯ãµãŒããŒéçšè ãæå¹ã«ããå¿ èŠããããŸããå°å ¥æã«æå¹ã確èªããŠãã ããã
éä¿¡æ¹åŒ
POST·Content-Type: application/json· UTF-8ã®JSONæ¬æã- æ¥ç¶3ç§ã»å¿ç10ç§ä»¥å
ã«
2xxãè¿ããšåä¿¡æåãšã¿ãªããŸããæéã®ãããåŠçã¯åä¿¡åŸã«å¥éè¡ã£ãŠãã ããã - 眲åããŒãç»é²ããåä¿¡å
ã«ã¯
X-JC-Signature: sha256=<å°æåã®hex>ããããŒãä»ããŸãã - åãåä¿¡å
ã«ã¯éä¿¡æå»å
¥ãã®
X-JC-Signature-V2: t=<UNIXç§>,v1=<å°æåã®hex>ããããŒãä»ããŸãïŒ2026-11-08ãïŒããªãã¬ã€ïŒååããèŠæ±ã®åéïŒãé²ãã«ã¯ãã¡ãã確èªããŠãã ããã - å詊è¡ã®ããåãæ¬æã2å以äžå±ãããšããããŸãã
eventã»alarmSeqïŒãªããã°occurredAtïŒsubjectïŒã§éè€ãé€ããŠãã ããã
眲åã®æ€èšŒ
眲åã¯åä¿¡ããæ¬æã®ãã€ãåãã®ãŸãŸïŒåã·ãªã¢ã©ã€ãºããªãåæïŒã«å¯ŸããHMAC-SHA256ã§ãéµã¯ç»é²ãã眲åããŒã§ããæ¯èŒã¯æéå·®ãåºãªãæ¹æ³ã§è¡ã£ãŠãã ããã
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);
}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 ãåŒãç¶ãä»ãã®ã§ãæ¢åã®æ€èšŒã¯ãã®ãŸãŸã§åããŸãã
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ã®URLïŒ
{
"event": "approval.requested",
"occurredAt": 1792382400000,
"workspaceSeq": 12,
"alarmSeq": 55012,
"actor": "倪é",
"recipients": [1034, 1050],
"subject": { "requestSeq": 7001, "title": "10æã®åºåŒµè²»", "requestType": "çµè²»ç³è«æž" }
}| ãã£ãŒã«ã | 説æ |
|---|---|
event | ã€ãã³ãããŒïŒäžã®è¡šïŒãäžåºŠæ±ºããååã¯å€ããŸãã |
occurredAt | çºçæå»ããšããã¯ããªç§ïŒæ°å€ïŒ |
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ã®URLã®ã¿ïŒ |
member.joined ã¯ããã¹ãŠããéžãã äžè¬ã®JSONã®URLã«ã®ã¿éããããã® occurredAt ã¯æ°å€ã§ã¯ãªãæååã§ãããŸã event ã§åå²ããŠãã ããã
Teamsã»Slackã§åãåã
URLã®ãã¹ãã hooks.slack.comã*.webhook.office.comã*.environment.api.powerplatform.comã*.logic.azure.com ã®å Žåããã®ãµãŒãã¹ã衚瀺ã§ãã圢ã§1è¡ã®éç¥ãäœã£ãŠéããŸãããã®ãšãã¯äžã®äžè¬ã®JSONã»çœ²åã¯äœ¿ããŸããã
倱æãšå詊è¡
| åãåã£ãå¿ç | åŠç |
|---|---|
2xx | æå |
408 · 429 · 5xx · 3xx · æ¥ç¶å€±æã»ã¿ã€ã ã¢ãŠã | åè©Šè¡ |
ãã®ä»ã® 4xx | ããã«äžæ¢ |
æåã®1åãšå詊è¡4åãåãããŠ5åãŸã§è©Šã¿ãééã¯åŸã ã«åºãããŸãïŒæå€§4åååŸïŒã5åãšã倱æãããã®ã¯åéããŸãããåä¿¡å ããªãã«ããŠããéã®éç¥ã¯èç©ãããŸããã
12. AIããŒã«æ¥ç¶ïŒMCPïŒ
Claudeã»ChatGPTã»Geminiãªã©ã®AIããŒã«ããåãAPIããŒã§teamsideãMCPããŒã«ãšããŠäœ¿ããŸããå¥éãµãŒããŒã¯äžèŠã§ãURL1ã€ã§æ¥ç¶ããŸãã
| é ç® | å€ |
|---|---|
| URL | 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åããšã«ãªã¯ãšã¹ãäžéã1åæ°ããŸãã
claude mcp add --transport http joycollab https://<å°å
¥ãã¡ã€ã³>/serv/api/external/v1/mcp \
--header "Authorization: Bearer ${JC_API_KEY}"AIããŒã«ã§èªã¿åã£ãã¡ã³ããŒã»å€æ ã®æ å ±ã¯ã客æ§ãéžãã AIäºæ¥è ã«æž¡ããŸããå©çšåã«ç€Ÿå ã®å人æ å ±åæ±ãåºæºïŒã¡ã³ããŒã®åæã»å§èšå¥çŽãªã©ïŒã確èªããŠãã ããã
ããŒã«ããšã®æ¥ç¶äŸã¯å°å ¥ã®ãçžè«æã«ãæž¡ãããŸããMCPæ¥ç¶ã¯åæç¶æ ã§ãªãã§ãäŒç€Ÿããªã³ã«ãããã©ãããæ±ºããŸãã
13. ããŒã®çºè¡ãšç®¡ç
ã¯ãŒã¯ã¹ããŒã¹ã®ãªãŒããŒã»ç®¡çè ã¯ãteamsideã®èšå® ⺠管çè èšå® ⺠ãå€éšé£æºããŒãã§ããŒãèªåã§äœæã»å»æ¢ã§ããŸããããŒããšã«èªã¿åããé ç®ïŒ4ç« ïŒãéžã³ãããŒã®å šæã¯äœææã«äžåºŠã ã衚瀺ãããŸãã䜿çšäžã®ããŒã¯ã¯ãŒã¯ã¹ããŒã¹ããã10åãŸã§ã§ãã
ãèªèº«ã§ã®äœæãé£ããå Žåãäžéã®èª¿æŽãå¿ èŠãªå Žåã¯ã次ãèšå ¥ããŠãç³ã蟌ã¿ãã ããã
- 飿ºããã¯ãŒã¯ã¹ããŒã¹ïŒååãŸãã¯URLïŒ
- å¿ èŠãªã¹ã³ãŒãïŒ4ç« ïŒ
- æ³å®åŒã³åºãéïŒæ¯åã®åæ°ãåæã®åšæïŒ
- ããŒã®æå¹æéã®åžææç¡
- AIããŒã«ïŒMCPïŒã§äœ¿ããã©ãã â 䜿ãå Žåã¯ç€Ÿå ã®å人æ å ±åæ±ãåºæºãç¢ºèªæžã¿ã§ããããš
ããŒãçŽå€±ããããŸãã¯æŒããããæããããå Žåã¯ããã«ãç¥ãããã ããã廿¢ããŠåçºè¡ããŸãããªã³ãã¬ãã¹ã®å Žåã¯å°å ¥æ åœè ã«ãäŸé Œãã ããã
ã¹ã³ãŒããåŒã³åºãéã®ãçžè«ããæ°è»œã«ã©ããã
APIããŒã»é£æºã®ãåãåãã14. ãã©ãã«ã·ã¥ãŒãã£ã³ã°
| çç¶ | 確èªããããš |
|---|---|
| Webãµã€ãã®404 HTMLãè¿ã | URLãã /serv ãæããŠããªãã |
401 | ããŒã®èª€åã»jc_ ã®æ¥é èŸã»Bearer ã®åŸã®ç©ºçœã»æéåãã»å»æ¢ãhealth ã«èª€ã£ãããŒãä»ããŠããªãã |
403 | ã¡ãã»ãŒãžã«ããã¹ã³ãŒããç³è« |
倿 ã§ 400 | fromã»to ã®åœ¢åŒã92æ¥ä»¥å
ãto ⥠from |
ã¹ããŒã¹ã§ 404 | ã¹ããŒã¹çªå·ããã®ããŒã®ã¯ãŒã¯ã¹ããŒã¹ã®ãã®ã |
429 | æ¯åã®äžéè¶ éã60ç§åŸã«åè©Šè¡ |
| å 容ã®éè€ã»æ¬ èœ | ããŒãžéãã®éã«ããŒã¿ãå€åã6ç« åç § |
æçµæŽæ° 2026-11-06 · API v1