봉이모바일 × 트레딧 — API 연동 스펙

1. 연동 개요

구분	방향	방식	설명
POST 접수 전달	봉이 → 트레딧	REST API	고객 매입 접수 데이터 전달
WEBHOOK 상태 변경	트레딧 → 봉이	웹훅 (POST)	상태 변경 시 즉시 푸시
WEBHOOK 시세 변경	트레딧 → 봉이	웹훅 (POST)	시세 변경 시 즉시 푸시

봉이모바일 역할: 고객 접수 UI + 접수 데이터 전달 + 상태/시세 수신 + 마이페이지 표시
트레딧 역할: 카카오톡 발송 + 계약서 발송 + 수거 + 검수 + 입금 + 상태/시세 웹훅 발송

2. 접수 전달 API (봉이 → 트레딧)

POST 매입 접수 전달

URL	[트레딧 API URL] ← 트레딧 제공 필요
Method	POST
Content-Type	application/json
인증	API Key (Header) ← 트레딧 제공 필요

Request Body

{ "customer": { "name": "이수현", // 고객명 (PASS 인증 실명) "phone": "01065890129", // 연락처 "address": "전남 광양시 동백길 35 14동202호", // 수거 주소 "birth": "1990-01-15", // 생년월일 (PASS) "gender": "M", // 성별 (PASS) M/F "carrier": "SKT" // 통신사 (PASS) }, "device": { "manufacturer": "삼성전자", // 제조사 "model": "Galaxy A15", // 모델명 "storage": "128G", // 용량 "imei": "353850473495282", // IMEI (선택) "self_grade": "A" // 셀프등급 (A~E) }, "bank": { "bank_name": "KB국민은행", // 은행명 "account_number": "123-456-789012", // 계좌번호 "holder_name": "이수현" // 예금주 }, "type": "후보상", // 구분 (후보상 등) "referrer": "상무점", // 추천인 (매장명 or "없음") "bongi_order_id": "BP-20260418-001" // 봉이 내부 주문번호 }

Request 필드 상세

필드	타입	필수	설명
customer.name	string	필수	PASS 인증 실명
customer.phone	string	필수	연락처 (하이픈 없이)
customer.address	string	필수	수거 주소
customer.birth	string	선택	생년월일 (YYYY-MM-DD)
customer.gender	string	선택	M / F
customer.carrier	string	선택	SKT / KT / LGU+ / 알뜰폰
device.manufacturer	string	필수	삼성전자 / Apple / LG
device.model	string	필수	모델명
device.storage	string	필수	128G / 256G / 512G / 1T
device.imei	string	선택	IMEI 번호
device.self_grade	string	필수	A / B / C / D / E
bank.bank_name	string	필수	은행명
bank.account_number	string	필수	계좌번호
bank.holder_name	string	필수	예금주
type	string	필수	구분 (후보상 등)
referrer	string	선택	추천인 매장명 (없으면 "없음")
bongi_order_id	string	필수	봉이 내부 주문번호

Response (성공)

{ "success": true, "tredit_order_id": "20260418-0003571923068800869461", // 트레딧 접수번호 "status": "동의대기" }

Response (실패)

{ "success": false, "error_code": "INVALID_MODEL", "message": "지원하지 않는 모델입니다" }

3. 상태 변경 웹훅 (트레딧 → 봉이)

WEBHOOK 상태 변경 시 봉이로 푸시

URL	https://bongi-mobile-production.up.railway.app/api/webhook/buyback-status
Method	POST
Content-Type	application/json
인증	X-Webhook-Secret: [공유 시크릿 키]

Request Body (트레딧이 봉이로 전송)

{ "tredit_order_id": "20260418-0003571923068800869461", "bongi_order_id": "BP-20260418-001", "status_code": 11, "status_name": "보상완료", "device": { "model": "Galaxy A15", "storage": "128G" }, "grade": { "self_grade": "A", // 고객 셀프등급 "auto_grade": "A", // 자동기능검수등급 "inspect_grade": "B", // 입고후검수등급 "final_grade": "B", // 보상등급 (최종) "final_price": 85000 // 보상가격 (원) }, "logistics": { "pickup_date": "2026-04-19", // 픽업일자 "tracking_number": "1234567890", // 송장번호 "payment_date": "2026-04-20" // 입금일자 }, "timestamp": "2026-04-20T10:30:00+09:00" }

상태 코드 매핑

코드	상태명	설명	봉이 마이페이지 표시
-	동의대기	고객 동의서 서명 대기	접수완료 (동의서 확인 중)
6	접수완료	위탁업체에 접수됨, 수거 예정	수거 대기
?	매입대기	입고 완료, 검수 진행 중	검수 중
11	보상완료	검수 완료, 고객 계좌 송금	매입 완료
41	반송대기	매입 불가, 반송 준비	반송 처리 중
42	반송완료	기기 고객에게 반송 완료	반송 완료
43	매입취소	고객 요청 or 기타 사유 취소	취소

봉이 수신 후 처리

#	처리	설명
1	DB 업데이트	bongi_used_phone_buyback 상태/등급/가격 업데이트
2	어드민 반영	중고폰 매입현황 (11번 메뉴) 상태 자동 반영
3	마이페이지 반영	고객 마이페이지 진행바 자동 업데이트
4	앱 푸시 발송	상태 변경 시 고객에게 앱 푸시 알림 (봉이가 발송)

Response (봉이가 응답)

{ "success": true, "received": "2026-04-20T10:30:01+09:00" }

4. 시세 변경 웹훅 (트레딧 → 봉이)

WEBHOOK 시세 변경 시 봉이로 푸시

URL	https://bongi-mobile-production.up.railway.app/api/webhook/buyback-price
Method	POST
Content-Type	application/json
인증	X-Webhook-Secret: [공유 시크릿 키]

Request Body (트레딧이 봉이로 전송)

{ "type": "price_update", "updated_at": "2026-04-18T09:00:00+09:00", "prices": [ { "manufacturer": "Apple", "model": "iPhone 16 Pro Max", "storage": "256G", "grade_a": 1110000, "grade_b": 980000, "grade_c": 920000, "grade_d": 560000, "grade_e": 10000 }, { "manufacturer": "삼성전자", "model": "Galaxy S26 Ultra", "storage": "256G", "grade_a": 950000, "grade_b": 850000, "grade_c": 780000, "grade_d": 450000, "grade_e": 10000 } // ... 변경된 모델만 전송 (전체 302개 아님) ] }

시세 필드 상세

필드	타입	설명
manufacturer	string	제조사 (Apple / 삼성전자 / LG)
model	string	모델명
storage	string	용량
grade_a ~ grade_e	number	등급별 매입가 (원)

전체 전송 vs 변경분만: 변경된 모델만 전송하면 효율적. 전체 전송도 가능 (봉이에서 upsert 처리).
봉이 처리: 수신 → bongi_used_phone_prices 테이블 upsert → 고객에게 최신 시세 표시

Response (봉이가 응답)

{ "success": true, "updated_count": 2, "received": "2026-04-18T09:00:01+09:00" }

5. 접속 정보

항목	URL / 값	비고
봉이 웹훅 (상태)	POST /api/webhook/buyback-status	상태 변경 시 호출
봉이 웹훅 (시세)	POST /api/webhook/buyback-price	시세 변경 시 호출
봉이 프로덕션	https://bongi-mobile-production.up.railway.app
트레딧 접수	https://bonge.tredit.ai/model_chk.php	온라인 접수 페이지
트레딧 어드민	https://soprs.tredit.ai	ID: bonge / PW: bonge

6. 개발 업무 분담

#	업무	봉이모바일	트레딧
1	접수 UI	바텀시트 + 신청서 폼 개발	-
2	접수 전달	POST API 호출	API 수신 + 처리
3	시세 동기화	웹훅 수신 → DB 업데이트	시세 변경 시 웹훅 푸시
4	상태 동기화	웹훅 수신 → DB/어드민/마이페이지 반영	상태 변경 시 웹훅 푸시
5	마이페이지	매입 이력 + 진행바 표시	-
6	어드민	매입 현황 조회 + 관리	-
7	카카오톡 발송	-	접수 안내 / 계약서 발송
8	수거	-	택배 방문수거 처리
9	검수	-	실물 검수 + 등급 확정
10	입금	-	고객 계좌 송금

봉이: 접수 + 표시 (프론트/어드민/마이페이지)
트레딧: 처리 + 알림 (수거/검수/입금/카톡)

7. 트레딧 확인 요청 사항

#	항목	설명
1	접수 API URL	봉이에서 접수 데이터 전달할 엔드포인트
2	API Key / 인증 방식	접수 API 호출 시 인증 헤더
3	웹훅 시크릿 키	봉이 웹훅 수신 시 검증용 시크릿
4	접수 필드 확인	위 Request Body 필드 중 추가/삭제/변경 사항
5	상태 코드 확인	동의대기/접수완료(6)/매입대기(?)/보상완료(11)/반송대기(41)/반송완료(42)/매입취소(43) — 매입대기 코드 확인 필요
6	시세 웹훅 가능 여부	시세 변경 시 웹훅 푸시 가능한지, 아니면 봉이가 주기적 조회?
7	시세 API URL	시세 웹훅 불가 시 봉이가 조회할 시세 API
8	사진 등록	고객이 기기 사진 업로드 필요한지? 사진등록URL은 트레딧에서 제공?
9	매장 코드	추천인(매장명) 전달 시 매장명 문자열 or 매장 코드(831=상무점 등)? 코드 목록 필요
10	에러 코드 목록	접수 실패 시 에러 코드 종류 (INVALID_MODEL 외)
11	웹훅 재시도 정책	봉이 서버 응답 실패 시 재시도 횟수/간격?
12	테스트 환경	스테이징/샌드박스 환경 제공 여부

우선 확인: 1번(접수 API URL) + 2번(인증) + 6번(시세 웹훅 가능 여부) + 9번(매장 코드)가 가장 중요합니다.

봉이모바일 × 트레딧 API 연동 스펙