> For the complete documentation index, see [llms.txt](https://sharelink-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sharelink-docs.toss.im/developers/open-api/convention.md). # 공통 규약 응답 형식, 오류 코드, 재시도, 호출 제한, 일 사용 상한, 페이징 등 모든 API 호출에 공통으로 적용되는 규칙입니다. 인증·환경 설정은 [연동 시작하기](/developers/open-api/auth.md)를 먼저 보세요. *** ## 공통 응답 형식 쇼핑 서버의 응답은 아래 공통 형식을 사용합니다. OAuth 토큰 발급 응답과 API 게이트웨이에서 먼저 거절한 응답은 형식이 다를 수 있습니다. **성공** ```json { "resultType": "SUCCESS", "success": { // 각 API별 응답 본문 } } ``` **실패** ```json { "resultType": "FAIL", "error": { "errorType": 400, "errorCode": "INVALID_ARGUMENT", "reason": "오류 내용" } } ``` > **HTTP 상태 코드와 응답 본문을 함께 확인해 주세요.** HTTP 200이어도 `resultType: "FAIL"`이면 실패입니다. 공통 응답 형식일 때는 `resultType`으로 성공 여부를 판단하고, 실패 원인은 `error.errorCode`와 `error.reason`에서 확인합니다. `errorType: 400`은 본문의 오류 분류이며 HTTP 400을 뜻하지 않습니다. ### HTTP 상태와 본문은 이렇게 구분합니다 입력값 검증 항목은 인증·권한 등 앞선 검사를 통과한 요청을 기준으로 설명합니다. 앞선 검사에서 거절되면 그 실패가 먼저 응답됩니다. | 상황 | HTTP 상태 | `resultType` | `error.errorCode` | | ----------------------------------------------------------- | --------- | -------------- | ------------------------------------------- | | 요청 성공 | 200 | `SUCCESS` | 해당 없음 | | 상품 상세 ID 누락·숫자 형식 오류·중복 제거 후 30건 초과, 조회 기간·페이지 크기 등 값 검증 실패 | 200 | `FAIL` | `INVALID_ARGUMENT` | | 필수 요청 파라미터 누락, 날짜·숫자·열거형 변환 실패, 잘못된 JSON 등 요청을 읽는 단계의 오류 | 400 | `FAIL` | 고정된 값이 있다고 가정하지 마세요 | | 등록되지 않은 출발지 IP 등 쉐어링크 접근 인가 실패 | 200 | `FAIL` | `SHARELINK_OPENAPI_ACCESS_DENIED` | | 일 사용 상한 초과 | 200 | `FAIL` | `SHARELINK_OPENAPI_QUOTA_EXCEEDED` | | 상품 링크 발급 대상 ID가 모두 없는 경우 | 200 | `FAIL` | 고정된 코드가 없으므로 `error.reason`도 확인하세요 | | 지원하지 않는 지면, 지면 링크에 상품 ID·정의되지 않은 필드를 함께 전달 | 200 | `FAIL` | `SHARELINK_OPEN_API_INVALID_LANDING_TARGET` | | 쉐어링크 점검 중 링크 발급 | 200 | `FAIL` | `SHARELINK_MAINTENANCE_ISSUE_BLOCKED` | | 쇼핑 서버의 예기치 못한 오류 | 200 | `FAIL` | `500` | | 게이트웨이·인증·통신 단계에서 거절되거나 실패 | 4xx·5xx 등 | 공통 형식이 아닐 수 있음 | HTTP 상태·헤더·본문을 함께 기록하세요 | 예를 들어 상품 상세의 `tacaItemIds`는 문자열로 받은 뒤 값을 검사하므로 숫자가 아닌 값도 HTTP 200 + `INVALID_ARGUMENT`로 응답합니다. 반면 실적 조회의 `fromDate`는 날짜로 읽어야 하므로, 날짜 형식 자체가 잘못되면 HTTP 400으로 거절됩니다. 같은 "입력 오류"라도 발생 단계가 다릅니다. 실제 데이터는 `success` 안에서 읽으시면 됩니다. ### 오류 코드 **알려진 실패 원인은 `error.errorCode`로 판별해 주세요.** 모든 오류에 고정 코드가 있는 것은 아닙니다. 코드가 없거나 모르는 값이면 HTTP 상태와 `error.reason`을 함께 기록하세요. | `errorCode` | 의미 | 조치 | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INVALID_ARGUMENT` | 요청을 읽은 뒤의 값 검증 실패입니다. 상품 상세 ID 오류, 주문상품 조회의 구매기간·페이지 크기·식별자 오류, 조회 기간·페이지 크기 오류, **존재하지 않는 `categoryId`** 등이 해당합니다 | 요청 형식을 고쳐 주세요. 재시도해도 결과가 같습니다 | | `SHARELINK_OPENAPI_ACCESS_DENIED` | 인증 정보 무효·폐기, 등록되지 않은 출발지 IP, 비활성 거래처, 등록되지 않았거나 다른 거래처의 `subTagId`·`publisherId` 중 하나입니다 | 인증 정보 상태, 어드민에 등록하신 호출 서버 IP를 확인해 주세요. 링크 발급만 실패하면 요청에 넣은 `publisherId`·`subTagId`도 확인하세요 | | `SHARELINK_OPENAPI_QUOTA_EXCEEDED` | 오늘 쓰실 수 있는 한도를 모두 사용하셨습니다 | 이 페이지의 **일 사용 상한**을 참고해 주세요. 자정(KST)에 리셋됩니다 | | `SHARELINK_OPEN_API_INVALID_LANDING_TARGET` | 링크 발급 대상이 올바르지 않습니다 | [쉐어링크 발급](/developers/open-api/api/link.md)의 지면별 요청 규칙을 확인해 주세요 | | `SHARELINK_MAINTENANCE_ISSUE_BLOCKED` | 쉐어링크 점검 중이라 링크 발급이 거절됐습니다. 상품·지면 링크 발급과 기존 링크 재요청 모두 해당합니다 | 점검이 끝난 뒤 다시 요청해 주세요. 거절된 요청은 일 사용 상한에서 차감되지 않습니다 | | `500` | 서버 오류. HTTP 200 + `errorCode: "500"`(문자열)로 내려갑니다 | 잠시 후 재시도해 주세요 | | `OPENAPI_SUB_TAG_*` | subTag 관리 전용 오류입니다 | [subTag 관리](/developers/open-api/api/sub-tags.md)의 **오류 코드**를 봐 주세요 | | `NOT_FOUND` | 주문상품 단건 조회에서 해당 거래처가 조회할 수 있는 완성된 내역이 없습니다 | [주문상품 조회](/developers/open-api/api/order-products.md)의 **오류 처리**를 확인해 주세요 | | `INVALID_REQUEST` | 주문 이벤트 조회의 `subTagId` 형식 검증 실패입니다 | [주문 이벤트 조회](/developers/open-api/api/order-events.md)의 요청 규칙에 맞게 값을 고쳐 주세요 | | `INVALID_CURSOR` | 주문 이벤트·주문상품 조회에서 커서가 손상됐거나 조회 조건과 맞지 않을 때 발생합니다. 주문 이벤트의 기간·무기간 커서 혼용도 해당합니다 | [주문 이벤트 조회](/developers/open-api/api/order-events.md)·[주문상품 조회](/developers/open-api/api/order-products.md)의 **오류 처리**를 확인하고, 조건을 고친 뒤 커서 없이 다시 시작해 주세요 | HTTP 401을 받으면 토큰 누락·만료·유효성을, HTTP 403을 받으면 응답 사유와 필요한 스코프를 확인하세요. **HTTP 403만 보고 출발지 IP 오류라고 단정하지 마세요.** 쇼핑 서버의 출발지 IP 인가 실패는 위 표의 HTTP 200 + `SHARELINK_OPENAPI_ACCESS_DENIED`로 구분합니다. HTTP 429는 호출 속도 제한 안내에 따라 처리하세요. 게이트웨이 응답의 오류 코드·본문은 공통 응답과 다를 수 있습니다. 파라미터 값 오류의 처리는 각 API 문서의 표를 따르세요. [쉐어링크 발급](/developers/open-api/api/link.md)에는 `errorCode` 없이 `reason`만 오는 실패(ID 누락, 발급 제한 상품·판매자)가 있습니다. 그 페이지의 안내를 따라 주세요. `errorCode`는 추가될 수 있습니다. 목록에 없는 값이 오더라도 동작이 멈추지 않도록, 알 수 없는 `errorCode`는 재시도하지 않는 실패로 처리하고 로그에 남겨 주시길 권장합니다. 문제가 계속된다면 발생 시각, 엔드포인트, 요청 파라미터, HTTP 상태 코드, 응답 헤더와 본문을 함께 전달해 주세요. ### 재시도 | 상황 | 처리 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `500` · HTTP 5xx · HTTP 429 | 지수 백오프로 재시도해 주세요. 429는 `Retry-After` 헤더를 우선 따릅니다 | | `SHARELINK_OPENAPI_QUOTA_EXCEEDED` | **재시도하지 마세요.** 자정(KST) 리셋 전까지는 결과가 같습니다 | | `SHARELINK_MAINTENANCE_ISSUE_BLOCKED` | **즉시 재시도하지 마세요.** 점검 중에는 결과가 같습니다. 점검이 끝난 뒤 다시 요청해 주세요 | | `SHARELINK_OPEN_API_INVALID_LANDING_TARGET` · `INVALID_ARGUMENT` · `INVALID_REQUEST` · `INVALID_CURSOR` · `SHARELINK_OPENAPI_ACCESS_DENIED` · HTTP 400·401·403 | **재시도하지 마세요.** 요청이나 자격의 문제라 그대로 다시 보내도 결과가 같습니다. 원인을 고쳐야 합니다 | 조회 API(`GET`)는 멱등하므로 안전하게 재시도하실 수 있습니다. *** ## 호출 제한 (Rate Limit) | 항목 | 기준 | | ------ | ------------------------------ | | 지속 한도 | 거래처 단위 **10 rps** (전 엔드포인트 합산) | | 순간 버스트 | 최대 30 | | 초과 시 | HTTP 429 + `Retry-After` 헤더 | 아래 캐시·재사용 안내는 승인받은 제휴 목적 안에서 호출량을 줄이는 기술적 기준입니다. 캐시 기간을 짧게 유지하거나 소수 상품만 노출한다는 조건만으로 추천 페이지·외부 서비스의 운영이나 이미지 사용이 승인되는 것은 아닙니다. 서비스 사용 승인과 상품 이미지 사용 범위는 별도로 확인해 주세요. 사용 범위가 불분명하면 서비스 URL·노출 화면·저장 기간·이미지 사용 방식을 준비해 [토스쇼핑 고객센터](https://toss-business.channel.io)에 문의해 주세요. **응답을 저장해서 재사용하시는 것을 전제로 설계해 주세요.** 랭킹은 실시간이 아닙니다. 베스트 상품은 1시간 단위, 카테고리 베스트는 매일 09:00(KST)에 갱신되므로 그보다 자주 호출할 이유가 없습니다. 발급받은 쉐어링크도 저장해 두고 재사용하시면 됩니다. *** ## 일 사용 상한 바로 위 호출 제한이 **순간** 호출 속도를 제한한다면, 일 사용 상한은 **하루에 가져가실 수 있는 총량**을 제한합니다. 적용 지점과 초과 시 응답이 서로 다르므로 하나의 카운터로 합쳐 관리하지 마세요. | 항목 | 기준 | | --------- | ---------------------------------------------------------- | | 조회로 받은 상품 | 하루 **10,000개** | | 새로 발급한 링크 | 하루 **10,000개** | | 적용 단위 | 거래처(인증 정보 1벌) 단위 | | 리셋 | 매일 자정(KST) | | 초과 시 | HTTP 200 + `errorCode: "SHARELINK_OPENAPI_QUOTA_EXCEEDED"` | 두 한도는 **서로 독립적**입니다. 합산되지 않으며, 한쪽을 다 쓰셔도 다른 쪽은 그대로 사용하실 수 있습니다. 한도를 모두 쓰신 뒤의 응답입니다. 호출 속도 제한(HTTP 429)과 달리 **HTTP 200으로 내려가므로 `errorCode`로 구분해 주세요.** ```json { "resultType": "FAIL", "error": { "errorCode": "SHARELINK_OPENAPI_QUOTA_EXCEEDED", "reason": "오늘 사용할 수 있는 요청 한도를 모두 사용했어요." } } ``` 두 축 중 어느 쪽이 소진됐는지는 응답에 담기지 않습니다. 상품 조회와 링크 발급 중 어느 호출에서 받으셨는지로 판단해 주세요. ### 세는 방식 | 대상 | 세는 기준 | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 상품 목록·상세 조회 | 응답에 담겨 나간 상품 수를 그대로 누적합니다. 같은 상품을 다시 조회하시면 그때마다 다시 차감됩니다 | | 쉐어링크 발급 | 새로 발급된 링크만 셉니다. 상품 링크는 같은 `tacaItemId`·`publisherId`·`subTagId`, 지면 링크는 같은 `landingType`·`publisherId`·`subTagId`로 다시 요청하시면 기존 링크가 반환되므로 차감되지 않습니다. **`subTagId`가 다르면 새 링크가 발급되어 1건 차감됩니다** | | 연결성 확인·카테고리 조회·subTag 관리·실적/정산 실적 조회·주문 이벤트 조회·주문상품 조회 | 상품을 반환하지 않으므로 차감되지 않습니다 | 한도는 요청을 받기 전에 확인하므로 **응답이 도중에 잘리는 일은 없습니다.** 남은 한도가 있으면 그 요청은 그대로 처리됩니다. 정상적인 연동에서는 한도에 닿지 않는 수준입니다. ### 자주 묻는 호출 한도 질문 #### 한도 상향이 필요하면 어떻게 하나요? 한도 상향은 자동으로 제공되지 않으며, 사용 목적과 서비스 구조를 바탕으로 내부 검토를 거칩니다. 전체 카테고리를 짧은 주기로 반복 조회하기보다는 필요한 범위만 조회하고, 이전 결과와 비교하는 방식을 권장합니다. *** ## 커서 페이징 상품 목록 API 3종(카테고리 베스트·베스트·하루특가)과 subTag 목록 조회·실적 조회·정산 실적 조회·주문상품 목록 조회는 커서 방식으로 페이징합니다. | 파라미터 | 설명 | | -------- | ---------------------------- | | `cursor` | 다음 페이지 조회 위치. 첫 요청에는 넣지 않습니다 | | `size` | 한 번에 받을 개수 | **응답** | 필드 | 설명 | | ------------ | ------------------------------------- | | `nextCursor` | 다음 페이지 조회에 사용할 커서. 다음 페이지가 없으면 `null` | | `hasNext` | 다음 페이지 존재 여부 | **사용법** 1. 첫 요청은 `cursor` 없이 호출합니다. 2. 응답의 `hasNext`가 `true`이면, `nextCursor` 값을 그대로 `cursor`에 담아 다시 호출합니다. 3. `hasNext`가 `false`가 될 때까지 반복합니다. > `cursor` 값은 형식을 보장하지 않는 문자열입니다. **값을 해석하거나 직접 만들어 넣지 말고**, 직전 응답이 준 값을 그대로 전달해 주세요. `size` 허용 범위와 범위를 벗어났을 때의 처리(자동 보정 또는 `INVALID_ARGUMENT` 거절)는 엔드포인트마다 다르니 각 문서를 확인해 주세요. [주문상품 조회](/developers/open-api/api/order-products.md)는 구매 시각·내부 식별자 오름차순으로 페이지를 넘깁니다. 구매기간·필터·인증 거래처를 유지하고, 조건을 바꾸면 커서 없이 다시 시작해 주세요. 상태 변경을 확인하려면 이전 구매기간이나 단건을 재조회합니다. > [**주문 이벤트 조회**](/developers/open-api/api/order-events.md)**는 페이징 규약이 다릅니다.** 다음 페이지 여부 필드가 `hasNext`가 아니라 **`hasMore`이고**, `nextCursor`는 마지막 페이지에서도 `null`이 되지 않으며, 기간 미지정 시 기록 ID 내림차순, 기간 지정 시 발생 시각·기록 ID 내림차순으로 **과거 방향**으로만 넘어갑니다. 새 이벤트를 다시 보려면 커서 없이 새로 시작해야 합니다. 손상된 커서나 조회 조건과 맞지 않는 기간 커서는 `errorCode: "INVALID_CURSOR"`로 거절됩니다. 필터·기간 조건을 바꿀 때는 커서 없이 시작해 주세요. *** ## 상품 카드 공통 필드 상품 목록 API 3종은 아래 필드를 공통으로 내려줍니다. `partnerMallType`은 [상품 상세 조회](/developers/open-api/api/product-detail.md)에도 같은 이름과 규칙으로 제공합니다. | 필드 | 타입 | 설명 | | ----------------- | ------- | ------------------------------------------------------------------------ | | `tacaItemId` | number | 상품 옵션 ID. **상세 조회·링크 발급에 사용하는 식별자입니다** | | `displayName` | string | 상품명 | | `partnerMallType` | string | 판매자 제휴몰 유형. 일반 셀러는 `NONE`, 오아시스는 `OASIS`이며, 모르는 값은 일반 셀러처럼 처리합니다 | | `thumbnailUrl` | string | 썸네일 이미지 주소 | | `productUrl` | string | 상품 페이지 주소. **추적이 없는 일반 링크입니다** (아래 주의사항 참고) | | `displayPrice` | number | 판매가 (원). **배송비가 포함된 금액입니다** (아래 주의사항 참고) | | `originalPrice` | number | 정가 (원) | | `discountRate` | number | 할인율 (%) | | `isSoldOut` | boolean | 품절 여부 | | `reviewScore` | number | 리뷰 평점 | | `reviewCount` | number | 리뷰 수 | | `rank` | number | 목록 내 순위. 1부터 시작하며 페이지 경계를 넘어 연속됩니다 | | `categoryIds` | array | 상품이 속한 카테고리 ID 경로. 상위에서 하위 순서이며 마지막 값이 가장 구체적인 카테고리입니다. **비어 있을 수 있습니다** | ### 제휴몰 유형 (`partnerMallType`) 상품 조회 4종(카테고리 베스트·베스트·하루특가·상품 상세)의 `success.items[]` 각 항목에 `partnerMallType`을 제공합니다. 판매자 제휴몰을 구분하는 문자열이며, 현재 정의된 값은 다음과 같습니다. | 값 | 의미 | | ------- | -------- | | `NONE` | 일반 셀러 | | `OASIS` | 오아시스 제휴몰 | 제휴몰 유형은 앞으로 늘어날 수 있습니다. 응답을 고정된 열거형으로 제한하지 말고, **모르는 값은 일반 셀러처럼 처리해 주세요.** ### 카테고리 경로 (`categoryIds`) `categoryIds`는 이름 없이 ID만 담깁니다. 이름이 필요하시면 [카테고리 조회](/developers/open-api/api/categories.md)로 트리를 한 번 받아 두고 ID로 찾아 쓰시면 됩니다. **경로에 담기는 ID는 모두 그 트리에 존재하는 값**이라 이름을 찾지 못하는 경우는 없습니다. ```json "categoryIds": [100, 101, 10125] ``` 위 예시는 `패션 > 여성의류 > 원피스`처럼 상위에서 하위로 이어지는 경로입니다. **경로 길이는 상품마다 다르고, 빈 배열로 내려오는 상품도 있습니다.** 상품이 속한 카테고리가 공개 트리에서 대분류부터 이어서 확인되지 않으면(트리에 아직 반영되지 않았거나, 트리가 공개하는 5단계보다 깊은 곳에만 속한 경우) 확인되는 데까지만 담고 그 아래는 생략합니다. | 응답 | 의미 | 처리 방법 | | ------------------- | ------------------------ | ------------------------------------------------ | | `[100, 101, 10125]` | 3단계까지 확인된 상품 | 첫 번째는 가장 큰 분류, 마지막은 가장 구체적인 분류로 쓰시면 됩니다 | | `[100]` | 대분류까지만 확인된 상품 | 하위 분류 없이 대분류로만 분류해 주세요 | | `[]` | 공개 트리에서 확인되는 카테고리가 없는 상품 | 카테고리 미분류로 처리해 주세요 (분류 목록에서 제외하거나 '기타'로 묶으시면 됩니다) | `categoryIds[0]`이나 마지막 값에 바로 접근하면 빈 배열에서 오류가 납니다. **값을 꺼내기 전에 배열이 비어 있는지 먼저 확인해 주세요.** *** ## 공통 주의사항 ### 게시글 링크는 반드시 발급 API로 만들어 주세요 조회 API 응답의 `productUrl`은 **추적이 되지 않는 일반 상품 링크**입니다. 이 링크로 발생한 구매는 수익으로 집계되지 않습니다. 게시글에 넣으실 링크는 [쉐어링크 발급](/developers/open-api/api/link.md)으로 발급받은 `shortUrl` 또는 `originUrl`을 사용해 주세요. ### 상품 이미지는 가공하지 말고 원본 그대로 사용해 주세요 {% hint style="warning" %} **썸네일과 상세 페이지 이미지는 쉐어링크 상품을 소개하는 목적으로 표시하실 수 있지만, 가공은 할 수 없습니다.** 크롭·합성·편집·번역 없이 원본 그대로 노출해 주세요. 가급적 썸네일 이미지 사용을 권장합니다. * 셀러가 요청하면 해당 이미지를 바로 내려야 할 수 있습니다. 상품 단위로 이미지 노출을 중단할 수 있게 구현해 주세요. * 상세 페이지에 이미지 사용 금지가 표시된 상품은 썸네일을 포함해 이미지를 사용하지 마세요. 자세한 기준은 크리에이터 가이드 [운영 정책](/help/operations/policy.md#policy-flow-11)의 **상품 이미지 사용**을 확인해 주세요. {% endhint %} ### 배송비는 `displayPrice`에 이미 포함돼 있습니다 `displayPrice`는 **이 상품 하나를 살 때 실제로 결제하게 되는 금액**이며, 배송비가 이미 더해진 값입니다. 배송비를 따로 더해서 노출하시면 실제 결제금액보다 비싸게 표시됩니다. 무료배송이면 더해지는 금액이 없고, 조건부 무료배송이면 해당 상품 하나 기준으로 조건 충족 여부를 계산한 결과가 반영됩니다. 여러 상품을 함께 담아 주문할 때의 배송비는 토스쇼핑 주문 단계에서 다시 계산되므로, 응답 값과 다를 수 있습니다. ### 개인화 정보는 제공되지 않습니다 서버 간 호출이라 특정 사용자 정보가 없습니다. 쿠폰·배송지·적립 등 사용자별로 달라지는 정보는 응답에 포함되지 않으며, 상품 자체 정보만 제공됩니다. ### 가격·품절 상태는 실시간으로 변합니다 응답을 저장해서 사용하시는 경우, 게시 시점의 가격·품절 상태가 실제와 달라질 수 있습니다. [상품 상세 조회](/developers/open-api/api/product-detail.md)로 최신 상태를 확인하실 수 있습니다. ### 성인 상품은 제공되지 않습니다 Open API 조회 기능은 성인 상품을 제공하지 않습니다. *** ## 버전·변경 정책 외부 경로는 `/openapi` 하위로 제공합니다. * **필드 추가처럼 하위호환을 지키는 변경은 기존 경로에 그대로 반영**됩니다. 그래서 알 수 없는 필드를 무시하도록 구현해 주시길 권장합니다. * **하위호환을 깨는 변경은 별도 경로로 제공**합니다 (예: `/openapi/v2`). 쓰시던 경로가 갑자기 달라지지 않습니다. * 기존 기능을 없애는 경우 **사전에 공지**합니다. *** ## 이용 조건 * 제공되는 데이터는 **제휴 목적 범위 내에서만** 사용해 주세요. * 가격 크롤링, 무단 재판매, 비정상적 대량 수집 등은 이용이 제한되거나 차단될 수 있습니다. 자세한 약관과 정산 조건은 [토스쇼핑 고객센터](https://toss-business.channel.io)로 문의해 주세요. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://sharelink-docs.toss.im/developers/open-api/convention.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.