아마노 법인 웹 API 명세서 - 통합본

상세 목차

대분류 중분류 링크
1. 랜딩 페이지 📍
1.1 주차장 리스트 조회 🔗
1.2 이벤트/공지/FAQ 조회 🔗
1.3 이벤트 배너 조회 🔗
2. 주차장 상세 📍
2.1 주차장 상세 조회 🔗
2.2 주차권 수량 확인 조회 🔗
3. 주차장 즐겨찾기 📍
3.1 즐겨찾기 주차장 리스트 조회 🔗
3.2 주차장 즐겨찾기 등록 🔗
3.3 주차장 즐겨찾기 삭제 🔗
4. 계정 관련 API 📍
4.1 아이디 찾기 🔗
4.2 비밀번호 변경가능 여부 확인 🔗
4.3 비밀번호 재설정 🔗
4.4 회원 탈퇴 🔗
5. 회원가입 API 📍
5.1 약관 내용 조회 🔗
5.2 회원가입 🔗
6. 알림 📍
6.1 알림 리스트 조회 🔗
6.2 알림 읽음 상태 업데이트 🔗
7. 이용문의 - 공지사항 📍
7.1 공지사항 리스트 조회 🔗
7.2 공지사항 상세 조회 🔗
8. 이용문의 - 이벤트 📍
8.1 이벤트 리스트 조회 🔗
8.2 이벤트 상세 조회 🔗
9. 이용문의 - FAQ 📍
9.1 FAQ 리스트 조회 🔗
10. 마이페이지 - 동/호수 관리 📍
10.1 동/호수 리스트 조회 🔗
10.2 동/호수 등록 🔗
10.3 동/호수 삭제 🔗
10.4 주차장 조회 (동/호수 등록용) 🔗
11. 마이페이지 - 차량 등록 관리 📍
11.1 차량 리스트 조회 🔗
11.2 차량 등록 (단건) 🔗
11.3 차량 삭제 🔗
12. 마이페이지 - 기본정보 📍
12.1 내 정보 조회 🔗
12.2 내 정보 수정 🔗

1. 랜딩 페이지

법인웹 첫 페이지. 지도와 지도에 표시된 주차장 리스트, 내가 즐겨찾기한 주차장, 새로운 소식, 이벤트 배너가 표시됩니다.

1.1 주차장 리스트 조회

지도와 연동된 주차장 리스트 조회

API 정보

Request Parameters

{
  "latitude": 37.5665, 
  "longitude": 126.9780,
  "parkingLotName": "아마노",
  "region": "종로구",
  // 페이징이 필요할까요..?
  "page": 1,
  "pageSize": 8
}

Response

