커넥터 — /v1/connectors

{
  "group": { "name": "과학 동아리", "role": "group_admin" },
  "connectors": [
    {
      "service": "notion",
      "name": "Notion",
      "state": "needs_link",
      "tools": {
        "read": { "state": "needs_link" },
        "write": { "state": "unavailable", "reason": "reapproval_needed" }
      },
      "link_url": "https://schoolorder.kr/ai/connect/notion",
      "valid_until": "2027-02-28"
    },
    {
      "service": "padlet",
      "name": "Padlet",
      "state": "unavailable",
      "reason": "off_for_group",
      "tools": {
        "read": { "state": "unavailable", "reason": "off_for_group" },
        "write": { "state": "unavailable", "reason": "off_for_group" }
      }
    },
    {
      "service": "kahoot",
      "name": "Kahoot!",
      "state": "requestable",
      "reason": "declined",
      "tools": {
        "read": { "state": "requestable", "reason": "declined" },
        "write": { "state": "requestable", "reason": "declined" }
      },
      "can_request_again": true,
      "message": "이번 학기엔 학교에서 쓰는 퀴즈 도구로 모아요."
    }
  ]
}

curl https://oneport.kr/v1/connectors/requests \
  -H "Authorization: Bearer $ONEPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: jotform-request-001' \
  -d '{"service_name":"Jotform","reason":"설문 응답을 모아 보려고요"}'

{
  "id": "00000000-0000-4000-8000-000000000010",
  "object": "connector_request",
  "service_name": "Jotform",
  "matched_service": null,
  "state": "received",
  "wallet_decision": null,
  "requested_by": { "role": "wallet_key" },
  "reason": "설문 응답을 모아 보려고요",
  "created_at": "2026-10-30T01:00:00+00:00",
  "updated_at": "2026-10-30T01:00:00+00:00"
}

{
  "error": {
    "type": "connector_unavailable",
    "code": "connector_unavailable",
    "message": "…",
    "reason": "declined",
    "connector_request_id": "00000000-0000-4000-8000-000000000010",
    "request_id": "00000000-0000-4000-8000-0000000000a1"
  }
}

import os
import re
import uuid

import requests

BASE = "https://oneport.kr"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEPORT_API_KEY']}"}
WANT = "Jotform"  # 사람이 쓰고 싶다고 한 서비스 이름
ONEPORT = "원포트(admin@schoolorder.kr)에 물어보세요."
# 지갑 관리자 몫 — 지갑에서 켜고 · 거절하고 · 막는 건 지갑 관리자예요.
WALLET = "지갑 관리자에게 물어보세요."
# 지갑에서 켜지 않아도 원포트 채팅 · 작업실에 열리는 공개 서비스 — 그 밖의 서비스는 지갑에서 켜야 열려요.
PUBLIC = {"notion", "kahoot", "padlet", "replit", "canva", "suno"}

# 막힌 까닭(reason)마다 누구에게 물을지 — message 문장으로 가르지 말고 이 이름으로 가르세요.
ASK = {
    "blocked_by_admin": "지갑 관리자가 막았어요. " + WALLET,
    "not_verified": ONEPORT,
    "off_for_group": "이 그룹엔 안 켜졌어요. group.role 쪽(그룹 관리자 · 지갑 관리자)에게 이 그룹에도 켜 달라고 하세요.",
    "student_blocked": "학생 키예요. 선생님께 말해 주세요.",
    "term_ended": "켜 둔 기한이 지났어요. " + WALLET,
    "reapproval_needed": "저희가 다시 확인하는 중이에요. 나중에 다시 보세요.",
    "declined": "거절됐어요. 저희 거절이면 부탁 줄의 message 를 보세요. 지갑 관리자 거절이면 이 줄의 message 를 보세요 — " + WALLET,
}


def same(name):
    """목록 줄과 견주기용 이름 — 소문자로 바꾸고 공백 · 문장부호를 빼요. 한글로 적은 이름은 목록에서 안 맞을 수 있어요."""
    return re.sub(r"[\W_]+", "", name.lower())


