# 서버나 앱에서 링크 만들기

콘솔 외에 Mocco API로도 링크를 만들 수 있습니다. 서버는 **시크릿** 키로 링크를 관리하고, 앱은 **퍼블리셔블** 키로 공유 링크("이 항목 공유" 버튼)를 만듭니다.

먼저 콘솔에서와 같은 준비가 필요합니다. 딥링크를 켜고, 링크 호스트를 정하고, iOS나 Android 앱을 등록하세요([딥링크 개요](https://www.mocco.club/docs/ko/articles/xz8btr-overview) 참고).

## 1. 키 만들기

키는 프로젝트의 **API 키**에서 소유자와 관리자가 만듭니다.

- 서버용으로는 **시크릿** 키를 만듭니다. 링크를 만들고 바꾸려면 `links:write`, 링크와 클릭 수를 읽으려면 `links:read`를 고릅니다. 이 키는 서버에만 두세요. Mocco는 브라우저에서 보낸 시크릿 키를 거부합니다.
- 앱용으로는 `links:app`이 있는 **퍼블리셔블** 키를 만듭니다. 공유 링크만 만들 수 있으므로 앱에 넣어 배포해도 안전합니다.

## 2. 서버에서 링크 만들기

Node에서는 `@mocco/node`를 씁니다.

```ts
import { createMoccoServer } from '@mocco/node';

const mocco = createMoccoServer({ secretKey: process.env.MOCCO_SECRET_KEY! });

const link = await mocco.links.create({
  slug: 'spring',
  deepLinkPath: '/sale/spring',
  campaign: 'spring-2026',
  fallbacks: { web: 'https://shop.example.com/spring' },
  og: { title: '봄 세일', description: '최대 50% 할인' },
});
console.log(link.url); // https://acme.<링크 도메인>/spring
```

시크릿 키로는 콘솔에서 할 수 있는 모든 것을 정할 수 있습니다. 슬러그, 이름, 경로, 파라미터, 캠페인, 웹 대체 주소, 공유 미리보기, 만료일입니다. 콘솔에서처럼 웹 대체 주소는 소유를 확인한 웹 목적지에 있어야 합니다. 같은 클라이언트로 링크 목록을 보고(`list`), 하나를 읽고(`get`), 바꾸고(`update`, 슬러그는 바뀌지 않습니다), 끄고 켜고, 날짜별 클릭 수를 읽습니다(`stats(id, { from, to })`).

다른 언어에서는 `Authorization: Bearer <시크릿 키>`로 API를 직접 부르세요. API 설명은 `/v1/links/openapi.json`에 있습니다.

시크릿 키로 바꾼 내용은 감사 로그에 키를 만든 사람이 한 일로 남고, 어떤 키였는지도 기록됩니다.

## 3. 앱에서 공유 링크 만들기

퍼블리셔블 키로 앱은 다음 항목만으로 공유 링크를 만듭니다.

- `deepLinkPath`: 링크가 앱에서 열 위치. 예: `/items/42`
- `params` (선택): 앱이 링크와 함께 받는 값
- `campaign` (선택)
- `og.title`, `og.description` (선택): 공유 미리보기 문구

```ts
const response = await fetch('https://<Mocco API 주소>/v1/links', {
  method: 'POST',
  headers: { authorization: `Bearer ${publishableKey}`, 'content-type': 'application/json' },
  body: JSON.stringify({ deepLinkPath: '/items/42', og: { title: '42번 상품' } }),
});
const { url } = await response.json();
```

슬러그는 Mocco가 만들고, 앱이 없는 사람은 앱의 스토어 페이지로 갑니다. 공유 링크는 슬러그, 이름, 웹 대체 주소, 이미지, 만료일을 정할 수 없습니다. 정하려고 하면 Mocco가 `field_not_allowed`로 답하며 그 항목을 알려 줍니다. 그래서 누군가 앱에서 키를 빼내도 내 앱 안으로 가는 링크밖에 만들 수 없습니다.

**같은 내용이면 같은 링크입니다.** 앱이 같은 경로, 파라미터, 캠페인, 문구로 다시 요청하면 Mocco는 새 링크 대신 전에 만든 링크를 돌려줍니다. 그래서 공유 버튼을 누를 때마다 링크가 생기지 않습니다.

**한도.** 키 하나는 1분에 공유 링크를 60개까지 만들 수 있고, 프로젝트의 앱들은 하루에 새 공유 링크를 5,000개까지 만들 수 있습니다. 한도를 넘으면 Mocco가 `429`와 `Retry-After`로 답합니다. 이미 있는 링크를 다시 요청하는 것은 그래도 됩니다.

공유 링크도 콘솔의 링크 목록에 다른 링크처럼 나옵니다. 악용되는 링크가 있으면 거기서 끄세요. 그러면 앱이 그 링크를 다시 만들 수 없습니다.