2026-09-11-cin7-core-api-readonly-assessment

Ingest Notes

David가 매니저로부터 공유받은 TAB Project 공유드라이브 Cin7 폴더에서 수집. 작성자는 이 세션이 아닌 별도 작업자(매니저 또는 동료로 추정, macOS 기기·Python 로컬 스크립트·Keychain 사용)로 보인다. 문서 자체가 “비밀정보 요청 없음, 실제 계정 접속 없음, API 호출 없음, 쓰기 동작 없음”을 전제로 조사했다고 명시한 §0과, 실제로는 §6~§7에서 연결·읽기 시험까지 수행했다는 서술이 섞여 있다 — 원문 그대로 보존.

Original Content

Turbo Air DEAR/Cin7 Core API 읽기 전용 사전 조사

• 기준일: 2026-09-11 (Australia/Sydney)
• 상태: 공식 공개자료 조사 완료 / 실제 계정·API 연결 미실시
• 사용자 제공 근거: 현재 로그인 주소 https://inventory.dearsystems.com/
• 금지 범위 준수: 비밀정보 요청 없음, 실제 계정 접속 없음, API 호출 없음, 쓰기 동작 없음

1. 제품 식별 결론

사용자가 제공한 로그인 주소는 Cin7 공식 도움말이 Cin7 Core 웹 애플리케이션 주소로 명시하는 주소와 일치한다. 따라서 현재 제품은 Cin7 Core(기존 DEAR 계열) 로 식별하는 것이 가장 타당하다. 공식 도움말의 로그인 링크도 같은 inventory.dearsystems.com 도메인을 계속 사용한다.

• 공식 근거: Connecting to the Cin7 Core API
• 공식 근거: Cin7 API 도움말 섹션
• 미검증: Turbo Air 계정 화면에 실제 표시되는 제품명, 조직명, 지역, 구독 플랜

2. API 기본 사양

항목	공식 공개자료에서 확인된 내용	현재 판정
권장 버전	API V2. 공식 문서는 V1 사용자에게 V2 이전을 권장하며 V2가 최근 시스템 변경과 고급 기능을 더 넓게 지원한다고 설명	V2 우선 설계
V1 기본 URL	https://inventory.dearsystems.com/ExternalApi/	확인됨
V2 상세 문서	https://dearinventory.docs.apiary.io	공식 링크 확인, 이번 조사 환경에서는 페이지 로드 타임아웃
인증	HTTP 헤더 api-auth-accountid, api-auth-applicationkey	확인됨
자격증명 성격	Account ID와 Application Key는 로그인/비밀번호와 동등한 비밀로 취급	확인됨
회사·앱 범위	회사별 Account ID가 다르며 한 계정에 여러 API Application 생성 가능	확인됨
호출 제한	공식 상태코드 문서상 60 calls/min 초과 시 HTTP 503. 연결 문서상 제한은 API Application별 적용	기본 API 기준 확인됨
페이지네이션	공개 도움말은 Customers, Suppliers, Products, ProductFamilies, ProductAvailability, Sales를 열거하며 기본 100, 최대 1000건/페이지로 설명	확인됨. V2 개별 차이는 연결 전 재확인 필요
API 이용 조건	현재 가격표와 도움말은 Cin7 Core API를 추가 옵션/add-on으로 표시	Turbo Air 구독 포함 여부 미검증
Flex API	지원팀 문의로 선택 가능하며 고처리량용 추가 옵션으로 표시	가격·한도 미공개/미검증
웹훅	공식 FAQ는 판매·구매 이벤트 웹훅을 설명하고 Automation 모듈을 요구	기능 확인, 구독 여부 미검증
샌드박스	전용 sandbox 조직/환경에 대한 공식 공개 근거를 이번 조사에서 찾지 못함. Trial 계정도 API 접근 가능하다는 설명은 있음	전용 샌드박스는 확인 불가. Trial을 운영 계정과 분리된 테스트 환경으로 쓸 수 있는지는 지원팀 확인 필요

주요 공식 근거: API V2 introduction, API Status Codes, Pagination, Available add-ons and integrations, Cin7 pricing

3. 권한 모델

