ROADMAX 개발자 센터

X-RoadMax-Api-Key: rmk_<test|live>_<32자>

curl -s "https://roadmax.kr/api/v1/partner/v1/stores" \
  -H "X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

GET https://roadmax.kr/api/v1/partner/v1/stores
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
  "data": [
    {
      "partnerStoreCode": "STORE-001",
      "storeName": "쌀통닭 맹동점",
      "address": "충북 음성군 맹동면 혁신로 10",
      "status": "ACTIVE"
    }
  ]
}

POST https://roadmax.kr/api/v1/partner/v1/quotes
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

{
  "partnerStoreCode": "STORE-001",
  "dropoff": {
    "lat": 36.9288,
    "lng": 127.6867,
    "address": "충북 음성군 맹동면 혁신로 10"
  }
}

{
  "data": {
    "fee": 4300,
    "distanceKm": 2.31,
    "currency": "KRW",
    "breakdown": {
      "base": 3800,
      "extra": 500,
      "cap": 10000
    },
    "partnerStoreCode": "STORE-001",
    "estimate": true
  }
}

POST https://roadmax.kr/api/v1/partner/v1/deliveries
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Idempotency-Key: order-20261002-0001
Content-Type: application/json

{
  "partnerStoreCode": "STORE-001",
  "partnerRef": "ORDER-20261002-0001",
  "dropoff": {
    "address": "충북 음성군 맹동면 혁신로 20",
    "detail": "101동 1203호",
    "phone": "010-1234-5678",
    "lat": 36.9301,
    "lng": 127.689
  },
  "itemTotal": 15000,
  "deliveryFee": 4300,
  "memo": "문 앞에 놓아주세요"
}

{
  "data": {
    "id": "cm1x2y3z40000abcd1234efgh",
    "partnerRef": "ORDER-20261002-0001",
    "partnerStoreCode": "STORE-001",
    "status": "pending",
    "externalChannel": null,
    "externalOrderRef": null,
    "pickup": {
      "name": "쌀통닭 맹동점",
      "address": "충북 음성군 맹동면 혁신로 10",
      "lat": 36.9288,
      "lng": 127.6867
    },
    "dropoff": {
      "address": "충북 음성군 맹동면 혁신로 20 101동 1203호",
      "lat": 36.9301,
      "lng": 127.689
    },
    "customerPhoneMasked": "010-1234-****",
    "memo": "문 앞에 놓아주세요",
    "fee": {
      "deliveryFee": 4300,
      "itemTotal": 15000,
      "currency": "KRW"
    },
    "rider": null,
    "createdAt": "2026-10-02T01:23:45.000Z",
    "assignedAt": null,
    "pickedUpAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "updatedAt": "2026-10-02T01:23:45.000Z",
    "sandbox": false
  },
  "estimatedFee": 4300
}

{
  "error": {
    "code": "branch_min_riders",
    "message": "현재 배차 가능한 라이더가 부족합니다",
    "requestId": "req_3f9a1c7d2b8e4a6f10c5d9e2"
  }
}

{
  "id": "cm1x2y3z40000abcd1234efgh",
  "partnerRef": "ORDER-20261002-0001",
  "partnerStoreCode": "STORE-001",
  "status": "assigned",
  "externalChannel": null,
  "externalOrderRef": null,
  "pickup": {
    "name": "쌀통닭 맹동점",
    "address": "충북 음성군 맹동면 혁신로 10",
    "lat": 36.9288,
    "lng": 127.6867
  },
  "dropoff": {
    "address": "충북 음성군 맹동면 혁신로 20 101동 1203호",
    "lat": 36.9301,
    "lng": 127.689
  },
  "customerPhoneMasked": "010-1234-****",
  "memo": "문 앞에 놓아주세요",
  "fee": {
    "deliveryFee": 4300,
    "itemTotal": 15000,
    "currency": "KRW"
  },
  "rider": {
    "name": "김**",
    "phoneMasked": "010-5678-****"
  },
  "createdAt": "2026-10-02T01:23:45.000Z",
  "assignedAt": "2026-10-02T01:24:10.000Z",
  "pickedUpAt": null,
  "deliveredAt": null,
  "cancelledAt": null,
  "updatedAt": "2026-10-02T01:24:10.000Z",
  "sandbox": false
}

