manuERDchahbot · ERP API 제공 요청안

manuERDchahbot · 제조업 발주 지원 서비스 ERP 연동 협의 초안

manuERDchahbot · ERP API 제공 요청안

협의 초안 · 2026-10-14
대상: ERP/API 제공 업체와 실제 사용 업체의 실무 담당자
목적: 발주 수량과 근거 설명, 챗봇 질의, 고객사별 업무 방식, 사용량 관리를 구현하기 위한 데이터 계약 협의

이 문서는 기존 ERP API의 확정 명세가 아닙니다. 최초 「외주 AI 개발 요청 사항」 1쪽에 적힌 데이터 목록과 기능 요구를 바탕으로 제공 가능 여부·실제 필드·의미·샘플 응답을 요청하는 문서입니다. 경로와 JSON 예시는 협의용 형식입니다. ERP 운영 DB 변경이나 쓰기 권한은 이번 요청 범위가 아닙니다.

1. 먼저 회신받을 자료

  1. 현재 사용 중인 API 문서(OpenAPI/Swagger가 있으면 원본), 접근 가능한 시험 환경, 인증·IP 허용 방식, 기술 담당자.
  2. 아래 데이터별 제공 가능 여부와 실제 API 경로, 필드 설명, 가명 처리한 샘플 응답·오류 응답. 사용하지 않는 기능은 업무 미사용, 존재하지만 공개 불가하면 제공 불가, 아직 조사 중이면 미확인으로 구분해 주세요.
  3. 업체·사업장·창고·품목을 식별하는 ID와 데이터 갱신 주기, 기준 시간대, 과거 데이터 제공 범위.
  4. 발주 권장 수량의 현행 업무 공식·예외·승인자. 공식이 없다면 실제 실무 판단 사례 10~20건과 계산을 보류해야 하는 사례.
  5. 실사용 업체 DB를 기준으로 담당자가 확인할 수 있는 시험 범위와 개인정보·거래정보 반출 제한.

제공 가능 데이터 확인표

매출은 최초 요청서에 공통 데이터로 제시되어 우선 제공을 요청합니다. 다만 매출은 확정 수요가 아니라 거래 실적일 수 있으므로 수주·생산 수요의 대체물로 자동 사용하지 않습니다.

데이터 최초 요청서에 적힌 필드 추가로 확인할 핵심 내용 없거나 미사용일 때
매출 내역 일자·품목·수량 거래/행 ID, 취소·반품, 단위, 사업장, 집계 기준 공통 제공 요청. 일부만 있으면 누락 범위 명시
수주 내역 일자·품목·수량·출고예정일 잔여 수량, 상태, 변경·취소, 고객 납기, 중복 출고 미출고 수요 계산 보류. 매출 추이는 별도 설명
발주 내역 일자·품목·입고예정일 수량 필드 존재 여부, 발주 상태, 잔여/부분입고, 공급처 발주서 미사용으로 설정 가능. 공급 확정량은 임의 추정 금지
매입 내역 일자·품목·수량 발주·입고 연결 ID, 반품·취소, 실제 입고 여부 공급 실적 검증 경로가 줄어듦
작업지시서 일자·품목·수량·생산예정일 상태, 생산 대상/투입 대상, 수주 연결 ID 생산 예정 수요 계산 제외
생산전표 일자·품목·수량 실적/불량/취소 구분, 작업지시 연결 ID 생산 실적 대조 제외
BOM 품목·소요량 모품목·자품목 ID, 단위, 수율, 버전·유효기간, 대체품 원자재 소요량 계산 보류
품목정보 품목·명칭·리드타임 품목 ID·기본 단위, 활성 상태, 최소발주량·배수 품목 매칭 또는 납기 판단 보류
창고별 재고 창고별 재고현황 창고 ID, 현재고·예약·검사중·불량·가용 수량 구분 창고별 계산 보류
전체 재고 재고현황 창고 합계와 일치 여부, 기준 시각 재고 기반 수량 계산 보류

각 행에 대해 제공됨 / 업무 미사용 / 제공 불가 / 일시 장애 / 미확인, API 경로, 담당자, 갱신 주기, 샘플 유무를 채워 회신해 주세요. 성공 응답의 빈 목록은 해당 조건의 거래가 0건임을 뜻하는지도 확인이 필요합니다. 누락·장애·미사용을 모두 0으로 보내면 잘못된 발주 수량이 생길 수 있습니다.