listing = requests.get(f"{BASE}/v1/connectors", headers=HEADERS, timeout=30)
listing.raise_for_status()  # 503 이면 잠시 뒤 다시 — 빈 목록으로 읽지 마세요
row = next((c for c in listing.json()["connectors"] if same(WANT) in (same(c["service"]), same(c["name"]))), None)

if row is not None:
    if row.get("reason"):
        print(ASK.get(row["reason"], ONEPORT), row.get("message", ""))
    elif row["state"] == "requestable" and row["service"] in PUBLIC:
        print("원포트 채팅 · 작업실에서 쓸 수 있어요. 부탁할 필요 없어요.")
    elif row["state"] == "requestable":
        print("지갑에서 켜야 원포트 채팅 · 작업실에서 열려요. " + WALLET)
    elif row["state"] == "needs_link":
        print("이 키로는 못 써요. 사람에게 이 주소를 건네 원포트 채팅 · 작업실에서 이어 쓰게 해요:", row["link_url"])
    else:  # pending
        print("원포트 채팅 · 작업실에선 공개 서비스면 지금도 써요. 결과를 기다리는 부탁은 GET /v1/connectors/requests 로 봐요 — 그 부탁이 approved 면 이 줄은 지갑 관리자가 다시 정할 때까지 pending 이에요. 바꾸려면 " + WALLET)
    # 쓰기 도구가 닫힌 건 tools.write 로만 보여요 — needs_link 줄 state 는 읽기 쪽이고, requestable · pending 줄 state 는 도구 칸과 따로 서요.
    write = (row.get("tools") or {}).get("write")
    if row["state"] in ("needs_link", "requestable", "pending") and write and write["state"] == "unavailable":
        print("쓰기 도구는 지금 꺼져 있어요.", ASK.get(write.get("reason"), ONEPORT))
    # link_url 은 tools.read · tools.write 가운데 하나라도 needs_link 면 와요 — 읽기 도구를 다시 확인하는 동안(줄 unavailable)에도 와요.
    if row["state"] != "needs_link" and row.get("link_url"):
        print("쓰기 도구는 이어서 쓸 수 있어요. 사람에게 이 주소를 건네요:", row["link_url"])
else:
    # 목록에 없는 서비스만 부탁해요. 이름 견주기는 저희가 해요 — 결과를 기다리는 같은 서비스 부탁이 있으면 그 줄로 이어져요.
    # 저희 확인이 끝난(approved) 부탁이 있으면 저희 확인 없이 그 줄로 이어지거나(같은 그룹) approved 새 줄이 서요.
    idem = str(uuid.uuid4())  # 응답을 못 받았으면(503 · 연결 끊김) 이 값 그대로 다시 보내요 — 다른 부탁엔 새 값
    r = requests.post(
        f"{BASE}/v1/connectors/requests",
        headers={**HEADERS, "Idempotency-Key": idem},
        json={"service_name": WANT, "reason": "설문 응답을 모아 보려고요"},
        timeout=30,
    )
    if r.status_code in (200, 201):
        req = r.json()
        if req["state"] == "approved" and req.get("matched_service"):
            # 한글 이름 등으로 위 목록 견주기는 못 맞췄지만 저희가 연 서비스예요 — 목록의 그 service 줄대로 해요.
            print("열린 서비스예요 — GET /v1/connectors 의", req["matched_service"], "줄을 보세요.")
        elif req["state"] == "approved":
            print("저희 확인은 끝났고 공개 전이에요.", ONEPORT)
        else:  # 결과는 GET /v1/connectors/requests/{id}
            print("부탁했어요:" if r.status_code == 201 else "이미 있던 부탁이에요:", req["id"], req["state"])
    else:
        err = r.json()["error"]
        if err["code"] == "student_cannot_request":
            print(ASK["student_blocked"])
        else:
            # 403 의 declined 는 늘 저희 거절이에요 — 지갑 관리자 거절은 403 이 아니라 다시 부탁돼요.
            # blocked_by_admin 의 message 는 정해진 안내 문장이라 까닭으로 보이지 마세요(까닭은 API 로 오지 않아요).
            print(err["code"], ONEPORT if err.get("reason") == "declined" else ASK.get(err.get("reason"), err["message"]))
            # declined · not_verified 403 엔 그 부탁 줄 id 가 와요(blocked_by_admin 엔 없어요) — 까닭은 그 줄의 message 예요.
            if err.get("connector_request_id"):
                s = requests.get(f"{BASE}/v1/connectors/requests/{err['connector_request_id']}", headers=HEADERS, timeout=30)
                if s.status_code == 200:
                    print("까닭:", s.json().get("message") or "적힌 까닭이 없어요")
                elif s.status_code == 503:  # 저희가 잠깐 못 읽었어요 — Retry-After 가 없으니 몇 초 쉬고 다시 봐요
                    print("까닭을 지금 못 읽었어요 — 잠시 뒤 다시 보세요")
                else:
                    print("까닭을 못 읽었어요:", s.json()["error"]["code"])


