퀵서비스 API 연동 가이드: 한 번 붙여 여러 업체 최저가로 자동 접수

하루 퀵 주문이 몇 건이면 사람이 접수해도 괜찮습니다. 수십 건이 되면 이야기가 달라집니다. 운영자가 자사 주문서를 열어 주소와 연락처를 읽고, 퀵 업체 화면에 다시 옮겨 적고, 배송이 끝났는지 전화로 확인하는 시간이 매일 쌓입니다.

퀵서비스 API는 이 옮겨 적기를 없애는 방법입니다. 다만 붙이는 방식에 따라 얻는 게 꽤 다릅니다. 이 글은 무엇이 달라지는지와 어디서부터 시작하면 되는지를 정리합니다. 싼퀵은 이 흐름을 REST API로 제공하며, 자세한 사항은 개발자센터에서 확인할 수 있습니다.

API를 이용해야 하는 이유

이미 주문 시스템을 쓰고 있다면 퀵 접수에 필요한 정보는 전부 그 안에 있습니다. 그런데 사람이 그걸 읽어 업체 화면에 다시 칩니다. 이 한 단계 때문에 비용이 세 갈래로 붙습니다.

첫째, 사람 시간이 매일 나갑니다

주문 한 건을 옮겨 적는 데 2~3분이 걸린다고 해봅시다. 하루 30건이면 한 시간이 넘습니다. 주문이 몰리는 시간대에 이 작업이 겹치면 접수 자체가 뒤로 밀립니다. API로 보내면 이 시간이 0에 수렴합니다.

둘째, 옮겨 적는 만큼 오타가 납니다

주소와 연락처를 다시 타이핑하는 순간 오타 가능성이 생깁니다. 동·호수 한 자리가 틀리면 기사가 현장에서 전화를 겁니다. 잘못 간 배송은 회수 비용까지 따라붙습니다. 자사 데이터를 그대로 전송하면 이 오차가 사라집니다.

셋째, 배송 상태를 사람이 확인합니다

손으로 접수하면 상태도 손으로 확인해야 합니다. 고객이 "지금 어디쯤인가요"라고 물을 때 담당자가 업체 화면을 다시 열어야 한다면 그만큼 응대가 늦어집니다. 웹훅을 받으면 상태 변화가 자사 시스템에 먼저 들어옵니다.

싼퀵 API를 연동해야 하는 이유

퀵 API는 배송업체가 직접 제공하기도 합니다. 그 길로 가면 업체 하나를 붙이는 것으로 끝나지 않습니다. 싼퀵을 고르는 이유는 한 번 붙여 여러 업체를 쓰게 된다는 점에 있습니다.

계약도 연동도 한 번이면 됩니다

업체마다 직접 연동하면 업체를 늘릴 때마다 계약을 맺고 인증·상태값·오류 처리를 새로 구현해야 합니다. 싼퀵은 한 곳과 계약하고 한 번 연동합니다. 그 뒤로는 여러 주요 업체가 한 창구로 들어옵니다.

요금 비교를 만들지 않아도 됩니다

업체별로 붙였다면 어디가 싼지 알기 위해 여러 곳을 동시에 호출하고 응답을 모아 정렬하는 코드를 직접 짜야 합니다. 싼퀵은 견적 응답이 이미 비교된 상태로 옵니다. 비교가 기능이 아니라 기본값입니다.

업체가 바뀌어도 자사 코드는 그대로입니다

업체가 추가되거나 빠져도 연동 코드를 고치지 않습니다. 상태값과 오류 규격이 하나로 통일돼 있어 업체별 예외 처리도 없습니다. 자사 화면 문구는 한 번만 맞춰두면 됩니다.

요청 한 번에 여러 업체 가격, 접수는 최저가로

앞의 이유가 실제로 어떻게 돌아가는지 보겠습니다. 견적을 한 번 요청하면 여러 주요 업체 가격이 한꺼번에 돌아오고, 주문은 그중 가장 싼 곳으로 접수됩니다.

견적은 비교된 상태로 온다

출발지와 도착지를 보내면 응답에 업체별 견적이 금액이 낮은 순으로 담겨 옵니다. 각 항목에는 서비스 유형과 금액, 예상 소요 시간이 들어 있습니다. 같은 구간이라도 업체별로 금액이 갈리는데, 요금 차이가 왜 생기는지는 가격비교가 필수인 이유에 정리되어 있습니다.

