퀵스타 통관부호 셀러발송 — 최종 시스템 경계도

1. 책임 경계 — 누가 무엇을 하나

각자 가진 데이터와 권한 안에서 처리하고, 상대 시스템의 내부 DB에는 직접 접근하지 않습니다.

엘피스 · 기존 홈페이지

quickstar.co.kr · 솔라피 계정/카카오 채널 소유

불일치 행에 [통관정보 요청] 버튼 노출
엘피스 백엔드에서 우리 send API 호출
주문·수취인·주소 정보를 items로 전달
응답 token을 #{토큰} 변수에 넣어 알림톡 발송
운송장·수취인명·상품명 템플릿 변수 관리

API
경계

우리 서버 · 통관부호 서비스

pass.quickstar-cs.co.kr · 별도 서버

72시간·1회용 토큰 생성 및 link 반환
토큰과 신청서·수취인 스냅샷 연결
수취인 입력화면과 토큰 접근 제어
관세청 UNIPASS 진위 검증
결과를 personal_update로 반영

2. 확정된 전체 흐름

셀러의 클릭부터 결과 반영까지, 실제 실행 주체를 단계별로 표시했습니다.

엘피스 화면

셀러가 불일치 건의 [통관정보 요청] 클릭

버튼은 불일치 행에만 보이고, 여러 건은 items 배열로 한 번에 요청할 수 있습니다.

엘피스 백엔드

우리 send API를 서버 간 호출

브라우저에서 직접 호출하지 않습니다. 신청서번호·수취인·우편번호·주소를 전달하고 운영 인증을 함께 보냅니다.

우리 서버

토큰 발급 후 token과 link 반환

POST /openapi/pccc/send.php가 무작위 토큰을 저장하고 건별 결과를 반환합니다.

엘피스 · 솔라피

#{토큰}을 채워 알림톡 실제 발송

템플릿 버튼 URL은 https://pass.quickstar-cs.co.kr/pccc/?t=#{토큰}입니다. 운송장·이름·상품 변수도 엘피스 주문 데이터로 채웁니다.

수취인

알림톡 버튼을 눌러 통관부호 입력

우리 화면은 토큰으로 해당 건만 찾아 마스킹된 이름·신청서번호를 보여주며, P+숫자 12자리 형식을 검사합니다.

우리 서버 · 관세청

UNIPASS로 이름·전화·우편번호·PCCC 검증

일치·불일치·관세청 오류를 구분하고 토큰 재사용·만료·시도 횟수를 통제합니다.

우리 서버 → 엘피스

personal_update로 결과 반영

신청서 식별값과 검증 결과를 API로 전달합니다. 우리 서버는 엘피스 DB를 직접 수정하지 않습니다.

✓

완료

통관정보 반영 후 토큰 소멸

성공한 링크는 즉시 1회용 소멸되어 다시 열어도 제출할 수 없습니다.

3. 엘피스↔우리 서버 연결점은 두 개

알림톡 발송은 엘피스 내부 처리이므로 별도의 세 번째 시스템 간 호출이 아닙니다.

연결점 1

엘피스 → send → token 응답

엘피스 백엔드가 items를 보내고 우리 서버가 건별 token/link를 반환합니다. 같은 응답을 받아 엘피스가 바로 솔라피 발송을 수행합니다.

연결점 2

우리 서버 → personal_update

수취인 입력과 UNIPASS 검증이 끝나면 우리 서버가 엘피스 제공 API에 일치/불일치 결과를 반영합니다.

4. send API 확정 계약

필드명은 현재 구현과 동일한 recipient_* 이름으로 통일합니다.

REQUEST · 엘피스 백엔드 → 우리 서버

POST https://pass.quickstar-cs.co.kr/openapi/pccc/send.php
Content-Type: application/json
[운영 인증 헤더]

{
  "items": [{
    "gr_code": "GR2607...",
    "recipient_name": "홍길동",
    "recipient_phone": "01012345678",
    "recipient_zipcode": "06236",
    "recipient_addr1": "서울 강남구 ...",
    "recipient_addr2": "1층"
  }]
}

RESPONSE · 우리 서버 → 엘피스

{
  "ok": true,
  "sent": [{
    "gr_code": "GR2607...",
    "ok": true,
    "error": null,
    "link": "https://pass.quickstar-cs.co.kr/pccc/?t=...",
    "token": "..."
  }]
}

솔라피 템플릿 연결

엘피스는 응답의 token 값을 카카오 템플릿 변수 #{토큰}에 넣습니다. 전체 URL이 필요한 구현에서는 같은 응답의 link를 사용할 수 있습니다.

5. 운영 안전 규칙

서버 간 호출만

API Key/HMAC 비밀값을 브라우저 JavaScript에 넣지 않습니다. 버튼은 엘피스 백엔드를 거칩니다.

발송 주체는 엘피스 하나

우리 서버는 token/link만 반환합니다. live에서 우리 CoolSMS 발송 경로는 사용하지 않습니다.

mock 인증은 운영 차단

X-Mock-Mb-Id는 명시적 전체 mock에서만 허용하고, 하나라도 live면 자동 거부합니다.

부분 성공 처리

배치 전체 ok와 별개로 sent 배열의 각 항목 ok/error를 확인해 성공 건만 발송합니다.

토큰은 비밀값

token/link를 화면 로그·분석도구·오류 메시지에 불필요하게 기록하지 않습니다.

중복 클릭 방지

버튼 로딩 처리와 서버 멱등성 정책을 적용하고 최신 링크 하나만 사용합니다.

6. 남은 엘피스 작업

핵심 구현은 한 묶음입니다

불일치 행에 [통관정보 요청] 버튼 추가
버튼 클릭 시 엘피스 백엔드에서 send API 호출
성공 항목의 token을 #{토큰}에 넣어 솔라피 알림톡 발송
운영 인증 방식(API Key 또는 HMAC)과 테스트 일정을 우리 쪽과 확정