벌마루 도매 API

판매처가 로트 기록을 읽는 가상 API 안내입니다. 예시의 BEOLMARU_API 주소와 키는 지어낸 것이며 실제로 응답하지 않습니다.

읽기 전용 · v1

시작하기

도매 API 는 로트 기록을 읽기만 합니다. 주문·쓰기 엔드포인트는 없습니다. 모든 응답은 JSON 이고, 한 쪽에 최대 24건을 돌려줍니다.

요청

curl "$BEOLMARU_API/v1/lots?per_page=24" \
  -H "Authorization: Bearer <키>"

요청

const API = process.env.BEOLMARU_API;
const res = await fetch(API + "/v1/lots?per_page=24", {
  headers: { Authorization: "Bearer <키>" },
});
const { lots } = await res.json();

요청

import os, requests
API = os.environ["BEOLMARU_API"]
r = requests.get(API + "/v1/lots", params={"per_page": 24},
                 headers={"Authorization": "Bearer <키>"})
lots = r.json()["lots"]

응답

{
  "lots": [ { "lot": "BM-26-0514-A", "name": "아까시 첫물꿀" } ],
  "page": 1,
  "total": 1284
}

매개변수	형식	설명
`per_page`	정수	한 쪽 건수 (1~24, 기본 24)
`page`	정수	쪽 번호 (1~54)

인증

키는 읽기 전용이며 판매처마다 하나입니다. 헤더에 Bearer 로 붙입니다. 키 없이 부르면 한 시간에 60번까지 허용합니다.

curl JavaScript Python

요청

curl -I "$BEOLMARU_API/v1/lots"

요청

await fetch(API + "/v1/lots", { method: "HEAD" });

요청

requests.head(API + "/v1/lots")

응답

HTTP/2 200
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

매개변수	형식	설명
`Authorization`	헤더	Bearer <키> — 없으면 시간당 60번

로트 목록

꽃·구역·정렬로 로트를 거릅니다. 화면의 꿀 목록과 같은 순서를 돌려줍니다.

curl JavaScript Python

요청

curl "$BEOLMARU_API/v1/lots?flower=acacia&zone=upper&sort=sales"

요청

await fetch(API + "/v1/lots?flower=acacia&zone=upper&sort=sales");

요청

requests.get(API + "/v1/lots", params={"flower": "acacia", "zone": "upper", "sort": "sales"})

응답

{
  "lots": [
    { "lot": "BM-26-0514-A", "flower": "acacia", "jars_week": 412 },
    { "lot": "BM-26-0524-B", "flower": "acacia", "jars_week": 256 }
  ],
  "total": 2
}

매개변수	형식	설명
`flower`	문자열	꽃 (acacia · chestnut · buckwheat …)
`zone`	upper \| lower \| …	구역
`sort`	recommended \| harvested \| sales \| name	정렬 (기본 recommended)

로트 한 건

로트 번호로 한 로트의 꽃·구역·검사표·수확일을 읽습니다.

curl JavaScript Python

요청

curl "$BEOLMARU_API/v1/lots/BM-26-0514-A"

요청

await fetch(API + "/v1/lots/BM-26-0514-A");

요청

requests.get(API + "/v1/lots/BM-26-0514-A")

응답

{
  "lot": "BM-26-0514-A",
  "zone": "윗마루 · 한결",
  "checks": ["moisture", "brix", "color_mm", "crystal"],
  "harvested": "2026-05-14"
}

매개변수	형식	설명
`lot`	경로	로트 번호