A API DiginotaNFE, é RestFul e todos os retornos serão realizados no formato JSON.
A API utiliza a autenticação (JSON Web Token – Bearer Token), o JWT é um padrão de segurança e sua boa pratica visa o acesso seguro a API e não expira no ambiente de testes.

Detalhes Json Web Token: JWT

Liberação do Ambiente de testes e produção:

Para iniciar os testes de integração da API DigiNota, após o contato com o setor comercial e a aprovação do contrato, o suporte técnico irá liberar a URL e a chave token de autenticação de homologação, possibilitando assim utilizar os métodos descritos nesta documentação. Após os testes e a implementação, será liberado também pelo suporte técnico a URL e a chave token em ambiente de produção.

Chave Bearer Token:

Os tokens em ambiente de produção serão únicos para cada usuário, identificados pelo CNPJ, afim de garantir a privacidade e segurança de cada usuário. Eles também são imutáveis, uma vez que cada token irá garantir a identificação de cada sistema e seus respectivos dados inseridos.

• Métodos Utilizados
• Preenchendo os Campos da NF

O método utilizado traz todos os campos a serem pertinentes a uma emissão de uma NF, separados por blocos específicos de informações:

Porém alguns campos são preenchidos após a execução da chamada e não precisam ser enviados na requisição do JSON, são eles:

“owner”: “string”,

  “numeroNF”: 0,

Juntamente com esses campos, a chamada irá retornar link da visualização do pdf e o guid identificador único da nota fiscal.

A chamada também irá retornar se a emissão da Nf foi feita com sucesso e se é uma NF válida ou não, conforme imagem demonstrada abaixo:

O cadastro de um cliente deve obedecer ao mesmo preenchimento do Emitente, com preenchimento obrigatório para os seguintes campos:

• razaoSocial; Denominação ou nome do destinatário ou tomador do serviço. (Tamanho máximo do campo: 35 caracteres).

• cnpjcpf;
• ierg; O campo Inscrição Estadual/RG pode ou não conter a numeração. Para os casos de não conter (isentos), o campo será preenchido com a expressão ‘ISENTO’             (Tamanho máximo do campo: 14 caracteres).
• telefone; O campo telefone obrigatoriamente tem que ser preenchido com 10 ou 11 caracteres no formato exemplo: 1938033223
• Email; O campo Email é obrigatório.
• tipoCliente; A seleção do tipo de cliente está relacionada diretamente com o campo CFOP no cadastro.
  Por exemplo, para uma CFOP (5303 – comercial) o tipo de cliente utilizado geralmente será o 1- Comercial

• Endereço completo com:

  logradouro;

  município;

  uf;

  cep;

  codigoMunicipio; A API trabalha com a validação do CEP e dos Municípios brasileiros seguindo a tabela do IBGE, que pode ser consultada no item 8.1.
  Para que a validação ocorra, basta preencher o codigo Municipio de acordo com a tabela do IBGE (Instituto Brasileiro de Geografia e Estatística). O código possui 7 dígitos. 

  codigoIdentificação; Código único de identificação do consumidor ou assinante do serviço prestado.

• Identificador; Código utilizado na emissão e atualização das notas, se tornando um identificador único para cada nota. Pode ser utilizado o número do boleto do cliente referente a nota ou qualquer outro ID que possa identificar aquela nota especificamente.

  Este ID irá auxiliar a API nas requisições, identificando cada nota emitida ou editada, para que não ocorra uma emissão duplicada de notas fiscais, em caso de duas ou mais requisições simultâneas ocorrerem para cada nota, por exemplo.
  Essas requisições podem não retornar devido a uma perda na conexão, ocasionando em uma segunda tentativa de envio da nota, o que pode gerar duplicidade na emissão. Portanto, o código identificador irá prevenir esta emissão em duplicidade, uma vez que a API irá reconhecer qual nota está sendo emitida.

O Campo ‘Responsável’ não é de preenchimento obrigatório. Ele funciona como o campo de “Aos Cuidados de” em uma Nota Fiscal e, caso seja preenchido, os mesmos campos obrigatórios necessários para um cadastro de um emitente ou um cliente deverão ser preenchidos conforme figura demonstrada abaixo:

