TaxPlus DF-e | Configuração | Configurações de Recebimento | Documentos | Dados Gerais (3) | API de Recebimento DF-e
10 min
Criado por Gracyelly Silva de Moraes em 30/08/2022 10:36
Atualizado por Samuel Elias em 09/11/2026 11:28

Dúvida

API de Recebimento DF-e

Procedimento

Esta documentação tem por objetivo detalhar o processo de configuração da API de Recebimento DF-e, incluindo o envio de manifestos e dos eventos da Reforma Tributária.

Configurações de Recebimento

1. Definir se deseja salvar uma cópia do XML recebido via API. Definir o diretório do XML e em seguida definir a inclusão automática do documento após Recebimento via API:

Configurações do Serviço

2. Iniciar o Serviço de Recebimento API:

  • Definir a porta da API que, por padrão, será 5001;
  • Gerar o token de autenticidade da API;
  • Salvar configurações.



Exemplo de comunicação com Postman

Método POST

3. Informar a URL, o tipo de autorização e o token gerado no serviço:

4. Em seguida, habilite o parâmetro XML e informe o XML de recebimento:

  

5. Exemplo de comunicação C#.

using RestSharp;
static void Main(string[] args)
{
var url = "http://localhost:5001";
var token = "SEU-TOKEN";
var xml = File.ReadAllText(@"C:\CAMINHO\DO\ARQUIVO\entrada.xml");
var restClient = new RestClient(url);
var request = new RestRequest("/api/recepcionar/entrada", Method.POST)
{
RequestFormat = DataFormat.Xml,
XmlSerializer = new RestSharp.Serializers.DotNetXmlSerializer()
};
request.AddHeader("Authorization", token);
request.AddParameter("xml", xml, ParameterType.QueryString);
var response = restClient.Post(request);
Console.WriteLine(response.Content);
Console.ReadKey();
}

6. Retorno do Envio:    

<RetornoRecebimento>
        <Sucesso>true</Sucesso>
        <Mensagem>Documento [53201212769092000158550510000010601489428191]
recebido com sucesso.</Mensagem>
</RetornoRecebimento>


Manifestos e Eventos da Reforma Tributária via API

Para realizar o envio de manifestos e dos eventos da Reforma Tributária via API, é necessário configurar a requisição e informar os dados abaixo. O TaxPlus DF-e monta o evento a partir do XML armazenado, assina com o certificado da empresa, envia à SEFAZ e devolve o resultado na mesma resposta (chamada síncrona). O evento fica registrado no histórico do documento, exatamente como quando enviado pela tela.

Pré-requisitos

  • Serviço API DF-e em execução no Monitor de Serviço;

  • Token: campo Token Api do serviço. É o valor enviado no cabeçalho Authorization;

  • Porta: campo Porta API do serviço (padrão 5001);

  • Ambiente: apelido da base cadastrado em Monitor de Serviço > Banco do SAP (coluna Ambiente). É o valor de {ambiente} na URL;

  • Certificado digital configurado para a empresa destinatária. Os eventos da Reforma Tributária são enviados sempre direto para a SEFAZ, mesmo com provedor externo (Qive/Arquivei) habilitado.

Importante: para que o processo funcione corretamente, o documento já deve ter sido capturado pelo DFe e estar disponível na tela de Administração do Add-on. Confira também no log do Serviço API DF-e se a conexão com o banco de dados foi realizada com sucesso. Caso seja apresentado o erro authentication failed, corrija o usuário e a senha em Monitor de Serviço > Dados de Conexão do Banco de Dados, clique em Testar Conexão e Salvar Alterações e reinicie o serviço. Sem conexão com o banco de dados, as chamadas retornam erro 500.

Eventos contemplados

A API permite o registro dos seguintes eventos:

Manifestos

  • 210200 - Confirmação da Operação;

  • 210210 - Ciência da Operação;

  • 210220 - Desconhecimento da Operação (exige justificativa);

  • 210240 - Operação não Realizada (exige justificativa);

  • 610110 - Prestação do Serviço em Desacordo (CT-e).

Eventos da Reforma Tributária (somente NF-e modelo 55)

  • 211110 - Solicitação de Apropriação de Crédito Presumido (a NF-e precisa ter itens com o grupo gCredPresOper);

  • 211124 - Perecimento, Perda, Roubo ou Furto durante o Transporte (Adquirente);

  • 211128 - Aceite de Débito na Apuração por Emissão de Nota de Crédito (enviado sempre como aceite);

  • 211130 - Imobilização de Item;

  • 211140 - Solicitação de Apropriação de Crédito de Combustível;

  • 211150 - Solicitação de Apropriação de Crédito para Bens e Serviços.

