3Works 오픈 API 명세서 · 건설사 시스템 연동 가이드

개요

3Works 오픈 API는 REST 기반·JSON 통신의 표준 HTTPS API입니다. 건설사 전산팀은 자사 시스템에서 발주를 생성하고 출역 현황을 조회할 수 있으며, 모든 요청은 발급받은 API Key로 인증됩니다.

BASE URL

https://3works.co.kr/api

프로토콜

HTTPS · TLS 1.2+

포맷

application/json (UTF-8)

퀵스타트

1
연동할 용역회사 사장님께 API Key 발급을 요청합니다. (용역회사 설정 → 우리 회사 Open API 관리 → 새 API Key 발급받기)
2
전달받은 키를 모든 요청의 X-3Works-API-Key 헤더에 넣습니다.
3
아래 발주 생성 예제를 복사·붙여넣기 하면 즉시 첫 오더가 용역회사 장부에 꽂힙니다.

첫 요청 (cURL)

# API 연결 상태 확인 — 키가 유효하면 우리 회사 정보가 반환됩니다
curl https://3works.co.kr/api/v1/open/ping/ \
  -H "X-3Works-API-Key: tw_live_여기에_발급받은_키"

인증 (API Key)

모든 API 요청은 HTTP 헤더에 API Key를 포함해야 합니다. 키 1개가 곧 1개 용역회사를 식별하므로, 이 키로 들어온 오더는 자동으로 해당 용역회사 장부에 격리·기록됩니다.

보안 주의 — API Key는 비밀번호와 동일합니다. 클라이언트(브라우저·앱) 코드에 노출하지 말고 서버 측에서만 사용하세요. 유출 시 용역회사 설정에서 즉시 폐기·재발급할 수 있습니다.

인증 헤더

X-3Works-API-Key: tw_live_a8Kd...3fZq
Content-Type: application/json

RATE LIMIT

⏳ 과부하 방지 및 트래픽 제한

본 오픈 API는 안정적인 서비스 운영을 위해 API Key당 초당 5회, 분당 60회의 호출 제한이 적용됩니다. 한도 초과 시 429 Too Many Requests 에러가 반환되므로, 클라이언트 측에서 지수 백오프(Exponential Backoff) 등의 딜레이 처리를 권장합니다.

초당 한도

5 req/sec

분당 한도

60 req/min

429 응답에는 Retry-After 헤더(재시도까지 남은 초)가 포함됩니다. 이 값만큼 대기 후 재시도하세요.

429 Too Many Requests

# HTTP/1.1 429 Too Many Requests · Retry-After: 1
{
  "detail": "요청 횟수가 너무 많습니다. 잠시 후 다시 시도해 주세요."
}

POST /api/v1/open/orders/

발주 생성

건설사 현장에 필요한 인력을 직종별 인원 수로 발주합니다. 동일 날짜·직종 재발주 시 요청 인원이 갱신됩니다.

요청 본문(Body)

* 필수 · 용역회사는 **API Key로 자동 식별**되므로 본문에 agency_id 불필요
필드	타입	설명
`order_date` *	string	근무 일자 `YYYY-MM-DD`
`lines` *	array	직종별 요청 라인 `[{worker_type, count, label}]`
`site_name`	string	현장명 (생략 시 자동 명명)
`site_type`	string	현장 업종 `CONSTRUCTION` / `MANUFACTURING` / `LOGISTICS` / `FOOD_SERVICE` / `EVENT`
`external_company`	string	발주처(원청) 표기 — 알림·현장 원청명
`memo`	string	현장 메모(선택)

cURL

curl -X POST https://3works.co.kr/api/v1/open/orders/ \
  -H "X-3Works-API-Key: tw_live_여기에_발급받은_키" \
  -H "Content-Type: application/json" \
  -d '{
    "order_date": "2026-06-20",
    "site_name": "오창 아파트 현장",
    "site_type": "CONSTRUCTION",
    "external_company": "대기업건설(주)",
    "lines": [
      {"worker_type": "CONCRETE", "count": 3, "label": "타설 오야지"},
      {"worker_type": "GENERAL_LABOR", "count": 5, "label": "잡부"}
    ],
    "memo": "B동 3층 골조 작업 / 07:00 집결"
  }'

