SuperAPI AI 工具集

asaas

编程与开发

查看项目

更新于 11-16 03:53

技能介绍

本资料整理 Asaas 支付 API(巴西支付服务商)的集成与调试知识,面向需要在代码中接入 Asaas 的开发者。Asaas 使用 REST 与 JSON,每个环境一份 API key。资料中标注为“this skill's rule”的内容属于建议,不是厂商事实;标注为“observed in production, not in the docs”的内容来自实际集成,可能变化。

一、认证与环境 基础地址:沙箱 https://api-sandbox.asaas.com/v3,生产 https://api.asaas.com/v3。请求头使用 access_token 放 API key,不使用 Authorization: Bearer;Content-Type 为 application/json;2024-06-13 起创建的根账户必须传 User-Agent。沙箱 key 以 $aact_hmlg_ 开头,生产 key 以 $aact_prod_ 开头,key 发错环境会返回 401 invalid_environment。其他 401 代码包括 access_token_not_found、invalid_access_token_format、invalid_access_token。key 只展示一次,账户最多 10 个 key;未使用的 key 3 个月后停用(可重新启用),6 个月后永久过期,并有 ACCESS_TOKEN_DISABLED、ACCESS_TOKEN_EXPIRING_SOON、ACCESS_TOKEN_EXPIRED 事件提醒。 资料特别提醒 key 中的 $ 是 key 的一部分,.env 加载器可能把 $aact_… 当作变量引用替换为空串;不同加载器(Bun、Docker Compose)对裸值、双引号、单引号、双美元、反斜杠的转义效果不同,建议启动时检查 key 前缀,缺失或格式错误时明确失败,且不要记录 key。

二、定时扣款方式选择 资料区分三种容易混淆的产品:Assinatura(/subscriptions,billingType 为 PIX)由 Asaas 每个周期创建新扣款,Pix 和 boleto 不会自动扣款;Pix Automático 是付款人一次性授权后的循环借记,授权状态 ACTIVE 时自动扣款,首笔通过一个二维码完成支付并授权;Pix Recorrente 是付款人安排的循环出站转账,不是扣款。Pix Automático 需要拥有 CNPJ 且活跃至少 6 个月的 PJ 账户。

三、客户与一次性 Pix 扣款 任何扣款前先 POST /v3/customers,name 和 cpfCnpj 为必填,需收集并存储税号;响应返回 cus_… 需保存。Asaas 接受相同 CPF/CNPJ 的重复客户,超时后应先查询再重试。notificationDisabled: true 可停止 Asaas 自身扣款通知;mobilePhone 是手机号,phone 是座机。 一次性 Pix 扣款示例:POST /v3/lean/payments,字段 customer、billingType 为 PIX、value、dueDate;GET /v3/payments/{id}/pixQrCode 返回 encodedImage(base64)、payload(copia e cola)、expirationDate。动态二维码只能支付一次,并在扣款到期日之后 12 个月过期。需先在账户注册 Pix key:POST /v3/pix/addressKeys,{"type":"EVP"}(API 只创建随机 key)。无 key 时二维码绑定合作机构,仅当天 23:59 前可付且处理更慢;创建 key 需账户完全批准并完成活体证明,个人限 5 个、公司限 20 个,创建间隔一分钟。更新扣款后需重新获取二维码;沙箱 404 页面说明后注册的 key 不能修复之前生成的二维码,应新建扣款。

四、支付链接、订阅与 Webhook POST /v3/paymentLinks 创建托管页面,chargeType 可为 DETACHED、INSTALLMENT、RECURRENT,billingType 为 UNDEFINED 时付款人自选方式;链接创建的客户可能重复。订阅示例:POST /v3/subscriptions,字段包括 customer、billingType、nextDueDate、value、cycle、description;cycle 可选 WEEKLY、BIWEEKLY、MONTHLY、BIMONTHLY、QUARTERLY、SEMIANNUALLY、YEARLY。默认在到期日前 40 天创建每笔扣款(可配置 14 或 7 天),可用 PAYMENT_CREATED 事件跟踪,建议按 dueDate 自行发送提醒。PUT 可修改未来扣款,updatePendingPayments: true 同时修改待处理扣款;status 为 INACTIVE 暂停,DELETE 结束并移除待处理和逾期扣款。 Webhook 处理需返回 HTTP 200(FAQ 与暂停队列页面只接受 200),10 秒内响应,不跟随重定向;15 次连续失败暂停该 webhook 队列,队列事件 14 天后删除。需处理的事件包括 PAYMENT_CREATED、PAYMENT_RECEIVED、PAYMENT_CONFIRMED、退款类事件、拒付类事件、PAYMENT_OVERDUE 等。全额 Pix 退款可能以 PAYMENT_PARTIALLY_REFUNDED 到达,建议按 refunds 数组汇总判断是否全额撤销;拒付未结时建议暂停而非撤销。

五、沙箱、子账户与限制 沙箱需单独账户和 key,覆盖范围与生产不同,折扣、利息、罚款及 WhatsApp 通知等可能无法测试。沙箱接口包括 POST /v3/sandbox/payment/{id}/confirm、/overdue、POST /v3/sandbox/myAccount/approve。子账户与支付分账不在本技能覆盖范围;只有 PJ(CNPJ)账户可创建子账户,新 API 子账户用户有评估期限制(最多 10 个子账户、每子账户 R$ 2.000 扣款、最长 60 天),分账默认禁用,需在 Integrações > Segurança 启用,分账按净额计算。资料最后列出常见陷阱,如不要用 Authorization 传 key、不要假设 Pix 订阅自动扣款、不要用固定模式校验支付 id(新 id 含下划线)、Webhook 不要返回 201/204、不要在存储事件前返回 200 等。