Utilizando o mesmo método para emissão de notas (POST /V1/Invoice), os campos a serem preenchidos para acrescentar um item na nota são os seguintes:

• codigoitem; Código identificador único de cada item/serviço.
• descricaoitem; Informação que apareça no corpo da nota com a descrição do item.
• unidade; Informa o tipo de unidade do item. Para as notas modelo 21/22 utilizar “Serv”.
• quantidadeContrada; Preencher 1.
• quantidadeFornecida; Preencher 1.
• quantidadeFaturada; Preencher 1.
• valorUnit; Valor de cada item/serviço.
• aliquotaICMS; Preencher alíquota (em porcentagem %) de ICMS do item.
• reducao; Alíquota de redução de ICMS (em porcentagem %) do item
• aliquotaPIS; Preencher alíquota (em porcentagem %) de PIS do item.
• aliquotaCOFINS; Preencher alíquota (em porcentagem %) de COFINS do item.
• aliqValorTribFederais; Preencher alíquota (em porcentagem %) dos Tributos Federais do item.
• aliqValorTribEstaduais; Preencher alíquota (em porcentagem %) dos Tributos Estaduais do item.
• aliqValorTribMunicipais; Preencher alíquota (em porcentagem %) dos Tributos Municipais do item.
• desconto; Valor do desconto a ser aplicado no item.
• outrosValores; Outros valores do item a serem destacados na nota.
• infoAdicional; Observação/Informações adicionais do item.

Os serviços de notas modelo 21/22, podem ter os seguintes tipos de tributação:

• Tributação de ICMS

Utilizando o campo “Alíquota ICMS” para incluir o percentual de ICMS e o campo “Redução”, caso a base de cálculo para o ICMS não seja o valor total do item;

• Alíquota de PIS – Inclusa em percentual;
• Alíquota de COFINS – Inclusa em percentual
• Tributos federais, estaduais e municipais – Alíquota aproximada de tributos, inclusas em percentual;

Existem também casos em que a nota não terá tributação apontada. Para estes casos, as opções serão:

• Campo “Outros” – Valor total do item será classificado como Outros valores;
• Isento – O não preenchimento dos campos de alíquota ou outros, acarreta automaticamente na adição do valor em Isento, campo não presente na API.

Também na inclusão de um serviço, é necessário o apontamento do código de classificação do mesmo.

Após selecionar o ‘tipo Utilização’ é necessário apontar o tipo de serviço prestado no campo ‘codigoClassificacao’ para que a remessa seja validada pela Sefaz.

Para verificar em qual código o serviço prestado se encaixa é necessário consultar Tabela de Classificação do Item do documento Fiscal no Convênio 115/03 através do item 8.2.

• CFOP – Natureza de Operação da nota (4 caracteres)

• Serie

Representa a série do documento fiscal. Caso a série seja única, basta utilizar a letra U para indicar;

• incideBC – Incide base de cálculo

Identifica se vai ser realizado os cálculos dos valores das Alíquotas informadas. Alíquota ICMS ou Alíquota de Redução do ICMS caso exista.

É sinalizado por True ou False.

True: o sistema faz os cálculos dos valores da Base de Cálculo do ICMS pela alíquota ICMS informada na nota fiscal e a Redução da base de cálculo conforme alíquota redução informada.

False: todos valores de Tributos serão 0.00 e automaticamente o valor total da nota ficará como “Isentos”

• CFOP – Código Fiscal de Operações e Prestação
• Modelo – Modelo da Nota Fiscal a ser emitida
  Exemplo: 21 Comunicação, 22 Telecomunicação, 99 Fatura
• tipoUtilizacao – Tipo de Utilização da NF
  Exemplo: 1 – Telefonia, 2 – Comunicação de dados, 3 – TV por Assinatura, etc

• O campo “nfInicial” vem como padrão “0”, isso significa que a primeira nota fiscal gerada tanto do modelo 21, quanto do 22 será de numeração 1, caso o número inicial seja outro, o campo deve ser preenchido com o referido número.

