API 사용 안내

개요

세 가지 방식으로 사용할 수 있습니다.

판정 값은 배송완료 여부입니다. 중간 단계는 택배사마다 이름과 단계 수가 달라 하나의 기준으로 통일할 수 없습니다. 해당 값이 필요하면 조회 결과에 포함된 원문을 사용하십시오.

기준 주소

https://tracking.nicereparts.co.kr/api/v1

인증

발급받은 액세스 키를 모든 요청 헤더에 포함하십시오.

X-Api-Key: nt_xxxxxxxxxxxx

다음 형식도 수신합니다.

Authorization: Bearer nt_xxxxxxxxxxxx

키가 일치하지 않으면 401 과 함께 {"result":"fail","message":"사용할 수 없는 키입니다."} 를 반환합니다. 이 경우에도 호출 기록은 남으므로 관리자에게 확인을 요청하실 수 있습니다.

키는 서버에서만 사용하십시오. 화면에 포함하면 누구나 확인할 수 있습니다.

이용 제한

서비스별로 호출 가능한 기능과 월간 호출 건수가 지정됩니다. 발급받은 키로 호출 가능한 기능은 관리자에게 확인하십시오.

두 경우 모두 재시도하지 말고 관리자에게 문의하십시오. 동일한 응답이 반복됩니다.

호출 건수에는 인증에 성공한 요청만 포함됩니다. 키가 일치하지 않아 401 을 받은 요청은 포함되지 않습니다.

운송장 예약

POST https://tracking.nicereparts.co.kr/api/v1/shipments
Content-Type: application/json

{
  "shipments": [
    {"ref": "order-1001", "courier_code": "daesin", "invoice_no": "2140649004805"},
    {"ref": "return-55",  "courier_code": "cj",     "invoice_no": "123456789012"}
  ]
}

한 번에 500건까지 전송할 수 있습니다. 동일한 ref 를 다시 전송하면 운송장 번호가 변경되며, 운송장 번호가 달라지면 기존 조회 결과를 제외하고 처음부터 다시 조회합니다.

{
  "result": "success",
  "accepted": [{"ref": "order-1001", "created": true}],
  "rejected": [{"ref": "return-55", "message": "등록되지 않은 택배사입니다."}]
}

예약 요청은 접수되며 조회는 주기 실행에서 수행됩니다. 응답이 즉시 반환되므로 운송장 번호를 저장하는 위치에서 그대로 호출할 수 있습니다.

예약 건 상태

GET https://tracking.nicereparts.co.kr/api/v1/shipments/{ref}

{
  "result": "success",
  "shipment": {
    "ref": "order-1001",
    "courier_code": "daesin",
    "invoice_no": "2140649004805",
    "status": "delivered",
    "status_label": "배송 완료",
    "delivered_at": "2026-07-15 06:47:00",
    "tracked_at": "2026-09-29 08:50:13",
    "track_count": 3,
    "closed": true,
    "close_reason": "delivered",
    "message": ""
  }
}

이 경로는 저장된 값을 반환하며 택배사를 조회하지 않습니다. 상태 확인을 위해 주기적으로 호출하지 마십시오. 결과는 통보로 수신하십시오.

예약 해제

DELETE https://tracking.nicereparts.co.kr/api/v1/shipments/{ref}

주문 취소 등으로 추가 조회가 불필요한 경우 해제하십시오. 해제하지 않더라도 추적 기간이 지나면 자동으로 종료됩니다.

즉시 조회

예약하지 않고 즉시 택배사에 배송 상태를 조회합니다. 택배사 응답을 대기하므로 응답이 지연됩니다.

POST https://tracking.nicereparts.co.kr/api/v1/track
Content-Type: application/json

{
  "shipments": [
    {"ref": "order-1001", "courier_code": "daesin", "invoice_no": "2140649004805"},
    {"ref": "order-1002", "courier_code": "cj",     "invoice_no": "123456789012"}
  ]
}

ref 는 선택 항목입니다. 입력한 ref 는 결과에 그대로 포함되므로 대상 건을 구분할 수 있습니다.

한 건만 조회할 때에도 동일한 형식으로 전송하십시오. 결과는 건수와 관계없이 동일한 구조로 반환됩니다.

