API Documentation - maulufia/clovergarden GitHub Wiki

BASE URI : http://api.clovergarden.co.kr/v1

---

Prefix URIs

1. 보고서 - http://clovergarden.co.kr/imgs/up_file/clover/{파일명}
2. 프로필 이미지 (수정되지 않은 경우) - http://clovergarden.co.kr/imgs/up_file/member/{파일명}

---

• 모든 Request는 contentType="application/x-www-form-urlencoded"입니다
• 파일 업로드 시 제한 업로드 크기는 10MB입니다. 따로 에러 메시지를 출력하지 않으니 클라이언트에서 처리해주셔야 합니다
• FCM을 사용할 때 안드로이드나 iOS에서 초기 Topic을 news로 지정해주시기 바랍니다.
  Android 참고 : https://firebase.google.com/docs/cloud-messaging/android/topic-messaging

Version : v1

---

2016/01/13 수정

1. 아이디 중복 확인에 아이디(이메일) 형식 검사도 추가됨

2016/12/10 수정

1. 조회 가능한 연도 목록 불러오기 추가
2. 연도별로 후원 내역 조회 추가
3. 위 내역은 이전에 추가되었으나 문서에만 반영이 안되어 있어 이제 추가함

2016/08/16 수정

1. 기관 상세에 이미지 3개로 데이터베이스 및 API 수정
2. 타임라인 글에 이미지 3개로 데이터베이스 및 API 수정

2016/08/14 수정

1. 회원가입 시 핸드폰 중복 에러 처리

2016/08/06 수정

1. 타임라인 목록 데이터에 clover_id 데이터 추가 - 긴급후원 시에 사용

2016/08/03 수정

1. 결제 모듈 구현 관련 문서 추가

2016/07/25 수정

1. 내 정보 불러오기 API(/user/me)에서 member_id 키 추가 (댓글 수정, 삭제에 이용)

2016/07/25 수정

1. 로그인 API에서 기관담당자일 시 true 반환하는 isCompanySup 키 추가

2016/07/20 수정

1. 좋아요 API를 토글링 API로 변경
2. 게시물을 '좋아요'한 여부를 'isIlike'로 반환 (isIlike가 'y'인 경우가 자신이 좋아하는 게시물)
3. 전체 타임라인을 받아올 경우 로그인한 경우의 URL을 따로 분리

2016/07/17 수정

1. 인증번호 발송 API를 POST 메소드로 변경

2016/07/14 수정

1. 내 후원 기관 목록 불러오기에 후원금액 정보 추가 (후원 기관 변경에서 사용)

2016/06/11 수정

1. 내 정보 불러오기 메소드를 GET으로 수정

2016/06/09 수정

1. 내 후원기관 목록 불러오기 API 추가

2016/06/08 수정

1. 로그인이 필요한 모든 API에서 기존에 api_token을 body parameter로 보내는 것을 헤더 요청으로 변경하였습니다. 헤더에서 '_'(언더라인)이 허용되지 않으므로 api_token이 아닌 api-token을 사용합니다.
2. 아이디 중복 확인 API 추가
3. 타임라인 (개별사용자) URL를 /timeline/list에서 /user/me/timeline으로 변경
4. 타임라인 (전체) API 추가
5. 네이버 로그인시 전화번호 반드시 추가하는것으로 수정
6. 타임라인 (특정 후원기관) API 추가
7. 타임라인에서 보고서만 받는 (only_report) 파라미터를 optional로 수정

---

계정 관련

로그인 API

[POST] /user/login

구분	파라미터 or 타입	설명
@param	id	로그인 ID
@param	passwd	패스워드
@return	JSON	오류 시 JSON 텍스트, 승인 시 Array('success', token) 반환

반환 값

키	값	설명
error	is_seceded_member	탈퇴한 회원
error	is_not_accepted_yet	승인되지 않은 회원 (기업회원)
error	invalid_credentials	잘못된 아이디 혹은 비밀번호
success	login_success	로그인 성공 시
success	token	애플리케이션에 쓰일 api-token
success	isCompanySup	기관담당자일 시 true 반환

네이버 로그인 API

네이버 API에서 받은 access_token을 이용하여 클로버가든 로그인 기능을 수행한다.
토큰은 rfc3389를 따르므로 그에 맞는 인코딩이 필요
[POST] /user/login/naver

