Accord API 文档

版本: 2.0
基础 URL: https://accord.seeyon.chat/api 最后更新: 2026年1月

目录

1. 概述
2. 身份认证
3. 通用模式
4. 合同 API
5. 交易方 API
6. 风险 API
7. 任务 API
8. 付款 API
9. 对话 API
10. 政策 API
11. 活动 API
12. 红线对比 API
13. Webhooks
14. 错误代码

概述

Accord 是一个 AI 驱动的合同管理平台，将您的法律文档库转变为可查询的"透明盒子"。此 API 使开发者能够将 Accord 的功能集成到他们的工作流程中。

核心概念

• 语料库 (Corpus): 包含所有合同、元数据和语义嵌入的聚合知识库
• 实体引用 (EntityRef): 允许任何实体链接到任何其他实体的多态引用系统
• SSE (服务器发送事件): 用于实时流式传输 AI 响应

API 约定

• 所有请求和响应使用 JSON 格式（文件上传除外）
• 日期使用 ISO 8601 格式: YYYY-MM-DDTHH:mm:ssZ
• ID 为 UUID v4 字符串
• 分页使用 page 和 limit 查询参数
• 排序使用 sort（字段名）和 order（asc 或 desc）

身份认证

Accord 使用 JWT（JSON Web Token）进行身份认证。

获取令牌

POST /auth/login
Content-Type: application/json

{
  "email": "user@company.com",
  "password": "your-password"
}

响应:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

使用令牌

在 Authorization 头中包含令牌：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

刷新令牌

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

令牌权限范围

通用模式

分页

GET /contracts?page=1&limit=20

响应头:

X-Total-Count: 150
X-Total-Pages: 8
X-Current-Page: 1

过滤

GET /contracts?status=active&party_id=uuid&min_value=10000

排序

GET /contracts?sort=created_at&order=desc

字段选择

GET /contracts?fields=id,title,status,value

实体引用系统

用于链接实体的多态引用系统：

interface EntityRef {
  entity: 'Contract' | 'Clause' | 'Risk' | 'Payment' | 'Policy' | 'Task' | 'Party';
  id: string;
  semanticRelevance?: number; // AI 计算的相关性 (0.0 - 1.0)
}

合同 API

Accord 的核心枢纽。合同是连接交易方、风险、付款和任务的锚点实体。

获取合同列表

GET /contracts

查询参数:

响应:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "主服务协议 - Acme 公司",
      "type": "msa",
      "status": "active",
      "value": 500000,
      "currency": "USD",
      "start_date": "2025-01-01",
      "end_date": "2026-12-31",
      "risk_score": 35,
      "parties": [
        {
          "id": "party-uuid-1",
          "name": "Acme 公司",
          "role": "client"
        }
      ],
      "created_at": "2024-12-15T10:30:00Z",
      "updated_at": "2025-01-02T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

获取单个合同

GET /contracts/:id

响应:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "主服务协议 - Acme 公司",
  "type": "msa",
  "status": "active",
  "value": 500000,
  "currency": "USD",
  "start_date": "2025-01-01",
  "end_date": "2026-12-31",
  "auto_renewal": true,
  "renewal_notice_days": 30,
  "risk_score": 35,
  "embedding_vector": null,
  "ai_summary": "此 MSA 与 Acme 公司建立了为期2年的软件开发服务关系...",
  "parties": [
    {
      "id": "party-uuid-1",
      "name": "Acme 公司",
      "role": "client",
      "signing_date": "2024-12-20"
    }
  ],
  "clauses": [
    {
      "id": "clause-uuid-1",
      "type": "termination",
      "title": "便利终止条款",
      "content": "任何一方均可终止本协议...",
      "risk_level": "medium"
    }
  ],
  "obligations": [
    {
      "id": "obligation-uuid-1",
      "description": "提交月度进度报告",
      "responsible_party": "provider",
      "due_date": "2025-02-01",
      "status": "pending"
    }
  ],
  "payment_schedules": [
    {
      "id": "schedule-uuid-1",
      "description": "月度服务费",
      "amount": 25000,
      "frequency": "monthly",
      "next_due": "2025-02-01"
    }
  ],
  "documents": [
    {
      "id": "doc-uuid-1",
      "filename": "MSA_AcmeCorp_v2.pdf",
      "mime_type": "application/pdf",
      "size": 245678,
      "uploaded_at": "2024-12-15T10:30:00Z"
    }
  ],
  "metadata": {
    "jurisdiction": "纽约，美国",
    "governing_law": "纽约州法律",
    "dispute_resolution": "仲裁",
    "confidentiality_level": "standard"
  },
  "created_at": "2024-12-15T10:30:00Z",
  "updated_at": "2025-01-02T14:22:00Z"
}

