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/documentoHeaders
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=211128Verificaçã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/statusConferê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.