문서 보고서와 데이터

API

자신의 도구에서 스터디, 결과, 장비, 카탈로그를 읽거나 운영 데이터를 밀어 넣기, 통합마다 키 하나로.

1 분 소요7 섹션

API는 견적 도구가 누군가 보고서에서 숫자를 베끼지 않고도 스터디의 처리량과 투자 회수를 원할 때, 또는 차량군 관리자가 스프레드시트 없이 일별 운영 데이터를 보내고 싶을 때를 위한 것입니다. Team과 Enterprise에서, auddomate.com과 자체 호스팅 설치본 모두에서 이용할 수 있습니다. 반환하는 모든 것은 앱에서 보는 것과 같습니다: 같은 차량군, 같은 가정, 같은 산수.

키

소유자는 설정 → API 키에서 키를 만듭니다. 사용할 시스템의 이름을 붙이고, 할 수 있는 것을 체크하고, 나타날 때 키를 복사하세요 — 한 번만 보여주고 해시로 저장됩니다. 키는 하나 이상의 범위를 갖습니다:

read: 스터디, 결과, 장비, 카탈로그. 모든 키가 갖습니다.
telemetry: 스터디에 텔레메트리 행 쓰기.
audit: 감사 로그 읽기.

같은 페이지에서 키를 회수하세요. 여전히 그것을 쓰는 것은 그 순간부터 401을 받습니다. 키 생성과 회수 자체도 감사 로그에 기록됩니다. 조직당 활성 키 최대 스무 개.

호출

모든 요청은 키를 베어러 토큰으로 지닙니다. 기본 주소는 Auddomate 주소 뒤에 /api/v1을 붙인 것입니다.

bash

curl -H "Authorization: Bearer aud_…" https://auddomate.com/api/v1/me

여러분과 서버 사이의 무언가가 Authorization 헤더를 떼어내면 대신 X-Api-Key: aud_…로 보내세요. 응답은 안정된 형태의 JSON입니다:

json

{ "ok": true, "data": …, "meta": { "page": 1, "per_page": 50, "total": 132, "pages": 3 } }
{ "ok": false, "error": "not_found", "message": "No study ST-9999 in this organisation." }

목록은 ?page=와 ?per_page=(최대 200)로 페이지를 나눕니다. 시각은 서버 현지 시각으로 YYYY-MM-DD HH:MM:SS; 길이는 밀리미터, 거리는 미터, 비율은 시간당 또는 일당, 앱과 정확히 같습니다. 각 키는 분당 300 요청을 할 수 있고, 그 이상은 Retry-After 헤더와 함께 429를 받습니다.

엔드포인트

GET /api/v1/me: 조직, 키의 이름과 범위, 에디션, 속도 제한. 키가 작동하는지 확인하는 데 쓰세요.
GET /api/v1/studies: 모든 스터디: 참조, 이름, 현장, 고객, 상태, 현재 시나리오의 처리량 판정과 여유, 차량군의 대수. ?status=, ?client= 또는 ?updated_since=2026-09-01로 거릅니다.
GET /api/v1/studies/{ref}: 참조(ST-1001)나 id로 스터디 하나 전체: 도면(파일, 축척, 범위, 랙·통로·도크·장애물 수), 그리고 각 시나리오의 차량군 줄, 가정, 줄별 처리량 결과, 가장 까다로운 장비에 대한 통로 검사, 그 장비가 무엇이었는지.
GET /api/v1/studies/{ref}/telemetry: 스터디의 운영 데이터, 장비당 하루에 한 행.
GET /api/v1/studies/{ref}/pdf: 서버에서 만든 PDF 파일로서의 보고서. ?lang=과 ?units=imperial로 언어와 단위를 고릅니다. 저장된 버전은 /versions/{n}/pdf.
GET /api/v1/studies/{ref}/versions: 스터디의 저장된 버전, 최신순; /versions/{n}은 하나를 스터디 자체와 같은 형태로 전부 반환하고, ?diff=1은 그 뒤 바뀐 것을 더합니다.
POST /api/v1/studies/{ref}/telemetry: 운영 데이터 쓰기. telemetry 범위가 필요합니다. {"rows": [...]}를 최대 5 000행까지 보내세요; 각 행은 machine_id나 machine(정확한 이름)으로 장비를 지정하고, day와 moves, run_minutes, idle_minutes, distance_km, faults 중 아무것이나 담습니다. 이미 있는 장비와 날짜의 행은 대체됩니다. 응답은 몇 행이 기록됐는지 알리고 건너뛴 처음 쉰 행과 이유를 나열합니다.
GET /api/v1/machines: 장비 라이브러리, 각 프로필의 수치와 카탈로그 모델의 경우 출처 사양서. 하나는 /machines/{id}.
GET /api/v1/catalogue: 실제 제조사와 모델의 카탈로그와 출처 사양서. ?vendor=나 ?class=로 거릅니다.
GET /api/v1/audit: 감사 로그, 최신순. audit 범위가 필요합니다. ?group=, ?from=, ?to=, ?q=로 거릅니다.

