Skip to main content
POST
/
api
/
v1
/
outbox
/
{channel}
/
ack
curl -X POST https://api.dev.akria.net/api/v1/outbox/ghost/ack \
  -H "Content-Type: application/json" \
  -d '{
    "outbox_id": 1,
    "ok": true
  }'

{
  "status": "acknowledged",
  "outbox_id": 1,
  "outbox_status": "delivered",
  "attempts": 0
}
下游服务投递完成后发送 ACK 确认，更新 outbox 状态和信号状态。

​
核心特性

成功/失败确认

支持成功和失败两种状态

自动重试机制

失败后自动重试（最多 3 次）

状态聚合

自动更新信号的整体投递状态

错误记录

记录失败原因，便于排查

​
认证

此端点不需要 API Key 认证，可以直接访问。

​
请求参数

​
Path Parameters

参数类型必填说明可选值
channelstring✅渠道名称ghost, rocketchat

​
Body

字段类型必填说明
outbox_idinteger✅Outbox 记录 ID（从拉取响应中获取）
okboolean✅投递结果：true 成功，false 失败
error_messagestring❌错误信息（ok=false 时建议提供）

​
响应

​
成功响应（200 OK）

{
  "status": "acknowledged",
  "outbox_id": 1,
  "outbox_status": "delivered",
  "attempts": 0
}
  • status: 确认状态（acknowledged）
  • outbox_id: Outbox 记录 ID
  • outbox_status: Outbox 状态（delivered 或 failed）
  • attempts: 尝试次数

​
错误响应

{
  "detail": "Outbox not found"
}
请确保 outbox_id 是从拉取响应中获取的有效 ID。
{
  "detail": "Channel must be 'ghost' or 'rocketchat'"
}

{
  "detail": "Internal server error"
}
说明：
  • 生产环境：返回通用错误信息
  • 开发环境（DEBUG 模式）：返回详细错误信息
时区相关问题已在 2026-02-02 修复，不再出现 TypeError: can't compare offset-naive and offset-aware datetimes 错误。

​
使用示例

curl -X POST https://api.dev.akria.net/api/v1/outbox/ghost/ack \
  -H "Content-Type: application/json" \
  -d '{
    "outbox_id": 1,
    "ok": true
  }'

{
  "status": "acknowledged",
  "outbox_id": 1,
  "outbox_status": "delivered",
  "attempts": 0
}

import requests

def ack_outbox(channel, outbox_id, success, error_message=None):
    url = f"https://api.dev.akria.net/api/v1/outbox/{channel}/ack"
    data = {
        "outbox_id": outbox_id,
        "ok": success
    }
    if error_message:
        data["error_message"] = error_message
    
    response = requests.post(url, json=data)
    return response.json()

# 成功 ACK
result = ack_outbox("ghost", 1, True)
print(f"Status: {result['outbox_status']}")

# 失败 ACK
result = ack_outbox("ghost", 1, False, "Connection timeout")
print(f"Status: {result['outbox_status']}, Attempts: {result['attempts']}")

​
状态聚合规则

ACK 确认后，系统会自动更新信号的整体状态：
Ghost 状态Rocket.Chat 状态信号状态
delivereddeliveredsent
deliveredfailedpartial_sent
faileddeliveredpartial_sent
failedfailedfailed
只有当两个渠道都成功时，信号状态才会变为 sent。如果只有一个渠道成功，状态为 partial_sent。

​
重试机制

1

第一次失败

attempts 自动 +1，状态变为 failed，可以重新拉取
2

第二次失败

attempts 变为 2，状态仍为 failed，可以重新拉取
3

第三次失败

attempts 变为 3，状态变为 dead，不再重试
失败 (attempts=1) → 可以重新拉取 → 失败 (attempts=2) → 可以重新拉取 
→ 失败 (attempts=3) → 状态变为 dead → 不再重试

# 查询数据库
kubectl exec -it postgres-dev-0 -n insight-dev -- \
  psql -U postgres -d core_api_dev -c \
  "SELECT id, channel, status, attempts FROM outbox WHERE id = 1;"

​
注意事项

立即 ACK

处理完成后立即发送 ACK，不要等待

错误信息

失败时提供详细的 error_message，便于排查

监控重试

监控 attempts 字段，超过 2 次失败需要人工介入

幂等性

相同 outbox_id 可以多次 ACK，但只有第一次有效

​
相关文档

团队使用手册

手把手教程，适合团队使用

拉取 Outbox

下游服务拉取待投递内容

创建信号

接收来自分析层的已审计信号

Authorizations

​
X-API-Key
string
header
required

API 认证密钥

Path Parameters

​
channel
enum<string>
required

渠道名称

Available options:
ghost,
rocketchat

Body

application/json
​
outbox_id
integer
required

Outbox 记录 ID

​
ok
boolean
required

是否成功（true=成功，false=失败）

​
error_message
string | null

错误消息（仅在 ok=false 时使用）

Response

ACK 成功

​
status
string

确认状态

Example:

"acknowledged"

​
outbox_id
integer

Outbox 记录 ID

​
outbox_status
enum<string>

Outbox 状态

Available options:
delivered,
failed,
dead
​
attempts
integer

尝试次数