• Cin7 Core 사용자 유형은 Account owner, Co-owner, Adviser, Regular user로 구분된다.
• 사용자 역할과 권한은 웹 UI 기능 접근을 통제한다. API 설정 화면 접근에는 별도의 Cin7 Core API - Setup 권한이 설명되어 있다.
• 공식 연결 문서는 API Application 자격증명을 별도로 발급한다고 설명하지만, 공개자료만으로 API 키 자체에 읽기 전용 scope 또는 엔드포인트별 세분 권한이 있는지는 확인되지 않았다.
• 따라서 “초기 읽기 전용”은 키 자체가 강제하는 권한이라고 가정하지 않고, 우리 통합 서비스에서 GET allowlist와 쓰기 차단을 적용하는 구조로 설계해야 한다. 이는 설계 제안이며 실제 계정 연결 전 검증 대상이다.

공식 근거: Introduction to users, User permissions explained

4. 업무 영역별 API 제어 가능 범위

판정 의미:

• 가능: 공식 공개 문서가 관련 API 읽기 또는 쓰기 동작을 명시
• 제한적: 일부 하위 기능만 확인되었거나 구독·상태 전이·권한·UI 설정에 의존
• UI 전용/확인 불가: 공개 API 근거가 없거나 UI 권한 설명만 확인됨

업무 영역	읽기	쓰기/제어	판정 및 제한
상품·서비스	Products, ProductFamilies, ProductAvailability, categories, brands, suppliers, attachments 관련 문서 존재	Products/ProductFamilies POST·PUT가 공식 목록에 있음	가능/제한적. 삭제, 동적 가격 규칙, 모든 첨부 동작은 V2 상세 확인 필요
재고 가용량	ProductAvailability 조회	재고 수량 직접 변경은 공개 V1 목록에 없음	읽기 가능, 조정 제한적. Stock Adjustment/Stocktake의 V2 지원 범위는 Apiary 문서 재확인 필요
창고·위치	Locations 조회, V2 변경 기록에 StockTransfer/StockTransferOrder 언급	재고 이동 관련 V2 기능 존재 정황	제한적. 생성·승인·완료 상태별 메서드는 상세 문서 미검증
구매	PurchaseList/Purchase GET, V2는 Advanced Purchase 지원	Purchase POST·DELETE, 구매 credit note 관련 V2 문서 링크 존재	가능/고위험. 승인·입고·invoice·payment·credit note 상태 전이는 개별 게이트 필요
판매·견적·주문	Sale/SaleList GET	Sale POST, payment, pick, pack, ship, credit note 관련 동작 확인	가능/고위험. 주문 상태와 허용 전이는 판매 상태에 의존하며 삭제 대신 Void/Undo 개념 포함
출고·배송	fulfilment, pick, pack, ship 조회·상세 문서 링크	pick/pack/ship 갱신 및 자동 pick 방식 설명	가능/고위험. 실제 출고 확정은 운영 영향이 커 별도 승인 필요
고객	Customers GET	Customers POST·PUT	가능. 신용한도·credit hold 같은 UI 권한 기능이 모두 API로 노출되는지는 확인 불가
공급자	Suppliers GET	공개 V1 목록에는 쓰기 없음	읽기 가능, 쓰기 확인 불가. V2 상세 문서 확인 필요
가격	제품 가격 정보, PriceTier 조회 언급	제품 갱신을 통한 일부 가격 변경 가능성	제한적. 가격 tier 이름, 동적 계산, customer-specific pricing의 API 완전성은 확인 불가; CSV/UI 경로 존재
회계 기준정보	ChartOfAccounts, TaxationRules, PaymentTerms 조회	기준정보 쓰기는 공개 목록에서 확인 안 됨	읽기 가능, 쓰기 확인 불가
회계 연동	Xero/QuickBooks Online 네이티브 통합이 공식 가격표에 표시	동기화 설정·재처리·posting을 일반 API로 전부 통제한다는 근거 없음	제한적/UI 의존. API 거래 데이터와 회계 연동 운영은 별개
결제	SalePayments GET/POST/PUT/DELETE가 공식 목록에 있음	결제 생성·수정·삭제 가능	가능/최고위험. 실제 결제수단 승인·자금 이동과 장부상 payment 기록을 구분해야 함
반품	반품은 credit note로 처리된다는 공식 FAQ	Sale/Purchase credit note API 링크 존재	제한적/고위험. RMA는 별도 add-on이며 RMA 포털 전체 API 통제는 확인 불가
BOM·제조	Bill of Materials 문서와 V2의 확장 기능 존재	제조·assembly/MES 전체 제어는 공개 목록만으로 불충분	제한적/확인 불가. Advanced Manufacturing은 별도 add-on일 수 있음
사용자·역할·권한	UI 도움말로 사용자/역할 구조 확인	사용자·역할 관리를 일반 Core API로 수행한다는 공개 근거 없음	UI 전용 또는 확인 불가
구독·결제 플랜	UI에서 My Subscription 확인	플랜 변경·add-on 구매는 권한 있는 UI 동작	UI 전용으로 취급. API 자동화 대상에서 제외
가져오기·내보내기	여러 모듈에서 CSV export 가능	CSV import 가능	대체 경로. API 공백을 보완할 수 있으나 UI 권한과 형식 검증 필요
자동화·알림·웹훅	이벤트 알림·실행 로그·외부 알림 제공	외부 URL 호출 및 API webhook 구독 가능	제한적. Automation add-on 필요, 모든 알림 유형이 외부 전송을 지원하지 않음
보고서·대시보드	예약 보고 등 Automation 기능 존재	모든 보고서/대시보드 설정을 API로 제어한다는 근거 없음	UI 전용 또는 확인 불가
네이티브 통합 설정	다수의 회계·전자상거래·배송 통합 존재	연결 설치·자격증명·매핑을 일반 API로 통제한다는 근거 없음	UI 전용 또는 확인 불가

