pipefy-api-fallback

Pipefy API フォールバック（Tier 3 — 最終手段）

使用しているインターフェースに応じて、MCP リファレンスまたはCLI リファレンスを参照してください。関連するリファレンスのみを読み込んでください。

このスキルは、Tier 1 と Tier 2 が失敗した場合にのみ有効になります。ツールキットの接続をバイパスして、Pipefy GraphQL API を直接呼び出します。

書き込みが失敗したと報告された場合は、Tier を変更したり再試行したりする前に、対象を再読み込みしてください。変更がすでに適用されている可能性があります。書き込み失敗が不明確な場合に従ってください。

---

3-tier の解決方法（常に順番どおりに実行）

1. 専用の操作（create_card、get_phase_cards、get_phase_allowed_move_targets、update_pipe など）を試してください。カード／フェーズのシードとインベントリについては、pipefy-pipes-and-cards — パイプをフェーズ全体にわたってシードする、を参照してください。
2. 専用の操作が利用できない場合や、予期せず失敗した場合は、スキーマのイントロスペクションと execute_graphql を使用してください。pipefy-introspection を参照してください。
3. ツールキットの接続が利用できない場合、または GraphQL の実行がインフラストラクチャエラーで失敗した場合にのみ、直接 HTTP を使用してください。

**1 回失敗しただけで Tier 3 に進まないでください。**順番どおりに各 Tier を実行してください。新しいミューテーションのテストは Tier 2 で行います。

---

認証

2 つの方法があります（環境で利用できる方を使用してください）。両方利用できる場合は、サービスアカウントを優先してください。

設定されている変数を確認するには、値ではなく名前のみを一覧表示してください。

env | cut -d= -f1 | grep '^PIPEFY_'

方法を選ぶために、これらの変数に対して env、printenv、echo を実行しないでください。ユーザーが同意する前に、シークレットが会話に出力されます。

PIPEFY_* 変数を読み取る前に、どの変数を読み取るかと、その値が Authorization ヘッダーまたはトークンリクエストで app.pipefy.com に送信されることをユーザーに伝え、許可を待ってください。ユーザーが指定していないファイルから読み取らないでください。

オプション A — OAuth2 クライアントクレデンシャル（推奨）：

TOKEN=$(curl -s -X POST https://app.pipefy.com/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_ID\",\"client_secret\":\"$PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

オプション B — Personal Access Token（PAT）：

TOKEN="$PIPEFY_PAT"   # or $PIPEFY_TOKEN

新しいインテグレーションでは PAT は非推奨ですが、環境に残っている場合があります。

トークンのルール

• Bearer プレフィックスは必須です。これがないリクエストは Pipefy に拒否されます。
• PIPEFY_SERVICE_ACCOUNT_CLIENT_ID、PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET、PIPEFY_PAT、PIPEFY_TOKEN をユーザーへの応答やログに出力しないでください。
• サービスアカウントのトークンは有効な間は再利用し、有効期限切れ（401）の場合にのみ再取得してください。

---

エンドポイント

用途	URL
クエリ、ミューテーション、イントロスペクション	https://app.pipefy.com/graphql
OAuth2 トークン	https://app.pipefy.com/oauth/token

このエンドポイントは、公開スキーマのクエリ、ミューテーション、イントロスペクションに使用されます。また、https://api.pipefy.com/graphql も同じように応答します。これは、公開スキーマに対してツールキットが使用するエンドポイント（PIPEFY_BASE_URL に /graphql を加えたもの）です。ポータルツールなど一部のツールでは、さらに 2 つのエンドポイント /graphql/interfaces と /internal_api を使用します。詳細は docs/mcp/tools/portal.md を参照してください。

---

GraphQL クエリを実行する

curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id name } }"}' | jq .

GraphQL ミューテーションを実行する

curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateCard($input: CreateCardInput!) { createCard(input: $input) { card { id } } }",
    "variables": {
      "input": {
        "pipe_id": 67890,
        "title": "Fallback Card"
      }
    }
  }' | jq .

---

Raw API 経由のイントロスペクション

直接 HTTP でスキーマを確認する必要がある場合は、同じエンドポイントを呼び出してください。

# All queries and mutations
curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __schema { queryType { fields { name description } } mutationType { fields { name description } } } }"}'

