API 명세서
개요
TSA서버로 PDF에 서명을 추가하는 TimeStamp 요청을 위한 API를 정의합니다.
API 목록
분류
API 명
설
비
PDF 파일
로컬 PDF파일 서명
WAS내부에 저장되어 있는 PDF파일을 타임스탬프 서명을 추가해서 다른 위치에 저장
PDF 파일
원격 PDF파일 서명
클라이언트가 업로드한 PDF파일을 타임스탬프 서명을 추가해서 반환
회사코드 누락 및 등록되지 않은 코드 사용시 서비스 불가
PDF 파일
PDF파일 검증
클라이언트가 업로드한 PDF파일의 서명을 검증.
API 상세정보
1. 로컬 PDF파일 서명
WAS내부에 저장되어 있는 PDF파일을 타임스탬프 서명을 추가해서 다른 위치에 저장
* 유의사항 : API 사용을 위해서는 사본파일과 원본파일의 저장 위치가 TSA가 설치된 서버가 파일경로에 접근할 수 있는 동일 서버(Local)에 존재해야 사용 가능합니다.
URL
Method : POST
Endpoint : $SERVER/api/ext/signpdf
Content-Type: application/x-www-form-urlencoded
입력 파라미터
필드명
타입
비고
in
string
서명을 추가할 pdf파일 경로. 절대경로
예) /opt/pdfs/raw/fileA.pdf
out
string
서명이 추가된 pdf파일 경로. 절대경로
예) /opt/pdfs/signed/fileA_signed.pdf
category
string
서명 방식 (대소문자 구분 없음). 생략할 경우 기본값은 AERGO AERGO: 서버에 설치한 인증서로 서명한 Timestamp토큰 발행
companyId
string
DTT Alliance가 발급한 companyid
응답
Content-Type: plain/text
HTTP status:
200 성공
400 잘못된 요청으로 인한 실패
500 서버쪽 문제로 실패
BODY:
성공시: 결과 파일명 (UTF-8 인코딩 바이트)
실패시: 오류종류
오류 종류
이름
설명
NotFound
입력 파일이 없음
Invalid
입력 파일을 읽는데 실패함, 혹은 잘못된 category 값.
WriteFail
출력 파일이 이미 있는 파일 혹은 쓰기 권한이 없는 파일 경로
Internal
TSA서버 이상
샘플코드
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.Map;
public class SignByPathSender {
private static final int API_TIMEOUT = 300 * 1000; // 30 seconds
public static void main(String[] args) throws MalformedURLException {
URL url = new URL("http://localhost:8080/api/ext/signpdf"); //Aergo TSA서버의 주소로 변경
Map<String, String> params = new HashMap<>();
params.put("in", args[0]);
params.put("out", args[1]);
params.put("category", args[2]);
try {
byte[] result = postForm(url, params);
System.out.println("success: result file is in " + new String(result));
} catch (IllegalArgumentException e) {
String cause = e.getMessage(); // 서버쪽에서 알린 실패 이유
System.out.println("server response error: " + cause);
} catch (IOException e) {
String cause = e.getMessage();
System.out.println("unexpected failure: " + cause);
}
}
private static byte[] postForm(URL url, Map<String, String> params) throws IllegalArgumentException, IOException {
try {
HttpURLConnection con = (HttpURLConnection) url.openConnection();
con.setConnectTimeout(API_TIMEOUT); //서버에 연결되는 Timeout 시간 설정
con.setReadTimeout(API_TIMEOUT); // InputStream 읽어 오는 Timeout 시간 설정
con.setRequestMethod("POST"); //POST 방식 선언
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded"); //content-type 선언
con.setDoInput(true);
con.setDoOutput(true); //POST 데이터를 OutputStream으로 넘겨 주겠다는 설정
con.setUseCaches(false);
con.setDefaultUseCaches(false);
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> ent : params.entrySet()) {
sb.append(ent.getKey()).append('=').append(URLEncoder.encode(ent.getValue(), "UTF-8"));
sb.append('&');
}
sb.deleteCharAt(sb.length() - 1);
con.getOutputStream().write(sb.toString().getBytes());
con.getOutputStream().flush();
if (con.getResponseCode() == HttpURLConnection.HTTP_OK) {
byte[] bytes = readToByteArray(con.getInputStream());
return bytes;
} else {
int responseCode = con.getResponseCode();
byte[] bytes = readToByteArray(con.getErrorStream());
throw new IllegalArgumentException(new String(bytes));
}
} catch (IOException e) {
// FIXME
throw new IOException("io exception", e);
}
}
private static byte[] readToByteArray(InputStream is) throws IOException {
ByteArrayOutputStream buffer = new ByteArrayOutputStream();
int nRead;
byte[] data = new byte[4096];
while ((nRead = is.read(data, 0, data.length)) != -1) {
buffer.write(data, 0, nRead);
}
return buffer.toByteArray();
}
}
2. 원격 PDF파일 서명
클라이언트가 업로드한 PDF파일을 타임스탬프 서명을 추가해서 반환
URL
Method : POST
Endpoint : $SERVER/api/ext/pdf/sign
Content-Type: multipart/form-data
입력 파라미터
필드명
타입
비고
inpdf
binary
서명을 추가할 pdf파일 데이터
filename
string
결과 pdf파일의 이름. 추후 서버 검색용도로 사용함
category
string
서명 방식 (대소문자 구분 없음). 생략할 경우 기본값은 AERGO AERGO: 서버에 설치한 인증서로 서명한 Timestamp토큰 발행
companyId
string
회사코드는 반드시 등록된 회사코드로 사용해야 함.
만약 등록되지 않은 회사코드로 접근시 InvalidParam에러 발생
응답
Content-Type: application/json
HTTP status:
200 성공
400 잘못된 요청으로 인한 실패
500 서버쪽 문제로 실패
BODY:
성공시: SignResult
실패시: 오류종류
SignResult
필드명
타입
비고
docHash
string
hexa-decimal 인코딩된 문서 해시
txhash
string
base58 인코딩된 블록체인 tx해시
filename
string
결과 pdf파일의 이름. 요청때 보낸 것과 동일한 이름
outpdf
byte[]
서명이 추가된 PDF파일 데이터. base64로 인코딩된 바이트 배열
오류 종류
이름
설명
NotFound
입력 파일이 없음
Invalid
입력 파일을 읽는데 실패함, 혹은 잘못된 category 값. 혹은 회사코드 누락
WriteFail
출력 파일이 이미 있는 파일 혹은 쓰기 권한이 없는 파일 경로
Internal
TSA서버 이상
3. PDF파일 검증
클라이언트가 업로드한 PDF파일을 타임스탬프 서명을 추가해서 반환
URL
Method : GET
Endpoint : $SERVER/api/ext/pdf/sign
Content-Type: multipart/form-data
입력 파라미터
필드명
타입
비고
inpdf
binary
서명을 추가할 pdf파일 데이터
filename
string
결과 pdf파일의 이름. 추후 서버 검색용도로 사용함
category
string
서명 방식 (대소문자 구분 없음). 생략할 경우 기본값은 AERGO AERGO: 서버에 설치한 인증서로 서명한 Timestamp토큰 발행
응답
Content-Type: application/json
HTTP status:
200 성공
400 잘못된 요청으로 인한 실패
500 서버쪽 문제로 실패
BODY:
성공시: SignResult
실패시: 오류종류
SignResult
필드명
타입
비고
docHash
string
hexa-decimal 인코딩된 문서 해시
txhash
string
base58 인코딩된 블록체인 tx해시
filename
string
결과 pdf파일의 이름. 요청때 보낸 것과 동일한 이름
outpdf
byte[]
서명이 추가된 PDF파일 데이터. base64로 인코딩된 바이트 배열
오류 종류
이름
설명
NotFound
입력 파일이 없음
Invalid
입력 파일을 읽는데 실패함, 혹은 잘못된 category 값.
WriteFail
출력 파일이 이미 있는 파일 혹은 쓰기 권한이 없는 파일 경로
Internal
TSA서버 이상
Last updated