연동 및 API
OptiRoutes는 이미 운영 중인 시스템과 연결됩니다. 주문은 Excel이나 CSV 파일, FTP나 SFTP, 또는 보안 파일 API로 들어오며, 서명된 배송 확인서, 경로 내보내기, 리포트도 같은 방식으로 돌아갑니다. 리포트 API는 BI 도구에 데이터를 제공하고, 지정한 웹 주소로 배송 보고와 경로 내보내기를 실시간으로 받을 수 있습니다.
업데이트:
OptiRoutes는 어떤 연동을 제공하나요?
| 필요 | OptiRoutes의 방식 |
|---|---|
| 그날의 주문 불러오기 | Excel 또는 CSV 업로드, FTP·SFTP·파일 API에서 CSV, JSON, 고정 폭 TXT로 자동 불러오기. |
| 서명된 POD 수집 | 날짜별 또는 주문별 파일 API 호출, 또는 하루 ZIP 하나. 이메일 사본도 제공. |
| 자사 시스템으로 경로 전송 | CSV, XLSX, XML, JSON, TXT 형식의 경로 내보내기를 파일, 귀사 FTP, 회사 폴더, 웹 주소로. |
| BI나 ERP로 리포트 | 리포트 API: 주문, 경로, 기사, 고객, POD, 일일 배송 요약. |
| 배송마다 반응하기 | 보고가 생길 때마다 모두 받는 배송 보고 수신 주소. |
| 서비스 결제 | 선불 충전과 자동 충전을 위한 Stripe Checkout. |
파일, FTP, SFTP로 주문 불러오기
가장 간단한 연동은 귀사 시스템이 이미 내보내는 파일입니다. 주문 화면의 배송 불러오기는 Excel 또는 CSV 파일을 읽습니다. 주소, 고객명, 주문 번호, 수량 등 시스템 필드마다 귀사의 열 이름을 한 번만 매핑하면, 이후 모든 파일이 같은 방식으로 불러와집니다. 고정 폭 TXT 파일은 열 이름 대신 문자 위치를 지정합니다. 비고의 표시 단어로 행을 건너뛸 수 있고, 두 번째 표시 단어로 주소를 대체할 수 있으며, 기존 주문 번호를 업데이트할지 새로 추가할지 정할 수 있습니다.
사람의 손을 덜려면 설정에서 자동 불러오기 방식을 선택하세요.
- OptiRoutes 파일 서버 — 귀사 시스템이 날짜로 이름 붙인 일일 파일을 FTP 서버 또는 암호화된 SFTP 서버의 회사 폴더에 넣습니다.
- 귀사의 자체 FTP 서버 — OptiRoutes가 제공받은 사용자로 접속해 오늘 날짜로 이름 붙은 파일이나 가장 최근에 업데이트된 파일을 불러옵니다.
- 자동 가져오기 및 내보내기 — 주문이 자동으로 불러와지고 경로까지 계획되어, 클릭이 필요 없습니다.
- 파일 API — 귀사 소프트웨어가 HTTPS로 주문 파일을 업로드합니다. 아래에서 설명합니다.
고객 화면에서 고객 번호, 이름, 주소, 정차 시간, 영업 시작·종료 시간이 담긴 Excel 또는 CSV 파일로 고객과 시간대를 생성하거나 업데이트할 수 있습니다.
파일 API: 주문은 들여오고, POD와 리포트는 내보내고
OptiRoutes의 모든 회사에는 전용 파일 폴더가 있습니다. 불러오는 주문, 사진과 서명이 담긴 서명된 배송 확인서, 경로 내보내기, 일 마감 리포트입니다. 파일 API를 사용하면 귀사 시스템이 중간에 FTP 서버 없이 HTTPS로 이 폴더를 직접 읽고 쓸 수 있습니다. 회사 관리자가 설정 → API 및 파일에서 FTP와 API를 전환하고 키를 생성합니다. 지원팀에 요청할 필요가 없으며, 신규 회사는 API로 시작합니다.
| 폴더 | 내용 | 작성 주체 |
|---|---|---|
| orders_files/ | 일일 주문 파일과 경로 내보내기. | 귀사(주문), OptiRoutes(내보내기) |
| pod/YYYY/MM/DD/ | 그날의 서명된 POD: 서명된 PDF, 서명, 사진. | OptiRoutes |
| pod/ | 기사 앱에서 서명받을 원본 배송 확인서, 주문 번호당 PDF 하나. | 귀사 |
| reports/YYYY/MM/ | 일 마감 리포트와 반품 리포트. | OptiRoutes |
| podBaseFile/ | POD 기본 양식. | 귀사 |
| inbox/ | 전달하고 싶은 파일을 위한 자유 폴더. | 귀사 |
호출에는 키 확인, 폴더 목록 조회, 다운로드, 업로드(파일당 최대 50MB), 직접 업로드한 파일 삭제, 주문과 종류별로 하루의 POD 파일 목록 조회, 하루의 모든 POD 파일을 ZIP 하나로 다운로드가 포함됩니다. 가이드에는 Python, C#, Node.js 코드 예제와, 귀사 서버의 폴더를 회사 폴더와 동기화하는 PowerShell 스크립트가 있어 FTP에 익숙한 팀도 같은 방식으로 계속 일할 수 있습니다. 파일 API 가이드에서 확인하세요.
API 키는 어떻게 보호되나요?
- 최소 권한 — 각 키에는 필요한 권한만 부여됩니다. 서명된 POD만, 모든 파일 읽기, 또는 주문 및 inbox 파일 업로드.
- 허용 주소 — 키를 귀사 서버의 고정 IP 주소로 제한할 수 있습니다.
- 만료와 교체 — 키는 일정 일수 후 만료되도록 할 수 있습니다. 새 키를 만들어 전환한 뒤 이전 키를 폐기하면 중단 없이 교체됩니다.
- 즉시 폐기 — 폐기된 키는 30초 안에 작동을 멈춥니다.
- 감사 기록 — 모든 호출이 시간, 주소, 파일, 응답과 함께 기록되어 관리자에게 표시됩니다.
- 안전한 보관 — OptiRoutes는 각 키의 SHA-256 지문만 보관합니다. 연결은 TLS 1.2 이상의 HTTPS이며, 키는 자기 회사의 폴더에만 접근할 수 있습니다.
제한: 키당 분당 300회 요청, 파일당 50MB, 회사당 활성 키 20개, 폴더 목록 1회 조회당 최대 5,000개 항목.
리포트 및 푸시 API
리포트 도구와 ERP 커넥터를 위해 api-users.optiroutes.com의 별도 API가 귀사 데이터를 리포트로 제공하고 푸시된 데이터를 받습니다. OptiRoutes가 귀사에 발급한 주소 하나와 토큰 하나로 모든 호출을 처리합니다. 문서 페이지에 토큰을 붙여 넣으면 사용 가능한 리포트와 계정의 열 매핑을 확인할 수 있습니다. API 문서 보기.
| 리포트 | 반환 내용 |
|---|---|
| orders | 경로와 기사가 포함된 주문 및 배송. |
| routes | 기사와 경유지 수가 포함된 경로. |
| drivers | 기사 데이터. |
| customers | 고객 데이터와 주소. |
| pod | 배송 증빙 문서. |
| delivery-summary | 상태별 일일 요약. |
두 가지 푸시 호출은 반대 방향으로 작동합니다. 주문 푸시는 그날의 주문 파일을 작성하고 자동 불러오기를 시작하며, 기사·라인·차량 푸시는 차량 파일처럼 전체 차량 정보를 교체합니다. 푸시된 기사 목록이 전체 차량 정보로 간주되므로, 변경 사항만이 아니라 항상 모든 기사를 보내세요.
경로 내보내기와 웹훅
경로 내보내기는 표시된 경로를 CSV, XLSX, XML, JSON, 고정 폭 TXT로 기록합니다. 열 표에서 어떤 필드를 어떤 제목으로 내보낼지 정하고, 주문 파일의 원래 열을 추가할 수 있으며, 품목 관리를 사용하면 두 번째 파일에 모든 품목이 나열됩니다. 내보내기는 내 컴퓨터, 귀사의 FTP 서버, 회사 폴더로 보낼 수 있고, JSON이면 웹 주소로도 보낼 수 있으며, 전송에 실패하면 시스템이 한 번 더 시도합니다.
배송이 일어날 때마다 받으려면 기사 앱 설정에 배송 보고 수신 주소를 입력하세요. 기사들의 모든 배송 보고가 그곳으로도 전송되어 귀사의 다른 시스템이 자동으로 업데이트됩니다.
이메일, 결제, 지도, 메시지
- 이메일 — 서명된 배송 확인서는 Google 앱 비밀번호를 사용해 귀사의 Gmail 계정에서 발송되고, 일 마감 팔레트 리포트 같은 리포트는 리포트 수신 이메일로 가며, 정산에서 결제 고객에게는 영수증을, 기사에게는 입금 확인서를 보냅니다.
- 결제 — 충전은 보안 Stripe 결제 페이지에서 결제하며, 자동 충전을 위해 카드를 선택적으로 저장할 수 있습니다.
- 주소와 지도 — 주소는 Google 추천 목록에서 선택하고, 계획 전에 지도에서 확인합니다.
- 내비게이션 — 기사 앱은 각 경유지를 주소 또는 정확한 좌표로 Waze, 또는 iPhone의 Apple Maps에 넘깁니다.
- SMS와 WhatsApp — 고객에게 도착 메시지와 추적 링크, 관리자에게 알림, 하도급업체에 라인, 그리고 기사에게 WhatsApp으로 경로 이미지를 보냅니다.
자주 묻는 질문
OptiRoutes가 ERP에서 주문을 자동으로 불러올 수 있나요?
네. ERP가 일일 파일을 OptiRoutes FTP 또는 SFTP 서버, 귀사의 자체 FTP 서버에 넣거나, 파일 API로 업로드하면 OptiRoutes가 자동으로 불러옵니다.
서명된 POD를 우리 시스템으로 어떻게 가져오나요?
파일 API로 하루의 POD 파일 목록을 조회해 다운로드하거나, 전부를 ZIP 하나로 다운로드하세요. 설정한 발송 규칙에 따라 이메일 사본도 발송됩니다.
파일 API 키는 누가 만드나요?
회사 관리자가 설정의 API 및 파일에서 만듭니다. 키에는 권한, 선택적 허용 주소와 만료일이 있으며, 언제든 폐기할 수 있습니다.
리포트용 API가 있나요?
네. 리포트 API는 OptiRoutes가 발급한 토큰으로 주문, 경로, 기사, 고객, POD, 일일 배송 요약을 반환합니다.
경로를 어떤 파일 형식으로 내보낼 수 있나요?
CSV, XLSX, XML, JSON, 고정 폭 TXT이며, 원하는 열과 제목으로 내보낼 수 있습니다.