创建合同

POST /contracts
Content-Type: multipart/form-data

请求体:

响应: 201 Created

{
  "id": "new-contract-uuid",
  "title": "新服务协议",
  "status": "draft",
  "created_at": "2025-01-04T09:00:00Z"
}

更新合同

PATCH /contracts/:id
Content-Type: application/json

{
  "status": "active",
  "value": 600000,
  "end_date": "2027-12-31"
}

响应: 200 OK 返回更新后的合同对象

删除合同

DELETE /contracts/:id

响应: 204 No Content

上传合同文档

POST /contracts/:id/documents
Content-Type: multipart/form-data

document: [二进制文件]

响应:

{
  "id": "doc-uuid",
  "filename": "Amendment_v3.pdf",
  "mime_type": "application/pdf",
  "size": 123456,
  "uploaded_at": "2025-01-04T09:15:00Z"
}

AI 分析

触发合同的 AI 分析：

POST /contracts/:id/analyze
Content-Type: application/json

{
  "analysis_types": ["risk_assessment", "obligation_extraction", "summary"]
}

响应 (SSE 流):

event: status
data: {"step": "analyzing", "progress": 25, "message": "正在提取条款..."}

event: result
data: {"type": "risk_assessment", "risk_score": 42, "findings": [...]}

event: complete
data: {"message": "分析完成"}

交易方 API

管理交易对手及其关系档案。

获取交易方列表

GET /parties

查询参数:

响应:

{
  "data": [
    {
      "id": "party-uuid-1",
      "name": "Acme 公司",
      "type": "client",
      "status": "active",
      "credit_score": 750,
      "payment_behavior": {
        "average_days_late": 5,
        "on_time_percentage": 85
      },
      "active_contracts_count": 3,
      "total_contract_value": 1500000,
      "created_at": "2024-06-15T08:00:00Z"
    }
  ],
  "pagination": {...}
}

获取单个交易方

GET /parties/:id

响应:

{
  "id": "party-uuid-1",
  "name": "Acme 公司",
  "type": "client",
  "status": "active",
  "legal_name": "Acme Corporation Inc.",
  "registration_number": "12-3456789",
  "tax_id": "XX-XXXXXXX",
  "industry": "科技",
  "website": "https://acme.com",
  "credit_score": 750,
  "payment_behavior": {
    "average_days_late": 5,
    "on_time_percentage": 85,
    "total_payments": 45,
    "late_payments": 7
  },
  "contacts": [
    {
      "id": "contact-uuid-1",
      "name": "张三",
      "title": "法务顾问",
      "email": "zhangsan@acme.com",
      "phone": "+86-138-0000-0000",
      "is_primary": true
    }
  ],
  "addresses": [
    {
      "type": "headquarters",
      "street": "中关村大街1号",
      "city": "北京",
      "state": "北京市",
      "postal_code": "100080",
      "country": "中国"
    }
  ],
  "contracts": [
    {
      "id": "contract-uuid-1",
      "title": "MSA - Acme 公司",
      "status": "active",
      "value": 500000
    }
  ],
  "risk_profile": {
    "overall_risk": "low",
    "financial_risk": "low",
    "compliance_risk": "medium",
    "notes": "付款记录良好，存在轻微合规问题"
  },
  "created_at": "2024-06-15T08:00:00Z",
  "updated_at": "2025-01-02T14:00:00Z"
}

创建交易方

POST /parties
Content-Type: application/json

{
  "name": "新供应商有限公司",
  "type": "vendor",
  "legal_name": "新供应商有限责任公司",
  "industry": "制造业",
  "contacts": [
    {
      "name": "李四",
      "email": "lisi@newvendor.com",
      "is_primary": true
    }
  ]
}

更新交易方

PATCH /parties/:id
Content-Type: application/json

{
  "credit_score": 780,
  "status": "active"
}

删除交易方

DELETE /parties/:id

注意: 有活跃合同的交易方无法删除。

风险 API

具有 AI 驱动评估的动态风险管理。

获取风险列表

GET /risks

查询参数:

响应:

{
  "data": [
    {
      "id": "risk-uuid-1",
      "title": "供应商破产风险",
      "description": "关键供应商显示财务困难信号",
      "category": "financial",
      "severity": "high",
      "probability": 35,
      "impact": 80,
      "risk_score": 28,
      "status": "open",
      "contract": {
        "id": "contract-uuid-1",
        "title": "供应协议 - XYZ 公司"
      },
      "mitigation_plan": "寻找替代供应商，协商托管安排",
      "owner": {
        "id": "user-uuid-1",
        "name": "风险经理"
      },
      "due_date": "2025-02-15",
      "created_at": "2025-01-02T10:00:00Z"
    }
  ],
  "pagination": {...}
}

