개발자 문서
오너웍스 오픈 API
쓰던 쇼핑몰·자체 프로그램이 오너웍스의 주문·판매·매입·품목·재고·거래처·작업·장부 요약을 읽고, 주문·거래처·작업을 만들 수 있어요. 일이 생기면 웹훅으로 바로 알려 드려요. 무료예요.
기계가 읽는 문서: OpenAPI JSON
시작하기
- 설정 > 기능 블록에서 "오픈 API·웹훅"을 켜요.
- 설정 > API 키·웹훅에서 키를 만들어요. 키는 만들 때 한 번만 보여요.
- 요청마다
Authorization: Bearer ilt_live_…머리글을 붙여요.
금액은 원 단위 정수, 수량은 문자열(소수 3자리까지)이에요. 목록은 { items, nextCursor } 모양이고 ?cursor=로 다음 쪽을 받아요. 키 하나는 한 사업장 자료만 볼 수 있어요.
범위
키마다 볼 수 있는 범위를 골라요. "읽기 전용" 키는 만들기를 할 수 없어요. 만들기는 키를 만든 사람의 권한 안에서만 돼요.
orders주문 · 만들기: orders:writesales판매(청구)purchases매입items품목·재고partners거래처 · 만들기: partners:writejobs작업·일정 · 만들기: jobs:writeledger장부 요약
주소 목록
/orders주문 목록범위 orders · 조건: limit, cursor, updatedSince, status
/orders주문 만들기범위 orders:write
/orders/{id}주문 하나 (품목 줄 포함)범위 orders · 조건: id
/sales판매(청구) 목록범위 sales · 조건: limit, cursor, from, to
/purchases매입 목록범위 purchases · 조건: limit, cursor, updatedSince
/items품목·재고 목록범위 items · 조건: limit, cursor, updatedSince, sku
/items/{id}품목 하나범위 items · 조건: id
/partners거래처 목록범위 partners · 조건: limit, cursor, updatedSince, kind, businessNumber
/partners거래처 만들기범위 partners:write
/partners/{id}거래처 하나범위 partners · 조건: id
/jobs작업·일정 목록범위 jobs · 조건: limit, cursor, updatedSince, from, to
/jobs작업 만들기범위 jobs:write
/jobs/{id}작업 하나범위 jobs · 조건: id
/ledger/summary장부 요약 (기본: 이번 달)범위 ledger · 조건: from, to
예제
어제 이후 바뀐 주문 가져오기
curl -H "Authorization: Bearer $ILTEO_KEY" \
"https://<오너웍스 주소>/api/public/v1/orders?updatedSince=2026-11-14T00:00:00Z&limit=50"주문 만들기 (거래처가 없으면 이름으로 새로 만들어요)
curl -X POST -H "Authorization: Bearer $ILTEO_KEY" \
-H "Content-Type: application/json" \
-d '{"partnerName":"행복마트","date":"2026-11-15",
"lines":[{"name":"사과 5kg","qty":"2","unitPrice":25000}]}' \
"https://<오너웍스 주소>/api/public/v1/orders"재고 확인 (품목 코드로)
curl -H "Authorization: Bearer $ILTEO_KEY" "https://<오너웍스 주소>/api/public/v1/items?sku=APPLE-5KG"작업(방문 일정) 만들기
curl -X POST -H "Authorization: Bearer $ILTEO_KEY" -H "Content-Type: application/json" \
-d '{"title":"에어컨 청소","customerName":"김고객","customerPhone":"010-1234-5678",
"address":"서울 마포구 월드컵로 1","scheduledDate":"2026-11-20","startTime":"10:00"}' \
"https://<오너웍스 주소>/api/public/v1/jobs"웹훅
설정 > API 키·웹훅에서 받는 주소(https)와 받을 일을 골라요. 일이 생기면 JSON 으로 POST 해요. 내용은 id 위주라, 자세한 내용은 그 id 로 다시 조회해 주세요.
order.created주문이 들어왔어요sale.created판매(청구·매장 판매)가 생겼어요purchase.created매입이 생겼어요stock.changed재고가 바뀌었어요job.created작업이 만들어졌어요job.updated작업이 바뀌었어요partner.created거래처가 추가됐어요partner.updated거래처가 바뀌었어요
POST https://내-서버/hook
x-ilteo-signature: t=1763190000,v1=5f2c…
x-ilteo-event: order.created
{"id":"<이벤트 id>","type":"order.created","createdAt":"2026-11-15T03:00:00Z",
"data":{"id":"<주문 id>"},"deliveryId":"…","attempt":1}서명 확인 (Node.js)
import crypto from 'node:crypto';
function verify(secret, rawBody, header) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5분 넘은 건 거절
const mac = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(mac, 'hex'), Buffer.from(v1, 'hex'));
}2xx 로 답하면 받은 걸로 봐요. 그 밖의 답이나 연결 실패는 1분·5분·15분·1시간·3시간·6시간·12시간 간격으로 다시 보내고, 그래도 안 되면 실패로 남겨요. 설정 화면의 기록에서 "다시 보내기"를 누를 수 있어요. 같은 이벤트가 두 번 갈 수 있으니 id 로 중복을 걸러 주세요.
오류·한도
오류는 { "error": { "code", "message" } } 모양이고 message 는 바로 보여 줄 수 있는 한국어 문장이에요.
- 401 키가 없거나 맞지 않거나 지워졌어요.
- 403 키에 그 범위가 없거나, 블록이 꺼졌거나, 키를 만든 사람이 사업장에서 빠졌어요.
- 429 1분 한도(키마다 30~300번)를 넘었어요.
Retry-After초 뒤에 다시 해 주세요. 남은 횟수는X-RateLimit-Remaining. - 400 보낸 내용이 맞지 않아요(화면에서 저장할 때와 같은 검사).