관련 공식 근거: List of Endpoints, User Questions: Cin7 Core API, Notifications

5. 웹훅과 이벤트

공식 FAQ에서 확인되는 판매 이벤트 예시는 QuoteAuthorized, OrderAuthorized, Voided, Backordered, ShipmentAuthorized, InvoiceAuthorized, PickAuthorized, PackAuthorized, CreditNoteAuthorized, Undo, PartialPaymentReceived, FullPaymentReceived, ShipmentTrackingNumberChanged다. 이벤트 수신 후 식별자로 GET 조회하는 패턴을 권장한다.

주의사항:

• 웹훅은 Automation 모듈 구독에 의존한다.
• 모든 알림 유형이 External delivery를 지원하지 않는다.
• External notification은 No Auth, Basic Auth, Bearer Auth와 사용자 정의 헤더를 지원한다.
• 운영 설계에서는 서명 또는 공유 비밀 검증, replay 방지, 멱등 처리, 실패 보관과 재조정이 필요하다. 이 항목은 우리 측 설계 제안이다.

6. 현재 상태 판정

상태	결과
제품 URL 식별	완료 — 사용자 제공 URL과 공식 Cin7 Core 주소 일치
공식 공개문서 조사	완료 — 현재 접근 가능한 Cin7/Cin7 Core 자료 기준
V2 전체 엔드포인트 전수 검증	미검증 — 공식 Apiary 상세 페이지가 조사 환경에서 타임아웃
Turbo Air 플랜/API add-on	30일 trial 활성화 확인 — 유료 전환 조건·만료 후 상태는 미검증
Turbo Air 사용자 권한/API Setup 권한	미검증
API Application 생성	완료 — Turbo Air Core API - Read Only Pilot, active 상태 화면 확인
자격증명 보관	완료 — macOS 로그인 키체인 내 두 application password 항목의 존재 확인, 값은 기록하지 않음
API 연결 성공	완료 — 2026-09-11 GET /ExternalApi/Me 1회, HTTP 200
읽기 성공	최소 범위 완료 — JSON object와 최상위 키 구조만 확인, 실제 값은 출력·기록하지 않음
샌드박스 테스트	미실시
쓰기 검증	미실시
운영 배포	미실시
100% 기능 커버리지	미달성·현재 보장 불가

최소 읽기 시험 근거

• 로컬 검사기: work/cin7_readonly_probe.py
• 안전장치: GET 메서드 고정, Me 단일 allowlist, Keychain 조회, 응답 값 미출력
• 로컬 단위 테스트: 3개 통과
• 실제 응답: HTTP 200, application/json, object
• 확인한 최상위 키 이름: Company, Currency, LockDate, OpeningBalanceDate, TimeZone
• 회사명·통화·날짜·시간대의 실제 값은 출력하거나 파일에 저장하지 않음

