Parâmetros Adicionais de Emissão
O segundo argumento de InvoiCyFramework_EmiteDocumento (e de InvoiCyFramework_ImprimeDocumentoEx) aceita configurações válidas somente para aquela chamada. O conteúdo é um XML, ou o caminho de um arquivo XML, com a tag raiz **ParametrosAdicionais:
<ParametrosAdicionais>
<ImpressaoRecibo>1</ImpressaoRecibo>
<MensagemPromocional>Obrigado pela preferência!</MensagemPromocional>
<DocumentoTexto1>...comprovante TEF...</DocumentoTexto1>
</ParametrosAdicionais>
| TAG | VALORES |
|---|---|
| ImpressaoRecibo | 0 = não imprime; 1 = imprime; 2 = não imprime, mas gera o DANFE em BMP/PDF. |
| AguardarFinalizarImpressaoRecibo | 0; 1 = retorna a emissão só após concluir a impressão. |
| MensagemPromocional | Texto impresso no DANFE. |
| DocumentoTexto1 … DocumentoTexto5 | Até 5 comprovantes (TEF, confissão de dívida etc.) impressos após o DANFE, em texto ou Framework-HTML. Em contingência, impressos uma única vez. |
| LayoutImpressaoDanfeNfce, LayoutImpressaoPosQrcode, ImprimeAcrescDescItens, ImprimeCPFDestMascarado, NaoImprimeEnderecoDest, ImprimeChaveAcessoBarcode, ImprimeCodigoProdutoEAN | Mesmos valores dos parâmetros de configuração equivalentes. |
| ModoCortePapel | parcial ou total. |
| Correcao | 0; 1 = reenvio corrigido de documento rejeitado. Veja Correção de documento rejeitado. |
Se o AC controla a numeração, o mesmo argumento pode levar a tag SubstituirDocumento. Veja em detalhes, em Substituição de documento.
Emissão, Eventos e Consultas
Emissão
Monte o XML (ou JSON) no layout de integração InvoiCy e chame EmiteDocumento. O FW converte para o layout SEFAZ, assina, numera, envia, imprime e devolve o resultado.
Na NF-e (modelo 55) o fluxo é o mesmo. O FW só imprime o DANFE Simplificado Tipo 2 (tpImp=6), e só essa NF-e admite contingência offline. Os demais DANFEs de NF-e são responsabilidade do AC.
Para a emissão de NF-e por contribuinte exclusivo do IBS/CBS (sem Inscrição Estadual), veja Adaptações à Reforma Tributária.
Interpretação do Retorno
Avalie dois campos: Codigo** (resultado da comunicação) e **SitCodigo (situação do documento). Veja o Anexo A.
| OPERAÇÃO | CODIGO | SITCODIGO | RESULTADO |
|---|---|---|---|
| Emissão | 100 | 100, 120 ou 150 | Autorizado — imprimir/entregar. |
| Emissão | 100 | 108 | Emitido em contingência (NFC-e ou NF-e com DANFE Simplificado Tipo 2) — válido; será sincronizado. |
| Cancelamento | 100 | 101 | Cancelamento homologado. |
| Inutilização | 100 | 102 | Inutilização homologada. |
Qualquer outra combinação significa documento/evento não emitido; SitDescricao traz o motivo.
Importante: cStat 120 - A partir de 05/10/2026 (NT 2026.002) a SEFAZ pode responder 120 – Autorizado o uso da NF-e, com alerta. É uma autorização: o documento tem protocolo e não deve ser reemitido. Teste a autorização pelo conjunto {100, 120, 150}, nunca por igualdade a 100 — caso contrário a venda autorizada será tratada como erro e reemitida. Os alertas (até 5 pares cMsg / xMsg) vêm no **protNFe** do XML autorizado e podem acompanhar também uma rejeição. Com cMsg=200, o texto de xMsg é impresso no DANFE.
Contingência Offline (NFC-e e NF-e Tipo 2)
Vale para a NFC-e e, desde a 01.50.04, para a NF-e com DANFE Simplificado Tipo 2 (tpImp=6, NT 2026.002). As demais NF-e não entram em contingência.
Com TIPO_CONTINGENCIA=1 e AUTO_INCREMENTA=1, quando o InvoiCy ou a SEFAZ não respondem (timeout, falha de conexão, Codigo 201, SitCodigo 108/109 sem XML, rejeições configuradas em REJEICAO_nnn_*), o FW:
- avança o sequencial e emite o documento em
tpEmis=9, retornandoSitCodigo108 com o DANFE de contingência (2 vias, ou 1 via se configurado no InvoiCy em Painel de controle → Configurações para a emissão de NFC-e); - envia junto a instrução de substituição do documento original, que o InvoiCy cancela ou inutiliza conforme a situação na SEFAZ;
- permanece em contingência até a comunicação voltar (mais
CONTINGENCIA_ATRASO) e sincroniza os pendentes a cadaTEMPO_VERIFICACAO.
Documentos rejeitados na sincronização vão para DocPendentes/Erro e precisam de ação do AC (veja Correção).
Com TIPO_CONTINGENCIA=0, a falha de comunicação retorna 999.
Importante: Imprimir uma única via em contingência exige que o emitente tenha lavrado termo no livro modelo 6 (ou declaração equivalente da UF), assumindo a guarda eletrônica do XML. Santa Catarina tem particularidades para contingência: consulte integracao@migrate.info.
Contingência Forçada
EMITIR_EM_CONTINGENCIA=1 faz o FW emitir tudo em contingência sem tentar o online — útil quando o AC já sabe que está sem conexão. Volte para 0 assim que a conexão for restabelecida: enquanto ativo, os pendentes não são sincronizados.
Substituição de Documento
Quando o AC controla a numeração (AUTO_INCREMENTA=0) e não obtém a situação final de um documento (ex.: SitCodigo 108 sem XML), ele deve emitir a mesma venda com o próximo número em tpEmis=9 e pedir a substituição do anterior:
<SubstituirDocumento>
<nNF>2035</nNF> <serie>260</serie> <modelo>NFCe</modelo>
<CNPJ_emit>99999999999999</CNPJ_emit>
<nNFSubstituta>2036</nNFSubstituta> <serieSubstituta>260</serieSubstituta>
</SubstituirDocumento>
Regras da SEFAZ para o cancelamento por substituição (evento 110112): a nota substituída deve ter tpEmis=1 e a substituta tpEmis=9 (rejeição 920); dhEmi da substituta até 2 h após a original (915); a substituta precisa estar autorizada (913).
Correção de Documento Rejeitado
Um documento emitido em contingência e rejeitado na sincronização pode ser corrigido e reenviado com <Correcao>1</Correcao>. O XML corrigido deve manter tpEmis=9, a série, o número e o dhEmi originais. O resultado é devolvido diretamente, sem acionar contingência.
Cancelamento
Prazo normal de 30 minutos após a autorização (pode variar por UF). Fora do prazo, ou com trânsito de mercadoria, use NF-e de devolução.
<EnvioEvento>
<ModeloDocumento>NFCe</ModeloDocumento>
<Versao>4.00</Versao>
<Evento>
<NtfCnpjEmissor>99999999999999</NtfCnpjEmissor>
<NtfNumero>100</NtfNumero>
<NtfSerie>1</NtfSerie>
<tpAmb>2</tpAmb>
<EveInf>
<EveDh>2026-10-13T10:18:21</EveDh>
<EveFusoHorario>-03:00</EveFusoHorario>
<EveTp>110111</EveTp>
<EvenSeq>1</EvenSeq>
<Evedet>
<EveDesc>Cancelamento</EveDesc>
<EvexJust>Cancelamento solicitado pelo cliente</EvexJust>
<EvenProt>0</EvenProt>
</Evedet>
</EveInf>
</Evento>
</EnvioEvento>
Inutilização
Inutiliza um número ou faixa não utilizada, a qualquer momento:
<Inutilizacao>
<ModeloDocumento>NFCe</ModeloDocumento>
<Versao>4.00</Versao>
<CnpjEmissor>99999999999999</CnpjEmissor>
<tpAmb>2</tpAmb>
<NumeroInicial>545</NumeroInicial>
<NumeroFinal>545</NumeroFinal>
<Serie>35</Serie>
<Justificativa>Numeracao nao utilizada</Justificativa>
</Inutilizacao>
Consulta
Consulta a situação de um documento ou faixa:
<Consulta>
<ModeloDocumento>NFCe</ModeloDocumento>
<Versao>4.00</Versao>
<tpAmb>2</tpAmb>
<CnpjEmissor>99999999999999</CnpjEmissor>
<NumeroInicial>1</NumeroInicial>
<NumeroFinal>10</NumeroFinal>
<Serie>1</Serie>
</Consulta>
Na consulta, a situação vem em DocSitCodigo / DocSitDescricao.
Impressão e Recursos Auxiliares
Impressão
O DANFE NFC-e pode ser tratado de três formas:
| QUEM MONTA | QUEM IMPRIME | COMO |
|---|---|---|
| FW | FW | Configure IMPRESSORA_CANAL. |
| FW | AC | Crie a subpasta recibos (PDF) ou use ImpressaoRecibo=2 / IMPRESSORA_CANAL=BITMAP. |
| AC | AC | Use o XML autorizado de DocXMLBase64. |
- Reimpressão:
ImprimeDocumentocom o retorno da emissão, com o XML autorizado ou comNULL(última emissão). - Logotipo: grave
logotipo.bmpna pasta de trabalho — BMP monocromático (1 bit), largura máxima de 576 pixels. Logotipo de até 210 × 210 px é impresso alinhado à esquerda com dados do emitente impressos ao lado; acima disso, a impressão do logotipo e dados é centralizada.
DANFE Simplificado Tipo 2 (NF-e)
O FW imprime o DANFE Simplificado Tipo 2 (NT 2026.002 e 2026.003) da NF-e emitida com tpImp=6. A SEFAZ aceita esse tipo de impressão com indPres 1, 4 ou 5.
<Envio>
<ModeloDocumento>NFe</ModeloDocumento>
<ide>
<mod>55</mod>
<indPres>1</indPres>
<tpImp>6</tpImp>
...
- QR Code: o FW monta o grupo
infNFeSupl(qrCodeeurlChave) como na NFC-e. Usa o CSC e o ID Token da NFC-e cadastrados no InvoiCy (QR Code v2) ou o certificado (v3, conforme a vigência). Sem eles, a emissão volta com 464. UminfSupleminformado pelo AC é respeitado. - Layout: o mesmo do DANFE NFC-e, com o título "DANFE Simplificado Tipo 2", a identificação "NF-e Nº … Série …" e os totais de CBS, IBS e IS. Na autorização com alerta (
cMsg=200), o texto dexMsgé impresso. - Parâmetros: valem os mesmos do DANFE NFC-e:
IMPRESSORA_CANAL,LAYOUT_IMPRESSAO_*,ImpressaoRecibo, logotipo eImprimeDocumentopara reimpressão. O PDF gravado emrecibosmantém o nomeNFCe<chave>.pdf. - Contingência: segue a contingência offline da NFC-e, inclusive a impressão do DANFE de contingência. NF-e com
tpEmis=9e outrotpImpé rejeitada com 711. No Android, a contingência da NF-e Tipo 2 ainda não está disponível.
Obs.: As impressoras homologadas são a Bematech, Epson, Elgin, Daruma, Dimep, Sweda, Control iD, além de impressoras genéricas ESC/POS e do spooler do Windows.
Valor Aproximado dos Tributos — Lei 12.741/2012
Com LEI_DO_IMPOSTO_CALCULAR_VALORES entre 1 e 5, o FW obtém a tabela IBPT do InvoiCy (ou do CSV em LEI_DO_IMPOSTO_ARQUIVO), calcula vTotTrib por item e no total e gera a mensagem em infCpl. Com 0, tudo isso é responsabilidade do AC.
| VALOR | INFADPROD POR ITEM | MENSAGEM EM INFCPL |
|---|---|---|
| 1 | — | Valor Aprox dos Tributos: R$ xx,xx |
| 2 | Federal/Estadual/Municipal | idem ao 1 |
| 3 | idem | Detalhada: federais, estaduais, municipais, total e fonte, uma por linha |
| 4, 5 | idem | Valor Aprox dos Tributos: R$ ww,ww + linha com Federal/Estadual/Municipal e fonte |
Calculadora de Tributos da RTC
O FW pode consultar a Calculadora de Tributos sobre o Consumo da Receita Federal para montar os grupos de IBS/CBS/IS dos itens e dos totais. O uso é opcional; a calculadora não faz parte do FW.
- Instale a calculadora offline (WSL, Docker ou Java) conforme as instruções oficiais.
- Configure
URL_API_CALCULADORA(padrão localhttp://localhost:8080/api; em Android ou em rede, use o IP da máquina da calculadora). -
Informe em cada item o grupo
<IBSCBS>com<CST>e<cClassTrib>, além decUF,cMunFG,dhEmi,NCM,vProd,qComeuCom. -
Java local: baixe
IniciarCalculadoraDeTributosSobreConsumo.jardo repositório do FW e o pacote "Java (JAR)" da página da calculadora; extraia ambos na pasta de trabalho. ComURL_API_CALCULADORAconfigurado, o FW inicia a calculadora automaticamente.
Se a URL estiver configurada e a calculadora não responder, a emissão retorna 996. Os tributos anteriores à RTC (ICMS, IPI, PIS, COFINS) continuam sob responsabilidade do AC durante a transição.
Logs
Arquivo diário invoicyfrmwrkAAAAMMDD.log na pasta de trabalho (ou em LOG_DIRETORIO), mantido por LOG_DIAS. Envie o log do dia ao suporte em qualquer ocorrência.
Atualização Automática
Disponível em Windows e Linux a partir da 01.50.00. O FW consulta periodicamente o InvoiCy e, se o parceiro tiver designado uma versão para a instalação, baixa, valida (checksum) e ativa a nova biblioteca — sem alterar o arquivo carregado pelo AC e, em geral, sem reiniciar o processo.
- A biblioteca carregada pelo AC (pai) nunca é substituída. A versão baixada (filho, ex.:
InvoiCyFramework_01_50_02.dll) é gravada no diretório de dados do FW e passa a atender todas as chamadas. - A versão é escolhida pelo parceiro no cadastro do InvoiCy; o FW apenas aplica.
char* InvoiCyFramework_GetModuleIdentity(); // JSON: papel (pai/filho), arquivo e versão em execução
GetModuleIdentityresponde qual versão está de fato atendendo.- Desligar:
ATUALIZACAO_AUTOMATICA=0interrompe as consultas e consequentemente as atualizações.