# Type details
curl -s -X POST https://app.pipefy.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __type(name: \"CreateCardInput\") { inputFields { name description type { name kind ofType { name kind } } } } }"}'

---

エラーコード → 原因

構文エラー（GRAPHQL_PARSE_FAILED）を含む GraphQL エラーは、HTTP 200 を返します。HTTP ステータスコードではなく、errors 配列とその extensions.code を確認してください。認証エラーは HTTP 401 を返し、有効な JSON ではないリクエスト本文は、プレーンテキストのページとともに HTTP 500 を返します。

コード	考えられる原因	対処方法
HTTP 401、本文が {"errors": [{"title": "Unauthorized", ...}]}	Authorization ヘッダーがないか空、または Bearer プレフィックスを付けずにトークンを送信している	ヘッダーを Authorization: Bearer $TOKEN に修正し、トークンが空でないことを確認します。
HTTP 401、本文が {"error": "invalid_token", ...}	Bearer トークンは指定されているが、無効または期限切れ	トークンを再取得します（オプション A）。
PERMISSION_DENIED	Service Account がこの pipe/table のメンバーではありません。Pipefy は、存在しない pipe または card ID に対してもこのエラーを返します	ID を確認し、invite_members で SA を追加するか、ユーザーに依頼します。
resource_not_found	ID が存在しないか、SA から参照できません	ID を確認し、pipe/table のメンバーシップを確認します。
invalid_input	引数名または型が間違っています	introspect_type（Tier 2）を実行して、入力の形式を再確認します。
undefinedField	クエリで、その型に存在しないフィールドを選択しています	対象の型に対して introspect_type を実行し、選択内容を修正します。
INTERNAL_SERVER_ERROR	API のバグ、またはサポートされていないペイロード	同じペイロードを再試行しないでください。 別の mutation または回避策を試してください。
missingRequiredInputObjectAttribute	入力に必須フィールドがありません	ペイロードを __type(name: …InputType) と照合します。
曖昧な書き込み失敗（success: false、メッセージが空または不明瞭）	mutation がすでに適用されている可能性があります（サーバー上で副作用が発生しています）	再試行する前に必ず再読み込みしてください — 曖昧な書き込み失敗を参照してください。

---

曖昧な書き込み失敗（再試行前に再読み込み）

書き込み操作や execute_graphql は、mutation がすでに適用されていても失敗を報告することがあります。むやみに再試行すると、顧客データが重複します（例：success: false にもかかわらず、多数のカードが作成される）。

1. 同じ create/mutation をすぐに再実行しないでください。
2. まず再読み込みします。対象の pipe または phase で get_cards／get_phase_cards_count／返された ID／cards_count を確認してください。可能であれば、書き込み前に記録した件数または ID の集合と比較してください。
3. 再読み込みの結果、書き込みが適用されていないことが明確に確認できた場合に限り、再試行します。
4. 再読み込みの結果が不明確な場合（書き込み前の基準値がない、ページネーションで結果が途中までしか取得できない、または件数から存在しないことを証明できない場合）は、中止してください。曖昧な失敗と再読み込みで得られた証拠をユーザーに報告します。推測で再試行しないでください。
5. 厳守事項 — クライアント側の冪等性はありません： CreateCardInput には idempotency_key がありません（clientMutationId のみで、create の冪等性を保証するものではありません）。クライアント側のキーを独自に作成したり、再試行が安全だと思い込んだりしないでください。API に実際の冪等性機能が追加されるまでは、再読み込みのみが安全な方法です。

---

既知の回避策

pipe をまたいだカードの作成

• action: create_card と field_map を指定した createAutomation は、pipe をまたぐ作成先に対して INTERNAL_SERVER_ERROR を返すことがあります。そのペイロードを変更せずに再試行しないでください。
• 一度限りの接続カードであれば、コネクターフィールドの canCreateNewConnected: true が設定されている場合、throughConnectors を指定した createCard でカードを作成できます。
• createCard は自動化ルールを作成しません。ユーザーが今後のカードを自動作成したい場合は、この一度限りの呼び出しでは要件を満たさないことを伝えてください。

pipesCount より短いパイプ一覧