주문은 업체를 고르지 않는다

주문 요청에 배송업체를 지정하는 값이 없습니다. 이코노미·일반·급송 중 서비스 유형만 고르면, 그 시점 해당 유형의 최저가 업체로 접수됩니다. 어느 업체가 쌀지 자사 시스템이 판단하지 않아도 됩니다.

접수가 실패해도 주문이 멈추지 않는다

배차 실패, 업체 취소, 기사 배정 지연이 생기면 자동 라우팅(업체전환)이 다음 순위 업체로 다시 접수합니다. 대시보드 설정에서 켜고 끌 수 있습니다. 새 요금이 더 높으면 차액이 등록 카드로 추가 결제되고, 옮길 곳이 없으면 자동 취소와 전액 환불로 끝납니다.

금액은 주문 응답을 기준으로 보세요

견적 조회 금액과 실제 결제 금액은 다를 수 있습니다. 견적과 주문 사이에 요금이 바뀔 수 있어서입니다. 확정 금액은 주문 응답에 담겨 오고, 그 금액이 그대로 결제되며 결제 단계에서 별도 수수료가 더해지지 않습니다.

연동하면 쓰게 되는 것들

붙여야 할 것은 많지 않습니다. 네 가지면 접수부터 종료까지 돕니다.

견적 조회와 주문 생성

견적으로 금액을 확인하고 주문으로 접수합니다. 자사 주문번호를 함께 보내면 같은 번호로 다시 요청해도 중복 접수가 생기지 않습니다. 네트워크 오류로 재시도하는 경우를 그대로 처리할 수 있습니다.

취소와 환불

취소 전에 수수료와 환불 예정 금액을 먼저 조회할 수 있습니다. 취소할 수 없는 구간이면 조회 결과가 그 사실을 알려줍니다. 화면에 취소 버튼을 항상 열어두는 대신, 이 결과로 버튼 상태를 정하는 편이 낫습니다. 수수료 기준은 취소·환불 수수료 가이드에 정리되어 있습니다.

배송 상태 웹훅

상태를 반복 조회하는 대신 서버가 알림을 받습니다. 기사 배정, 기사 재배정, 픽업 완료, 배송 완료, 주문 취소 다섯 가지가 옵니다. 업체가 어디든 같은 규격으로 들어오므로 자사 화면 문구를 한 번만 맞춰두면 됩니다.

온보딩은 세 단계

연동은 테스트 환경에서 끝낸 다음 운영으로 올립니다. 신청서를 먼저 내고 기다리는 순서가 아닙니다.

1. 테스트 키 발급

대시보드 API 메뉴에서 발급합니다. 이메일 인증을 마친 회원이면 별도 승인 없이 바로 받을 수 있습니다. 주문까지 시험하려면 테스트 결제 카드를 함께 등록합니다.

2. 테스트 환경에서 검증

결제·기사 배정·배송·취소·환불이 모두 가상으로 처리됩니다. 실제 카드 청구나 기사 접수는 일어나지 않습니다. 반면 웹훅은 등록한 주소로 실제 전송되므로 수신 서버를 그대로 검증할 수 있습니다. 테스트 주문과 내역은 7일간 보관하며 운영으로 넘어가지 않습니다.

3. 운영 사용 신청

대시보드에서 신청하면 검토 후 운영 키를 발급합니다. 주소와 키만 바꾸면 되고 요청·응답 규격은 테스트와 같습니다. 운영 카드를 미리 등록해 두세요.

자주 묻는 질문 (FAQ)

정리

퀵 접수를 사람이 옮겨 적는 구조는 물량이 늘수록 비싸집니다. 퀵서비스 API를 붙이면 그 단계가 사라지는데, 어떻게 붙이느냐에 따라 남는 일의 양이 다릅니다. 업체마다 계약하고 비교 로직을 직접 만드는 대신, 한 번 연동해 비교된 견적을 받고 최저가로 접수하는 쪽이 운영 부담이 적습니다.

• 연동 한 번: 여러 주요 업체를 한 번에
• 견적: 금액이 낮은 순으로 정렬돼 응답
• 주문: 서비스 유형만 고르면 최저가 업체로 접수
• 실패 대응: 자동 라우팅으로 다음 업체 재접수
• 온보딩: 테스트 키 발급 → 연동 검증 → 운영 신청