集成指南¶

集成方式¶

集成方式	适用场景	复杂度
REST API	通用场景	低
Webhook	事件驱动	低
SDK	深度集成	中
消息队列	高并发场景	高

REST API 集成¶

Python 示例¶

from product import Client

client = Client(api_key="your_key")

# 文档处理
result = client.document.upload("file.pdf")

# 工作流
wf = client.workflow.execute("workflow_id", params={})

Java 示例¶

import com.example.product.sdk.Client;

Client client = new Client("apiKey", "apiSecret");
DocumentResult result = client.getDocumentService().upload("file.pdf");

Webhook 集成¶

from product import WebhookHandler

handler = WebhookHandler(secret_key="secret")

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    if not handler.verify_signature(request):
        return "Invalid", 401

    event = handler.parse_event(request.json)

    if event.type == "document.processed":
        print(f"文档处理完成: {event.data}")
    elif event.type == "workflow.completed":
        print(f"工作流完成: {event.data}")

    return "OK"

支持的事件¶

事件	触发时机
`document.uploaded`	文档上传完成
`document.processed`	文档处理完成
`workflow.started`	工作流开始
`workflow.completed`	工作流完成
`workflow.failed`	工作流失败

SDK 集成¶

Python SDK¶

pip install product-sdk

from product import YuranClient

client = YuranClient(api_key="your_key")

# 文档
result = client.documents.process(file="doc.pdf")

# 工作流
result = client.workflows.execute(workflow_id="xxx", params={})

# 客服
result = client.chatbot.chat(session_id="xxx", message="你好")

Node.js SDK¶

npm install product-sdk

const { Client } = require('product-sdk');
const client = new Client({ apiKey: 'your_key' });

const result = await client.documents.process({ file: './doc.pdf' });

最佳实践¶

错误处理¶

from product.exceptions import APIError, AuthError, RateLimitError

try:
    result = client.process(file_path)
except AuthError:
    # 刷新token
    client.refresh_token()
except RateLimitError as e:
    # 限流等待
    time.sleep(e.retry_after)
except APIError as e:
    logger.error(f"API错误: {e.code}")

重试机制¶

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2))
def call_api():
    return client.api_call()

:material-arrow-right-circle: 常见问题{: .md-button }