개발가이드 - 장기요양시설 개방형 API 통합플랫폼

1 인증 및 API 키

모든 API 요청에는 발급받은 API 키가 필요합니다. API 키는 HTTP 헤더에 포함하여 전송합니다.

요청 헤더

Authorization: Bearer {API_KEY}
Content-Type: application/json

서버 환경

환경	URL	용도
테스트	`https://test-api.ltc.or.kr`	개발 및 테스트
운영	`https://api.ltc.or.kr`	실제 서비스

2 암호화

민감한 데이터 전송 시 암호화가 필요합니다. AES-256 암호화를 사용합니다.

암호화 대상 필드

주민등록번호
건강보험번호
연락처
주소

암호화 예시 (Python)

from Crypto.Cipher import AES
import base64

def encrypt_data(plain_text, key):
    cipher = AES.new(key.encode(), AES.MODE_CBC, iv)
    encrypted = cipher.encrypt(pad(plain_text.encode(), AES.block_size))
    return base64.b64encode(encrypted).decode()

# 사용 예시
encrypted_ssn = encrypt_data("123456-1234567", SECRET_KEY)

암호화 예시 (Java)

import javax.crypto.Cipher;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public String encrypt(String plainText, String key) {
    SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(), "AES");
    Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
    cipher.init(Cipher.ENCRYPT_MODE, secretKey);
    byte[] encrypted = cipher.doFinal(plainText.getBytes());
    return Base64.getEncoder().encodeToString(encrypted);
}

3 API 명세

건강 데이터 전송 API

Method	Endpoint	설명
POST	`/api/v1/health-data`	건강 데이터 전송
GET	`/api/v1/health-data/{id}`	건강 데이터 조회
PUT	`/api/v1/health-data/{id}`	건강 데이터 수정
DELETE	`/api/v1/health-data/{id}`	건강 데이터 삭제

요청 본문 예시

{
  "resident_id": "R12345",
  "device_type": "blood_pressure",
  "measured_at": "2024-03-25T14:30:00+09:00",
  "data": {
    "systolic": 120,
    "diastolic": 80,
    "pulse": 72
  }
}

응답 예시

{
  "success": true,
  "data": {
    "id": "HD20240325143000001",
    "status": "received"
  },
  "timestamp": "2024-03-25T14:30:01+09:00"
}

4 에러 처리

API 에러 발생 시 적절한 HTTP 상태 코드와 에러 메시지가 반환됩니다.

에러 코드

HTTP 코드	에러 코드	설명
400	INVALID_REQUEST	잘못된 요청 형식
401	UNAUTHORIZED	인증 실패 (API 키 오류)
403	FORBIDDEN	권한 없음
404	NOT_FOUND	리소스 없음
429	RATE_LIMIT	요청 한도 초과
500	SERVER_ERROR	서버 오류

에러 응답 예시

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "timestamp": "2024-03-25T14:30:01+09:00"
}

5 Swagger UI 사용법

Swagger UI를 통해 API를 직접 테스트할 수 있습니다.

발급받은 API 키로 Swagger UI에 접속합니다.
우측 상단의 "Authorize" 버튼을 클릭합니다.
API 키를 입력하고 인증합니다.
원하는 API를 선택하고 "Try it out" 버튼을 클릭합니다.
요청 파라미터를 입력하고 "Execute" 버튼을 클릭합니다.

Swagger UI는 API 키 발급 후 이용할 수 있습니다. Swagger UI 바로가기

기술 지원이 필요하신가요?

API 연동 관련 문의사항은 아래 연락처로 문의해 주세요.

api-support@ltc.or.kr

API 개발 가이드

목차