GET https://roadmax.kr/api/v1/partner/v1/deliveries/cm1x2y3z40000abcd1234efgh
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

curl -s "https://roadmax.kr/api/v1/partner/v1/deliveries?from=2026-10-02T00:00:00%2B09:00&status=assigned&limit=20" \
  -H "X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "data": [
    {
      "id": "cm1x2y3z40000abcd1234efgh",
      "partnerRef": "ORDER-20261002-0001",
      "partnerStoreCode": "STORE-001",
      "status": "assigned",
      "externalChannel": null,
      "externalOrderRef": null,
      "pickup": {
        "name": "쌀통닭 맹동점",
        "address": "충북 음성군 맹동면 혁신로 10",
        "lat": 36.9288,
        "lng": 127.6867
      },
      "dropoff": {
        "address": "충북 음성군 맹동면 혁신로 20 101동 1203호",
        "lat": 36.9301,
        "lng": 127.689
      },
      "customerPhoneMasked": "010-1234-****",
      "memo": "문 앞에 놓아주세요",
      "fee": {
        "deliveryFee": 4300,
        "itemTotal": 15000,
        "currency": "KRW"
      },
      "rider": {
        "name": "김**",
        "phoneMasked": "010-5678-****"
      },
      "createdAt": "2026-10-02T01:23:45.000Z",
      "assignedAt": "2026-10-02T01:24:10.000Z",
      "pickedUpAt": null,
      "deliveredAt": null,
      "cancelledAt": null,
      "updatedAt": "2026-10-02T01:24:10.000Z",
      "sandbox": false
    }
  ],
  "nextCursor": "MTc5...",
  "hasMore": true
}

PATCH https://roadmax.kr/api/v1/partner/v1/deliveries/cm1x2y3z40000abcd1234efgh
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

{
  "dropoff": {
    "address": "충북 음성군 맹동면 혁신로 22",
    "detail": "102동 501호"
  },
  "deliveryFee": 4800,
  "memo": "벨을 눌러 주세요"
}

{
  "data": {
    "id": "cm1x2y3z40000abcd1234efgh",
    "partnerRef": "ORDER-20261002-0001",
    "partnerStoreCode": "STORE-001",
    "status": "pending",
    "externalChannel": null,
    "externalOrderRef": null,
    "pickup": {
      "name": "쌀통닭 맹동점",
      "address": "충북 음성군 맹동면 혁신로 10",
      "lat": 36.9288,
      "lng": 127.6867
    },
    "dropoff": {
      "address": "충북 음성군 맹동면 혁신로 22 102동 501호",
      "lat": 36.9301,
      "lng": 127.689
    },
    "customerPhoneMasked": "010-1234-****",
    "memo": "벨을 눌러 주세요",
    "fee": {
      "deliveryFee": 4800,
      "itemTotal": 15000,
      "currency": "KRW"
    },
    "rider": null,
    "createdAt": "2026-10-02T01:23:45.000Z",
    "assignedAt": null,
    "pickedUpAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "updatedAt": "2026-10-02T01:25:30.000Z",
    "sandbox": false
  },
  "editedFields": [
    "address",
    "memo",
    "deliveryFee"
  ],
  "feeChangePending": false
}

POST https://roadmax.kr/api/v1/partner/v1/deliveries/cm1x2y3z40000abcd1234efgh/cancel
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

{
  "reason": "고객 요청으로 취소"
}

