> For the complete documentation index, see [llms.txt](https://help.genser.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genser.ai/developers/action-data/action-data-integration.md). # 행동 데이터 연동 가이드
{% stepper %} {% step %} ## 연동 준비하기 (Prepare) API를 호출하기 위해 필요한 기본 정보입니다. * **API Endpoint:** `https://api.gelatto.ai` * **Method:** `POST` * **Content-Type:** `application/json` (또는 `application/ld+json`) * **API Key:** 어드민 \[설정] 메뉴에서 발급받은 API Key {% endstep %} {% step %} ## 인증하기 (Authenticate) 준비된 키를 HTTP 요청 헤더(Header)에 설정합니다. 모든 API 요청 시 아래 헤더가 반드시 포함되어야 합니다.
필드명구분설명
Content-Type필수데이터 전송 형식을 JSON으로 지정합니다.
api-key필수[인증키] 어드민 설정에서 발급받은 API Key입니다.
requestId필수[추적키] 매 요청마다 새로 생성하는 고유 식별자입니다. (오류 추적용)
Idempotency-Key필수[중복방지키] 네트워크 오류 등으로 인한 중복 처리를 막기 위한 키입니다.
{% hint style="success" %} **Idempotency Key 포맷 상세 기준** genser API는 UUID Version 4 표준 사용을 권장합니다. * **권장 형식:** 하이픈(-)이 포함된 표준 형식 * **글자 수 길이:** * **표준 (권장):** 하이픈 포함 시 총 36자 (예: `550e8400-e29b-41d4-a716-446655440000`) * **대체:** 하이픈 제거 시 총 32자 (예: `550e8400e29b41d4a716446655440000`) {% endhint %} **HTTP 요청 헤더 예시:** ``` POST /actions/cart/add HTTP/1.1 Host: api.gelatto.ai Content-Type: application/json api-key: Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 requestId: req-20260112-001 ``` {% endstep %} {% step %} ## 데이터 전송하기 (Send Data) 사용자의 행동이 발생한 시점(버튼 클릭, 페이지 로드 등)에 맞춰 해당 API를 호출합니다. 아래 상황별 JSON 예시를 참고하여 데이터를 전송해 주세요. 상세한 필드 규격은 각 항목의 [**\[API 레퍼런스\]**](https://docs.genser.ai/integration/action-data/api-references)에서 확인하실 수 있습니다. {% hint style="info" %} 아래 요청 Body는 연동을 위한 예시입니다. Optional 필드는 고객사에서 수집 가능한 경우에만 전송하며, 수집하지 않는 필드는 요청에서 제외할 수 있습니다. {% endhint %} #### **장바구니 (Cart)** **장바구니 추가 (Add to Cart)** 사용자가 '장바구니 담기' 버튼을 클릭했을 때 호출합니다. **Path**: `/actions/cart/add`
본문(Body) 코드 샘플 ```js { "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) 코드 샘플 ```js { "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) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-START-CHECKOUT-001", "type": "start_checkout", "time": "2025-12-02T10:20:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "CheckoutAction", "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/purchase/checkout](https://shop.example.com/purchase/checkout)" } } } ```
**결제 완료 (Complete Purchase)** 결제가 성공적으로 완료된 시점(주문 완료 페이지)에 호출합니다. **가장 중요한 데이터**입니다. **Path**: `/actions/purchase/complete`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-COMPLETE-PURCHASE-001", "type": "complete_purchase", "time": "2025-12-02T10:25:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "OrderAction", "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/purchase/complete](https://shop.example.com/purchase/complete)" } } } ```
**결제 취소 (Cancel Purchase)** 사용자가 결제를 취소하거나 주문을 철회했을 때 호출합니다. **Path**: `/actions/purchase/cancel`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-CANCEL-PURCHASE-001", "type": "cancel_purchase", "time": "2025-12-02T11:00:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "CancelAction", "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/purchase/cancel](https://shop.example.com/purchase/cancel)" } } } ```
#### 검색 (Search) **검색어 제출 (Search Submitted)** 사용자가 검색창에 검색어를 입력하고 엔터키를 치거나 돋보기 아이콘을 눌렀을 때 호출합니다. **Path**: `/actions/search/submitted`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-SEARCH-SUBMITTED-001", "type": "search_submitted", "time": "2025-11-28T10:00:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "SearchAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ], "gender": "Female", "additionalProperty": [ { "@type": "PropertyValue", "propertyID": "age", "value": 18 } ] }, "query": "편안한 소파 찾아줘", "object": { "@type": "Thing", "actionOption": [ { "@type": "PropertyValue", "propertyID": "search_type", "value": "AI" }, { "@type": "PropertyValue", "propertyID": "color", "value": "검정" } ] }, "target": { "@type": "EntryPoint", "urlTemplate": "[https://shop.example.com/search?color=검정](https://shop.example.com/search?color=검정)" } } } ```
**검색 결과 조회 (View Search Result)** 검색 결과 리스트 페이지가 로딩되었을 때 호출합니다. **Path**: `/actions/search/result`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-VIEW-SEARCH-RESULT-001", "type": "view_search_result", "time": "2025-11-28T10:00:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "ViewAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ] }, "object": { "@type": "ItemList", "numberOfItems": 1, "itemListElement": { "@type": "ListItem", "item": { "@type": "Product", "sku": "131776", "name": "소이 3인소파" }, "position": 1 } }, "target": { "@type": "EntryPoint", "urlTemplate": "[https://shop.example.com/search](https://shop.example.com/search)" } } } ```
#### 상품 (Product) **상품 상세 조회 (View Product)** 상품 상세 페이지(PDP)에 진입했을 때 호출합니다. **Path**: `/actions/view/product`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-VIEW-PRODUCT-001", "type": "view_product", "time": "2025-11-28T10:00:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "ViewAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ] }, "object": { "@type": "Product", "sku": "131776", "name": [{ "@value": "소이 3인소파", "@language": "ko" }] }, "target": { "@type": "EntryPoint", "urlTemplate": "[https://shop.example.com/product/131776](https://shop.example.com/product/131776)" } } } ```
**상품 클릭 (Click Product)** 리스트에서 특정 상품을 클릭했을 때 호출합니다. **Path**: `/actions/click/product`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-CLICK-PRODUCT-001", "type": "click_product", "time": "2025-11-28T10:00:00Z", "source": "[https://shop.example.com](https://shop.example.com)", "data": { "@context": "[https://schema.org/](https://schema.org/)", "@type": "ChooseAction", "agent": { "@type": "Person", "identifier": [ { "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" } ] }, "object": { "@type": "ItemList", "itemListElement": { "@type": "ListItem", "position": 1, "item": { "@type": "Product", "sku": "131776", "name": [{ "@value": "소이 3인소파", "@language": "ko" }] } } }, "target": { "@type": "EntryPoint", "urlTemplate": "[https://shop.example.com/product/131776](https://shop.example.com/product/131776)" } } } ```
#### 위시리스트 (Wishlist) **위시리스트 등록 (Add to Wishlist)** '찜하기' 또는 '위시리스트 추가' 버튼 클릭 시 호출합니다. **Path**: `/actions/wishlist/add=`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-ADD-TO-WISHLIST-001", "type": "add_to_wishlist", "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" } ] }, "object": { "@type": "OrderItem", "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/wishlist](https://shop.example.com/wishlist)" } } } ```
**위시리스트 제거 (Remove from Wishlist)** 위시리스트에서 상품을 삭제할 때 호출합니다. **Path**: `/actions/wishlist/remove`
본문(Body) 코드 샘플 ```js { "specversion": "1.0.0", "id": "EVT-REMOVE-FROM-WISHLIST-001", "type": "remove_from_wishlist", "time": "2025-12-02T10:05: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", "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/wishlist](https://shop.example.com/wishlist)" } } } ```
{% endstep %} {% step %} ## 응답 확인하기 (Check Response) API 호출 후 HTTP 상태 코드를 확인하여 전송 성공 여부를 판단합니다.
상태 코드결과설명
200 OK성공성공입니다. 다음날 00:15am 배치를 통해 반영됩니다.
400 Bad Request요청 형식 오류JSON 문법이 틀렸거나, 필수 값(sku, name 등)이 누락되었는지 확인하세요.
401 Unauthorized인증 실패api-key가 유효하지 않거나 누락되었습니다.
500 Internal Error서버 오류일시적인 장애일 수 있습니다. 잠시 후 재시도(Retry) 로직을 실행하세요.
{% endstep %} {% step %} ## 연동 결과 확인하기 (Verify) - 추후 제공 예정 API 연동 후 데이터가 정상적으로 쌓이고 있는지 어드민에서 확인할 수 있습니다. {% endstep %} {% endstepper %}