A API v2 do nsdocs proporciona uma visão abrangente da infraestrutura do serviço, oferecendo uma interface programática padronizada. Com ela, você pode realizar praticamente todas as operações disponíveis no painel, tudo isso na sua linguagem de programação favorita. Baseada em solicitações HTTP e respostas JSON, a API do nsdocs é uma solução RESTful que simplifica a interação com o serviço.
\nPrincipais operações:
\nEnviar documentos e eventos para o nsdocs.
\nListar dados dos documentos armazenados usando filtros e paginação.
\nImportar documentos como NF-e e CT-e através da Chave de Acesso.
\nListar dados das empresas cadastradas e consultar a quantidade de créditos disponíveis.
\nRealizar a Pesquisa e Manifestação do Destinatário.
\nPara garantir a segurança, esta versão da API utiliza a autenticação do tipo Bearer, exigindo que todas as solicitações sejam criptografadas e enviadas via HTTPS.
Todas as chaves de API podem ser restritas a um pequeno conjunto de permissões. Você pode gerar suas chaves de API através do painel web do nsdocs, no menu Configurações > Integração via API.
Você deve fornecer sua chave no cabeçalho da solicitação para se autenticar na API.
\n\n\nAuthorization: \"Bearer CHAVE_API\"
\n
Nunca compartilhe suas chaves de API. Mantenha-as protegidas e seguras.
Durante a operação normal, garantimos que todas as respostas da API sejam compactadas, seja com GZIP ou DEFLATE. Ambos os algoritmos são bastante comuns e a maioria das plataformas deve ter ferramentas internas para lidar com a descompactação.
\nA motivação para isso é simples, servir conteúdo não compactado é uma perda para todas as partes. A largura de banda é, em comparação com o tempo de CPU, excepcionalmente cara e severamente limitada em muitos dispositivos.
\nEmbora seja verdade que a maioria dos navegadores solicite conteúdo compactado, é importante considerar que muitos dos aplicativos que utilizam nossa API podem não estar totalmente atualizados em relação às melhores práticas de protocolos HTTP. A probabilidade de que algumas aplicações não adotem a compactação, o que pode resultar em um desempenho inferior, é algo que devemos evitar e corrigir.
\nA API tentará preservar a garantia de compactação em face dos erros, no entanto, é possível que ocorram erros cedo o suficiente na pilha para que a compactação não ocorra. Nesses casos, os erros serão retornados sem compactação.
\nEm primeiro lugar, sempre defina o cabeçalho Accept-Encoding. Nossa API tentará honrar sua codificação solicitada (GZIP ou DEFLATE), voltando ao GZIP se o cabeçalho não chegar ou for modificado no caminho.
\nSe Content-Encoding estiver definido na resposta, use o algoritmo especificado. Se estiver faltando, suponha GZIP.
\nSe a resposta não for compactada, isso sugere que um proxy entre o usuário e nós está descomprimindo intencionalmente o conteúdo ou que erros estão ocorrendo muito cedo nas solicitações de processamento. Você pode detectar conteúdo não compactado verificando os números mágicos apropriados, supondo que sua biblioteca não possa detectar esse erro para você.
\nA API nunca retornará uma resposta descompactada durante a operação normal.
\nÉ possível controlar a quantidade e o deslocamento da Consulta de Documentos especificando os parâmetros quantidade e deslocamento, sendo que a quantidade máxima de documentos é de 100 registros por requisição.
Além disso, a API deve retornar no header X-Total-Registros a quantidade total de registros retornados.
quantidade: Informe a quantidade de documentos por página. Máximo de 100 documentos.
deslocamento: Informe o deslocamento da consulta (offset).
Digamos que com base em um filtro informado na consulta, a requisição retorne 6 registros no header X-Total-Registros
\n\nA soma dos valores informados nos parâmetros
\nquantidadeedeslocamentoé limitada a 2.000 registros no retorno. Caso seja informado um valor dedeslocamentoque exceda esse limite, os resultados ainda serão limitados a 2.000 registros.
Exemplo: Se a busca tem 10.000 documentos possíveis e forem informados quantidade = 100 e deslocamento = 1.950, a chamada retornará os 50 documentos a partir da posição 1.950 até a posição 2.000. Para acessar documentos além desse limite, será necessário ajustar os filtros de busca, como período de data de recebimento ou emissão, ou intervalo de número do documento. Também é possível usar parâmetros de ordenação, como número, data de emissão ou recebimento.
O corpo das mensagens de erro são retornadas no formato JSON na seguinte estrutura:
\n{\n 'codigo': '400',\n 'descricao': 'Consulta inexistente na base de dados do nsdocs'\n}\n\ndeflate/gzip
\n"},{"key":"Empresa-Id","value":"Id da Empresa cadastrada no nsdocs.
\n"},{"key":"Empresa-Cnpj","value":"CNPJ da Empresa cadastrada no nsdocs.
\n"},{"key":"Accept","value":"application/json; charset=utf-8"}],"url":"https://api.nsdocs.com.br/v2/documentos?campos=Retorna os dados dos documentos armazenados no nsdocs. Informe o parâmetro \"campos\" para especificar as informações que deseja obter dos documentos. Esta requisição é necessária para recuperar o Id dos documentos que deseja baixar o XML/PDF.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Filtro por Emitente, Destinatário, Transportador, Tomador, Chave de Acesso, Data de Emissão, Número ou Valor. Também é possível realizar o filtro por um campo específico, informando o nome do campo como um parâmetro da requisição.
\n","type":"text/plain"},"key":"filtro","value":"Indique os campos que deseja incluir na consulta, separados por vírgula. Lembre-se de que o campo ‘Id’ será sempre retornado.
\nClique aqui para ver mais detalhes sobre os campos.
\n","type":"text/plain"},"key":"campos","value":"O limite de documentos por página
\n\n\n","type":"text/plain"},"key":"quantidade","value":"Máximo :
\n100
O deslocamento da consulta (offset) >= 0
Campo usado na ordenação dos dados:
\n\n\nExemplo:
\n\"numero\", \"data_emissao\", \"data_recebimento\", \"hora_recebimento\", \"valor\" ou \"peso\".
Clique aqui para ver mais detalhes sobre os campos.
\n","type":"text/plain"},"key":"ordenacao_campo","value":"Método de ordenação dos dados:
\n\n\n","type":"text/plain"},"key":"ordenacao_tipo","value":"Exemplo:
\n\"desc\" ou \"asc\"
O parâmetro campos informado acima é utilizado para informar quais \"colunas\" retornam no resultado da requisição. Como adicional, o sistema permite informar qualquer um desses valore dos \"campos\" como parâmetro de filtro na busca.
\n\n\nExemplo:
\n{ \"status\": \"Pendente\"},{ \"modelo\": \"nfse\"}ou{\"marcadores\": \"Teste, Teste2\"}
observação: Se o valor não for informado ou é inválido, o sistema utilizará um valor padrão pré configurado internamente.
\n","type":"text/plain"},"key":"deflate/gzip
\n","key":"Accept-Encoding","value":"gzip"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json; charset=utf-8"}],"body":{"mode":"raw","raw":"{\n \"id_documentos\": \"Marca um documento como utilizado/importado.
\nVeja como utilizar os parâmetros:
\nid_documentos: Lista de IDs dos documentos que serão atualizados no nsdocs.
\nTipo: Array de inteiros.
\nExemplo:
\"id_documentos\":[1,4,5,6,54]
\"id_documentos\":[5642]
utilizado: Define se o documento foi utilizado/importado.
\nTipo: Booleano.
\nValores:
\ntrue: o documento já foi utilizado dentro do ecosistema.
false: O documento ainda não foi utilizado.
Exemplo da Requisição
\n{\n \"id_documentos\": [1,4,5,6,54],\n \"utilizado\": true\n}\n\nO indicador utilizado pode ser usado para filtrar documentos no endpoint Consultar Documentos. Para fazer isso, informe o parâmetro status na requisição informando se a busca deve trazer somente documentos já utilizados ou não.
Exemplo do uso do parâmetro status no endpoint Consultar Documentos.
status:
\nPendente: Carrega os documentos que não estão indicados como utilizados(false).
\nImportado: Carrega os documentos que estão indicados como utilizados(true).
\nDefault: Se nenhum valor for informado no parâmetro, não houver o parâmetro ou ele for inválido, o sistema usará o valor \"Pendente\" como padrão.
\nExemplo:
{ \"status\": \"Pendente\"}
{ \"status\": \"Importado\"}
deflate/gzip
\n","key":"Accept-Encoding","value":"gzip"},{"key":"Accept","value":"application/json; charset=utf-8"}],"url":"https://api.nsdocs.com.br/v2/documentos/campos","description":"Cada campo possui parâmetros que determinam suas configurações:
\nCampo: Nome do campo. Pode ser informado no endpoint Consulta de Documentos para especificar quais campos deseja que sejam retornados na requisição.
\nDescrição: Descrição do campo.
\nTipo: Tipo de dado. Pode ser usado para determinar como a informação pode ser usada no seu sistema.
\nLargura: Usado como referência para o tamanho da informação. Pode ser usado em interfaces para definir o tamanho de coluna por exemplo.
\nOrdenação: Se retornado como true, o campo pode ser usado em outro endpoint para ser ordenado como desc ou asc.
camposO parâmetro campo pode ser usado de três maneiras, todas nas requisições do endpoint Consulta de Documentos:
\nPara informar quais campos devem retornar da requisição.
\nPara realizar filtros nas buscas especificas.
\nPara ordenar os dados.
\nNo endpoint Consulta de Documentos informe o parâmetro campos. Nele informe uma lista formada pelo nome de cada campo, assim cada campo informado nessa lista, vai retornar na requisição.
Cada campo disponível nesse retorno, pode ser usado como um filtro e cada um pode ser usado de maneira diferente:
\nUse-o com valores em períodos ou intervalos.
\nPeríodo de data: 27/05/2024 - 20/06/2024
Intervalo de valores inteiros: 200 - 5000
Intervalo de valores racionais: 25,51 - 65,32
Use-o de forma parecida com operador igual ou diferente.
\nValor igual:
\nvalor=356
\nnumero=564
\ncfop=6910
\nValor diferente(use o caractere exclamação no nome do campo)
\n!valor=356
\n!numero=564
\n!cfop=6910
\nUse-o para ordenar os dados.
Cada campo possui um parâmetro chamado ordenacao que estabelece se o campo pode ou não ser usado para ordenação. Para ordenar, é preciso informar dois parâmetros na requisição Consulta de Documentos.
ordenacao_tipo: informe o método da ordenação
\ndesc: decrescente.
\nasc: crescente.
\nordenacao_campo: informe qualquer campo que possui o parâmetro ordenacao definido como true.
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Verifique os exemplos de chamadas e respostas em Consulta de Documentos. Ao abrir a collection através do Postman, também é possível visualizar descrições sobre o uso dos campos nos exemplos
\n
deflate/gzip
\n"},{"key":"Accept","value":"application/xml"}],"url":"https://api.nsdocs.com.br/v2/documentos/:id/xml?status=Retorna o arquivo XML do documento.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Status de utilização do Documento.
\n\n\n","type":"text/plain"},"key":"status","value":"Exemplo:
\nImportadoouPendente
Id do documento obtido em Consulta de Documentos
\n","type":"text/plain"},"type":"any","value":"deflate/gzip
\n"},{"key":"Accept","value":"application/pdf"}],"url":"https://api.nsdocs.com.br/v2/documentos/:id/pdf?incluir_fonte_pdf=Retorna o arquivo PDF do documento.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Incorporar fontes no PDF
\n","type":"text/plain"},"key":"incluir_fonte_pdf","value":"Id do documento obtido em Consulta de Documentos
\n","type":"text/plain"},"type":"any","value":"deflate/gzip
\n"},{"key":"Empresa-Id","value":"Id da Empresa cadastrada no nsdocs.
\n"},{"key":"Content-Type","value":"application/x-www-form-urlencoded"},{"key":"Accept","value":"application/json; charset=utf-8"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Required Conteúdo do arquivo XML
Grava um Documento Fiscal Eletrônico [NF-e, NFC-e, CT-e, CT-e OS, MDF-e, CF-e, NFS-e] no nsdocs.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"deflate/gzip
\n"},{"key":"Empresa-Id","value":"Id da Empresa cadastrada no nsdocs.
\n"},{"key":"Content-Type","value":"application/x-www-form-urlencoded"},{"key":"Accept","value":"application/json; charset=utf-8"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Required Modelo do documento fiscal eletrônico (DF-e)
\n\n","key":"modelo","value":"Exemplo:
\n55,57,58,65ou67
Consulta pelo número do último NSU
\n","key":"ult_nsu","value":"Consulta pela Chave de Acesso
\n","key":"chave_acesso","value":"Distribuição de Documentos Fiscais Eletrônicos (DF-e) destinados ao CNPJ da empresa.
\n\n\nrequer o uso de um Certificado Digital modelo A1 armazenado no nsdocs.
\n
Veja como utilizar os parâmetros:
\nmodelo: Este parâmetro é obrigatório e permite definir qual documento será pesquisado.
\nult_nsu: Opcionalmente, caso não seja informado, o sistema usará o último NSU registrado. Se for informado, o sistema buscará documentos a partir do valor especificado.
\nchave_acesso: Também opcional, se informado, altera a forma de busca para uma busca exclusiva pela chave de acesso fornecida.
\ndeflate/gzip
\n"},{"key":"Accept","value":"application/json; charset=utf-8"}],"url":"https://api.nsdocs.com.br/v2/documentos/:id/marcadores?marcadores=Adiciona os marcadores ao documento. Os marcadores devem ser cadastrados através do painel.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Required Lista com os nomes dos Marcadores, separados por vírgula.
Id do documento obtido em Consulta de Documentos
\n","type":"text/plain"},"type":"any","value":"deflate/gzip
\n"},{"key":"Accept","value":"application/json; charset=utf-8"}],"url":"https://api.nsdocs.com.br/v2/documentos/:id/marcadores?marcadores=Remove os marcadores do documento.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Lista com os nomes dos Marcadores, separados por vírgula. Caso não seja enviado todos os Marcadores do documento são removidos.
\n\n\n","type":"text/plain"},"key":"marcadores","value":"Exemplo:
\nmarcador1, Contabilidade, Defeito, Devolução
Id do documento obtido em Consulta de Documentos
\n","type":"text/plain"},"type":"any","value":"CNPJ da Empresa cadastrada no nsdocs.
\n","type":"text"}],"url":"https://api.nsdocs.com.br/v2/log-consulta/:tipo","description":"Retorna o Histórico de Consultas de Documentos fiscais [NF-e, CT-e, MDF-e] realizados no Distribuição DF-e.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Required Modelo do documento fiscal eletrônico (DF-e)
\n\n","type":"text/plain"},"type":"any","value":"Exemplo:
\nnfe,cte,mdfe
Listagem e gravação de documentos armazenados no nsdocs.
\n","_postman_id":"d95ae7d6-1c5e-410f-a95a-e691fcd9c746","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Required CNPJ da Empresa cadastrada no nsdocs.
Retorna os Eventos de Documentos Fiscais Eletrônicos [NF-e, NFC-e, CT-e, CT-e OS, MDF-e] armazenados no nsdocs.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Required Data inicial da emissão do evento no formato dd/mm/aaaa ou dd/mm/aaaa hh:mm:ss.
\n\n","type":"text/plain"},"key":"data_inicial","value":"Exemplo:
\n01/05/2023 10:44:00ou01/05/2023
Chave de Acesso
\n","type":"text/plain"},"key":"chave_acesso","value":"Código de Status retornado pela Sefaz
\n\n\n","type":"text/plain"},"key":"status","value":"Exemplo:
\n\"135\"ou\"596\"
Modelo do documento fiscal eletrônico (DF-e)
\n\n\n","type":"text/plain"},"key":"tipo_doc","value":"Enum:
\n\"nfe\"\"cte\"\"cteos\"
Numeração do tipo do Evento.
\n\n\n","type":"text/plain"},"key":"tipo_evento","value":"Exemplo:
\n\"210210\"
Sequência do Evento
\n","type":"text/plain"},"key":"sequencia","value":"Número de Protocolo do Evento
\n","type":"text/plain"},"key":"protocolo","value":"deflate/gzip
\n"},{"key":"Empresa-Id","value":"Id da Empresa cadastrada no nsdocs.
\n"},{"key":"Content-Type","value":"application/x-www-form-urlencoded"},{"key":"Accept","value":"application/json; charset=utf-8"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Required Lista com até 20 Chaves de Acesso, separadas por vírgula
Required Código do Evento
Justificativa do Evento
\n","key":"justificativa","value":"Envia um Evento de Documento Fiscal Eletrônico [NF-e, CT-e, CT-e OS] para a Sefaz. Requer Certificado Digital modelo A1 armazenado no nsdocs.
\nEventos permitidos:
\ndeflate/gzip
\n"},{"key":"Content-Type","value":"application/x-www-form-urlencoded"},{"key":"Accept","value":"application/json; charset=utf-8"}],"body":{"mode":"urlencoded","urlencoded":[{"description":"Required Arquivo XML
Grava o XML de um Evento de Documento Fiscal Eletrônico [NF-e, NFC-e, CT-e, CT-e OS, MDF-e, CF-e] para o nsdocs.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Listagem de Eventos, gravação de XMLs de Eventos no nsdocs e envio de Eventos para a Sefaz.
\n","_postman_id":"97a52853-8313-430f-a341-96a0a6ec675f","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"deflate/gzip
\n"},{"key":"Accept","value":"application/json; charset=utf-8"}],"url":"https://api.nsdocs.com.br/v2/marcadores","description":"Retorna os Marcadores de Documentos cadastrados no nsdocs.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Os Marcadores são tags que podem ser cadastradas pelo usuário e vinculadas manualmente ou automaticamente aos Documentos.
\n","_postman_id":"fe9c49f1-c1eb-4a7a-8f05-bb7ff385a42c","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"deflate/gzip
\n","key":"Accept-Encoding","value":"gzip"},{"key":"Accept","value":"application/json; charset=utf-8"}],"url":"https://api.nsdocs.com.br/v2/empresas","description":"Retorna as Empresas cadastradas no nsdocs.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Este endpoint retorna um JSON com informações detalhadas sobre o plano, incluindo a quantidade contratada, consumida e disponível. Além disso, fornece dados sobre a empresa responsável pela cobrança e detalhes do plano de Consulta Garantida.
\nBusca o valor de um parâmetro de configuração de Empresa.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Required Id da Empresa cadastrada no nsdocs.
Required Código do parâmetro
\n\n","type":"text/plain"},"type":"any","value":"Exemplo:
\n\"url_webhook\"