구분	파라미터 or 타입	설명
@param	token	네이버 access_token
@param	phone	핸드폰 번호
@return	JSON	성공 시 성공 텍스트와 애플리케이션에 사용할 api-token을 반환한다. 로그인이 아니라 가입이 필요한 경우 핸드폰 번호를 필요로 한다. 이때는 'error':'need_phone_num'을 반환한다.

회원가입

[POST] /user/signup

구분	파라미터 or 타입	설명
@param	id	로그인 ID (이메일)
@param	name	이름
@param	passwd	패스워드
@param	phone	핸드폰 번호
@return	JSON	성공 메시지(join_success), 회원 id (database id)

반환 값

키	값	설명
error	duplicated_phone_number	핸드폰 번호 중복
success	join_success	회원 가입 성공

아이디 중복확인

[POST] /user/check/id

구분	파라미터 or 타입	설명
@param	id	로그인 ID (이메일)
@return	JSON	중복 시 is_duplicate 키 값이 true, 아닐 시 false

반환 값

키	값	설명
error	wrong_format	이메일 형식 맞지 않음
success	is_duplicate	true or false

아이디 찾기

[POST] /user/findId

구분	파라미터 or 타입	설명
@param	user_name	회원 이름
@param	phone	핸드폰 번호
@return	JSON	아이디

반환 값

키	값	설명
error	failed_to_find_id	아이디 찾기 실패
id	아이디	성공 시 아이디 반환

비밀번호 찾기

[POST] /user/findPw

구분	파라미터 or 타입	설명
@param	user_id	회원 아이디
@param	user_name	회원 이름
@param	phone	핸드폰 번호
@return	JSON	sendSms 리턴값

유저 정보를 불러옴 (로그인 한)

쓰지말것
[GET] /user

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@return	JSON	user information

내 정보 불러오기

[GET] /user/me

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@return	JSON	유저 이름, 소속 기업, 썸네일(URL), 총 후원 금액

프로필 사진 업로드

[POST] /user/profile/upload

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@param	upload_pic	업로드할 사진 (form data)
@return	JSON	성공 시 success 반환

내 후원 내역 불러오기 (사용하지 않음)

[GET] /user/me/support

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@return	JSON	otype 후원 형태
@return	JSON	clover_seq 후원 기관 코드 (id 아님)
@return	JSON	price 후원 금액
@return	JSON	이하 생략

내 후원 내역 불러오기 (연도별)

[GET] /user/me/support/year/{$year}

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@param	year	연도 (형식 : yyyy)
@return	JSON	otype 후원 형태
@return	JSON	clover_seq 후원 기관 코드 (id 아님)
@return	JSON	price 후원 금액
@return	JSON	이하 생략

조회 가능한 연도 불러오기

[GET] /user/me/support/getAvailableYears

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@return	JSON	연도들

후원 기관 변경

[POST] /user/me/support/change

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@param	clover_codes	후원 변경 코드. ','로 구분
@param	clover_prices	후원 변경 금액. ','로 구분
@return	JSON	성공 메시지

반환 값

키	값	설명
error	price_not_matching	기존 후원 전체 금액과 변경하려는 후원 전체 금액이 동일하지 않을 때
error	duplicated_clover_code	후원 변경 기관에 2개 이상 중복 신청된 기관이 있을 때
success	success_change_clover	변경 신청 성공 시

후원기관 관련

후원 기관 목록 불러오기

[GET] /company/list

구분	파라미터 or 타입	설명
@return	JSON	seq 후원 기관 ID
@return	JSON	code 후원 기관 변경 때 쓰이는 code
@return	JSON	subject 후원 기관 명
@return	JSON	mobile_intro 후원 기관 소개 (모바일용)
@return	JSON	mobile_thumbnail 후원 기관 리스트 썸네일 (모바일용)
@return	JSON	mobile_image1 후원 기관 이미지 (상세 페이지 최상단 이미지)
@return	JSON	mobile_image2 후원 기관 이미지 (이미지2)
@return	JSON	mobile_image3 후원 기관 이미지 (이미지3)

내 후원 기관 목록 불러오기

[GET] /user/me/companies

구분	파라미터 or 타입	설명
@return	JSON	후원 기관 목록 불러오기와 같음 + 후원금액

후원 기관 세부 내역

[GET] /company/{company_id}

구분	파라미터 or 타입	설명
@param	company_id	후원 기관 id
@return	JSON	후원 기관 불러오기의 리턴형식과 같음

클로버가든 게시판

공지사항 받아오기

[GET] /board/notice