• Métodos Utilizados

Para emitir notas fiscais em lote, os campos necessários para preenchimento são os mesmos utilizados para uma emissão avulsa, com a diferença que o objeto aceitará diversas notas pertencentes ao lote e de que será necessário o preenchimento de um novo campo obrigatório determinado ‘idIntegração’ que servirá como validador para eventuais erros.

Após o envio do lote, caso todos os parâmetros estejam corretos, será retornada uma mensagem contendo o Status da geração daquele lote, bem como o Id e a quantidade de Nf enviadas, conforme demonstrado abaixo:

• Para consultar o status da emissão de um lote, o método utilizado é o /v1/Invoice/Batch/Search/{id} onde será necessário utilizar o ID gerado na emissão em lote para a consulta.

Após a busca pelo ID do lote e execução da chamada, a API retornará o Status da emissão conforme demonstrado abaixo:

O Status atual será mostrado, bem como uma mensagem caso tenha sido gerado com sucesso e outras informações como o período da emissão, e a quantidade de NF de cada modelo.

• Métodos Utilizados

Após emitir uma ou mais notas fiscais a consulta delas poderá ser feita através do método /v1/Invoice/ {owner} inserindo o Guid identificador que foi gerado ao emitir a NF previamente.

Através do método é possível visualizar todas as informações da NF e utilizar o corpo da NF para uma possível edição caso necessário.

Também é possível consultar as notas fiscais geradas em um período específico ao filtrar pela data de emissão e/ou de um modelo através do método abaixo:

Para que a listagem de notas de um determinado período seja exibida, os filtros ‘inicio’ e ‘fim’ devem ser obrigatoriamente preenchidos. Caso queira uma busca mais detalhada, os outros filtros podem ser utilizados na busca, como por exemplo o modelo da NF.

É importante lembrar que os filtros de data obedecem um padrão onde são inseridos primeiramente o ano, depois o mês e por último o dia conforme exemplificado abaixo.

{

  “inicio”: “2021-03-09T17:36:44.014Z”,

  “fim”: “2021-09-09T17:36:44.014Z”,

}

Após a filtragem, uma listagem de NF obedecendo o padrão de filtragem irá aparecer e nelas as informações principais da NF serão exibidas:

É através desse método de busca que podemos consultar a Guid de uma NF e realizar uma busca mais detalhada utilizando o primeiro método de busca informado.

Também como resposta da busca e filtros utilizados, o método apresenta a quantidade de itens por página (que por padrão são 50, caso o filtro não seja preenchido), a página atual exibida (caso não seja selecionado nenhuma em específico, sempre será exibida a primeira), a quantidade de NF dentro do período de busca e o total de páginas dentro daquela busca.

• Métodos Utilizados

Para atualizar uma Nota Fiscal que já foi gerada o método utilizado é o destacado abaixo:

• Editando as Informações da Nota Fiscal

Após gerar uma Nota fiscal, caso seja necessária a atualização de algum dado, o body da nota que pode ser consultado e pego através do método /v1/Invoice/ {owner} deve ser inserido e os dados a serem atualizados ou acrescentados devem ser preenchidos obedecendo à mesma regra de preenchimento de um cadastro de uma nova nota fiscal, onde os campos obrigatórios permanecem sendo os mesmos.

Ao alterar as informações necessárias de maneira correta, uma mensagem de sucesso semelhante à exibida quando a NF foi criada será exibida contendo a Guid daquela Nf, o link para o PDF e o número da NF para consulta.

É importante ressaltar que alguns dados como, numeroNF e diaVencimento, para o caso de datas menores que o dia atual, não devem ser alterados pois a resposta será recebida com erro. Para testes onde o resultado esperado seja um erro, essas informações poderão ser alteradas livremente.

Importante: O campo “Identificador” deve ser retirado da requisição do JSON. Caso contrário, a requisição irá somente buscar a nota já emitida com aquele ID.

Para cancelar uma nota fiscal já gerada ao editar as informações da NF deixe o campo “cancelado”: true; conforme imagem demonstrada abaixo.