{
  "status": "success",
  "data": {
    "parkingLots": [
      {
        "id": "pl-001",
        "name": "아마노 주차장 1호점",
        "address": "서울 종로구 세종로 81-3",
        "image": "https://example.com/parking-lot-image.jpg",
        "price": 2000,
        "latitude": 37.5665,
        "longitude": 126.9780,
        "isFavorite": false
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 10,
      "totalItems": 80,
      "pageSize": 8
    }
  }
}

1.2 이벤트/공지/FAQ 리스트 조회 (최신 5건)

API 정보

Request Parameters

{
  "limit": 5
}

Response

{
  "status": "success",
  "data": {
    "noticeItems": [
      {
        "id": 1,
        "author": "관리자",
        "title": "시스템 점검 안내",
        "date": "2024.01.10",
        "status": "new"
      }
    ],
    "eventItems": [
      {
        "id": 1,
        "title": "신규 회원 첫 주차 50% 할인",
        "date": "2024.02.29",
        "status": "ongoing" // 진행중, 종료
      }
    ],
    "faqItems": [
      {
        "id": 1,
        "title": "주차권 구매는 어떻게 하나요?",
        "answer": "앱에서 원하는 주차장을 선택하신 후...",
        "category": "주차권",
        "date": "2024.01.15"
      }
    ]
  }
}

1.3 이벤트 배너 조회

API 정보

Response

{
  "status": "success",
  "data": {
    "eventBanners": [
      {
        "id": "banner-001",
        "imageUrl": "https://example.com/event-banner-1.jpg",
        "linkUrl": "/events/new-member-discount",
        "displayOrder": 1
      }
    ]
  }
}

2. 주차장 상세

랜딩 페이지에서 주차장을 선택하면 나오는 주차장 상세 화면입니다. 주차권을 선택해서 구매/결제 프로세스를 시작합니다.

2.1 주차장 상세 조회

API 정보

Request Parameters

{
  "id": "pl-001"
}

Response

{
  "status": "success",
  "data": {
    "id": "1",
    "name": "아마노 주차장 1호점",
    "address": "서울 종로구 세종로 81-3",
    "phone": "02-1234-1234",
    "lastUpdated": "2025. 08. 29(금) 14:11",
    "isFavorite": true,
    "features": ["기계식", "자주식", "리프트", "노상", "복합", "부설주", "전기"],
    "carTypes": [
      { "label": "승용(소형)", "code":"car-s" },
      { "label": "승용(중형)", "code":"car-m" },
      { "label": "SUV", "code":"suv" },
      { "label": "화물(중형)", "code":"truck-m" },
      { "label": "화물(대형)", "code":"truck-l" }
    ],
    "operatingHours": [
      { "day": "월요일", "hours": "00:00~24:00" },
      { "day": "화요일", "hours": "00:00~24:00" },
      { "day": "수요일", "hours": "00:00~24:00" },
      { "day": "목요일", "hours": "00:00~24:00" },
      { "day": "금요일", "hours": "00:00~24:00" },
      { "day": "토요일", "hours": "00:00~24:00" },
      { "day": "일요일", "hours": "00:00~24:00" },
      { "day": "공휴일", "hours": "00:00~24:00" }
    ],
    "pricing": [
      { "label": "기본요금", "value": "10분/500원" },
      { "label": "무료회차", "value": "10분/무료" },
      { "label": "일최대요금", "value": "80000원" },
      { "label": "출차시간", "value": "10분" }
    ],
    "notice": "안녕하세요 저희 주차장은 신규 결제시 승인후 사용이 가능한 주차장입니다. 신규결제시 3일 전에 미리 주차권을 구매하시는 기다림 없이 사용이 가능합니다.",
    "images": [
      "https://c.animaapp.com/mfqlhxftrWTeQN/img/parkinglot-image1.svg",
      "https://c.animaapp.com/mfqlhxftrWTeQN/img/parkinglot-image2.svg",
      "https://c.animaapp.com/mfqlhxftrWTeQN/img/parkinglot-image3.svg",
      "https://c.animaapp.com/mfqlhxftrWTeQN/img/parkinglot-image4.svg",
      "https://c.animaapp.com/mfqlhxftrWTeQN/img/parkinglot-image5.svg"
    ],
    "parkingPasses": [
      {
        "id": "1",
        "title": "정기권(구독)",
        "type": "approval_required", // 구독인지 일반인지
        "approval": "", // 승인이 필요한지
        "usageTime": "00:00~23:59",
        "stock": "999", // 남은 수량
        "price": "9999000",
        "available": true // 매진인지 구매 가능한지
      }
    ],
    "caution": {
      "using": "본 상품의 유효기간은 구매 당일 00 사전정산기 사용시 주차권 적용이 불가능합니다.",
      "refund": "아마노 App을 통해 구매 결정하신 상품에 대해서만 취소 및 환불이 가능합니다."   
    }
  }
}

2.2 주차권 수량 확인 조회

API 정보

Request Parameters

{
  "id": "pass-001"
}

Response

{
  "status": "success",
  "data": {
    "id": "pass-001",
    "stock": "999",
    "available": true
  }
}

3. 주차장 즐겨찾기

3.1 즐겨찾기 주차장 리스트 조회

API 정보

Request Parameters

{
  "page": 1,
  "pageSize": 8
}

Response

{
  "status": "success",
  "data": {
    "favoriteParkingLots": [
      {
        "id": "fpl-001",
        "name": "즐겨찾기 주차장 1",
        "address": "서울 강남구 테헤란로 123",
        "image": "https://example.com/favorite-parking.jpg",
        "price": 1500,
        "latitude": 37.5013,
        "longitude": 127.0396,
        "addedDate": "2024.01.15"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 40,
      "pageSize": 8
    }
  }
}

3.2 주차장 즐겨찾기 등록

API 정보

Request Body

{
  "parkingLotId": "pl-001"
}

Response

{
  "status": "success",
  "message": "즐겨찾기에 추가되었습니다.",
  "data": {
    "id": "fpl-002",
    "parkingLotId": "pl-001",
  }
}

3.3 주차장 즐겨찾기 삭제

API 정보

Request Parameters

{
  "parkingLotId": "pl-001"
}

Response

{
  "status": "success",
  "message": "즐겨찾기에서 제거되었습니다."
}

4. 계정 관련 API

4.1 아이디 찾기

API 정보

Request Parameters

{
  "businessNumber": "string",     // 사업자번호 (10자리, 하이픈 제외)
  "phoneNumber": "string"         // 휴대폰 번호 (하이픈 제외)
}

Response

{
  "success": true,
  "data": {
    "userId": "user***1"  // 아스터리스크로 가려진 아이디
  },
  "message": "아이디 조회가 완료되었습니다."
}

4.2 비밀번호 변경가능 여부 확인

API 정보

Request Parameters

{
  "userId": "string",            // 사용자 아이디
  "businessNumber": "string",    // 사업자번호 (10자리, 하이픈 제외)
  "phoneNumber": "string"        // 휴대폰 번호 (하이픈 제외)
}

Response

{
  "success": true,
  "data": {
    "canChangePassword": true,    // 비밀번호 변경 가능 여부
    "resetToken": "string"        // 비밀번호 재설정용 임시 토큰 (가능한 경우에만 제공)
  },
  "message": "비밀번호 변경이 가능합니다."
}

4.3 비밀번호 재설정

API 정보

Request Parameters

{
  "newPassword": "string",       // 신규 비밀번호 (8자 이상, 영문+숫자+특수문자 조합)
  "resetToken": "string"         // 비밀번호 재설정용 토큰 (JWT 토큰 없는 경우 필수)
}

Response

{
  "success": true,
  "message": "비밀번호가 성공적으로 변경되었습니다."
}

4.4 회원 탈퇴

API 정보

Request Parameters

{
  "reason": "string",            // 탈퇴 사유 (선택)
  "password": "string"           // 현재 비밀번호 (확인용)
}

Response

{
  "success": true,
  "message": "회원 탈퇴가 완료되었습니다.",
  "data": {
    "withdrawalDate": "2025-10-14T10:30:00Z",
    "dataRetentionPeriod": "30일" // 개인정보 보관 기간
  }
}

5. 회원가입 API

5.1 약관 내용 조회

API 정보

Request Parameters

{
  "termId": "terms|privacy|location|optional-location"
}

Response

{
  "success": true,
  "data": {
    "title": "아마노파킹 이용약관",
    "content": "제1조 (목적)..."
  }
}

5.2 회원가입

API 정보

Request Parameters

{
  "userId": "testuser123",
  "password": "password123!",
  "phoneNumber": "01012345678",
  "companyName": "(주)테스트컴퍼니",
  "businessNumber": "1234567890",
  "businessCertFiles": ["file_id_1", "file_id_2"],
  "email": "test@company.com",
  "optionAgreement": {
    "sms": true,
    "phone": true,
  }
}

Response

{
  "success": true,
  "data": {
    "userId": "testuser123",
    "message": "회원가입이 완료되었습니다."
  }
}

6. 알림

사용자에게 제공되는 상품 알림과 그 외 알림을 관리하는 기능입니다.

6.1 알림 리스트 조회

API 정보

Response

{
  "status": "success",
  "data": {
    "productNotifications": [
      {
        "id": 1,
        "type": "product",
        "status": "구매완료",
        "title": "주차장 상품이 결제되었습니다.",
        "subtitle": "[아마노타워 월 정기권]이 35,000원 결제 되었습니다.",
        "date": "2025. 07. 10",
        "orderNumber": "1",
        "isRead": false,
        "createdAt": "2025-07-10T10:30:00Z"
      },
      {
        "id": 2,
        "type": "product",
        "status": "만료예정",
        "title": "정기권이 7일 후 만료됩니다.",
        "subtitle": "[아마노타워 월 정기권]의 유효기간이 2025.07.17에 종료됩니다.",
        "date": "2025. 07. 09",
        "orderNumber": "2",
        "isRead": false,
        "createdAt": "2025-07-09T09:00:00Z"
      }
    ],
    "etcNotifications": [
      {
        "id": 5,
        "type": "etc",
        "status": "공지사항",
        "title": "여름 정기권 할인 이벤트",
        "subtitle": "7월 한정! 모든 정기권 20% 할인 혜택을 놓치지 마세요.",
        "date": "2025. 07. 05",
        "isRead": false,
        "createdAt": "2025-07-05T08:00:00Z"
      },
      {
        "id": 6,
        "type": "etc",
        "status": "이벤트",
        "title": "시스템 점검 안내",
        "subtitle": "2025.07.15(월) 02:00~06:00 시스템 점검이 예정되어 있습니다.",
        "date": "2025. 07. 04",
        "isRead": false,
        "createdAt": "2025-07-04T12:00:00Z"
      }
    ]
  }
}

6.2 알림 읽음 상태 업데이트

API 정보

Request Body

{
  "ids": "1,2,3,4",
  "isRead": true
}

Response

{
  "status": "success",
  "message": "알림 읽음 상태가 업데이트되었습니다.",
  
}

7. 이용문의 - 공지사항

7.1 공지사항 리스트 조회

API 정보

Request Parameters

{
  "page": 1,
  "pageSize": 10,
  "keyword": "시스템", // 제목, 내용
  "sortBy": "date",
  "sortOrder": "desc"
}

Response

{
  "status": "success",
  "data": {
    "notices": [
      {
        "id": 1,
        "title": "시스템 점검 안내",
        "author": "관리자",
        "createdDate": "2024.01.10"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 20,
      "totalItems": 200,
      "pageSize": 10
    }
  }
}

7.2 공지사항 상세 조회

API 정보

Request Parameters

{
  "id": 1
}

Response

{
  "status": "success",
  "data": {
    "id": 1,
    "title": "시스템 점검 안내",
    "author": "관리자",
    "createdDate": "2024.01.10",
    "content": "<p>시스템 점검으로 인해...</p>",
    "attachments": [
      {
        "id": "att-001",
        "filename": "점검안내.pdf",
        "fileUrl": "https://example.com/files/notice.pdf",
        "fileSize": 1024000
      }
    ]
  }
}

8. 이용문의 - 이벤트

8.1 이벤트 리스트 조회

API 정보

Request Parameters

{
  "page": 1,
  "pageSize": 10,
  "keyword": "할인", // 제목, 내용
  "status": "ongoing" 
}

Response

{
  "status": "success",
  "data": {
    "events": [
      {
        "id": 1,
        "title": "신규 회원 첫 주차 50% 할인",
        "author": "이벤트팀",
        "createdDate": "2024.02.29",
        "status": "ongoing",
        "startDate": "2024.02.01",
        "endDate": "2024.02.29",
        "thumbnail": "https://example.com/event-detail-1.jpg"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 15,
      "totalItems": 150,
      "pageSize": 10
    }
  }
}

8.2 이벤트 상세 조회

API 정보

Request Parameters

{
  "id": 1
}

Response

{
  "status": "success",
  "data": {
    "id": 1,
    "title": "신규 회원 첫 주차 50% 할인",
    "author": "이벤트팀",
    "createdDate": "2024.02.29",
    "content": "<p>신규 회원을 위한 특별 할인...</p>",
    "status": "ongoing",
    "startDate": "2024.02.01",
    "endDate": "2024.02.29",
    "detailImages": [
      "https://example.com/event-detail-1.jpg",
      "https://example.com/event-detail-2.jpg"
    ]
  }
}

9. 이용문의 - FAQ

9.1 FAQ 리스트 조회

API 정보

Response

{
  "status": "success",
  "data": {
    "faqs": [
      {
        "id": 1,
        "title": "주차권 구매는 어떻게 하나요?",
        "answer": "앱에서 원하는 주차장을 선택하신 후 주차권을 선택하여 결제하시면 됩니다.",
        "category": "parking",
        "createdDate": "2024.01.15"
      }
    ]
  }
}

10. 마이페이지 - 동/호수 관리

내 주차장 등록하는 페이지입니다. 입주민인 경우 어느 아파트의 몇 동 몇 호인지 관리합니다.

10.1 동/호수 리스트 조회

API 정보

Response

{
  "status": "success",
  "data": {
    "parkingUnits": [
      {
        "id": 6,
        "parkingName": "아마노코리아1호점",
        "building": "101",
        "unit": "1004",
        "registrationDate": "2025.09.02",
        "status": "승인완료"
      }
    ],
    "totalCount": 6
  }
}

10.2 동/호수 등록

API 정보

Request Body

{
  "parkingLotId": "parking_001",
  "building": "101",
  "unit": "1004",
  "files": ["base64_encoded_file_data"]
}

Response

{
  "status": "success",
  "message": "동/호수가 성공적으로 등록되었습니다.",
  "data": {
    "id": 7,
    "parkingName": "아마노코리아1호점",
    "building": "101", 
    "unit": "1004",
    "registrationDate": "2025. 09. 19",
    "status": "승인대기"
  }
}

10.3 동/호수 삭제

API 정보

Request Parameters

{
  "id": 6
}

Response

{
  "status": "success",
  "message": "동/호수가 성공적으로 삭제되었습니다."
}

10.4 주차장 조회 (동/호수 등록용)

주차장 검색을 위한 api

API 정보

Request Parameters

{
  "page": 1,
  "pageSize": 10,
  "keyword": "현대주차장", // 주차장명 또는 주소

}

Response

{
  "status": "success",
  "data": {
    "parkingLotOptions": [
      {
        "id": "parking_001",
        "name": "아마노코리아1호점",
        "address": "서울시 강남구 테헤란로 123",
        "buildings": ["101", "102", "103", "104", "105"],
        "units": {
          "101": ["101", "102", "103", "104", "105", "201", "202"],
          "102": ["101", "102", "103", "104", "105", "201", "202"]
        }
      }
    ]
  }
}

11. 마이페이지 - 차량 등록 관리

내 차량을 관리하는 페이지입니다.

11.1 차량 리스트 조회

API 정보

Response

{
  "status": "success",
  "data": {
    "cars": [
      {
        "id": 10,
        "carNumber": "123가1234",
        "carType": "suv",
        "carName": "카니발",
        "registrationDate": "2025. 09. 02"
      }
    ],

  }
}

11.2 차량 등록 (단건)

API 정보

Request Body (단건 등록)

{
  "carNumber": "123가1234",
  "carType": "suv",
  "carName": "카니발"
}

Response (단건 등록)

{
  "status": "success",
  "message": "차량이 성공적으로 등록되었습니다.",
  "data": {
    "id": 11,
    "carNumber": "123가1234",
    "carType": "suv", 
    "carName": "카니발",
    "registrationDate": "2025. 09. 19"
  }
}

Request Body (일괄 등록)

일괄등록이 있으면 단건 등록이 필요 없어 보이네요

{
  "cars": [
    {
      "carNumber": "123가1234",
      "carType": "suv",
      "carName": "카니발"
    },
    {
      "carNumber": "456나5678",
      "carType": "sedan",
      "carName": "아반떼"
    }
  ]
}

Response (일괄 등록)

{
  "status": "success",
  "message": "차량이 일괄 등록되었습니다.",
  "data": {
    "successCount": 10,
    "failedCount": 2,
    "failedItems": [
      {
        "carNumber": "잘못된번호",
        "reason": "올바르지 않은 차량번호 형식"
      }
    ]
  }
}

11.3 차량 삭제

API 정보

Request Parameters

{
  "id": 10
}

Response

{
  "status": "success",
  "message": "차량이 성공적으로 삭제되었습니다."
}

12. 마이페이지 - 기본정보

12.1 내 정보 조회

API 정보

Response

{
  "success": true,
  "data": {
    "userInfo": {
      "userId": "abcd1234",
      "companyName": "(주)테스트컴퍼니",
      "businessNumber": "1234567890",
      "businessCertFiles": ["file_id_1", "file_id_2"],
      "email": "test@company.com",
      "phoneNumber": "01012345678",
    },
    "bankInfo": {
        "bank": "kb",
        "accountNumber": "123-456-789012",
        "accountHolder": "테스트컴퍼니",
        "accountFiles": ["file_id_1", "file_id_2"]
    },
    "optionAgreement": {
      "sms": true,
      "phone": true,
    }
  }
}

12.2 내 정보 수정

API 정보

Request Parameters

{
  "userInfo": {
    "companyName": "(주)수정된컴퍼니",
    "email": "updated@company.com",
    "phoneNumber": "01098765432",
    "businessNumber": "1234567890",
    "businessCertFiles": ["file_id_1", "file_id_2"],
    "password":""

  },
  "bankInfo": {
        "bank": "kb",
        "accountNumber": "123-456-789012",
        "accountHolder": "테스트컴퍼니",
        "accountFiles": ["file_id_1", "file_id_2"]
  },
  "optionAgreement": {
    "sms": true,
    "phone": true,
  }
}

Response

{
  "success": true,
  "data": {
    "message": "정보가 성공적으로 수정되었습니다.",
    "updatedAt": "2025-09-23T10:30:00Z"
  }
}

13. 중복 체크 API

13.1 차량 등록 중복 체크

API 정보

Request Parameters

{
  "carNumber": "123가1234"
}

Response

{
  "success": true,
  "data": {
    "isDuplicate": false,
    "message": "사용 가능한 차량번호입니다."
  }
}