As APIs do Omie permitem realizar diversas operações no ERP. Com isso, você consegue integrar diferentes aplicativos, expandindo ainda mais as possibilidades.
Descubra como importar um Cupom Fiscal (NFC-e) contendo Serviços através da API! 🚀
⚠️ Atenção
A emissão de NFC-e Conjugada é uma prática específica, que depende da legislação de cada estado e Prefeitura. Conforme regulamentação estadual da maioria dos estados e Prefeituras, há casos onde se deve realizar a emissão de documentos fiscais para Serviços prestados separadamente, a partir da emissão de NFS-es. Consulte a sua contabilidade para confirmar a disponibilidade da prática em seu estado/Prefeitura.
Após a consulta da condição de sua Cidade, a importação de NFC-e de Serviço deve prosseguir conforme o status retornado. O status deve ser confirmado previamente a partir do método CidadesCupomConsultar.
Se "CONVENIADA", pode-se optar por qualquer um dos métodos indicados neste Artigo;
Se "HABILITADA", utilize o método "IncluirNfce" descrito neste Artigo;
Se "INDISPONIVEL", consulte o Suporte para verificar a possibilidade de integração.
É possível importar o arquivo do XML do Cupom Fiscal de Serviço emitido por sua empresa diretamente pelo Painel de NFC-e, CF-e SAT e Cupom Fiscal ECF.
Tópicos do Artigo
Informações importantes
Antes de iniciar seus testes com a nossa API, é fundamental conhecer alguns processos básicos:
✅ Acessando a documentação: Consulte nossa documentação oficial para entender os endpoints disponíveis e seus respectivos parâmetros.
🔑 Chaves de Integração da API: Saiba como obter e utilizar suas credenciais de acesso para autenticar as requisições.
⚙️ Características e Recomendações: Fique por dentro das melhores práticas para otimizar sua experiência com a API da Omie.
🔐 Login no Portal: Para testar suas requisições no Portal do Desenvolvedor é necessário fazer login na plataforma com o mesmo e-mail e senha que você já usa no ERP. Fácil, né? 😉
🧪 Aplicativo Teste: Aprenda a criar um Aplicativo Teste gratuito e descubra, na prática, como utilizar nossas APIs e aproveitar ao máximo os nossos recursos.
💡 Dica Omie: Você pode testar nossas APIs diretamente no nosso Portal do Desenvolvedor. Além disso, ferramentas como Postman, Insomnia e ThunderClient (extensão do VS Code) também são ótimas opções para realizar testes.
Importando o NFC-e de Serviço via ImportarNFCe
O código do Serviço, informado na tag cProd do XML do Cupom de Serviço deve ser igual ao Código do Serviço cadastrado no Omie.
Caso o seu Serviço não esteja cadastrado, confira este artigo:
1) Antes de iniciar o processo via API, é necessário conferir se o seu Serviço já se encontra cadastrado e configurado no Omie. Para isso, após realizar o login no Omie e acessar o seu aplicativo, acesse o módulo de Serviço:
2) Acesse o menu suspenso do módulo (1) e clique em "Exibir todos" (2), no grupo de opções de "Serviços":
3) Será apresentada a listagem de Serviços cadastrados. Localize o Serviço utilizado na venda do Cupom de Serviço e dê um duplo clique para acessá-lo:
4) Confira o Código utilizado para o Serviço (1), pois ele deve ser idêntico ao Código do Serviço do Cupom Fiscal.
Em seguida, confira as informações de tributação (2) e os Impostos preenchidos (3) na aba "Impostos:
Caso não estejam configurados, é necessário realizar a parametrização antes de prosseguir.
5) Com tudo certo no ERP, você pode prosseguir com a importação da NFC-e!
Para importar uma NFC-e de Serviço emitido a partir de uma Cidade com Status "CONVENIADA" ou "HABILITADA", será necessário utilizar o método "ImportarNFCe":
6) Você terá a seguinte requisição inicial:
{
"emiNome": "SeuPDV",
"emiVersao": "1.01.02",
"emiId": "PDV01",
"chNFe": "",
"nfceXml": "",
"nfceMd5": "",
"cAcaoCliente": "INCLUIR",
"idCliente": 0,
"idVendedor": 0,
"idProjeto": 0,
"idLocalEstoque": 0,
"cNaoMovEstoque": "N",
"cNaoGerarTitulo": "N",
"cIncluirProduto": "N"
}
Importante
As tags emiNome, emiVersao e emiId são referente ao aplicativo emissor de Cupom Fiscal, que deve ser previamente cadastrado no Omie. Para o cadastro prévio, entre em contato com nosso suporte. Ao final do credenciamento, os dados serão informados.
7) Para preencher os dados na requisição, é necessário realizar dois processos para a conversão do XML:
(1) Retire os acentos do arquivo XML: ^; ~; ´; `
(2) Converter o arquivo XML, trocando os caracteres especiais, tais como:
&== &<== <>== >'== '"== "|== |Remover:
\Sim... O "
;" faz parte da conversão, ele deve ser informado.
8) Com o arquivo convertido, preencha a informação na tag nfceXml.
9) Agora, é necessário gerar o MD5 do arquivo. Para isso, você pode utilizar qualquer site ou programa do seu interesse.
10) Com o hash do MD5 em mãos, informe na tag: nfceMd5.
11) As demais tags são de preenchimento opcional: "cAcaoCliente", "idCliente", "idVendedor", "idProjeto", "idLocalEstoque", "cNaoMovEstoque", "cNaoGerarTitulo", "IncluirProduto"
12) Com todas as tags preenchidas, envie a requisição! Com tudo certo, você terá o seguinte retorno:
{
cCodStatus: "0",
cDesStatus: "NFC-e adicionada com sucesso! Elapsed time: XXX", idCupom: XXXX,
idImportacao: XXXX,
idLote: XXXX
}
13) E pronto! Sua NFC-e de Serviço foi cadastrada com sucesso e estará disponível no sistema acessando o menu suspenso do módulo de "Vendas e NF-e", e clicando em "Painel de NFC-e, CF-e, SAT e Cupom Fiscal ECF":
💡 Ao acessar o seu Cupom Fiscal, será possível visualizar os Serviços na aba "Serviços":
Importando o NFC-e de Serviço via IncluirNfce
O código do Serviço, informado na tag nCodServ do XML do Cupom de Serviço deve ser igual ao ID interno do Serviço cadastrado no Omie.
Caso o seu Serviço não esteja cadastrado, confira este artigo:
1) Antes de iniciar o processo via API, é necessário conferir se o seu Serviço já se encontra cadastrado e configurado no Omie. Para isso, realize a consulta do ID do Serviço a partir das APIs ListarCadastroServico e ConsultarCadastroServico.
2) Para importar um NFC-e de Serviço emitido a partir de uma Cidade com Status "HABILITADA", será necessário utilizar o método "IncluirNfce":
3) Você terá a seguinte requisição inicial:
{
"NFe": {
"chNFe": "99999999999999999999999999999999999999999999",
"dEmi": "dd/mm/aaaa",
"det": [
{
"lCanc": false,
"lNaoMovEstoque": false,
"prod": {
"CFOP": "5405",
"NCM": "04061090",
"cEAN": "SEM GTIN",
"cProd": "325",
"cUn": "UN",
"nQuant": 1,
"vAcresc": 0,
"vDesc": 0,
"vItem": 15,
"vProd": 15,
"vUnit": 15,
"xProd": "REQUEIJAO CREMOSO 400GR MINAS MILK"
},
"prodIdent": {
"emiProduto": "325",
"idLocalEstoque": "1205784081",
"idProduto": 1208514897
},
"seqItem": 1
}
],
"hEmi": "08:24:01",
"lCanc": false,
"nNF": "000016064",
"serie": "002",
"total": {
"vAcresc": "0.00",
"vCF": "25.00",
"vDesc": "0.00",
"vICMS": "0.00",
"vItem": "25.00",
"vTaxa": 0,
"vTotTrib": 0
},
"tpAmb": "P",
"tpEmis": "1"
},
"caixa": {
"lCxAberto": false,
"seqCaixa": 710,
"seqCupom": 1012303
},
"cupomIdent": {
"idCliente": 120834285,
"idProjeto": 0,
"idVendedor": 0
},
"emissor": {
"emiId": "0001",
"emiNome": "SEU_PDV",
"emiSerial": "WD-WXS1A499REDFTB58F00D65",
"emiVersao": "1.9.00"
},
"formasPag": [
{
"Parcelas": [
{
"dVenc": "dd/mm/aaaa",
"nParc": "001/001",
"vParc": 25
}
],
"TEF": {
"NSU": "",
"cBandeiraTef": "",
"cRedeTef": "Outros",
"cTipoCartao": "",
"nNumeroAut": "",
"nParcTef": 0,
"nValorAut": 25
},
"lCanc": false,
"lNaoGerarTitulo": false,
"pag": {
"pTaxa": 0,
"vLiq": 25,
"vPag": 25,
"vTaxa": 0,
"vTroco": 0
},
"pagIdent": {
"cCategoria": "1.01.03",
"cTipoPag": "CRT",
"idConta": 1298842804
},
"seqPag": 1
}
],
"nfce": {
"nfceMd5": "754d4c0594e4ebcbcf7fdd75547f9d7d",
"nfceProt": "999999999999999",
"nfceXml": "SEU_XML"
}
}
4) Para preencher os dados na requisição, é necessário realizar dois processos para a conversão do XML:
(1) Retire os acentos do arquivo XML: ^; ~; ´; `
(2) Converter o arquivo XML, trocando os caracteres especiais, tais como:
&== &<== <>== >'== '"== "|== |Remover:
\Sim... O "
;" faz parte da conversão, ele deve ser informado.
5) Com o arquivo convertido, preencha a informação na tag nfceXml.
6) Agora, é necessário gerar o MD5 do arquivo. Para isso, você pode utilizar qualquer site ou programa do seu interesse.
7) Com o hash do MD5 em mãos, informe na tag: nfceMd5.
8) Atente-se para as tags de preenchimento opcional, como: "lNaoMovEstoque", "lNaoGerarTitulo",. Realize, também, o preenchimento da array "servicos", onde os itens de Serviços serão indicados, como no exemplo abaixo:
"servicos": [
{
"nCodServ": 2902957,
"nItem": 1,
"nQtde": 3,
"nValorUni": 2,
"nValorTot": 6,
"cMunFG": "3550308"
},
{
"nCodServ": 2902957,
"nItem": 2,
"nQtde": 1,
"nValorUni": 2,
"nValorTot": 2,
"cMunFG": "3550308"
}
9) Com todas as tags preenchidas, envie a requisição! Com tudo certo, você terá o seguinte retorno:
{
cCodStatus: "0",
cDesStatus: "NFC-e adicionada com sucesso! Elapsed time: XXX", idCupom: XXXX,
idImportacao: XXXX,
idLote: XXXX
}
10) E pronto! Sua NFC-e de Serviço foi cadastrada com sucesso e estará disponível no sistema acessando o menu suspenso do módulo de "Vendas e NF-e", e clicando em "Painel de NFC-e, CF-e, SAT e Cupom Fiscal ECF":
💡 Ao acessar o seu Cupom Fiscal, será possível visualizar os Serviços na aba "Serviços":
12) Para cidades com status igual a "HABILITADA" no método CidadesCupomConsultar, haverá a execução de uma rotina automática ao final do dia para tratamento dos serviços vendidos via Cupom Fiscal, onde os Serviços serão faturados a partir de Ordens de Serviços para a emissão de NFS-es.
📚 Artigos Relacionados
