푸딩 편집기(청첩장·대본·체크리스트·예산·일정)를 제휴사 사이트에 그대로 심거나, 도구 API로 커플용 화면을 직접 만들거나, 계약 커플의 준비 현황만 받아 가요.
https://server.pudding.im/api/companies시작하기
푸딩을 붙이는 방법은 세 갈래예요. 커플이 보는 화면을 누가 만드느냐로 갈려요. 하나만 골라도 되고, 도구마다 다르게 섞어도 돼요 (청첩장은 심고 체크리스트는 직접 만들기처럼요).
푸딩 화면을 그대로 심기
푸딩이 만든 편집기 화면을 제휴사 사이트 안에 창문처럼 끼워 넣어요. 커플이 그 안에서 직접 만들고 고쳐요. 화면을 만들지 않아도 돼요.
POST /me/embed-sessions
↓ cs_ 토큰
sdk.js embed() 또는 <iframe>커플 화면을 직접 만들기
푸딩 화면을 쓰지 않고 제휴사 디자인 그대로 커플용 UI를 직접 만들어요. 데이터 저장과 AI 자동 생성은 도구 API가 맡아요.
POST /me/embed-sessions ↓ cs_ 토큰 POST /embed/exchange ↓ 커플 토큰 (10분) GET·POST /checklists …
현황 숫자만 받아 오기
커플이 보는 화면은 건드리지 않고, 계약 커플의 준비 현황만 받아 제휴사 관리자 화면에 그려요. 예식일까지 며칠·하객 몇 명·체크리스트 몇 % 같은 것들이요.
GET /me/insights GET /me/insights/couples
| 이럴 때 | 갈래 | 제휴사가 만드는 것 |
|---|---|---|
| 가장 빨리 열고 싶어요 | A · 심기 | 편집기를 띄울 자리 + 토큰 발급 엔드포인트 하나 |
| 우리 디자인·UX를 그대로 유지해야 해요 | B · 직접 만들기 | 커플용 화면 전체 (푸딩은 데이터·AI만 맡아요) |
| 기존 화면에 없는 입력 흐름이 필요해요 | B · 직접 만들기 | 커플용 화면 전체 |
| 커플에게 보여줄 화면은 없고, 직원이 볼 현황만 필요해요 | C · 현황 | 제휴사 관리자 화면 |
2번이 세 갈래 모두의 관문이에요. 토큰도 현황도 초대를 수락한 커플에게만 나와요. 순서를 건너뛰면 그 다음이 계속 실패해요.
콘솔에서 API 키를 발급받아요. 개발·테스트엔 샌드박스 키(pk_test_)를 권장해요.
고객 커플에게 초대를 보내요. 커플이 수락해야 다음 단계가 열려요.
수락한 커플의 cs_ 토큰을 받아요. 기본 15분짜리예요.
cs_ 토큰을 SDK에 넘기면 그 커플 편집기가 열려요. 여기서 끝이에요.
cs_를 커플 토큰으로 교환하고, 도구 API로 읽고 쓰면서 화면은 직접 그려요.
수락한 커플들의 준비 현황·집계를 받아 관리자 화면에 그려요.
시작하기
이 API는 스탠다드 요금제부터 쓸 수 있어요. 베이직은 키를 만들 수 없고, 이미 키가 있어도 모든 호출이 403 plan_required로 막혀요.
| 기능 | 베이직 | 스탠다드 | 프리미엄 | 엔터프라이즈 |
|---|---|---|---|---|
| API 키 발급 업체당 최대 5개 | ✕ | ○ | ○ | ○ |
| 임베드 · SDK 편집기 심기 | ✕ | ○ | ○ | ○ |
| 도구 API · 커플 대시보드 | ✕ | ○ | ○ | ○ |
| 로고·색 바꾸기 화이트라벨 · 콘솔에서 신청 | ✕ | ✕ | ○ | ○ |
| 커플 수 | 100팀 | 무제한 | 무제한 | 무제한 |
401이 나요. 요금·세팅비 금액은 제휴사 안내에 있어요. 시작하기
모든 요청 헤더에 API 키를 Bearer로 담아요. 키는 서버에서만 쓰고 프론트엔드에 노출하지 마세요.
Authorization: Bearer pk_live_8f3c2a9d4b6e1057c9a2f4e8b1d7c05a 키는 모드 표시(pk_live_ · pk_test_) + 무작위 32자로 총 40자예요. 콘솔 목록에는 앞뒤만 보여요 — pk_live_8f3c····c05a
pk_live_는 실제 데이터·정산에 반영, pk_test_는 샌드박스 샘플만. 키 발급은 STANDARD 플랜부터, 업체당 최대 5개예요. 키가 잘 발급됐는지 확인하는 첫 호출. 키가 속한 업체·플랜·커플 사용량이 나와요. mode로 운영/샌드박스를 구분해요.
{ "code": 200, "message": "ok", "data": { "company": { "uuid": "a1b2…", "name": "그랜드 웨딩홀", "plan": "STANDARD", "status": "ACTIVE" }, "usage": { "couples_included": null, "couples_accepted": 48, "couples_remaining": null }, "mode": "live" } }
커플
커플을 초대·목록 조회·취소해요. 커플이 수락하면 PRO가 열리고, 그때부터 편집기를 심을 수도 현황을 받을 수도 있어요. 여기서 받은 uuid를 화면 심기·현황에서 그대로 써요.
커플 초대를 만들고 수락 링크를 돌려줘요. couple_email을 넣으면 초대 메일이 자동으로 나가요.
| couple_name 선택 | 식별용 메모 (예: 김철수·이영희) |
| couple_email 선택 | 입력 시 초대 메일 자동 발송 |
식별용 메모 (예: 김철수·이영희)
입력 시 초대 메일 자동 발송
{ "code": 201, "message": "ok", "data": { "uuid": "inv_7d2…", "couple_name": "김철수·이영희", "status": "PENDING", "invite_url": "https://pudding.im/ko/partner/invite/inv_7d2…", "created": "2026-07-28T…" } }
보낸 초대·수락 커플 목록 (미수락 포함). status가 ACCEPTED인 커플의 uuid를 다음 단계에서 써요.
{ "code": 200, "message": "ok", "data": { "count": 31, "results": [ { "uuid": "00000000-0000-0000-0000-000000000901", "couple_name": "곽지훈·백서현", "status": "PENDING", "wedding_date": null, "accepted_at": null, "created": "2027-01-12T…" }, { "uuid": "00000000-0000-0000-0000-000000000001", "couple_name": "김도현·박수아", "status": "ACCEPTED", "wedding_date": "2027-03-20", "accepted_at": "2027-01-10T…", "created": "2027-01-07T…" } ] } }
수락 전 초대를 취소해요. 이미 수락된 초대는 취소되지 않아요(400).
{ "code": 200, "message": "ok", "data": { "uuid": "inv_7d2…", "status": "CANCELED" } }
A · 화면 심기
iframe 태그를 직접 쓰는 대신 sdk.js를 얹으면, 높이 자동 맞춤 · 저장 알림 · 에러 전달을 SDK가 대신 해줘요. 심는 방법은 이게 가장 흔해요.
<div id="pudding"></div>
<script src="https://pudding.im/sdk.js"></script>
<script>
var pudding = Pudding.init({ publishableKey: 'pk_pub_…' });
var view = pudding.embed('#pudding', {
tool: 'invitation', // invitation · script · checklist · budget · schedule
view: 'hub', // hub(목록) · create(생성) · edit(수정)
embedToken: 'cs_live_…', // 서버에서 발급 — 아래 임베드 토큰 참고
onSave: function (data) {},
});
</script>| tool | invitation · script · checklist · budget · schedule |
| view | hub(목록) · create(생성) · edit(수정). 안 주면 resourceId 있을 때 edit, 없으면 hub |
| embedToken | 커플 스코프 단기 토큰(cs_) — 서버에서 발급받아 넘겨요 |
| resourceId | 수정할 항목 uuid (view가 edit일 때) |
| locale | 편집기 언어. 기본 ko |
| minHeight | 첫 렌더 최소 높이(px). 기본 480 |
| onReady() | 편집기가 다 뜬 뒤 한 번 |
| onSave(data) | 커플이 저장할 때마다 — 저장된 내용이 함께 와요 |
| onResize(height) | 높이가 바뀔 때. SDK가 iframe 높이를 이미 맞춰줘요 |
| onError(err) | 토큰 만료 등 — 새 토큰을 받아 reload 하면 돼요 |
| view.reload(cfg) | 다른 커플·항목으로 갈아끼우기 |
| view.destroy() | 편집기 걷어내기 (SPA 화면 전환 시) |
POST /embed-sessions 응답의 embed_url을 그대로 src에 넣으면 돼요. 높이 자동 맞춤만 직접 처리하면 됩니다. A · 화면 심기
SDK에 넘길 cs_ 토큰을 발급받아요. 수락한 커플에게만 나오고, 기본 15분이면 만료돼요.
cs_ 토큰만 브라우저로 내려보내고, API 키는 절대 프론트엔드에 두지 마세요. 수락된 커플·도구에 대한 단기 세션 토큰(cs_)을 발급해요. 이 토큰을 iframe·SDK에 넘기면 그 커플 편집기가 열려요. 기본 15분 만료.
| couple_uuid 필수 | 수락된 커플 uuid (GET /me/invitations 에서 확인) |
| tool 필수 | invitation · script · checklist · budget · schedule |
수락된 커플 uuid (GET /me/invitations 에서 확인)
invitation · script · checklist · budget · schedule
{ "code": 200, "message": "ok", "data": { "embed_token": "cs_live_…", "expires_in": 900, "embed_url": "https://pudding.im/ko/embed/invitations?embed_token=cs_live_…", "mode": "live" } }
A · 화면 심기
커플이 실제로 쓰는 편집기 그대로예요. 아래 편집기는 공개 데모 커플로 이미 열려 있어서 그냥 만져 보면 돼요. 도구를 고르면 생성 · 수정 · 조회 세 화면이 함께 떠요.
예식일·예산·하객 규모로 준비 항목을 자동 생성. 커플이 직접 체크·수정해요.
편집기를 불러오는 중…
수정할 항목이 아직 없어요. 위 생성 데모로 하나 만들면 여기서 바로 열려요. (또는 리소스 uuid 입력)
편집기를 불러오는 중…
B · 직접 만들기
푸딩 화면을 쓰지 않고 제휴사 디자인으로 커플용 UI를 직접 만드는 갈래예요. 그러려면 위에서 받은 cs_ 토큰을 커플 계정 토큰으로 한 번 더 바꿔요. 화면은 제휴사가 그리고, 저장과 AI 자동 생성은 도구 API가 맡아요.
POST /embed-sessions // 파트너 API · API 키로 — cs_ 토큰 ↓ POST /companies/embed/exchange // cs_ 토큰으로 — 커플 access token (10분) ↓ GET /checklists/mine // 도구 API · 커플 토큰으로 — 진짜 데이터
403 EMBED_SCOPE_FORBIDDEN으로 막혀요. 브라우저로 내려보내지 말고 서버에서만 쓰세요. 막는 것만 정해져 있어요. 토큰 하나로 다섯 도구를 다 부를 수 있고, 화면을 그리는 데 필요한 커플 본인 데이터(프로필·예식 정보·미디어 업로드)도 열려 있어요. 막히는 건 커플 본인만 해야 하는 일 세 가지예요.
| 돈 | /payment · /subscriptions | 결제수단 · 구독. 잘못 건드리면 되돌릴 수 없어요 |
| 계정 | /user/withdraw · /user/password · /user/…/social-accounts · /auth · /oauth · /verification | 탈퇴 · 비밀번호 · 소셜 연결. 커플이 계정 자체를 잃어요 |
| 명의 | /posts · /comments · /boards · /anonymous-identity | 커뮤니티 글 · 댓글. 제휴사가 커플 이름으로 말하게 돼요 |
| 운영 | /admin · /companies · /company | 운영 · 제휴사 API. 커플 자격으로 부를 일이 없어요 |
커플 토큰은 10분이면 만료돼요. 갱신 엔드포인트는 없고, cs_ 발급부터 다시 해요. 커플이 한 화면에 오래 머무는 편집 UI라면 만료를 미리 잡아 다시 받는 코드가 필요해요.
// 제휴사 서버 — 만료 1분 전에 미리 새로 받아 둬요 // 캐시 키는 커플 하나. 도구별로 나눌 필요 없어요 — 토큰 하나가 다섯 도구에 다 통해요. async function coupleToken(coupleUuid) { const hit = cache.get(coupleUuid); if (hit && hit.expiresAt - Date.now() > 60_000) return hit.token; const s = await api('POST', '/me/embed-sessions', // API 키로 { couple_uuid: coupleUuid, tool: 'checklist' }); // tool 은 필수값이라 아무거나 const t = await api('POST', '/embed/exchange', // cs_ 토큰으로 { token: s.data.embed_token }); cache.set(coupleUuid, { token: t.data.access_token, expiresAt: Date.now() + t.data.expires_in * 1000 }); return cache.get(coupleUuid).token; }
cs_ 토큰을 커플 계정 access token 으로 교환해요. API 키가 아니라 cs_ 토큰 자체가 자격증명이라 Authorization 헤더는 없어도 돼요. 발급되는 토큰은 그 커플의 다섯 도구 전부에 쓰이고 기본 10분이면 만료돼요.
| token 필수 | POST /me/embed-sessions 로 받은 cs_ 토큰 |
POST /me/embed-sessions 로 받은 cs_ 토큰
{ "code": 200, "message": "ok", "data": { "access_token": "eyJhbGciOi…", "tool": "checklist", "couple_uuid": "inv_7d2…", "expires_in": 600, "mode": "live" } }
B · 직접 만들기
커플이 앱에서 쓰는 API를 그대로 부르는 거라, 여기서 만들고 고친 건 커플 화면에 바로 보여요. 앞의 제휴사 API와는 주소도 인증도 달라요.
| 파트너 API | 도구 API | |
|---|---|---|
| 주소 | https://server.pudding.im/api/companies | https://server.pudding.im/api |
| 인증 | API 키 (pk_live_) 또는 담당자 로그인 | 커플 토큰 (access_token) |
| 유효 | 만료 없음 | 10분 — 끊기면 cs_부터 다시 |
네 가지가 도구마다 똑같은 모양이에요. {uuid}는 목록에서 받은 값이에요.
| 도구 | 목록 | 만들기 | 상세 · 수정 |
|---|---|---|---|
| 체크리스트 | GET /checklists/mine | POST /checklists | GET · PATCH /checklists/{uuid} |
| 예산 | GET /budgets/mine | POST /budgets | GET · PATCH /budgets/{uuid} |
| 일정 | GET /schedules/mine | POST /schedules | GET · PATCH /schedules/{uuid} |
| 대본 | GET /scripts/mine | POST /scripts | GET · PATCH /scripts/{uuid} |
| 청첩장 | GET /invitations/mine | POST /invitations | GET · PATCH /invitations/{uuid} |
예식일·예산·하객 규모를 주면 그 커플에게 맞춘 항목이 자동으로 채워져요. 값 목록은 아래 상태값(enum)에 있어요.
curl -X POST "https://server.pudding.im/api/checklists" \
-H "Authorization: Bearer <커플 토큰>" \
-H "Content-Type: application/json" \
-d '{"wedding_date": "2026-11-15", "budget": 50000000,
"wedding_venue_type": "HOTEL", "guest_scale_tier": "LARGE"}'C · 현황
수락 커플들의 현황·집계. 신랑·신부 연락처가 포함돼요(파트너 고객). 하객 명단은 개개인이 아니라 집계로만 나가요 — 커플별 guest_count(총 하객) · predicted_attendees(AI 예상 참석) · attend_responses(응답) · expected_gift_total(예상 축의금) 필드로요.
전체 집계(totals) + 초대 퍼널(invitations) + 예식 일정 분포(calendar) + 커플별 현황(couples) + 월별 추세(trend).
{ "code": 200, "message": "ok", "data": { "totals": { "couple_count": 24, "guest_count": 3415, "predicted_attendees": 2471, "attend_responses": 1406, "expected_gift_total": 253793000, "published_count": 16, "invitation_readers": 1765, "invitation_opens": 4410, "needs_care_count": 3 }, "invitations": { "sent": 31, "accepted": 24, "pending": 5, "canceled": 2, "accept_rate": 77 }, "calendar": { "this_month": 1, "next_month": 3, "within_30_days": 4, "venue_undecided": 3, "undated": 2 }, "couples": [ { "uuid": "00000000-0000-0000-0000-000000000001", "couple_name": "김도현·박수아", "groom": { "name": "김도현", "email": "groom01@example.com", "phone": "010-0000-0001", "joined": true }, "bride": { "name": "박수아", "email": "bride02@example.com", "phone": "010-0000-0002", "joined": true }, "wedding_date": "2027-03-20", "days_left": 62, "guest_count": 210, "predicted_attendees": 164, "attend_responses": 118, "expected_gift_total": 18040000, "invitation_readers": 172, "invitation_opens": 482, "venue": "그랜드 하얏트 서울", "checklist_progress": 88, "budget_set": true, "invitation_published": true, "blockers": [], "needs_care": false } ], "trend": [{ "month": "2027-01", "couple_count": 24, "guest_count": 3415, … }] } }
수락 커플을 needs_care·예식일·blocker로 걸러 검색·정렬·페이지네이션. 커플 많아도 필요한 것만 뽑아요. (wedding_before / wedding_after=YYYY-MM-DD 도 지원)
{ "code": 200, "message": "ok", "data": { "count": 3, "page": 1, "page_size": 20, "results": [ { "uuid": "00000000-0000-0000-0000-000000000003", "couple_name": "박시우·정하윤", "groom": { "name": "박시우", "phone": "010-0000-0005", "joined": true }, "bride": { "name": "정하윤", "phone": "", "joined": false }, "wedding_date": "2027-02-04", "days_left": 17, "needs_care": true, "blockers": ["venue_undecided"], "checklist_progress": 24, "guest_count": 130 } ] } }
수락 커플 1건의 현황(위 couples[] 원소와 동일). 없거나 미수락이면 404. 데모 키로도 위 목록의 uuid를 그대로 넣어보면 돼요.
{ "code": 200, "message": "ok", "data": { "uuid": "00000000-0000-0000-0000-000000000001", "couple_name": "김도현·박수아", "groom": { "name": "김도현", "phone": "010-0000-0001", "joined": true }, "bride": { "name": "박수아", "phone": "010-0000-0002", "joined": true }, "wedding_date": "2027-03-20", "days_left": 62, "guest_count": 210, "checklist_progress": 88, "blockers": [], "needs_care": false } }
설정 · 레퍼런스
요청에 넣을 수 있는 값 목록이에요. 하드코딩 대신 이걸 받아 쓰면 언어·통화가 늘어도 안 깨져요.
입력값으로 쓸 수 있는 선택지 목록 — 언어 18종·통화 14종·대본 종류·톤.
{ "code": 200, "message": "ok", "data": { "locales": [{ "code": "ko", "label": "한국어" }, …], "currencies": ["KRW", "USD", "JPY", …], "script_types": ["mc", "officiant", "vow", "toast", "blessing", "reception"], "tones": ["formal", "casual", "touching"] } }
설정 · 레퍼런스
주소에 업체를 적을 자리는 me 하나예요. 키가 이미 업체를 정하니까 업체 uuid를 들고 다닐 필요가 없어요.
| https://server.pudding.im/api/companies/me/… | 키가 속한 업체. 파트너가 쓰는 형태예요 |
| https://server.pudding.im/api/companies/meta | 업체와 무관한 값이라 me가 없어요 (선택지 값 · 토큰 교환) |
같은 주소를 담당자가 로그인해서 부를 수도 있어요. 그때는 사람 한 명이 여러 업체를 맡을 수 있어서 me 대신 업체 uuid를 적어요. 파트너 서버는 신경 쓸 일이 없어요.
모든 응답은 동일한 봉투로 감싸져요. 실제 데이터는 항상 data 안에 있어요.
{ "code": 200, "message": "ok", "data": { … } }
실패도 같은 봉투로 와요. 분기는 HTTP 상태코드가 아니라 errors.field_errors.code로 하세요. 상태코드는 겹쳐서, 403만 보고는 요금제를 올려야 할지 콘솔로 가야 할지 알 수 없어요.
{ "code": 403, "message": "이 기능은 API 키로 호출할 수 없어요. 파트너 콘솔에서 진행해주세요.", "errors": { "field_errors": { "detail": ["…"], "code": ["api_key_not_allowed"] }, "non_field_errors": [] } }
| HTTP | code | 언제 | 할 일 |
|---|---|---|---|
| 401 | (code 없음) | Authorization 헤더가 없어요 | Bearer pk_live_… 를 붙여요 |
| 401 | invalid_api_key | 키가 틀렸거나, 업체가 이용 중(ACTIVE)이 아니에요 | 콘솔에서 키를 다시 확인해요. 키가 맞다면 업체 상태 문제예요 |
| 403 | plan_required | 스탠다드 미만 요금제예요 | 요금제를 올리면 바로 열려요 |
| 403 | api_key_not_allowed | 키로는 부를 수 없는 기능이에요 (담당자·정산·결제수단·해지) | 파트너 콘솔에서 진행해요 |
| 404 | company_not_found | 다른 업체를 가리켰어요 | 업체 자리에는 me 를 넣어요 |
| 404 | couple_not_found | 없거나 아직 수락하지 않은 커플이에요 | GET /me/invitations 에서 status가 ACCEPTED인지 봐요 |
| 400 | invalid_input | 필수값 누락·형식 오류 | message에 어느 값이 문제인지 나와요 |
| 400 | tool_not_supported | 없는 도구 이름이에요 | invitation · script · checklist · budget · schedule |
Authorization 헤더가 없어요
Bearer pk_live_… 를 붙여요
키가 틀렸거나, 업체가 이용 중(ACTIVE)이 아니에요
콘솔에서 키를 다시 확인해요. 키가 맞다면 업체 상태 문제예요
스탠다드 미만 요금제예요
요금제를 올리면 바로 열려요
키로는 부를 수 없는 기능이에요 (담당자·정산·결제수단·해지)
파트너 콘솔에서 진행해요
다른 업체를 가리켰어요
업체 자리에는 me 를 넣어요
없거나 아직 수락하지 않은 커플이에요
GET /me/invitations 에서 status가 ACCEPTED인지 봐요
필수값 누락·형식 오류
message에 어느 값이 문제인지 나와요
없는 도구 이름이에요
invitation · script · checklist · budget · schedule
| 커플 초대 status | PENDING · ACCEPTED · CANCELED |
| 임베드 tool | invitation · script · checklist · budget · schedule |
| plan | BASIC · STANDARD · PREMIUM · ENTERPRISE |
| business_type | VENUE · SDM · PLANNER · AGENCY · ETC |
| company status | PENDING_DEPOSIT · ACTIVE · SUSPENDED |
| mode | live · test (샌드박스) |
| wedding_venue_type | INDOOR · OUTDOOR · HOTEL · CHAPEL · SMALL |
| budget_tier | ECONOMY · STANDARD · PREMIUM · LUXURY |
| guest_scale_tier | SMALL · MEDIUM · LARGE · XLARGE |
설정 · 레퍼런스
파트너는 자기 고객(커플)의 정보를 받아 직접 챙길 수 있어요. 커플의 손님(하객)은 개개인이 아니라 집계로만 나가요.
