Delivery API

배달 주문의 배차 정보를 조회하고, 배차 정보가 바뀔 때 이벤트를 받을 수 있는 API예요. posPluginSdk.delivery.dispatch로 사용해요.

Types

Dispatch

배달 주문의 배차 정보를 나타내는 객체예요.

{
    dispatchId: number;                 // 배차 ID
    orderId: string;                    // 주문 ID
    status: DispatchStatus;             // 배차 상태
    riderStatus: DispatchDeliveryStatus; // 배달 라이더 상태
    provider: DispatchProvider;         // 배차 제공자
}

필드	타입	필수	설명
dispatchId	number	필수	배차 ID
orderId	string	필수	주문 ID
status	DispatchStatus	필수	배차 상태
riderStatus	DispatchDeliveryStatus	필수	배달 라이더 상태
provider	DispatchProvider	필수	배차 제공자

DispatchStatus

배차 상태예요.

type DispatchStatus = 'WAITING_ALLOCATION' | 'ALLOCATION_COMPLETED' | 'CANCEL_WAITING' | 'CANCEL_COMPLETED' | 'COMPLETED';

DispatchDeliveryStatus

배달 라이더의 상태예요.

type DispatchDeliveryStatus = 'NOT_ALLOCATION' | 'ASSIGNED' | 'PICKUP_COMPLETED' | 'DELIVERY_COMPLETED';

DispatchProvider

{
    type: 'SELF' | 'AGENCY';
    id: number;
    code: string;
    name: string;
}

type

값	설명
SELF	자체 라이더
AGENCY	배달대행사

DispatchChangePayload

배차 정보가 바뀌었을 때 update 이벤트로 전달되는 객체예요.

{
    orderId: string;
    dispatchId: number;
}

Methods

getDispatch

주문의 배차 정보를 조회해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const dispatch = await posPluginSdk.delivery.dispatch.getDispatch({ orderId });

Parameters

파라미터	타입	필수	설명
params.orderId	string	O	배차 정보를 조회할 주문의 ID

Response

Promise<Dispatch | null> — 조회한 배차 정보예요. 배차 정보가 없으면 null이에요.

on

배차 정보 변경 이벤트를 수신하기 위한 핸들러를 등록해요.

Parameters

파라미터	타입	필수	설명
event	'update'	O	구독할 이벤트
callback	(payload: DispatchChangePayload) => void	O	이벤트 콜백

Response

반환값이 없어요.

update

• 배차 정보가 바뀌었을 때 실행돼요.
• 콜백에는 orderId와 dispatchId만 전달돼요. 상세 정보는 getDispatch로 조회해주세요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.delivery.dispatch.on('update', ({ orderId, dispatchId }) => {
    // 배차 정보 변경 처리 로직
});

사용 예시

배차 정보 변경 시 최신 정보 조회

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.delivery.dispatch.on('update', async ({ orderId }) => {
    const dispatch = await posPluginSdk.delivery.dispatch.getDispatch({ orderId });
    if (!dispatch) {
        return;
    }
    console.log(`배차 상태: ${dispatch.status}, 라이더 상태: ${dispatch.riderStatus}`);
});