GET/api/v1/media/country-flags/{countryCode}
匿名,需App公共头JSON 响应接入指南 ↗

读取国家与地区图标

请求参数

此地址由支持国家列表的flagUrl返回。八项公共请求头全部必填,X-Client-Type=app、平台为ios或android;无需Bearer。若主动携带凭证则仍会验证。

位置 字段 类型 必填 约束
路径 countryCode string 是 支持目录内的小写两位代码,例如cn、us;不带.svg后缀

无查询参数、无请求体。图片是固定SVG媒体,不使用JSON/JWE封装,也不携带X-Budyoo-Encryption或X-Budyoo-JWE。生产要求HTTPS;当前固定码dev可按开发策略使用HTTP。与需要登录的用户头像读取相互独立,不开放其他媒体文件。

请求示例

base_url='https://api.budyoo.cn' # 当前dev;生产使用HTTPS
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7'
request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"
curl --fail-with-body \
  "$base_url/api/v1/media/country-flags/cn" \
  -H 'Accept: image/svg+xml, application/json' \
  -H 'Accept-Language: zh-CN' \
  -H 'X-Client-Type: app' \
  -H 'X-Platform: android' \
  -H 'X-App-Version: 1.0.0' \
  -H 'X-App-Build: 1' \
  -H 'X-Channel: dev' \
  -H "X-Device-Id: $device_id" \
  -H "X-Request-Id: $request_id" \
  -H "X-Request-Timestamp: $timestamp" \
  --output flag_cn.svg

成功响应

HTTP 200,正文为SVG文件字节,不包含code/message/data/errors包装。

响应头 值/说明
Content-Type image/svg+xml
Cache-Control no-store
Content-Security-Policy default-src 'none'; sandbox,不执行脚本或加载外部资源
X-Request-Id 回传合法请求ID

图标采用现有正式UI中的国旗SVG,保持原始色彩与纵横比。国家目录加载时检查249项素材完整性;不会以空白图标响应缺失文件。

失败响应

HTTP 业务码 条件/处理
400 INVALID_CLIENT_HEADERS 公共头缺失、重复或不合法
400 INVALID_ENCRYPTED_REQUEST 媒体请求错误携带JWE加密模式
401 UNAUTHORIZED 主动携带了无效或格式错误的凭证
403 FORBIDDEN 客户端类型不是app
404 NOT_FOUND 未支持的代码、大小写或后缀不符,例如zz、CN、cn.svg
426 HTTPS_REQUIRED 当前模式要求HTTPS,却使用明文HTTP

失败时按公共协议返回JSON与当前语言提示,例如:

{"code":"NOT_FOUND","message":"对应当前语言的资源不存在提示","data":null,"errors":[]}

接入说明

把flagUrl与当前API源站组合,不与文档站或UI预览站组合,也不要写死服务器IP。图片组件需支持SVG并附带公共头;国旗无需发送用户Token。

仅从服务器已发布的白名单目录读取,不支持上传、任意路径或外部URL代理。国旗和国家数据按同一版本发布;新客户端以国家列表的version管理本地显式缓存。服务端接口验证不代表Flutter已迁移到此图标入口。

验证:服务器272项整合Java回归全部通过,包含249个代码逐项HTTP处理链读取SVG、未知/大写/错误后缀404、公共头与客户端类型、错误凭证、HTTPS及媒体拒绝JWE。已随整合版本部署,完整278项Java回归通过;公网四种语言的目录及首项国旗读取成功,249项逐一读取仍以隔离回归为验证范围。