{
  "result": "success",
  "results": [
    {
      "ref": "order-1001",
      "courier_code": "daesin",
      "invoice_no": "2140649004805",
      "status": "delivered",
      "status_label": "배송 완료",
      "delivered_at": "2026-07-15 06:47:00",
      "message": "",
      "current": {"time": "2026-07-15 06:47", "place": "강남지점", "state": "배송완료"},
      "steps": [
        {"time": "2026-07-14 18:20", "place": "서울지점", "state": "집하"},
        {"time": "2026-07-15 06:47", "place": "강남지점", "state": "배송완료"}
      ]
    }
  ],
  "rejected": [{"ref": "order-1002", "message": "등록되지 않은 택배사입니다."}],
  "elapsed_ms": 712
}

current 는 택배사가 표시한 마지막 단계입니다. 판정 상태인 status 와 달리 택배사의 표기를 그대로 반환합니다. 단계를 확인하지 못하면 각 항목이 빈 값으로 반환됩니다.

steps 는 택배사가 표시한 진행 단계입니다. 단계의 명칭과 수는 택배사마다 다르므로 판정에는 사용하지 마시고 화면 표시에만 사용하십시오. 택배사가 단계를 제공하지 않으면 빈 배열이 반환됩니다.

한 번에 10건까지 전송할 수 있습니다. 택배사를 건별로 순차 호출하므로 건수에 비례하여 응답이 지연됩니다. 전체 조회 시간이 20초를 초과하면 남은 건은 조회하지 않고 rejected 에 포함하여 반환합니다. 여러 건을 주기적으로 확인할 때는 예약을 사용하십시오.

택배사 목록

GET https://tracking.nicereparts.co.kr/api/v1/couriers

현재 등록된 택배사입니다. 화면의 선택 항목은 이 경로의 응답으로 구성하고 목록을 서비스에 기재하지 마십시오. 택배사가 추가되어도 화면에 반영되지 않습니다.

자동 확인 택배사는 배송완료를 확인하여 통보합니다. 예약 전용 택배사는 운송장 예약만 처리하며 통보하지 않습니다.

배송완료 통보

배송완료를 확인하면 등록하신 주소로 통보를 전송합니다. 통보 주소를 등록하지 않으시면 전송하지 않습니다.

POST <등록한 주소>
Content-Type: application/json; charset=utf-8
X-Nicetrack-Signature: <서명>

{
  "event": "shipment.delivered",
  "ref": "order-1001",
  "courier_code": "daesin",
  "invoice_no": "2140649004805",
  "status": "delivered",
  "delivered_at": "2026-07-15 06:47:00",
  "sent_at": "2026-09-29T08:50:28+09:00"
}

서명을 확인한 후 처리하십시오. 확인하지 않으면 누구나 해당 주소로 배송완료 통보를 전송하여 주문을 완료 상태로 변경할 수 있습니다.

서명은 본문 전체를 시크릿 키로 해싱하여 생성한 값입니다.

$want = hash_hmac('sha256', file_get_contents('php://input'), $secret);
$got  = $_SERVER['HTTP_X_NICETRACK_SIGNATURE'] ?? '';

if (! hash_equals($want, $got)) {
	http_response_code(400);

	return;
}

응답 상태가 200대가 아니면 실패로 판단하여 다음 실행 시 재전송합니다. 최대 5회까지 시도합니다. 동일한 통보를 두 번 수신해도 문제가 없도록 구현하십시오.

상태 값

추적을 종료한 사유

연동 순서

1. 관리자에게 서비스 등록을 요청한 후 액세스 키와 시크릿 키를 발급받으십시오.
2. 통보를 수신할 주소를 등록하십시오.
3. 운송장을 저장하는 시점에 예약을 호출하십시오. 예약에 실패해도 저장은 완료로 처리하고, 정기 실행 시 재시도하십시오.
4. 통보를 수신하는 주소를 구현하고 서명을 확인한 후 해당 건을 배송완료로 처리하십시오.
5. 관리자가 즉시 확인해야 하는 화면에는 즉시 조회를 연결하십시오.

택배사를 서비스에 추가하지 마십시오. 조회 기능은 이곳에서만 구현합니다. 서비스마다 조회 기능을 두면 택배사가 화면 구성을 변경할 때 모든 서비스를 수정해야 합니다.