nf-stock - Integração API 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.

Acesse a documentação técnica de como realizar essa integração → clicando aqui


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.

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:

  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.


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


Onde localizo o Código CRM para realizar a integração via API com o nf-stock?

É possível identificar o Código CRM seguindo este caminho no sistema:

  • Vá em Configurações

  • Clique em Opções de Contas

  • Selecione Dados

  • Localize o campo Código CRM

 

A autenticação da API exige que o código tenha exatamente 6 dígitos. Caso o seu código seja menor, preencha com zeros à esquerda. Por exemplo, se o seu número for 123, você deve inserir 000123.



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.


Dúvidas Frequentes

  • Pergunta: Existe um endpoint específico na API de exportação para obter apenas documentos CTe ou NFSe?
  • Resposta: Ainda não há um endpoint disponível especificamente para CTe ou NFSe. Atualmente, os endpoints específicos são apenas para NFe e NFCe. No entanto, é possível utilizar o endpoint api/v1/crm/cnpj/documentos/0/novos, que permite obter todos os modelos de documentos consultando por NSU.
  • Pergunta: Quais os valores corretos a serem preenchidos no parâmetro "Tipo" (ex: se eu quiser filtrar apenas notas recebidas)?
  • Resposta: Os valores aceitos para o parâmetro "Tipo" são: Emitidas, Recebidas e Todas. Para buscar somente as recebidas, basta passar a palavra Recebidas.
  • Pergunta: É possível testar a URI da API colando o link diretamente no navegador?
  • Resposta: Não. Não é possível testar direto no navegador porque as requisições da API exigem autenticação.
  • Pergunta: Como funciona a busca no endpoint api/v1/crm/cnpj/documentos/{nsu}/novos? Se eu fizer uma requisição e ele trouxer 10 notas, a próxima requisição trará as mesmas notas?
  • Resposta: A premissa desse endpoint é de uma consulta sequencial. Se você consultar passando o NSU 0 e a API retornar 10 notas (onde a última tem o NSU 55, por exemplo), a sua próxima consulta deverá ser passando o NSU 55. Dessa forma, os 10 documentos entregues anteriormente não virão mais. Se você desejar que eles permaneçam sendo entregues, deve manter sempre o NSU 0 na requisição (lembrando que este endpoint tem a limitação de entrega de documentos apenas dos últimos 90 dias).
  • Pergunta: Para criar uma rotina de busca (ex: a cada 60 minutos), devo guardar o NSU do último documento e enviar ele mesmo na próxima requisição, ou devo enviar o valor dele "+ 1"?
  • Resposta: Você deve guardar o último NSU recebido e enviá-lo exatamente como está na próxima requisição. A própria API se encarrega de retornar apenas os documentos com NSU estritamente maior que esse valor enviado.


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.


api token nf-stock? como conseguir token api nf-stock? token nf-stock? api integração nf-stock?