API 호출

오퍼레이션을 요청할 때는 HTTP 메서드와 요청 URL을 결합한다. 예를 들어, 메일을 발송하는 오퍼레이션은 다음과 같다.

예) 메일 발송 오퍼레이션

POST https://apis.worksmobile.com/{API ID}/mail/sendMail

개별 API 설명에서 서비스 환경에 대한 요청 URL을 확인할 수 있다.

Request 공통

API를 호출할 때는 반드시 헤더에 NAVER WORKS 토큰과 컨슈머키를 포함해야 한다. NAVER WORKS 토큰 및 컨슈머키 발급 방법은 API 인증 준비를 참고한다.

헤더에 NAVER WORKS 토큰과 컨슈머키를 설정하는 방법은 다음과 같다.

주의

Authorization 타입으로 'Bearer'를 반드시 명시해야 하며, 'Bearer'와 'Token' 사이에 공백(space)을 빠트리지 않도록 주의한다.

method.setRequestHeader("consumerKey", "컨슈머키");
method.setRequestHeader("Authorization", "Bearer 토큰");

Response 공통

API 호출에 실패하면 오류 코드와 오류 메시지가 반환된다.

참고

API 성공 시 결과 형태는 API마다 다르므로 개별 API 설명을 참고한다.

속성	타입	필수 여부	설명
errorCode	String	Y	오류 코드
errorMessage	String	Y	오류 메시지

상세한 오류 코드와 오류 메시지 종류는 다음과 같다.

코드	REST HTTP 상태 코드	메시지	설명
001	404	Not support url	지원하지 않는 URL로 호출
002	404	Not support port	지원하지 않는 Port로 호출
024	401	Authentication failed	컨슈머키와 토큰의 인증 실패
028	401	Authentication header not exists	컨슈머키와 토큰이 헤더에 없음
029	401	Malformed authentication header	헤더의 컨슈머키와 토큰 형식이 틀림
041	403	Not allowed tenantApiId	허가되지 않은 고객사 API ID로 호출
042	403	Not allowed consumerKey	허가되지 않은 컨슈머키 호출
043	403	Not allowed remote ip	허가되지 않은 IP에서 호출
044	403	Not allowed domainId	허가되지 않은 도메인 호출
045	403	Not allowed service	권한이 없는 서비스 호출
051	404	Api not exists	존재하지 않는 API
064	405	Malformed http method	지원하지 않는 HTTP Method
065	400	Mandatory parameter not exists	필수 파라미터 없음
081	400	Target not exists	대상이 존재하지 않음
083	500	Additional information fail	추가 정보 획득에 실패
085	429	Daily quota fail	일별 쿼터 초과
086	503	Service use fail	서비스(메일, 메시지 봇 등) 사용 실패
087	403	Domain stop	도메인이 일시 정지된 경우
088	403	Blacklist	도메인 또는 IP 주소가 blacklist인 경우
089	400	Malformed json parameter	contentType이 application/json인데 파라미터가 JSON 형식이 아닌 경우
090	503	Service fail	서비스(메일, 메시지 봇 등) 내부 오류 예) {errorMessage=Service fail, HTTP/1.1 400 bad_path(name), errorCode=090}
092	429	API rate limit exceeded	Rate Limit 초과
999	500	Unknown error	알 수 없는 에러

API별로 발생하는 오류 코드와 오류 메시지는 각 API 설명에서 확인할 수 있다.

샘플 코드

서비스 API 샘플 코드

소스 코드에 필요한 consumerKey는 Developer Console에서 발급받는다.


/* authorization code 요청 */

var consumerKey = "LQwDde6x8eV4ROOCOdSW";
var url = "https://auth.worksmobile.com/oauth/authorize?client_id=" + consumerKey
               + "&redirect_uri=https://mydomain.com/getToken"
               + "&domain=mydomain.com";

window.open(url, 'authorize' , 'width=600px,height=800px');