• Método Utilizado

• Gerando uma Remessa

A remessa é um lote que compreende todas as emissões realizadas no mês e que irá passar por um processo de validação e envio para a Receita Federal com a finalidade de autenticar as emissões de notas fiscais daquele mês.

Após a geração de todas as notas de um mês, iniciando-se a contagem pela data de emissão, é gerada a remessa mensal para a validação/envio para no Sefaz.

Para que isso seja possível é necessário preencher os dados solicitados, lembrando que uma remessa somente será criada para um mês que hajam notas fiscais geradas, estando elas canceladas ou não

• Pontos importantes a serem ressaltados:

  Caso uma remessa já tenha sido gerada para o mês especificado, a API retornará uma mensagem avisando juntamente do link de download da remessa já emitida:

  A primeira remessa gerada em um mês sempre terá como padrão o status “Normal”;

• A partir do momento da criação da remessa, não se pode criar ou editar mais notas dentro do mês vigente, ou seja, caso tenha sido criada uma remessa para o mês de outubro/2020, esse mês não receberá mais notas fiscais e não será possível a edição das já existentes;

Caso for necessária a edição ou cancelamento de uma nota, é necessário cancelar a remessa tipo Normal gerada para aquele mês através do seguinte método:

O cancelamento de remessas atualmente é executado por nosso suporte técnico (usuário administrador) para evitar cancelamentos incorretos.

Após o cancelamento, é possível fazer todas alterações necessárias, como edição, inclusão ou cancelamento de alguma nota fiscal utilizando os outros métodos normalmente.

Com as alterações feitas há duas possibilidades ao gerar uma nova remessa.

1 – Uma nova remessa do tipo normal, caso a remessa não tenha sido validada pela Sefaz ou;

2 – Caso a remessa já tenha passado pelo processo de validação e envio para a Sefaz, a nova remessa deverá ser gerada de forma Substituta;

Essa validação acontece na substituição do status ao gerar uma remessa que ao invés de ir com o padrão “Normal” deve ser substituído por “Substituto”.

• Métodos Utilizados

A consulta deverá ser realizada preenchendo os campos solicitados pelo método e o retorno será o impresso da nota fiscal que foi solicitada através do guid.

• -Sobre o Convênio ICMS 115/03:

  Confaz (Legislação)

  Anexo único

  Antes de iniciar a emissão das notas via API, é necessário verificar alguns dados que serão utilizados para criação das notas:

  – CFOPs utilizadas (5.301, 5.302, 5.303, 5.304, 5.305, 5.306, 5.307 sendo estas intra-estaduais. Se iniciadas em 6, interestaduais e a CFOP 7.301, para cliente estrangeiro).

  – Data de emissão: A emissão das notas deve ser sempre realizada em datas crescentes, dando preferência por emitir as notas com a data do dia vigente (atual).

  – Modelo de nota fiscal: (Modelo 21 – Comunicação, Modelo 22 – Telecomunicação ou Modelo 99 – Nota fatura)

  – Tipos de utilização (referente ao tipo de serviço prestado):

  1 – Telefonia

  2 – Comunicação de dados

  3 – TV por Assinatura

  4 – Provimento de acesso à Internet

  5 – Multimídia

  6 – Outros

  -Sobre os Códigos de classificação dos serviços:

  Cada tipo de prestação de serviço para o Convênio ICMS 115/03, possui um código de classificação de três dígitos.

  – Sobre a emissão para cliente estrangeiro:

  Para emissão de notas para cliente estrangeiro, os dados devem ser preenchidos da seguinte forma:

  Município: EXTERIOR/ UF: EX/ CEP: 00000000/ Cnpj: 9999999999999

  Os outros campos de endereço devem ser inseridos no formato padrão para clientes Brasileiros.

  – Sobre a validação e envio da remessa mensal:

  Alguns campos de cadastro devem ter atenção especial, para que não gerem erros na validação da remessa mensal de notas:

  Logradouro – Não deve conter menos de três dígitos.

  Número – Inserir apenas caracteres numéricos.

  Município – Deve constar no formato de escrita federativo do IBGE (Exemplo: “São Paulo” é a forma correta e não “SÃO PAULO”).

  Código IBGE – Deve ser inserido o código da cidade, com sete caracteres numéricos.

  IE/RG – Caso não possua, preencher como “ISENTO”.

  Telefone – Padrão brasileiro com DDD + dez ou onze dígitos, não podendo se iniciar em zero ou sequências do número 1 (00-00000000, 11-111111111).

  Tipo de utilização e Classificação do serviço – O tipo de utilização (1, 2, 3, 4, 5 ou 6) é relacionado ao tipo de serviço prestado. Sendo assim, o código de classificação fiscal do item, deve ser incluso conforme o mesmo padrão (Exemplo incorreto: Tipo de utilização 1 – Telefonia com Código de Classificação Fiscal 0104 – Assinatura de Serviços de Provimento à internet não é uma combinação coerente)

  Tributações / Isenções do item – A API possui as opções de “incideBC”, preenchida com “true” ou “false” e “outrosValores”. Caso nenhuma delas for preenchida, a nota será emitida com valores em “Isentos”. Ao optar por utilizar o “incideBC”, o campo de “outrosValores” só poderá ser utilizado se houver preenchimento de redução da alíquota (“reducao”).  Caso contrário, o campo deverá ficar zerado. Se houver redução, optando por dividir o valor em BC e Isentos, preencher “incideBC” como true e incluir a redução da base de cálculo em “reducao”, manter o campo “outrosValores” zerado.

