푸딩 제휴사 API

시작하기

개요

연동 방식은 커플이 보는 화면을 누가 만드느냐에 따라 세 가지로 나뉩니다. 도구마다 다른 방식을 골라 섞어 써도 됩니다.

사이드바에 API 키를 입력하면 각 엔드포인트의 '실행해 보기' 버튼이 활성화됩니다. 입력한 키는 브라우저에만 저장됩니다. 키가 없어도 도구별 레퍼런스는 데모 커플 데이터로 살펴볼 수 있습니다. AI 생성 버튼만 방문자당 하루 1회로 제한되며, 남은 횟수는 버튼에 표시됩니다.

시작하기

퀵스타트

네 단계만 거치면 커플의 체크리스트가 제휴사 사이트 안에서 열립니다.

1. 1
   키 받기

   제휴사 콘솔의 정보 관리에서 발급받습니다. 이 퀵스타트는 sk_live_ 키로 진행하세요. 샌드박스 키(sk_test_)는 응답 형식만 돌려주기 때문에 4단계에서 화면이 열리지 않습니다. 키는 스탠다드 요금제부터 발급되고, 베이직 요금제에서는 403 plan_required 로 거절됩니다.

2. 2
   유저 등록하기

   커플 이메일로 계정을 찾아서 없으면 새로 만들고, 있으면 기존 계정에 연결합니다. 여기서 받은 uuid를 3단계에서 사용합니다.

   curl -X POST "{BASE}/users" \
     -H "Authorization: Bearer sk_live_…" \
     -H "Content-Type: application/json" \
     -d '{"user_email": "couple@example.com", "user_name": "김커플"}'
   
   → { "code": 201, "message": "ok",
       "data": { "uuid": "…", "outcome": "created" } }

   복사
3. 3
   임베드 토큰 받기

   등록한 커플의 cs_ 토큰을 발급받습니다. 유효 시간은 기본 15분입니다. 어느 커플인지는 주소의 uuid로 정해지므로 본문에 다시 적을 필요가 없습니다. locale 은 편집기를 열 언어이고, 생략하면 커플이 푸딩에서 쓰던 언어로 열립니다.

   curl -X POST "{BASE}/users/{유저 uuid}/embed-sessions" \
     -H "Authorization: Bearer sk_live_…" \
     -H "Content-Type: application/json" \
     -d '{"tool": "checklist", "locale": "ko"}'
   
   → { "code": 200, "message": "ok",
       "data": { "embed_url": "https://pudding.im/ko/embed/checklists?embed_token=cs_…" } }

   복사
4. 4
   iframe 띄우기

   받은 embed_url을 iframe의 src에 그대로 넣으면 완료입니다.

   <iframe src="{embed_url}"
     style="width:100%; border:0; min-height:480px"
     allow="clipboard-write; fullscreen"></iframe>

   복사

연동 준비

API 키 · 커플 연결

모든 요청의 Authorization 헤더에 API 키를 Bearer 방식으로 담아 보냅니다. 키는 스탠다드 요금제부터 쓸 수 있고, 베이직 요금제에서는 403 plan_required 로 거절됩니다. 요금은 제휴사 안내에서 확인할 수 있습니다.

Authorization: Bearer sk_live_8f3c2a9d4b6e1057c9a2f4e8b1d7c05a

코드를 작성하는 동안은 sk_test_ 키를, 실제 화면을 띄울 때는 sk_live_ 키를 쓰세요. 지금 어느 키로 호출하고 있는지는 응답의 mode 값으로 확인합니다.

커플 연결

커플을 등록하면 그 즉시 커플에게 PRO가 열립니다. 등록 단위는 커플의 대표 계정(유저) 한 명이고, 배우자는 커플이 푸딩 안에서 직접 초대해 연결합니다. 등록할 때 받은 uuid 는 임베드 토큰 발급과 현황 조회에서 그대로 사용합니다.

아래 취소 API는 수락 대기 중인 초대 전용입니다. 이미 연결된 커플에 호출하면 400 already_accepted 를 받습니다. 연결 해지는 API로는 할 수 없고 제휴사 콘솔에서 진행합니다.

커플이 계정을 넘겨받는 방법

등록하면 계정이 생기지만 비밀번호는 아무도 모릅니다. 제휴사가 만들어 알려줄 수도 없습니다.

어느 쪽을 거치든 그때까지 만든 데이터는 그대로 남습니다. 이 과정에서 제휴사가 호출할 API는 없습니다.