Python (requests)

import requests

API_KEY = "tw_live_여기에_발급받은_키"
resp = requests.post(
    "https://3works.co.kr/api/v1/open/orders/",
    headers={"X-3Works-API-Key": API_KEY},
    json={
        "order_date": "2026-06-20",
        "site_name": "오창 아파트 현장",
        "site_type": "CONSTRUCTION",
        "lines": [{"worker_type": "GENERAL_LABOR", "count": 5}],
    },
)
print(resp.status_code, resp.json())

JavaScript (fetch)

const res = await fetch("https://3works.co.kr/api/v1/open/orders/", {
  method: "POST",
  headers: {
    "X-3Works-API-Key": "tw_live_여기에_발급받은_키",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order_date: "2026-06-20",
    site_name: "오창 아파트 현장",
    site_type: "CONSTRUCTION",
    lines: [{ worker_type: "GENERAL_LABOR", count: 5 }],
  }),
});
const data = await res.json();

응답 (201 Created)

200/201 Response

{
  "detail": "발주가 정상 접수되었습니다. 용역회사 대시보드·거래처 관리에 등록되었습니다.",
  "agency_name": "영통인력",
  "site_id": 48,
  "site_name": "오창 아파트 현장",
  "order_date": "2026-06-20",
  "created": 2,
  "updated": 0
}

GET /api/v1/open/ping/

연결 확인 (ping)

키가 유효한지, 어느 용역회사로 연결되는지 확인합니다. 발주 직종·업종 코드 목록도 함께 반환합니다.

Response

{
  "ok": true,
  "agency": "영통인력",
  "message": "'영통인력' 연동이 정상 확인되었습니다.",
  "worker_types": [{ "code": "GENERAL_LABOR", "label": "보통인부" }, ...],
  "site_types": [{ "code": "CONSTRUCTION", "label": "건설/토목" }, ...]
}

GET /api/v1/open/attendance/

실시간 출역 현황 조회

우리 용역회사 반장님들이 오늘 어느 현장에 출근 도장을 찍었는지 실시간으로 조회합니다. 건설사 전산 대시보드에 그대로 띄우기 좋은 JSON 배열로 반환됩니다.

쿼리 파라미터

파라미터	타입	설명
`date`	string	조회 일자 `YYYY-MM-DD` (생략 시 오늘)
`site_name`	string	특정 현장명으로 필터(선택)

출근완료 현장 출근 도장 완료

대기중 배정됐고 출근 시각 전

펑크 예정 시각 30분 초과 미출근

cURL

curl "https://3works.co.kr/api/v1/open/attendance/?date=2026-06-20" \
  -H "X-3Works-API-Key: tw_live_여기에_발급받은_키"

Python (requests)

import requests

resp = requests.get(
    "https://3works.co.kr/api/v1/open/attendance/",
    headers={"X-3Works-API-Key": "tw_live_여기에_발급받은_키"},
    params={"date": "2026-06-20"},
)
for row in resp.json()["attendance"]:
    print(row["worker_name"], row["site_name"], row["status_label"])

JavaScript (fetch)

const res = await fetch(
  "https://3works.co.kr/api/v1/open/attendance/?date=2026-06-20",
  { headers: { "X-3Works-API-Key": "tw_live_여기에_발급받은_키" } }
);
const { attendance } = await res.json();

응답 (200 OK)

Response

{
  "agency": "영통인력",
  "date": "2026-06-20",
  "summary": { "total": 8, "checked_in": 6, "waiting": 1, "no_show": 1 },
  "attendance": [
    {
      "worker_name": "배반장",
      "specialty_label": "보통인부",
      "site_name": "오창 아파트 현장",
      "check_in_at": "06:52",
      "status": "CHECKED_IN",
      "status_label": "출근완료"
    }
  ]
}

GET /api/v1/open/orders/

발주 현황 및 정산 조회

우리가 던진 오더가 현재 어떻게 처리되고 있는지(요청·확정 인원, 상태)와 확정 노무비 정산 금액을 현장·직종 단위로 조회합니다. 같은 URL로 POST는 발주, GET은 현황 조회입니다.