2. 공통 API 계약 요청

항목 요청·확인 사항
경계 ERP 측의 읽기 전용 HTTPS API 우선. 직접 MS-SQL 접속이 필요한 경우 읽기 전용 뷰·계정·접속망을 별도로 협의
인증·권한 서비스 계정 또는 OAuth 방식, 토큰 수명/갱신, 고객사·사업장 범위, IP 허용 목록, 키 교체 절차. 비밀 값은 문서·샘플에 포함하지 않음
버전 /v1 같은 버전 규칙, 하위 호환 기간, 변경 사전 통지, 필드 폐기 절차
범위 조회 기간·품목·사업장·창고·상태 필터, 필드 선택 가능 여부. 전체 테이블 다운로드를 기본 경로로 요구하지 않음
페이지 이동 안정적인 커서 또는 페이지 방식, 최대 페이지 크기, 정렬 키, 총건수 제공 여부, 중간 갱신 시 중복/누락 방지
증분 동기화 updated_since 또는 변경 커서, 취소·삭제 표식, 재처리 가능 기간과 순서. 지원하지 않으면 스냅샷·ETag/Last-Modified 가능 여부
신선도 응답의 as_of(업무 기준 시각)와 extracted_at(API 추출 시각)을 구분. ISO 8601 시간대 표기. 지연·장애 시 마지막 성공 시각 제공
식별자 고객사/사업장/창고/품목 및 거래·행 ID의 안정성, 코드 변경·합병·폐기 처리, API 간 연결 키
수량·단위 정수/소수, 기본 단위와 환산, 음수·반품·취소 표시, 소수점/반올림 규칙. 금액은 필요한 경우 통화·부가세 기준 별도
오류 HTTP 상태, 기계 판독 코드, 재시도 가능 여부, request_id, 제한 초과 시 Retry-After, 부분 실패 범위
호출 정책 초당/분당 한도, 동시 요청, 응답 최대 크기, 압축, 타임아웃, 예상 건수, 시험 환경 제한
감사·보안 최소 권한, 전송 암호화, 접근 로그, 테스트용 가명 데이터, 개인정보·거래정보 보존·반출 범위

권장 공통 응답 메타데이터의 예시입니다. 실제 필드명은 제공 업체 표준에 맞춰 조정할 수 있습니다.

{
  "data": [],
  "meta": {
    "source_system": "ERP",
    "tenant_id": "sample-tenant",
    "as_of": "2026-10-14T09:00:00+09:00",
    "extracted_at": "2026-10-14T09:00:05+09:00",
    "next_cursor": null,
    "request_id": "sample-request-id",
    "completeness": "complete"
  }
}

completeness는 complete / partial / unavailable / unknown 같은 구분이 가능한지 묻는 제안입니다. null 값의 이유(미입력·해당 없음·권한 제한·장애)도 가능하면 별도 코드로 알려 주세요.

3. 데이터별 상세 질문

매출과 수주

발주·매입·입고

생산·BOM·품목

재고

4. 업체별 기능 설정과 데이터 공백 처리

서비스는 업체마다 아래 기능 프로필을 두는 방안을 제안합니다. 현재 ERP API에 이 설정 API가 있다는 가정은 하지 않습니다. 실무 승인 후 서비스 자체 저장소에서 관리할 수도 있습니다.

설정 후보 값 예시 효과와 확인할 점
발주서 사용 사용 / 미사용 미사용이면 발주서 조회·생성 UI를 숨김. 권장량 계산 가능 여부는 다른 데이터와 산식으로 별도 판정
수요 기준 확정 수주 / 생산계획 / 매출 이력 / 복합 각 원천의 중복 제거 규칙과 승인된 산식 필요
재고 범위 전체 / 지정 창고 창고별 데이터가 없으면 창고별 계산 불가
공급 예정 원천 발주 잔량 / 승인된 입고 계획 / 없음 원천이 없으면 확정 공급량을 0으로 간주하지 않음
품목별 정책 안전재고, 최소발주량, 배수, 리드타임 대체값 단위·적용 범위·유효기간·승인자 필요
사용량 정책 고객사/사용자별 기간 한도 ERP API 호출·바이트와 LLM 호출·토큰을 분리 측정

