볼테나 EQP 모듈 필요 API

openapi: 3.2.0
info:
  title: 볼테나 ERP 외부연동 EQP 모듈 필요 API
  version: 1.25.2
  description: '- 모든 요청에 `x-api-key` 헤더로 발급받은 키를 넣습니다. 키에 회사 정보가 담겨 있어 회사코드를 따로 보내지 않습니다.

    - 호출 주소는 모든 고객이 같습니다(회사별 주소가 따로 있지 않습니다) — 어느 회사인지는 키가 정합니다. 전용 서버(온프렘)로 쓰시는 경우에만 계약된 주소를 사용하세요.

    - 외부연동은 연동(CONN) 모듈 계약이 있어야 열립니다. 계약이 해지되면 기준정보 내려받기(GET)와 이미 보낸 자료의 취소(DELETE)는 계속 되지만, 새로 보내는 것(POST)과 AI 비서 연결(MCP) 은 닫힙니다 — 이미 보낸 자료를 정리할 길은 항상 열어 두되, AI 조회는 이 모듈이 제공하는 기능 자체이기 때문입니다.

    - 장부 자료 자체는 계약과 무관합니다. AI 조회가 닫혀도 재고·매출·미수채권·시산표는 제품 화면에서 계속 보시고 엑셀로 내보낼 수 있습니다 — 잠기는 것은 자료가 아니라 AI 가 읽는 통로입니다.

    - 보내는 쪽 고유번호(extRef)를 반드시 남겨 두세요. 통신이 끊겨 같은 자료를 다시 보내도 중복이 생기지 않고, 나중에 취소할 때도 이 번호로 찾습니다.

    - 기준정보는 ERP 가 원본입니다. 외부에서 품목·거래처를 만들거나 고치는 API 는 열려 있지 않습니다(한 장부 원칙).

    - 호출 한도는 분당 600회입니다(초과 시 429).

    - AI 비서 연결(MCP): 같은 키로 `POST /api/ext/mcp` 에 연결하면 Claude·ChatGPT 같은 AI 비서가 재고·매출·미수채권·수주/발주 잔량·시산표를 직접 조회합니다. 조회 전용이며 입력·수정·삭제 도구는 제공하지 않습니다.

    - 키를 발급할 때 그 키의 AI 조회 범위를 지정할 수 있습니다(미지정이면 전체). 범위 밖 도구는 `tools/list` 에 나오지 않고, 이름을 알고 호출해도 데이터 없이 사유만 돌아옵니다. 발급 후 범위 변경은 불가하며 새 키를 발급합니다.

    - MCP 조회는 감사 기록에 남습니다 — 어느 키가 언제 어떤 자료를 읽었는지 제품의 사용현황 화면에서 확인할 수 있습니다.'
  contact:
    name: 볼테나 도입 문의
    url: https://boltena.com/contact
servers:
- url: https://app.boltena.com
  description: 클라우드(공통 주소 — 회사는 API 키가 정합니다)
security:
- ApiKeyAuth: []
tags:
- name: EQP 모듈 필요
  description: EQP 모듈 계약이 있어야 호출됩니다
paths:
  /api/ext/eqp/downtime:
    post:
      summary: 설비 비가동 보내기
      description: 설비가 멈춘 시간을 기록합니다(OEE 계산의 재료). 생산실적과 같은 멱등 규칙이 적용됩니다.
      operationId: post_api_ext_eqp_downtime
      tags:
      - EQP 모듈 필요
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: object
              example:
                ok: true
                docNb: ED2608000003
                dup: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                extRef:
                  type: string
                  description: 보내는 쪽 고유번호
                  maxLength: 100
                  example: IOT-DN-20260810-003
                eqpCd:
                  type: string
                  description: 설비코드
                  example: EQ001
                dnDt:
                  type: string
                  description: 발생일자 YYYYMMDD
                  pattern: ^[0-9]{8}$
                  example: '20260810'
                downMin:
                  type: number
                  description: 비가동 분(分)
                  minimum: 0
                  example: 45
                rsnCd:
                  type: string
                  description: 사유코드
                  example: BRK
              required:
              - extRef
              - eqpCd
              - dnDt
              - downMin
  /api/ext/eqp/downtime/{extRef}:
    delete:
      summary: 설비 비가동 취소
      description: 보냈던 비가동 기록을 취소합니다.
      operationId: delete_api_ext_eqp_downtime_extref
      tags:
      - EQP 모듈 필요
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: object
              example:
                ok: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - name: extRef
        in: path
        required: true
        description: 보낼 때 쓴 고유번호
        schema:
          type: string
          description: 보낼 때 쓴 고유번호
          example: MES-WR-20260810-001
components:
  responses:
    TooManyRequests:
      description: 분당 호출 한도 초과
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: 사람이 읽을 수 있는 오류 사유
              module:
                type: string
                description: 모듈 게이트로 막힌 경우 그 모듈키
          example:
            error: 요청이 너무 많습니다...
    Forbidden:
      description: 연동(CONN) 또는 해당 모듈 미계약 · 해지 상태에서 신규 전송 또는 AI 조회(MCP)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: 사람이 읽을 수 있는 오류 사유
              module:
                type: string
                description: 모듈 게이트로 막힌 경우 그 모듈키
          example:
            error: '...'
            module: CONN
    BadRequest:
      description: 필수값 누락·형식 오류(메시지에 어느 값인지 명시)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: 사람이 읽을 수 있는 오류 사유
              module:
                type: string
                description: 모듈 게이트로 막힌 경우 그 모듈키
          example:
            error: extRef(멱등키, 100자 이내)는 필수입니다
    Unauthorized:
      description: 키가 없거나 유효하지 않음
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: 사람이 읽을 수 있는 오류 사유
              module:
                type: string
                description: 모듈 게이트로 막힌 경우 그 모듈키
          example:
            error: 유효하지 않은 API 키입니다
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 제품의 시스템 > API 키 관리에서 발급합니다. 키에 회사 정보가 담겨 있어 회사코드를 따로 보내지 않습니다.