• pipesCount は組織全体の合計です。organization { pipes { ... } } と search_pipes が返すのは、呼び出し元の ID がメンバーになっているパイプのみです。一覧が短い、または空であることは想定された動作であり、エラーではありません。ロールによって範囲が広がることもありません。super_admin でも同じくメンバーシップに基づく結果が返されます。詳細と回避策については、docs/mcp/tools/organization.md を参照してください。
• organization { pipes(include_publics: true) } を使うと、組織内で公開されているパイプも一覧に含まれます。それでも通常、pipesCount より少ない数が返されます。
• この状況が最もよく発生するのはサービスアカウントです。SA は最初、どのパイプのメンバーにもなっていません。
• API 経由で作成されたパイプは、SA から自動的に参照できます。
• UI で作成されたパイプの場合、SA を管理者として追加する必要があります。
• 回避策：ユーザーから一度パイプ ID を取得し、pipe(id: "...") で直接クエリします。

invite_members は不明なメールアドレスを黙って受け入れる

• Pipefy は、形式が誤っているアドレスでも招待を拒否せず、新しい user_id を発行します。呼び出す前にメールアドレスの構文を確認してください。

---

外部リソース（生の API も失敗する場合）

• Pipefy 開発者ポータル：
  • https://developers.pipefy.com/reference/cards
  • https://developers.pipefy.com/reference/pipes
  • https://developers.pipefy.com/reference/automation-creation
  • https://developers.pipefy.com/reference/how-to-handle-errors
• API リファレンス：
  • https://api-docs.pipefy.com/reference/mutations/overview/
  • https://api-docs.pipefy.com/reference/queries/overview/
• コミュニティと変更履歴：
  • https://community.pipefy.com/api-76
  • https://developers.pipefy.com/changelog
• ステータスページ：https://status.pipefy.com

エラーメッセージの完全一致文字列と「Pipefy GraphQL」、またはミューテーション名と「example Pipefy API」で検索してください。

---

ユーザーへのエスカレーション（最終手段）

3 つのティアと外部リソースをすべて試しても解決しない場合に限ります。

1. 試したこと（専用オペレーション、イントロスペクション、生の API）を正確に伝えます。
2. エラーレスポンスをそのまま提示します。
3. 具体的な回避策を提案します（例：「Pipefy UI で作成し、取得した ID を使って API 経由で続行する」）。
4. そこで終了します。同じことを繰り返さないでください。

---

成功条件

• HTTP 4xx/5xx エラーなしでオペレーションが完了すること。
• レスポンスに data キーが含まれ、errors が null または存在しないこと。

失敗モード

• HTTP 401：ヘッダーがない、空、または Bearer を含まない場合（本文は Unauthorized）、あるいはトークンが無効または期限切れの場合（本文は invalid_token）。ヘッダーを修正するか、OAuth トークンを再取得します（オプション A）。
• HTTP 200 での GRAPHQL_PARSE_FAILED：GraphQL 構文エラーです。クエリ文字列を検証し、シェル経由で埋め込む際は引用符を適切にエスケープしてください。
• HTTP 500：まずリクエスト本文が有効な JSON か確認してください。本文が不正でも 500 が返されます。有効な場合は、Pipefy API の障害として扱います。status.pipefy.com を確認し、後で再試行してください。繰り返し再試行しないでください。
• errors 配列内の INTERNAL_SERVER_ERROR — 同じペイロードを再試行しないでください。別のミューテーション経路を選んでください。
• 書き込み結果が不明 — 作成などの書き込み後、エラーメッセージが空または不明瞭な状態でエラーが報告された場合：再試行前に件数と ID を読み直してください。作成を確認せずに再試行してはいけません（書き込み結果が不明 — 再試行前に読み直す）。

セキュリティに関する注意

• トークンを平文で記録または表示しないでください。
• 認証情報を直接埋め込むより、環境変数を使用してください。
• 個人利用または開発用途には PIPEFY_TOKEN / PIPEFY_PAT のみを使用し、サービスアカウントにはサービスアカウントの認証情報（PIPEFY_SERVICE_ACCOUNT_CLIENT_ID + PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET）を使用してください。

関連項目

• pipefy-introspection — ティア 2：直接 HTTP に切り替える前に、execute_graphql とイントロスペクションツールを使用します。