조회 서버 API

AXCam 앱은 번호판을 판독한 뒤, 고객사가 운영하는 조회 서버에 질의하여 정상/비정상 판정을 받아 화면에 표시합니다. 이 문서는 그 조회 서버가 구현해야 하는 HTTP 엔드포인트 하나의 규격입니다.

한눈에 보기

앱 설정의 [조회 URL] 로 POST 요청이 옵니다 (JSON).
앱 설정의 [API 키] 값은 X-API-Key 헤더에 그대로 담겨 전송됩니다. 키를 입력하지 않으면 헤더 자체가 전송되지 않습니다.
응답은 JSON — 정상/비정상 여부와 화면에 보여줄 문구를 돌려줍니다.
응답이 빠를수록 현장 체감이 좋습니다. 1초 이내를 권장합니다 (앱 타임아웃: 연결 5초 / 응답 15초).

요청

POST {조회 URL}
Content-Type: application/json; charset=utf-8
X-API-Key: {앱 설정에 입력한 API 키}   ← 키를 입력한 경우에만 전송

{
  "plate":            "서울31바1234",              // 판독된 번호판 (원문 그대로)
  "plate_type":       "commercial",              // 번호판 종류 코드 (아래 표)
  "plate_type_label": "영업용",                   // 종류 한글
  "plate_format":     "region_biz",              // 표기 형식 (아래 표)
  "region1":          "서울",                     // 지역1 — 시·도 (없으면 null)
  "region2":          null,                      // 지역2 — 시·군·구 (이륜 구형판만, 없으면 null)
  "number1":          "31",                      // 앞 숫자 — 차종 기호 (없으면 null)
  "hangul":           "바",                       // 용도 문자 (없으면 null)
  "number2":          "1234",                    // 뒤 숫자 — 일련번호
  "plate_color":      "yellow",                  // 번호판 색상 코드 (아래 표, 모르면 null)
  "plate_color_label": "영업용",                  // 색상 한글
  "captured_at":      "2026-08-13T14:02:11+09:00", // 촬영 시각 (ISO-8601)
  "device_id":        "1f0c…-…",                 // 앱 설치별 고유 ID (재설치 시 갱신)
  "confidence":       0.97,                      // 선택: 번호판 판독 신뢰도 (0~1)
  "image_data":       "/9j/4AAQSk…"              // 선택: base64 JPEG (아래 참고)
}

번호판 구조 필드

plate 는 항상 원문 전체이고, 나머지는 앱이 같은 문자열을 나눠 둔 것입니다 (조회 서버가 다시 파싱하지 않아도 되게). 나눌 수 없는 자리는 null 로 옵니다. 판단은 문자열 규칙만으로 하며 판 색깔은 보지 않습니다.

plate_type	plate_type_label	기준	예
`private`	자가용	용도 문자 가나다라마거너더러머버서어저고노도로모보소오조구누두루무부수우주	12가3456 · 서울12가3456
`commercial`	영업용	용도 문자 바사아자 (버스·택시·화물)	서울31바1234 · 12사3456
`rental`	렌터카	용도 문자 하허호	12허3456
`delivery`	택배	용도 문자 배	12배3456
`motorcycle`	이륜차	이륜 표기 (구형 지역판 · 신형 1글자+5자리)	서울금천차9145 · 1거62826
`diplomatic`	외교	외교/영사/준외/준영/국기/협정/대표 + 000-000	외교012-345
`temporary`	임시운행	임 + 허가관청 + 4자리	임화성시장5493
`unknown`	미상	위 어느 것에도 맞지 않음	—

plate_color	plate_color_label	번호판 바탕색
`white`	일반	흰색 (자가용 등)
`blue`	전기차	파란색 (전기·수소차)
`yellow`	영업용	노란색 (택시·버스·화물)
`green`	법인	초록색 (법인·리스 승용)
`orange`	건설기계	주황색
`null`	null	색을 가리지 못함

