Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

행동 데이터 연동 가이드

1

연동 준비하기 (Prepare)

API를 호출하기 위해 필요한 기본 정보입니다.

  • API Endpoint: https://api.gelatto.ai

  • Method: POST

  • Content-Type: application/json (또는 application/ld+json)

  • API Key: 어드민 [설정] 메뉴에서 발급받은 API Key

2

인증하기 (Authenticate)

준비된 키를 HTTP 요청 헤더(Header)에 설정합니다. 모든 API 요청 시 아래 헤더가 반드시 포함되어야 합니다.

필드명
구분
설명

Content-Type

필수

데이터 전송 형식을 JSON으로 지정합니다.

api-key

필수

[인증키] 어드민 설정에서 발급받은 API Key입니다.

requestId

필수

[추적키] 매 요청마다 새로 생성하는 고유 식별자입니다. (오류 추적용)

Idempotency-Key

필수

[중복방지키] 네트워크 오류 등으로 인한 중복 처리를 막기 위한 키입니다.

Idempotency Key 포맷 상세 기준

genser API는 UUID Version 4 표준 사용을 권장합니다.

  • 권장 형식: 하이픈(-)이 포함된 표준 형식

  • 글자 수 길이:

    • 표준 (권장): 하이픈 포함 시 총 36자 (예: 550e8400-e29b-41d4-a716-446655440000)

    • 대체: 하이픈 제거 시 총 32자 (예: 550e8400e29b41d4a716446655440000)

HTTP 요청 헤더 예시:

POST /actions/cart/add HTTP/1.1
Host: api.gelatto.ai
Content-Type: application/json
api-key: <YOUR_API_KEY>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
requestId: req-20260112-001

3

데이터 전송하기 (Send Data)

사용자의 행동이 발생한 시점(버튼 클릭, 페이지 로드 등)에 맞춰 해당 API를 호출합니다. 아래 상황별 JSON 예시를 참고하여 데이터를 전송해 주세요. 상세한 필드 규격은 각 항목의 [API 레퍼런스]에서 확인하실 수 있습니다.

아래 요청 Body는 연동을 위한 예시입니다. Optional 필드는 고객사에서 수집 가능한 경우에만 전송하며, 수집하지 않는 필드는 요청에서 제외할 수 있습니다.

장바구니 (Cart)

장바구니 추가 (Add to Cart)

사용자가 '장바구니 담기' 버튼을 클릭했을 때 호출합니다.

Path: /actions/cart/add

본문(Body) 코드 샘플
{
  "specversion": "1.0.0",
  "id": "EVT-ADD-TO-CART-001",
  "type": "add_to_cart",
  "time": "2025-12-02T10:00:00Z",
  "source": "[https://shop.example.com](https://shop.example.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "AddAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" },
        { "@type": "PropertyValue", "propertyID": "userId", "value": "2aa9a562..." }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 2,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.example.com/cart](https://shop.example.com/cart)"
    }
  }
}

장바구니 제거 (Remove from Cart)

사용자가 장바구니에서 상품을 삭제했을 때 호출합니다.

Path: /actions/cart/remove

본문(Body) 코드 샘플
{
  "specversion": "1.0.0",
  "id": "EVT-REMOVE-FROM-CART-001",
  "type": "remove_from_cart",
  "time": "2025-12-02T10:10:00Z",
  "source": "[https://shop.example.com](https://shop.example.com)",
  "data": {
    "@context": "[https://schema.org/](https://schema.org/)",
    "@type": "DeleteAction",
    "agent": {
      "@type": "Person",
      "identifier": [
        { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
      ]
    },
    "object": {
      "@type": "OrderItem",
      "orderQuantity": 1,
      "orderedItem": {
        "@type": "Product",
        "sku": "131776",
        "name": [{ "@value": "소이 3인소파", "@language": "ko" }],
        "offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
      }
    },
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "[https://shop.example.com/cart](https://shop.example.com/cart)"
    }
  }
}

주문/결제 (Purchase)

결제 시작 (Start Checkout)

사용자가 주문서 작성 페이지에 진입했을 때 호출합니다.

Path: /actions/purchase/checkout

본문(Body) 코드 샘플

결제 완료 (Complete Purchase)

결제가 성공적으로 완료된 시점(주문 완료 페이지)에 호출합니다. 가장 중요한 데이터입니다.

Path: /actions/purchase/complete

본문(Body) 코드 샘플

결제 취소 (Cancel Purchase)

사용자가 결제를 취소하거나 주문을 철회했을 때 호출합니다.

Path: /actions/purchase/cancel

본문(Body) 코드 샘플

검색 (Search)

검색어 제출 (Search Submitted)

사용자가 검색창에 검색어를 입력하고 엔터키를 치거나 돋보기 아이콘을 눌렀을 때 호출합니다.

Path: /actions/search/submitted

본문(Body) 코드 샘플

검색 결과 조회 (View Search Result)

검색 결과 리스트 페이지가 로딩되었을 때 호출합니다.

Path: /actions/search/result

본문(Body) 코드 샘플

상품 (Product)

상품 상세 조회 (View Product)

상품 상세 페이지(PDP)에 진입했을 때 호출합니다.

Path: /actions/view/product

본문(Body) 코드 샘플

상품 클릭 (Click Product)

리스트에서 특정 상품을 클릭했을 때 호출합니다.

Path: /actions/click/product

본문(Body) 코드 샘플

위시리스트 (Wishlist)

위시리스트 등록 (Add to Wishlist)

'찜하기' 또는 '위시리스트 추가' 버튼 클릭 시 호출합니다.

Path: /actions/wishlist/add=

본문(Body) 코드 샘플

위시리스트 제거 (Remove from Wishlist)

위시리스트에서 상품을 삭제할 때 호출합니다.

Path: /actions/wishlist/remove

본문(Body) 코드 샘플

4

응답 확인하기 (Check Response)

API 호출 후 HTTP 상태 코드를 확인하여 전송 성공 여부를 판단합니다.

상태 코드
결과
설명

200 OK

성공

성공입니다. 다음날 00:15am 배치를 통해 반영됩니다.

400 Bad Request

요청 형식 오류

JSON 문법이 틀렸거나, 필수 값(sku, name 등)이 누락되었는지 확인하세요.

401 Unauthorized

인증 실패

api-key가 유효하지 않거나 누락되었습니다.

500 Internal Error

서버 오류

일시적인 장애일 수 있습니다. 잠시 후 재시도(Retry) 로직을 실행하세요.

5

연동 결과 확인하기 (Verify) - 추후 제공 예정

API 연동 후 데이터가 정상적으로 쌓이고 있는지 어드민에서 확인할 수 있습니다.

이전사용자 행동 데이터 수집
다음API 레퍼런스

마지막 업데이트