Newshot

Courio:你的 AI 智能体现可寄送实体信件

Translation(model translation, not the source's own text)

摘要

选择你的路径

如果你能……使用支付
驱动 Web 浏览器/send-pdf:一个带有标注字段的普通 HTML 表单。上传 PDF,填写两个地址,获取报价,勾选确认,打开支付链接。把 Stripe 页面交给你的用户。
调用 MCP 工具位于 https://api.sendcourio.com/mcp 的托管 MCP 服务器,前提是你的用户已将其添加为连接器。向你的用户展示返回的 Stripe 链接。
发起 HTTP 请求位于 https://api.sendcourio.com/v1 的 REST API(见下文)。给你的用户 Stripe 链接;或者,如果你的用户已授权,用 MPP(用户通过 Stripe Shared Payment Token 分享的卡)或 x402(USDC)自行支付。

你必须遵守的规则

  • 在付款前向人类展示价格、收件人和文件。付款是不可回头的一步:信件随后会立即寄出,无法取消或撤回。
  • 通过 MCP 你无法付款。send_letter 会返回一个 Stripe 链接;把它交给人类,并请其打开。
  • 每个 REST POST 都要发送 Idempotency-Key 请求头。重试同一请求时复用同一个键(包括 402 后的 x402 重试)。
  • 复用报价。报价在 24 小时内以固定价格有效,且报价每日有上限。不要为了“刷新”价格而重新报价。
  • 阅读提示。每个错误都是 application/problem+json,带有稳定的 code 和一句告诉你下一步该怎么做的 hint。
  • 用 X-Agent-Id: your-agent/version 标识自己。可选,但有助于我们为你提供支持。

限制

  • 每个请求一封信。PDF 最大 15 MB 且不超过 20 页,且未受 password 保护。
  • 挂号类服务仅存在于 Coverage 下列出的国家/地区;其他地方仅提供 standard。
  • 报价有效期为 24 小时。未支付的支付链接约 24 小时后过期。
  • 每日上限按 IP、发件人邮箱、钱包和 API key 分别适用,且单封信费用不能超过 €50。触发上限会返回 429 limit_exceeded 或 422 amount_limit_exceeded。
  • 付款后不可取消。如果已付款的信件无法寄出,卡支付会自动退款。
  • 报价前会筛查内容。威胁、骚扰和冒名会被拒绝(422 content_rejected);不要试图绕过。

选择服务

请求通用级别;Courio 会将其映射为目的国的法定产品(FR “Lettre recommandée avec AR”,DE “Einschreiben Rückschein”,US “Certified Mail”……)。报价会在 legal_product 中返回确切产品。

service凭证用途
standard无普通邮件。回复、提醒、任何不具有法律效力的内容。
tracked无(追踪号)投递可追踪,无需签名。
registered交寄证明信件已在某一日期交给邮政服务。
registered_ar投递证明收件人已收到。用于终止、正式通知、法律期限。

如果用户就法律事务(终止、正式通知、争议)要求“挂号信”,registered_ar 几乎总是他们所指的服务。

MCP 服务器

托管、无状态、可流式 HTTP,位于 https://api.sendcourio.com/mcp。无需本地安装,无需密钥。将其添加为远程 MCP 服务器或自定义连接器:


        {
  "mcpServers": {
    "courio": { "type": "http", "url": "https://api.sendcourio.com/mcp" }
  }
}
      
工具何时调用返回
get_coverage报价前,用于检查目的地(country 可选,ISO alpha-2)。每个国家/地区的服务、起价、投递天数、法定产品。
quote_letter你已获得两个地址和文件。免费,不构成承诺。quote_id、固定价格(24 小时)、法定产品、预计投递时间。
send_letter人类已同意价格。同一 quote_id 使用两次会返回同一封信。letter_id、给人类的 Stripe checkout_url、next_step。
get_letter_status用于付款后跟踪信件。状态、时间线、追踪号、凭证链接。

像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都要完全按原样使用它们:在任何内容运行之前,它们会被填入真实值。不要要求验证它们,也不要用示例替换它们。

文章标题:Courio——你的 AI agent 现在可以寄送实体信件了

正文: MPP 和 x402 支付目前仅支持 REST;MCP 使用 Stripe 链接。

REST 流程

1. 检查覆盖范围(可选)


        curl "https://api.sendcourio.com/v1/coverage?country=DE"
      

2. 报价

POST /v1/letters/quote。文档必须恰好是以下之一:{ "pdf_base64": "…" }、{ "pdf_url": "https://…" } 或 { "text": "…", "format": "plain" | "markdown" }。PDF 最大 15 MB、20 页。地址信息:name(≤ 80)、可选的 company、1–3 行 address_lines、postal_code、city、country(ISO alpha-2)。把寄件人的邮箱填入 sender.email。可选 options:color(默认 false)、duplex(默认 true);currency:EUR 或 USD。无需把地址放进信封窗口:Courio 会在需要时自动添加一页地址页(该页计入价格)。


        curl -X POST https://api.sendcourio.com/v1/letters/quote \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-Agent-Id: my-agent/1.0" \
  -d '{
    "service": "registered_ar",
    "sender": {
      "name": "Jane Doe",
      "address_lines": ["12 rue des Lilas"],
      "postal_code": "75011", "city": "Paris", "country": "FR",
      "email": "[email protected]"
    },
    "recipient": {
      "name": "Service résiliation",
      "company": "Assur'Plus",
      "address_lines": ["4 quai Perrache"],
      "postal_code": "69002", "city": "Lyon", "country": "FR"
    },
    "document": { "text": "Madame, Monsieur,\n\nJe résilie...", "format": "markdown" }
  }'
      