获取单个风险

GET /risks/:id

创建风险

POST /risks
Content-Type: application/json

{
  "title": "监管合规缺口",
  "description": "合同缺少 GDPR 合规条款",
  "category": "compliance",
  "severity": "medium",
  "probability": 60,
  "impact": 50,
  "contract_id": "contract-uuid-1",
  "mitigation_plan": "协商修订以包含数据保护条款",
  "owner_id": "user-uuid-1",
  "due_date": "2025-03-01"
}

更新风险

PATCH /risks/:id
Content-Type: application/json

{
  "status": "mitigated",
  "resolution_notes": "修订协议于 2025-02-20 签署"
}

风险矩阵

获取用于可视化的聚合风险数据：

GET /risks/matrix

响应:

{
  "matrix": [
    {"probability_range": "0-20", "impact_range": "0-20", "count": 5, "risks": [...]},
    {"probability_range": "0-20", "impact_range": "21-40", "count": 3, "risks": [...]},
    ...
  ],
  "summary": {
    "total": 45,
    "critical": 2,
    "high": 8,
    "medium": 20,
    "low": 15
  },
  "trends": {
    "new_this_month": 5,
    "closed_this_month": 8,
    "average_resolution_days": 12
  }
}

任务 API

从风险、义务或手动创建生成的行动项。

获取任务列表

GET /tasks

查询参数:

响应:

{
  "data": [
    {
      "id": "task-uuid-1",
      "title": "审查终止条款",
      "description": "根据供应商破产风险分析终止条款",
      "status": "in_progress",
      "priority": "high",
      "assignee": {
        "id": "user-uuid-1",
        "name": "法务分析师",
        "avatar": "https://..."
      },
      "due_date": "2025-01-15",
      "source": {
        "type": "risk",
        "id": "risk-uuid-1",
        "title": "供应商破产风险"
      },
      "contract": {
        "id": "contract-uuid-1",
        "title": "供应协议 - XYZ 公司"
      },
      "comments_count": 3,
      "attachments_count": 1,
      "created_at": "2025-01-02T10:30:00Z",
      "updated_at": "2025-01-04T08:00:00Z"
    }
  ],
  "pagination": {...}
}

获取单个任务

GET /tasks/:id

创建任务

POST /tasks
Content-Type: application/json

{
  "title": "协商付款条款",
  "description": "请求60天付款期限而非30天",
  "priority": "medium",
  "assignee_id": "user-uuid-1",
  "due_date": "2025-02-01",
  "contract_id": "contract-uuid-1",
  "labels": ["negotiation", "payment"]
}

更新任务

PATCH /tasks/:id
Content-Type: application/json

{
  "status": "done",
  "completion_notes": "成功协商到45天付款期限"
}

添加评论

POST /tasks/:id/comments
Content-Type: application/json

{
  "content": "已与供应商沟通，他们愿意讨论"
}

看板数据

GET /tasks/board

响应:

{
  "columns": [
    {
      "id": "todo",
      "title": "待办",
      "tasks": [...],
      "count": 12
    },
    {
      "id": "in_progress",
      "title": "进行中",
      "tasks": [...],
      "count": 5
    },
    {
      "id": "review",
      "title": "审核中",
      "tasks": [...],
      "count": 3
    },
    {
      "id": "done",
      "title": "已完成",
      "tasks": [...],
      "count": 45
    }
  ]
}

付款 API

财务跟踪和收入泄漏检测。

获取付款列表

GET /payments

查询参数:

响应:

