--- title: "SW CPAs API·MCP 개발자 문서 | 에스더블유 공인회계사 사무소" description: "SW CPAs 공개 API와 MCP 서버 문서입니다. AI 에이전트와 개발자는 가입·키 없이 사무소 정보, 서비스, 글 검색, 미국 진출 진단을 쓰고 사용자를 대신해 상담을 신청할 수 있습니다. OpenAPI, MCP, WebMCP, NLWeb 연결 방법을 안내합니다." canonical: "https://sw-cpas.co.kr/developers/" lang: "ko" --- [홈](https://sw-cpas.co.kr/)개발자 문서 # SW CPAs API · MCP 개발자 문서 가입·API 키 없이 바로 쓰는 공개 API **결론부터:** SW CPAs API와 MCP 서버는 가입이나 API 키 없이 바로 씁니다. 사무소 정보·서비스·글 검색·미국 진출 진단은 읽기 전용이고, 쓰기 작업은 사용자를 대신한 상담 신청 하나뿐입니다. 모든 기능은 무료입니다. ## 한눈에 보기 - OpenAPI 3.1 계약: [`/openapi.json`](https://sw-cpas.co.kr/openapi.json) - MCP 서버(제품): `https://sw-cpas.co.kr/mcp` (Streamable HTTP) · 서버 카드 [`/.well-known/mcp/server-card.json`](https://sw-cpas.co.kr/.well-known/mcp/server-card.json) - MCP 서버(문서): `https://sw-cpas.co.kr/mcp/docs` · 서버 카드 [`/.well-known/mcp/docs-server-card.json`](https://sw-cpas.co.kr/.well-known/mcp/docs-server-card.json) - NLWeb 질의: `GET /ask?q=…` 또는 `POST /ask` - WebMCP: 홈 화면이 브라우저 에이전트용 도구를 등록합니다. - 에이전트 자원 목록: [`/.well-known/ard.json`](https://sw-cpas.co.kr/.well-known/ard.json) · API 목록 [`/.well-known/api-catalog`](https://sw-cpas.co.kr/.well-known/api-catalog) · 에이전트 스킬 [`/.well-known/agent-skills/index.json`](https://sw-cpas.co.kr/.well-known/agent-skills/index.json) - 사이트 안내: [`/llms.txt`](https://sw-cpas.co.kr/llms.txt) · 이 섹션 안내 [`/developers/llms.txt`](https://sw-cpas.co.kr/developers/llms.txt) · 인증 안내 [`/auth.md`](https://sw-cpas.co.kr/auth.md) - 공식 에이전트 키트(GitHub): [`samorj16-bot/sw-cpas-agent`](https://github.com/samorj16-bot/sw-cpas-agent). 에이전트 플러그인, 스킬, `AGENTS.md`, 명령줄 도구가 있습니다. 명령줄 도구는 npm 패키지 [`sw-cpas-mcp`](https://www.npmjs.com/package/sw-cpas-mcp)로도 설치할 수 있습니다(`npx sw-cpas-mcp firm`, 인자 없이 실행하면 표준입출력 MCP 서버). MCP 공식 레지스트리 이름은 `kr.co.sw-cpas/mcp` 입니다. ## 빠른 시작 가입 단계가 없으므로 첫 호출이 곧 시작입니다. ```bash curl https://sw-cpas.co.kr/api/v1/firm curl "https://sw-cpas.co.kr/api/v1/insights?q=LLC&limit=5" curl -X POST https://sw-cpas.co.kr/api/v1/us-incorporation/evaluate \ -H "Content-Type: application/json" \ -d '{"answers":{"business_type":"saas","presence":"none","owner":"korean_corp","funding":"yes_12mo","visa":"stay_korea","profit":"reinvest","privacy":"none","revenue":"lt_100k"}}' ``` ## 엔드포인트 | 메서드 | 경로 | 내용 | |---|---|---| | `GET` | `/api/v1/firm` | 사무소 정보(대표 자격·사무소·연락처·견적 방식) | | `GET` | `/api/v1/services` | 서비스 목록과 각 페이지 주소, 무료 도구 | | `GET` | `/api/v1/insights` | 글 목록·검색(q, category, limit 1~50, cursor) | | `GET` | `/api/v1/us-incorporation/questions` | 미국 진출 진단 질문과 허용 값 | | `POST` | `/api/v1/us-incorporation/evaluate` | 추천 설립 주·법인 형태·1년차 비용 계산(저장하지 않음) | | `POST` | `/api/v1/consultation-requests` | 사용자를 대신한 상담 신청. 202 와 상태 주소(Location)를 돌려줌(dry_run 시험 모드, Idempotency-Key) | | `GET` | `/api/v1/consultation-requests/{request_id}` | 상담 신청 접수 상태(개인정보 없음) | 목록 응답은 `next_cursor` 로 다음 페이지를 이어 받습니다. 요청·응답 형식은 모두 [OpenAPI 계약](https://sw-cpas.co.kr/openapi.json)에 있습니다. ## MCP 서버 연결 제품 서버 도구: `get_firm_profile`, `list_services`, `search_insights`, `get_us_incorporation_questions`, `evaluate_us_incorporation`, `request_consultation`. 문서 서버 도구: `search_docs`, `get_document`, `ask_site`. 모든 도구는 입력·출력 스키마와 읽기 전용 여부 표시를 갖습니다. ```json { "mcpServers": { "sw-cpas": { "type": "http", "url": "https://sw-cpas.co.kr/mcp" }, "sw-cpas-docs": { "type": "http", "url": "https://sw-cpas.co.kr/mcp/docs" } } } ``` ## 상담 신청 에이전트는 사용자를 대신해 상담을 신청할 수 있습니다. 실제 이메일이 사무소에 전달되므로 다음을 지켜 주세요. 1. 이름·이메일·상담 내용을 사용자에게 확인합니다. 모르는 값을 지어내지 않습니다. 2. 사용자가 [개인정보 처리방침](https://sw-cpas.co.kr/privacy/)에 동의한 경우에만 `consent_privacy: true` 를 보냅니다. 3. 먼저 `dry_run: true` 로 검증한 뒤 한 번만 보냅니다. 재시도에는 같은 `Idempotency-Key` 를 씁니다. 접수되면 `202 Accepted` 와 함께 `request_id`·`Location` 헤더를 돌려줍니다. 그 주소(`GET /api/v1/consultation-requests/{request_id}`)로 접수 상태를 다시 확인할 수 있습니다. 접수 후 1영업일 이내 담당 CPA가 이메일 또는 전화로 연락드립니다. ```bash curl -X POST https://sw-cpas.co.kr/api/v1/consultation-requests \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 3f1c9a7e-0b2d-4c55-9a51-2f8e6d1b7c40" \ -d '{"name":"홍길동","email":"name@company.com","message":"미국 델라웨어 C-Corp 설립과 한국 해외직접투자 신고 상담을 원합니다.","consent_privacy":true,"dry_run":true}' ``` ## 오류 형식 모든 오류는 같은 JSON 모양으로 돌아옵니다. `code` 로 분기하고 `hint` 를 따라 고칩니다. ```json { "type": "https://sw-cpas.co.kr/developers/#error-invalid_answers", "title": "Some answers are missing or not allowed.", "status": 422, "detail": "GET /api/v1/us-incorporation/questions lists every question id and allowed value.", "error": { "code": "invalid_answers", "message": "Some answers are missing or not allowed.", "hint": "GET /api/v1/us-incorporation/questions lists every question id and allowed value.", "status": 422, "docs": "https://sw-cpas.co.kr/developers/", "details": [{ "field": "presence", "message": "미응답: presence" }] } } ``` 오류 코드(`error.code`)는 다음과 같습니다. `type` 은 이 목록의 해당 항목을 가리킵니다. - `not_found`: 없는 경로나 요청 ID - `method_not_allowed`: 허용되지 않는 HTTP 메서드(Allow 헤더 참고) - `invalid_json`: 본문이 JSON 객체가 아님 - `invalid_parameter`: 질의 매개변수 값이 범위를 벗어남 - `invalid_answers`: 진단 답변 누락·허용되지 않는 값 - `invalid_request`: 상담 신청 필드 누락·형식 오류·동의 없음 - `missing_query`: /ask 에 질문이 없음 - `rate_limited`: 요청 한도 초과(Retry-After 만큼 기다린 뒤 재시도) - `service_unavailable`: 상담 신청을 잠시 받을 수 없음 - `delivery_failed`: 저장·전달 실패(같은 Idempotency-Key 로 재시도) - `internal_error`: 서버 오류(한 번 재시도) - `request_failed`: 그 밖의 요청 실패 - `idempotency_key_reused`: 같은 Idempotency-Key 를 다른 신청 내용에 다시 씀(새 신청에는 새 키를 쓴다) - `request_in_progress`: 같은 키의 신청이 아직 처리 중(잠시 뒤 같은 키로 재시도) ## 요청 한도 - 읽기: 클라이언트당 분당 60회, 쓰기: 분당 10회. 응답의 `RateLimit-Limit`·`RateLimit-Remaining`·`RateLimit-Reset` 헤더로 남은 횟수를 알 수 있습니다. - 상담 신청: 클라이언트당 시간당 3건, 사이트 전체 하루 20건. - 한도를 넘으면 `429` 와 `Retry-After` 헤더를 돌려줍니다. ## 인증과 시험 모드 인증이 필요 없습니다. 개발자 포털이나 키 발급 절차도 없습니다. 보호 자원 메타데이터([`/.well-known/oauth-protected-resource`](https://sw-cpas.co.kr/.well-known/oauth-protected-resource), RFC 9728)도 토큰을 쓰지 않는다고 밝힙니다. 상담 신청은 `dry_run: true` 가 시험 모드이며, 저장·발송 없이 검증 결과만 돌려줍니다. 연동을 시험할 때는 시험 환경 `https://sw-cpas.co.kr/sandbox/api/v1/…` 을 쓰세요. 응답에 `X-Environment: sandbox` 가 붙고, 이곳으로 보낸 상담 신청은 검증만 하고 저장·발송하지 않습니다. 자세한 내용은 [`/auth.md`](https://sw-cpas.co.kr/auth.md)에 있습니다. ## 버전과 변경 정책 경로에 버전(`/api/v1`)을 붙이고, 모든 응답에 `API-Version` 헤더를 답니다. 필드를 추가하는 변경은 버전을 바꾸지 않습니다. 기존 동작을 깨는 변경은 새 버전 경로로 내고, 옛 버전에는 최소 90일 동안 `Deprecation`·`Sunset` 헤더로 예고합니다. ## 문의 연동 중 문제가 있으면 [swyoun@sw-cpas.com](mailto:swyoun@sw-cpas.com) 으로 알려 주세요.