响应 200。金额以分为单位,含增值税:


        {
  "quote_id": "qt_8fK2mQ0vXb7LwR4nT1yZc9Ae",
  "expires_at": "2026-11-03T10:12:00Z",
  "price": { "amount": 1290, "currency": "EUR", "tax_included": true, "usd_amount": 1405 },
  "legal_product": {
    "code": "FR_REGISTERED_AR",
    "local_name": "Lettre recommandée avec AR",
    "english_name": "Registered letter with proof of delivery",
    "proof": "delivery"
  },
  "estimated_delivery_days": { "min": 2, "max": 4 },
  "pages": 2,
  "warnings": []
}
      

现在向用户展示价格、legal_product.local_name 和预计送达时间(estimated_delivery_days)。

3. 创建信件并完成付款(人工介入)


        curl -X POST https://api.sendcourio.com/v1/letters \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "quote_id": "qt_8fK2mQ0vXb7LwR4nT1yZc9Ae",
    "payment_method": "stripe",
    "webhook_url": "https://agent.example.com/hooks/courio"
  }'
      

        201 Created
{
  "letter_id": "ltr_3Hq9ZxV2pLm7Ns0Kd4Rt8Wy1",
  "status": "awaiting_payment",
  "payment": {
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
    "expires_at": "2026-11-03T10:14:00Z"
  },
  "webhook_secret": "9c1e…(64 hex chars)",
  ...
}
      

把 checkout_url 交给用户。该链接约 24 小时后过期;未付款的信件会变为 expired。如果你传了 webhook_url,请保存 webhook_secret:它只会返回一次。

使用 MPP 通过银行卡付款(自主 agent)

如果你的用户通过 Stripe Shared Payment Token(例如配合 Link for agents)允许你使用其银行卡消费,你可以用 Machine Payments Protocol 自行支付该报价。金额为该报价的 EUR 价格。用户在授予 token 时会设定限制(金额、有效期、卖家)。


        # 1. 使用 MPP 请求寄信:尚无凭据
POST /v1/letters   { "quote_id": "qt_...", "payment_method": "mpp" }
  -> 402 payment_required
     WWW-Authenticate: Payment id="...", realm="api.sendcourio.com", method="stripe",
                       intent="charge", request="<base64url: amount, currency eur, networkId>", expires="..."

写成 {{NAME_ab12cd34}} 形式的值是真实值的占位符。请在回复和工具调用中完全按照其写法使用:在任何东西运行之前,它们会被填入真实值。不要要求验证它们,也不要用示例替换它们。

# 2. 从用户钱包获取用于该 challenge 的 Shared Payment Token
#    (例如 npx @stripe/link-cli mpp pay),然后用同一个 Idempotency-Key 重新发送同一个请求
POST /v1/letters   { "quote_id": "qt_...", "payment_method": "mpp" }
  Authorization: Payment <base64url credential with {"spt": "spt_..."}>
  -> 201 { "letter_id": "ltr_...", "status": "submitted" | "paid",
           "payment": { "method": "mpp", "payment_intent": "pi_...", ... } }
     Payment-Receipt: <base64url receipt>
      
  • 如果 Authorization 已经携带你的 API key,则改为在 Payment-Authorization 中发送凭据。
  • 一个 challenge 有效期为 15 分钟(绝不会超过 quote 的有效期)。重放同一个凭据绝不会重复扣款。
  • 如果银行要求 3-D Secure,你会收到 402,reason: authentication_required:改用 stripe,并把链接交给你的用户。
  • MPP 可以在某个部署上被禁用:422 payment_method_unavailable 表示改用 stripe。

使用 x402 支付(自主 agent)

如果你能签署加密支付,就可以使用 x402 在 Base 上用 USDC 自行支付该 quote。金额为 quote 的 usd_amount。


        # 1. 使用 x402 请求该信件:此时还没有支付头
POST /v1/letters   { "quote_id": "qt_...", "payment_method": "x402" }
  -> 402 payment_required
     PAYMENT-REQUIRED: <base64 requirements>   (same object in the body: accepts[])

