---
title: "시작하기"
description: "API 키를 만들고 첫 마켓플레이스 검색을 몇 분 안에 실행해 보세요."
---

## 개요

Apinoa는 마켓플레이스 상품 데이터를 위한 하나의 API입니다. 아마존, 이베이, 쇼피파이, 월마트, 알리익스프레스가
키 하나로, 같은 정규화 스키마로 응답합니다. 마켓플레이스는 경로의 한 조각이고, 요청의 나머지는 모두 같습니다.
같은 키로 이미지 번역도 사용할 수 있습니다.

## 빠른 시작

### 1. 계정 만들기

[apinoa.com](https://apinoa.com)에서 가입하고 이메일 주소를 인증하세요.

### 2. 크레딧 충전

선택할 요금제가 없고, 가입에 카드 등록도 필요 없습니다. 요금은 선불 잔액에서 호출당 차감되며
[요금 안내](/pricing)에 나온 단가를 따릅니다. **대시보드 > 잔액**에서 남은 금액을 확인하고
충전하세요. 먼저 평가해 보고 싶다면 대시보드의 무료 크레딧 카드에서 **$1 무료 크레딧**을 신청할 수 있습니다.

### 3. API 키 생성

**대시보드 > API 키**에서 새 키를 만드세요. 구분하기 쉽도록 접두사를 지정할 수도 있습니다.

```bash
# API 키는 다음과 같은 형태입니다:
myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

API 키는 생성할 때 한 번만 표시되니 안전하게 보관하세요. 키 하나로 모든 마켓플레이스를 호출합니다.

### 4. 첫 요청 보내기

키를 `x-api-key` 헤더에 담아 보내세요.

```bash
curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" \
  -H "x-api-key: YOUR_API_KEY"
```

같은 요청의 파라미터를 쿼리 문자열 대신 JSON 본문으로 보낼 수도 있습니다. 두 방식은 동일합니다.

```bash
curl -X POST https://gateway.apinoa.com/v1/walmart/search \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"query": "wool socks", "priceMax": 30}'
```

```javascript
const url = new URL("https://gateway.apinoa.com/v1/walmart/search");
url.searchParams.set("query", "wool socks");

const res = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" } });
const { success, data, error } = await res.json();
console.log(success ? data.items[0] : error);
```

### 5. 응답 이해하기

모든 응답은 같은 봉투를 씁니다. `success`, 그리고 `data` 또는 `error` 중 하나입니다. 검색은 `data` 안에
[`SearchResult`](/docs/api-reference/marketplaces/response-schema)를 돌려줍니다.

```json
{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 40, "total": 1000 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "996425081",
        "title": "Merino Wool Hiking Socks, 3 Pack",
        "price": { "currency": "USD", "amount": 18.97 },
        "rating": { "average": 4.6, "count": 1204 },
        "inStock": true
      }
    ]
  }
}
```

`price.amount`는 소수점 주 단위입니다. 필드가 없다는 건 마켓플레이스가 말하지 않았다는 뜻입니다. 기본값으로
채우지 않으므로 `price`가 없는 것은 0이 아닙니다.

문제가 생기면 봉투에 에러 코드와 메시지가 담겨 옵니다.

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "brands: Unrecognized key(s) in object: 'brands'"
  }
}
```

### 6. 다른 마켓플레이스 호출하기

경로의 마켓플레이스만 바꾸세요. 키도, 파라미터도, 응답 형태도 그대로입니다.

```bash
curl "https://gateway.apinoa.com/v1/ebay/search?query=wool+socks" -H "x-api-key: YOUR_API_KEY"
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: YOUR_API_KEY"
```

`GET /v1/marketplaces`는 모든 마켓플레이스와 지원 작업, 작업별 비용, 각 작업 입력의 JSON Schema를 알려 줍니다.

## 제공 API

| API | 엔드포인트 | 설명 |
|-----|-----------|-------------|
| 마켓플레이스 | `search`, `browse`, `categories`, `image-search`, `product`, `reviews` | 아마존, 이베이, 쇼피파이, 월마트, 알리익스프레스 상품 데이터를 하나의 스키마로 |
| 이미지 번역 | 번역, OCR, 지원 폰트 | 원본의 시각적 스타일을 유지하며 상품 이미지 속 텍스트 교체 |
| 알리익스프레스 | `search`, `product`, `categories`, `browse`, `image-search` | 알리익스프레스 상품 데이터 |

## 다음 단계

- [마켓플레이스](/docs/api-reference/marketplaces) -- 마켓플레이스 간에 같은 것과 다른 것
- [응답 스키마](/docs/api-reference/marketplaces/response-schema) -- 받을 수 있는 모든 필드
- [필터](/docs/api-reference/marketplaces/filters) -- 모든 마켓플레이스의 가격, 브랜드, 평점, 상태, 정렬
- [인증](/docs/authentication) -- API 키 인증
- [버전 관리](/docs/versioning) -- `/v1`, 버전 없는 구 URL의 지원 종료 예정과 종료 일자
- [에러 코드](/docs/errors) -- 전체 에러 레퍼런스