def request_state(request_id):
    """부탁 한 줄의 결과 — (state, message, can_request_again, wallet_decision). wallet_decision 칸이 없으면 「모름」이에요."""
    s = requests.get(f"{BASE}/v1/connectors/requests/{request_id}", headers=HEADERS, timeout=30)
    s.raise_for_status()
    body = s.json()
    return body["state"], body.get("message"), body.get("can_request_again"), body.get("wallet_decision")

import { randomUUID } from "node:crypto";

const BASE = "https://oneport.kr";
const headers = { Authorization: `Bearer ${process.env.ONEPORT_API_KEY}` };
const WANT = "Jotform"; // 사람이 쓰고 싶다고 한 서비스 이름
const ONEPORT = "원포트(admin@schoolorder.kr)에 물어보세요.";
// 지갑 관리자 몫 — 지갑에서 켜고 · 거절하고 · 막는 건 지갑 관리자예요.
const WALLET = "지갑 관리자에게 물어보세요.";
// 지갑에서 켜지 않아도 원포트 채팅 · 작업실에 열리는 공개 서비스 — 그 밖의 서비스는 지갑에서 켜야 열려요.
const PUBLIC = ["notion", "kahoot", "padlet", "replit", "canva", "suno"];

// 막힌 까닭(reason)마다 누구에게 물을지 — message 문장으로 가르지 말고 이 이름으로 가르세요.
const ASK: Record<string, string> = {
  blocked_by_admin: "지갑 관리자가 막았어요. " + WALLET,
  not_verified: ONEPORT,
  off_for_group: "이 그룹엔 안 켜졌어요. group.role 쪽(그룹 관리자 · 지갑 관리자)에게 이 그룹에도 켜 달라고 하세요.",
  student_blocked: "학생 키예요. 선생님께 말해 주세요.",
  term_ended: "켜 둔 기한이 지났어요. " + WALLET,
  reapproval_needed: "저희가 다시 확인하는 중이에요. 나중에 다시 보세요.",
  declined: "거절됐어요. 저희 거절이면 부탁 줄의 message 를 보세요. 지갑 관리자 거절이면 이 줄의 message 를 보세요 — " + WALLET,
};
// 목록 줄과 견주기용 이름 — 소문자로 바꾸고 공백 · 문장부호를 빼요. 한글로 적은 이름은 목록에서 안 맞을 수 있어요.
const same = (name: string) => name.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");

const listing = await fetch(`${BASE}/v1/connectors`, { headers });
if (!listing.ok) throw new Error(`GET /v1/connectors ${listing.status} — 503 이면 잠시 뒤 다시`);
type Gate = { state: string; reason?: string };
type Row = { service: string; name: string; state: string; reason?: string; message?: string; link_url?: string; tools?: { read: Gate | null; write: Gate | null } };
const { connectors } = (await listing.json()) as { connectors: Row[] };
const row = connectors.find((c) => [same(c.service), same(c.name)].includes(same(WANT)));