{
  "data": {
    "id": "cm1x2y3z40000abcd1234efgh",
    "partnerRef": "ORDER-20261002-0001",
    "partnerStoreCode": "STORE-001",
    "status": "cancelled",
    "externalChannel": null,
    "externalOrderRef": null,
    "pickup": {
      "name": "쌀통닭 맹동점",
      "address": "충북 음성군 맹동면 혁신로 10",
      "lat": 36.9288,
      "lng": 127.6867
    },
    "dropoff": {
      "address": "충북 음성군 맹동면 혁신로 20 101동 1203호",
      "lat": 36.9301,
      "lng": 127.689
    },
    "customerPhoneMasked": "010-1234-****",
    "memo": "문 앞에 놓아주세요",
    "fee": {
      "deliveryFee": 4300,
      "itemTotal": 15000,
      "currency": "KRW"
    },
    "rider": null,
    "createdAt": "2026-10-02T01:23:45.000Z",
    "assignedAt": "2026-10-02T01:24:10.000Z",
    "pickedUpAt": null,
    "deliveredAt": null,
    "cancelledAt": "2026-10-02T01:30:05.000Z",
    "updatedAt": "2026-10-02T01:30:05.000Z",
    "sandbox": false
  }
}

GET https://roadmax.kr/api/v1/partner/v1/deliveries/cm1x2y3z40000abcd1234efgh/rider-location
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
  "data": {
    "deliveryId": "cm1x2y3z40000abcd1234efgh",
    "status": "assigned",
    "location": {
      "lat": 36.9291,
      "lng": 127.6872,
      "updatedAt": "2026-10-02T01:26:40.000Z"
    }
  }
}

{
  "data": {
    "deliveryId": "cm1x2y3z40000abcd1234efgh",
    "status": "pending",
    "location": null
  }
}

{
  "error": {
    "code": "feature_disabled",
    "message": "라이더 위치 공유는 아직 사용할 수 없습니다. 운영 담당에게 문의해 주세요.",
    "requestId": "req_3f9a1c7d2b8e4a6f10c5d9e2"
  }
}

POST https://roadmax.kr/api/v1/partner/v1/webhooks/test
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

{
  "eventType": "delivery.assigned"
}

{
  "data": [
    {
      "endpointId": "cm1x2y3z40001wxyz5678abcd",
      "eventId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "eventType": "delivery.assigned",
      "delivered": true,
      "statusCode": 200,
      "latencyMs": 124,
      "error": null
    }
  ]
}

POST https://roadmax.kr/api/v1/partner/v1/sandbox/deliveries/cm1x2y3z40000abcd1234efgh/advance
X-RoadMax-Api-Key: rmk_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
  "data": {
    "id": "cm1x2y3z40000abcd1234efgh",
    "partnerRef": "ORDER-20261002-0001",
    "partnerStoreCode": "STORE-001",
    "status": "assigned",
    "externalChannel": null,
    "externalOrderRef": null,
    "pickup": {
      "name": "쌀통닭 맹동점",
      "address": "충북 음성군 맹동면 혁신로 10",
      "lat": 36.9288,
      "lng": 127.6867
    },
    "dropoff": {
      "address": "충북 음성군 맹동면 혁신로 20 101동 1203호",
      "lat": 36.9301,
      "lng": 127.689
    },
    "customerPhoneMasked": "010-1234-****",
    "memo": "문 앞에 놓아주세요",
    "fee": {
      "deliveryFee": 4300,
      "itemTotal": 15000,
      "currency": "KRW"
    },
    "rider": {
      "name": "김**",
      "phoneMasked": "010-5678-****"
    },
    "createdAt": "2026-10-02T01:23:45.000Z",
    "assignedAt": "2026-10-02T01:24:10.000Z",
    "pickedUpAt": null,
    "deliveredAt": null,
    "cancelledAt": null,
    "updatedAt": "2026-10-02T01:24:10.000Z",
    "sandbox": false
  },
  "from": "pending",
  "to": "assigned"
}

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "object": "event",
  "type": "delivery.assigned",
  "apiVersion": "2026-10-02",
  "createdAt": "2026-10-02T01:24:10.000Z",
  "livemode": true,
  "data": {
    "delivery": {
      "id": "cm1x2y3z40000abcd1234efgh",
      "partnerRef": "ORDER-20261002-0001",
      "partnerStoreCode": "STORE-001",
      "status": "assigned",
      "externalChannel": null,
      "externalOrderRef": null,
      "pickup": {
        "name": "쌀통닭 맹동점",
        "address": "충북 음성군 맹동면 혁신로 10",
        "lat": 36.9288,
        "lng": 127.6867
      },
      "dropoff": {
        "address": "충북 음성군 맹동면 혁신로 20 101동 1203호",
        "lat": 36.9301,
        "lng": 127.689
      },
      "customerPhoneMasked": "010-1234-****",
      "memo": "문 앞에 놓아주세요",
      "fee": {
        "deliveryFee": 4300,
        "itemTotal": 15000,
        "currency": "KRW"
      },
      "rider": {
        "name": "김**",
        "phoneMasked": "010-5678-****"
      },
      "createdAt": "2026-10-02T01:23:45.000Z",
      "assignedAt": "2026-10-02T01:24:10.000Z",
      "pickedUpAt": null,
      "deliveredAt": null,
      "cancelledAt": null,
      "updatedAt": "2026-10-02T01:24:10.000Z",
      "sandbox": false
    }
  }
}