자유 텍스트 요청(예: “우리는 발주서를 사용하지 않아요”)은 참고 메모로 저장하고, 실제 동작 변경은 구조화된 값·버전·승인자·유효기간으로 확정합니다. 원천 데이터가 없거나 품질 기준을 만족하지 않으면 결과에 계산 보류와 누락 이유를 보여 주며 임의의 수량을 만들지 않습니다.

5. 협의용 조회 경로 예시

실제 ERP 경로가 다르면 동등한 기존 API로 매핑해 주세요. 신규 API 개발이 필요한 항목은 별도로 표시해 주세요.

용도 협의용 경로 주요 조건
제공 범위 GET /v1/capabilities 고객사·사업장별 데이터셋 상태·갱신 주기·마지막 성공 시각
품목 GET /v1/items 품목 ID/코드, 활성 상태, 수정 시각
매출 GET /v1/sales 기간, 품목, 사업장, 상태, 변경 커서
수주 GET /v1/sales-orders 기간, 품목, 미출고 여부, 상태
발주 GET /v1/purchase-orders 기간, 품목, 잔여 입고 여부, 상태
매입/입고 GET /v1/purchases 또는 GET /v1/receipts 기간, 품목, 창고, 원천 연결 ID
작업지시·생산 GET /v1/work-orders, GET /v1/production-records 기간, 품목, 상태, 연결 ID
BOM GET /v1/boms 모품목, 적용일, 버전, 구성 품목
재고 GET /v1/inventory 품목, 창고, 기준 시각, 재고 유형

거래형 자료에는 최소한 record_id, line_id(행이 있으면), item_id, quantity, unit, 업무 날짜/예정일, status, updated_at, as_of를 제공할 수 있는지 확인해 주세요. 발주 수량은 원 요청서에 없으므로 제공 가능 여부부터 확인합니다. 재고 응답에는 warehouse_id, 수량 종류와 스냅샷 기준 시각이 필요합니다. 각 수치의 원천 ID는 챗봇 답변에 출처로 연결합니다.

6. 질문·계산·사용량의 책임 경계

업체 API는 원천 데이터를 제공합니다. 우리 서비스는 고객사 권한을 확인하고 승인된 규칙으로 조회·계산합니다. LLM은 검증된 결과를 설명하며 수량·권한을 결정하지 않습니다. 실제 LLM 공급자, 데이터 외부 전송 범위와 키는 별도 협의 대상입니다.

초기 질문 범위는 현재고, 기간별 수주/입고 예정, 발주 권장량의 근거, 고객사 규칙 설명입니다. 각 답에는 출처 레코드 ID와 기준 시각을 포함합니다. 원천 누락·불일치·산식 미승인 시 확인 필요/계산 보류로 답합니다. 업체 API 사용량은 호출 수·요청/응답 바이트·실패/재시도를, LLM 사용량은 실제 공급자 응답의 입력/출력 토큰·비용을 별도 집계합니다. 필터 조회·증분 동기화·압축 가능 여부를 확인해 전송량을 줄입니다.

7. 시험 및 회신 형식

실제 사용 업체 DB에서 다음 사례를 실무 담당자와 검증하고 싶습니다: 정상 계산, 데이터 누락, 발주서 미사용, 수주 없음/매출만 있음, 부분 입고·취소, BOM 변경, 창고별 재고 불일치, 고객사 간 자료 분리, 한도 초과. 각 사례에는 원천 ID·기준 시각·기대 결과·보류해야 하는 이유를 함께 기록합니다. 실거래 원본은 승인된 시험 환경 안에서만 취급하고, 외부 전달 샘플은 가명 처리해 주세요.

회신은 아래 묶음이면 충분합니다.

  1. API 명세 또는 제공 가능 데이터 표(각 데이터셋의 제공됨/업무 미사용/제공 불가/일시 장애/미확인).
  2. 데이터별 성공·빈 결과·누락·오류 응답 예시와 필드 사전(단위·상태·ID 관계 포함).
  3. 인증·호출량·시험 환경·담당자 정보. 인증 키와 비밀번호는 문서 대신 별도 보안 경로로 전달.
  4. 발주 산식 또는 실무 판단 사례, 업체별 예외 규칙의 승인 주체.
  5. 실사용 업체 DB 시험 일정과 실무 확인 방식.

협의 결과에 따라 필수 API와 화면 필드를 좁히고 버전 1 계약을 확정하겠습니다.