쿼리 파라미터

파라미터	타입	설명
`date`	string	발주 일자 `YYYY-MM-DD` (생략 시 오늘)
`site_name`	string	특정 현장명으로 필터(선택)

접수 대기 PENDING

배정 완료 COMPLETED

요청 취소 CANCELED

cURL

curl "https://3works.co.kr/api/v1/open/orders/?date=2026-06-20" \
  -H "X-3Works-API-Key: tw_live_여기에_발급받은_키"

Python (requests)

import requests

resp = requests.get(
    "https://3works.co.kr/api/v1/open/orders/",
    headers={"X-3Works-API-Key": "tw_live_여기에_발급받은_키"},
    params={"date": "2026-06-20"},
)
data = resp.json()
print("오늘 확정 노무비:", data["summary"]["settlement_total"])
for o in data["orders"]:
    print(o["site_name"], o["worker_type_label"], o["assigned_count"], o["settlement_amount"])

JavaScript (fetch)

const res = await fetch(
  "https://3works.co.kr/api/v1/open/orders/?date=2026-06-20",
  { headers: { "X-3Works-API-Key": "tw_live_여기에_발급받은_키" } }
);
const { summary, orders } = await res.json();

응답 (200 OK)

Response

{
  "agency": "영통인력",
  "date": "2026-06-20",
  "summary": { "orders": 2, "requested_total": 7, "assigned_total": 3, "settlement_total": 560000 },
  "orders": [
    {
      "site_name": "오창 아파트 현장",
      "worker_type_label": "보통인부",
      "job_detail": "잡부 5명",
      "requested_count": 5,
      "assigned_count": 2,
      "status": "COMPLETED",
      "status_label": "배정 완료",
      "settlement_amount": 360000
    }
  ]
}

LIVE CONSOLE

⚡ 발주 / 🔎 출근 조회 콘솔

내 인력소 API Key를 넣고 — 발주 테스트로 실제 오더를 꽂거나, 출근 조회로 오늘 반장님들이 어느 현장에 도장을 찍었는지 실시간으로 확인하세요. (발주는 실데이터가 생성되니 테스트 후 대시보드에서 정리하세요.)

내 API Key *

키는 [용역회사 설정 → 우리 회사 Open API 관리]에서 발급합니다. (브라우저에만 사용 — 서버로 별도 저장되지 않음)

근무 일자 *

현장 업종

현장명

요청 직종 / 인원

조회 일자

현장명 (선택 · 비우면 전체)

반장님	직종	현장	출근 시간	상태

발주 일자

현장명 (선택 · 비우면 전체)

현장	직종	요청	확정	상태	확정 노무비

응답·에러 코드

코드	의미	설명
200 / 201	성공	요청이 정상 처리됨
400	Bad Request	필수 필드 누락·형식 오류·잘못된 직종 코드
401	Unauthorized	API Key 누락 또는 유효하지 않음
403	Forbidden	해당 자원에 대한 권한 없음
429	Too Many Requests	요청 제한(rate limit) 초과 — 잠시 후 재시도

에러 응답 예시

{
  "detail": "유효하지 않은 API Key 입니다."
}

지원·연동 문의

전산팀 연동 지원이 필요하신가요?

실시간 Swagger 콘솔에서 모든 엔드포인트를 직접 테스트하거나, 인력요청문의로 전담 연동 지원을 받으세요.

Swagger 콘솔 열기 연동 문의하기

건설사 전산 시스템을 우리 인력 장부에 바로 연결하세요.

개요

퀵스타트

인증 (API Key)

⏳ 과부하 방지 및 트래픽 제한

발주 생성

요청 본문(Body)

응답 (201 Created)

연결 확인 (ping)

실시간 출역 현황 조회

쿼리 파라미터

응답 (200 OK)

발주 현황 및 정산 조회

쿼리 파라미터

응답 (200 OK)

⚡ 발주 / 🔎 출근 조회 콘솔

응답·에러 코드

지원·연동 문의

전산팀 연동 지원이 필요하신가요?

건설사 전산 시스템을
우리 인력 장부에 바로 연결하세요.