/**
 * https://mydomain.com/getToken
 * Authorization Code 획득 후 Access Token 요청
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServiceApiTest {

    public void testGetAccessToken() throws Exception {
        String url = "https://auth.worksmobile.com/oauth/token";
        String consumerKey = "LQwDde6x8eV4ROOCOdSW";
        String authorizationCode = "QkJxMFc4ekRnMGdLNjhOMQ==";
        String domain = "mydomain.com";

        PostMethod method = new PostMethod(url);
        NameValuePair[] parameters = new NameValuePair[3];
        parameters[0] = new NameValuePair("client_id", consumerKey);
        parameters[1] = new NameValuePair("code", authorizationCode);
        parameters[2] = new NameValuePair("domain ", domain);
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
        /* response={"errorCode":"00","expire_in":"604800","refresh_token":"AAAAT/bdZsj81ULzym+URwKwM+OEj69MPhkqDuFiWMRjSZkR+Yk","access_token":"AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW"}
         response에서 accessToken을 추출하여 별도 저장할 것을 권장 */
    }
}


/** 
 * 서비스 API 호출
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServiceApiTest {

    public void testServiceApi() throws Exception {
        String url = 
             "https://apis.worksmobile.com/kr1wwTrYrbIot/calendar/getCalendar";
        String consumerKey = "LQwDde6x8eV4ROOCOdSW";
        String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW";

        PostMethod method = new PostMethod(url);
        method.setRequestHeader("consumerKey", consumerKey);
        method.setRequestHeader("Authorization", "Bearer " + token);

        NameValuePair[] parameters = new NameValuePair[1];
        parameters[0] = new NameValuePair("calendarId", "1234");
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
    }
}

서버 API 샘플 코드

소스 코드에 필요한 consumerKey와 token은 Developer Console에서 발급 받는다.


/** 
 * 서버 API 호출
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServerApiTest {

    public void testServerApi() throws Exception {
        String url = 
                     "https://apis.worksmobile.com/kr1wwTrYrbIot/admin/getDomain";
        String consumerKey = "dz0jtXyXc9Zo953HdjZA";
        String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLWt";

        PostMethod method = new PostMethod(url);
        method.setRequestHeader("consumerKey", consumerKey);
        method.setRequestHeader("Authorization", "Bearer " + token);

        NameValuePair[] parameters = new NameValuePair[1];
        parameters[0] = new NameValuePair("params", "{\"domain\":\"mydomain.com\"}");
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
    }
}

동시 접속

동시 접속 가능 요청 수는 5이다. 허용된 동시 접속 요청 수를 넘으면 API 호출에 실패할 수 있다.

Rate Limit

Rate Limit란 특정 시간 내에 할 수 있는 API 호출 수를 의미한다. 사용자의 API 호출 수가 Rate Limit값을 초과하면 API 호출이 제한되며 요청이 실패하게 된다. 실패 시엔 아래와 같은 응답을 반환한다.

코드	REST HTTP 상태 코드	메시지	설명
092	429	API rate limit exceeded	Rate Limit 초과

Message, Contact, Organization 3개의 서비스에 Rate Limit가 적용되며, Rate Limit값은 상품별로 차등 적용한다.

적용대상

Category	Product	Rate Limit
Message	Free	1 API 당 60/min
Message	Lite, Basic, Premium	1 API 당 200/min
Contact	Lite, Basic, Premium	1 API 당 120/min
Organization	Lite, Basic, Premium	1 API 당 1000/min 아래의 API들은 1 API당 600 request/min으로 변경 ● 구성원 추가 ● 구성원 수정 ● 구성원 부분 수정 ● 구성원 삭제 ● 구성원 삭제 취소 ● 구성원 즉시 삭제

참고

Organization API 사용 시 주의를 확인한다.

Rate Limit가 적용된 Message, Contact, Organization API를 호출하면 아래와 같이 응답에 3가지 헤더가 추가된다. 이를 통해 현재 API 호출 수, 남은 API 호출 수, 갱신까지 남은 시간을 알 수 있다.

헤더	설명	단위
RateLimit-Limit	기준 시간 단위 API 호출 수
RateLimit-Remaining	기준 시간 단위 남은 API 호출 수
RateLimit-Reset	기준 시간 갱신까지 남은 시간	초

NAVER WORKS Developers