개발자 문서

공개 API v1

서식을 검색하고, 변수 스키마를 조회하고, 값을 채워 완성 문서를 생성합니다.콘솔 > API·MCP 키에서 키를 발급하세요. (프리미엄 포함)

인증

모든 요청에 Authorization: Bearer <API_KEY> 헤더가 필요합니다.

curl https://pinderform.com/api/v1/forms?query=근로계약서 \
  -H "Authorization: Bearer pf_live_xxx"

Claude 등 AI 에이전트에서는 MCP 서버가 이 API를 그대로 감싸search_forms·get_form_schema·create_document 도구로 제공합니다. 같은 계약, 이중 구현 없음.

GET/api/v1/forms?query=

서식 검색(요약). 서식명·설명·키워드 매칭, 상위 20건.

{
  "count": 3,
  "forms": [
    {
      "id": "labor/standard-employment-contract",
      "category": "labor",
      "slug": "standard-employment-contract",
      "name": "표준근로계약서 (기간의 정함이 없는 경우)",
      "description": "...",
      "free": true
    }
  ]
}

GET/api/v1/forms/{category}/{slug}/schema

변수 스키마. 그룹·필드(타입·필수·옵션·자동계산·조건부) 반환.

{
  "id": "labor/standard-employment-contract",
  "name": "표준근로계약서 ...",
  "groups": ["사업주", "근로자", "근로조건", "임금", "기타"],
  "fields": [
    { "key": "employer_company", "label": "사업체명",
      "type": "text", "required": true, "group": "사업주" },
    { "key": "monthly_salary", "label": "월급", "type": "money",
      "required": true, "group": "임금", "computed": "annual_salary" }
  ]
}

POST/api/v1/documents

값을 채워 완성 문서 생성 + 문서함 저장 + 공유 다운로드 URL 반환. 필수 필드 누락 시 422로 어떤 값이 필요한지 안내(MCP는 설문으로 수집).

// 요청
{ "form": "labor/standard-employment-contract",
  "values": { "employer_company": "주식회사 핀더", "employee_name": "홍길동" },
  "name": "홍길동 근로계약서" }

// 응답 200
{ "id": "doc_...", "name": "홍길동 근로계약서",
  "download": { "pdf": "https://.../d/<token>?format=pdf",
                "docx": "https://.../d/<token>?format=docx" } }

// 응답 422 — 필수 필드 누락
{ "error": "missing_required_fields",
  "missing": [ { "key": "employer_name", "label": "대표자 성명", ... } ] }

에러 코드

401 unauthorized — 키 누락/무효
402 limit_exceeded — 무료 AI 작성 한도 초과(프리미엄 필요)
404 form not found
422 missing_required_fields — 필수 필드 누락