구분	파라미터 or 타입	설명
@return	JSON	제목, 내용, 등록일

자주하는 질문 받아오기

[GET] /board/faq

구분	파라미터 or 타입	설명
@return	JSON	제목, 내용, 등록일

타임라인

타임라인 받아오기 (개별 사용자)

protected-urgency, public-urgency 순. 일반과 보고서는 날짜순으로 정렬
[GET] /user/me/timeline

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@param	(Optional) only_report	보고서만 받아오기 (0: false, 1: true)
@return	JSON	게시물 리스트 + 댓글 수

타임라인 받아오기 (전체) - 비로그인

public 게시물만 받아옴 (당연히 보고서는 받아오지 않음. urgency, normal 순)
[GET] /timeline/all

구분	파라미터 or 타입	설명
@return	JSON	게시물 리스트 + 댓글 수

타임라인 받아오기 (전체) - 로그인

public 게시물만 받아옴 (당연히 보고서는 받아오지 않음. urgency, normal 순)
[GET] /timeline/all/withlogin

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@return	JSON	게시물 리스트 + 댓글 수

타임라인 받아오기 (특정 후원기관)

특정 후원기관의 public 게시물만 받아옴 (당연히 보고서는 받아오지 않음. urgency, normal 순)
[GET] /timeline/clover/{$clover_code}

구분	파라미터 or 타입	설명
@param	clover_code	후원기관 코드 (예: a01)
@return	JSON	게시물 리스트 + 댓글 수

타임라인 게시물 세부 내용

댓글 수도 가져와야 할듯. 수정예정
[GET] /timeline/{$board_id}

구분	파라미터 or 타입	설명
@param	board_id	게시물 ID
@return	JSON	게시물 상세

타임라인 글쓰기

