XML: Noções básicas
É essencial para analistas e programadores entenderem os padrões mais técnicos para troca de informações utilizados no mercado, pois são eles que constroem as soluções. No entanto, não só pessoas técnicas podem tirar proveito do conhecimento um pouco mais avançado. Iremos demonstrar neste artigo como e porquê conhecer arquivos XML pode ser muito útil.
Existem diversos padrões para troca de informações de texto como por exemplo CSV, JSON e XML. Iremos tratar neste artigo sobre o padrão XML, que é adotado pela SEFAZ para implementação dos Documentos Fiscais eletrônicos (DF-e) como por exemplo a NF-e. Como podemos ver no artigo do blog DANFE é nota fiscal? – Prospera ERP a DANFE não é a nota fiscal em si, ela é somente um demonstrativo, uma amostra de parte das informações da NF-e, voltado para impressão e rápida visualização.
Arquivos XML são basicamente arquivos de texto estruturados. A estrutura e descrição dos campos e valores aceitos em um determinado arquivo são determinados pelo XML Schema Definitions, para entender o que são e o que são os erros de Schema na emissão você pode acessar o nosso artigo sobre Schemas. Por que o XML é o escolhido para trafegar e armazenar as notas ? A resposta é que arquivos de texto simples são escolhidos para trafegar dados no lugar de arquivos complexos de texto com formatação como por exemplo docx pois, estes são mais pesados consumindo mais recursos de tráfego de banda.
Estrutura do arquivo
Após uma longa e necessária introdução vamos ao assunto principal que é entender a estrutura do XML. Neste tópico vamos entender o que são as estruturas e o que significam os principais dados comuns a maioria dos documentos fiscais. Tomando como caso a NF-e vamos analisar alguns grupos de tags (campos) para entender a hierarquia e significado dos dados mais comuns entre os diversos documentos.
Tags
Tal qual uma linguagem de marcação, como por exemplo o HTML, o XML é composto por tags que são os campos do XML que descrevem as informações. Toda tag tem um início e um fim e ao final da informação a mesma tag deve existir com um caractere “/” antes do nome.
Ex.:
<Nome>Elías Ricardo Figueroa Brander</Nome> Grupos de tags
Os grupos de tags são agrupamentos que listam dados sobre uma entidade, pessoa ou coisa. A lógica é a mesma da tag, onde o agrupamento é em si uma tag e todas as tags pertencentes ficam dentro dela.
Ex.:
1<Pessoa>2 <Nome>Elías Ricardo Figueroa Brander</Nome>3 <DataNasc>1946-10-25</DataNasc>4 <LocalidadeNasc>Valparaíso</LocalidadeNasc>5 <Pais>56</Pais>6</Pessoa>Identificação da nota fiscal
Nesta parte da nota fiscal temos os campos (tags) que identificam a nota fiscal, qual sua operação, sua natureza, se é emitida para fora do estado, se a pessoa é contribuinte, etc..
1<ide> Nesta linha inicia o grupo de tag Identificação da NF-e
2 <cUF>43</cUF> Código da UF3 <cNF>39418940</cNF> Código numérico de segurança da NF4 <natOp>VENDA</natOp> Descrição da natureza da operação5 <mod>55</mod> Modelo do documento fiscal6 <serie>1</serie> Número da série de sequencia7 <nNF>5016</nNF> Número da NF8 <dhEmi>2021-08-03T00:00:00-03:00</dhEmi> Data e hora da emissão9 <dhSaiEnt>2021-08-03T14:24:20-03:00</dhSaiEnt> Data e hora da saída/entrada10 <tpNF>1</tpNF> Tipo da nota: 0-Entrada ou 1-Saída11 <idDest>2</idDest> Tipo de localização do destinatário12 <cMunFG>4307005</cMunFG> Código do município fato gerador13 <tpImp>1</tpImp> Formato de impressão da DANFE14 <tpEmis>1</tpEmis> Tipo de emissão: Normal ou contingências15 <cDV>2</cDV> Dígito verificador da chave de acesso16 <tpAmb>2</tpAmb> Ambientes: 1-Produção 2-Homologação17 <finNFe>1</finNFe> Finalidade da emissão18 <indFinal>1</indFinal> Indicador se é ou não consumidor final19 <indPres>0</indPres> Indicador de presença20 <procEmi>0</procEmi> Processo de emissão21 <verProc>1.0.0.0</verProc> Versão aplicativo de emissão22</ide> Termina o grupo de tag Identificação da NF-eIdentificação do Emitente
Identificação da pessoa responsável pela emissão dos dados.
1<emit> Início grupo Emitente
2 <CNPJ>08359143000367</CNPJ> Número do CNPJ3 <xNome>Camila Torres Fonseca ME</xNome> Razão Social4 <xFant>Casa & Banho Torres</xFant> Nome fantasia5 <enderEmit> Início do grupo Endereço de registro do Emitente6 <xLgr>AV MAURICIO CARDOSO</xLgr> Nome do Logradouro7 <nro>341</nro> Número8 <xCpl>SALA 101</xCpl> Complemento9 <xBairro>CENTRO</xBairro> Nome do Bairro10 <cMun>4307005</cMun> Código do Município11 <xMun>ERECHIM</xMun> Nome do município12 <UF>RS</UF> Sigla da UF13 <CEP>99700426</CEP> Número do CEP14 <cPais>1058</cPais> Código do País15 <xPais>BRASIL</xPais> Nome do País16 <fone>5433210214</fone> Número de telefone17 </enderEmit> Fim do grupo Endereço de registro do Emitente18 <IE>0390129763</IE> Número da Inscrição Estadual19 <CRT>1</CRT> Código do Regime Tributário20</emit> Fim do grupo EmitenteIdentificação do Destinatário
Identificação da pessoa a quem se destina o documento.
1<dest> Início grupo Emitente2 <CPF>09823791266</CPF> Número do CPF (pessoa física)3 <CNPJ>27785587000857</CNPJ> Número do CNPJ (pessoa jurídica)4 <xNome>Mara Roberta Vieira</xNome>Nome do destinatário5 <enderDest> Início do grupo de endereço para destinatário6 <xLgr>AV. DEODORO DA FONSECA</xLgr>
7 <nro>250</nro>
8 <xCpl>SALA 102</xCpl>
9 <xBairro>PETROPOLIS</xBairro>
10 <cMun>2408102</cMun>
11 <xMun>NATAL</xMun>
12 <UF>RN</UF>
13 <CEP>59010000</CEP>
14 <cPais>1058</cPais>
15 <xPais>BRASIL</xPais>
16 <fone>54996339064</fone>
17 </enderDest> Fim do grupo de endereço para destinatário18 <indIEDest>9</indIEDest>Indicador de tipo de Inscrição Estadual (contribuinte, não contribuinte, isento)19 <IE>0420285210</IE> Número da Inscrição Estadual (pessoa jurídica)20</dest>Autorização de download
Documentos autorizados a baixar o XML da nota fiscal. A pessoa emitente, destinatária e transportadora já tem acesso, estes documentos enviados pelo sistema emissor são pessoas adicionais autorizadas.
1<autXML> Um grupo autXML para cada documento2 <CNPJ>42180710000209</CNPJ>
3</autXML>
4<autXML>
5 <CPF>45305805008</CPF>
6</autXML>Produtos e Serviços da NF-e
Grupo de tags que descreve produtos e serviços. É criado um grupo prod para cada produto/serviço existente.
1<prod> Início do grupo de tags de produto2 <cProd>31</cProd> Código de produto3 <cEAN>9516132500001</cEAN> GTIN (Global Trade Item Number) do produto, antigo código EAN ou código de barras4 <xProd>AGUA SEM GAS</xProd> Nome/Descrição do produto5 <NCM>22011000</NCM> Código NCM6 <CEST>1200400</CEST> Código CEST, obrigatório se o NCM informado se enquadra na categoria de produtos ICMS-ST7 <cBenef>RS052012</cBenef> Código de Benefício Fiscal. Composto por Sigla da UF mais código, habilitado para as UFs RS, PR, RJ e DF.8 <CFOP>6403</CFOP> Número do CFOP9 <uCom>UN</uCom> Sigla da unidade comercial10 <qCom>1.0000</qCom> Quantidade de produtos/itens11 <vUnCom>2.0410000000</vUnCom> Valor unitário comercial12 <vProd>2.04</vProd> Valor total bruto do produto/serviço13 <uTrib>UN</uTrib> Sigla da unidade tributável14 <indTot>1</indTot> 0–valor do item (vProd) não compõe o valor total, 1–valor do item (vProd) compõe o valor total15</prod> Fim do grupo de tagsPedido de compra
Tag onde é enviado o número do pedido de compra da pessoa remetente
1<xPed>112588</xPed> Número do pedidoNúmero de item de pedido
Tag onde é enviado o número do item do pedido de compra a pedido do remetente
1<nItemPed>112588</nItemPed> Número do item do pedidoTributos incidentes nos produtos e serviços da nota
Esse grupo de tags é criado um para cada produto/serviço.
1<imposto>
2 <ICMS>
3 <ICMSSN500> Grupo de tags de ICMS para empresas do regime Simples Nacional conforme tabela CSOSN.4 .
5 .
6 .
7 </ICMSSN500>
8 <ICMS10> Grupo de tags de ICMS para empresas do regime do Lucro Presumido conforme tabela CST-ICMS.9 .
10 .
11 .
12 </ICMS10>
13 </ICMS>
14 <IPI> Grupo de envio de informações sobre o IPI15 <cEnq>999</cEnq> Código de enquadramento legal – Classificação das operações de IPI16 <IPITrib>
17 <CST>99</CST> Código da Situação Tributária do IPI18 <vBC>0.00</vBC> Valor da base para o cálculo do valor do IPI19 <pIPI>0.0000</pIPI> Alíquota do IPI20 <vIPI>0.00</vIPI> Valor do IPI21 </IPITrib>
22 </IPI>
23 <PIS> Grupo de envio de informações do PIS24 <PISAliq> Grupo de informações do PIS quando CST é diferente de 9925 <CST>01</CST> 26 <vBC>834.06</vBC>
27 <pPIS>1.6500</pPIS>
28 <vPIS>13.76</vPIS>
29 </PISAliq>
30 <PISOutr> Grupo de informações do PIS quando CST é igual a 9931 .
32 .
33 .
34 </PISOutr>
35 </PIS>
36 <COFINS>
37 <COFINSAliq> Grupo de informações do COFINS quando CST é diferente de 9938 <CST>01</CST>
39 <vBC>834.06</vBC>
40 <pCOFINS>7.6000</pCOFINS>
41 <vCOFINS>63.39</vCOFINS>
42 </COFINSAliq>
43 <COFINSOutr> Grupo de informações do COFINS quando CST é igual a 9944 .
45 .
46 .
47 </COFINSOutr>
48 </COFINS>
49 <ICMSUFDest> Grupo de informações do ICMS para consumidor final ou não contribuinte em operações para fora do estado50 <vBCUFDest>7.21</vBCUFDest> Valor da BC para a UF de destino51 <vBCFCPUFDest>0.00</vBCFCPUFDest> Valor da BC para a UF de destino52 <pFCPUFDest>0.0000</pFCPUFDest> Percentual adicional inserido na alíquota interna da UF de destino, relativo ao Fundo de Combate à Pobreza (FCP) naquela UF53 <pICMSUFDest>17.5000</pICMSUFDest> Alíquota adotada nas operações internas na UF do destinatário para o produto54 <pICMSInter>7.00</pICMSInter> Alíquota interestadual das UF envolvidas: – 4% alíquota interestadual para produtos importados; – 7% para os Estados de origem do Sul e Sudeste (exceto ES), destinado para os Estados do Norte e Nordeste ou ES; – 12% para os demais casos55 <pICMSInterPart>100.0000</pICMSInterPart> Percentual de partilha para a UF do destinatário: – 40% em 2016; – 60% em 2017; – 80% em 2018; – 100% a partir de 201956 <vFCPUFDest>0.00</vFCPUFDest> Valor do ICMS relativo ao Fundo de Combate à Pobreza (FCP) da UF de destino57 <vICMSUFDest>0.76</vICMSUFDest> Valor do ICMS de partilha para a UF do destinatário58 <vICMSUFRemet>0.00</vICMSUFRemet> Valor do ICMS de partilha para a UF do remetente. Nota: A partir de 2019, este valor será zero59 </ICMSUFDest>
60</imposto>Dados dos totais da nota
1<total>Grupo dos totais da NF-e2 <ICMSTot> Grupo dos totais da NF-e relativo ao ICMS3 <vBC>0.00</vBC> 4 <vICMS>0.00</vICMS>
5 <vICMSDeson>0.00</vICMSDeson>
6 <vICMSUFDest>0.97</vICMSUFDest>
7 <vFCP>0.00</vFCP>
8 <vBCST>0.00</vBCST>
9 <vST>0.00</vST>
10 <vFCPST>0.00</vFCPST>
11 <vFCPSTRet>0.00</vFCPSTRet>
12 <vProd>9.25</vProd>
13 <vFrete>0.00</vFrete>
14 <vSeg>0.00</vSeg>
15 <vDesc>0.00</vDesc>
16 <vII>0.00</vII>
17 <vIPI>0.00</vIPI>
18 <vIPIDevol>0.00</vIPIDevol>
19 <vPIS>0.00</vPIS>
20 <vCOFINS>0.00</vCOFINS>
21 <vOutro>0.00</vOutro>
22 <vNF>9.25</vNF>
23 </ICMSTot>
24</total>Dados de transporte
Dados referentes ao transporte dos produtos, neste grupo estão inclusos dados da transportadora, dados de veículo e veículo reboque. Por padrão somente a modalidade de frete é enviada.
1<transp>
2 <modFrete>0</modFrete> Modalidade de frete. Ex: CIF, FOB, Terceiros, etc.
3</transp>Dados de cobrança
O grupo de tags de cobrança é enviado sempre que o meio de pagamento for diferente de 90-Sem pagamento.
1<cobr>
2 <fat>
3 <nFat>5016</nFat>
4 <vOrig>9.25</vOrig>
5 <vDesc>0.00</vDesc>
6 <vLiq>9.25</vLiq>
7 </fat>
8</cobr>Meio de pagamento
O Meio de pagamento selecionado. Ex.: 01-Dinheiro
1<pag>
2 <detPag>
3 <tPag>01</tPag>
4 <vPag>9.25</vPag>
5 </detPag>
6</pag>Informações adicionais (complementares) da nota
Campo de texto longo personalizável que pode ser utilizado pelo emissor e pelo usuário do sistema emissor para colocar informações pertinentes a operação.
1<infAdic>
2 <infCpl>Tributos Federais R$ 0,69(7,44%) Tributos Estaduais R$ 0,49(5,28%) Tributos Municipais R$ 0,19(2,07%) Fonte: IBPT</infCpl>
3</infAdic>