Este artigo orienta desenvolvedores e gestores sobre o funcionamento das APIs (1.0 e 2.0), as estruturas disponíveis e os passos para iniciar a sua integração.
A partir de junho de 2026, a Qive disponibiliza a sua API 2.0, projetada especificamente para entregar alta performance e eficiência técnica no processamento de grandes volumes de dados. A nova arquitetura otimiza o consumo de banda e reduz o tempo de resposta através de requisições estruturadas via POST e payloads em formato JSON.
O que é preciso para utilizar a API Qive?
A nossa API está disponível para todas as empresas e escritórios contábeis que desejam automatizar fluxos integrados. Para utilizá-la, considere os seguintes pontos:
Responsabilidade técnica: O desenvolvimento, codificação e manutenção da integração são de responsabilidade do cliente. É indispensável validar previamente com a sua equipe de TI ou parceiro de desenvolvimento se você possui a estrutura necessária para implementar o projeto.
Disponibilidade de histórico: A API Qive opera a partir do fluxo de documentos consultados ou importados após a liberação do ambiente de produção. Ela não realiza a busca retroativa de notas anteriores à contratação do serviço.
Ativação de novos CNPJs: Caso a sua empresa adicione novas empresas (CNPJs) na plataforma Qive, a liberação desses acessos para a API deve ser solicitada ao nosso time para configuração manual.
Comercial e Precificação: O uso da API segue uma precificação específica baseada no volume de documentos operados. Para solicitar uma proposta parametrizada para o seu negócio, entre em contato via
suporte@arquivei.com.brou pelo chat interno da plataforma.
Como funciona a arquitetura da API Qive?
A Qive opera com duas versões de API de forma simultânea e complementar para garantir a robustez do ecossistema de Gestão de Documentos:
Padrão REST: Ambas as versões utilizam o padrão de mercado REST, o que assegura compatibilidade com qualquer linguagem de programação moderna e agilidade na curva de desenvolvimento.
API 2.0 (Busca e performance): Desenvolvida com foco em eficiência de dados. Ela substitui o modelo antigo de rotas
GETcom parâmetros longos na URL por requisiçõesPOSTcentralizadas em payloadsJSON. Esse modelo traz duas grandes vantagens práticas:Busca por projeção: O desenvolvedor define estritamente quais campos quer receber através do array
fields(ex: apenas a chave de acesso e o status). Se o XML completo não for solicitado, a API não o envia, reduzindo drasticamente o consumo de banda.Busca por documento completo: Para obter o conteúdo do documento, basta declarar no
fieldso parâmetroXML(para o arquivo bruto) oudocument(para o formato JSON), podendo inclusive retornar ambos na mesma chamada.
API 1.0 (Operações e utilitários): Operações que envolvem ações específicas de escrita ou ferramentas adicionais continuam rodando de forma estável na versão 1.0.
Quais endpoints e documentos estão disponíveis?
A estrutura de endpoints está dividida de forma clara e limpa conforme o objetivo da sua aplicação:
Busca de Documentos Fiscais (API 2.0)
Endpoints unificados e otimizados para a entrega de dados estruturados em lote:
Endpoint | Objetivo | Documento Fiscal |
| Consulta de Notas de Produto | NF-e |
| Consulta de Conhecimentos de Transporte | CT-e |
| Consulta de Notas de Serviço | NFS-e |
Operações, Envio e Utilitários (API 1.0)
Rotas independentes dedicadas a ações operacionais e downloads de arquivos de visualização:
Manifestação do Destinatário: Envio de eventos de manifestação de NF-e em lote.
Upload de Arquivos: Envio manual ou automatizado de arquivos XML para a plataforma.
Serviço de OCR: Envio e leitura de NFS-e por Reconhecimento Ótico de Caracteres.
Downloads em PDF: Geração de arquivos visuais de conferência, como DANFe, DACTe e DACTe-OS.
Gerenciamento de Metadados: Aplicação de marcadores e Tags Customizadas (
properties).
Como utilizar os novos filtros inteligentes (API 2.0)
A inteligência da API 2.0 reside na granularidade dos seus filtros aplicados diretamente no corpo (body) da requisição JSON. Os principais parâmetros de controle são:
Papel do CNPJ (
OwnerRoles): Permite filtrar se a sua empresa deseja receber apenas os documentos onde ela atua como destinatária/tomadora (received) ou como emissora (emitted).Data de Emissão (
EmissionDate): Filtro de alta precisão que aceita as propriedadesFrom(De) eTo(Até) no formatoAAAA-MM-DD HH:MM:SS. Isso possibilita capturar atualizações ocorridas há poucos minutos e evita lacunas diárias na escrituração.Status do Documento (
Status): Evita o processamento desnecessário no banco de dados do cliente. É possível filtrar o retorno diretamente por notas autorizadas (authorized) — prontas para a escrituração contábil — ou canceladas (canceled).Paginação Saudável (
Limit): Controla o volume de dados por chamada. O limite recomendado é de até 100 registros por bloco, mantendo as filas de processamento dos sistemas internos leves e constantes.
Passo a passo para iniciar o desenvolvimento
Siga estas etapas para integrar o seu sistema ao ecossistema de dados da Qive:
Acesse a documentação técnica: Reúna a sua equipe de engenharia e acesse o portal de desenvolvedores em developers.qive.com.br para conhecer os esquemas de dados, payloads e modelos de requisição.
Utilize o ambiente de testes (Sandbox): Antes de colocar a integração em produção, solicite as credenciais do ambiente Sandbox https://developers.qive.com.br/sandbox. Ele fornece notas com dados fictícios (sem valor jurídico), permitindo testar as respostas da API, o tratamento de erros e a conversão de dados de forma totalmente segura.
Obtenha suas credenciais: Após validar os testes, a nossa equipe emitirá o seu ID de Usuário e a sua Chave Secreta (Client Secret). Esses dados realizam a autenticação de segurança de todas as chamadas realizadas.
Dúvidas frequentes (FAQ)
Como as alterações e cancelamentos de notas são atualizados na API?
Para NF-e e CT-e: Todo evento legal ocorrido após a primeira consulta (como o cancelamento) é vinculado à chave de acesso correspondente. O arquivo é atualizado na base da Qive, mantendo apenas um XML contendo os novos status e eventos consolidados.
Para NFS-e (Notas de Serviço): O motor de consulta realiza a varredura nas prefeituras duas vezes ao dia, porém não faz buscas retroativas por padrão. Se uma nota de serviço for consultada e, posteriormente, sofrer um cancelamento na prefeitura, essa alteração não será retroagida automaticamente na nota já armazenada. Caso o cancelamento ocorra no intervalo exato entre a emissão e a nossa primeira captura, o documento já entrará no sistema com o status atualizado.
Nota: Nosso time de engenharia está finalizando melhorias estruturais para que a consulta de NFS-e passe a seguir o mesmo modelo retroativo automático da NF-e e CT-e em breve.
Se eu for autorizado em uma NF-e, receberei também o CT-e correspondente de forma automática?
Não. Tratam-se de Documentos Fiscais Eletrônicos (DFes) com naturezas e estruturas de arquivos distintas. A consulta de um arquivo não dispara o retorno do outro; cada um deve ser requisitado em seu respectivo endpoint (/nfe ou /cte).
Para todo evento é gerada uma nova nota ou o evento é registrado no documento original?
Quando um novo evento legal ocorre (como uma Carta de Correção), é gerado um XML de evento específico. A Qive consolida essa informação associando-a à chave de acesso original. Tecnicamente, o arquivo sofre uma atualização estrutural de dados, mantendo a mesma chave identificadora.
Como funciona o filtro created_at e qual a diferença para a data de emissão?
O filtro created_at analisa exclusivamente o momento em que o documento fiscal deu entrada na estrutura do banco de dados da Qive (data de captura ou importação), e não quando a nota foi emitida pelo fornecedor. Para utilizá-lo, deve-se aplicar o formato composto contendo obrigatoriamente a estrutura created_at[from] e created_at[to] com data e hora completas (AAAA-MM-DD HH:MM:SS).
Como os dados do XML são transmitidos e decodificados na API?
Para otimização e redução do tamanho dos pacotes de transmissão de dados, as strings dos XMLs retornadas pela API são codificadas em formato Base64. Para ler as informações detalhadas da nota, o seu sistema interno deve apenas aplicar uma função de conversão padrão de Base64 para texto XML.
Existe suporte para Webhooks para notificar novas notas capturadas?
Atualmente, a API Qive não dispõe de arquitetura de Webhooks. O controle de novos documentos deve ser feito de maneira programática através de chamadas estruturadas de consulta aos nossos endpoints usando os filtros de período e paginação.
Como identificar uma nota de forma única sem precisar decodificar o Base64?
No retorno padrão de dados da API, disponibilizamos de forma aberta a Chave de Acesso do documento (que funciona como o ID único nacional da nota). Além disso, o nó da resposta contém o campo cursor, que serve como o identificador posicional exclusivo daquela nota na sua fila de leitura.
Como gerenciar usuários dentro da estrutura da API?
A API Qive não utiliza o conceito de gerenciamento de usuários individuais. O acesso é autenticado globalmente por meio do ID e da Chave Secreta gerados na contratação. Essas credenciais dão acesso total a todos os documentos fiscais disponíveis para a conta contratada.
A API Qive pode ser disponibilizada para parceiros ou sistemas de terceiros?
Sim. É possível conceder acesso controlado a parceiros externos sem a necessidade de expor ou compartilhar o seu ID e Chave Secreta principais. Através da geração de uma chave de permissão específica, o seu parceiro ou fornecedor de tecnologia poderá efetuar buscas e downloads utilizando credenciais próprias, restritas às empresas autorizadas por você.
💡 Precisa de suporte estratégico ou de uma solução sob medida? Se a sua empresa possui cenários complexos de negócios ou necessita de um desenho técnico parametrizado para o seu ERP, acesse o chat na plataforma Qive e fale diretamente com o nosso time de Experiência do Cliente. Caso prefira avaliar módulos complementares de sincronização automática sem código, consulte também o nosso artigo sobre o Módulo Sincroniza Notas®.