그린퀵Developers· 거래처 API
시험 키 신청· 1588-2824

GreenQuick Partner API v1 · 2026-11-16

ERP에서 바로,
퀵이 출발합니다

귀사 시스템이 사람 손을 거치지 않고 퀵을 접수하고, 배차·픽업·완료까지 받아 갑니다. 지금 이 페이지에서 바로 눌러 보세요.

8개엔드포인트
5개 언어예제 코드 자동 생성
10분시험 키로 접수→완료 연습
POST /api/v1/orders
curl -sS --max-time 60 -X POST "https://greenquick.ai/api/v1/orders" \
  -H "Authorization: Bearer $GQ_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "PO-2026-10-000123",
    "requester": { "phone": "010-0000-0001" },
    "pickup":  { "name": "가나상사", "phone": "02-0000-0000",
                 "address": "서울특별시 중구 세종대로 110", "address_detail": "3층" },
    "dropoff": { "name": "다라마 물류", "phone": "031-000-0000",
                 "address": "경기도 성남시 중원구 성남대로 997", "address_detail": "1층" },
    "schedule": { "type": "standard" },
    "vehicle":  { "type": "motorcycle" },
    "items":    { "packages": { "document": true } }
  }'

# 201 → { "error": 0, "data": { "id": "ord_9QF2…", "status": "received", … }, "request_id": "req_…" }
접수 확인 중배차 시스템에 들어갔어요
보통 1~2초접수 응답 · 타임아웃은 60초로 잡아 주세요
약 2분마다상태 갱신
하루 접수 한도 없음분당·동시 처리 한도만 있어요
두 번 접수 걱정 없음Idempotency-Key로 안전하게 다시 보내기

연동 미리보기

귀사 ERP에 붙이면, 이렇게 됩니다

예시 회사 '가나상사'의 그룹웨어 화면입니다. [그린퀵으로 퀵 요청]을 눌러 보세요. 진행 상황, 귀사 서버와 그린퀵 API가 주고받는 호출, 접수 담당자 휴대폰 알림톡이 함께 움직입니다. 시험 키 10분 시나리오를 빠르게 재생합니다.

가나상사 그룹웨어 — 퀵 요청 (예시 화면)

퀵 배송 요청

그린퀵 API 연동
—
요청하면 여기서 진행이 보여요

접수 → 배차 → 픽업 → 완료가
그린퀵 API 로 자동으로 들어옵니다.

퀵 요청
저장
접수
배차 대기
기사 배정
배송 중
완료
출발 · 시청 도착 · 성남
배정 대기
기사님을 찾고 있어요
연락처—
확인 시각—
요금—
귀사 서버 ↔ 그린퀵 API빠르게 보여 주려고 자주 부릅니다 · 실제는 목록 5~10분
  1. // 버튼을 누르면 귀사 서버 ↔ 그린퀵 API 호출이 여기에 찍힙니다
카카오톡 · 홍길동 휴대폰
재생 속도
시험 키 10분 시나리오를 빠르게 보여 드려요

API 체험

키 없이, 지금 바로 불러 보세요

본문을 고쳐 보내면 실제 API와 같은 모양의 응답이 옵니다. 아래 예제 코드는 cURL·Node.js·Python·Java·PHP로 바로 바뀝니다. 체험용 가상 서버라 실제 오더는 만들어지지 않습니다.

헤더
본문 (JSON) — 고쳐서 보내 보세요
체험용 가상 서버 · 실제 오더 없음

01개요와 흐름

그린퀵 연동 API는 귀사 서버가 사람 손을 거치지 않고 퀵 배송을 접수하고, 진행 상황을 받아 가는 HTTPS·JSON API입니다.

기본 주소: https://greenquick.ai/api/v1 (이 주소 하나만 씁니다)

1-1할 수 있는 일

기능 주소 필요한 권한
연결 확인 GET/ping (유효한 키)
값표·칸 길이·청구 계정 GET/reference (유효한 키)
예상 요금 POST/quotes orders:write
오더 접수 POST/orders orders:write
오더 목록 GET/orders orders:read
오더 상세 GET/orders/{id} orders:read
배송 추적 GET/orders/{id}/tracking orders:track
오더 취소 POST/orders/{id}/cancel orders:cancel

v1에 없는 것

  • 접수할 때 카드로 바로 결제하는 온라인 결제(카드 결제 오더로 접수하는 것은 됩니다. 2-6), 정기 오더, 여러 건 한꺼번에 접수, 물품 사진, 왕복·경유
  • 접수한 오더 고치기(배차 시스템에 들어가기 전이면 취소하고 새 번호로 다시 접수합니다)
  • 배차 시스템에 들어간 뒤의 API 취소(고객센터 1588-2824 전화로 합니다)
  • 웹·전화로 접수한 오더 조회(API로 접수한 오더만 보입니다)
  • 상태 변경 알림(웹훅): v1.1에서 제공할 예정입니다. 그때까지는 주기 조회(9장)를 씁니다.
  • 브라우저·모바일 앱에서 직접 호출(CORS 미지원). 반드시 귀사 서버에서 부릅니다.

1-2전체 흐름

순서 귀사 ERP가 하는 일 그린퀵이 하는 일 결과
1 (선택) POST/quotes로 예상 요금을 묻습니다 주소 위치를 찾고 요금표로 계산합니다 예상 요금
2 POST/orders로 접수합니다(Idempotency-Key 필수) 저장한 뒤 바로 배차 시스템으로 보냅니다(운영 키) 201 + 오더 id, 보통 dispatch_no까지
3 5~10분마다 GET/orders?updated_since=…로 바뀐 오더를 가져옵니다 배차 시스템 상태를 약 2분 간격으로 가져와 반영합니다 상태·기사·요금
4 필요할 때 GET/orders/{id}, GET/orders/{id}/tracking을 부릅니다 저장된 값을 돌려줍니다(배차 시스템을 따로 부르지 않음) 상세·추적
5 취소: 배차 시스템에 들어가기 전이면 POST/orders/{id}/cancel, 그 뒤는 고객센터 1588-2824 보내기 전 오더만 API로 취소합니다 cancelled
6 월 정산 대조: GET/orders?completed_from=…&completed_to=… 완료 오더와 요금을 돌려줍니다 정산 자료

1-3확정된 기본 규칙

  • 키로 볼 수 있는 것은 귀사가 API로 접수한 오더뿐입니다. 그 안에서 키마다 범위를 정합니다(2-5).
  • API 오더는 키의 기본 청구 계정으로 접수·청구됩니다. 부서별 청구를 허락받은 키만 billing_account로 다른 계정을 고릅니다.
  • 요금을 계산할 수 없는 경우(밴, 요금표 밖)에도 접수는 됩니다. 이때 price.estimated는 null이고, 요금은 콜센터가 정합니다.
  • 위치를 정확히 찾지 못하는 주소는 받지 않습니다. 대충 비슷한 곳으로 받으면 기사가 엉뚱한 곳으로 가기 때문입니다.
  • API로 넣은 오더는 그린퀵 웹 화면 오더 내역에도 (API) 표시로 보입니다. 다만 웹에서는 보기만 되고, 고치기·취소는 API나 전화로 합니다.
  • 운영 키는 허용 IP 등록이 필수입니다.
  • 하루 접수 건수 한도는 없습니다. 분당 호출 한도, 동시 처리 한도, 서버 앞단 한도(같은 IP 초당 10회 등)만 있습니다(7장).
  • 결제 방법은 귀사 총괄관리자가 그린퀵 사이트 API 설정 화면에서, 알림톡은 알림 설정 화면에서 정합니다(2-6).
  • 요금은 기본으로 예상 요금과 실제(확정) 요금을 모두 드립니다. 기사가 배정되면 기사 이름·차량번호·전화도 드립니다(배송 확인에만 쓰세요, 11장). 기사 위치는 지금 드리지 않습니다(3-7). 다른 배차망에서 배정된 오더는 기사 대신 그린퀵 고객센터 번호를 드립니다(3-7).

02시작하기

2-1연동 신청

그린퀵에 아래 내용을 알려 주세요.

  • 회사명, 담당 개발자 이름·연락처·메일(장애·점검 공지를 받을 주소)
  • 호출할 서버의 고정 IPv4 주소(운영 키는 필수, 최대 10개, CIDR /8~/32 가능)
  • 청구 계정(부서별 청구를 쓰는 경우)
  • 키 하나로 볼 오더 범위(2-5)
  • 귀사에 그린퀵 사이트 총괄관리자 계정이 있어야 합니다. 키는 이 계정으로만 받습니다.

API 연동 상담: 1588-2824 (10:00~16:00) — 전화하셔서 '개발 담당자'를 찾아 주세요.

운영 키는 상담 뒤 그린퀵 담당자가 발급합니다. 시험 키로 하는 연동 시험은 운영 키 없이도 할 수 있습니다.

2-2키 받는 법

  1. 그린퀵이 귀사 총괄관리자에게 1회용 수령 링크를 보냅니다.
  2. 총괄관리자 계정으로 그린퀵 사이트에 로그인합니다.
  3. 링크를 열고 [키 만들기]를 누릅니다.
  4. 키가 화면에 한 번만 보입니다. 바로 비밀 저장소에 넣으세요.
  • 링크는 24시간 안에 한 번만 쓸 수 있습니다. 만료됐거나 이미 썼으면 새 링크를 요청하세요.
  • 그린퀵 직원도 키를 볼 수 없습니다. 그린퀵도 키 원문을 갖고 있지 않아서, 잃어버리면 새로 발급합니다.
  • 직접 받지 않은 키 링크가 왔다면 바로 1588-2824로 알려 주세요.
  • 운영 키도 시험 키와 같이 귀사 총괄관리자에게 1회용 수령 링크로 드립니다. 운영 키는 허용 IP(귀사 서버 IP) 등록이 필수입니다(2-1).

2-3시험 키와 운영 키