{
  "edit": {
    "field": "memo",
    "pending": false,
    "actorRole": "OWNER"
  }
}

{
  "location": {
    "lat": 36.9291,
    "lng": 127.6872,
    "at": "2026-10-02T01:26:40.000Z"
  }
}

export ROADMAX_WEBHOOK_SECRET="whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

// Node.js (Express) — 서명 검증 예제
const crypto = require('crypto');
const express = require('express');
const app = express();

// 서명은 "받은 원문 그대로"에 대해 계산됩니다. JSON 으로 파싱하기 전의 raw body 를 쓰세요.
app.post('/roadmax/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.ROADMAX_WEBHOOK_SECRET; // whsec_...
  const header = req.get('X-RoadMax-Signature') || ''; // t=1790000000,v1=ab12...
  const parts = header.split(',').map((p) => p.split('='));
  const t = Number((parts.find(([k]) => k === 't') || [])[1]);
  const candidates = parts.filter(([k]) => k === 'v1').map(([, v]) => v);

  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.status(400).send('timestamp');

  const raw = req.body.toString('utf8');
  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${t}.${raw}`).digest('hex'));
  const ok = candidates.some((v) => {
    const given = Buffer.from(v || '');
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
  if (!ok) return res.status(400).send('signature');

  const event = JSON.parse(raw);
  // event.id 로 이미 처리한 이벤트인지 확인한 뒤 처리하세요(같은 이벤트가 다시 올 수 있습니다).
  res.sendStatus(200); // 2xx 를 빨리 돌려주세요. 오래 걸리는 일은 큐로 넘기세요.
});

# Python (Flask) — 서명 검증 예제
import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["ROADMAX_WEBHOOK_SECRET"].encode()  # whsec_...


@app.post("/roadmax/webhook")
def webhook():
    raw = request.get_data()  # 파싱하기 전의 원문 바이트
    header = request.headers.get("X-RoadMax-Signature", "")  # t=1790000000,v1=ab12...
    pairs = [p.split("=", 1) for p in header.split(",") if "=" in p]
    try:
        t = int(next((v for k, v in pairs if k == "t"), "0"))
    except ValueError:
        t = 0
    candidates = [v for k, v in pairs if k == "v1"]

    if not t or abs(time.time() - t) > 300:
        abort(400)

    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest().encode()
    if not any(hmac.compare_digest(v.encode(), expected) for v in candidates):
        abort(400)

    event = request.get_json(force=True)
    # event["id"] 로 중복 처리를 막으세요.
    return "", 200

{
  "error": {
    "code": "invalid_api_key",
    "message": "API 키가 올바르지 않습니다.",
    "requestId": "req_3f9a1c7d2b8e4a6f10c5d9e2"
  }
}