한 커플이 여러 업체와 동시에 연결될 수 있습니다. 정산은 업체별로 따로 계산하고, 같은 업체가 같은 커플을 두 번 등록하면 outcome: already 로 응답합니다.

iframe 연동

임베드 토큰 · iframe 붙이기

iframe 주소에 실을 cs_ 토큰을 발급합니다. 토큰은 기본 15분이면 만료됩니다. 발급에 API 키가 필요하므로 서버에서 호출하세요.

iframe에 넣기

응답의 embed_url 을 src 에 그대로 넣습니다. 주소를 직접 조립하지 마세요.

<iframe
  src="https://pudding.im/ko/embed/checklists?embed_token=cs_live_…"
  style="width:100%; border:0; min-height:480px"
  allow="clipboard-write; fullscreen"></iframe>

높이 맞추기

임베드 화면은 높이가 바뀔 때마다 부모 창에 메시지를 보냅니다. 받아서 iframe 높이에 반영하세요.

const frame = document.querySelector('iframe');

window.addEventListener('message', (e) => {
  // 푸딩에서 온 메시지인지, 그리고 이 iframe이 보낸 것인지 둘 다 확인합니다.
  // iframe을 여러 개 붙였을 때 서로의 높이를 덮지 않으려면 두 번째 검사가 꼭 필요합니다.
  if (e.origin !== 'https://pudding.im') return;
  if (e.source !== frame.contentWindow) return;
  if (!e.data?.__pudding_embed) return;

  if (e.data.type === 'resize') frame.style.height = e.data.height + 'px';
  if (e.data.type === 'ready')  { /* 화면이 다 떴으니 로딩 표시를 걷어내세요. */ }
  if (e.data.type === 'error')  console.warn(e.data.code);
});

ready

화면이 다 뜬 뒤 한 번 옵니다

resize

height 에 내용 높이(px)가 담깁니다. 이 값으로 iframe 높이를 맞춥니다

save

커플이 저장할 때마다 옵니다. url 에 무엇을 저장했는지가 담깁니다. 저장이 성공했다는 신호일 뿐 저장된 내용은 담겨 있지 않으므로, 값이 필요하면 도구 API로 다시 조회합니다

error

code 에 사유가 담깁니다. no_token · exchange_failed · no_access_token · network 네 가지입니다. 토큰 문제라면 토큰을 새로 발급해 src 를 교체합니다

부모 창으로 오는 메시지는 이 네 가지가 전부입니다.

임베드 화면의 색과 폰트는 바꿀 수 없습니다. 로고와 색을 바꾸는 화이트라벨은 프리미엄 요금제에서 제공합니다.

iframe 연동

JavaScript SDK

위의 iframe 코드를 대신 만들어 주는 스크립트입니다. 선택 사항이라 직접 리스너를 달았다면 쓰지 않아도 됩니다.

<div id="pudding"></div>
<script src="https://pudding.im/sdk/v1.js"></script>
<script>
  const editor = Pudding.mount('#pudding', { embedUrl });  // 서버에서 받은 주소를 그대로 넘기세요.

  await editor.ready;                       // 화면이 다 뜨면 풀립니다. 실패하면 에러를 던집니다.
  editor.on('error', (e) => e.code);        // 구독을 끊는 함수를 돌려줍니다.
  editor.reload({ embedUrl: freshUrl });    // 토큰이 15분 지나 만료됐을 때 새 주소로 다시 엽니다.
  editor.destroy();                         // 화면을 떠날 때 정리합니다.
</script>

SDK가 대신하는 것

발신자 확인

iframe을 여러 개 붙여도 서로 간섭하지 않습니다. 직접 구현할 때는 e.origin과 e.source를 둘 다 확인해야 합니다

ready

Promise라 await로 로딩 표시를 걷을 수 있습니다

on(type, fn)

ready · resize · error 세 이벤트를 구독합니다. 구독을 끊는 함수를 돌려줍니다

reload(next)

새 토큰이나 다른 항목으로 교체해 다시 엽니다

destroy()

iframe과 리스너를 정리합니다. SPA에서는 호출하지 않으면 리스너가 쌓입니다

타입

/sdk/v1.d.ts를 받아 두면 전역 Pudding에 자동완성이 붙습니다. 번들러를 쓴다면 npm i @runners/pudding-js 설치를 권합니다

다만 SDK는 save 메시지를 넘겨주지 않습니다. 저장 시점이 필요하면 앞 절의 리스너를 직접 추가하세요.

스크립트 주소에 버전이 들어 있습니다(/sdk/v1.js). 호환이 깨지는 변경은 v2 주소로 따로 배포합니다.

