# Pactery for AI — 문서 작업 가이드
사용자가 “팩터리에 문서작업을 요청해줘”, “팩터리에 문서를 만들어줘”라고 요청하면 이 가이드와 [OpenAPI](https://pactery.com/api/openapi)를 먼저 읽으세요. 이 안내는 사용자가 허용한 작업 범위 안에서 적용합니다.
## 홈페이지에서 가이드 찾기
[팩터리 홈페이지](https://pactery.com)의 “for AI” 또는 “AI 문서 작업 가이드” 링크가 이 가이드로 연결됩니다. [llms.txt](https://pactery.com/llms.txt)는 안내 색인이며, [텍스트 원문](https://pactery.com/developers/ai/guide.txt)은 로그인이나 JavaScript 실행 없이 읽을 수 있습니다. API 경로와 입력 형식은 OpenAPI를 기준으로 확인하세요.
## 1. API 등록·연결 안내
API 연결이 없다면 먼저 안내하세요: “팩터리에서 API 키를 발급하고 사용 중인 AI 도구의 보안 설정에 등록해야 합니다. [API 키 발급 화면](https://pactery.com/app/settings/developer)에서 사용할 워크스페이스를 선택해 키를 발급해 주세요.” 이미 유효한 키가 연결되어 있으면 다시 발급할 필요가 없습니다.
전체 키는 발급 직후 한 번 표시됩니다. 키를 채팅 본문, 문서, 링크, 로그에 적지 말고 도구의 보안 입력 또는 서버 환경변수 PACTERY_API_KEY에 등록하세요. 키는 선택한 워크스페이스의 권한으로 작동합니다. API 실행 도구가 없는 AI는 연결 방법을 안내하고 본문 초안을 준비하되 저장했다고 말하지 않습니다. 새 API 키 발급은 사용자가 직접 하거나 도구가 요구하는 승인을 받은 뒤 진행하세요.
관리 화면 주소를 전달받았을 때 브라우저를 조작하는 AI는 사용자가 로그인한 화면을 읽을 수 있습니다. 일반적인 URL 읽기 도구가 브라우저 로그인 상태를 공유한다고 가정하지 마세요. 브라우저 로그인과 API 키 인증은 별개이므로, API로 수정하려면 해당 워크스페이스의 키가 연결되어 있어야 합니다.
- API 주소: `https://api.pactery.com/v1` (기존 `https://pactery.com/v1` 호환)
- 인증: `Authorization: Bearer {PACTERY_API_KEY}`
- `GET /organization`으로 연결된 워크스페이스를 확인합니다. 401이면 키 연결을 안내하고 중단합니다. 플랜·권한 오류가 있으면 응답의 안내를 따릅니다.
- 리소스 조회가 404이면 `error.explain`, `current_workspace`, `workspaces`, `next_action`을 확인하세요. `GET /workspaces`도 키 발급자가 가입한 공간의 이름·ID를 반환합니다. 목록은 찾는 문서나 템플릿이 그곳에 있다는 뜻이 아닙니다. 사용자에게 대상 공간을 확인하고 그 공간에서 발급한 키로 다시 연결하세요. 현재 키에 다른 공간의 ID나 헤더를 덧붙여 접근할 수는 없습니다. 같은 키로 재시도하거나 원본 대신 다른 문서를 생성해 해결하지 않습니다.
## 2. 요청에 맞게 문서 작성
“문서를 만들어줘”는 초안 저장입니다. `POST /documents`에 title, content, content_format을 보냅니다. 이메일·문자 발송이나 서명 요청까지 허용한 것으로 해석하지 마세요.
```bash
curl https://api.pactery.com/v1/documents \
-H "Authorization: Bearer $PACTERY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-document-task-001" \
--data '{"title":"안내문","content":"안내문
확인한 내용으로 작성합니다.
","content_format":"html"}'
```
실제 작업마다 고유한 Idempotency-Key를 사용합니다. 연결이 끊겨 결과가 불명확하면 같은 본문과 같은 키로 재시도해 중복 생성을 방지하세요. 재시도 전에 본문을 바꾸지 않습니다.
- 수정: `PATCH /documents/{id}`. 먼저 기존 문서와 편집 가능한 상태를 확인합니다.
- 관리 화면 주소의 `/app/docs/{shortId}/manage`에 있는 shortId와 API 문서 id는 다릅니다. 문서 목록·조회 응답의 `document_url`을 전달받은 관리 주소와 대조하여 문서를 확인하고, 응답의 id로 수정합니다. 이미 발송했거나 완료·편집 잠금 상태이면 오류 안내를 따르고, 자동으로 잠금을 풀거나 다른 문서를 만들어 대체하지 않습니다.
- 템플릿: `GET /templates/{id}`의 variables를 채우고 `POST /templates/{id}/render`로 확인한 뒤 문서를 생성합니다.
- 서명 요청까지 명시적으로 허용했을 때만 `POST /signature_requests` 또는 `/documents/{id}/send`를 사용합니다. 원자 서명 요청에는 Idempotency-Key가 필수입니다.
- `sk_test_` 키는 signature_requests의 실제 메일을 보내지 않지만 문서는 저장됩니다. 다른 발송 API까지 모두 모의 실행한다고 가정하지 않습니다.
## 3. 응답의 문서 바로가기를 반드시 전달
문서 작업을 마친 AI는 성공 응답의 `document_url`을 사용하여 사용자에게 클릭 가능한 문서 링크를 남겨야 합니다. 문서 ID만 전달하거나 주소를 추측하지 마세요.
```json
{
"id": "doc_example",
"object": "document",
"status": "draft",
"document_url": "https://pactery.com/app/docs/example/manage"
}
```
최종 답변 예시: “안내문을 초안으로 저장했습니다. [팩터리에서 문서 보기](응답의 document_url)”
- `document_url`: 로그인한 작성자·해당 워크스페이스 권한자가 보는 문서 관리 주소입니다. 이 링크를 전달한다고 공개 열람 권한이 생기지는 않습니다.
- `sign_url`: 허용된 서명 요청 작업에서 반환하는 수신자용 서명 링크입니다. 작성자용 바로가기와 구분해서 표시합니다.
- 문서 목록은 각 `data[]` 항목에 document_url이 있습니다. 서명 요청 응답에는 최상위와 document 안에 모두 있습니다. 참여자·필드·감사추적·리마인더의 문서별 JSON 응답에도 포함됩니다.
- 문서 삭제 응답 또는 주소가 없는 과거 자료는 document_url이 null일 수 있습니다. 삭제 완료를 알리고 열 수 없는 링크는 제공하지 않습니다. 오류 응답에도 링크를 임의로 붙이지 않습니다.
- PDF 다운로드는 JSON이 아닌 파일 응답이므로 `Link` 헤더의 `rel="related"` 주소를 사용하거나 문서 조회 응답의 document_url을 사용합니다.
- 이전 버전 응답에 링크가 없으면 `GET /documents/{id}`로 다시 조회합니다. 그래도 없으면 링크 미제공 상태를 알리고 ID를 보조 정보로 남깁니다. URL을 만들어내지 않습니다.
저장 성공과 실제 발송·서명 완료는 다릅니다. 응답의 status 및 delivery.status에 맞추어 결과를 설명하세요.