O que é a NS DDF-e API
A NS DDF-e API, ou Distribuidor de Documentos Fiscais Eletrônicos, é uma aplicação de integração por onde outras aplicações podem realizar o download e a manifestação de documentos eletrônicos.
Diferentemente das aplicações tradicionais, onde os dados dos documentos são enviados para a aplicação de integração através de arquivos TXTs ou banco de dados, com a NS DDF-e API os dados são enviados e recebidos através de requisições HTTPs que podem ser facilmente implementadas em qualquer linguagem de programação.
Uma API é uma aplicação que possui métodos consumíveis por outras aplicações, ou seja, é uma aplicação que possui métodos que podem ser acessados diretamente através do código de outras aplicações.
Dá-se o nome de Consumidora ou Cliente à aplicação que consome os métodos de uma API.
Padrão de comunicação
A URL base para todos os métodos da API é https://ddfe.ns.eti.br e o content-type esperado e devolvido será sempre JSON.
Em todas as requisições haverá sempre um campo status que indicará o resultado da operação seguindo o padrão de códigos utilizados pelo protocolo HTTP, sendo que códigos de erro estarão em forma negativa (ex.: -401, -404…). Sempre que o status for diferente de 200(OK), o retorno conterá também o campo motivo informando por escrito o erro ocorrido.
Exemplo de retorno 200:Retorno do login
{
"status": 200,
"ultNSU": "999",
"xml": "..."
}
Exemplo de retorno diferente de 200:Retorno do login
{
"status": -404,
"motivo": "'Username' ou 'Password' invalidos"
}
Limites de acesso
Por motivos de segurança e garantia de performance e instabilidade para todos os usuários do NS DDF-e API, a ferramenta possui um limite de 50 acessos por documento.
Como acesso, entende-se a requisição de um documento específico, seja de forma única ou em lotes.
Por exemplo, ao enviar para a API uma requisição de download único do documento com chave 1234, será contabilizado 1 acesso, permitindo assim que esse mesmo documento (chave 1234) possa ser requisitado outras 49 vezes.
Se a requisição realizada for para lote de documentos e no retorno forem devolvidos os documentos de chave 1234 e 5678, será contabilizado 1 acesso para cada documento, permitindo assim que cada um destes documentos possa ser requisitado outras 49 vezes.
Por padrão, percebe-se que a quantidade de acesso a documentos costuma ser igual a 1 e em raros casos chega a 2 ou 3 acessos. A NS disponibiliza a quantidade superestimada de 50 acessos por entender que em casos específicos pode haver a necessidade de uma quantidade maior de requisições e que é difícil determinar uma quantidade exata.
O descumprimento desta regra pode ocasionar bloqueios de acesso a NS DDF-e API pela licença solicitante (CNPJ interessado).