> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiderx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 추천 요청

> 추천 API로 상품 추천을 받아 표시하고, 빈 결과와 요청 실패에 대비하는 방법을 안내합니다.

추천 API는 광고 단위에 설정된 추천 정책으로 상품 목록을 반환합니다. 이 페이지에서는 추천을 요청하고, 응답의 상품을 표시하고, 빈 결과와 요청 실패에 대비하는 방법을 다룹니다.

## 시작하기 전에

* **API 주소:** [API 주소](https://docs.aiderx.io/development/ko/api-access-and-auth.md)를 확인합니다. 추천 요청에는 액세스 토큰이 필요 없습니다.
* **광고 단위:** 추천이 활성화된 광고 단위의 ID를 A2 담당자에게 받습니다. 추천 정책, 추천 개수, 노출 추적 방식은 A2 담당자가 광고 단위에 설정합니다.
* **카탈로그:** 추천할 상품을 [상품 카탈로그](https://docs.aiderx.io/development/ko/catalog.md)에 등록합니다. 응답의 `catalog_id`는 카탈로그의 상품 ID입니다.

## 추천 요청 구성

추천 목록이 필요한 시점에 클라이언트(웹 또는 앱)나 서버에서 `POST /app/v0/recommendation/{tagid}`를 호출합니다. `tagid`에는 광고 단위 ID를 넣습니다. 사용 가능한 필드는 API Reference의 [추천 제공](https://docs.aiderx.io/ko/0.5.0/decision/recommendation-serving/serving-recommendation.md)을 참고하세요.

```bash theme={null}
curl -i -X POST "<A2_API_URL>/app/v0/recommendation/<광고 단위 ID>" \
  -H "Content-Type: application/json" \
  -d '{"user": {"id": "user-123"}}'
```

| 필드 | 사용 기준 |
| - | - |
| `user.id` | 사용자 식별자입니다. 같은 사용자에게는 항상 같은 값을 보냅니다. 이 값이 없으면 추천 실험에 사용자를 배정할 수 없고, 추천 정책에 사용자 이력 조건(이미 본 상품 제외 등)이 있어도 적용되지 않습니다. |
| `seed_item_id` | 기준 상품의 카탈로그 ID입니다. 상품 상세의 연관 상품처럼 특정 상품을 기준으로 추천하는 정책에서 사용합니다. |
| `filter` | 추천에서 제외할 조건입니다. 사용할 수 있는 조건은 카탈로그에 따라 다르므로 A2 담당자와 확인하세요. 배열마다 값은 최대 100개입니다. |

추천 개수는 요청이 아니라 광고 단위의 설정으로 정해집니다.

| 호출 위치 | 응답을 받은 뒤 처리할 내용 |
| - | - |
| 클라이언트 | 응답의 상품으로 목록을 표시하고, `tracking_token`과 상품별 `position`으로 추천 이벤트를 보냅니다. |
| 서버 | 응답을 클라이언트에 전달합니다. 상품마다 `catalog_id`와 `position`을, 목록마다 `tracking_token`을 함께 전달하세요. 운영 규칙으로 일부 상품을 빼거나 순서를 바꾸더라도 `position`은 화면 순번이 아니라 원래 응답의 값을 유지해야 합니다. |

## 응답 처리

```json 추천 응답 예시 theme={null}
{
  "version": "0.1.0",
  "items": [
    { "catalog_id": "catalog-123", "position": 0, "score": 0.87 },
    { "catalog_id": "catalog-234", "position": 1 }
  ],
  "tracking_token": "<tracking_token>",
  "ext": { "ad_log_tracking_mode": "on_event_tracker" }
}
```

| 필드 | 설명 |
| - | - |
| `items[].catalog_id` | 추천 상품의 카탈로그 ID입니다. 상품명·이미지 등 표시할 정보는 서비스의 상품 데이터에서 찾습니다. |
| `items[].position` | 0부터 시작하는 추천 순서입니다. 추천 이벤트의 `event_position`에 그대로 넣습니다. |
| `items[].score` | 추천 점수입니다. 추천 방식에 따라 없을 수 있습니다. |
| `tracking_token` | 이 추천 결과의 추적 토큰입니다. 추천 이벤트에 그대로 넣습니다. |
| `ext.ad_log_tracking_mode` | 노출 추적 방식입니다. [추천 이벤트 추적](https://docs.aiderx.io/development/ko/reco-events-and-logs.md#응답-노출-추적)을 참고하세요. |

응답은 다음과 같이 구분해 처리합니다.

| 응답 | 처리 |
| - | - |
| HTTP `200`, `items` 있음 | 상품을 표시하고 `tracking_token`을 보관합니다. |
| HTTP `200`, `items` 비어 있음 | 추천 영역을 숨기거나 서비스의 기본 목록을 표시합니다. 보낼 추천 이벤트가 없습니다. |
| 오류 상태·통신 실패 | 서비스의 기본 목록을 표시합니다. 응답에 `tracking_token`이 없습니다. |

### 요청 실패

서비스에서 추천을 기다릴 최대 시간을 정해 두고, 그 시간이 지나거나 요청이 실패하면 서비스의 기본 목록으로 대체하세요. 그 뒤에 도착한 응답은 표시하지 않습니다. A2는 기본 설정에서 1초 안에 처리하지 못한 요청에 HTTP `408`을 반환합니다.

오류 응답에는 `errorcode`와 `ext.message`가 들어 있습니다.

| HTTP 상태 | `errorcode` | 원인 | 확인할 내용 |
| - | - | - | - |
| `408` | 없음 | A2가 기본 설정에서 1초 안에 추천을 처리하지 못했습니다. | 서비스의 기본 목록으로 대체합니다. 반복되면 발생 시각과 광고 단위 ID를 A2 담당자에게 전달합니다. |
| `400` | `1300` | `tagid`가 UUID 형식이 아닙니다. | 요청 경로의 광고 단위 ID를 확인합니다. |
| `400` | `1304` | `filter`의 배열에 값이 100개를 넘습니다. | 제외 조건의 값 개수를 줄입니다. |
| `404` | `1301` | 광고 단위를 찾을 수 없습니다. | 광고 단위 ID와 A2 환경이 맞는지 확인합니다. |
| `422` | `1302` | 광고 단위에 추천이 활성화되지 않았습니다. | A2 담당자에게 추천 설정을 요청합니다. |
| `422` | `1303` | 광고 단위에 적용할 추천 정책이 없습니다. | A2 담당자에게 추천 정책 설정을 확인합니다. |

```json 오류 응답 예시 theme={null}
{
  "version": "0.1.0",
  "errorcode": "1302",
  "items": [],
  "ext": { "message": "Recommendation not enabled." }
}
```

다시 요청하면 추천 결과와 `tracking_token`이 달라질 수 있습니다. 이벤트에는 실제로 표시한 응답의 값을 사용하세요. 노출 추적 방식이 추천 응답 기준(`on_ad_response`)이면 표시하지 않은 응답도 응답 수로 집계됩니다.

## 다음 단계

[추천 이벤트 추적](https://docs.aiderx.io/development/ko/reco-events-and-logs.md)에서 표시한 추천의 노출·클릭·전환을 보내는 방법을 확인합니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.