API 연동

유저 토큰

커플용 화면을 제휴사가 직접 만드는 방식입니다. 데이터 저장과 AI 생성만 도구 API에 맡깁니다.

도구 API는 커플 본인의 토큰으로 호출합니다. 커플이 앱에서 로그인할 때 받는 토큰과 같은 것이고 수명도 1시간으로 같습니다. 로그인 대신 API 키로 발급받는다는 점만 다릅니다.

POST /users/{uuid}/tokens   // API 키로 부릅니다. 그 커플의 토큰을 1시간짜리로 받습니다.
  ↓
GET  /checklists/mine         // 방금 받은 토큰으로 부릅니다. 커플의 진짜 데이터가 옵니다.

만료되면

/users/{uuid}/tokens 를 다시 호출해 새 토큰을 받습니다. refresh token은 제휴사에 제공하지 않습니다.

API 연동

호출 규칙

커플이 앱에서 쓰는 API를 그대로 호출합니다. 여기서 만들고 수정한 내용은 커플 화면에 바로 보입니다.

호출 한도는 IP가 아니라 키 단위로 계산합니다. 서버를 여러 대로 늘려도 같은 키면 한도를 함께 쓰고, 읽기와 쓰기는 따로 셉니다. 한도를 넘으면 429 응답이 오고, Retry-After 헤더에 몇 초 뒤에 다시 호출하면 되는지 담깁니다.

조회되는 범위 · 배우자 데이터

신랑과 신부는 각각 별도 계정입니다. 조회하면 연결된 배우자의 데이터까지 합쳐서 내려옵니다.

API로 새로 만드는 데이터는 토큰 주인 소유가 되고, 나중에 배우자가 연결되면 배우자에게도 열립니다.

API 연동

만들기 · 읽기 · 편집

다섯 도구가 같은 호출 형태를 씁니다. {리소스} 자리에는 복수형 이름이 들어갑니다. checklists · budgets · schedules · scripts · invitations 다섯입니다.

만들기

AI 초안과 기본 템플릿 둘 다 /previews 아래에 있습니다. AI 쪽에만 대기 시간과 한도가 있습니다.

AI가 만든 결과는 초안이라 confirm 을 호출하기 전까지 커플 화면에 보이지 않습니다. 청첩장에는 템플릿 방식이 없습니다.

POST /{리소스}/previews                  // AI 에게 초안을 맡깁니다. 202와 uuid를 받고 쿼터가 차감됩니다.
  ↓  진행률 확인하는 법은 'AI 생성'에 있습니다
POST /{리소스}/previews/{uuid}/confirm   // 초안을 커플의 것으로 저장합니다.

POST /{리소스}/previews/{uuid}/retry     // 실패했을 때 다시 돌립니다. 쿼터를 한 번 더 씁니다.

읽기

읽기는 도구마다 목록과 상세 두 가지뿐입니다. 상세 조회는 섹션과 항목까지 한 번에 내려줍니다.

GET /{리소스}/mine     // 커플이 가진 것을 목록으로 봅니다.
GET /{리소스}/{uuid}   // 한 건을 통째로 봅니다. 섹션과 항목까지 같이 옵니다.

편집

도구마다 다루는 단위가 다릅니다. 체크리스트·예산은 섹션과 항목, 일정·대본은 항목만, 청첩장은 블록입니다.

보낸 값을 그대로 저장합니다. 즉시 완료되고 AI 한도를 쓰지 않습니다.

삭제는 되돌릴 수 없습니다. 섹션을 지우면 안의 항목도 함께 사라지고, 대표로 지정된 것을 지우려 하면 400 을 받습니다.

API 연동

AI 생성

AI 생성은 202 응답으로 uuid만 먼저 주고 서버에서 비동기로 진행됩니다. 완료 여부는 상태 조회로 확인합니다.

AI 쿼터

쿼터는 제휴사 단위가 아니라 커플 한 팀 기준으로 차감되고, 다섯 도구를 합쳐서 셉니다. 만들기·AI 편집·재시도가 각각 1회씩 차감됩니다.

PRO 커플

하루 20회 (매일 자정 리셋) · 누적 1,000회까지

무료 커플

0회라 AI 생성을 호출할 수 없습니다. 템플릿 방식은 제한 없이 쓸 수 있습니다

완료를 확인하는 법

GET /{리소스}/previews/{uuid}/status 를 몇 초 간격으로 호출하면서 status 값을 확인합니다. 이 주소는 상태만 돌려주고 초안 본문은 담지 않아서, 기다리는 동안 같은 문서를 반복해서 내려받지 않아도 됩니다.