{
  "data": [
    {
      "id": "payment-uuid-1",
      "description": "2025年第一季度许可费",
      "amount": 25000,
      "currency": "USD",
      "direction": "inbound",
      "status": "pending",
      "due_date": "2025-01-31",
      "paid_date": null,
      "contract": {
        "id": "contract-uuid-1",
        "title": "软件许可协议"
      },
      "party": {
        "id": "party-uuid-1",
        "name": "Acme 公司"
      },
      "invoice_number": "INV-2025-0042",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {...}
}

获取单个付款

GET /payments/:id

创建付款

POST /payments
Content-Type: application/json

{
  "description": "月度支持费",
  "amount": 5000,
  "currency": "USD",
  "direction": "inbound",
  "due_date": "2025-02-01",
  "contract_id": "contract-uuid-1",
  "party_id": "party-uuid-1",
  "schedule_id": "schedule-uuid-1"
}

更新付款

PATCH /payments/:id
Content-Type: application/json

{
  "status": "paid",
  "paid_date": "2025-01-28",
  "payment_method": "wire_transfer",
  "reference_number": "WT-2025-12345"
}

付款仪表板

GET /payments/dashboard

响应:

{
  "summary": {
    "total_receivable": 450000,
    "total_payable": 125000,
    "overdue_receivable": 35000,
    "overdue_payable": 0,
    "due_this_month": 85000
  },
  "by_status": {
    "scheduled": {"count": 45, "amount": 320000},
    "pending": {"count": 12, "amount": 85000},
    "overdue": {"count": 3, "amount": 35000},
    "paid": {"count": 156, "amount": 1250000}
  },
  "cash_flow_forecast": [
    {"month": "2025-01", "inbound": 120000, "outbound": 45000},
    {"month": "2025-02", "inbound": 95000, "outbound": 50000},
    ...
  ],
  "revenue_leakage_alerts": [
    {
      "type": "missed_milestone",
      "contract_id": "contract-uuid-1",
      "description": "付款到期但交付物未标记完成",
      "amount": 15000
    }
  ]
}

付款日历

GET /payments/calendar?year=2025&month=1

响应:

{
  "year": 2025,
  "month": 1,
  "payments": [
    {
      "date": "2025-01-15",
      "payments": [
        {"id": "payment-uuid-1", "amount": 25000, "direction": "inbound", "status": "pending"}
      ]
    },
    ...
  ]
}

对话 API

用于查询合同语料库的 AI 驱动聊天界面。

获取对话列表

GET /conversations

查询参数:

响应:

{
  "data": [
    {
      "id": "conv-uuid-1",
      "title": "最惠国条款分析",
      "persona": "lawyer",
      "model": "gpt-5",
      "contexts": [
        {"entity": "Contract", "id": "contract-uuid-1", "semanticRelevance": 0.95}
      ],
      "message_count": 12,
      "last_message_at": "2025-01-04T08:30:00Z",
      "created_at": "2025-01-03T14:00:00Z"
    }
  ],
  "pagination": {...}
}

获取单个对话

GET /conversations/:id

响应:

{
  "id": "conv-uuid-1",
  "title": "最惠国条款分析",
  "persona": "lawyer",
  "model": "gpt-5",
  "contexts": [
    {"entity": "Contract", "id": "contract-uuid-1", "semanticRelevance": 0.95}
  ],
  "messages": [
    {
      "id": "msg-uuid-1",
      "role": "user",
      "content": "我们对最惠国条款的总风险敞口是多少？",
      "created_at": "2025-01-03T14:00:00Z"
    },
    {
      "id": "msg-uuid-2",
      "role": "assistant",
      "content": "根据我对您合同语料库的分析，我发现了12份包含最惠国条款的合同...",
      "sources": [
        {"entity": "Contract", "id": "contract-uuid-1", "relevance": 0.95},
        {"entity": "Clause", "id": "clause-uuid-1", "relevance": 0.92}
      ],
      "created_at": "2025-01-03T14:00:15Z"
    }
  ],
  "created_at": "2025-01-03T14:00:00Z"
}

创建对话

POST /conversations
Content-Type: application/json

{
  "title": "新分析",
  "persona": "risk_analyst",
  "model": "gpt-5",
  "contexts": [
    {"entity": "Contract", "id": "contract-uuid-1"}
  ]
}

发送消息（流式）

POST /conversations/:id/messages
Content-Type: application/json
Accept: text/event-stream

{
  "content": "用简单的语言解释赔偿条款",
  "attachments": []
}

响应 (SSE 流):

event: thinking
data: {"status": "正在搜索语料库..."}

event: sources
data: {"sources": [{"entity": "Clause", "id": "clause-uuid-1", "relevance": 0.98}]}

event: delta
data: {"content": "本合同中的赔偿条款"}

event: delta
data: {"content": "意味着..."}

event: complete
data: {"message_id": "msg-uuid-3", "tokens_used": 450}

更新对话上下文

PATCH /conversations/:id/contexts
Content-Type: application/json

{
  "contexts": [
    {"entity": "Contract", "id": "contract-uuid-1"},
    {"entity": "Risk", "id": "risk-uuid-1"}
  ]
}

政策 API

内部规则和合规标准。

获取政策列表

GET /policies

查询参数:

响应:

{
  "data": [
    {
      "id": "policy-uuid-1",
      "title": "无需董事会批准的最大合同金额",
      "description": "超过100万美元的合同需要董事会批准",
      "category": "financial",
      "severity": "critical",
      "status": "active",
      "rule": {
        "field": "value",
        "operator": "greater_than",
        "threshold": 1000000
      },
      "violations_count": 2,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {...}
}

获取单个政策

GET /policies/:id

创建政策

POST /policies
Content-Type: application/json

{
  "title": "强制保密条款",
  "description": "所有合同必须包含保密条款",
  "category": "legal",
  "severity": "major",
  "rule": {
    "type": "clause_required",
    "clause_type": "confidentiality"
  }
}

政策违规

GET /policies/:id/violations

响应:

{
  "data": [
    {
      "id": "violation-uuid-1",
      "policy_id": "policy-uuid-1",
      "contract": {
        "id": "contract-uuid-1",
        "title": "大型企业协议"
      },
      "details": "合同金额150万美元超过100万美元阈值",
      "status": "open",
      "detected_at": "2025-01-02T09:00:00Z"
    }
  ]
}

活动 API

所有系统操作的综合审计跟踪。

获取活动列表

GET /activities

查询参数:

响应:

{
  "data": [
    {
      "id": "activity-uuid-1",
      "action": "updated",
      "description": "合同状态更改为 'active'",
      "entity_refs": [
        {"entity": "Contract", "id": "contract-uuid-1"}
      ],
      "user": {
        "id": "user-uuid-1",
        "name": "张三",
        "avatar": "https://..."
      },
      "metadata": {
        "previous_status": "draft",
        "new_status": "active"
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2025-01-04T09:15:00Z"
    }
  ],
  "pagination": {...}
}

获取单个活动

GET /activities/:id

红线对比 API

AI 驱动的合同对比和智能红线标注。

对比文档（流式）

POST /redline
Content-Type: multipart/form-data
Accept: text/event-stream

original: [二进制文件 - DOCX/PDF]
revised: [二进制文件 - DOCX/PDF]

响应 (SSE 流):

event: status
data: {"step": "uploading", "status": "completed", "side": "left", "message": "原始文件已上传", "progress": 100}

event: status
data: {"step": "uploading", "status": "completed", "side": "right", "message": "修订文件已上传", "progress": 100}

event: status
data: {"step": "extracting", "status": "processing", "side": "left", "message": "正在提取原始文件...", "progress": 0}

event: status
data: {"step": "extracting", "status": "completed", "side": "both", "message": "提取完成", "progress": 100}

event: segmented_text
data: {"left": ["1. 本协议...", "2. 服务..."], "right": ["1. 本协议...", "2. 专业服务..."]}

event: status
data: {"step": "parsing", "status": "processing", "side": "both", "message": "AI 正在分析差异...", "progress": 0}

event: comparison_result
data: {"type": "identical", "startLineLeft": 1, "endLineLeft": 1, "startLineRight": 1, "endLineRight": 1}

event: comparison_result
data: {"type": "diff", "startLineLeft": 2, "endLineLeft": 2, "startLineRight": 2, "endLineRight": 2, "blackline": "将'服务'改为'专业服务' - 扩展了范围定义"}

event: comparison_result
data: {"type": "insertion", "startLineRight": 15, "endLineRight": 17}

event: comparison_result
data: {"type": "deletion", "startLineLeft": 20, "endLineLeft": 22}

event: summary
data: {"identical": 45, "diff": 8, "insertion": 3, "deletion": 2}

event: status
data: {"step": "parsing", "status": "completed", "side": "both", "message": "AI 分析完成", "progress": 100}

event: complete
data: {"original": "完整 markdown...", "revised": "完整 markdown...", "diff": "已流式传输"}

对比结果类型

Webhooks

订阅实时事件。

注册 Webhook

POST /webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["contract.created", "contract.updated", "risk.created", "payment.overdue"],
  "secret": "your-webhook-secret"
}

Webhook 事件

Webhook 负载

{
  "id": "webhook-event-uuid",
  "event": "contract.updated",
  "timestamp": "2025-01-04T09:15:00Z",
  "data": {
    "id": "contract-uuid-1",
    "changes": {
      "status": {"from": "draft", "to": "active"}
    }
  },
  "signature": "sha256=..."
}

验证 Webhook 签名

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

错误代码

HTTP 状态码

错误响应格式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "无效的请求参数",
    "details": [
      {
        "field": "email",
        "message": "无效的邮箱格式"
      }
    ],
    "request_id": "req-uuid-12345"
  }
}

错误代码

速率限制

速率限制响应头：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704358800