-Sobre a conexão de dados, requisições e retornos:
A API irá retornar os status de cada requisição com base nos dados inseridos, nos processamentos executados e nas conexões estabelecidas.
Quando uma requisição for recebida e processada corretamente (200 – Ok), sem erros, será retornado “success: true” e os dados imputados serão mostrados já processados.

Caso ocorra algum erro por conta de dados inseridos fora do padrão exigido pela aplicação (400 – Bad Request), será retornado “success: false” juntamente com a mensagem de erro, informando o que foi inserido incorretamente, por exemplo.

As requisições podem levar um tempo maior para processamento dependendo da alta quantidade de dados a serem processados e retornados pela API. Para estes casos, a API retornará Connection Timeout, 500 – Server Error ou vazio, dependendo do caso. Portanto o usuário deverá realizar novas tentativas de requisições, não ultrapassando o limite de 5 tentativas.

Para casos em que a conexão for interrompida, a API não retornará dados, sendo necessário o usuário verificar as suas conexões e fazer até no máximo entre 3 e 5 tentativas de envio. Se a requisição for feita pelo método POST /v1/Invoice e o campo Identificador estiver preenchido, uma nova requisição pode ser feita, pois não ocorrerá duplicidade na emissão da nota fiscal, reenviando até no máximo de 3 a 5 tentativas de requisições.

O suporte técnico estará disponível também para avaliar e entender os motivos para que uma requisição não seja processada ou retornada, averiguando se esse retorno ocorreu por conta de dados inseridos fora do padrão exigido pela aplicação, falha na conexão, processamento em segundo plano ou qualquer outro erro ou falha que possa ocorrer, podendo assim auxiliar e orientar de forma eficiente.

A emissão das notas deve ser sempre realizada em datas crescentes, dando preferência por emitir as notas com a data do dia vigente (atual). Lembrando que o campo considerado seria o de “dataEmissao” e não “dataPrestacao” (que pode ser preenchido conforme necessitar).

Uma das regras da API vai impedir a emissão de notas retroativas de um mês para outro. Por exemplo, se já existirem notas emitidas para o mês de janeiro e forem iniciadas as emissões de fevereiro, ao ocorrer uma tentativa de emissão para janeiro (mês retroativo), a API irá bloquear a emissão, mostrando a mensagem abaixo:

Portanto, se deve ficar atento para as emissões seguirem estas regras, a fim de não quebrar a sequência numérica das notas, uma vez que a numeração segue a ordem crescente das datas de emissões.