링크
요청 필드, 링크별 결과, 반복 요청을 확인하세요.
링크 생성
POST https://www.ninjabuy.com/api/v1/links에는 Bearer 토큰과 Content-Type: application/json이 필요합니다.
| 필드 | 규칙 |
|---|---|
links | 문자열 1 |
campaign | 선택 사항입니다. 소문자, 숫자 또는 하이픈 3~64자로 구성하며 첫 글자는 문자나 숫자여야 합니다: ^[a-z0-9][a-z0-9-]{2,63}$. 방문 시 utm_campaign으로 전달됩니다. |
label | 링크 목록에 표시할 선택적 이름입니다. 앞뒤 공백 제거 후 인쇄 가능한 문자 1~40자여야 하며 제어 문자는 허용되지 않습니다. 공백을 제거하면 경고가 반환됩니다. |
async | 선택적 불리언입니다. true이면 항상 백그라운드 작업을 시작합니다. |
Taobao, Tmall, Weidian, 1688 상품 링크, 지원되는 구매대행 서비스 링크와 단축 링크, Weidian 및 Taobao 상점(지원되는 구매대행 서비스의 상점 페이지 포함), 지원되는 공개 NinjaBuy 페이지를 변환할 수 있습니다. NinjaBuy URL이나 /search?q=hoodie 같은 경로만 입력해도 됩니다. 기존 NinjaBuy 추천 링크를 붙여넣으면 해당 대상으로 연결되며 본인 계정에 추천 실적이 기록되는 링크가 생성됩니다.
즉시 처리 또는 일괄 처리
async: true 없이 100개 이하를 입력하면 results, warnings, request_id를 포함한 200이 반환됩니다. 100개를 초과하거나 async: true이면 작업, Location, Retry-After를 포함한 202가 반환됩니다. 빠른 시작 및 작업을 확인하세요.
결과는 중복 입력을 포함하여 입력 순서를 유지합니다. 각 행에는 input, status가 있으며 선택적으로 target, url, code, note가 포함됩니다.
| 상태 | 의미 |
|---|---|
ok | 변환되었습니다. url은 추천 실적이 기록되는 NinjaBuy 링크입니다. |
unsupported | 인식했지만 지원되지 않는 마켓플레이스나 비공개 NinjaBuy 페이지 등이라 링크를 만들 수 없습니다. |
unreadable | 사용할 수 있는 대상을 읽을 수 없습니다. |
sheet | Google Sheet URL입니다. 이 엔드포인트는 시트 내용을 변환하지 않습니다. |
시트의 경우 시트 API로 내용을 XLSX로 변환하거나 NinjaBuy에 붙여넣으세요. 기존 NinjaBuy /spreadsheets/d/<sheet id> 페이지 자체에도 추천 실적이 기록되는 링크를 만들 수 있습니다.
반복 요청 및 추천 실적
동일한 계정, 정규화된 대상, 캠페인, 라벨로 생성하면 REST, MCP, 일괄 처리 모두 동일한 링크를 반환합니다. 캠페인이나 라벨이 다르면 별도 링크가 생성됩니다. Idempotency-Key 없이 일괄 요청을 다시 보내면 새 작업이 만들어집니다. 링크 재사용으로 작업 제출의 중복이 제거되지는 않습니다.
새 REST 링크는 createdVia: "api"로 기록됩니다. 링크를 재사용하면 원래 출처(api, mcp, share, redirect)를 유지합니다. 이 필드는 MCP list_links 및 link 결과에 있으며 REST 생성 응답에는 없습니다. 추천 실적 및 보고는 추천을 확인하세요.
Idempotency-Key
POST /api/v1/links, POST /api/v1/uploads, POST /api/v1/sheets에 선택적으로 Idempotency-Key를 보내면 다른 작업을 만들거나 링크 생성 할당량을 추가로 사용하지 않고 요청을 다시 시도할 수 있습니다. 실행하려는 요청마다 인쇄 가능한 ASCII 문자 1~255자로 구성된 고유 키를 사용하세요.
Idempotency-Key: partner-batch-2026-10-23-00124시간 동안 동일한 계정, 키, 검증된 요청은 원래 상태, 바이트 단위로 동일한 본문, 원래 request_id를 포함한 헤더를 Idempotent-Replayed: true와 함께 재반환합니다. JSON 객체 키의 순서는 상관없습니다. 24시간 후에는 키를 재사용할 수 있습니다.
- 동일한 키로 다른 본문이나 POST 경로를 보내면
422(idempotency-key-reused)를 반환합니다. 새 키를 사용하세요. - 첫 요청이 실행 중이면 재시도에
Retry-After와 함께409(idempotency-key-in-progress)를 반환합니다. 기다린 뒤 다시 시도하세요. - 유효하지 않은 키는
400(bad-idempotency-key)을 반환합니다. 유효하지 않은 본문은 키를 예약하지 않습니다. - 실행이 시작되면 오류를 포함한 첫 응답을 저장합니다.
429는 저장하지 않습니다.Retry-After후 동일한 키로 다시 시도하세요.
비정상 종료된 요청은 키가 만료될 때까지 진행 중으로 남을 수 있습니다. 이 요청 재반환 기능은 위의 일치하는 링크 재사용과 별개입니다.