{"openapi":"3.1.0","info":{"title":"NITACO 契約書API","version":"v1","description":"建設業向けBPO「ツクノビ」の契約書を作るためのAPI。顧客（仕事を出す企業）とワーカー（仕事を請ける個人）の双方と契約を結び、個別契約書・基本業務委託契約書・秘密保持契約書（NDA）をPDFと編集用ファイルで作る。契約期間の延長・単価の変更・途中終了は、覚書と合意解約書（m1〜m4）で行う。案件・ワーカー・顧客の情報はNotionにあり、ここから読んで差し込む。押印と相手への送付はこのシステムの外で行う。契約書は相手に渡る書面なので、足りない情報・曖昧な情報を推測で埋めてはいけない。必ず利用者に確認してから渡す。"},"servers":[{"url":"https://keiyaku.tsukunobi.net"}],"security":[{"bearer":[]}],"x-手順":["0. 足りない情報・曖昧な情報は推測で埋めず、必ず利用者に確認してから渡す","1. GET /api/v1/cases?contract=missing で、まだ契約書を作っていない案件を引く","2. どの案件から着手するか、利用者に聞く。足りない項目と、合いそうな書式も一緒に返る","3. POST /api/v1/documents に dryRun: true を付けて下見する。caseId を渡せば、ワーカーと顧客はこちらで照合して埋める","4. 「足りない項目」が返ったら、そこに書いてある項目だけを利用者に聞いて渡す","5. dryRun を外して同じ内容で呼ぶと作れる","6. GET /api/v1/documents/（id）/bundle.zip で一式を受け取り、どこへ保存するかを利用者に確認する"],"x-書式":[{"id":"d3","相手":"ワーカー","名前":"個別契約書（継続・月初スタート）","開始日の条件":"月初（〜01）のみ","形式":"PDF / Excel"},{"id":"d2","相手":"ワーカー","名前":"個別契約書（継続・初月日割り）","開始日の条件":"月の途中のみ","形式":"PDF / Excel"},{"id":"d1","相手":"ワーカー","名前":"個別契約書（単発）","開始日の条件":"指定なし","形式":"PDF / Excel"},{"id":"d6","相手":"顧客","名前":"個別契約書（継続・月初スタート）","開始日の条件":"月初（〜01）のみ","形式":"PDF / Excel"},{"id":"d5","相手":"顧客","名前":"個別契約書（継続・初月日割り）","開始日の条件":"月の途中のみ","形式":"PDF / Excel"},{"id":"d4","相手":"顧客","名前":"個別契約書（単発）","開始日の条件":"指定なし","形式":"PDF / Excel"},{"id":"b1","相手":"顧客","名前":"基本業務委託契約書","開始日の条件":"指定なし","形式":"PDF / Word"},{"id":"b3","相手":"顧客","名前":"秘密保持契約書（NDA）","開始日の条件":"指定なし","形式":"PDF / Word"},{"id":"b2","相手":"ワーカー","名前":"基本業務委託契約書","開始日の条件":"指定なし","形式":"PDF / Word"},{"id":"m1","相手":"顧客","名前":"契約期間変更に関する覚書","開始日の条件":"指定なし","形式":"PDF / Word"},{"id":"m2","相手":"ワーカー","名前":"契約期間変更に関する覚書","開始日の条件":"指定なし","形式":"PDF / Word"},{"id":"m3","相手":"顧客","名前":"業務委託料変更に関する覚書","開始日の条件":"指定なし","形式":"PDF / Word"},{"id":"m4","相手":"ワーカー","名前":"合意解約書","開始日の条件":"指定なし","形式":"PDF / Word"}],"paths":{"/api/v1/":{"get":{"summary":"入口","description":"使える操作・手順・作成に必要な項目・書式が1回で返る。鍵を渡されたら最初にここを読む。鍵を付ければ GET / でも同じものが返る。","responses":{"200":{"description":"入口の案内"},"401":{"$ref":"#/components/responses/鍵が要る"}}}},"/api/v1/me":{"get":{"summary":"鍵の持ち主","description":"鍵に紐づく利用者のメールアドレス・役割・担当者IDを返す。","responses":{"200":{"description":"鍵の持ち主"},"401":{"$ref":"#/components/responses/鍵が要る"}}}},"/api/v1/templates":{"get":{"summary":"作れる書式","description":"書式ごとの開始日の条件・取れる形式・対になる書式と、選べる担当CS・納期・請求締日を返す。","responses":{"200":{"description":"書式と選択肢"},"401":{"$ref":"#/components/responses/鍵が要る"}}}},"/api/v1/staff":{"get":{"summary":"担当者の一覧","description":"鍵の持ち主が見られる担当者だけを返す。管理者は全員ぶん。","responses":{"200":{"description":"担当者の一覧"},"401":{"$ref":"#/components/responses/鍵が要る"}}}},"/api/v1/cases":{"get":{"summary":"担当案件","description":"Notionから読んだ担当案件。contract=missing を付けると、まだ契約書を作っていない案件だけを、足りない項目・状態・合いそうな書式つきで返す。","parameters":[{"name":"staff","in":"query","required":false,"schema":{"type":"string"},"description":"担当者ID。省略すると鍵の持ち主の担当。他人ぶんは管理者のみ"},{"name":"contract","in":"query","required":false,"schema":{"type":"string","enum":["missing"]},"description":"missing を渡すと、まだ契約書を作っていない案件だけ"}],"responses":{"200":{"description":"案件の一覧","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/案件"}}}}}}},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/workers":{"get":{"summary":"ワーカーの照合","description":"氏名でワーカー台帳を引く。住所・メールアドレス・電話番号は受託者の署名に要る。caseId を渡して作るときは、こちらで自動照合するので呼ばなくてよい。","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"氏名の一部（2〜80文字）"}],"responses":{"200":{"description":"ワーカーの一覧"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"}}}},"/api/v1/customers":{"get":{"summary":"担当の顧客一覧","description":"案件を会社ごとにまとめ、契約書の進み具合（契約書あり・未作成）まで返す。","parameters":[{"name":"staff","in":"query","required":false,"schema":{"type":"string"},"description":"担当者ID。省略すると鍵の持ち主の担当"},{"name":"contract","in":"query","required":false,"schema":{"type":"string","enum":["missing"]},"description":"missing を渡すと、未作成のある会社だけ"}],"responses":{"200":{"description":"顧客の一覧"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/customer":{"get":{"summary":"顧客の照合","description":"顧客の正式名称・住所・担当者。契約書にそのまま載る。idは案件の customerIds から取る。","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"顧客ID。案件の customerIds に入っている値"},{"name":"staff","in":"query","required":false,"schema":{"type":"string"},"description":"担当者ID。省略すると鍵の持ち主の担当"}],"responses":{"200":{"description":"顧客1件"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/documents":{"get":{"summary":"作成済みの一覧","description":"作った書類の一覧。idはPDFやZIPの取り出しと、basedOn での作り直しに使う。","parameters":[{"name":"staff","in":"query","required":false,"schema":{"type":"string"},"description":"担当者ID。省略すると鍵の持ち主の担当"}],"responses":{"200":{"description":"作成済みの一覧"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}},"post":{"summary":"契約書を作る","description":"caseId から案件・ワーカー・顧客を自動で埋めて作る。指定した値は動かさず、空いているところだけ埋める。dryRun: true なら作らずに下見だけ返す。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/作成依頼"}}}},"responses":{"200":{"description":"下見（dryRun: true）、または二重作成を止めて前の結果を返したとき","content":{"application/json":{"schema":{"$ref":"#/components/schemas/下見の応答"}}}},"201":{"description":"作成した","content":{"application/json":{"schema":{"$ref":"#/components/schemas/作成の応答"}}}},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/documents:batch":{"post":{"summary":"まとめて作る","description":"複数の案件を一度に作る（20案件まで）。cases に1件ぶんの依頼を並べ、共通の項目は外側に書く。中身は1件ぶんの作成をそのまま呼ぶ。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cases"],"properties":{"cases":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/作成依頼"},"description":"案件ごとの依頼。外側に書いた項目は全件に効く"}}}}}},"responses":{"200":{"description":"件数・作れた・作れなかった・結果"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/drafts":{"get":{"summary":"下書きの一覧","description":"作りかけの下書き。画面で保存したものも読める。","parameters":[{"name":"staff","in":"query","required":false,"schema":{"type":"string"},"description":"担当者ID。省略すると鍵の持ち主の担当"}],"responses":{"200":{"description":"下書きの一覧"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/documents/{id}":{"delete":{"summary":"作った書類を消す","description":"取り消せない。自分のものだけ、idを明示したものだけ消せる。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"GET /api/v1/documents で分かる書類のid"},{"name":"bundle","in":"query","required":false,"schema":{"type":"string","enum":["true"]},"description":"true なら同じ回に作ったものをまとめて消す"},{"name":"staff","in":"query","required":false,"schema":{"type":"string"},"description":"担当者ID。省略すると鍵の持ち主の担当"}],"responses":{"200":{"description":"消した件数とid"},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/documents/{id}/document.pdf":{"get":{"summary":"PDFを取り出す","description":"同じ形で document.xlsx（個別契約書）と document.docx（基本契約・NDA）も取れる。どちらが取れるかは作成の応答の excel / word で分かる。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"書類のid"}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/api/v1/documents/{id}/bundle.zip":{"get":{"summary":"一式を受け取る","description":"同じ回に作った書類をまとめたZIP。受け取ったあと、どこへ保存するかは必ず利用者に確認する。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"書類のid"}],"responses":{"200":{"description":"ZIP","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/項目不足"},"401":{"$ref":"#/components/responses/鍵が要る"},"403":{"$ref":"#/components/responses/他人の担当"},"404":{"$ref":"#/components/responses/見つからない"}}}},"/openapi.json":{"get":{"summary":"この仕様書","description":"鍵なしで読める。データは入っていない。","security":[],"responses":{"200":{"description":"この仕様書"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"管理者が「アカウント」画面で発行した鍵。ログイン画面は使わない。"}},"responses":{"鍵が要る":{"description":"鍵が無い、または無効か失効している","content":{"application/json":{"schema":{"$ref":"#/components/schemas/エラー"}}}},"他人の担当":{"description":"鍵の持ち主の担当ではない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/エラー"}}}},"見つからない":{"description":"案件・顧客・書類が見つからない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/エラー"}}}},"項目不足":{"description":"項目が足りない、または書式IDが正しくない","content":{"application/json":{"schema":{"$ref":"#/components/schemas/エラー"}}}}},"schemas":{"作成依頼":{"type":"object","required":["templateIds","caseId","clientName","taskName","workerName","workerRate","customerRate","hours","startDate","endDate","csManager"],"description":"caseId を渡せば、案件・ワーカー台帳・顧客一覧から埋まるものはこちらで埋める。必須の項目でも、そこで埋まるなら書かなくてよい。","properties":{"templateIds":{"type":"array","description":"作る書式。1回に6つまで","items":{"type":"string","enum":["d3","d2","d1","d6","d5","d4","b1","b3","b2","m1","m2","m3","m4"]}},"caseId":{"type":"string","description":"案件IDか manual。manual は案件に紐づけずに手入力で作るとき"},"clientName":{"type":"string","description":"顧客の会社名"},"taskName":{"type":"string","description":"業務名称。契約書に載る文言なので、候補があっても利用者に確かめる"},"workerName":{"type":"string","description":"ワーカー氏名"},"workerRate":{"type":"integer","description":"ワーカーへの支払時給（1〜1,000,000）"},"customerRate":{"type":"integer","description":"顧客への請求単価（1〜1,000,000）"},"hours":{"type":"integer","description":"契約時間（整数）"},"startDate":{"type":"string","description":"契約開始日（YYYY-MM-DD）。書式によっては月初のみ・月の途中のみ"},"endDate":{"type":"string","description":"契約終了日（YYYY-MM-DD）"},"csManager":{"type":"string","description":"業務責任者（受託者）の担当CS。GET /api/v1/templates の csManagers から選ぶ"},"dryRun":{"type":"boolean","description":"true なら作らずに下見だけ返す"},"autofill":{"type":"boolean","description":"false なら案件・ワーカー・顧客からの自動補完を止める"},"force":{"type":"boolean","description":"true なら、同じ内容を5分以内に作っていてもわざと作り直す"},"basedOn":{"type":"string","description":"作成済みのid。その内容を引き継ぎ、渡した項目だけ差し替えて作り直す"},"renewalMonths":{"type":"integer","description":"更新期間（1・3・6・12）。省略すると6ヶ月"},"delivery":{"type":"string","description":"納期。省略すると書式ごとの既定"},"billing":{"type":"string","description":"請求締日。省略すると書式ごとの既定"},"signedDate":{"type":"string","description":"締結日（YYYY-MM-DD）"},"workerAddress":{"type":"string","description":"ワーカーの住所。受託者の署名欄に入る"},"workerEmail":{"type":"string","description":"ワーカーのメールアドレス"},"workerPhone":{"type":"string","description":"ワーカーの電話番号"},"clientAddress":{"type":"string","description":"顧客の住所。委託者の署名欄に入る"},"clientTitleName":{"type":"string","description":"顧客の役職＋担当者名"},"clientContact":{"type":"string","description":"顧客の担当者名"},"originalSignedDate":{"type":"string","description":"覚書・合意解約書（m1〜m4）で要る。原契約（個別契約書）の締結日（YYYY-MM-DD）"},"originalStartDate":{"type":"string","description":"原契約の契約開始日（YYYY-MM-DD）。m1・m2・m4 で要る"},"originalEndDate":{"type":"string","description":"原契約の契約終了日（YYYY-MM-DD）。m1・m2・m4 で要る"},"newStartDate":{"type":"string","description":"変更後の契約開始日（YYYY-MM-DD）。省略すると originalStartDate をそのまま使う"},"newEndDate":{"type":"string","description":"変更後の契約終了日（YYYY-MM-DD）。m1・m2 で要る。短縮もできる"},"effectiveDate":{"type":"string","description":"変更後の業務委託料を適用する日（YYYY-MM-DD）。m3 で要る"},"previousHours":{"type":"integer","description":"変更前の契約時間（整数）。m3 で要る。変更後は hours"},"previousCustomerRate":{"type":"integer","description":"変更前の顧客単価（1〜1,000,000）。m3 で要る。変更後は customerRate"},"terminationDate":{"type":"string","description":"解約日（YYYY-MM-DD）。m4 で要る"}}},"下見の応答":{"type":"object","description":"dryRun: true のときの形。作らずに、埋まった値・足りない値・見込み金額を返す。","properties":{"下見":{"type":"boolean","description":"下見であることの目印"},"埋めた項目":{"type":"array","items":{"type":"string"},"description":"どの項目を、案件・ワーカー台帳・顧客一覧・前の書類のどれから埋めたか"},"使う値":{"type":"object","description":"このまま作った場合に使われる値"},"利用者に確認する値":{"type":"object","description":"Notionの値をそのまま載せるので、利用者に見せて直すか決めてもらう値（住所）","properties":{"clientAddress":{"type":"string","description":"顧客の住所"},"workerAddress":{"type":"string","description":"ワーカーの住所"},"理由":{"type":"string","description":"確認をお願いする理由"}}},"書式ごと":{"type":"array","description":"書式ごとの見通し","items":{"type":"object","properties":{"templateId":{"type":"string","description":"書式ID"},"作れる":{"type":"boolean","description":"この書式で作れるか"},"相手":{"type":"string","description":"顧客かワーカーか"},"見込み金額":{"type":"string","description":"単価×時間（税抜）"},"空いている欄":{"type":"array","items":{"type":"string"},"description":"作れるが、埋まっていない欄"},"足りない項目":{"type":"array","description":"作れないときに聞くべき項目","items":{"type":"object","properties":{"項目":{"type":"string","description":"渡すときのキー名"},"説明":{"type":"string","description":"何を聞けばよいか"},"候補":{"type":"string","description":"案件名から拾った候補。確かめてから使う"},"選べる値":{"type":"array","items":{"type":"string"},"description":"選択肢が決まっている項目の候補"}}}},"理由":{"type":"string","description":"作れない理由"}}}},"次の一手":{"type":"string","description":"次に何をすればよいか"}}},"作成の応答":{"type":"object","description":"作ったときの形。","properties":{"bundleId":{"type":"string","description":"同じ回に作った書類をまとめる束のid"},"staffId":{"type":"string","description":"担当者ID"},"documents":{"type":"array","description":"作れた書類","items":{"type":"object","properties":{"id":{"type":"string","description":"書類のid。取り出しと作り直しに使う"},"templateId":{"type":"string","description":"書式ID"},"pages":{"type":"integer","description":"ページ数"},"hasExcel":{"type":"boolean","description":"Excelが取れるか"},"hasWord":{"type":"boolean","description":"Wordが取れるか"},"ファイル名":{"type":"string","description":"保存するときのファイル名"},"pdf":{"type":"string","description":"PDFの取り出し先"},"excel":{"type":"string","description":"Excelの取り出し先。無ければ null"},"word":{"type":"string","description":"Wordの取り出し先。無ければ null"}}}},"failures":{"type":"array","description":"作れなかった書式と理由","items":{"type":"object","properties":{"templateId":{"type":"string","description":"書式ID"},"error":{"type":"string","description":"作れなかった理由"}}}},"埋めた項目":{"type":"array","items":{"type":"string"},"description":"どの項目をどこから埋めたか"},"一式":{"type":"string","description":"同じ回に作った書類をまとめたZIPの取り出し先"},"次の一手":{"type":"string","description":"次に何をすればよいか"},"作らなかった":{"type":"boolean","description":"同じ内容を5分以内に作っていて、前の結果を返したとき true"},"理由":{"type":"string","description":"作らなかったときの理由"}}},"案件":{"type":"object","description":"GET /api/v1/cases の各要素。行の出どころ（進捗・営業・顧客一覧）によって、値が入る項目は変わる。無いものは null。","properties":{"id":{"type":"string","description":"案件ID。作成の caseId に渡す"},"caseNumber":{"type":"string","description":"案件番号"},"title":{"type":"string","description":"Notionの案件名"},"clientName":{"type":"string","description":"顧客の会社名"},"taskName":{"type":"string","description":"業務名称"},"workerName":{"type":"string","description":"ワーカー氏名"},"workerIds":{"type":"array","items":{"type":"string"},"description":"ワーカーの参照ID"},"customerIds":{"type":"array","items":{"type":"string"},"description":"顧客の参照ID。GET /api/v1/customer?id=… に渡す"},"hours":{"type":"integer","description":"契約時間"},"workerRate":{"type":"integer","description":"ワーカー時給"},"customerRate":{"type":"integer","description":"契約時間単価"},"clientContact":{"type":"string","description":"顧客の担当者名"},"startDate":{"type":"string","description":"契約開始日"},"endDate":{"type":"string","description":"終了予定日"},"caseStatus":{"type":"string","description":"案件のステータス"},"customerStatus":{"type":"string","description":"顧客のステータス"},"csName":{"type":"string","description":"Notionの担当CS名。契約書に載る正式な値とは形が違う"},"source":{"type":"string","description":"行の出どころ（progress / sales / customer）"},"updatedAt":{"type":"string","description":"Notionでの最終更新"},"retrievedAt":{"type":"string","description":"読み取った時刻"},"staffId":{"type":"string","description":"担当者ID"},"assignees":{"type":"array","description":"担当者","items":{"type":"object","properties":{"id":{"type":"string","description":"担当者ID"},"name":{"type":"string","description":"氏名"}}}},"taskName候補":{"type":"string","description":"案件名の末尾から拾った業務名の候補。確かめてから使う"},"csManager候補":{"type":"string","description":"csName から突き合わせた、契約書に載る担当CS。合わなければ null"},"csManager備考":{"type":"string","description":"突き合わせられなかったときの案内"},"そのまま作れる":{"type":"boolean","description":"contract=missing のときだけ。足りない項目が無いか"},"状態":{"type":"string","description":"contract=missing のときだけ","enum":["すぐ作れる","確認すれば作れる","まだ作れない"]},"足りない項目":{"type":"array","items":{"type":"string"},"description":"contract=missing のときだけ。作る前に埋める項目"},"参考":{"type":"array","items":{"type":"string"},"description":"contract=missing のときだけ。作れない事情の補足"},"合いそうな書式":{"type":"array","items":{"type":"string"},"description":"contract=missing のときだけ。開始日から見た書式の候補"}}},"エラー":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"何が起きたか"},"手引き":{"type":"string","description":"どう直せばよいか"},"次の一手":{"type":"string","description":"次に何をすればよいか"}}}}}}