API

Gem Logic API를 사용하면 외부 시스템과 통합하고 업무 흐름을 자동화할 수 있습니다. 프로그래밍 방식으로 제품, 판매, 연락처, 수리, 재고 실사 및 인쇄 작업을 관리할 수 있습니다.

:menuselection:`설정 –> API`로 이동하여 API 키를 생성하고 관리하실 수 있습니다.

인증

모든 API 요청은 x-api-key HTTP 헤더에 API 키를 포함해야 합니다. 설정 ‣ API 페이지에서 키를 생성할 수 있으며, 언제든지 키를 비활성화하거나 삭제할 수 있습니다.

요청 예시:

curl -X GET https://your-instance.gem-logic.com/api/marketplaces/ \
  -H "x-api-key: YOUR_API_KEY"

위험

API 키를 비밀로 유지하십시오. 공개 저장소나 클라이언트 측 코드에 절대 공유하지 마십시오. 키가 유출된 경우 즉시 비활성화하고 새로운 키를 생성하시기 바랍니다.

기본 URL

모든 엔드포인트는 귀하의 인스턴스 URL에 /api/ 접두사가 붙은 형태로 제공됩니다:

https://your-instance.gem-logic.com/api/

응답 형식

모든 응답은 JSON 형식으로 반환됩니다. 성공적인 요청은 ``200``(GET의 경우) 또는 ``201``(POST의 경우) 상태 코드를 반환합니다. 오류는 해당하는 상태 코드와 함께 메시지를 반환합니다:

  • 200 OK — 성공적인 GET 요청

  • 201 Created — 성공적인 POST 요청

  • 400 Bad Request — 잘못되었거나 누락된 데이터

  • 401 Unauthorized — 잘못되었거나 누락된 API 키

  • 404 Not Found — 리소스가 존재하지 않음

엔드포인트

마켓플레이스

메서드

GET

URL

/api/marketplaces/

설명

모든 판매 채널의 목록을 반환합니다.

응답 필드:

필드

유형

설명

id

integer

고유 식별자

marketplace

string

마켓플레이스 이름

제품

제품 목록 조회

메서드

GET

URL

/api/products/{marketplace_id}

설명

마켓플레이스별로 필터링된 제품을 반환합니다. 마켓플레이스 엔드포인트에서 제공하는 마켓플레이스 ID를 사용하십시오.

응답 필드:

필드

유형

설명

id

integer

고유 식별자

item_sku

string

제품 SKU

created

datetime

생성 날짜

status

string

제품 상태

images

array

제품 이미지 목록 (id, image)

item_weight

decimal

무게

item_height

decimal

높이

item_length

decimal

길이

item_width

decimal

너비

제품 이미지 생성

메서드

POST

URL

/api/products/create/image/

설명

base64 인코딩을 사용하여 제품 이미지를 업로드합니다. 제품 SKU가 아직 존재하지 않으면 새 제품이 자동으로 생성됩니다.

요청 필드:

필드

유형

필수

설명

item_sku

string

예

이미지를 첨부할 제품 SKU

image

string (base64)

예

Base64로 인코딩된 이미지 데이터

판매

판매 목록

메서드

GET

URL

/api/sales/

설명

모든 판매 주문의 목록을 반환합니다.

응답 필드:

필드

유형

설명

order_id

string

고유 주문 식별자

판매 생성

메서드

POST

URL

/api/sales/create/

설명

새 판매 주문을 생성합니다.

연락처

메서드

GET

URL

/api/contacts/

설명

모든 연락처의 목록을 반환합니다.

응답 필드:

필드

유형

설명

id

integer

고유 식별자

complete_name

string

전체 이름

contact_type

string

연락처 유형

email

string

이메일 주소

phone

string

전화번호

language

string

선호 언어

수리

수리 생성

메서드

POST

URL

/api/repairs/create/

설명

연결된 수리 항목이 포함된 새 수리 주문을 생성합니다. 판매 채널 또는 부서가 제공되지 않으면 사용 가능한 첫 번째 채널 또는 부서가 사용됩니다.

요청 필드:

필드

유형

필수

설명

client_id

integer

아니요

고객/연락처 ID

marketplace

문자열 / 정수

아니요

판매 채널 ID 또는 이름

division_id

integer

아니요

사업 부서 ID

title

string

아니요

수리 항목의 제목 또는 설명

repair_info_1

string

아니요

추가 수리 설명

repair_info_2

string

아니요

추가 수리 설명

repair_info_3

string

아니요

추가 수리 설명

quantity

decimal

아니요

수량 (기본값: 1)

weight

decimal

아니요

항목 무게

weight_unit

string

아니요

무게 측정 단위

size

string

아니요

항목 크기

color

string

아니요

항목 색상

engravement

string

아니요

각인 텍스트

client_reference | string

아니요

고객 참조 번호

응답 예시:

{"message": "Repair created successfully.", "order_id": "R-0001"}

수리에 품목 추가

메서드

POST

URL

/api/repairs/add-item/

설명

기존 수리 주문에 새 품목을 추가합니다.

요청 필드:

필드

유형

필수

설명

order_id

string

필수

품목을 추가할 수리의 주문 ID

item_sku

string

아니요

품목과 연결할 제품 SKU

title

string

아니요

제목 또는 설명

repair_info_1

string

아니요

추가 수리 설명

repair_info_2

string

아니요

추가 수리 설명

repair_info_3

string

아니요

추가 수리 설명

quantity

decimal

아니요

수량 (기본값: 1)

weight

decimal

아니요

항목 무게

weight_unit

string

아니요

무게 측정 단위

size

string

아니요

항목 크기

color

string

아니요

항목 색상

engravement

string

아니요

각인 텍스트

client_reference | string

아니요

고객 참조 번호

cost

decimal

아니요

품목의 원가

재고 실사

재고 실사 생성

메서드

POST

URL

/api/inventory-counts/

설명

새 재고 실사 세션을 생성합니다.

응답 필드:

필드

유형

설명

id

string

재고 실사 ID

created_at

datetime

생성 타임스탬프

status

string

항상 active

tag_count

integer

실사된 제품 수

재고 실사 제품 목록

메서드

GET

URL

/api/inventory-counts/{inventory_count_id}/products/

설명

특정 재고 실사에서 실사된 모든 제품을 반환합니다.

응답 필드:

필드

유형

설명

id

string

고유 식별자

created_at

datetime

제품이 실사된 시점

product_sku

string

제품 SKU

product_name

string

제품명

quantity

integer

계수된 수량

대화형 API 탐색기

Gem Logic은 Swagger UI 기반의 대화형 API 탐색기를 내장하고 있습니다. 설정 ‣ API 페이지의 API 문서 링크를 통해 접근하실 수 있습니다. 탐색기를 사용하면 브라우저에서 직접 각 엔드포인트를 시험해 보실 수 있습니다.

더 보기