抖音企业号api认证需严格遵循oauth2授权码模式，access_token有效期2小时、refresh_token仅1年且单次有效；调用fan/list须用企业号open_id而非用户open_id；私信仅限用户24小时内主动发起会话后回复；webhook回调需aes-128-cbc解密并严格校验签名。
抖音企业号 API 认证失败：access_token 拿不到或 401 报错
调用抖音企业号 API 的第一步就卡住，大概率是认证流程没走对。抖音不支持直接用账号密码或 cookie 调用，必须走 OAuth2 授权码模式 + 服务端换 token 流程，且 access_token 有效期仅 2 小时，refresh_token 也只有一年（且只能用一次）。
常见错误现象：{"error":"invalid_grant","error_description":"authorization code invalid"} —— 多半是授权码用了两次、过期了，或 redirect_uri 和申请应用时填的不完全一致（连末尾斜杠都算差异）。
- 务必用服务端发起
POST https://open.douyin.com/oauth/access_token换取access_token，别在前端 JS 里拼接请求 -
client_id、client_secret、code、grant_type=authorization_code四个参数缺一不可，grant_type必须小写、不能带空格 - 抖音要求
redirect_uri必须和应用后台配置的**完全相同**，包括协议（https）、域名、路径、查询参数（如有），建议配置成简单路径如https://yourdomain.com/callback避免歧义 - 拿到
access_token后要存到服务端（如 Redis 或数据库），PHP session 不可靠，尤其多机部署时
用 PHP 调用粉丝列表接口：fan/list 返回空或报错
抖音企业号粉丝接口不是“查全部”，而是分页拉取，且默认只返回最近 7 天关注的用户；更关键的是，它要求传 open_id（不是 union_id），而这个 open_id 必须来自你已授权的企业号主体，不是测试号或个人号。
常见错误现象：{"error_code":10001,"description":"invalid open_id"} 或返回 "data":[] 却确认有粉丝。
- 确保调用的是企业号自己的
open_id，可通过/oauth/userinfo接口用access_token换取，注意该接口返回的open_id是用户维度的，不是企业号维度的——企业号本身的open_id在应用后台「应用信息」页里找，叫「企业号唯一标识」 -
fan/list接口需传open_id（企业号的）、access_token、cursor（起始位置，默认 0）、count（每页最多 50，不能超） - 抖音不会实时同步粉丝关系，新关注用户可能延迟几分钟才出现在接口里；取消关注也不会立刻消失，有缓存周期
- 该接口不返回用户手机号、微信号等敏感字段，只含
fan_open_id、follow_time、status（1=关注中，2=已取关）
PHP 主动发私信失败：message/send 提示权限不足或消息被拒
抖音对企业号私信有极严限制：必须是用户 24 小时内主动发送过消息（即开启过会话），你才能回一条；超过 24 小时未互动，再发就报错 error_code: 10012（“not allowed to send message”）。
常见错误现象：{"error_code":10012,"description":"not allowed to send message"} 或提示 "message template not approved"（但私信不用模板）。
- 发私信前必须先调用
message/conversation/list查用户是否在可回复窗口期内，看last_msg_time是否在当前时间减去 24 小时之内 -
message/send的to_user_id必须是用户的fan_open_id（不是open_id），且该用户必须已关注你，否则直接拒绝 - 消息内容不能含营销话术、链接、二维码、联系方式，纯文本长度上限 500 字；含图片需先调
media/upload上传，返回media_id再传入消息体 - 不要高频调用，抖音限流明显：单个 access_token 每分钟最多 60 次，私信类接口实际阈值更低，建议加
sleep(1)控制节奏
PHP 处理私信回调（Webhook）收不到事件或解析失败
抖音推送的私信事件是 POST 到你配置的 callback_url，但 Body 是加密的 JSON（AES-128-CBC），不是明文；而且签名验证不通过就等于白搭，抖音会停止推送。
常见错误现象：Nginx 日志显示 200，但 PHP 没收到数据；或解密后 JSON 格式错误；或抖音后台显示“回调失败”。
- 必须用抖音提供的
encoding_aes_key（32位 base64 字符串）和token（应用后台配置的字符串）做签名验证，顺序是：拼接msg_signature+timestamp+nonce+body（原始 raw body），再 SHA1 - 解密前要先 Base64 解码 body，再用 AES-CBC（PKCS7 填充）解密，IV 是
timestamp的前 16 字节（需补零或截取） - PHP 用
openssl_decrypt()时，$options = OPENSSL_ZERO_PADDING，且必须手动去除 PKCS7 填充字节（不能依赖函数自动处理） - 回调地址必须是 HTTPS，且响应要在 3 秒内返回 HTTP 200，body 只能是纯字符串
success（无空格、无换行、无 JSON）
抖音的 access_token 生命周期、open_id 层级混淆、私信时间窗硬限制、Webhook 加密细节——这些不是文档漏了，是设计如此。绕不开，只能按它的规则写。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