Nos eventos 211124, 211130, 211140 e 211150 a NF-e precisa ter itens com o grupo gIBSCBS. Os itens e valores do evento são lidos do XML da NF-e armazenado no TaxPlus, não sendo necessário enviá-los na requisição.

Informações necessárias

  • ID do documento (coluna Id da tela de Administração do DF-e) ou chave de acesso de 44 dígitos;

  • Código do evento, conforme definido pela SEFAZ;

  • Justificativa, somente nos manifestos que a exigem. Nos eventos da Reforma Tributária ela é ignorada.

Configuração no Postman

Método e URL
Selecione o método POST e informe a URL abaixo, substituindo SERVIDOR e {ambiente}:

POST http://SERVIDOR:5001/api/v2/{ambiente}/dfe/manifestar/documento

Headers
Na aba Headers, informe a chave Authorization com o Token gerado nos serviços do Add-on DFe, sem o prefixo Bearer. Na aba Authorization, mantenha a opção No Auth.

Body → raw → JSON
As informações do evento devem ser preenchidas no corpo da requisição, utilizando a opção raw com o formato JSON:

{
    "documentoId": 23577,
    "chave": "52220212945116000182550520000006917890086699",
    "evento": 211128,
    "justificativa": ""
}

Atenção:

  • Informe o documentoId ou a chave. Se enviar os dois, a API confere se pertencem ao mesmo documento;
  • A chave deve ser informada entre aspas;
  • Envie um evento por requisição, com o JSON direto no corpo, sem lista [ ] e sem o campo ArquivoJason;
  • O método deve ser POST e o corpo deve estar como JSON. O método GET nesta rota realiza a consulta e não o envio do evento.

Após realizar essas configurações, a requisição poderá ser enviada para processamento do evento via API.

Exemplo de retorno

{
    "Mensagem": "Evento registrado e vinculado a NF-e",
    "DocumentoId": 23577,
    "Chave": "52220212945116000182550520000006917890086699",
    "Evento": 211128,
    "DescricaoDoEvento": "Aceite de Débito na Apuração por Emissão de Nota de Crédito",
    "DataDoEvento": "",
    "StatusId": 3,
    "Status": "Registro encontrado",
    "CodigoDoRetorno": 135,
    "Protocolo": "352260000015392"
}

  • CodigoDoRetorno: código de retorno (cStat) da SEFAZ. Nos eventos da Reforma Tributária, 135 e 136 indicam sucesso. O valor 0 indica que a recusa ocorreu antes do envio à SEFAZ;

  • Protocolo: preenchido somente quando o evento é registrado;

  • Status / StatusId: situação do documento na tela de Administração do DF-e. Os eventos da Reforma Tributária não alteram essa situação.

Códigos de retorno HTTP

  • 200 - Evento registrado na SEFAZ;

  • 400 - Requisição inválida (JSON, campos, evento ou ambiente). Corrija o envio;

  • 401 - Token ausente ou diferente do configurado no serviço. Confira o cabeçalho Authorization;

  • 404 - Documento não encontrado no TaxPlus DF-e. Realize o download do documento antes de enviar o evento;

  • 409 - O documento não é NF-e, a chave não corresponde ao Id ou a chave está repetida. Envie apenas o Id ou apenas a chave;

  • 422 - Evento não registrado: rejeição da SEFAZ, NF-e sem os itens exigidos pelo evento, documento sem XML ou falha no certificado. Verifique os campos CodigoDoRetorno e Mensagem;

  • 503 - API ocupada com outra requisição. Aguarde 30 segundos e envie novamente;

  • 500 - Falha inesperada. Verifique o log do Serviço API DF-e.

Consulta do último evento (opcional)

Para consultar o último evento registrado para um documento, utilize o método GET na mesma rota, informando os parâmetros na URL e o Token no cabeçalho Authorization. Sem o parâmetro evento, é retornado o último manifesto do documento.

GET http://SERVIDOR:5001/api/v2/{ambiente}/dfe/manifestar/documento?chave=52220212945116000182550520000006917890086699&evento=211128

Verificação da disponibilidade da API (opcional)

Para verificar se a API está em funcionamento, utilize a rota abaixo com o Token no cabeçalho Authorization. O retorno 200 - API disponível indica que o serviço está atendendo.

GET http://SERVIDOR:5001/api/v2/{ambiente}/dfe/status

Conferência no Add-on

Na tela de Administração do DF-e, localize o documento e verifique o histórico de eventos. O evento enviado pela API é apresentado com o mesmo protocolo e os mesmos XMLs de envio e retorno de um evento enviado pela tela.


Este artigo foi útil para você?
Últimos artigos visitados