스터디의 형태

json

{
  "ref": "ST-1002", "name": "Cold store aisle audit", "status": "review",
  "plan": { "file": "cold-store.dxf", "scale": { "mm_per_unit": 1, "source": "dxf" },
            "extent_mm": { "width": 61000, "height": 45000 },
            "shapes": { "rack": 6, "aisle": 5, "dock": 1, "block": 3 } },
  "scenarios": [ {
    "name": "Base", "current": true,
    "fleet": [ { "machine": "VNA turret, 1.0 t", "class": "vna", "qty": 3, "shifts": 2 } ],
    "assumptions": { "moves_required": 2110, "hours_per_shift": 8, "days_per_year": 300,
                     "distance_m": 14, "distance_source": "plan", "handling_s": 55 },
    "throughput": { "verdict": "meets", "moves_per_day": 3024.6, "required_per_day": 2110,
                    "headroom_per_day": 914.6, "utilisation_pct": 69.8, "lines": [ … ] },
    "aisles": { "verdict": "fail", "aisle_min_mm": 2100, "narrowest_mm": 1800, "aisles": 5, "below": 5 },
    "checked_against": { "machine": "Pallet truck, pedestrian 1.6 t", "aisle_min_mm": 2100 }
  } ]
}

throughput.verdict는 meets, short, nofleet, nodistance, notarget 중 하나; aisles.verdict는 pass, fail, noplan, noscale, noaisles, none 중 하나입니다. distance_source는 시뮬레이션 페이지처럼 이동 거리가 입력됐는지 도면에서 도출됐는지 알려줍니다.

운영 데이터 보내기

bash

curl -X POST https://auddomate.com/api/v1/studies/ST-1002/telemetry \
  -H "Authorization: Bearer aud_…" -H "Content-Type: application/json" \
  -d '{"rows": [
        {"machine": "VNA turret, 1.0 t", "day": "2026-09-01", "moves": 412, "run_minutes": 480, "idle_minutes": 60, "distance_km": 18.4, "faults": 1},
        {"machine_id": 327, "day": "2026-09-02", "moves": 390}
      ]}'

json

{ "ok": true, "data": { "written": 2, "skipped": 0, "errors": [] } }

오류

401 unauthorised: 키가 없거나 우리가 모르는 키.
401 revoked: 키가 회수되었습니다. 메시지가 언제인지 알려줍니다.
403 plan: 조직이 무료 또는 Studio 플랜입니다.
403 scope: 키에 엔드포인트가 요구하는 범위가 없습니다.
404 not_found: 그런 스터디, 장비 또는 엔드포인트가 없습니다.
400 json / empty: 본문이 JSON 객체가 아니거나 행이 없습니다.
413 too_many: 텔레메트리 요청 하나에 5 000행 초과.
429 rate_limited: 1분에 300 요청 초과. Retry-After초 기다리세요.

버전 관리

경로가 버전을 지닙니다. 필드는 시간이 지나며 v1에 추가되지만 이름이 바뀌거나 제거되지 않습니다; 클라이언트를 깨뜨릴 것은 v2가 되고 v1은 최소 1년간 나란히 유지됩니다. 변경은 다른 모든 것처럼 변경 이력에 나열됩니다.

API는 키가 속한 조직만 읽고 쓰며 그 밖에는 아무것도 하지 않습니다 — 어떤 키로도 다른 조직의 스터디에 닿을 방법은 없습니다. 키를 비밀번호처럼 다루세요: 시스템당 하나, 그 시스템이 퇴역하면 회수.