plate_format	구조	region1 / region2 / number1 / hangul / number2
`standard`	숫자 2~3 + 한글 + 숫자 4 (승용 신형)	null / null / "12" / "가" / "3456"
`region_biz`	시·도 + 숫자 1~2 + 한글 + 숫자 4 (지역판)	"서울" / null / "31" / "바" / "1234"
`moto_old`	시·도 [+ 시·군·구] + 한글 + 숫자 4~5 (이륜 구형)	"서울" / "금천" / null / "차" / "9145"
`moto_new`	숫자 1 + 한글 + 숫자 5 (이륜 신형)	null / null / "1" / "거" / "62826"
`diplomatic`	접두 + 000-000[0]	"외교" / null / null / null / "012-345"
`temporary`	임 + 허가관청 + 4자리	"화성시장" / null / null / null / "5493"
`unknown`	문법 밖	파싱된 자리만 채우고 나머지 null

image_data

앱 설정에서 [이미지 함께 전송] 을 켠 경우에만 포함됩니다. 차량에 파란 사각형을 치고 그 아래 판독된 번호판을 적은 프레임 전체를 JPEG 로 인코딩한 base64 문자열입니다 (data: 접두어 없음). 화질은 원본 또는 섬네일(가로 800px) 중 앱에서 선택합니다. 데모 모드에서는 전송되지 않습니다.

응답 (권장 형식)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "plate":        "12가3456",
  "is_abnormal":  true,               // 판정: true = 비정상(경보)
  "status":       "suspended",        // 상태 코드 (자유 정의 가능)
  "status_label": "출입정지",          // 화면에 그대로 표시할 짧은 문구
  "reason":       "출입이 정지된 차량입니다"  // 비정상 사유 (크게 표시됨)
}

status_label 은 라이브 화면 배지에, reason 은 비정상 경보 배너에 그대로 표시됩니다. 문구는 서버가 내려주는 값을 가공 없이 사용합니다.

수용하는 다른 필드명

이미 운영 중인 서버에 붙이기 쉽도록 아래 변형도 해석합니다.

용도	인식하는 키	비고
판정	`is_abnormal` · `isAbnormal` · `abnormal` · `normal`(반대 의미) · `status` · `result`	불리언 또는 문자열(`"true"/"1"/"yes"` 등)
판정 문자열 값	정상: `normal, ok, allow, allowed, pass, 정상, 허용` 비정상: `abnormal, deny, denied, blocked, 차단, 비정상`	그 외 상태 코드(`expired` 등)는 비정상으로 간주
사유	`reason` · `message` · `detail` · `description` · `note`	비정상일 때만 표시
표시 문구	`status_label` · `statusLabel` · `label`	없으면 `status` 값, 그것도 없으면 "정상"/"비정상"
감싸기	`{"data": {…}}` · `{"result": {…}}` · `{"payload": {…}}`	한 겹 감싼 응답도 해석

상태 코드 예시

상태 코드는 자유롭게 정의할 수 있습니다. 참고용 예시:

status	status_label	기본 사유 예시
`normal`	정상	—
`expired`	기간만료	출입 유효기간이 만료된 차량입니다
`suspended`	출입정지	출입이 정지된 차량입니다
`unpaid`	요금미납	요금이 미납된 차량입니다
`stolen`	도난·수배차량	도난·수배 등록 차량입니다
`blacklist`	블랙리스트	출입이 금지된 차량입니다
`unregistered`	미등록	등록되지 않은 차량입니다

오류 · 과부하

200 이외의 응답은 판정 실패로 처리되어 화면에 오류 메시지가 뜹니다. 판정 결과는 반드시 200 으로 돌려주세요 (비정상도 200 입니다).
429 또는 503 을 돌려주면 앱이 Retry-After 헤더(초)만큼 모든 요청을 멈췄다가 재개합니다. 서버 보호가 필요할 때 사용하세요.
앱은 같은 번호판의 판정을 30초 동안 재사용하므로, 같은 차가 화면에 머물러도 조회가 반복되지 않습니다.

동작 확인

curl -X POST https://lookup.example.com/api/lookup \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-lookup-api-key' \
  -d '{"plate":"12가3456","plate_type":"private","plate_type_label":"자가용","plate_format":"standard",
       "region1":null,"region2":null,"number1":"12","hangul":"가","number2":"3456",
       "captured_at":"2026-08-13T14:02:11+09:00","device_id":"test-device"}'

최소 응답은 이것으로 충분합니다: {"is_abnormal": false}
앱 설정 화면의 [조회 테스트] 버튼으로 실제 앱에서 왕복을 확인할 수 있습니다.

이미지에서 번호판 문자열을 얻는 HTTP API 는 판독 서버 API 문서를 보세요.