시트

계정의 Bearer 토큰을 사용해 Google Sheet나 업로드한 통합 문서 전체의 링크를 변환하세요. CSV를 입력해도 출력은 항상 .xlsx입니다. 링크에 설명된 대로 링크를 원래 위치에서 교체하며, 계정의 추천 실적과 선택적 campaign, label이 적용됩니다.

Google Sheet 입력섹션 링크 복사

NinjaBuy가 읽을 수 있는 Google Sheets URL을 제출하세요. 변환은 표시된 미리보기뿐 아니라 모든 탭을 읽고 이 작업을 위한 스냅샷을 고정합니다.

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

XLSX 또는 CSV 입력섹션 링크 복사

먼저 업로드를 예약하세요. filename은 .xlsx 또는 .csv로 끝나야 하며, 앞뒤 공백 제거 후 1255자여야 합니다. bytes는 정확한 파일 크기를 바이트로 나타내며 120,971,520입니다.

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

201 응답에는 upload_id, 서명된 PUT url, expires_at(Unix 기준 시점부터의 밀리초), max_bytes, request_id가 포함됩니다. 예약은 15분 후 만료됩니다. 반환된 URL에 원본 파일을 PUT으로 보낸 다음 해당 업로드 ID를 제출하세요.

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

직접 PUT은 스토리지 서비스의 응답 규약을 사용합니다. NinjaBuy는 변환을 제출할 때 업로드한 바이트를 검증합니다. 알 수 없거나 다른 계정의 업로드 ID는 404를 반환합니다. 저장된 객체의 바이트 수는 선언한 값과 일치해야 합니다. 선언한 크기 또는 최대 한도를 초과하는 객체는 413 upload-too-large를 반환하고, 선언한 크기보다 작은(잘린) 객체는 바이트 수 불일치 설명과 함께 422 invalid-workbook을 반환합니다. 이 검사는 다운로드 전에 수행되며 메타데이터 검사 후 바이트가 변경된 경우에도 적용됩니다. 거부된 원본 업로드 파일은 삭제되며, 승인된 원본 업로드 파일은 검증된 스냅샷이 기록되면 삭제됩니다.

url 또는 upload_id 중 정확히 하나의 소스만 보내세요. 둘 다 선택적 campaign과 label을 허용하며 async 필드는 필요하지 않습니다. 두 POST 경로 모두 Idempotency-Key를 허용하며, 각각 공유 분당 30회 생성 구간의 호출 1회를 사용합니다. 하위 링크 변환은 추가 호출을 사용하지 않습니다.

작업과 다운로드섹션 링크 복사

시트 제출은 Location: /api/v1/jobs/JOB_ID, Retry-After: 5 및 다음 본문과 함께 202를 반환합니다.

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

poll_after_seconds를 지키며 done 또는 failed가 될 때까지 동일한 계정의 토큰으로 작업을 폴링하세요. 완료된 job.result에는 kind: "sheet_conversion", counts 및 15분간 유효한 서명된 download_url이 포함됩니다. 새 다운로드 서명을 받으려면 다시 폴링하세요. 실패한 작업에는 error가 있으며 부분 다운로드는 제공되지 않습니다.

Google 스프레드시트의 경우 job.result에 copy_url이 포함될 수도 있습니다. 이는 링크를 고객님의 링크로 바꾼 Google 스프레드시트 정확한 사본의 보기 전용 링크이며, 링크가 있는 사람은 파일 → 사본 만들기로 자신의 사본을 보관할 수 있습니다. copy_notes에는 그 사본을 보는 사람이 알아야 할 내용(예: =IMAGE()로 만든 그림은 자신의 사본에서 액세스 허용을 한 번 눌러야 함)이 들어 있습니다. download_url은 계속 XLSX를 반환합니다. copy_counts에는 사본에 대한 같은 집계가 들어 있습니다. XLSX를 만들 수 없으면 결과에 copy_url은 남고 download_url은 없으며, copy_notes에 그 이유가 들어 있습니다. download_notes에는 차트나 한 셀의 두 번째 링크처럼 XLSX가 시트에서 담을 수 없는 내용이 한 줄씩 들어 있습니다.

스냅샷과 결과 파일은 작업이 완료되거나 실패한 후 7일간 보관됩니다. 정리 후에도 작업의 상태와 집계를 조회할 수 있지만 job.result.download_url은 생략됩니다. 공유 스냅샷은 다른 작업에서 아직 필요한 동안 유지됩니다. 방치된 원본 업로드 파일은 업로드 예약이 만료된 후 1시간이 지나면 삭제됩니다. 검증된 업로드에서 작업이 시작되지 않은 경우 해당 스냅샷은 예약 만료 후 7일이 지나면 삭제됩니다. 정리는 매시간 실행됩니다.

변환 범위는 links_found = converted + sum(left_by_host) + unresolved를 충족합니다. 소셜 링크, Google Sheets 링크, 동일 통합 문서 내 탐색 및 기존 NinjaBuy 링크는 그대로 유지됩니다. 출력을 쓰기 전에 모든 변환 후보가 응답을 받아야 하며, 응답이 누락되면 작업이 실패합니다.

통합 문서에서 보존되는 내용섹션 링크 복사

출력은 파싱된 격자에 표현된 스타일, 병합, 행과 열 크기, 그림을 보존합니다. 서식 있는 텍스트의 구간은 셀 하이퍼링크가 없는 셀에서 보존되며, 링크된 셀은 텍스트 라벨 하나와 하이퍼링크를 사용합니다. 통합 문서를 새로 직렬화하므로 차트, 매크로 및 해당 격자 밖의 다른 기능은 보존되지 않습니다.

XLSX는 셀당 하이퍼링크 하나를 지원합니다. 변환은 옆에 두 번째 링크를 추가하지 않고 원래 위치에서 링크를 교체합니다. 그림이 아닌 서로 다른 링크 대상이 두 개 이상 있는 셀은 첫 번째 대상을 하이퍼링크로 유지하고 나머지는 셀 메모에 적어 두므로 대상이 사라지지 않습니다.

한도섹션 링크 복사

파서 또는 쓰기 한도를 초과하면 명시적으로 실패합니다. invalid-workbook, upload-expired, upload-too-large는 오류를 참고하세요.