NF-e
查询 NF-e
返回状态、票面与 DANFE / XML 下载链接。
GET
/openapi/v2/empresas/{empresaId}/nf-e/{nfeId}需要
token、timestamp、sign 三个签名头,参见认证与签名。路径参数
empresaId* | string | 开票主体标识 |
nfeId* | string | 发票标识 |
* 必填字段
200
查询成功。
id | string | 请求标识 |
tipo | string | 单据类型 |
status | string | 发票状态 |
motivoStatus | string | 驳回原因 |
ambienteEmissao | string | 开票环境 |
enviadaPorEmail | bool | 是否已邮件发送 |
dataCriacao | string | 受理时刻 |
dataUltimaAlteracao | string | 最后更新时刻 |
forcarEmissaoContingencia | bool | 是否强制应急开票 |
| object | 订单信息 |
| object | 买方信息 |
numero | string | 票号 |
serie | string | 系列号 |
dataEmissao | string | 开票时刻 |
chaveAcesso | string | 访问密钥 |
| object | 运输信息 |
dataAutorizacao | string | 授权时刻 |
linkDanfe | string | DANFE 下载链接 |
linkDownloadXml | string | 授权 XML 下载链接 |
linkConsultaPorChaveAcesso | string | 公开查询地址 |
| object | 授权协议 |
emitidaEmContingencia | bool | 是否应急开出 |
finalidade | string | 开票目的 |
naturezaOperacao | string | 操作性质描述 |
| object | 原票引用 |
| array | 商品行 |
valorTotal | number | 发票总额 |
informacoesAdicionais | string | 票面备注 |
informacoesAdicionaisFisco | string | 给税务机关的备注 |
发票在 SEFAZ 应答前为 AguardandoAutorizacao,之后进入 Autorizada、Negada 或 Cancelada 终态。终态后平台释放请求参数:pedido、备注、naturezaOperacao 以及税码税率以外的税参不再返回。
AguardandoAutorizacao:处理中
受理后到 SEFAZ 应答前。没有票号、密钥、协议与链接;pedido、cliente 与全部税参按传入回显。再查一次或等回调。
json
{"id": "NFe-000014553","status": "AguardandoAutorizacao","numero": null,"chaveAcesso": null,"dataAutorizacao": null,"linkDanfe": null,"linkDownloadXml": null,"pedido": { "presencaConsumidor": "OperacaoPelaInternet", "pagamento": { "tipo": "PagamentoAVista", "formas": [ { "tipo": "CartaoDeCredito", "valor": 28.47 } ] } },"itens": [ { "cfop": "6102", "codigo": "000068", "origem": 0, "impostos": { "icms": { "situacaoTributaria": "102" }, "pis": { "situacaoTributaria": "49", "aliquota": 0 }, "cofins": { "situacaoTributaria": "49", "aliquota": 0 } } } ]}
Autorizada:已授权
票号、密钥、dataAutorizacao、protocolo 与两个链接都有值。每次查询都重新签发链接。
json
{"id": "NFe-000014553","status": "Autorizada","numero": "262","serie": "2","chaveAcesso": "35241104893402000113550020000002621202427463","dataAutorizacao": "2024-11-27T20:56:55Z","protocolo": { "numero": "135240009194753" },"linkDanfe": "https://api.v2.tffiscal.com/openapi/files/danfe/35241104893402000113550020000002621202427463?token=…","linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=…"}
Negada:已驳回
motivoStatus 给出 SEFAZ 返回码与原因。没有 DANFE;已分配的票号会回收,后续开票按先后补上,不会跳号。修正请求后重新开票。
json
{"id": "NFe-000014553","status": "Negada","motivoStatus": "778 - Rejeicao: NCM inexistente","linkDanfe": null,"linkDownloadXml": null}
Cancelada:已取消
取消 NF-e 之后。票号、密钥与协议保留;DANFE 链接不再返回,XML 仍可下载。
json
{"id": "NFe-000014553","status": "Cancelada","numero": "262","chaveAcesso": "35241104893402000113550020000002621202427463","protocolo": { "numero": "135240009194753" },"linkDanfe": null,"linkDownloadXml": "https://api.v2.tffiscal.com/openapi/files/xml/8801?token=…"}
linkDanfe 与 linkDownloadXml 形如 https://api.v2.tffiscal.com/openapi/files/{kind}/{ref}?token=…,不需要签名头:直接 GET 并跟随 302 跳转即可。每次查询都重新签发链接;过期回 401 + 10009036。有效期与其余错误见文件下载。
tipo单据类型
| 取值 | 含义 |
|---|---|
| NF-e | 电子发票,固定此值 |
status发票状态
| 取值 | 含义 |
|---|---|
| AguardandoAutorizacao | 已受理,等待 SEFAZ 应答 |
| Autorizada | SEFAZ 已授权;DANFE 与 XML 可下载 |
| Negada | SEFAZ 驳回;原因在 motivoStatus |
| Cancelada | 授权后已取消 |
ambienteEmissao开票环境
| 取值 | 含义 |
|---|---|
| Homologacao | 税务局测试环境,票无法律效力 |
| Producao | 正式环境 |
finalidade开票目的
| 取值 | 含义 |
|---|---|
| Normal | 普通销售 |
| Complementar | 补充票,补已授权原票的金额、数量或税额 |
| Ajuste | 调整票,对已授权原票做无货物流转的调整 |
| Devolucao | 退货票;带 notaReferenciada |
pedido.presencaConsumidor在场方式
| 取值 | 含义 |
|---|---|
| NaoSeAplica | 不适用,退货票 |
| OperacaoPresencial | 门店现场成交 |
| OperacaoPelaInternet | 互联网成交 |
| OperacaoPorTelefone | 电话成交 |
| EntregaEmDomicilio | 送货上门时成交 |
| OperacaoPresencialForaDoEstabelecimento | 店外现场成交 |
| Outros | 其他 |
pedido.pagamento.tipo付款时点
| 取值 | 含义 |
|---|---|
| PagamentoAVista | 即付 |
| PagamentoAPrazo | 赊购 |
pedido.pagamento.formas[].tipo支付方式
| 取值 | 含义 |
|---|---|
| Dinheiro | 现金 |
| Cheque | 支票 |
| CartaoDeCredito | 信用卡 |
| CartaoDeDebito | 借记卡 |
| CreditoLoja | 店铺信用 |
| ValeAlimentacao | 食品券 |
| ValeRefeicao | 餐券 |
| ValePresente | 礼品券 |
| ValeCombustivel | 燃油券 |
| BoletoBancario | 银行票据 |
| DepositoBancario | 银行存款 |
| PagamentoInstantaneoPix | Pix 即时支付 |
| TransferenciaBancaria | 银行转账 |
| ProgramaDeFidelidade | 忠诚计划或返现 |
| PagamentoInstantaneoPixEstatico | Pix 静态码 |
| CreditoEmLoja | 店内余额 |
| PagamentoEletronicoNaoInformado | 未能对接的电子支付 |
| PagamentoInstantaneoPixAutomatico | Pix 自动扣款 |
| TransferenciaTefBookTransfer | TEF 同行转账 |
| SemPagamento | 无支付,退货票 |
| PagamentoPosterior | 后付 |
| Outros | 其他 |
cliente.indicadorContribuinteICMS买方 ICMS 身份
终态后只有 ContribuinteICMS(带 IE 的 CNPJ)或 NaoContribuinte。
| 取值 | 含义 |
|---|---|
| ContribuinteICMS | 纳税人,带州注册号 |
| ContribuinteIsento | 免登记 |
| NaoContribuinte | 非纳税人 |
cliente.tipoPessoa买方类型
| 取值 | 含义 |
|---|---|
| F | 个人,证件是 11 位 CPF |
| J | 企业,证件是 14 位 CNPJ |
cliente.endereco.uf买方所在州
EX 只出现在出口票。
| 取值 | 含义 |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
| EX | 国外,出口票用 |
transporte.frete.modalidade运费方式
| 取值 | 含义 |
|---|---|
| SemFrete | 无运费 |
| PorContaDoEmitente | 发货方承担 |
| PorContaDoDestinatario | 收货方承担 |
| PorContaDeTerceiros | 第三方承担 |
| TransporteProprioPorContaDoRemetente | 发货方自有车辆 |
| TransporteProprioPorContaDoDestinatario | 收货方自有车辆 |
itens[].origem商品来源
| 取值 | 含义 |
|---|---|
| 0 | 国产 |
| 1 | 直接进口 |
| 2 | 国内购入的进口品 |
| 3 | 国产,进口成分超 40 % |
| 4 | 国产,按基本生产流程制造 |
| 5 | 国产,进口成分不超 40 % |
| 6 | 直接进口,无国产同类品 |
| 7 | 国内购入的进口品,无国产同类品 |
| 8 | 国产,进口成分超 70 % |
itens[].impostos.icms.situacaoTributariaICMS 税码 CST,一般税制 CRT 2 / 3
| 取值 | 含义 |
|---|---|
| 00 | 全额征税。传 aliquota;CRT 3 不传时平台按税率表补 |
| 02 | 燃油按量,自征。须传 monofasico 与商品行 combustivel 块 |
| 10 | 征税并代收下游 ST。须传 aliquota 与 substituicaoTributaria,买方须为 ICMS 纳税人;可选 partilha;可选 motivoDesoneracaoSt |
| 15 | 燃油按量,自征加代征。须传 monofasico,含自征与代征税率 |
| 20 | 税基缩减。须传 aliquota、percentualReducaoBase 与 codigoBeneficioFiscal;可选 motivoDesoneracao |
| 30 | 自身免税但代收下游 ST。须传 substituicaoTributaria 与 codigoBeneficioFiscal,买方须为 ICMS 纳税人;可选 motivoDesoneracao |
| 40 | 免税。须传 codigoBeneficioFiscal;可选 motivoDesoneracao |
| 41 | 不征税。须传 codigoBeneficioFiscal;州际转拨 ST 时同传 substituicaoTributariaDestino 与 retencaoAnterior;可选 motivoDesoneracao |
| 50 | 暂缓。须传 codigoBeneficioFiscal;可选 motivoDesoneracao |
| 51 | 递延。须传 aliquota、percentualDiferimento 与 codigoBeneficioFiscal;传了 aliquotaFcp 还须传 percentualDiferimentoFcp;带减基时可选 codigoBeneficioFiscalReducaoBase |
| 53 | 燃油按量,递延。须传 monofasico,递延比例放 percentualDiferimento |
| 60 | 上游已代收 ST。可选 retencaoAnterior;tributacaoEfetiva 与 substituicaoTributariaDestino 按州要求传 |
| 61 | 燃油按量,前环节已征。须传 monofasico,含前环节税率 |
| 70 | 税基缩减并代收下游 ST。须传 aliquota、percentualReducaoBase、codigoBeneficioFiscal 与 substituicaoTributaria,买方须为 ICMS 纳税人;可选 motivoDesoneracao 与 motivoDesoneracaoSt |
| 90 | 其他。须传 codigoBeneficioFiscal;可选 substituicaoTributaria 与 partilha;可选 motivoDesoneracao 与 motivoDesoneracaoSt |
itens[].impostos.icms.situacaoTributariaICMS 税码 CSOSN,Simples Nacional CRT 1 / 4
| 取值 | 含义 |
|---|---|
| 101 | 征税且允许买方抵扣。须传 percentualCreditoSimples,买方须为 ICMS 纳税人 |
| 102 | 征税不抵扣。ICMS 里不用再传别的;codigoBeneficioFiscal 与 creditosPresumidos 按州要求传 |
| 103 | 营收区间免征。ICMS 里不用再传别的;codigoBeneficioFiscal 与 creditosPresumidos 按州要求传 |
| 201 | 代收 ST 且允许抵扣。须传 percentualCreditoSimples 与 substituicaoTributaria,买方须为 ICMS 纳税人 |
| 202 | 代收 ST 不抵扣。须传 substituicaoTributaria,买方须为 ICMS 纳税人 |
| 203 | 营收区间免征并代收 ST。须传 substituicaoTributaria,买方须为 ICMS 纳税人 |
| 300 | 宪法豁免。ICMS 里不用再传别的;codigoBeneficioFiscal 与 creditosPresumidos 按州要求传 |
| 400 | 不征税。ICMS 里不用再传别的;codigoBeneficioFiscal 与 creditosPresumidos 按州要求传 |
| 500 | 上游已代收 ST。可选 retencaoAnterior |
| 900 | 其他。可选 substituicaoTributaria |
itens[].impostos.pis.situacaoTributariaPIS 税码
| 取值 | 含义 |
|---|---|
| 01 | 基本税率征税 |
| 02 | 差别税率征税 |
| 03 | 按数量征税 |
| 04 | 单相制转售零税率 |
| 05 | 代收 |
| 06 | 零税率 |
| 07 | 免税 |
| 08 | 不征,出口用 |
| 09 | 暂缓 |
| 49 | 其他销项操作 |
| 50–56 | 进项有抵扣权,按收入类型细分,只用于退货票 |
| 60–66 | 进项推定抵扣,按收入类型细分,只用于退货票 |
| 67 | 进项推定抵扣,其他情形,只用于退货票 |
| 70 | 进项无抵扣权,只用于退货票 |
| 71 | 进项免税,只用于退货票 |
| 72 | 进项暂缓,只用于退货票 |
| 73 | 进项零税率,只用于退货票 |
| 74 | 进项不征,只用于退货票 |
| 75 | 进项代收,只用于退货票 |
| 98 | 其他进项操作,只用于退货票 |
| 99 | 其他操作 |
itens[].impostos.cofins.situacaoTributariaCOFINS 税码
与 PIS 同一张表。
| 取值 | 含义 |
|---|---|
| 01 | 基本税率征税 |
| 02 | 差别税率征税 |
| 03 | 按数量征税 |
| 04 | 单相制转售零税率 |
| 05 | 代收 |
| 06 | 零税率 |
| 07 | 免税 |
| 08 | 不征,出口用 |
| 09 | 暂缓 |
| 49 | 其他销项操作 |
| 50–56 | 进项有抵扣权,按收入类型细分,只用于退货票 |
| 60–66 | 进项推定抵扣,按收入类型细分,只用于退货票 |
| 67 | 进项推定抵扣,其他情形,只用于退货票 |
| 70 | 进项无抵扣权,只用于退货票 |
| 71 | 进项免税,只用于退货票 |
| 72 | 进项暂缓,只用于退货票 |
| 73 | 进项零税率,只用于退货票 |
| 74 | 进项不征,只用于退货票 |
| 75 | 进项代收,只用于退货票 |
| 98 | 其他进项操作,只用于退货票 |
| 99 | 其他操作 |
itens[].impostos.ipi.situacaoTributariaIPI 税码
| 取值 | 含义 |
|---|---|
| 00 | 进项征税 |
| 01 | 进项零税率 |
| 02 | 进项免税 |
| 03 | 进项不征 |
| 04 | 进项豁免 |
| 05 | 进项暂缓 |
| 49 | 其他进项 |
| 50 | 销项征税 |
| 51 | 销项零税率 |
| 52 | 销项免税 |
| 53 | 销项不征 |
| 54 | 销项豁免 |
| 55 | 销项暂缓 |
| 99 | 其他销项 |
itens[].impostos.ibsCbs.situacaoTributariaIBS/CBS 状态码
只在分配票号前回显,取值同开票。
| 取值 | 含义 |
|---|---|
| 000 | 全额征税。只传状态码与分类码 |
| 200 | 减率。减率比例由分类码决定;200022 / 200024 须传 tributacaoRegular |
| 410 | 免征或不征。只传状态码与分类码 |
| 510 | 递延。须传 percentualDiferimento |
| 515 | 递延加减率。须传 percentualDiferimento |
| 550 | 暂停征收。须传 tributacaoRegular |
| 620 | 燃油按量征税。须传 monofasico 与商品行 combustivel 块 |
| 800 | 抵扣转移。须传 transferenciaCredito |
| 810 | 马瑙斯自贸区推定抵扣。须传 zonaFrancaManaus |
| 811 | 以前期间调整。须传 ajuste |
itens[].impostos.ibsCbs.classificacaoTributariaIBS/CBS 分类码
只在分配票号前回显,取值同开票。
| 取值 | 含义 |
|---|---|
| 000001 | IBS 与 CBS 全额征税的一般情形 |
| 000003 | 汽车业激励项目(第 311 条);可传 creditoPresumido |
| 000004 | 汽车业激励项目(第 312 条);可传 creditoPresumido |
| 000005 | 本应与 A 类汽油调和的无水乙醇改作他用 |
| 200002 | 供给非纳税人农业生产者或独立货运司机;减率 100 % |
| 200003 | 人类食用产品销售(附件一);减率 100 % |
| 200004 | 医疗器械供给(附件十二);减率 100 % |
| 200005 | 向政府机关与免税医疗机构供给医疗器械(附件十二);减率 100 % |
| 200006 | 政府认定的公共卫生紧急状态;减率 100 % |
| 200007 | 残障人士无障碍器具供给(附件十三);减率 100 % |
| 200008 | 政府机关采购的残障人士无障碍器具;减率 100 % |
| 200009 | Anvisa 注册药品供给;减率 100 % |
| 200010 | 政府机关采购的 Anvisa 注册药品;减率 100 % |
| 200011 | 政府机关采购的肠内与肠外营养制剂;减率 100 % |
| 200012 | 政府认定的公共卫生紧急状态;减率 100 % |
| 200013 | 卫生棉条与卫生巾供给;减率 100 % |
| 200014 | 蔬菜、水果与鸡蛋(附件十五);减率 100 % |
| 200015 | 职业司机或残障人士购买的国产乘用车;减率 100 % |
| 200020 | 选择 IBS/CBS 特定制度的合作社的交易;减率 100 % |
| 200022 | 自贸区外向马瑙斯自贸区内纳税人发送工业品;减率 100 %,须传 tributacaoRegular |
| 200023 | 激励工业之间的中间品供给;减率 100 % |
| 200024 | 自由贸易区外向区内纳税人发送货物;减率 100 %,须传 tributacaoRegular |
| 200030 | 医疗器械销售(附件四);减率 60 % |
| 200031 | 残障人士无障碍器具(附件五);减率 60 % |
| 200032 | Anvisa 注册药品或配制药品,附件十四除外;减率 60 % |
| 200033 | 肠内与肠外营养制剂(附件六);减率 60 % |
| 200034 | 人类食用食品(附件七);减率 60 % |
| 200035 | 个人卫生与清洁用品(附件八);减率 60 % |
| 200036 | 未加工的农、渔、林与植物采集产品;减率 60 % |
| 200038 | 农业与水产养殖投入品(附件九);减率 60 % |
| 200039 | 国内艺术、文化、活动、新闻与影视制作相关供给;减率 60 % |
| 200043 | 向政府供给的主权与安全相关商品和服务(附件十一);减率 60 % |
| 200047 | 酒吧与餐厅;减率 40 % |
| 200053 | Anvisa 注册的血清或疫苗类药品;减率 100 % |
| 200054 | 农业合作社向非正规制度社员供给货物;减率 100 % |
| 410001 | 票面注明且不依赖后续事件的赠品 |
| 410002 | 同一纳税人各分支之间的调拨 |
| 410003 | 捐赠人不取得对价的捐赠 |
| 410004 | 商品与服务出口 |
| 410005 | 联邦、州、联邦区与市政府的供给 |
| 410006 | 宗教团体与各类教堂的供给 |
| 410007 | 政党、工会与非营利教育或社会救助机构的供给 |
| 410008 | 书籍、报纸、期刊及其印刷用纸 |
| 410009 | 巴西制作的音乐录音与音乐影像 |
| 410012 | 未选正规制度的物业小区的供给 |
| 410013 | 燃油出口 |
| 410014 | 非纳税人农业生产者的供给;可传 creditoPresumido |
| 410016 | 固体废弃物的供给或采购;可传 creditoPresumido |
| 410017 | 带附条件推定抵扣的动产采购,须转售 |
| 410019 | 餐饮供给中小费不计入税基 |
| 410020 | 餐饮供给中平台佣金不计入税基 |
| 410026 | 需冲销抵扣的捐赠 |
| 410027 | 服务或无形商品出口 |
| 410029 | 只涉及 ICMS 的交易 |
| 410030 | 因腐坏、变质、被盗或遗失冲销抵扣 |
| 410031 | IBS 与 CBS 生效前的供给 |
| 410035 | 微型创业者的供给 |
| 410999 | 其他无对价且不征税的交易 |
| 510001 | 电力的进口、发电、销售、配电与输电,递延 |
| 515001 | 农业与水产养殖投入品,递延(附件九);减率 60 % |
| 550001 | 有形商品出口;须传 tributacaoRegular |
| 550002 | 过境制度;须传 tributacaoRegular |
| 550003 | 仓储制度(第 85 条);须传 tributacaoRegular |
| 550004 | 仓储制度(第 87 条);须传 tributacaoRegular |
| 550005 | 仓储制度(第 87 条单款);须传 tributacaoRegular |
| 550006 | 暂时进境制度;须传 tributacaoRegular |
| 550007 | 加工贸易制度;须传 tributacaoRegular |
| 550008 | Repetro 临时进口制度下的货物进口;须传 tributacaoRegular |
| 550009 | GNL 临时制度;须传 tributacaoRegular |
| 550010 | Repetro 永久制度;须传 tributacaoRegular |
| 550011 | Repetro 工业化制度;须传 tributacaoRegular |
| 550012 | Repetro 国产制度;须传 tributacaoRegular |
| 550013 | Repetro 保税仓制度;须传 tributacaoRegular |
| 550014 | 出口加工区;须传 tributacaoRegular |
| 550015 | 港口现代化与扩建激励税制;须传 tributacaoRegular |
| 550016 | 基础设施发展特别激励制度;须传 tributacaoRegular |
| 550017 | 造船业激励税制;须传 tributacaoRegular |
| 550018 | 资本品采购减负;须传 tributacaoRegular |
| 550019 | 激励工业为在马瑙斯自贸区使用而进口货物;须传 tributacaoRegular |
| 550020 | 自由贸易区;须传 tributacaoRegular |
| 550021 | 出口导向的加工;须传 tributacaoRegular |
| 550022 | 低碳氢生产特别激励制度;须传 tributacaoRegular |
| 550023 | 石油或天然气来源的非燃料液态烃,含石脑油;须传 tributacaoRegular |
| 620001 | 燃油单相征税 |
| 620002 | 燃油单相征税并负责代扣 |
| 620003 | 燃油单相征税,由第三方代扣 |
| 620004 | 乙醇与 A 类汽油调和比例高于法定值的单相征税 |
| 620005 | 乙醇与 A 类汽油调和比例低于法定值的单相征税 |
| 620006 | 燃油单相征税,前环节已征 |
| 620007 | 单相制度下的腐坏、变质、被盗或遗失 |
| 800001 | 合并、分立或吸收 |
| 800002 | 社员的抵扣转移,含基层合作社 |
| 810001 | 自马瑙斯自贸区发出的供给的推定抵扣 |
| 811001 | 免税或免征销项的抵扣冲销 |
| 811002 | 未纳入核算的发票税额补记 |
| 811003 | 退出 Simples Nacional |
| 错误码 | HTTP | |
|---|---|---|
| 10004000 | 404 | nfeId 不存在。核对开票时传入的 id 与 empresaId。 |
| 10004001 | 404 | nfeId 不存在。核对开票时传入的 id 与 empresaId。 |
| 10003000 | 404 | empresaId 不存在或非本应用名下。 |