구분 시험 키 gqk_test_… 운영 키 gqk_live_…
오더가 가는 곳 배차 시스템으로 가지 않습니다(가짜 진행) 실제 배차 시스템으로 갑니다
주소 확인·예상 요금 실제로 계산합니다 실제로 계산합니다
상태 변화 접수 뒤 정해진 시간표대로 저절로 바뀝니다(8장) 실제 배차 진행을 따라갑니다
취소 접수 뒤 1분 안에만 됩니다 배차 시스템에 들어가기 전만 됩니다(대부분 안 됨, 5장)
호출 한도 운영의 1/4(7장) 기본값(7장)
허용 IP 선택 필수
볼 수 있는 오더 시험 오더만 운영 오더만
발급 연동 신청 뒤 받습니다(2-1) 상담 뒤 그린퀵 담당자가 발급합니다. 그린퀵이 사용을 열기 전에는 503 api_disabled

먼저 시험 키로 연동을 끝내고, 10장의 점검표를 확인한 뒤 운영 키로 바꿔 끼웁니다.

2-4키 보관과 교체

  • 키는 서버의 환경변수나 비밀 저장소에만 둡니다.
  • 소스 저장소, 웹 페이지, 앱, 로그, 메일, 메신저에 넣지 마세요.
  • 키ID(키의 gqk_test_·gqk_live_ 바로 뒤 12자, GET/ping의 key.id)는 비밀이 아닙니다. 문의할 때는 키ID만 알려 주세요.
  • 교체 순서: 그린퀵이 새 수령 링크를 보냄 → 귀사 서버에 새 키를 넣음 → 그린퀵에 옛 키 폐기를 요청(요청이 없으면 7일 뒤 자동 만료).
  • 한 회사에 동시에 쓸 수 있는 키는 시험·운영 각각 최대 2개입니다.
  • 폐기·정지는 1분 안에 적용됩니다.
  • '이 키로 접수한 오더만' 범위의 키는 교체하면 옛 오더가 새 키로 보이지 않습니다. 이때는 새 키를 따로 받고, 옛 오더가 끝난 뒤 옛 키를 폐기합니다.
  • 올바른 운영 키가 등록하지 않은 IP에서 쓰이면 403 ip_not_allowed가 나고, 그린퀵은 키가 샌 것으로 봅니다. 그때부터 귀사의 새 운영 접수는 그린퀵 담당자가 확인한 뒤 배차 시스템으로 보냅니다(received + awaiting_review). 이때는 그린퀵에 연락해 키를 교체하세요.

2-5볼 수 있는 오더 범위

키로 볼 수 있는 것은 귀사가 API로 접수한 오더뿐입니다. 그 안에서 범위를 키마다 정합니다.

범위(read_scope) 볼 수 있는 오더
billing_accounts(기본) 이 키에 허용된 청구 계정으로 접수된 API 오더. 같은 회사의 다른 키가 같은 청구 계정으로 넣은 오더 포함
own_key 이 키로 접수한 오더만. 귀사가 일을 맡긴 개발사나 물류 대행사에 줄 키에 권합니다
company 귀사의 모든 API 오더. 총괄관리자의 서면 요청이 있을 때만
  • 범위 밖 오더는 번호를 알아도 404 not_found입니다. 있다·없다도 알려 주지 않습니다.
  • 요청에 회사 번호나 청구 계정을 넣어 범위를 넓힐 수 없습니다. 키가 곧 회사이고 범위입니다.
  • 청구 계정 허용 목록은 GET/ping과 GET/reference의 billing_accounts에 나옵니다. 맨 앞(default: true)이 기본 계정입니다.

2-6API 설정 화면