[POST] /timeline/write

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN(기관담당자만)
@param	type	게시물 타입 (urgency: 긴급 후원, normal: 일반, report: 보고서 // report는 쓰이지 않음)
@param	text	게시물 텍스트 (제목 아님)
@param	image1	이미지 파일 (썸네일)
@param	image2	이미지 파일 2
@param	image3	이미지 파일 3
@param	limitation	limitation 권한 (public: 전체 공개, protected: 후원자만 공개, private: 비공개)
@param	due_date	(긴급후원인 경우. 아닌 경우 null을 보내면 됨) 후원 마감일. 형식: yyyy-mm-dd
@return	JSON	성공 메시지

반환 값

키	값	설명
error	type_should_be_assigned	타입이 null이나 empty일 때
error	text_will_not_be_empty	텍스트(내용)가 null이나 empty일 때
error	due_date_should_be_assinged	(긴급후원) 마감일이 null이나 empty일 때
error	limitation_should_be_assinged	권한이 null이나 empty일 때
success	write_success	글쓰기 성공

타임라인 수정

[POST] /timeline/modify/{$board_id}

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN(기관담당자만)
@param	board_id	게시물 ID
@param	type	게시물 타입 (urgency: 긴급 후원, normal: 일반, report: 보고서 // report는 쓰이지 않음)
@param	text	게시물 텍스트 (제목 아님)
@param	image1	이미지 파일 (썸네일)
@param	image2	이미지 파일 2
@param	image3	이미지 파일 3
@param	limitation	limitation 권한 (public: 전체 공개, protected: 후원자만 공개, private: 비공개)
@param	due_date	(긴급후원인 경우. 아닌 경우 null을 보내면 됨) 후원 마감일. 형식: yyyy-mm-dd
@return	JSON	성공 메시지

반환 값

키	값	설명
error	type_should_be_assigned	타입이 null이나 empty일 때
error	text_will_not_be_empty	텍스트(내용)가 null이나 empty일 때
error	due_date_should_be_assinged	(긴급후원) 마감일이 null이나 empty일 때
error	limitation_should_be_assinged	권한이 null이나 empty일 때
success	write_success	글쓰기 성공

타임라인 삭제

[POST] /timeline/delete/{$board_id}

구분	파라미터 or 타입	설명
@param	api_token	USER TOKEN(기관담당자만 - 글쓴이만 삭제됨)
@param	board_id	게시물 ID
@return	JSON	성공 메시지

타임라인 좋아요

[POST] /timeline/like/{$board_id}

구분	파라미터 or 타입	설명
@param	api_token	USER TOKEN
@param	board_id	게시물 ID
@return	JSON	성공 메시지

반환 값

키	값	설명
success	success_like_board	좋아요 시
success	success_dislike_board	좋아요 취소 시

타임라인 댓글 불러오기

[GET] /timeline/comment/{$board_id}

구분	파라미터 or 타입	설명
@param	board_id	게시물 ID
@return	JSON	댓글 리스트 (+ properties)

타임라인 댓글 글쓰기

[POST] /timeline/comment/write

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN
@param	board_id	게시물 ID
@param	text	게시물 텍스트 (제목 아님)
@return	JSON	성공 메시지

타임라인 댓글 수정

[POST] /timeline/comment/modify/{comment_id}

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN (글쓴이만 가능)
@param	comment_id	댓글 ID
@param	text	게시물 텍스트 (제목 아님)
@return	JSON	성공 메시지

타임라인 댓글 삭제

[POST] /timeline/comment/delete/{comment_id}

구분	파라미터 or 타입	설명
@header	api-token	USER TOKEN (글쓴이만 가능)
@param	comment_id	댓글 ID
@return	JSON	성공 메시지

반환 값

키	값	설명
error	delete_comment_failed	댓글 삭제 실패
success	delete_comment_success	댓글 삭제 성공

기타

인증 번호 발송 API

실제 문자 발송되니 테스트는 적당히!
[GET] /sms/auth

구분	파라미터 or 타입	설명
@param	phone_num	핸드폰 번호
@return	JSON	인증번호

---

결제

결제 시스템은 API서버가 아닌 클로버가든 웹서버에 해당됩니다. 즉, 직접 웹페이지를 호출하는 형태로 구성이 됩니다.
안드로이드 혹은 iOS 웹뷰에서 호출되어야 하는 URL은 다음과 같습니다.
일시 후원 http://clovergarden.co.kr/agspay/AGSMobile_start_temp?seq=[company_id]
정기 후원 http://clovergarden.co.kr/agspay/AGSMobile_start_resv?seq=[company_id]

[company_id] 값에는 기관의 id(seq)가 들어옵니다.

주의! 상기 URL 요청또한 Custom Header가 필요합니다. 로그인을 위해서 api-token키를 token으로 지정하여 주세요.

리턴

상기 웹은 결제에 성공하면 clovergardenapp:// 이라는 APP URL Scheme을 호출합니다. 따라서 적용되는 스마트폰 애플리케이션에서 clovergardenapp이라는 URL Scheme이 호출되면 다시 앱 메인으로 돌아가도록 하시면 됩니다.
예)iOS

// webView에서 request가 존재할 때 호출되는 delegate
- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:  (UIWebViewNavigationType)navigationType  
{  
    NSURL *url = request.URL;  
    if ([url.scheme isEqualToString:@"http"]) {  
        return YES;  
    } else if ([url.scheme isEqualToString:@"clovergardenapp"]) { // URL Scheme이 clovergardenapp일 때  
        [self backToMain:self]; // 컨트롤러 종료 후 메인 컨트롤러로 돌아옴
      
        return NO;  
    }  
 
    return YES;  
} 

---

FAQ / 공지사항

안드로이드는 iOS와 달리 직접 URL을 받아서 처리합니다. 처리되는 URL은 다음과 같습니다.
공지사항 http://clovergarden.co.kr/mobile/notice/list/{id}
FAQ http://clovergarden.co.kr/mobile/faq/list/{id}

{id}는 보여줄 게시물의 sequence입니다.

---

FCM 푸시

FCM 푸시에 관한 내용은 직접 FCM문서( https://firebase.google.com/docs/cloud-messaging/ )를 찾아보셔도 되나, 필요한 부분이 한정적이기에 문서에 따로 정리합니다.
필요한 것은 API KEY와 보내질 내용 2가지입니다.
다음의 내용(JSON)으로 HTTP 리퀘스트(POST)를 전송하시면 됩니다.
URL: https://fcm.googleapis.com/fcm/send
------------------------------------ HEADER --------------------------------------
Content-Type: application/json
Authorization: key=AIzaSyAEyaxzaSjR7ViHaphBKxm6R8dVSXQ838s // 클로버가든의 서버키입니다.

{
  "to": "/topics/news",
  "notification": {
    "body": "This is a Firebase Cloud Messaging Topic Message!",
   }
}

클로버가든 앱에서는 모든 메시지를 news라는 토픽에 보내기로 합니다.
위의 요청이 성공적으로 완료되면 message_id라는 키를 가진 json 데이터를 반환합니다.