상품·재고·창고 최소 읽기 시험

• 수행일: 2026-09-11
• 로컬 검사기: work/cin7_schema_probe.py
• 안전장치: GET 고정, 3개 엔드포인트 allowlist, 목록 조회 Page 1/Limit 1, 응답 값 제거
• 누적 로컬 단위 테스트: 6개 통과
• 실행 기록: 첫 실행의 출력이 전달되지 않아 동일 검사를 1회 재실행했다. 따라서 각 엔드포인트는 최대 2회의 GET 요청이 발생했을 수 있으며, 확인 가능한 결과는 재실행 응답이다.

영역	요청 범위	결과	확인된 구조 요약
상품	Products, Page 1/Limit 1	HTTP 200 JSON object	식별자, SKU, 상품명, 설명, 분류·브랜드, 가격 tier, 원가·계정·세금 규칙, 단위·치수, 재주문, 판매 가능·상태 등 필드 존재
재고	ProductAvailability, Page 1/Limit 1	HTTP 200 JSON object	상품·SKU·barcode, location/bin/batch/expiry, on-hand, available, allocated, on-order, in-transit, next-delivery 등 필드 존재
창고	Locations	HTTP 200 JSON array	위치 ID·이름, 기본/폐기 여부, bins, pick zones, reorder 허용 등 필드 존재

실제 상품명, SKU, barcode, 가격, 원가, 계정, 재고 수량, 창고명과 전체 건수는 출력하거나 저장하지 않았다. 이 결과는 세 엔드포인트의 응답 구조 확인이며 데이터 값의 정합성이나 전체 페이지 수집 완료를 의미하지 않는다.

고객·공급자·구매·판매·회계 기준정보 최소 읽기 시험

• 수행일: 2026-09-11
• 안전장치: GET 고정, allowlist, 거래 목록 Page 1/Limit 1, 응답 값 제거
• 누적 로컬 단위 테스트: 8개 통과

영역	요청 범위	결과	확인된 구조 요약
고객	Customers, Page 1/Limit 1	HTTP 200 JSON object	고객 식별·상태, 주소·연락처, 통화·가격 tier·할인, 결제조건, 세금, 매출계정, 신용한도·credit hold 등 필드 존재
공급자	Suppliers, Page 1/Limit 1	HTTP 200 JSON object	공급자 식별·상태, 주소·연락처, 통화·할인·결제조건, 세금, 매입채무 계정 등 필드 존재
구매	PurchaseList, Page 1/Limit 1	HTTP 200 JSON object	주문·입고·invoice·credit note·payment 상태, 주문/납기/청구일, 금액·통화, 공급자 식별 필드 존재
판매	SaleList, Page 1/Limit 1	HTTP 200 JSON object	quote·order·pick·pack·ship·invoice·credit note·payment 상태, 날짜·금액·통화, 고객 식별 필드 존재
회계과목	ChartOfAccounts	HTTP 200 JSON array	code·type·class·status, system account, payment 허용 등 필드 존재
결제조건	PaymentTerms	HTTP 200 JSON array	ID·이름·방식·기간·활성·기본 여부 필드 존재
세금규칙	TaxationRules	HTTP 200 JSON array	ID·이름·type·세율, 매입/매출 적용, tax-inclusive·활성·account 필드 존재

실제 고객·공급자 정보, 주소·연락처·세금번호, 주문번호·날짜·금액, 계정명·코드, 세율과 전체 건수는 출력하거나 저장하지 않았다. 현재까지 Me와 총 10개 업무/기준정보 엔드포인트에서 최소 읽기 성공을 확인했다.

7. 다음 단계의 최소 입력 한 가지

비밀값은 가린 상태로, Cin7 Core의 My Subscription 화면에서 현재 플랜명과 API add-on 활성 여부가 보이는 스크린샷 한 장이 필요하다.

Account ID, Application Key, 이메일, 결제정보 등은 반드시 가려야 한다. 이 한 장으로 구독 조건과 API 설정 접근 가능 여부를 확인한 뒤, 실제 키를 채팅에 노출하지 않는 macOS Keychain 기반 읽기 전용 연결 계획을 작성할 수 있다.