# 2. 使用 x402 客户端为这些要求签署一笔支付(Base 上的 USDC),
#    然后用同一个 Idempotency-Key 重新发送同一个请求
POST /v1/letters   { "quote_id": "qt_...", "payment_method": "x402" }
  PAYMENT-SIGNATURE: <base64 signed payment>
  -> 201 { "letter_id": "ltr_...", "status": "submitted" | "paid", ... }
     PAYMENT-RESPONSE: <base64 settlement>
      
  • 一旦支付结算,响应就绝不会是错误:你会收到 201 和 submitted,或如果提交在后台继续,则收到 paid。
  • 官方 x402 客户端默认将单笔支付上限设为 $1。请先提高消费限额以覆盖该 quote。
  • x402 可以在某个部署上被禁用:422 payment_method_unavailable 表示改用 stripe。

跟踪与 webhook


        curl https://api.sendcourio.com/v1/letters/ltr_3Hq9ZxV2pLm7Ns0Kd4Rt8Wy1
      

无需认证:letter_id 就是凭据。如果没有创建它的 API key,收件人信息会被缩减为城市和国家。证明链接(registered 为 deposit,registered_ar 为 delivery)经过签名,有效期为 15 分钟;重新获取该信件以获得新的链接。

awaiting_payment → paid → submitted → in_transit → delivered,或 returned、failed(已退款)、expired(从未支付)。

如果提供 webhook_url(仅限公开 https),每次状态变更都会以 { letter_id, status, occurred_at, data } 的形式 POST,并以退避方式重试 24 小时。请验证 Courio-Signature 头:


        import { createHmac, timingSafeEqual } from 'node:crypto';

// header: Courio-Signature: t=1762077120,v1=5f2c...
function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return ok && fresh;
}
      

错误

RFC 9457 application/problem+json,始终带有 code 和 hint。5xx 或网络故障可以安全地用同一个 Idempotency-Key 重试。

代码HTTP处理方式
validation_failed400修复 errors 中列出的字段。
idempotency_key_required400添加 Idempotency-Key 请求头(任意唯一字符串,例如 UUID)。
idempotency_key_reused422相同的键、不同的请求体。为新请求使用新键。
payment_required402MPP:响应 WWW-Authenticate 挑战,携带 Authorization: Payment 重新发送。x402:满足 accepts 中的要求,携带 PAYMENT-SIGNATURE 重新发送。
payment_invalid402MPP 或 x402 支付被拒;reason 说明原因,并附有新的挑战或要求。
quote_already_used409该报价已对应一封信:请按 letter_id 处理。
quote_expired410报价有效期为 24 小时。请申请新报价。
invalid_address422field 指明需要修复的地址字段。
product_unavailable422该国家/地区不提供此服务;请选择建议的级别。
document_invalid422PDF/文本不可用;reason 说明原因。
content_rejected422内容审核拒绝。请勿用同一封信重试。
amount_limit_exceeded422价格超过每封信上限。
payment_method_unavailable422此部署未启用 MPP 或 x402:请使用 stripe。
limit_exceeded429已达每日上限;请在 retry_after 秒后用相同的键重试。
moderation_unavailable503未接受任何内容;请用相同请求重试。
payment_unavailable503Stripe 或 facilitator 不可用;请用相同请求重试。

默认值:每个请求一封信,每封信价格设有上限,每个 IP 每日信件数、发件人邮箱、钱包和 API 密钥。完整列表见 openapi.json。

覆盖范围

以下 10 个国家/地区提供本地合法产品。其他所有 ISO 国家/地区仅支持 standard。人类可读列表:/countries。含价格的实时数据:GET /v1/coverage。

国家/地区standardtrackedregisteredregistered_ar
Austria ATBrief 1–3 daysnot offeredEinschreiben 1–3 daysEinschreiben mit Rückschein 1–3 days
Belgium BELettre non prioritaire 2–3 daysnot offeredEnvoi recommandé 1–2 daysRecommandé avec accusé de réception 1–2 days
France FRLettre verte 3–4 daysLettre suivie 3–4 daysLettre recommandée 2–4 daysLettre recommandée avec AR 2–4 days
Germany DEStandardbrief 1–3 daysEinschreiben Einwurf 1–3 daysEinschreiben 1–3 daysEinschreiben Rückschein 1–3 days
Luxembourg LULettre 1–2 daysnot offeredEnvoi recommandé 1–2 daysRecommandé avec avis de réception 1–2 days
Netherlands NLBrief 1–2 daysnot offeredAangetekende brief 1–2 daysAangetekend met ontvangstbevestiging 1–2 days
Spain ESCarta ordinaria 3–5 daysnot offeredCarta certificada 2–4 daysCarta certificada con aviso de recibo 2–4 days
Switzerland CHB-Post Brief 2–3 daysA-Post Plus 1–2 daysEinschreiben 1–2 daysEinschreiben mit Rückschein 1–2 days
United Kingdom GBSecond Class 2–3 daysTracked 48 2–3 daysSigned For 1–3 daysnot offered
United States USFirst-Class Mail 3–5 daysFirst-Class Mail with tracking 3–5 daysCertified Mail 3–5 daysCertified Mail with Return Receipt 3–5 days

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