# Introduction to Gorela & API Documentation for Order Agency Integration

이 문서는 고릴리(Gorela) 서비스 소개 및 주문 제휴사를 위한 고릴라 연동 API의 전체 목차입니다.

## 목차

- [서비스 소개](#서비스-소개)
- [연동 가이드](#연동-가이드)
- [Common Information](#common-information)
- [Request APIs](#request-apis)
- [Request APIs](#request-apis)
- [Callback APIs](#callback-apis)


---

# 서비스 소개

## 고릴라 중계 서비스란?

고릴라는 배달대행 중계 플랫폼으로 주문 제휴사와 배달대행사의 중앙에서 주문과 배달을 중계합니다. 기본적으로 주문 제휴사는 주문을 접수하고 고릴라는 배달대행사들에게 배달을 요청할 수 있습니다. 반대로 배달대행사에서 발생하는 이벤트들을 주문 제휴사에게 전달할 수 있습니다. 고릴라는 주문 데이터와 배달 데이터가 분리된 구조를 갖고 있어, 1개의 주문은 N개의 배달로 이어지거나 확장될 수 있으며 주문과 배달은 부모와 자식 관계의 구조를 가지고 있습니다.

## 연동 방식

고릴라에서는 API 개발 연동 방식 2가지와 비개발 연동 방식을 제공합니다. 주문 제휴사의 상황과 서비스 목적에 따라 가장 적합한 방식을 검토하여 연동이 진행됩니다.

- 개발 연동: #FOR_DELIVERY, #ACCEPTED_ORDER
- 비개발 연동: #바로고 스토어 프로그램 (바로고에서 제공하는 상점 POS 프로그램 / 모바일 WEB, APP 지원)


### 연동 방식 비교표

| 구분 | 주문 수락의 주체 | 배달 요청의 주체 | 비고 |
| :-- | :-- | :-- | :-- |
| #바로고 스토어 프로그램 | 바로고 스토어 프로그램 | 바로고 스토어 프로그램 | - 선택적 주문 수락(또는 거절) 기능 제공<br>- 선택적 배달 대행(또는 자체 배달) 기능 제공<br>- 배달의민족 및 요기요 연동 기능 제공<br>- 수기 접수 기능 제공 |
| #ACCEPTED_ORDER | 주문 제휴사 | 바로고 스토어 프로그램 | - 선택적으로 배달 대행 요청 또는 자체 배달로 진행할 수 있음<br>- 고릴라로 주문이 들어오기 전 어떠한 프로세스에 의하여 사장님이 주문을 이미 수락한 경우<br>- 보통 주문 제휴사측에 주문을 받기 위한 프로그램은 준비되어 있으나 배달 대행 요청 기능이 없는 경우 |
| #FOR_DELIVERY | 주문 제휴사 | 주문 제휴사 | - 즉시 배달 대행을 요청하는 경우<br>- 보통 주문 제휴사측에 포스 프로그램이 준비되어 있음 |

## 프로세스

### Step 1. 제휴 협의

- 바로고 법인 영업/운영 담당자와 고릴라 연동과 관련된 사전 정책 협의를 진행합니다.
- 연동 전 사전 체크리스트를 작성하여 사전 점검 및 양사간 협의가 완료되어야 합니다.


### Step 2. 연동 개발

- 제휴 협의가 완료되면 고릴라 개발자 사이트에 가입하고 연동 가이드를 참고하여 테스트 연동을 시작합니다.
- (테스트 연동은 제휴 협의와 동시에 진행이 가능합니다)


### Step 3. 서비스 오픈 준비

- 연동 개발이 완료되면 운영 오픈 요청을 통해 서비스 오픈이 가능합니다. 운영 연동 관리가 승인되면 테스트 연동 관리와 동일한 과정을 진행합니다.
- 바로고 법인 영업/운영 담당자와 오픈 일자를 조율하고 운영 방식을 협의합니다.


### Step 4. 운영

- 서비스 오픈 후 운영 상황에서 발생하는 이슈에 대한 대응 및 모니터링 리포트를 제공합니다.

---

# 연동 가이드

## 사전 준비 사항

### 1. 고릴라 개발자 사이트 회원가입
- [연동 관리](https://developer.gorelas.com/linkage) 서비스를 이용하기 위해서는 회원가입이 필요합니다.

### 2. 연동 관리 - 주문 제휴사 등록
- 연동하는 사업체의 고유 식별 정보를 위해 주문 제휴사 정보 등록을 진행합니다.

### 3. 연동 관리 - API Key 발급
- API 요청 인증(Authentication)을 위한 API Key를 발급합니다.

### 4. 기타
- 주문 제휴사 상점 아이디: 주문 제휴사가 관리하는 상점의 고유한 키값입니다. 고릴라 API에서 `"orderAgencyStoreId"` 필드의 값으로 사용됩니다.

주문 제휴사의 상점이 고릴라에게 주문을 전달하거나 주문을 받기 위해서는 항상 고릴라 시스템에 상점 등록과 매핑(연결) 과정이 필요합니다.
매핑은 주문 제휴사의 상점 `(orderAgencyStoreId)`과 고릴라의 상점 `(storeId)`을 1:1로 매칭하는 개념입니다.

🚨 **서비스 오픈 준비 시** 진행되는 **운영 환경 상점 매핑 준비 과정**은 법인 영업/운영 담당자에게 문의 부탁드립니다.

연동 과정 중 어려움이 있다면 고릴라 TAM 공식 이메일 ([tech_poc@barogo.com](mailto:tech_poc@barogo.com)) 또는 [Gitter](https://gitter.im)(채팅) 초대를 요청하여 문의해주시길 바랍니다.

## 도메인 및 Header 설정

### API 도메인
- 테스트
  
  > https://staging-api-interlocker.gorelas.com

- 운영
  
  > https://api-interlocker.gorelas.com

### Header 설정
- 고릴라는 API Key 기반으로 접근 권한을 확인합니다.
  
  > Authorization : Bearer {API_Key}

## 방화벽

### 주문 제휴사 Inbound 방화벽 설정 (= 고릴라 Outbound)
- 해당 설정이 필요하신 경우 고릴라 TAM 공식 이메일 문의 ([tech_poc@barogo.com](mailto:tech_poc@barogo.com))를 통하여 안내해드립니다.
- 참고: 고릴라의 Inbound 방화벽 설정은 없습니다.

바로고 스토어 프로그램을 사용하시는 상점에 방화벽 설정이 필요한 경우 아래 주소들을 허용해 주시길 바랍니다.

- *.gorelas.com
- *.barogo.io
- *.8590.co.kr
- host.s9juso.co.kr
- ajax.googleapis.com
- https://api-whale.barogo.io
- http://barogo.s9juso.co.kr

## API 활용 가이드

고릴라는 다양한 API를 제공하고 있습니다. 연동하는 시나리오에 따라 필수로 연동해야하는 API, 선택적으로 활용할 수 있는 API 등을 가이드합니다.

### 1. 주문 제휴사→고릴라

ACCEPTED_ORDER, FOR_DELIVERY

#### 필수: 배달 가능 여부 및 요금 조회 - [연동 규격](https://developer.gorelas.com/api-doc/request#_고정_요금___의무_수행__주소_기반_-배달_가능_여부_및_요금_조회)
- 주문 접수 전, 배달 가능 여부와 배달 요금을 확인할 수 있습니다. 이에 따라 불필요한 주문 접수를 방지할 수 있으며 고객에게 접수 전, 배달 관련 정보를 제공할 수 있습니다.
- **주문 접수 전 필히 해당 API를 호출**하여 활용해주세요.

#### 필수: 주문 접수 - [연동 규격](https://developer.gorelas.com/api-doc/request#_고정_요금___의무_수행__주소_기반_-주문_접수)
- 당연하게도 필수로 연동해야하는 주문 접수입니다만, 몇가지 특이사항이 있습니다.
- 요청값 중 픽업 희망 일시(pickupWishAt)는 픽업을 "희망"하는 시간입니다. (사장님이) 희망을 하는 시간이기에 실제로 픽업이 요청한 시간에 이루어지지 않을 수 있습니다.
- 응답값 중 **픽업 예상 일시(pickupExpectedAt)**는 픽업이 "예상"되는 시간입니다. 예상되는 시간이기에 실제로 픽업이 해당 시간에 이루어지지 않을 수 있습니다. 
  배달 지연 상황과 픽업 희망 시간에 따라 이 값은 달라질 수 있습니다.

  🚨 해당 값을 사장님이 확인할 수 없으면 픽업 희망 시간만 알고 실제 픽업이 예상되는 시간은 인지하지 못하여 운영상 문제가 발생될 가능성이 높습니다. 꼭 해당 값을 프로그램 등에 노출해주세요.

- 주문 금액은 총 상품 금액(**총 결제 금액**)과 고객이 결제한 금액(**실제 결제 금액**), 라이더가 결제해야할 금액(**라이더 결제 금액**)으로 구분됩니다.
  총 결제 금액(**totalPayPrice**)은 총 상품 금액(할인 등이 포함되지 않은)을 의미하며, 따라서 실제 결제 금액과 다를 수 있습니다.

- 상품은 "본 상품"과 "옵션 상품"의 결합으로 구분됩니다. 따라서 **"본 상품"이 같아도 "옵션 상품"이 다르면 별개의 상품**으로 등록해주세요.
- 고객에게 받는 "배달팁" 항목은 상품 종류의 하나로 취급됩니다. **"배달팁"이 있는 경우 상품 종류 "DELIVERY_TIP"**으로 등록해주세요.
- 상품 단위별 상품 총 금액(**orderProducts.totalPrice**)

  상품 총 금액(본 상품의 금액과 옵션 금액의 합계)은 아래 계산식을 참고하시길 바랍니다.
  
  **product.totalPrice = (product.unitPrice + (option.unitPrice * option.quantity)) * product.quantity**
  
  예시) 본 상품: 부대찌개 (20,000원) 2개 / 옵션1: 라면사리 (1,500원) 2개 / 옵션2: 우동사리 (2,000원) 1개
  
  - 상품 총 금액(product.totalPrice): (20000 + (1500 * 2) + (2000 * 1)) * 2 = 50000
  - 본 상품 단가(product.unitPrice): 20000
  - 본 상품 수량(product.quantity): 2
  - 옵션1 단가(option.unitPrice): 1500
  - 옵션1 수량(option.quantity): 2
  - 옵션2 단가(option.unitPrice): 2000
  - 옵션2 수량(option.quantity): 1

- **비대면 배달**을 요구하는 경우 꼭 **"isUntact"** 필드를 이용해주시길 바랍니다. **메모의 내용으로는 비대면 배달 수행이 보장되지 않습니다**.
- **예약 주문**을 운영하는 경우 예약 시간으로부터 몇 분전에 배달을 노출시켜 수행을 시작할지 설정하는 값에 대한 협의가 필요합니다. 기본값은 60분이며 문의를 통하여 조정할 수 있습니다.
- 주문 접수 시 받은 **주소는 고릴라 내부 정책에 따라 보정이 될 수 있습니다.** 비정상적인 주소는 배달 수행 과정 중 문제를 일으킬 확률이 높으며 이에 대한 책임이 주문 제휴사측에 전달될 수 있습니다.
- 주문자(고객)의 요청 사항(**ordererOrderMemo**) 미전달 시 배달 수행 과정에서 문제가 발생될 수 있습니다.

  Ex1. 공동현관 비밀번호 #1234 입니다. 부재시 문 앞에 놔주세요.
  &gt; 세대 현관에서 초인종/노크 했음에도 수령자가 나오지 않거나 연락을 받지 않으면 배달 상품이 상점으로 회수될 수도 있습니다.
  
  Ex.2: 필히! 1번 게이트를 통해 경비실 호출 후 지하 주차장으로 들어와 주셔야 합니다.
  &gt; 지상 통로가 없거나, 지하 주차장 내부가 연결되지 않은 곳이 존재할 수 있어 배달 시간이 상당히 지연될 수 있습니다.

#### 필수: 주문 취소 - [연동 규격](https://developer.gorelas.com/api-doc/request#_주문_취소)
- 주문 제휴사에서 주문의 취소를 요청합니다. 단, 정책에 따라 취소 요청이 **거절**될 수 있으며 배달 진행 상태에 따라 **취소 수수료**가 발생될 수 있습니다.
- 주문 제휴사측에 주문 취소 기능이 존재하는 경우 구현이 필요하며, 구현 시 **불필요한 통신과 문의를 방지하기 위해 배달 진행 상태에 따른 버튼 노출 정책이 필요**합니다.

#### 옵션
- 상점 예치금 조회
- 배달 수행 상태 조회
- 주문 수정 (픽업 희망 일시 / 드랍지 / 결제 및 상품 / 메모 / 연락처)
- 주문 조회 (목록 / 상세)

### 2. 고릴라→주문 제휴사

특정 콜백에 대한 연동 여부와 상관없이 **고릴라는 기본적으로 발생되는 모든 콜백을 주문 제휴사에게 전달 합니다.**
이에 주문 제휴사는 최초 연동 개발 이후에도 시점에 관계 없이 선택적으로 콜백 연동을 추가할 수 있습니다. 연동한 콜백 이외에는 **404(Not Found)**로 응답해주시길 바랍니다.

#### FOR_DELIVERY

##### 필수: 주문 상태 변경 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_주문_상태_변경)
- 배달대행사에서 배달의 상태가 변경되고 최종적으로 주문의 상태(완료/취소)가 변경되었을 때 전달합니다.
- 고릴라 중계 서비스에서는 다양한 이유로 주문 1건에 배달 N건이 발생될 수 있습니다. 따라서 주문 완료/취소와 각 배달의 완료/취소는 상태가 별도로 관리되며, 특정 주문의 모든 배달이 종결(거절, 완료, 취소)되어야 주문도 종결(완료, 취소)됩니다.
- 상점 또는 고객이 최종적으로 주문 상태를 확인할 수 있도록 해당 콜백을 연동하여 필수로 제공해야합니다.

##### 필수: 픽업 예상 일시 변경 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_배달_정보-픽업_예상_일시_변경)
- 라이더가 픽업지에 도착하는 시간을 변경하면 발생합니다.
- 배달 상황에 따라 해당 시간이 지연될 수 있으므로, 해당 콜백을 연동하여 상점이 인지할 수 있도록 변경된 시간을 프로그램 등에 필히 노출해야합니다.

##### 권장: 배달 상태 변경 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_배달_상태_변경) / 배달 취소 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_배달_취소)
- 배달대행사에서 배달의 상태가 변경되었을 때 발생합니다.
- 주문 1 : N 배달 개념에 따라 각 배달에 대한 독립적인 콜백을 전달합니다.
- 배차 / 배차 취소 / 배차 변경 / 픽업지 도착 / 픽업 완료 / 드랍 완료 / 취소
- 배달 취소의 경우에는 일반적으로 발생하지는 않지만, 부득이한 경우 이해관계자들과 소통 후 협의를 거쳐 취소가 진행됩니다. 이러한 상황은 운영 중 발생하지 않을 수도 없는 일이기에 "주문 상태 변경"을 필히 연동하고 N 배달까지 관리한다면 배달 취소도 함께 연동하여 프로그램 등에 취소 상태를 꼭 인지시켜야합니다.

##### 권장: 카드 결제 내역 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_카드_결제_내역) / 현금영수증 발급 내역 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_현금영수증_발급_내역)
- 해당 콜백은 배달이 완료되는 시점에서 현장에서 카드 결제 또는 현금영수증 발급이 이루어지면 전달됩니다.
- 전달하는 결제 내역은 항상 누적된(취소 포함) 전체 목록입니다. 결제 건 단위만을 전달하지 않습니다.

  결제가 총 2건이 발생되었다면, 처음에 1건이 전달되고 그 다음에 이전의 1건을 포함한 전체 2건을 전달합니다.
  결제가 총 2건이 발생되었고 첫번째 결제가 취소되었다면, 처음에 결제 1건이 전달되고 그 다음에 두번째 결제를 포함한 2건이 전달되고 그 다음에 첫번째 결제가 취소된 총 3건을 전달합니다.

- 해당 콜백은 주문/배달 상태 완료 콜백과 순서가 보장되지 않습니다. 현장의 결제는 배달이 완료되는 시점에 진행되긴 하지만 꼭 완료 후에 결제를 한다는 보장이 없기 때문입니다.

##### 권장: 배달 요금 변경 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_배달_정보-배달_요금_변경)
- 해당 콜백은 배달 수행 중 어떠한 사유로 인해 배달 요금이 변경되는 경우 발생됩니다.
- 최초 접수 시 확인된 배달 요금이 변경되는 상황이오니 해당 콜백을 연동하여 프로그램 등에 적용이 필요합니다.

#### ACCEPTED_ORDER

##### 필수: 주문 상태 변경 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_주문_상태_변경)
- 배달대행사에서 배달의 상태가 변경되고 최종적으로 주문의 상태(완료/취소)가 변경되었을 때 전달합니다.
- 고릴라 중계 서비스에서는 다양한 이유로 주문 1건에 배달 N건이 발생될 수 있습니다. 따라서 주문 완료/취소와 각 배달의 완료/취소는 상태가 별도로 관리되며, 특정 주문의 모든 배달이 종결(거절, 완료, 취소)되어야 주문도 종결(완료, 취소)됩니다.
- 상점 또는 고객이 최종적으로 주문 상태를 확인할 수 있도록 해당 콜백을 연동하여 필수로 제공해야합니다.

##### 권장: 배달 접수 - [연동 규격](https://developer.gorelas.com/api-doc/callback#_배달_접수)
- 사장님이 바로고 스토어 프로그램을 사용하여 배달대행사에 배달을 요청하고 접수가 되었을 때 발생됩니다.
- 상점에서 자체 배달을 선택한 경우에는 발생되지 않습니다.

##### 옵션: 배달 접수
- 배달 상태 변경
- 배달대행사 배달 취소 
- 픽업 예상 일시 변경
- 배달 요금 변경
- 드랍지 변경
- 배달 중단, 해제 알림
- 배달 추가 알림
- 배달대행사 결제, 현금영수증 내역
- 상점 예치금 충전 알림

## 고릴라 컨트롤룸 (Admin)

주문 제휴사의 운영 관리자는 고릴라 컨트롤룸을 통해 모든 주문과 상점 등을 관리하고 다양한 기능을 이용할 수 있습니다. [테스트 환경](https://staging-admin.gorelas.com) / [운영 환경](https://admin.gorelas.com)

---

## Common Information

> API를 연동함에 있어서 공통적으로 해당되는 내용을 안내합니다.

### [API 연동 규격 - 공통](./common-doc.md)

- **1. 참고**

  ### < 권장사항 >  
  - 연동사측 API 응답 타임아웃은 최소 12000ms\(12초\) 이상을 권장합니다.  
  - 연동사측이 실패 응답을 받았을 때 즉시 재시도 하는 것은 지양합니다.         최소 10000ms\(10초\) 이상 간격을 두고 재시도 해주시길 바랍니다.         \(모든 API에 해당\)  
  ### < 콜백 정책 >  
  - 콜백 전달 시 응답은 최대 3초까지만 대기합니다. 3초를 초과하면 타임아웃으로 처리됩니다.  
  - 타임아웃 발생 시 총 3회 재시도합니다. \(2초 / 18초 / 50초\)  
  ### < 단위 >  
  - 날짜 및 시간 형식: **Timestamp\(GMT\+00:00\)** / Millisecond 단위까지 표시  
  - 거리 단위: **Meter\(m\)**  
  - 좌표 체계: **WGS84** / 소수점 이하 6 자릿수 이상 표시

- **2. 상태 코드**

  - API 요청에 대한 처리 결과는 응답 데이터의 **HTTP 상태 코드\(statusCode\)**로 확인할 수 있습니다.  
  - 에러가 발생된 경우 그 내용은 응답 데이터의 **에러 코드\(errorCode\)**와 **에러 메세지\(message\)**를 통해 확인할 수 있습니다.  
  ### 성공 응답  
  |  상태 코드 \(statusCode\) | 설명 |  
  | ----- | ----- |  
  | 200 | 요청한 작업이 성공했을 때 응답됩니다. |  
  | 201 | 데이터 생성에 성공했을 때 응답됩니다. |  
  | 204 | 데이터 삭제에 성공했을 때 응답됩니다. |  
  | 207 | 요청한 작업이 일부만 성공했을 때 응답됩니다. |  
  ### 성공 응답 예시  
  ```  
  {  
  "statusCode": 200,  
  "data": {  
  ...  
  }  
  }  
  ```     
  ### 에러 응답  
  |  상태 코드 \(statusCode\) | 에러 카테고리 \(errorCategory\) | 에러 코드 \(errorCode\) | 설명 |  
  | ----- | ----- | ----- | ----- |  
  | 400 | BAD_REQUEST | SCHEMA_VALIDATE | 요청 데이터의 검증에 통과하지 못한 경우 |  
  | 400 | BAD_REQUEST | NOT_ALLOW | 허용되지 않는 작업이 요청된 경우 |  
  | 400 | BAD_REQUEST | REQUEST_JSON_PARSING | 요청 데이터의 Json 형태가 잘못된 경우 |  
  | 400 | BAD_REQUEST | INVALID_INPUT | 유효하지 않은 정보로 요청한 경우 |  
  | 400 | BAD_REQUEST | \*NONE_DELIVERY_AGENCY_MAPPING | 배달대행사 매핑이 존재하지 않거나 매핑 상태가 모두 중지인 경우 |  
  | 400 | BAD_REQUEST | \*NONE_ORDER_AGENCY_MAPPING | 주문 제휴사 매핑이 존재하지 않거나 매핑 상태가 중지인 경우 |  
  | 401 | UNAUTHORIZED | EXPIRED_API_KEY | API Key의 유효기간이 만료되었거나, 삭제된 경우 |  
  | 401 | UNAUTHORIZED | VERIFY_API_KEY_FAIL | API Key 검증에 실패한 경우 |  
  | 401 | UNAUTHORIZED | ROLE_DENY | \(사용할 수 없는\) 권한이 없는 API를 요청한 경우 |  
  | 404 | NOT_FOUND | NOT_FOUND_API | 존재하지 않는 API를 요청한 경우 |  
  | 404 | NOT_FOUND | NOT_FOUND_RESOURCE | 해당 리소스\(데이터\)가 존재하지 않는 경우 |  
  | 404 | NOT_FOUND | EXTERNAL_NOT_FOUND_RESOURCE | 배달대행사에 해당 리소스\(데이터\)가 존재하지 않는 경우 |  
  | 409 | CONFLICT | DUPLICATED_ID | 생성하려는 데이터의 아이디가 이미 존재하는 경우 |  
  | 409 | CONFLICT | DUPLICATED | 생성하려는 데이터가 이미 존재하는 경우 |  
  | 429 | TOO_MANY_REQUESTS | TOO_MANY_REQUESTS | API를 요청하는 횟수가 제한을 초과한 경우 |  
  | 500 | INTERNAL_SERVER_ERROR | DB_FAIL | 데이터베이스에서 에러가 발생한 경우 |  
  | 500 | INTERNAL_SERVER_ERROR | JSON_PARSING | 요청 데이터 처리 중 Json 형태가 잘못된 경우 |  
  | 500 | INTERNAL_SERVER_ERROR | SERVER_ERROR | 알 수 없는 서버 에러가 발생한 경우 |  
  | 502 | BAD_GATEWAY | EXTERNAL_SERVER_ERROR | 배달대행사 서버에서 에러가 발생한 경우 |  
  | 502 | BAD_GATEWAY | NOT_ALLOW_EXTERNAL | 배달대행사에 허용되지 않는 작업이 요청되어 거절된 경우 |  
  | 502 | BAD_GATEWAY | MAINTENANCE_TIME | 서비스 점검 시간 |  
  | 503 | SERVICE_UNAVAILABLE | SERVICE_UNAVAILABLE | 서비스 이용 불가 상태인 경우 |  
  | 503 | SERVICE_UNAVAILABLE | EXTERNAL_SERVICE_UNAVAILABLE | 배달대행사 서비스 이용 불가 상태인 경우 |  
  | 504 | GATEWAY_TIMEOUT | GATEWAY_TIMEOUT | 내부 서버간 통신 중 타임아웃이 발생한 경우 |  
  | 504 | GATEWAY_TIMEOUT | EXTERNAL_SERVER_TIMEOUT | 외부\(배달대행사 등\) 서버간 통신 중 타임아웃이 발생한 경우 |  
  ### 에러 응답 예시  
  ```  
  {  
  "statusCode": 400,  
  "error": {  
  "category": "BAD_REQUEST",  
  "errorCode": "SCHEMA_VALIDATE",  
  "message": "should have required property 'orderAgencyId'"  
  }  
  }  
  ```



---

## Request APIs

> 주문 제휴사에서 고릴라에게 요청할 수 있는 API들에 대한 안내입니다.

### 1. [고정 요금 | 의무 수행 (주소 기반)](./request-1.md)

> \***고릴라**에서 **배달 요금을 결정**하여, **배달 수행**에 **의무성**을 부여하는 주문입니다.  
> 따라서 배달 수행 중 특별한 문제만 발생되지 않는다면, 배달 완료를 책임집니다.  
>
>   \*별도의 상점 등록과 매핑 없이 **픽업지**와 **드랍지**를 입력하여 주문을 접수할 수 있는 **주소 기반** 연동 방식입니다.  


- **배달 가능 여부 및 요금 조회**
- **주문 접수**

### 2. [고정 요금 | 의무 수행 (상점 기반)](./request-2.md)

> \***고릴라**에서 **배달 요금을 결정**하여, **배달 수행**에 **의무성**을 부여하는 주문입니다.  
>  따라서 배달 수행 중 특별한 문제만 발생되지 않는다면, 배달 완료를 책임집니다.  
>
>   \*별도의 **상점 등록**과 **매핑** 후 주문을 접수할 수 있는 **상점 기반** 연동 방식입니다.  


- **배달 가능 여부 및 요금 조회**
- **주문 접수**

### 3. [유연 요금 | 자율 수행 (주소 기반)](./request-3.md)

> \***주문 제휴사\(상점\)**에서 **배달 요금을 결정**하여, **배달 수행**에 **자율성**을 부여하는 주문입니다.  
>  따라서 배달 요금이 합리적이지 않은 경우, 라이더 배차가 원활하지 않아 일정 시간 후 자동으로 취소될 수 있습니다.  
>
>   \*별도의 상점 등록과 매핑 없이 **픽업지**와 **드랍지**를 입력하여 주문을 접수할 수 있는 **주소 기반** 연동 방식입니다.  


- **배달 가능 여부 및 요금 조회**
- **주문 접수**

### 4. [유연 요금 | 자율 수행 (상점 기반)](./request-4.md)

> \***주문 제휴사\(상점\)**에서 **배달 요금을 결정**하여, **배달 수행**에 **자율성**을 부여하는 주문입니다.  
>  따라서 배달 요금이 합리적이지 않은 경우, 라이더 배차가 원활하지 않아 일정 시간 후 자동으로 취소될 수 있습니다.  
>
>   \*별도의 **상점 등록**과 **매핑** 후 주문을 접수할 수 있는 **상점 기반** 연동 방식입니다.  


- **배달 가능 여부 및 요금 조회**
- **주문 접수**

### 5. [주문 접수 - ACCEPTED_ORDER](./request-5.md)

> **바로고 스토어 프로그램**을 이용하여 **배달 요청**을 할 수 있는 주문 접수 방식입니다.  



### 6. [주문 조회](./request-6.md)

> 접수된 주문들에 관한 정보를 조회할 수 있습니다.  
>   무분별한 조회\(Polling\)가 감지되는 경우 요청이 제한 될 수 있습니다.  
>
>   *\(정렬은 주문 접수 기준 최신순\)*  


- **주문 목록 조회**
- **단일 주문 조회**

### 7. [주문 취소](./request-7.md)

> 접수한 주문의 취소를 요청할 수 있는 API  
>
>   운영 정책에 따라 취소 요청이 거절될 수 있습니다.  
>
>   접수 실패된 주문은 취소 요청을 할 수 없습니다.  



### 8. [주문 수정](./request-8.md)

> 주문에 관한 정보를 수정할 수 있는 API 목록  


- **픽업 희망 일시 수정**

  주문의 픽업 희망 일시 수정을 요청합니다.  
    배달의 상태가 배차\(ALLOCATED\)로 변경되기 전에 요청이 가능합니다.

- **드랍지 수정**

  주문의 드랍지 정보 수정을 요청합니다.  
  수정 요청에 성공한 경우 **배달 요금이 변경되었을 수 있습니다. 따라서 응답값을 확인하여 변경된 배달 요금을 반영하시길 바랍니다.**  
  배달의 상태가 픽업 완료\(PICKUP_FINISHED\)로 변경되기 전에 요청이 가능합니다.

- **결제 및 상품 정보 수정**

  주문의 결제 및 상품 정보 수정을 요청합니다.  
    수정 요청에 성공한 경우 **배달 요금이 변경되었을 수 있습니다. 따라서 응답값을 확인하여 변경된 배달 요금을 반영하시길 바랍니다.**  
    배달의 상태가 종결\(완료/취소\) 상태로 변경되기 전에 요청이 가능합니다.

- **메모 정보 수정**

  주문의 메모 정보 수정을 요청합니다.

- **연락처 정보 수정**

  주문의 연락처 정보 수정을 요청합니다.

- **요청 배달 요금 수정**

  주문의 배달 요금 수정을 요청합니다.  
    **유연 요금 \| 자율 수행**으로 요청된 주문만 가능하며 배달이 **배차되기 전**에만 가능합니다.


### 9. [상점 예치금 조회](./request-9.md)

> 상점의 예치금\(Cash, Money\) 잔액을 조회할 수 있는 API  
>
>   *\*예치금 충전을 위한 가상 계좌가 발급되지 않는 상점인 경우 계좌 정보가 없을 수 있습니다.*  



### 10. [배달대행사 상태 조회](./request-10.md)

> 배달대행사의 현재 배달 수행 상태를 조회할 수 있는 API  
>
>   연동된 모든 배달대행사의 상태가 조회됩니다.  



### 11. [상품 준비 완료](./request-11.md)

> 주소 기반 주문에서 라이더에게 상품이 준비되었음을 알려줄 수 있는 API  
>
>   배달상태가 픽업 완료\(PICKUP_FINISHED\)로 변경되기 전에 요청이 가능합니다.  



### 12. [상점 매핑](./request-12.md)

> 상점 매핑을 위한 API 목록  


- **상점 목록 조회**

  매핑 대상 상점을 찾기 위해 상점을 검색합니다.

- **상점 매핑 등록**

  주문 제휴사 상점과 고릴라 상점 간에 매핑을 등록합니다.

- **상점 매핑 해제**

  주문 제휴사 상점과 고릴라 상점 간에 매핑을 해제합니다.

- **상점 매핑 조회**

  주문 제휴사 상점 아이디로 매핑되어 있는 목록을 조회합니다.


### 13. [상점 권역/구역 조회](./request-13.md)

> 상점에 설정된 배달 가능 권역, 배달 불가 구역, 할증 구역의 목록을 조회합니다.  





---

## Callback APIs

> 고릴라에서 주문 제휴사로 콜백(알림)을 전달하는 API들에 대한 안내입니다.

### 1. [배달 상태 변경](./callback-1.md)

> 접수한 주문이 배차 / 배차 취소 / 배차 변경 / 픽업지 도착 / 픽업 완료 되었을 때 발생됩니다.  
>
> 완료 또는 취소는 별도의 주문 상태 변경 콜백으로 전달됩니다.  



### 2. [주문 상태 변경](./callback-2.md)

> 접수한 주문이 완료 또는 취소되었을 때 발생됩니다.  
>
> 배차 / 배차 취소 / 배차 변경 / 픽업지 도착 / 픽업 완료는 별도의 배달 상태 변경 콜백으로 전달됩니다.  



### 3. [드랍지 곧 도착 알림](./callback-3.md)

> 픽업 완료 이후 라이더가 드랍지 100m 이내 접근 시 발생하는 콜백 API  



### 4. [배달 접수](./callback-4.md)

> 바로고 스토어 프로그램\(상점\)에서 ACCEPTED_ORDER 주문에 대하여 배달대행사에 배달을 요청하고 성공적으로 접수가 이루어진 경우 발생되는 콜백 API  
>
> \(상점에서 자체 배달을 선택한 경우 발생되지 않음\)  



### 5. [배달 정보](./callback-5.md)

> 배달에 관한 정보가 변경되었을 때 발생되는 콜백 API 목록  


- **픽업 예상 일시 변경**

  배달 수행 중 픽업 예상 일시가 변경되는 경우 발생되는 콜백 API

- **드랍 예상 일시 변경**

  배달 수행 중 드랍 예상 일시가 변경되는 경우 발생되는 콜백 API

- **배달 요금 변경**

  배달 접수 이후 배달 요금이 변경되는 경우 발생되는 콜백 API

- **드랍지 변경**

  배달 접수 이후 드랍 주소가 변경되는 경우 발생되는 콜백 API


### 6. [배달 중단 / 해제](./callback-6.md)

> 배달대행사에서 어떠한 사유\(기상 악화 등\)로 인해 배달 수행을 중단하는 경우 발생되는 콜백 API  
>
> 그리고 배달 수행 중단 후 해제가 되었을 때 발생되는 콜백 API  


- **배달 중단**

  배달 수행 중단 후에는 해당하는 상점들의 주문 접수가 중단됩니다.  
  \(\*배달 중단 상점 목록은 20개 단위로 분할하여 알림 전송\)

- **배달 중단 해제**

  배달 수행 중단 해제 후에는 해당하는 상점들의 주문 접수가 정상화됩니다.  
    \(\*배달 중단 해제 상점 목록은 20개 단위로 분할하여 알림 전송\)


### 7. [주문 결제 정보 변경](./callback-7.md)

> 주문의 결제 정보가 변경되는 경우 발생되는 콜백 API  



### 8. [카드 결제 내역](./callback-8.md)

> 배달이 수행되고 현장에서 카드 결제가 이루어졌을 때 발생하는 콜백 API  
>
> 전달하는 카드 결제 내역은 항상 누적된\(취소 포함\) 전체 목록입니다. 결제 건 단위만을 전달하지 않습니다.  
> \(예제: 결제A 승인 1건 → 결제A 승인 1건 \+ 결제A 취소 1건 → 결제A 승인 1건 \+ 결제A 취소 1건 \+ 결제B 승인 1건\)  



### 9. [현금영수증 발급 내역](./callback-9.md)

> 배달이 수행되고 현장에서 현금영수증 발급이 이루어졌을 때 발생하는 콜백 API  
>
> 전달하는 현금영수증 내역은 항상 누적된\(취소 포함\) 전체 목록입니다. 발급 건 단위만을 전달하지 않습니다.  
> \(예제: 발급A 승인 1건 → 발급A 승인 1건 \+ 발급A 취소 1건 → 발급A 승인 1건 \+ 발급A 취소 1건 \+ 발급B 승인 1건\)  



### 10. [상점 예치금 충전](./callback-10.md)

> 상점의 예치금\(Cash, Money\) 계좌에 금액이 충전\(입금\)되었을 때 발생되는 콜백 API  



### 11. [상점 권역/구역 정보](./callback-11.md)

> 상점의 권역/구역 정보가 생성, 수정, 삭제되었을 때 발생되는 콜백 API 목록  


- **권역/구역 생성**

  상점의 권역/구역이 생성되는 경우 발생되는 콜백 API

- **권역/구역 수정**

  상점의 권역/구역이 수정되는 경우 발생되는 콜백 API

- **권역/구역 삭제**

  상점의 권역/구역이 삭제되는 경우 발생되는 콜백 API


### 12. [주문 제휴사 권역/구역 정보](./callback-12.md)

> 주문 제휴사의 권역/구역 정보가 생성, 수정, 삭제되었을 때 발생되는 콜백 API 목록  


- **권역/구역 생성**

  주문 제휴사의 권역/구역이 생성되는 경우 발생되는 콜백 API

- **권역/구역 수정**

  주문 제휴사의 권역/구역이 수정되는 경우 발생되는 콜백 API

- **권역/구역 삭제**

  주문 제휴사의 권역/구역이 삭제되는 경우 발생되는 콜백 API




---

*Last updated: 2026-06-23*