PENDING

아직 생성 중입니다. progress 값으로 진행률을 표시할 수 있습니다

SUCCESS

생성이 끝났습니다. GET /{리소스}/previews/{uuid} 로 결과를 받고 confirm으로 저장합니다

FAILED

생성이 실패했습니다. retry 로 다시 시도하거나 중단합니다

curl "{도구 API}/checklists/previews/{uuid}/status" \
  -H "Authorization: Bearer {유저 토큰}"

→ { "status": "PENDING", "progress": 40, "error_message": "", "error_code": null }

실패로 판정할 때는 총 경과 시간이 아니라 진행률이 멈춘 시간을 기준으로 하세요. 푸딩 앱은 5분을 기준으로 씁니다.

자연어로 고치기

'예산을 5천만원으로 줄여줘'처럼 자연어 문장으로 수정을 요청합니다. 요청이 바로 반영되지는 않습니다. AI가 수정 제안을 먼저 만들고, 그중 고른 것만 적용됩니다. 쿼터는 첫 호출에서만 차감됩니다.

POST /{리소스}/{uuid}/edit-preview   // 어떻게 바꿀지 제안만 만듭니다. 아직 아무것도 안 바뀌고, 쿼터는 여기서 차감됩니다.
  ↓
POST /{리소스}/{uuid}/edit-apply     // 고른 제안만 반영합니다. AI를 다시 실행하지 않아 쿼터도 차감되지 않습니다.
POST /{리소스}/{uuid}/edit-reject/{preview_uuid}   // 안 쓸 제안은 버립니다.

현황 연동

현황 조회

등록한 커플들이 결혼 준비를 어디까지 했는지 집계해서 내려줍니다. 신랑·신부의 이름과 이메일·전화번호는 그대로 제공됩니다. 하객 정보는 개개인의 이름이나 연락처 없이 인원과 응답 수로만 제공되고, 축의금도 실제 수금액이 아니라 하객 응답으로 계산한 예상치입니다.

레퍼런스

도구별 레퍼런스

커플이 실제로 쓰는 다섯 가지 도구입니다. 도구마다 iframe 연동과 API 연동을 나란히 실었습니다.

레퍼런스

요청 · 응답 · ENUM

주소 규칙

주소에 업체 식별자를 적지 않습니다. BASE URL이 이미 키가 속한 업체를 가리키고, 뒤에는 리소스 경로만 옵니다.

https://api.pudding.im/users

등록한 유저(커플 계정). 하나는 /users/{uuid}

https://api.pudding.im/insights

현황·집계

응답 형식

모든 응답은 동일한 봉투로 감싸집니다. 실제 데이터는 항상 data 안에 있습니다.

{ "code": 200, "message": "ok", "data": { … } }

ENUM 코드

지원하는 값 목록입니다. 값을 하드코딩하지 말고 이 API로 받아서 사용하세요. locales 는 Accept-Language 헤더에 넣는 값이고, 이 헤더가 생성 결과물의 언어를 정합니다.

OpenAPI 스펙

Postman · Insomnia로 가져가려면 아래 파일을 불러오세요.

https://server.pudding.im/swagger/company.json

OpenAPI 파일. Postman의 'Import'에 주소를 그대로 넣습니다

https://server.pudding.im/docs/company/

브라우저에서 바로 열어 보는 스펙 문서 목록

레퍼런스

에러 코드

실패 응답도 같은 봉투 형식으로 옵니다. 분기는 상태코드가 아니라 type 으로 하세요. 같은 403 이 여러 사유로 옵니다.

errors.field_errors.code 에 같은 이름이 소문자로도 옵니다. 새로 작성하는 코드는 type 만 확인하면 됩니다.

{
  "code": 403,
  "type": "API_KEY_NOT_ALLOWED",
  "message": "이 기능은 API 키로 호출할 수 없어요. 제휴사 콘솔에서 진행해주세요.",
  "errors": {
    "field_errors": { "detail": ["…"], "code": ["api_key_not_allowed"] },
    "non_field_errors": []
  }
}

상태값 (enum)

커플 초대 status

PENDING · ACCEPTED · CANCELED

outcome (유저 등록)

created · linked · already

blocker (현황)

venue_undecided · invitation_unpublished · no_guests

plan

BASIC · STANDARD · PREMIUM · ENTERPRISE

company status

PENDING_DEPOSIT · ACTIVE · SUSPENDED

mode

live · test (샌드박스)