새티스팩토리 전용 서버 HTTPS API 정리
작성일 2026-07-26 · SameOS Tools
새티스팩토리 1.0부터 전용 서버에 공식 HTTPS API가 들어왔습니다. 세이브 백업, 서버 상태 확인, 콘솔 명령 실행까지 스크립트로 할 수 있어서, 서버를 직접 굴린다면 알아 둘 가치가 충분합니다. 그런데 구조가 팰월드나 다른 게임과 꽤 달라서 처음에 헤매기 쉽습니다 - 이 글은 그 다른 점부터 정리합니다.
주소는 하나, 함수 이름으로 부른다
보통의 API는 기능마다 주소가 다르지만, 새티스팩토리는 https://서버주소:7777/api/v1 주소 하나에 POST로 {"function": "함수이름", "data": {...}} 형태의 JSON을 보내는 방식입니다. 어떤 기능이든 주소는 같고 function 값만 바뀝니다. 그리고 항상 HTTPS인데, 인증서를 따로 넣지 않으면 서버가 자체 서명 인증서(공인 기관 없이 스스로 만든 인증서 - 암호화는 되지만 브라우저·도구가 신뢰하지 않아 경고를 냅니다)를 만들어 쓰므로, curl 에서는 -k 옵션으로 검증을 건너뛰어야 합니다.
토큰 발급 - 스크립트용은 콘솔에서
권한은 토큰(로그인 대신 요청에 실어 보내는 열쇠 문자열)으로 확인합니다. 사람이 쓸 때는 PasswordLogin 함수에 관리자 비밀번호를 보내 짧게 쓰는 토큰을 받으면 되지만, 백업 스크립트처럼 오래 돌 프로그램은 서버 콘솔에서 server.GenerateAPIToken 명령으로 만드는 전용 토큰을 쓰는 게 맞습니다 - 만료가 없고, server.InvalidateAPITokens 로 한 번에 회수할 수 있습니다. 받은 토큰은 요청의 Authorization: Bearer 헤더에 실어 보냅니다.
함수 24개 분류
| 분류 | 함수 | 용도 |
|---|---|---|
| 조회 | HealthCheckQueryServerStateGetServerOptionsGetAdvancedGameSettingsEnumerateSessions |
살아 있는지, 접속 인원·틱 상태, 설정값, 세션 목록 |
| 인증 | PasswordLoginPasswordlessLoginVerifyAuthenticationToken |
토큰 받기(비밀번호 유/무)와 토큰 확인 |
| 운영 | RunCommandShutdownApplyServerOptionsApplyAdvancedGameSettingsRenameServerSetClientPasswordSetAdminPasswordSetAutoLoadSessionNameClaimServer |
콘솔 명령 실행, 종료, 설정 적용, 이름·비밀번호 변경, 최초 점유 |
| 세이브 | SaveGameLoadGameCreateNewGameEnumerateSessionsDeleteSaveFileDeleteSaveSessionUploadSaveGameDownloadSaveGame |
저장·불러오기·새 게임, 세이브 파일 올리기/내려받기 |
이 중 실제 운영에서 매일 쓰게 되는 것은 HealthCheck(감시), QueryServerState(인원 확인), SaveGame·DownloadSaveGame(백업), Shutdown(재시작 전 정리) 정도입니다. DownloadSaveGame 이 특히 좋습니다 - 세이브 파일을 서버 밖으로 복사해 오는 백업이 API 호출 한 번으로 끝납니다.
curl 예제
# 살아 있는지 확인 (인증 불필요, -k 는 자체 서명 인증서 허용)
curl -k -X POST https://127.0.0.1:7777/api/v1 \
-H "Content-Type: application/json" \
-d '{"function": "HealthCheck", "data": {"clientCustomData": ""}}'
# 서버 상태 조회 (콘솔에서 server.GenerateAPIToken 으로 만든 토큰 사용)
curl -k -X POST https://127.0.0.1:7777/api/v1 \
-H "Authorization: Bearer 토큰값" \
-H "Content-Type: application/json" \
-d '{"function": "QueryServerState", "data": {}}'서버를 처음 여는 과정(설치·포트·systemd 등록)은 서버 구축 글에서 다뤘고, 생산 라인 계산이 필요하면 계산기 글이 있습니다.