O que é e para que serve
A API de Integração NF-stock é uma solução desenvolvida para permitir que sistemas externos (que não sejam nativos da Alterdata) se comuniquem com o banco de dados do NF-Stock.
Seu objetivo principal é criar uma "ponte" para o tráfego de dados, permitindo tanto a busca quanto a importação de notas fiscais de forma automatizada.
Principais Cenários de Uso
As possibilidades de integração são vastas. Abaixo, listamos alguns exemplos de como softwares parceiros utilizam essa tecnologia:
- Emissores de Notas: Softwares de terceiros podem enviar automaticamente as notas emitidas para serem armazenadas e organizadas no NF-Stock.
- Sistemas de Escrita Fiscal: Permite o envio e recebimento de notas para apuração de impostos.
- Clientes que já utilizam o sistema fiscal da Alterdata (Pack ou Prosoft) não precisam dessa API, pois a integração é nativa.
- Business Intelligence (BI): Empresas conectam ferramentas de análise de dados para extrair informações do NF-Stock, gerando gráficos, relatórios e cenários financeiros estratégicos.
Clique aqui para conhecer nossos parceiros.
Não há cobrança adicional para o uso da API. O acesso é um benefício incluso para clientes que já possuem o NF-Stock.
Ponto de Atenção: Responsabilidades
É muito comum haver confusão sobre quem deve executar essa integração. Para esclarecer:
O contador não é o responsável técnico pela integração; ele apenas gera o token, e o desenvolvedor do sistema parceiro realiza o restante do trâmite.
Como funciona a integração
O processo de integração é técnico, mas a participação do contador é essencial nesse momento. Primeiro, é necessário que o contador gere o token no NF-Stock e envie ao desenvolvedor do software parceiro. Somente com esse código em mãos é que o programador poderá configurar o ambiente e concluir a integração.
Clique aqui para mais informações sobre como gerar o Token no NF-Stock. Este token é gerado de forma única, sem data de expiração.
Conheça melhor as duas APIs:
→ MS-Importação: Recebimento e Armazenamento de Documentos
Permite que os documentos fiscais do seu ERP (NF-e, NFC-e, CT-e, NFS-e, CFe/SAT, NFCom, NF3e) sejam enviados automaticamente para o NF-Stock.
Cada documento é armazenado em nuvem, garantindo centralização, segurança e eliminação do envio manual de notas fiscais.
→ MS-Exportação: Consulta e Busca Otimizada
Oferece uma maneira rápida e segura de consultar e baixar documentos fiscais (NF-e, NFC-e, CT-e, NFS-e, CFe/SAT, NFCom, NF3e) diretamente do NF-Stock.
Ideal para integrações que necessitam de acesso dinâmico e automatizado aos arquivos já armazenados.
Apesar do nome "MS-Exportação", este serviço não realiza a emissão ou envio de documentos, apenas a consulta e recuperação dos já existentes. Para consultar a documentação técnica, clique aqui.
No momento, visto que o NF-Stock trabalha exclusivamente com documentos fiscais válidos, não dispomos de um ambiente de homologação ou testes. As integrações são realizadas diretamente no ambiente de produção.
Como realizar o upload de arquivos para a API
O processo de upload ocorre em duas etapas:
- Realize a chamada do endpoint /storage enviando os dados básicos do arquivo, como seu tamanho e extensão.
- Este endpoint irá retornar uma URL. Utilizando os parâmetros e a URL obtida no passo anterior, realize uma requisição com o método PUT para concluir o upload do arquivo.
O arquivo deverá ser enviado logo após a transmissão e autorização do documento fiscal. Estes arquivos devem obrigatoriamente estar no formato de distribuição (<nfeProc>), contendo os dados das notas fiscais junto com o seu protocolo de autorização. Esse procedimento é válido e deve ser realizado para os seguintes modelos: NFe (Modelo 55) e NFCe (Modelo 65).
Limite e Volumetria
Para garantir a estabilidade do serviço, aplicam-se as seguintes regras de tráfego:
- Rate Limit: O limite de requisições é de 90 requests por minuto, podendo ser expandido conforme o status do servidor.
- Tamanho de Arquivo: O limite máximo por arquivo enviado é de 30 MB.
- Arquivos ZIP: É permitido o envio de pacotes ZIP com múltiplos XMLs, desde que respeitem o limite de 30 MB. Para volumes maiores, recomenda-se o fracionamento em múltiplos arquivos zipados até o limite permitido.
Fluxo de Upload e Confiabilidade
É preciso atentar-se ao tempo de vida das requisições e aos retornos do servidor:
- URL Pré-assinada: Tem validade de 30 minutos. Se expirar, uma nova URL deve ser gerada.
- Deduplicação: Caso um documento duplicado seja enviado, o serviço realiza a deduplicação nativa, evitando registros repetidos na base de dados.
- Status de Retorno: A política de retry pode ser definida de acordo com a sua regra de negócio, pois varia conforme a infraestrutura do seu lado ou do cliente. O endpoint retorna os seguintes status:
- 200: Sucesso.
- 400 (Bad Request): Erro nos dados de envio (verificar JSON).
- 401 (Unauthorized): Token incorreto ou revogado.
- Consulta de Processamento: A confirmação é automática. Para verificar o status, utilize o polling no endpoint:
https://ms-importacao-service-nfstock.alterdatasoftware.com.br/storage/arquivo/[GUID_RETORNADO_AO_SOLICITAR_A_URL_DE_UPLOAD]
Escopo de Documentos (NFS-e)
Devido às variações nas implementações municipais, o tratamento de Notas de Serviço segue critérios específicos:
- Validação de Schema: Não realizamos validações rigorosas de schema para NFS-e, pois muitas prefeituras não seguem fielmente os padrões XML.
- Padrões Suportados: Oferecemos suporte nativo aos padrões ABRASF e Padrão Nacional.
- Homologação: Para layouts próprios de prefeituras, verifique a lista de municípios homologados antes da integração. Você conferir, clique aqui.
Próximos Passos
- Você é Desenvolvedor? Se deseja integrar o seu software à nossa base, entre em contato para obter a documentação técnica.
- Você é Contador? Se deseja indicar um parceiro de software para realizar essa integração no seu cliente, solicite que ele entre em contato conosco através deste link.
