광고연구소

OnSureLab API

개발 중

OnSureLab 서비스 연동을 위한 API 명세서입니다.

API 문서 내보내기

OpenAPI YAML

openapi.yaml (2,205 lines)

API 문서 (Markdown)

onsurelab-api-public.md (1,184 lines)

인증

모든 API 요청에는 API Key가 필요합니다. API Key는 담당자에게 발급받으세요.

요청 헤더

모든 API 요청 시 헤더에 X-API-Key를 포함해야 합니다.

X-API-Key: your-api-key-here

개발 환경 vs 운영 환경

OnSureLab API는 개발(dev)과 운영(prod) 두 가지 환경을 제공합니다. 발급받은 API Key에 따라 자동으로 환경이 결정됩니다.

환경	API Key 예시	용도
DEV	xxx-partner-dev	개발/테스트용. 테스트 DB 사용
PROD	xxx-partner	실제 서비스용. 운영 DB 사용

주의:개발 중에는 반드시 DEV 키를 사용하세요. PROD 키로 테스트하면 실제 데이터에 영향을 줍니다.

요청 예시

cURL

curl -X GET "https://api.example.com/api/onsurelab/users" \
  -H "X-API-Key: your-api-key-here"

JavaScript (fetch)

const response = await fetch('/api/onsurelab/users', {
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});
const data = await response.json();

인증 실패 응답

API Key 누락 (401)

{
  "success": false,
  "error": "API Key가 필요합니다."
}

유효하지 않은 API Key (401)

{
  "success": false,
  "error": "유효하지 않은 API Key입니다."
}

에러 응답

401 Unauthorized

{
  "success": false,
  "error": "API Key가 필요합니다."
}

404 Not Found

{
  "success": false,
  "error": "유저를 찾을 수 없습니다."
}

409 Conflict

{
  "success": false,
  "error": "이미 존재하는 이메일입니다."
}

500 Server Error

{
  "success": false,
  "error": "서버 오류 메시지"
}

DB 스키마

테이블	관계	용도
user	-	유저 (이메일, 비밀번호, 이름, 역할)
phone_verification	-	휴대폰 인증번호 (4자리, 5분 만료)
execution	user 1:N	집행건 메인 데이터 (draft + step2Payload JSON)
execution_file	execution 1:N	업로드 파일 메타 (URL, category, step)
execution_message	execution 1:N	외주 소통 채팅 메시지
execution_deliverable	execution 1:N	업체 결과물/시안 (버전 관리)
execution_plan	execution 1:1	집행계획서 (9개 섹션 + 테이블)

user

CREATE TABLE user (
    id         BIGINT PRIMARY KEY AUTO_INCREMENT,
    email      VARCHAR(255) NOT NULL UNIQUE,
    password   VARCHAR(255) NOT NULL,
    name       VARCHAR(100) NOT NULL,
    phone      VARCHAR(20),
    company    VARCHAR(200),
    role       VARCHAR(50) NOT NULL DEFAULT 'DEVELOPER',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

phone_verification

CREATE TABLE phone_verification (
    id          BIGINT PRIMARY KEY AUTO_INCREMENT,
    phone       VARCHAR(20) NOT NULL,
    code        VARCHAR(10) NOT NULL,
    is_verified TINYINT(1) NOT NULL DEFAULT 0,
    expires_at  TIMESTAMP NOT NULL,
    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_phone_verification_phone (phone)
);

execution

CREATE TABLE execution (
    id             VARCHAR(50) PRIMARY KEY,        -- "exec_" + UUID
    user_id        BIGINT NOT NULL,
    title          VARCHAR(255) DEFAULT NULL,
    current_step   INT NOT NULL DEFAULT 1,         -- 1~10
    status         VARCHAR(20) NOT NULL DEFAULT 'DRAFT',
                                                   -- DRAFT | IN_PROGRESS | COMPLETED
    step2_payload  JSON DEFAULT NULL,              -- Step 2 집행 조건 전체
    draft          JSON DEFAULT ('{}'),            -- Step 3~10 진행 데이터
    created_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES user(id),
    INDEX idx_execution_user_id (user_id),
    INDEX idx_execution_status (status)
);

execution_file

CREATE TABLE execution_file (
    id            VARCHAR(50) PRIMARY KEY,         -- "file_" + UUID
    execution_id  VARCHAR(50) NOT NULL,
    url           VARCHAR(1000) NOT NULL,          -- Naver Object Storage URL
    original_name VARCHAR(255) NOT NULL,
    size          BIGINT NOT NULL DEFAULT 0,
    mime_type     VARCHAR(100),
    category      VARCHAR(30) NOT NULL,            -- reference | logo | brand_guide
                                                   -- | evidence | deliverable
    step          INT,                             -- 어떤 스텝에서 올린 건지 (5, 7, 9 등)
    uploaded_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (execution_id) REFERENCES execution(id) ON DELETE CASCADE,
    INDEX idx_execfile_execution_id (execution_id),
    INDEX idx_execfile_category (category)
);

execution_message

CREATE TABLE execution_message (
    id            VARCHAR(50) PRIMARY KEY,         -- "msg_" + UUID
    execution_id  VARCHAR(50) NOT NULL,
    sender        VARCHAR(20) NOT NULL,            -- USER | VENDOR | SYSTEM
    text          TEXT NOT NULL,
    files         JSON DEFAULT NULL,               -- 첨부파일 URL 배열
    timestamp     BIGINT NOT NULL,                 -- Unix timestamp (ms)
    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (execution_id) REFERENCES execution(id) ON DELETE CASCADE,
    INDEX idx_execmsg_execution_id (execution_id),
    INDEX idx_execmsg_timestamp (timestamp)
);

execution_deliverable

CREATE TABLE execution_deliverable (
    id            VARCHAR(50) PRIMARY KEY,         -- "dlv_" + UUID
    execution_id  VARCHAR(50) NOT NULL,
    version       INT NOT NULL DEFAULT 1,          -- 같은 execution 내 자동 증가
    url           VARCHAR(1000) NOT NULL,
    original_name VARCHAR(255) NOT NULL,
    size          BIGINT NOT NULL DEFAULT 0,
    mime_type     VARCHAR(100),
    note          VARCHAR(500),                    -- 메모 ("초안", "수정본 v2" 등)
    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    created_by    VARCHAR(50),                     -- 업로드한 유저/업체 ID
    FOREIGN KEY (execution_id) REFERENCES execution(id) ON DELETE CASCADE,
    INDEX idx_execdlv_execution_id (execution_id)
);

execution_plan

CREATE TABLE execution_plan (
    id            VARCHAR(50) PRIMARY KEY,         -- "plan_" + UUID
    execution_id  VARCHAR(50) NOT NULL UNIQUE,     -- 1:1 관계
    meta          JSON DEFAULT NULL,
    sections      JSON DEFAULT NULL,               -- 9개 섹션
                                                   -- overview, background, strategy,
                                                   -- details, schedule, kpi,
                                                   -- budget, evidence, risk
    tables_data   JSON DEFAULT NULL,               -- budgetItems, scheduleItems 등
    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (execution_id) REFERENCES execution(id) ON DELETE CASCADE,
    INDEX idx_execplan_execution_id (execution_id)
);

API 엔드포인트