API 문서

Shifton 작업에서는 공개 API를 통해 플랫폼 작업을 자동화하고 외부 서비스와 연결할 수 있습니다. API로는 작업, 고객, 직원, 체크리스트, 재고, 서비스 구역, 재무 문서, 보고서 등 모든 핵심 개체를 이용할 수 있으므로, Shifton을 회사의 HR, 급여 계산, 분석 시스템은 물론 사내 서비스와도 연결할 수 있습니다.

문서는 두 가지 버전으로 공개되어 있습니다.

🚀 새 문서 — 구조가 새로 정리되고 최신 메서드가 포함된 현행 참조 문서입니다: 👉 https://api2.shifton.com/openapi/
📄 이전 문서 — 이전 버전입니다(기존 연동을 위해 계속 지원됩니다): 👉 https://api2.shifton.com/docs/

두 버전 모두 앱에서 바로 열 수 있습니다. Developer 섹션의 개요 탭에서 “새 문서”와 “이전 문서” 버튼을 사용하세요.

문서는 두 가지 언어로 제공됩니다. 새 문서 페이지의 오른쪽 위 모서리에는 EN / RU 전환 스위치가 있으며, 선택한 언어는 기억됩니다.

API 키를 받는 방법

API 키는 앱 안에서 만듭니다.

Developer 섹션을 여세요.
API 키 탭(“API 키”)으로 이동하세요.
“API 키 생성”을 클릭하세요.

키를 만들 때 입력할 내용

API 키 생성 사이드 패널이 열리며, 다음 필드가 있습니다.

제목 — 키의 이름이며 필수 항목입니다. 나중에 무엇을 끊어야 할지 알 수 있도록 용도에 맞게 이름을 지으세요. 예를 들어 “1С로 내보내기”, “분석용 보고서”처럼 씁니다.
만료 시간 — 이 날짜가 지나면 키가 작동하지 않습니다. 비워 두면 유효 기간에 제한이 없습니다.
액세스 — 키의 권한 범위입니다.
Full access (act as me) — 키가 본인 이름으로, 본인과 같은 권한으로 작동합니다.
제한된 권한 — 직접 선택한 제한된 권한 집합입니다.

키를 만들려면 추가를, 패널을 닫으려면 취소를 클릭하세요.

📷 *키 생성 패널 스크린샷 — 프로덕션에서 촬영할 것*

키는 특정 회사용으로 만들어지며 해당 회사의 데이터에만 작동합니다. 키는 언제든지 폐기할 수 있고, 폐기는 즉시 적용되므로 이후 이 키로 보내는 모든 요청은 401 오류를 반환합니다.

중요: 생성된 키는 한 번만 표시됩니다. 즉시 복사해 안전한 곳에 보관하세요. 다시 확인할 수는 없습니다. 키를 잃어버렸다면 새 키를 만들고 기존 키는 폐기하세요.

인증

API로 보내는 모든 요청은 헤더에 키를 담아 서명합니다.

Authorization: Bearer {your_API_key}

API 기본 주소는 다음과 같습니다.

https://api2.shifton.com/work/1.0.0

유효한 키 없이 보낸 요청은 401과 {"message":"Unauthenticated."} 본문을 반환합니다.

첫 번째 요청

예를 들어 회사의 직원 목록을 가져오려면 다음과 같이 합니다({companyId} 자리에 본인 회사 ID를 넣으세요).

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

curl로 같은 요청을 보내는 방법입니다.

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

회사 ID는 앱의 주소창에서 볼 수 있습니다. app.shifton.com/c/8397/... — /c/ 뒤에 오는 숫자입니다.

API로 이용할 수 있는 기능

참조 문서에는 360개가 넘는 메서드가 실려 있습니다. 현장 서비스와 관련된 주요 섹션은 다음과 같습니다.

작업 — /companies/{companyId}/tasks: 작업 생성, 수정, 상태, 파일.
할 일 목록 (To Do) — /companies/{companyId}/todo.
고객 — /companies/{companyId}/clients, 그리고 고객 주소와 사용자 지정 필드.
체크리스트 — /companies/{companyId}/checklists.
서비스 구역 — /companies/{companyId}/tasks/service-areas.
기술 — /companies/{companyId}/skills.
직원 — /companies/{companyId}/employees: 추가, 편집, 해고, 복원.
재고 — 물품, 카테고리, 세트, 창고 재고.
재무 문서 — 견적, 작업 지시, 송장, 영수증, 문서 카운터, 로고.
보고서 — 업무 및 출근 데이터 내보내기.

이 외에도 일정과 근무, 휴가와 휴가 신청, 출근, 결제와 SMS 청구, 알림, 모듈을 이용할 수 있습니다.

웹훅

API를 주기적으로 호출하는 대신 이벤트가 발생하는 순간에 받아야 한다면 웹훅을 사용하세요. Developer 섹션의 Webhooks 탭에 있습니다. 필요한 이벤트가 발생하면 Shifton이 직접 지정한 주소로 요청을 보내며, 지원되는 이벤트 목록은 별도의 메서드로 확인할 수 있습니다.

