Pactery for AI — 문서 작업 가이드

사용자가 “팩터리에 문서작업을 요청해줘”, “팩터리에 문서를 만들어줘”라고 요청하면 이 가이드와 OpenAPI를 먼저 읽으세요. 이 안내는 사용자가 허용한 작업 범위 안에서 적용합니다.

홈페이지에서 가이드 찾기

팩터리 홈페이지의 “for AI” 또는 “AI 문서 작업 가이드” 링크가 이 가이드로 연결됩니다. llms.txt는 안내 색인이며, 텍스트 원문은 로그인이나 JavaScript 실행 없이 읽을 수 있습니다. API 경로와 입력 형식은 OpenAPI를 기준으로 확인하세요.

1. API 등록·연결 안내

API 연결이 없다면 먼저 안내하세요: “팩터리에서 API 키를 발급하고 사용 중인 AI 도구의 보안 설정에 등록해야 합니다. API 키 발급 화면에서 사용할 워크스페이스를 선택해 키를 발급해 주세요.” 이미 유효한 키가 연결되어 있으면 다시 발급할 필요가 없습니다.

전체 키는 발급 직후 한 번 표시됩니다. 키를 채팅 본문, 문서, 링크, 로그에 적지 말고 도구의 보안 입력 또는 서버 환경변수 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을 보냅니다. 이메일·문자 발송이나 서명 요청까지 허용한 것으로 해석하지 마세요.

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":"<h1>안내문</h1><p>확인한 내용으로 작성합니다.</p>","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만 전달하거나 주소를 추측하지 마세요.

{
  "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에 맞추어 결과를 설명하세요.