귀사 사이트 총괄관리자는 그린퀵 사이트에 회사 총괄관리자 계정으로 로그인한 뒤 API 설정 화면(https://greenquick.ai/gq_api/settings)에서 결제 방법을 직접 정할 수 있습니다. 알림톡은 같은 계정으로 알림 설정 화면에서 정합니다(아래 '알림톡 설정'). 이 화면의 귀사 키 목록(이름·키ID·끝 4자리·시험/운영·상태)은 보기만 됩니다. 키 발급·교체·폐기는 그린퀵에 요청하세요. 총괄관리자가 아닌 계정은 바꿀 수 없습니다. 그린퀵 담당 직원에게 요청해 바꿀 수도 있습니다. 설정은 회사 단위라 귀사의 모든 키에 함께 적용됩니다. 시험 오더에는 알림톡이 가지 않습니다(결제 방법 설정은 시험 키에도 적용).

설정 고를 수 있는 것 처음 값
API 결제 방법 credit 신용(월 정산), bank_transfer 무통장입금, card 카드, cash_on_pickup 출발지 현금, cash_on_delivery 도착지 현금 — 각각 켜고 끔(하나 이상은 켜 두어야 함) credit·bank_transfer·card 켜짐
알림톡 이 화면에서는 바꾸지 않습니다. 지금 설정 한 줄과 알림 설정 화면으로 가는 링크만 보입니다(아래 '알림톡 설정') —
  • card는 접수할 때 결제하지 않습니다. 배차 시스템에 카드 결제 오더로 등록되고, 카드 결제는 그린퀵 안내에 따라 따로 진행합니다. API에는 카드 번호 같은 결제 정보를 보내지 마세요.
  • 꺼 둔 결제 방법으로 접수하면 422 payment_method_not_allowed입니다. 설정을 바꾼 뒤에는 GET/ping의 payment_methods로 반영됐는지 확인하세요.
  • credit을 끈 경우에는 접수 본문에 payment.method를 꼭 넣으세요. 빼면 credit으로 보아 422가 납니다.
  • 알림톡 설정: 알림톡은 API 설정 화면이 아니라 '(귀사 이름) 관리 → 알림 설정' 화면(https://greenquick.ai/order/client_notify, 회사 총괄관리자 계정으로 로그인)에서 정합니다. 회사 단위라 귀사의 웹·전화·API 오더에 함께 적용됩니다.
  • 접수 담당자(API 오더는 requester.phone으로): 접수 · 배차 · 출발(픽업) · 완료 중에서 고릅니다. 처음 값은 접수·출발·완료입니다. 배차 알림에는 기사 이름·연락처·차종이 들어가고, 귀사가 골랐을 때만 갑니다(기사가 바뀌면 '기사 변경' 알림 1통이 더 갑니다).
  • 받는 분(dropoff.phone으로): 출발(픽업) 알림을 '보내기'·'보내지 않기' 중에서 고릅니다. 처음 값은 보내기입니다.
  • 취소 알림톡은 어느 회사에도 보내지 않습니다. 취소는 GET/orders/{id}나 목록 조회(cancelled)로 확인하세요.
  • 같이 받을 사람(notify_cc): 접수 본문 notify_cc에 010 휴대폰 번호를 3개까지 적으면 그 오더의 배차(기사 이름·연락처·차종)·출발(픽업)·완료 알림톡이 그 번호에도 갑니다(접수 알림은 requester.phone만). 알림 설정과 상관없이 적은 오더에만 가고, requester.phone과 같은 번호는 한 통만 갑니다. 그린퀵이 이 기능을 연 뒤부터 보냅니다(열기 전에는 받아도 저장·발송하지 않습니다).
  • 알림톡은 그린퀵 이름의 카카오 알림톡입니다. 배차·출발·완료 알림에는 배송현황 링크가 들어갑니다(링크 화면에 보이는 것은 11장).
  • 받는 분 알림톡 본문에는 접수 담당자 이름·출발지 상호·물품·배송 수단·하차 방법·도착지 담당자 이름이 들어갑니다(11장). 받는 분에게 이 내용을 보내지 않으려면 알림 설정 화면에서 받는 분 알림을 '보내지 않기'로 고르세요(귀사 웹 오더에도 함께 적용됩니다).
  • 이 화면에서 바꿀 수 없는 것(키 발급·폐기, 허용 IP, 키 권한, 볼 수 있는 오더 범위, 청구 계정)은 그린퀵에 요청하세요.

03curl 빠른 시작

시험 키로 따라 해 봅니다. 30분이면 첫 접수까지 갈 수 있습니다.

먼저 알아 둘 것

  • -L(리다이렉트 따라가기)을 쓰지 마세요. 다른 주소로 넘어가면서 키가 함께 보내질 수 있습니다.
  • --max-time 60으로 타임아웃을 60초로 둡니다. 접수는 길면 약 55초까지 걸릴 수 있습니다.
  • -i를 붙이면 응답 헤더(X-Request-Id, X-RateLimit-*)도 보입니다.
  • 시험 키는 접수가 분당 15회, 동시 처리가 1개입니다. 명령을 하나씩 보내세요(앞 명령의 응답을 받은 뒤 다음 명령).
  • Windows PowerShell에서는 curl 대신 curl.exe를 쓰고, JSON 본문은 꼭 파일로 보내세요(따옴표가 깨집니다). 파일은 BOM 없는 UTF-8로 저장합니다. BOM이 붙으면 400 invalid_json이 납니다.

3-0키를 환경변수에 두기

Shell · curl
# Linux·macOS
export GQ_KEY='gqk_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
export GQ=https://greenquick.ai/api/v1
PowerShell
# Windows PowerShell
$env:GQ_KEY = 'gqk_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
$GQ = 'https://greenquick.ai/api/v1'

3-1연결 확인 GET/ping

Shell · curl
curl -sS --max-time 60 -i "$GQ/ping" -H "Authorization: Bearer $GQ_KEY"

응답 헤더(일부):

Text
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
X-Request-Id: req_5b1e0c7a9d2f
X-Api-Version: 1.0.0
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14
X-RateLimit-Reset: 37

응답 본문:

JSON
{
  "error": 0,
  "message": "success",
  "data": {
    "company": "가나상사",
    "key": {
      "id": "7d3k6m2q4x5p",
      "name": "ERP 시험",
      "env": "test",
      "scopes": ["orders:read", "orders:track", "orders:write", "orders:cancel"],
      "read_scope": "billing_accounts",
      "expires_at": null
    },
    "billing_accounts": [ { "code": "71400001", "name": "가나상사.API", "default": true } ],
    "payment_methods": ["credit", "bank_transfer", "card"],
    "server_time": "2026-10-09T10:00:00+09:00",
    "api_version": "1.0.0"
  },
  "request_id": "req_5b1e0c7a9d2f"
}

확인할 것: key.env가 test인지, billing_accounts에 귀사 청구 계정이 있는지, payment_methods에 쓸 결제 방법이 있는지(없으면 총괄관리자가 2-6 설정에서 켭니다).

3-2값표 받기 GET/reference

Shell · curl
curl -sS --max-time 60 "$GQ/reference" -H "Authorization: Bearer $GQ_KEY"

응답 본문(일부만 보입니다):

JSON
{
  "error": 0,
  "message": "success",
  "data": {
    "vehicles": [
      { "value": "motorcycle", "label": "오토바이", "quote_available": true },
      { "value": "van", "label": "밴", "quote_available": false }
    ],
    "truck_bodies": [
      { "value": "canvas", "label": "호루", "truck_tons": ["1t", "1.4t"] }
    ],
    "payment_methods": [
      { "value": "credit", "label": "신용(월 정산)", "allowed": true },
      { "value": "bank_transfer", "label": "무통장입금", "allowed": true },
      { "value": "card", "label": "카드", "allowed": true, "note": "접수 때 결제하지 않습니다. 배차 시스템에 카드 결제로 등록됩니다." },
      { "value": "cash_on_pickup", "label": "출발지 현금", "allowed": false },
      { "value": "cash_on_delivery", "label": "도착지 현금", "allowed": false }
    ],
    "field_limits": { "external_ref": 64, "requester.name": 20, "pickup.address": 300, "request_note": 100, "memo": 500 },
    "billing_accounts": [ { "code": "71400001", "name": "가나상사.API", "default": true } ],
    "reservation_window": { "min_minutes_ahead": 30, "max_days_ahead": 7 }
  },
  "request_id": "req_6c2f1d8b0a3e"
}

값표는 하루 한 번 정도 받아 두면 됩니다. 전체 칸은 명세 파일에 있습니다.

3-3예상 요금 POST/quotes

quote.json 파일:

JSON
{
  "pickup":  { "address": "서울특별시 중구 세종대로 110" },
  "dropoff": { "address": "경기도 성남시 중원구 성남대로 997" },
  "schedule": { "type": "urgent" },
  "vehicle": { "type": "motorcycle" }
}
Shell · curl
curl -sS --max-time 60 "$GQ/quotes" \
  -H "Authorization: Bearer $GQ_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @quote.json

응답:

JSON
{
  "error": 0,
  "message": "success",
  "data": {
    "currency": "KRW",
    "estimated": { "basic": 18000, "surcharge": 5000, "total": 23000 },
    "notes": ["예상 요금입니다. 최종 요금은 배송이 끝난 뒤 확정됩니다."],
    "valid_until": "2026-10-09T10:30:00+09:00"
  },
  "request_id": "req_1f4a7c9e2b6d"
}
  • basic에는 기본 요금, 악천후 할증(예보 기준), 카고가 아닌 트럭 할증이 들어 있습니다. surcharge는 급송 추가 요금과 밤 할증입니다.
  • 밤 시간(20:00~08:00)에는 웹 접수와 같이 요금이 1.5배입니다(천 원 단위 올림). 늘어난 만큼은 surcharge에 더하고 notes에 적습니다. 예약은 픽업 시각, 그 밖은 요청한 시각으로 봅니다. 그래서 예약이 아닌 견적은 30분 안에 밤 시작·끝(20:00·08:00)이 오면 valid_until을 그 앞까지로 줄이고 notes에 적습니다. 접수 요금은 접수한 시각으로 다시 계산합니다.
  • 고속버스 탁송(schedule.type linked, linked_mode bus)은 오토바이 65,000원, 다마스 80,000원으로 정한 요금입니다(거리·날씨와 관계없음, 밤에는 1.5배). 고속버스 탁송료는 따로입니다. 라보·트럭과 KTX·항공 연계는 거리 요금입니다.
  • 밴은 요금표가 없어 422 quote_unavailable입니다.
  • 기본으로 모든 회사에 예상 요금을 드립니다. 계약에서 예상 요금을 드리지 않기로 한 회사는 403 insufficient_scope입니다.
  • 예상 요금은 참고용입니다. 접수하면 이 값이 배송 요금의 첫 값으로 배차 시스템에 등록되고, 콜센터가 거리·대기·계약 단가에 따라 조정할 수 있습니다. 최종 요금은 오더의 price.charged(확정되면 price.status가 confirmed)로 확인하세요.

3-4오더 접수 POST/orders

order.json 파일:

JSON
{
  "external_ref": "PO-2026-10-000123",
  "requester": { "name": "홍길동", "department": "구매팀", "phone": "010-0000-0001" },
  "pickup": {
    "name": "가나상사 본사", "contact_name": "김담당", "phone": "02-0000-0000",
    "address": "서울특별시 중구 세종대로 110", "address_detail": "3층 총무팀"
  },
  "dropoff": {
    "name": "다라마 물류센터", "contact_name": "이수령", "phone": "031-000-0000",
    "address": "경기도 성남시 중원구 성남대로 997", "address_detail": "B동 1층 입고장"
  },
  "schedule": { "type": "standard" },
  "vehicle": { "type": "motorcycle" },
  "items": { "packages": { "document": true, "small_box": 2 } },
  "payment": { "method": "credit" },
  "request_note": "도착 10분 전 전화 부탁드립니다",
  "memo": "ERP 결재번호 A-778"
}
Shell · curl
# Linux·macOS — 요청마다 새 Idempotency-Key를 만들고, ERP에 external_ref와 함께 저장해 둡니다
IDEM=$(uuidgen)
curl -sS --max-time 60 -i "$GQ/orders" \
  -H "Authorization: Bearer $GQ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  --data-binary @order.json
PowerShell
# Windows PowerShell
$idem = [guid]::NewGuid().ToString()
curl.exe -sS --max-time 60 -i "$GQ/orders" -H "Authorization: Bearer $env:GQ_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $idem" --data-binary "@order.json"

응답 201(시험 키, 접수 직후):

JSON
{
  "error": 0,
  "message": "success",
  "data": {
    "id": "ord_9QF2M7KD4T1XHB6RZC8PWA",
    "external_ref": "PO-2026-10-000123",
    "env": "test",
    "status": "received",
    "status_label": "접수됨(전송 대기)",
    "status_reason": null,
    "dispatch_no": null,
    "billing_account": { "code": "71400001", "name": "가나상사.API" },
    "created_at": "2026-10-09T10:15:02+09:00",
    "transferred_at": null,
    "picked_up_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "updated_at": "2026-10-09T10:15:02+09:00",
    "requester": { "name": "홍길동", "department": "구매팀", "phone": "010-0000-0001", "company": "가나상사" },
    "pickup": {
      "name": "가나상사 본사", "department": null, "contact_name": "김담당", "phone": "02-0000-0000",
      "address": "서울특별시 중구 세종대로 110", "address_detail": "3층 총무팀", "jibun_address": null, "zonecode": null
    },
    "dropoff": {
      "name": "다라마 물류센터", "department": null, "contact_name": "이수령", "phone": "031-000-0000",
      "address": "경기도 성남시 중원구 성남대로 997", "address_detail": "B동 1층 입고장", "jibun_address": null, "zonecode": null
    },
    "schedule": { "type": "standard", "reserved_at": null, "linked_mode": null },
    "vehicle": { "type": "motorcycle", "only_this_vehicle": false },
    "items": { "packages": { "document": true, "small_box": 2 }, "description": null, "fragile": false },
    "handling": { "place": null, "carry_level": null, "loading": null, "unloading": null, "ride_along": false },
    "payment": { "method": "credit", "payer": "requester" },
    "request_note": "도착 10분 전 전화 부탁드립니다",
    "memo": "ERP 결재번호 A-778",
    "price": {
      "currency": "KRW",
      "status": "estimated",
      "estimated": { "basic": 18000, "surcharge": 0, "total": 18000 },
      "charged": null
    },
    "driver": null
  },
  "request_id": "req_5b1e0c7a9d2f"
}
  • id는 이후 모든 호출에 씁니다. ERP에 external_ref와 함께 저장하세요. 드물게 저장 직후 오더를 다시 읽지 못하면 201의 data에 id·status(received)·status_label·note 네 칸만 옵니다. 이때도 접수는 저장된 것이니 다시 접수하지 말고 GET/orders/{id}로 나머지 칸을 가져오세요.
  • 운영 키로 접수하면 보통 응답이 이미 "status": "waiting", "dispatch_no": "280001234"(배차 시스템 접수번호), transferred_at이 채워진 모양입니다. 그 밖의 경우는 5-3 표를 보세요.
  • 응답을 못 받았으면 같은 Idempotency-Key, 같은 본문으로 다시 보냅니다. 오더가 두 번 만들어지지 않고 처음 결과(201)가 옵니다.

3-5오더 상세 GET/orders/{id}

Shell · curl
curl -sS --max-time 60 "$GQ/orders/ord_9QF2M7KD4T1XHB6RZC8PWA" -H "Authorization: Bearer $GQ_KEY"

접수 8분 뒤(시험 키, 배송 중) 응답의 달라진 칸:

JSON
{
  "status": "in_transit",
  "status_label": "배송 중",
  "dispatch_no": "TEST00000123",
  "transferred_at": "2026-10-09T10:16:02+09:00",
  "picked_up_at": "2026-10-09T10:23:02+09:00",
  "updated_at": "2026-10-09T10:23:02+09:00",
  "driver": { "name": "시험 기사", "vehicle_no": "00시0000", "phone": "010-0000-0000" }
}

나머지 칸은 접수 응답과 같은 모양입니다. driver 칸은 추적(3-7)과 같은 규칙입니다(다른 배차망에서 배정된 오더는 그린퀵 배송기사·1588-2824).

3-6바뀐 오더 목록 GET/orders?updated_since=…

Shell · curl
curl -sS --max-time 60 -G "$GQ/orders" \
  -H "Authorization: Bearer $GQ_KEY" \
  --data-urlencode "updated_since=2026-10-09T10:00:00+09:00" \
  --data-urlencode "page_size=100"

--data-urlencode가 +09:00의 +를 %2B로 바꿔 줍니다. 주소에 직접 쓸 때는 +를 %2B로 쓰세요.

응답:

JSON
{
  "error": 0,
  "message": "success",
  "data": [
    {
      "id": "ord_9QF2M7KD4T1XHB6RZC8PWA",
      "external_ref": "PO-2026-10-000123",
      "status": "in_transit",
      "status_label": "배송 중",
      "status_reason": null,
      "dispatch_no": "TEST00000123",
      "billing_account": { "code": "71400001" },
      "created_at": "2026-10-09T10:15:02+09:00",
      "delivered_at": null,
      "updated_at": "2026-10-09T10:23:02+09:00",
      "pickup": { "name": "가나상사 본사" },
      "dropoff": { "name": "다라마 물류센터" },
      "vehicle": { "type": "motorcycle" },
      "price": { "status": "estimated", "estimated_total": 18000, "charged_total": null }
    }
  ],
  "next_cursor": null,
  "request_id": "req_4e34fc0eaec5"
}

next_cursor가 null이 아니면 같은 조건에 cursor=그 값을 더해 다음 쪽을 가져옵니다.

3-7배송 추적 GET/orders/{id}/tracking

접수 5분 뒤(시험 키, 기사 배정):

Shell · curl
curl -sS --max-time 60 "$GQ/orders/ord_9QF2M7KD4T1XHB6RZC8PWA/tracking" -H "Authorization: Bearer $GQ_KEY"
JSON
{
  "error": 0,
  "message": "success",
  "data": {
    "order_id": "ord_9QF2M7KD4T1XHB6RZC8PWA",
    "status": "assigned",
    "driver": { "name": "시험 기사", "vehicle_no": "00시0000", "phone": "010-0000-0000" },
    "location": null,
    "path": [],
    "data_as_of": null
  },
  "request_id": "req_8ed7180b57e4"
}
  • 기사 위치는 지금 드리지 않습니다. location·path·data_as_of 는 지금 늘 null·[] 입니다(운영 오더·시험 오더 모두, 칸은 그대로 둡니다). 다시 제공하게 되면 미리 알려 드립니다.
  • 기사 배정 전, 완료 뒤, 취소 뒤에는 driver도 null입니다.
  • 같은 오더는 5분에 한 번 이하로 불러 주세요.
  • 기사 이름·차량번호·전화를 드립니다. 기사 개인정보이므로 배송 확인에만 쓰고 다른 곳에 넘기지 마세요(11장).
  • 기사 이름·전화는 그린퀵 웹 배송현황·알림톡과 같은 모양으로 다듬어 드립니다(이름은 사람 이름만, 전화는 010-0000-0000·02-000-0000·0507-0000-0000처럼 하이픈 넣은 번호. 휴대폰 번호만 받는 검사는 쓰지 마세요).
  • 다른 배차망에서 배정된 오더는 실제 기사 정보를 드리지 않습니다. 이때 driver는 { "name": "그린퀵 배송기사", "vehicle_no": null, "phone": "1588-2824" }(그린퀵 고객센터)입니다. 배차 시스템 값으로 이름·전화를 알 수 없을 때도 같은 이름·번호가 옵니다.

3-8취소 POST/orders/{id}/cancel

시험 오더는 접수 뒤 1분 안에만 취소됩니다. 그래서 새 오더 B를 하나 더 접수하고 곧바로 취소해 봅니다. (B의 external_ref와 Idempotency-Key는 새 값을 씁니다.)

Shell · curl
curl -sS --max-time 60 -X POST "$GQ/orders/ord_X4HCBWYYBSQ6Q7NL8L4755/cancel" \
  -H "Authorization: Bearer $GQ_KEY"

본문은 선택입니다. 이유를 남기려면 -H "Content-Type: application/json" --data-binary @cancel.json(내용 {"reason": "고객 요청"}, 100자 이하)을 붙입니다.

주소의 {id}에는 접수 응답의 id(ord_ + 22자)만 넣으세요. external_ref 같은 다른 값을 넣으면 404이고, 그 값에 영문·숫자·_ 밖의 글자(예: PO-2026-10-000123의 -)가 있으면 취소되지 않았는데도 200이 올 수 있습니다(6-1). 성공은 본문 error가 0이고 request_id가 있을 때만입니다.

응답 200(달라진 칸):

JSON
{
  "status": "cancelled",
  "status_label": "취소",
  "dispatch_no": null,
  "cancelled_at": "2026-10-09T10:17:40+09:00",
  "updated_at": "2026-10-09T10:17:40+09:00"
}

같은 취소를 다시 보내도 같은 결과(200)가 옵니다.

1분이 지난 A를 취소하면:

JSON
{
  "error": -1,
  "message": "지금 상태에서는 API로 취소할 수 없습니다. 1588-2824로 연락해 주세요.",
  "code": "cancel_not_allowed",
  "request_id": "req_f1c0c6ac0425"
}
그린퀵 취소 규정

언제 취소비가 생기나요?

무료기사 배정 전

또는 배정 후 5분 안이면서 기사가 픽업지 1km 밖. 다른 배차망에서 먼저 배정됐으면 고객센터가 확인해 알려 드립니다

취소비배정 후 5분이 지남

또는 기사가 픽업지 1km 안(도착 포함, 시간 상관없음)

운송비 전액픽업 뒤

운송비 전액과 회차 요금을 내고 물건은 회차합니다. 기사가 이미 멀리 이동해 회차를 거부하면 회차할 수 없습니다.

오토바이3,000원
다마스 · 라보5,000원
밴 · 트럭10,000원

예외: 기사가 픽업지에서 오래(예: 30분쯤) 기다린 뒤 취소하면 취소비가 더해질 수 있습니다(더해지는 금액은 고객센터가 안내합니다).

API 취소는 배차 시스템에 넘어가기 전까지만 됩니다(그 뒤 409 cancel_not_allowed). 그 뒤 취소는 고객센터 1588-2824. 조건에 해당하지 않는데 기사가 취소비를 요구하면 오전 9시 이후 고객센터로 연락해 주세요.

3-9일부러 틀린 요청 보기

출발지 전화(pickup.phone)를 빼고, 접수자 이름을 21자 넘게 써서 보내 봅니다.

JSON
{
  "error": -1,
  "message": "입력값을 확인해 주세요.",
  "code": "validation_failed",
  "details": [
    { "field": "pickup.phone", "reason": "required" },
    { "field": "requester.name", "reason": "too_long", "max": 20 }
  ],
  "request_id": "req_5b1e0c7a9d2f"
}
  • details에 틀린 칸이 모두(최대 30개, 한 칸에 하나) 나옵니다.
  • 오더를 저장하기 전의 거절이라, 고친 본문을 같은 Idempotency-Key로 보내도 새로 처리합니다.
  • 주소 번호가 없으면 입력 확인을 통과한 뒤 422 address_not_found(details[].reason = building_number_missing)가 따로 나옵니다.

04공통 규칙

4-1인증 헤더

Text
Authorization: Bearer gqk_test_7d3k6m2q4x5p_****************************************
  • Bearer라고 쓰고 한 칸 띄운 뒤 키를 붙입니다. Bearer는 대소문자를 가리지 않지만 이 표기를 권합니다. 키 글자는 대소문자를 구별합니다.
  • 키 모양: gqk_<live|test>_<키ID 12자>_<비밀 40자>
  • 주소 뒤에 붙이는 방식(?key=…)은 받지 않습니다.
  • 본문이 있는 요청은 Content-Type: application/json이 있어야 합니다.

4-2같은 요청 두 번 막기 Idempotency-Key

POST/orders에는 이 헤더가 필수입니다.

상황 할 일 결과
새 오더 새 키(UUID 권장, 8~64자, 영문·숫자·. _ : -) 처리
응답을 못 받음, 5xx·게이트웨이 오류 같은 키 + 같은 본문으로 다시 이미 만들어졌으면 처음 결과(201), 아니면 새로 처리
처음 요청이 아직 처리 중 Retry-After(1~10초) 뒤 같은 키·같은 본문 409 idempotency_in_progress가 최대 약 90초 동안 올 수 있음
저장 전 4xx(입력 422, 중복 409 등)를 받음 본문을 고쳐 같은 키나 새 키로 새로 처리
5xx로 끝난 뒤 본문을 바꿈 새 키로 새로 처리(같은 키는 같은 본문만 받음)
같은 키로 다른 본문 — 422 idempotency_key_reused
  • 칸 순서·공백이 달라도 같은 본문으로 봅니다.
  • 키는 7일간 기억합니다. API 키마다 따로입니다.
  • 대소문자만 다른 두 값을 서로 다른 키로 쓰지 마세요. 같은 값으로 볼 수 있습니다.
  • 같은 키로 다시 받은 응답: 시험 오더는 접수 당시 모습, 운영 오더는 그 사이 전송 결과(waiting·dispatch_no 등)까지입니다. 지금 진행 상태는 상세 조회로 보세요.
  • 취소에는 이 헤더가 필요 없습니다. 이미 취소된 오더를 다시 취소해도 같은 결과입니다.

4-3ERP 번호 external_ref

  • 귀사 안에서 한 번만 씁니다. 시험 오더와 운영 오더는 따로 셉니다.
  • 1~64자, 영문·숫자·. _ : -만 씁니다.
  • 이미 쓴 번호면 409 duplicate_external_ref입니다. 오류 본문 data.id에 기존 오더 번호가 옵니다(이 키로 볼 수 없는 오더면 null). 같은 번호의 접수가 거의 동시에 겹치면 드물게 data가 빠질 수 있습니다. 그때는 GET/orders?external_ref=…로 찾으세요.
  • 취소한 오더의 번호도 다시 쓸 수 없습니다. 다시 접수할 때는 PO-123-R1처럼 새 번호를 쓰세요.
  • 대소문자만 다른 번호를 서로 다른 오더에 쓰지 마세요.
  • 응답을 못 받아 오더가 만들어졌는지 모를 때는 GET/orders?external_ref=PO-…로 확인할 수 있습니다.

4-4시각과 시간대

  • 시각은 ISO 8601이고, 시간대가 꼭 있어야 합니다. 예: 2026-10-09T14:30:00+09:00. Z(UTC)도 받습니다.
  • 초와 소수 초는 생략할 수 있습니다. 소수 초는 버립니다.
  • 응답 시각은 늘 한국 시간(+09:00)입니다.
  • 날짜 조건(created_from 등)은 한국 날짜 YYYY-MM-DD입니다.
  • 예약(schedule.type: reserved)의 reserved_at은 지금부터 30분 뒤 ~ 7일 안이어야 합니다. 아니면 out_of_range와 함께 가능한 가장 이른·늦은 시각을 알려 줍니다.
  • 예약 오더는 콜센터가 예약 시각을 확인하고 배차합니다. 그래서 처음에는 waiting으로 보이다가 scheduled가 될 수 있습니다.

4-5글자 제한

  • 칸 길이는 글자 수로 셉니다(/reference의 field_limits).
칸 최대 글자
external_ref 64
requester.name·requester.department 20
requester.company 25
전화번호 칸 13(서버가 맞춘 뒤)
pickup·dropoff의 name·department·contact_name 50
pickup·dropoff의 address·address_detail·jibun_address 각 300(단, 아래 바이트 제한)
items.description 100
payment.payer_name 20
request_note 100
memo 500
  • 주소 길이는 따로 셉니다. 한 장소의 주소·지번 주소·상세 주소를 합쳐 CP949 200바이트(한글 1자 = 2바이트, 영문·숫자 1자 = 1바이트, 한글로 약 100자)까지입니다. 넘으면 422 address_too_long입니다. 상세 주소를 줄이세요.
  • 전화번호는 숫자와 하이픈만 쓰고, 숫자는 8~12자리입니다. 서버가 010-0000-0001 모양으로 맞춥니다.

쓸 수 없는 글자

글자 어느 칸 오류
<, > 모든 글자 칸(memo 포함) forbidden_character
줄바꿈, 탭 같은 제어 문자 모든 글자 칸(memo 포함) forbidden_character
이모지, 일부 외국 문자처럼 한국어 문자 코드(CP949)로 바꿀 수 없는 글자 배차 시스템으로 가는 칸(이름·상호·부서·주소·물품 설명·요청사항·결제자·계산서) unsupported_character
꺾쇠 글자 <가 들어간 일부 조합 본문 어디든 서버 보안 규칙이 요청 전체를 거부(그린퀵 모양이 아님. JSON 본문 POST면 200일 수 있음, 6-1)
  • memo는 배차 시스템으로 가지 않아 CP949 제한이 없습니다. 다만 <, >, 줄바꿈은 쓸 수 없습니다.
  • request_note를 여러 줄로 쓰지 마세요. 한 줄로 이어 씁니다.
  • ERP에서 미리 걸러 보내면 오류가 줄어듭니다.

서버가 정리하는 값: 앞뒤 공백을 지우고, 주소의 여러 공백·전각 공백은 한 칸으로, 전각 숫자·여러 줄표는 보통 숫자·하이픈으로 바꿉니다. 응답에는 정리된 값이 나옵니다.

4-6주소 쓰는 법

  • address에는 시·도부터 건물번호(도로명) 또는 번지(지번)까지 씁니다. 위치는 이 칸으로만 찾습니다.
  • 층·호·회사 이름은 address_detail에 따로 씁니다. 없으면 "-"를 넣습니다(접수에서는 필수).
  • jibun_address는 선택입니다. 넣으면 기사에게 가는 주소 글자가 지번 주소 (도로명 주소) 상세 주소 모양이 되고, 주소 길이(띄어쓰기·괄호까지 합쳐 200바이트)에 포함됩니다. 위치는 address로만 찾으므로 address와 같은 곳의 지번만 넣으세요. 잘 모르면 비워 두세요.
  • 출발지와 도착지의 주소·상세 주소가 모두 같으면 422 same_address입니다. 같은 건물의 다른 층끼리는 접수됩니다.
주소(address) 결과
서울특별시 중구 세종대로 110 맞음
서울 중구 세종대로110 맞음(시·도 줄임말, 번호 붙여 쓰기 가능)
경기도 성남시 중원구 성남대로 997 맞음
경기도 성남시 중원구 여수동 200 맞음(지번)
세종특별자치시 한누리대로 2130 맞음(세종은 군·구 없음)
경기도 양평군 양평읍 양근리 123 맞음(리 + 번지)
중구 세종대로 110 틀림: 시·도가 없음 → sido_missing
04524 서울특별시 중구 세종대로 110 틀림: 우편번호를 앞에 붙임 → sido_missing(우편번호는 zonecode에)
서울특별시 중구 세종대로 틀림: 건물번호 없음 → building_number_missing
서울특별시 강남구 래미안아파트 101동 1203호 틀림: 도로명·지번 번호 없음 → building_number_missing
서울특별시 중구 (세종대로 110) 틀림: 번호가 괄호 안에만 있음 → building_number_missing
경기도 성남시 중원구 여수동200 틀림: 동 이름과 번지 사이를 띄어야 함 → building_number_missing
서울특별시 중구 세종대로 110번지 틀림: 도로명 주소에 번지를 붙임 → building_number_missing
  • 모양은 맞지만 위치를 찾지 못하면 not_found입니다. 주소 검색 서비스에서 나온 도로명 주소를 그대로 쓰면 가장 정확합니다.

4-7어떤 칸이 어디로 가나요

보낸 칸 가는 곳 기사에게 보이나
pickup·dropoff의 상호·부서·담당자·전화·주소 배차 시스템 출발지·도착지 칸 예
requester.name·department·phone·company 배차 시스템 접수자 칸(부서는 내역서 부서 칸) 콜센터·내역서에 보임
requester.phone 배차 시스템이 안내 문자를 보낼 수 있는 번호. 그린퀵 알림톡(접수·배차·출발·완료 중 귀사가 고른 것, 2-6)도 이 번호로 감. 배차 알림에는 기사 이름·연락처·차종이 들어감 —
dropoff.phone 배차 시스템 도착지 칸, 그리고 그린퀵 받는 분 알림톡(픽업 때 배송현황 링크, 2-6 설정에 따름) 예
payment.method 배차 시스템 결제 방식 칸(card는 카드 결제로 등록, 접수 때 결제 없음) 콜센터에 보임(기사에게도 결제 방식이 보일 수 있음)
vehicle.type·truck_ton·truck_body, 급송 여부 배차 시스템 차량·급송 칸 예
request_note 배차 시스템 적요(기사가 보는 메모) 예
물품(items.packages·description·fragile) 배차 시스템 적요 예
전달·상하차(handling.*), 리프트, 선택 차량만, 동승 배차 시스템 적요 예
예약 일자·시각, 연계 배송 방식 배차 시스템 적요 예
결제자(제3자 이름·전화 포함) 배차 시스템 적요 예
계산서 정보(사업자등록번호·대표자·담당자·연락처·메일·주소) 배차 시스템 오더메모(콜센터만 보는 칸) 아니오
memo 그린퀵 사이트에만 아니오
notify_cc 그린퀵 알림톡(배차·출발·완료, 2-6)만 — 배차 시스템으로 가지 않음 아니오
external_ref 그린퀵에만 아니오
  • 적요 맨 앞에는 (그린퀵 API ord_…) 표시가 붙습니다. 콜센터가 이 표시로 API 오더를 찾습니다.
  • 받는 분 픽업 알림톡(2-6에서 켰을 때, 기본은 켜짐)의 본문에는 접수 담당자 이름(requester.name), 출발지 상호(pickup.name), 물품(items.description), 배송 수단, 하차 방법, 도착지 담당자 이름(dropoff.contact_name)이 들어가 dropoff.phone으로 갑니다.
  • 개인정보는 배송에 꼭 필요한 만큼만 보내 주세요(11장).

05상태 값과 흐름

5-1흐름

단계 보통의 흐름 곁가지
1 received 그린퀵에 저장됨 보내기 전 확인 대기(awaiting_review), 전송 확인 중(confirming_transfer), transfer_failed
2 waiting 배차 시스템에 들어감(dispatch_no 생김) —
3 accepted 기사 배정 대기 scheduled 예약, on_hold 콜센터 확인 중
4 assigned 기사 배정 —
5 in_transit 배송 중 —
6 completed 배송 완료(끝) cancelled 취소(끝), unknown 그 밖
  • 운영 오더 상태는 배차 시스템에서 약 2분 간격으로 가져옵니다. 실제보다 보통 최대 약 3분 늦을 수 있습니다.
  • 밤 22:00~08:00에는 API로 새 오더를 받지 않습니다(409 night_closed, 시험 키도 같음). 그 시간에도 08:30 이후 픽업 예약(reserved)은 받고, 예상 요금·조회·취소는 그대로 됩니다. 밤 시간 배송이 필요하면 미리 그린퀵과 상의해 주세요.
  • 저녁(22:00 전)에 접수한 운영 오더와 밤에 받은 예약 오더도 저장·전송은 바로 되어 waiting이 됩니다. 다만 콜센터가 아침에 확인할 때까지 waiting으로 기다릴 수 있고, 기사 배정과 접수 알림톡도 그 뒤에 시작됩니다.
  • 같은 이유로 중간 상태를 건너뛸 수 있습니다(예: waiting에서 바로 in_transit). 순서대로 하나씩 바뀐다고 가정하지 마세요.
  • 끝 상태(completed, cancelled)에서는 상태가 더 바뀌지 않습니다. 다만 실제 요금(price.charged)은 완료 뒤 3일까지 바뀔 수 있습니다.
  • 모르는 상태 값이 오면 unknown처럼 처리하세요. 값은 늘어날 수 있습니다.

5-2상태 표

status status_label 뜻 API 취소
received 접수됨(전송 대기) 그린퀵에 저장됨. 보내기 전·확인 대기·전송 확인 중 status_reason에 따라 다름(아래)
transfer_failed 전송 지연(처리 중) 배차 시스템에 들어가지 않은 것이 확실하고, 그린퀵이 다시 보내거나 처리하는 중 됨
waiting 접수 확인 중 배차 시스템에 들어가 콜센터 확인을 기다림 안 됨(전화)
accepted 접수(배차 대기) 기사 배정을 기다림 안 됨(전화. 다른 배차망에서 먼저 배정됐으면 취소비가 생길 수 있음, 3-8)
scheduled 예약 콜센터가 예약 오더로 등록함 안 됨(전화)
on_hold 확인 필요 콜센터가 확인 중 안 됨(전화)
assigned 기사 배정 기사가 정해짐 안 됨(전화, 취소비가 생길 수 있음, 3-8)
in_transit 배송 중 물건을 받아 이동 중 안 됨
completed 배송 완료 도착(끝) 안 됨
cancelled 취소 취소됨(끝) 다시 보내도 200
unknown 확인 중 그 밖의 상태 안 됨(전화)

status_reason (상태 보충 설명, 없으면 null)

값 뜻 received일 때 API 취소
null 보내기 직전 됨
awaiting_review 그린퀵 담당자가 확인한 뒤 배차 시스템으로 보냄 됨
confirming_transfer 배차 시스템에 들어갔는지 확인하는 중(보통 몇 분 안에 정해짐) 409 cancel_pending_confirmation
retrying 일시 오류로 다시 보내는 중(transfer_failed와 함께) 됨
needs_attention 그린퀵 담당자가 처리 중 될 수도 있고 409 cancel_pending_confirmation일 수도 있음

5-3운영 접수 응답에서 볼 수 있는 상태

응답 상태 뜻 귀사가 할 일
waiting + dispatch_no 배차 시스템에 들어감(보통) 주기 조회로 진행을 따라갑니다
received + awaiting_review 그린퀵 담당자 확인 뒤 보냄 기다립니다. 급하면 1588-2824
received + null 또는 confirming_transfer 보내는 중·확인 중 몇 분 뒤 상세 조회
transfer_failed + retrying·needs_attention 아직 안 들어감, 그린퀵이 처리 중 기다립니다. 급하면 1588-2824

모두 접수는 저장된 것입니다. 다시 접수하지 마세요(같은 오더가 두 번 들어갈 수 있습니다).


06오류 표

모든 오류는 아래 모양입니다. HTTP 상태 코드로 먼저 판단하고, 그다음 code를 보세요. message는 사람이 읽는 안내라 바뀔 수 있습니다. 성공은 상태 코드가 2xx이면서 본문의 error가 0이고 request_id가 있을 때만입니다. 없는 주소를 POST로 부르면 200인데 성공이 아닌 응답이 올 수 있습니다(6-1).

JSON
{ "error": -1, "message": "…", "code": "validation_failed", "details": [ … ], "request_id": "req_5b1e0c7a9d2f" }
HTTP code 뜻 할 일 자동으로 다시 보내도 되나 같은 Idempotency-Key로?
400 invalid_json 본문이 JSON 객체가 아님, Content-Type 틀림, 32KB 넘음, BOM 붙음 본문·헤더 고치기 아니오 예(아직 키를 쓰지 않음)
400 invalid_parameter Idempotency-Key가 없거나 모양이 틀림, 또는 목록 조건이 틀림 details 보고 고치기 아니오 (키를 고쳐서)
401 unauthorized 키 없음·모양 틀림·틀린 키·폐기·만료 키 확인 아니오 —
403 https_required https가 아닌 요청(드묾) https로, 키 교체 요청 아니오 —
403 ip_not_allowed 등록하지 않은 IP IP 등록·키 교체 요청 아니오 —
403 insufficient_scope 키에 그 권한이 없음(예상 요금 비공개 계약 포함) 권한 요청 아니오 —
403 account_not_ready 그린퀵 쪽 회사·청구 계정 설정 문제 그린퀵에 연락 아니오 —
404 not_found 오더가 없거나 이 키로 볼 수 없음 id 확인 아니오 —
405 method_not_allowed GET만 받는 주소를 POST로, POST만 받는 주소를 GET으로 부름(예: POST/ping, GET/quotes). 키 확인 전에 나옴 Allow 헤더(GET·POST)의 방식으로 아니오 —
409 duplicate_external_ref 같은 external_ref가 이미 있음(취소된 오더 포함) data.id로 그 오더 확인(드물게 data가 없으면 GET/orders?external_ref=…). 다시 접수하려면 새 번호 아니오 새 번호로 고친 본문은 같은 키도 됨
409 idempotency_in_progress 같은 키 요청이 처리 중 Retry-After 뒤 예 예(같은 본문)
409 cancel_pending_confirmation 배차 시스템에 들어갔는지 확인 중 몇 분 뒤 상태 확인, 급하면 1588-2824 예(몇 분 뒤) —
409 cancel_not_allowed 지금 상태에서는 API 취소 불가 1588-2824 전화 아니오 —
409 night_closed 밤 22:00~08:00의 새 오더 접수(오더는 안 만들어짐). 그 시간에도 08:30 이후 픽업 예약은 받음 08:00 뒤 다시 보내거나 08:30 이후 예약으로, 급하면 1588-2824 아니오(08:00 뒤 한 번) 예(같은 본문도 아침에 새로 처리)
422 validation_failed 입력 확인 실패 details 보고 고치기 아니오 예(고친 본문도 됨)
422 idempotency_key_reused 같은 키로 다른 본문 같은 오더면 처음 본문 그대로, 새 오더면 새 키 아니오 새 키
422 address_not_found 주소 위치를 못 찾음 4-6장 보고 주소 고치기 아니오 예(고친 본문도 됨)
422 address_too_long 주소 합계가 200바이트 넘음(details[]의 field = 넘은 장소의 address_detail, reason = too_long, 한도는 max 대신 max_bytes = 200) 상세 주소 줄이기 아니오 예(고친 본문도 됨)
422 same_address 출발·도착 주소와 상세 주소가 모두 같음 확인 아니오 예(고친 본문도 됨)
422 quote_unavailable 요금 계산 불가(밴 등, 예상 요금 기능만) 접수는 가능. 요금은 고객센터 아니오 —
422 payment_method_not_allowed 귀사 설정에서 꺼 둔 결제 방법 GET/ping의 payment_methods를 보고 결제 방법 바꾸기(또는 총괄관리자가 2-6 설정에서 켬) 아니오 예(고친 본문도 됨)
429 rate_limited 분당 호출 한도·동시 처리 한도, 인증 실패 많음(하루 접수 건수 한도는 없음) Retry-After 뒤 예 예(같은 본문)
500 internal_error 서버 오류 잠시 뒤 예 예(같은 본문)
502 upstream_unavailable 주소·요금 확인에 쓰는 외부 시스템 무응답(오더는 안 만들어짐) 잠시 뒤 예 예(같은 본문)
503 api_disabled 점검 중, 그린퀵이 아직 사용을 열지 않은 운영 키, 일시 장애 잠시 뒤, 계속이면 연락 예(간격 두고) 예(같은 본문)
  • 501 not_implemented는 예약 코드입니다. 지금은 쓰지 않습니다.
  • 모르는 code가 오면 HTTP 상태 코드로 처리하세요. 값은 늘어날 수 있습니다.
  • 그린퀵이 접수를 저장한 뒤에는 5xx로 답하지 않습니다. 5xx를 받았다면 아직 접수가 확정되지 않은 것이니, 같은 키·같은 본문으로 다시 보내면 됩니다.

details[].reason 값

값 뜻
required 꼭 넣어야 하는 칸이 없음
invalid_type 형식이 틀림(expected: object·string·boolean·integer·array)
too_long 너무 김(max 글자)
forbidden_character <, >, 줄바꿈 같은 제어 문자
unsupported_character CP949로 바꿀 수 없는 글자(이모지 등)
invalid_value 값표에 없는 값(allowed 목록)
invalid_format 모양이 틀림(전화 숫자 8~12자리, 우편번호 5자리, 사업자등록번호, 메일, 시각, external_ref)
out_of_range 범위 밖(min·max)
not_allowed 이 키에 허용되지 않음(청구 계정 등, allowed)
unknown_key 오토바이 물품에 모르는 칸
truck_only 지게차는 트럭만
not_allowed_for_motorcycle 오토바이는 동승 불가
bank_transfer_only 계산서는 무통장입금일 때만
too_many notify_cc 번호가 3개를 넘음(max)
not_mobile notify_cc에 010 휴대폰이 아닌 번호(011·016~019·유선 포함)(notify_cc.0처럼 몇 번째인지 field에)
sido_missing, building_number_missing, not_found 주소 문제(4-6)
after_to, range_too_long, invalid_or_conditions_changed 목록 조건 문제(시작일이 끝일 뒤, 31일 넘음, 커서와 조건이 다름)

6-1JSON이 아닌 응답

서버 앞단에서 막혔거나 그린퀵 API까지 오지 못한 요청은 본문이 그린퀵 모양이 아니고 request_id도 없습니다. 상태 코드로 처리하세요. 다만 없는 주소를 POST로 부른 경우는 200이 올 수 있습니다. 성공은 2xx + 본문 error: 0 + request_id가 있을 때로만 판단하세요.

상황 상태 할 일
http://로 부름 403(greenquick.co.kr이면 421) https://로 고치고, 키 교체 요청
www.greenquick.ai·greenquick.co.kr 같은 다른 주소 이름으로 부름 421 https://greenquick.ai/api/v1로 고치기
본문이 64KB를 넘음 413 본문 줄이기(그린퀵 한도는 32KB)
서버 앞단 호출 한도(같은 IP 초당 10회·순간 20회, 동시 연결 4개) 429, Retry-After 없음 1·2·4초처럼 늘려 가며 기다린 뒤
보안 규칙(꺾쇠 글자 <가 들어간 일부 조합) 본문이 JSON인 POST면 200(JSON이지만 error: -1, code·request_id 없음), 그 밖은 오류 페이지 성공으로 보지 말기. 글자 고치기
PUT·DELETE·PATCH 같은 방식 404(서버 기본 모양) 명세의 방식(GET·POST)으로 고치기
없는 주소를 POST로 부름: 주소 오타(예: POST/order), {id}에 영문·숫자·_ 밖 글자(예: POST/orders/PO-2026-10-000123/cancel) 헤더(Content-Type·Accept)에 json이 있거나 본문이 JSON이면 200(JSON이지만 error: -1, code·request_id 없음), 아니면 404 성공으로 보지 말기. 주소와 id(ord_ + 22자) 고치기
없는 주소를 GET으로 부름(같은 경우) 404(서버 기본 모양) 주소와 id 고치기
게이트웨이 오류 502·504 같은 키·같은 본문으로 다시
응답 없음(타임아웃) — 같은 키·같은 본문으로 다시, 또는 external_ref로 목록 조회해 확인

6-2권장 재시도 규칙

  • 자동으로 다시 보내는 것은 위 표에서 "예"인 경우만입니다.
  • Retry-After가 있으면 그 초만큼 기다립니다.
  • 없으면 1초, 5초, 30초 뒤 최대 3번까지 다시 보냅니다.
  • 접수는 늘 같은 Idempotency-Key, 같은 본문으로 다시 보냅니다.
  • 3번 모두 실패하면 사람이 확인하도록 남기고, request_id·키ID·시각을 기록합니다.

07호출 한도

기본값이며 계약에 따라 조정합니다.

구분 운영 키 시험 키
키 하나 전체(모든 기능 합계) 분당 60회 분당 15회
접수 POST/orders 분당 60회 분당 15회
예상 요금 POST/quotes 분당 10회 분당 2회
목록 GET/orders 분당 30회 분당 7회
취소 POST/orders/{id}/cancel 분당 10회 분당 2회
동시에 처리 중인 요청 키당 2개 키당 1개
인증 실패(같은 IP) 분당 20회를 넘으면 그 IP를 10분 막음 같음
서버 앞단(같은 IP) 초당 10회(순간 20회), 동시 연결 4개, 본문 64KB(넘으면 6-1) 같음
  • 하루 접수 건수 한도는 없습니다. 위의 분당 한도, 동시 처리 한도, 서버 앞단 한도만 있습니다.
  • 접수 한도(분당 60회)는 키 전체 한도(분당 60회)와 함께 셉니다. 같은 1분 안에 목록·상세 등 다른 기능도 부르면 그만큼 접수할 수 있는 횟수가 줄어듭니다.
  • ping, reference, 상세, 추적은 키 전체 한도만 셉니다.
  • 분당 한도는 매 분 0초에 새로 시작하는 1분 창으로 셉니다.
  • 권한이 없거나 입력이 틀려 거절된 요청도 셉니다.
  • 한꺼번에 많이 접수할 때는 동시에 보내는 요청을 키당 2개(시험 키 1개) 이하로 두세요. 429를 받으면 Retry-After만큼 기다린 뒤 같은 Idempotency-Key·같은 본문으로 다시 보내세요.
  • 그린퀵 서버 전체에도 동시 처리 상한이 있습니다. 그래서 귀사 한도 안이어도 가끔 429 + Retry-After: 1이 올 수 있습니다. 1초 뒤 다시 보내면 됩니다. 특히 시험 키의 예상 요금·접수는 모든 시험 회사를 합쳐 한 번에 하나씩만 처리합니다.
  • 그린퀵이 아직 사용을 열지 않은 운영 키로 부른 것(503)도 인증 실패로 셀 수 있습니다.
  • 인증을 통과한 응답에는 아래 헤더가 붙습니다. 서버 사정으로 빠질 수 있습니다.
  • X-RateLimit-Limit: 분당 한도(키 전체와 그 기능 한도 중 남은 횟수가 적은 쪽)
  • X-RateLimit-Remaining: 지금 1분 창에서 남은 횟수
  • X-RateLimit-Reset: 지금 1분 창이 끝날 때까지 남은 초(시각이 아님)

08시험 키 동작 시간표

시험 오더는 접수 시각부터 지난 시간에 따라 상태가 저절로 바뀝니다.

접수 뒤 status 바뀌는 칸 API 취소
0초 received dispatch_no·transferred_at 없음 됨
1분 waiting dispatch_no = TEST + 숫자 8자리, transferred_at = 접수 + 1분 안 됨
3분 accepted — 안 됨
5분 assigned driver = 시험 기사·00시0000·010-0000-0000 안 됨
8분 in_transit picked_up_at = 접수 + 8분 안 됨
10분 completed delivered_at = 접수 + 10분, driver = null, price.charged = 예상 요금, price.status = provisional 안 됨
완료 3일 뒤 completed price.status = confirmed, updated_at이 그 시각으로 오름 안 됨
  • updated_at은 그 상태가 된 시각입니다. 그래서 updated_since 주기 조회를 시험 키로 그대로 연습할 수 있습니다.
  • 접수 응답과, 같은 키로 다시 보낸 응답은 늘 접수 당시 모습(received)입니다.
  • 시험 키 예상 요금은 같은 주소·차량·급송 여부·날짜면 24시간 같은 값을 줍니다.
  • 시험 오더는 30일 뒤 지워집니다.

시험 키로 재현되지 않는 상황 — 아래는 코드로 미리 만들어 두세요.

상황 운영에서 보이는 모양
접수 직후 이미 배차 시스템에 들어감 201이 waiting + dispatch_no
접수 직후 취소 불가 409 cancel_not_allowed
담당자 확인 뒤 전송 received + awaiting_review
전송 확인 중 received + confirming_transfer, 취소하면 409 cancel_pending_confirmation
전송 실패 transfer_failed + retrying·needs_attention
예약 등록, 콜센터 확인 scheduled, on_hold
상태 건너뛰기 waiting에서 바로 in_transit 등
모르는 상태 unknown
실제 요금이 예상과 다름 price.charged가 price.estimated와 다름, 완료 뒤 3일 안에 바뀔 수 있음
상태가 최대 약 3분 늦게 반영 updated_at이 실제 진행보다 늦음
저녁(22:00 전) 접수·밤에 받은 예약 아침 8시 무렵 콜센터가 확인할 때까지 waiting
다른 배차망에서 기사 배정 waiting·accepted에서 바로 assigned가 될 수 있음. driver는 name = 그린퀵 배송기사, phone = 1588-2824(그린퀵 고객센터), vehicle_no = null입니다. 기사 문의는 1588-2824로

09주기 조회 요령

웹훅이 없으므로 updated_since 주기 조회가 기본입니다.

9-1순서

Text
since = 저장해 둔 값(처음이면 지금부터 하루 전)
5~10분마다:
    cursor = 없음
    last = since
    반복:
        GET /orders?updated_since={since}&page_size=100[&cursor={cursor}]
        받은 오더마다: id 기준으로 ERP 자료를 덮어씀
                       last = max(last, 그 오더의 updated_at)
        cursor = 응답의 next_cursor
    cursor가 null이 될 때까지
    since = last 를 저장
  • updated_since는 같은 시각을 포함합니다. 그래서 지난번 마지막 오더가 다음에도 다시 나옵니다. id로 덮어쓰면 문제없습니다.
  • 쪽을 넘기는 동안에는 updated_since 값을 바꾸지 마세요. 커서는 같은 조건에서만 씁니다(아니면 400 invalid_parameter, details[].reason = invalid_or_conditions_changed — 이때는 커서를 버리고 처음 쪽부터 다시).
  • 결과는 updated_at이 오래된 것부터 나옵니다.
  • 권장 간격은 5~10분입니다. 상태는 배차 시스템에서 약 2분 간격으로 들어오므로 2분보다 자주 불러도 새 값이 거의 없습니다.
  • 목록에는 요약만 나옵니다. 기사·요금 세부가 필요하면 바뀐 오더만 GET/orders/{id}로 가져옵니다.
  • 추적은 같은 오더를 5분에 한 번 이하로 부릅니다.

9-2updated_at이 오르는 때

  • 상태나 status_reason이 바뀔 때
  • dispatch_no가 생길 때
  • 기사 정보가 바뀔 때
  • 실제 요금이 바뀔 때(완료 뒤 3일까지)
  • 요금이 확정(confirmed)으로 바뀔 때
  • 픽업·배송·취소 시각이 정해질 때

위치가 바뀌는 것만으로는 오르지 않습니다. 기사 정보는 추적 기능으로 봅니다.

9-3정산 대조

  • GET/orders?completed_from=2026-09-01&completed_to=2026-09-30처럼 완료일로 가져옵니다(한 번에 최대 31일).
  • 이 조건은 그린퀵이 완료를 확인한 시각의 날짜로 거릅니다. 응답의 delivered_at(배차 시스템 기록)과 몇 분 어긋날 수 있어, 자정 무렵 완료된 오더는 다음 날로 잡힐 수 있습니다.
  • 그래서 범위를 앞뒤로 하루씩 넉넉히 잡고, 받은 뒤 delivered_at으로 다시 거르세요.
  • 요금은 price.status가 confirmed인 것을 기준으로 맞추세요.

9-4응답 시간과 타임아웃

  • 조회는 보통 0.1초 안팎, 예상 요금·접수는 보통 1~2초입니다.
  • 예상 요금과 접수는 외부 시스템을 거쳐 길면 약 55초까지 걸릴 수 있습니다.
  • 클라이언트 타임아웃은 60초 이상으로 두세요. 30초로 두면 끊긴 뒤 재시도하면서 409 idempotency_in_progress를 받을 수 있습니다(같은 키로 기다리면 됩니다).

10운영 전환 전 점검표

운영 키를 요청하기 전에 확인하고, 이 표를 그린퀵에 보내 주세요.

  • [ ] 운영 서버의 고정 IPv4 주소(최대 10개)를 그린퀵에 알렸다.
  • [ ] 총괄관리자가 운영 키를 직접 받아 비밀 저장소에 넣었다. 소스·로그·메일에 남지 않는다.
  • [ ] 모든 POST/orders에 새 Idempotency-Key를 만들고, ERP에 external_ref와 함께 저장한다.
  • [ ] 응답이 없거나 5xx·게이트웨이 오류면 같은 키·같은 본문으로 다시 보낸다(최대 3번).
  • [ ] external_ref는 ERP 번호와 1:1이다. 취소 뒤 다시 접수할 때는 새 번호를 쓴다.
  • [ ] 클라이언트 타임아웃이 60초 이상이다.
  • [ ] 리다이렉트를 따라가지 않는다. https://greenquick.ai/api/v1만 쓴다.
  • [ ] 모르는 칸·상태·code가 와도 멈추지 않는다(unknown·HTTP 상태 코드로 처리).
  • [ ] JSON이 아닌 오류 응답(6-1)도 상태 코드로 처리한다. 성공은 2xx + 본문 error: 0 + request_id로만 판단한다. 주소의 {id}에는 ord_ 번호만 넣는다.
  • [ ] 주소는 시·도부터 건물번호까지 보낸다. 시험에서 address_not_found가 0건이 될 때까지 고쳤다.
  • [ ] 글자 제한(<, >, 줄바꿈, 이모지, 주소 200바이트)을 ERP에서 미리 거른다.
  • [ ] 주기 조회 간격이 5~10분이고, 추적은 같은 오더를 5분에 한 번 이하로 부른다.
  • [ ] 운영 접수 응답이 waiting·received·transfer_failed 어느 것이어도 다시 접수하지 않는다.
  • [ ] 취소는 대부분 고객센터 1588-2824 전화라는 업무 흐름을 담당 부서와 맞췄다.
  • [ ] 총괄관리자가 API 설정 화면에서 결제 방법을, 알림 설정 화면에서 알림톡(접수 담당자 접수·배차·출발·완료 중 고른 것, 받는 분 출발)을 확인했다(2-6). 켜 둔 알림톡이 접수 담당자·도착지 연락처로 간다는 것과 받는 분 알림톡 본문에 들어가는 내용(11장)을 담당 부서가 알고 있다.
  • [ ] 카드 번호 같은 결제 정보를 API로 보내지 않는다(card는 접수 때 결제하지 않음).
  • [ ] 키 교체를 한 번 연습했다(새 키 넣기 → 옛 키 폐기 요청).
  • [ ] 문의 담당자와 연락처를 그린퀵에 알렸다.
  • [ ] 시험 키로 아래를 모두 통과했다.
  • [ ] 접수 → 상세 → 목록 → 추적
  • [ ] 같은 external_ref로 다시 접수 → 409 duplicate_external_ref와 data.id
  • [ ] 같은 키·같은 본문으로 다시 보냄 → 같은 id의 201
  • [ ] 같은 키·다른 본문 → 422 idempotency_key_reused
  • [ ] 틀린 주소 → 422 address_not_found, 고친 뒤 같은 키로 → 201
  • [ ] 한도 초과(분당) → 429와 Retry-After 처리
  • [ ] 1분 안 취소 → 200, 1분 뒤 취소 → 409 cancel_not_allowed
  • [ ] 밤 22:00~08:00 접수 → 409 night_closed를 받으면 08:00 뒤 다시 보내거나 담당자에게 알린다(자동으로 되풀이하지 않음)
  • [ ] 목록 next_cursor로 끝까지 넘기기, updated_since 주기 조회

11개인정보와 보관

  • 배송에 꼭 필요한 정보만 보내 주세요: 출발·도착지 상호, 담당자 이름, 연락처, 주소.
  • external_ref, memo, request_note에는 주민등록번호나 계좌번호 같은 정보를 넣지 마세요. 카드 번호 같은 결제 정보는 어떤 칸에도 넣지 마세요.
  • 받은 정보는 배송 처리와 정산에만 씁니다.
  • 배송 처리를 위해 배차 시스템 운영사와 배송 기사에게 배송에 필요한 칸만 전달합니다(처리 위탁). memo는 전달하지 않습니다. 계산서 정보는 배차 시스템 오더메모(콜센터만 보는 칸)로 가고 기사에게는 보이지 않습니다(4-7).
  • 그린퀵은 귀사 알림 설정(2-6)에 따라 카카오 알림톡을 보냅니다. 처음 값은 접수 담당자에게 접수·출발(픽업)·완료, 받는 분에게 출발(픽업)입니다. 배차 알림(기사 이름·연락처·차종)은 귀사가 고른 경우에만 가고, 취소 알림톡은 보내지 않습니다. 새벽 2시 마감으로 배차 시스템이 자동 완료한 오더(기사 위치 기록 없음)에는 완료 알림톡을 보내지 않습니다.
  • 접수 담당자(requester.phone): 접수, 배차(귀사가 고른 경우 — 기사 이름·연락처·차종), 픽업(배송 출발), 배송 완료
  • 받는 분(dropoff.phone): 픽업(배송 출발)
  • 같이 받을 사람(notify_cc): 배차(기사 이름·연락처·차종)·픽업(배송 출발)·배송 완료 — 귀사가 그 오더에 적은 번호에만. 본문에는 귀사 이름, 출발지·도착지 상호, 물품, 배송현황 링크가 들어갑니다. 번호는 오더 연락처와 같은 기간 보관합니다.
  • 받는 분 픽업 알림톡 본문에는 접수 담당자 이름(requester.name), 출발지 상호(pickup.name), 물품(items.description), 배송 수단, 하차 방법, 도착지 담당자 이름(dropoff.contact_name)이 들어가 받는 분 휴대폰으로 갑니다. 알림 설정에서 받는 분 알림을 '보내지 않기'로 고르면(2-6) 이 내용도 가지 않습니다.
  • 배차·픽업·완료 알림톡에는 배송현황 링크가 들어갑니다. 링크는 오더마다 따로 만든 것이라 번호를 바꿔 다른 오더를 볼 수 없습니다. 이 링크로 연 화면에 보이는 것과 보이지 않는 것은 아래와 같습니다.
  • 보임: 진행 단계(접수 · 기사 배정 · 배송 중 · 배송 완료, 취소면 취소)와 시각, 기사 이름·연락처·차량번호(다른 배차망 배정이면 그린퀵 배송기사·1588-2824), 도착지 주소
  • 기사 위치(지도)는 지금 보이지 않습니다. 지도 자리에 진행 단계가 나옵니다.
  • 보이지 않음: 출발지·도착지 담당자 이름과 연락처, 출발지 상세 주소(출발지는 시·구·동까지만 보임)
  • 기사 이름·연락처·차량번호는 배차 시스템에서 받은 마지막 기록이라, 배송이 끝난 뒤에도 링크가 열리는 동안 보입니다.
  • 링크는 배송 완료·취소 7일 뒤, 또는 접수 30일 뒤에는 열리지 않습니다.
  • 그린퀵 사이트에 로그인해 그 오더를 볼 수 있는 귀사 직원에게는 담당자 이름·연락처와 출발지 상세 주소까지 모두 보입니다.
  • API 응답의 기사 이름·전화·차량번호는 배송 진행 중(assigned, in_transit)에만 제공합니다. 귀사는 이 정보를 배송 확인 외의 목적으로 쓰거나 다른 곳에 넘기지 않습니다.
  • 그린퀵의 API 호출 기록에는 요청 내용(주소·전화 등)을 남기지 않습니다. 호출 시각, 기능, 결과, IP, 키ID, 호출 프로그램 이름(User-Agent), 처리 시간만 남기고 90일 보관합니다.
  • 배차 시스템과 주고받은 기술 기록은 연락처·주소를 가린 채 최대 30일 보관합니다.
  • 시험 오더는 30일 뒤 지웁니다.
  • 같은 요청 두 번 막기 기록(Idempotency-Key)은 7일 보관합니다.
  • 오더 정보 보관 기간은 그린퀵 웹 접수 오더와 같습니다(이용약관).
  • 키 관리 책임, 키가 샜을 때 생긴 배차 비용의 분담, 개인정보 처리 위탁은 그린퀵과 귀사가 맺는 계약에서 정합니다.

12지원·문의

  • 배송 건(취소·변경·기사 문의): 고객센터 1588-2824. dispatch_no(배차 시스템 접수번호)를 알려 주면 빠릅니다. 밤 11시부터 아침 8시까지는 전화를 받지 않을 수 있습니다.
  • 밤 22:00~08:00에는 API로 새 오더를 받지 않습니다(409 night_closed, 시험 키도 같음). 그 시간에도 08:30 이후 픽업 예약(reserved)은 받고, 예상 요금·조회·취소는 그대로 됩니다. 저녁(22:00 전)에 접수한 운영 오더와 밤에 받은 예약 오더는 콜센터가 아침에 확인할 때까지 waiting으로 기다릴 수 있습니다. 밤 시간 배송이 필요하면 미리 그린퀵과 상의해 주세요.
  • API 연동 상담: 1588-2824 (10:00~16:00) — 전화하셔서 '개발 담당자'를 찾아 주세요.
  • 지원 시간과 응답: 연동 문의는 10:00~16:00에 확인하고 답합니다.
  • 장애·점검 공지: 연동 담당자 메일로 미리 알립니다. 긴급 장애는 복구한 뒤 알립니다. 점검 중에는 503 api_disabled가 납니다.
  • 문의할 때는 아래를 함께 알려 주세요.
  • request_id(또는 응답 헤더 X-Request-Id)
  • 키ID(키의 gqk_test_·gqk_live_ 바로 뒤 12자. 비밀 40자는 알려 주지 마세요)
  • 호출 시각과 기능(예: POST/orders)
  • 오더 id 또는 external_ref

버전

  • 주소에 버전이 들어 있습니다(/api/v1). 응답 헤더 X-Api-Version에 현재 버전이 나옵니다.
  • v1 안에서는 칸·상태 값·오류 code·기능을 더하기만 합니다. 모르는 칸은 무시하세요.
  • 칸을 빼거나 뜻을 바꾸는 변경은 /api/v2로 내고, v1은 최소 6개월 함께 운영합니다.
  • 변경 내역은 그린퀵이 메일로 알리고, 명세 파일도 함께 갱신합니다.