오류 코드

Shifton API는 표준 HTTP 상태 코드를 사용합니다.

200 — 요청이 성공적으로 처리되었습니다.
201 — 객체가 성공적으로 생성되었습니다.
400 — 요청 매개변수가 잘못되었습니다.
401 — 인증 오류입니다. 키가 전달되지 않았거나, 유효하지 않거나, 폐기되었습니다.
403 — 접근이 거부되었습니다.
404 — 리소스를 찾을 수 없습니다(대개 메서드 주소의 오타 때문입니다).
500 — 서버 오류입니다.

사용 팁

새로 만드는 연동에는 새 문서를 사용하세요. 이전 문서는 이미 작동 중인 연동을 위해 남겨 둔 것입니다.
요청을 확인할 때는 Postman이나 curl이 편리합니다. 코드를 한 줄도 쓰지 않고 응답을 볼 수 있습니다.
키를 코드에 그대로 저장하거나 제3자에게 전달하지 마세요. 키는 회사 데이터에 대한 접근을 허용합니다.
요청 빈도 제한(rate limits)을 지키세요. 이를 넘기면 API 접근이 일시적으로 차단될 수 있습니다.

자주 묻는 질문

질문: API 키는 어디에서 받나요? 답변: 앱에서 받습니다. Developer 섹션 → API 키 탭 → “API 키 생성” 버튼입니다. 키는 현재 회사용으로 발급됩니다.

질문: 창을 닫아서 키를 복사하지 못했습니다. 어디에서 확인할 수 있나요? 답변: 어디에서도 볼 수 없습니다. 키는 한 번만 표시되며 다시 발급되지 않습니다. 새 키를 만들고 기존 키는 폐기하세요.

질문: 키가 다른 사람 손에 넘어갔다면 어떻게 폐기하나요? 답변: API 키 탭에서 삭제하세요. 폐기는 즉시 적용되어 이 키로 보내는 모든 요청이 바로 401을 반환합니다.

질문: “Full access”와 “Restricted permissions”의 차이는 무엇인가요? 답변: Full access (act as me)는 키에 본인과 같은 권한을 부여합니다. 제한된 권한은 선택한 권한만 키에 부여하므로, 데이터의 일부만 필요한 연동에는 더 안전합니다.

질문: 키의 유효 기간을 제한할 수 있나요? 답변: 예. 키를 만들 때 만료 시간 필드를 사용하세요. 비워 두면 키는 기간 제한 없이 유효합니다.

질문: 하나의 키를 여러 회사에서 쓸 수 있나요? 답변: 아니요. 키는 생성된 회사에 연결되며 해당 회사의 데이터에만 작동합니다. 다른 회사에서는 별도의 키를 만드세요.

질문: API의 기본 주소는 무엇인가요? 답변: https://api2.shifton.com/work/1.0.0입니다. 그 뒤에 메서드 경로가 붙습니다. 예를 들어 /companies/{companyId}/tasks입니다.

질문: 요청에 쓸 회사 ID는 어디에서 받나요? 답변: 앱의 주소창에서 /c/ 바로 뒤에 있습니다. 예를 들어 app.shifton.com/c/8397/tasks에서 회사 식별자는 8397입니다.

질문: 어느 버전의 문서를 사용해야 하나요? 답변: 새로 만드는 연동에는 새 문서(api2.shifton.com/openapi)를 사용하세요. 이전 문서(api2.shifton.com/docs)는 기존 연동을 위해 지원됩니다.

질문: 러시아어 문서도 있나요? 답변: 예. 새 문서 페이지의 오른쪽 위 모서리에 EN / RU 전환 스위치가 있습니다.

질문: API 요청은 무엇으로 테스트하나요? 답변: Postman이나 curl이 가장 편리합니다. 코드를 쓰지 않고도 요청을 보내고 응답을 볼 수 있습니다.

질문: 키를 복사했는데도 401이 오는 이유는 무엇인가요? 답변: 키가 Authorization 헤더에 Bearer라는 단어와 함께 전달되는지, 키가 폐기되지 않았는지, 유효 기간이 지나지 않았는지 확인하세요.

질문: 404가 오는 이유는 무엇인가요? 답변: 대개 주소를 잘못 쓴 경우입니다. 기본 부분은 https://api2.shifton.com/work/1.0.0이어야 하고, 메서드 경로에는 올바른 {companyId}가 있어야 합니다.

질문: API로 무엇을 자동화할 수 있나요? 답변: 작업 생성과 수정, 고객과 고객 주소 관리, 체크리스트, 서비스 구역, 기술, 직원, 재고, 재무 문서, 보고서 내보내기는 물론 일정, 근무, 휴가까지 자동화할 수 있습니다.

질문: API를 계속 호출하지 않고 Shifton에서 이벤트를 받을 수 있나요? 답변: 예. 이를 위해 웹훅이 있으며, Developer 섹션의 Webhooks 탭에서 설정합니다.

질문: 비밀번호를 변경하면 연동 작동에 영향이 있나요? 답변: 아니요. 연동은 계정 비밀번호가 아니라 API 키로 작동합니다.