조회 서버 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":       "12가3456",                  // 판독된 번호판
  "captured_at": "2026-08-13T14:02:11+09:00", // 촬영 시각 (ISO-8601)
  "device_id":   "1f0c…-…",                   // 앱 설치별 고유 ID (재설치 시 갱신)
  "image_data":  "/9j/4AAQSk…"                // 선택: base64 JPEG (아래 참고)
}

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","captured_at":"2026-08-13T14:02:11+09:00","device_id":"test-device"}'

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

참고 — 판독 서버와의 관계

번호판 판독(이미지 → 문자열)은 AXCam 판독 서버가 담당하고, 앱이 자동으로 연결합니다(구독 결제된 기기만 사용 가능). 조회 서버는 판독된 문자열에 대한 판정만 책임집니다. 판독 이미지는 판독 서버에 저장되지 않으며, 조회 서버로는 위 image_data 를 켠 경우에만 이미지가 전달됩니다.