-
背景（谁？什么问题？有什么影响？为什么？）
UI图：https://www.figma.com/design/9FiI688Zkm8KsDgzADtl1Y/CJY%E9%9C%80%E6%B1%82?node-id=0-1&p=f&t=6ldbV7fPj9wkNBwO-0
oapi提供的接口：https://eccang.yuque.com/gv76wn/dfz5b2/zchwmz8noprskaad
Bling接口文档：
https://developer.bling.com.br/bling-api#introdu%C3%A7%C3%A3o
-
需求（做什么？怎么做？有什么要注意的？）
前置需求：
1.https://devops.aliyun.com/projex/req/ECERPH-28011# 《【巴西发票】仓配系统》产品资料新增支持填入税务信息NCM和CEST》
2.https://devops.aliyun.com/projex/req/ECERPH-27925# 《【巴西发票】订单系统》shopee订单新增待上传发票和已上传发票的标识》
3.https://devops.aliyun.com/projex/req/ECERPH-27601# 《【巴西发票】订单系统》shopee订单保存订单的CPF》
4.https://devops.aliyun.com/projex/req/ECERPH-28014# 《【巴西发票】新增Bling平台授权功能》
中台需求：
1.https://devops.aliyun.com/projex/req/ECERPJ-7664# 《中台》shopee需要提供一个拉取订单list的透传接口接口》【已上线】
关联文档：
https://eccang.yuque.com/gv76wn/kz11w8/sfog071znefqc8gn
2.https://devops.aliyun.com/projex/req/ECERPJ-7601# 《中台》shopee新增对接上传发票的接口》【已上线】
【以上基础需求需要和巴西发票需求一起上线】
----------------------------------------------------------------------------------------------------------------------------------------------------------
订单系统》巴西发票管理
-
新增巴西发票管理-店铺绑定页面
(1)展示当前授权的Bling账号以及绑定的店铺账号别名。
(2)点击查看全部和绑定店铺弹出如下绑定店铺弹窗
①添加绑定店铺弹窗如下，支持一次性多选多个店铺，选择多个店铺后按照每个店铺一行进行保存数据。
②添加店铺内仅展示Shopee巴西店铺以及未绑定Bling账号的店铺。
③发票商品金额支持以下2个设置方式
④发票运费金额支持选择不含买家运费和含买家运费
（2）编辑绑定设置弹窗如下
（3）删除绑定设置弹窗如下：
（4） 日志
|
操作场景
|
日志内容
|
|
绑定店铺关系
|
将XX店铺和此Bling账号绑定，发票商品金额按照商品金额百分比：10%，不含买家运费进行开票
|
|
编辑店铺关系
|
XX店铺的发票商品金额设置由按照商品金额百分比：10%调整为按照订单全额开票
|
|
删除店铺关系
|
删除和XX店铺的绑定关系
|
（5）筛选项
Bling账号：支持多选筛选
店铺账号：仅显示shopee店铺，支持多选筛选
授权状态：已授权/授权异常/已过期，单选筛选
账号状态：开启/关闭，单选筛选
2.在shopee订单上待发货审核状态下新增按钮
(1)勾选的订单不是待上传发票的订单提示
（2）)勾选的订单的订单号在系统内已经申请开票过了
(2)勾选的订单都是待上传发票订单的时候弹窗如下：
①点击开票的时候检验订单所在店铺有没有绑定Bling店铺
②检验商品信息中是否缺失NCM码
③检查订单中是否所有商品都设置了不发
④订单的商品缺失产品商品英文名
⑤已经成功加入创建发票队列
（3）①以上勾选的订单仅加入待开发票的队列等待等待订单审核成功后按照订单审核后的订单内容生成发票
②这些订单在审核的时候要推送给仓配系统，通知仓配系统这些订单为待上传发票的订单，暂缓进行订单预报。
③创建发票成功（即订单发票状态为开票中）后需要在订单日志中记录：”订单已提交开票，请在巴西发货管理页面查看开票结果。此订单将在发票上传成功后再进行预报。”
（4）创建发票接口调用详情说明
|
参数名
|
必选
|
类型
|
说明
|
服务商字段名
|
系统取值说明
|
|
account
|
是
|
object
|
帐号信息（params.account）
|
|
|
|
url
|
否
|
string
|
API请求地址
不填会使用默认地址：https://www.bling.com.br
|
|
|
|
authCompanyCode
|
是
|
string
|
帐号中心公司代码
|
传这2个字段时，将会使用帐号中心的授权信息
|
客户代码
|
|
platformSellerId
|
是
|
string
|
帐号中心店铺帐号
|
Bling店铺账号英文名
|
|
username
|
是
|
string
|
bling账号
|
传这3个字段时，将会使用OAPI的授权功能
|
|
|
clientId
|
是
|
string
|
bling开发者clientId
|
|
|
clientSecret
|
是
|
string
|
bling开发者clientSecret
|
|
|
order
|
是
|
object
|
订单信息
（params.order）
|
|
|
|
orderNo
|
是
|
string
|
订单号
|
|
系统订单号
|
|
weightUnit
|
否
|
string
|
重量单位，可选值（KG、G、LB、OZ），默认KG
KG 千克
G 克
LB 磅
OZ 盎司
|
|
|
|
createTime
|
否
|
string
|
签发时间(巴西时间)
example: 2025-05-12 12:34:19
不传值时默认传当前时间
|
dataOperacao
|
创建发票的时间（使用巴西首都的时间UTC-3）
|
|
shippingAmount
|
否
|
string
|
发票相关的额外费用。这些费用可以是运输费、手续费、包装费等，通常会影响发票的总金额。
默认为0
|
despesas
|
根据订单上用户的设置决定是否填写运费
|
|
discountAmount
|
否
|
string
|
对发票总金额的折扣。折扣可以是固定金额或百分比，通常用于促销、客户优惠或批量购买
默认为0
|
desconto
|
|
|
remark
|
否
|
string
|
备注
不传值时默认取第1个商品英文名
|
observacoes
|
|
|
ext
|
是
|
object
|
订单信息扩展字段
（params.order.ext）
|
|
|
|
naturezaOperacaoId
|
否
|
string
|
操作性质ID
这个 ID 是 Bling 系统内部生成的，用于区分不同的操作性质
您可登录 Bling 系统，导航到 Cadastros > Naturezas de Operação，在列表中查找您需要的操作性质，并记录其 ID。
|
naturezaOperacao.id
|
|
|
invoiceNum
|
否
|
string
|
发票序号
如果不传，则会从bling获取最大发票序号再加1生成
|
numero
|
|
|
products
|
是
|
[]object
|
产品信息
params.order.products
|
|
|
|
nameEn
|
是
|
string
|
英文品名
|
descricao
|
仓库SKU产品英文名。如果缺失英文名则报错提示
|
|
sku
|
否
|
string
|
产品sku
为空时取nameEn值
|
codigo
|
仓库SKU编码
|
|
quantity
|
是
|
int
|
数量
|
quantidade
|
仓库SKU数量
|
|
quantityUnit
|
否
|
string
|
数量单位
默认：PCS
|
unidade
|
|
|
price
|
是
|
float
|
产品单价
最多保留2位小数
|
valor
|
根据订单设置计算：
（1）全额：按照订单商品单价原价进行取值
（2）自定义比例：按照订单单价原价*自定义比例计算取值
|
|
grossWeight
|
否
|
float
|
毛重
最多保留2位小数
|
pesoBruto
|
|
|
netWeight
|
否
|
float
|
净重
最多保留2位小数
|
pesoLiquido
|
|
|
ext
|
是
|
object
|
扩展字段
（params.products.*.ext）
|
商品扩展
|
|
|
ncm
|
否
|
string
|
NCM（Nomenclatura Comum do Mercosul，南方共同市场通用命名法）是一个用于商品分类的编码系统。它是巴西和其他南方共同市场国家（如阿根廷、巴拉圭、乌拉圭等）用于标识商品类型和适用税率的标准编码。
|
classificacaoFiscal
|
根据仓配系统用户在仓库SKU上填写的NCM推送
|
|
cest
|
否
|
string
|
CEST（Código Especificador da Substituição Tributária，替代税特定代码）是一个用于标识商品是否适用 替代税制度（Substituição Tributária, ST） 的编码。CEST 编码与 NCM 编码结合使用，帮助确定商品的税务处理方式。
|
cest
|
根据仓配系统用户填写在仓库SKU上填写的的Cest推送
|
|
source
|
否
|
string
|
Origem（来源）用于标识商品的来源地。这个字段与巴西的税务规则（如 ICMS 税率）密切相关，直接影响税费的计算。默认为0.
0 国产商品（Nacional）
1 进口商品（Estrangeira - Importação Direta）
2 进口商品（Estrangeira - Adquirida no Mercado Interno）
3 国产商品，且符合特定法律条件（Nacional, Conteúdo de Importação >= 40%）
4 国产商品，且符合特定法律条件（Nacional, Cuja Produção Seguiu Processos Produtivos Básicos）
5 国产商品，且符合特定法律条件（Nacional, Conteúdo de Importação < 40%）
6 进口商品（Estrangeira - Importação Direta, sem Similar Nacional）
7 进口商品（Estrangeira - Adquirida no Mercado Interno, sem Similar Nacional）
8 国产商品，且符合特定法律条件（Nacional, Conteúdo de Importação >= 70%）
|
origem
|
|
|
serviceCode
|
否
|
string
|
服务代码，是用于标识发票（Nota Fiscal de Serviço, NFS-e）中提供的服务类型的代码。这个代码是巴西市政服务税（ISS）计算和申报的关键信息。
|
codigoServico
|
|
|
shipper
|
是
|
object
|
发件人信息（params.shipper）
|
|
|
|
name
|
否
|
string
|
姓名
|
|
|
|
companyName
|
否
|
string
|
公司名称
|
nomeUsuario
|
|
|
countryCode
|
否
|
string
|
国家二字简码
|
|
|
|
stateOrProvince
|
否
|
string
|
州/省
|
|
|
|
city
|
否
|
string
|
城市
|
|
|
|
address1
|
否
|
string
|
地址1
|
|
|
|
address2
|
否
|
string
|
地址2
|
|
|
|
houseNo
|
否
|
string
|
门牌号
|
|
|
|
postalCode
|
否
|
string
|
邮编
|
|
|
|
phone
|
否
|
string
|
电话号码
|
|
|
|
mobile
|
否
|
string
|
电话号码
|
|
|
|
phoneExtension
|
否
|
string
|
电话分机号
|
|
|
|
email
|
否
|
string
|
E-mail
|
|
|
|
vatNum
|
否
|
string
|
cnpj税号
|
cnpj
|
|
|
consignee
|
是
|
object
|
收件人信息（params.consignee）
|
|
|
|
name
|
是
|
string
|
姓名
|
nome
|
收件人名称
|
|
countryCode
|
是
|
string
|
国家二字简码
默认为BR
|
pais
|
收件人国家二字码
|
|
stateOrProvince
|
是
|
string
|
州/省
|
uf
|
州/省
|
|
city
|
是
|
string
|
城市
|
municipio
|
城市
|
|
address1
|
是
|
string
|
地址1
|
endereco
|
地址1
|
|
address2
|
否
|
string
|
地址2
|
地址2
|
|
houseNo
|
否
|
string
|
门牌号
|
numero
|
门牌号
|
|
postalCode
|
否
|
string
|
邮编
|
cep
|
邮编
|
|
phone
|
是
|
string
|
电话号码
|
telefone（有手机优先取手机，否则取电话）
|
|
|
mobile
|
否
|
string
|
手机号码
|
手机号码
|
|
email
|
否
|
string
|
邮箱号
|
email
|
邮箱号
|
|
vatNum
|
是
|
string
|
CNPJ（公司） 或 CPF（个人） 税号
|
numeroDocumento
|
CPF
|
|
ext
|
是
|
object
|
扩展字段
（params.consignee.ext）
|
|
|
|
personType
|
否
|
|
联系人的类型
F-Física 个人
J-Jurídica 公司
E-Estrangeira 外国联系人
不填默认 F
|
tipoPessoa
|
根据用户选择
|
|
taxPayer
|
否
|
string
|
纳税人类型(可不传)
1 Contribuinte do ICMS 需要缴纳 ICMS 的正规企业
2 Contribuinte isento de ICMS 享受 ICMS 免税政策的行业或交易
9 Não contribuinte 个人消费者
如果未传值时，会自动根据 personType值传值：如果 personType 为 J 时传 1; 为 F 时,传 9；默认传2
|
contribuinte
|
|
|
stateTaxNum
|
是
|
string
|
州税号
当personType为 J 时必填
|
ie
|
用户填写则提供
|
|
specialAttr
|
是
|
object
|
运输属性
|
|
|
|
insuranceValue
|
否
|
float
|
与发票相关的保险费用。保险费用通常用于保障货物在运输过程中的安全，可能会影响发票的总金额。
默认为0
|
|
|
3.发票管理页面
（1）发票状态说明
|
状态
|
场景说明
|
可操作按钮
|
|
开票中
|
加入系统创建发票队列未推送到Bling的发票
|
查看详情
日志
|
|
开票失败
|
调用了Bling接口开票失败的发票。（需要区分创建发票接口报错还是发送发票接口报错）
|
查看详情
日志
|
|
已开票
|
调用Bling接口开票成功的发票
|
查看详情
下载XML
下载DANFE（下载PDF）
|
（2）查看详情
（3）下载XML/下载DANFE/下载
以上按钮仅在已开票状态下显示。
下载按钮的情况下，如果勾选了发票则导出勾选发票，如果没有勾选发票则导出筛选条件下的发票。
导出的多个发票的时候合并在一个压缩包内，压缩包的名称为：”日期+时间+发票XML/发票Danfe“。例如：202505261130:01发票XML
（4）列表字段说明
|
字段名称
|
取值说明
|
|
系统订单号
|
系统订单号+系统订单状态
|
|
发票号
|
已开票状态显示发票号，点击发票号弹出发票详情弹窗
|
|
Bling账号
|
发票关联的Bling 账号，显示别名和英文名
|
|
店铺账号
|
订单所属的店铺，显示别名和英文名
|
|
开票金额
|
订单中商品开票金额+运费开票金额之和
|
|
收件人名称
|
发票的收票人的名称以及CPF
|
|
时间
|
创建时间：发票在系统的创建时间
开票时间：发票推送给Bling的时间
上传时间：发票推送给平台的时间
|
|
开票失败原因
|
仅在开票失败下显示。
需要根据返回判断是创建发票失败还是发送发票失败，并且显示对应的提示词。如下：
创建发票失败，请查看以下失败原因，然后按照失败原因编辑发票后提交重新开票
平台返回失败原因
创建发票失败，请查看以下失败原因，然后按照失败原因编辑发票后提交重新开票
系统返回失败原因（仓库SKU缺失NCM码；仓库SKU缺失英文名称）
发送发票失败，请查看以下失败原因，然后按照失败原因登陆Bling平台编辑发票后再提交开票
平台返回失败原因
|
|
上传状态
|
待上传：发票未生成的时候，等待上传发票的状态
上传中：已生成发票并且进入上传队列的状态
已上传：发票已经成功上传到shopee的状态
上传失败：发票上传到shopee失败的状态
|
（6）筛选功能
全部店铺：显示shopee的巴西店铺支持多选筛选
全部Bling账号：显示Bling账号，支持多选筛选
开票失败原因：创建发票失败/发送发票失败，支持单选
系统订单号/参考号/发票号：单个搜索时候模糊搜索，多个搜索的时候精确搜索
上传状态：待上传、上传中、已上传、上传失败
时间筛选项：创建时间/开票时间/上传时间。默认选中最近3个月的创建时间
（7）订单的发票状态已开票状态并且通过系统上传发票到shopee成功则需要在对应订单的日志中记录“通过系统成功上传发票，发票号：XXXXXXXXX”
（8）在审核的时候要推送给仓配系统，通知仓配系统这订单为待上传发票的订单暂缓进行订单预报。
这些订单如果通过系统上传发票成功或者此订单更新为已上传发票的订单则再次通知仓配系统此订单可以进行预报了。
关联需求：https://devops.aliyun.com/projex/req/ECERPH-29587# 《仓配系统》shopee巴西待上传发票的订单需要上传发票成功后再进行预报》