NFStock - Integração API NFStock - NF-Stock

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.

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.

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.

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.

Como realizar o upload de arquivos para a API

O processo de upload ocorre em duas etapas:

1. Realize a chamada do endpoint /storage enviando os dados básicos do arquivo, como seu tamanho e extensão.

2. 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.

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.