if (row) {
  if (row.reason) console.log(ASK[row.reason] ?? ONEPORT, row.message ?? "");
  else if (row.state === "requestable" && PUBLIC.includes(row.service)) console.log("원포트 채팅 · 작업실에서 쓸 수 있어요. 부탁할 필요 없어요.");
  else if (row.state === "requestable") console.log("지갑에서 켜야 원포트 채팅 · 작업실에서 열려요. " + WALLET);
  else if (row.state === "needs_link") console.log("이 키로는 못 써요. 사람에게 이 주소를 건네 원포트 채팅 · 작업실에서 이어 쓰게 해요:", row.link_url);
  else console.log("원포트 채팅 · 작업실에선 공개 서비스면 지금도 써요. 결과를 기다리는 부탁은 GET /v1/connectors/requests 로 봐요 — 그 부탁이 approved 면 이 줄은 지갑 관리자가 다시 정할 때까지 pending 이에요. 바꾸려면 " + WALLET); // pending
  // 쓰기 도구가 닫힌 건 tools.write 로만 보여요 — needs_link 줄 state 는 읽기 쪽이고, requestable · pending 줄 state 는 도구 칸과 따로 서요.
  const write = row.tools?.write;
  if (["needs_link", "requestable", "pending"].includes(row.state) && write?.state === "unavailable") console.log("쓰기 도구는 지금 꺼져 있어요.", ASK[write.reason ?? ""] ?? ONEPORT);
  // link_url 은 tools.read · tools.write 가운데 하나라도 needs_link 면 와요 — 읽기 도구를 다시 확인하는 동안(줄 unavailable)에도 와요.
  if (row.state !== "needs_link" && row.link_url) console.log("쓰기 도구는 이어서 쓸 수 있어요. 사람에게 이 주소를 건네요:", row.link_url);
} else {
  // 목록에 없는 서비스만 부탁해요. 이름 견주기는 저희가 해요 — 결과를 기다리는 같은 서비스 부탁이 있으면 그 줄로 이어져요.
  // 저희 확인이 끝난(approved) 부탁이 있으면 저희 확인 없이 그 줄로 이어지거나(같은 그룹) approved 새 줄이 서요.
  const idem = randomUUID(); // 응답을 못 받았으면(503 · 연결 끊김) 이 값 그대로 다시 보내요 — 다른 부탁엔 새 값
  const res = await fetch(`${BASE}/v1/connectors/requests`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": idem },
    body: JSON.stringify({ service_name: WANT, reason: "설문 응답을 모아 보려고요" }),
  });
  const body = await res.json();
  // approved 인데 matched_service 가 오면 한글 이름 등으로 위 목록 견주기는 못 맞췄지만 저희가 연 서비스예요 — 목록의 그 service 줄대로 해요.
  if (res.ok && body.state === "approved" && body.matched_service) console.log("열린 서비스예요 — GET /v1/connectors 의", body.matched_service, "줄을 보세요.");
  else if (res.ok && body.state === "approved") console.log("저희 확인은 끝났고 공개 전이에요.", ONEPORT);
  else if (res.ok) console.log(res.status === 201 ? "부탁했어요:" : "이미 있던 부탁이에요:", body.id, body.state); // 결과는 GET /v1/connectors/requests/{id}
  else if (body.error.code === "student_cannot_request") console.log(ASK.student_blocked);
  else {
    // 403 의 declined 는 늘 저희 거절이에요 — 지갑 관리자 거절은 403 이 아니라 다시 부탁돼요.
    // blocked_by_admin 의 message 는 정해진 안내 문장이라 까닭으로 보이지 마세요(까닭은 API 로 오지 않아요).
    console.log(body.error.code, body.error.reason === "declined" ? ONEPORT : ASK[body.error.reason] ?? body.error.message);
    // declined · not_verified 403 엔 그 부탁 줄 id 가 와요(blocked_by_admin 엔 없어요) — 까닭은 그 줄의 message 예요.
    if (body.error.connector_request_id) {
      const s = await fetch(`${BASE}/v1/connectors/requests/${body.error.connector_request_id}`, { headers });
      const line = await s.json();
      if (s.ok) console.log("까닭:", line.message ?? "적힌 까닭이 없어요");
      else if (s.status === 503) console.log("까닭을 지금 못 읽었어요 — 잠시 뒤 다시 보세요"); // 저희가 잠깐 못 읽었어요 — Retry-After 가 없으니 몇 초 쉬고 다시 봐요
      else console.log("까닭을 못 읽었어요:", line.error.code);
    }
  }
}