Como consultar eventos de um DFe?

Há algumas formas de consultar eventos fiscais via API REST Oobj. Neste artigo você encontra o passo a passo para:

Consultar todos os eventos;
Consultar os detalhes de um tipo específico de evento;
Consultar eventos em um determinado intervalo de datas.

Consultar todos os eventos de um DFe

Para consultar todos os eventos associados a um DFe, sendo o CNPJ da empresa o emissor do DFe, siga estes passos:

Para começar, faça uma requisição tipo GET ao endpoint de consultar eventos de um DFe;

[URL_BASE]/api/empresas/{empresa}/docs/{ambiente}/{codModelo}/{ano}/{serie}/{numero}/eventos

Preencha as seguintes informações (path parameters):
- {empresa}*: CNPJ da empresa;
- {ambiente}*: hom ou prod;
- {codModelo}*: 55 (NFe), 57 (CTe), 58 (MDFe), 59 (CFe-SAT), 65 (NFCe), 66 (NF3e), 67 (CTeOS) ou 99 (NFSe);
- {ano}*: ano de emissão no formato AAAA (quatro dígitos);
- {serie}*: série do DFe;
- {numero}*: número do DFe;
Informe o x-auth-token no cabeçalho (header parameters) da requisição.

Atenção

No campo conteudo do retorno 200 você encontra o XML Proc de todos os eventos relacionados ao DFe. Esse XML é idêntico ao armazenado pela Sefaz e deve ser guardado pelo contribuinte por no mínimo cinco anos.

Exemplo de requisição

O exemplo abaixo traz um modelo de requisição preenchido para consultar todos os eventos associados a um DFe.

Observação

A requisição contém dados fictícios, somente para demonstração.

curl -L -X GET 'https://rest-teste.oobj.com.br/api/empresas/07385111000102/docs/hom/55/2023/503/741567/eventos' \
-H 'Accept: */*' \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI3Yjc2OTg1ZGQ2MTNhOWVlYTFiN2RmZTNiZjRhMTRiZiIsImF1ZCI6IndlYiIsImV4cCI6MTYyOTI5MDcwNiwiaWF0IjoxNjI5Mjg4OTA2fQ.-Dj91d6fBZYcZpy1-zKzohAWd5dgW2CAS5BBfwGilemUYcOVDm8CnrDJHbwsFyixI5ohphy-65fqeobXkimtCg\'''

Exemplo de retorno

[
    {
        "sequencial": 1,
        "chaveAcesso": "43230207385111000102555030007415671314477460",
        "dataEvento": "2023-04-20T17:08:39-03:00",
        "codigoEvento": 110130,
        "descricaoEvento": "Comprovante de Entrega da NF-e",
        "status": "Homologado",
        "cStat": 135,
        "retornoSefaz": "Evento registrado e vinculado a NF-e",
        "conteudo": "<?xml ... />"
    },
    {
        "sequencial": 1,
        "chaveAcesso": "43230207385111000102555030007415671314477460",
        "dataEvento": "2023-04-24T13:03:17-03:00",
        "codigoEvento": 110111,
        "descricaoEvento": "Cancelamento",
        "status": "Rejeitado",
        "cStat": 501,
        "retornoSefaz": "Rejeicao: Prazo de Cancelamento Superior ao Previsto na Legislacao",
        "conteudo": "<?xml ... />"
    }
]

Consultar detalhes de um tipo específico de evento

Para consultar os detalhes de um tipo específico de evento a partir de uma chave de acesso, siga estes passos:

Faça uma requisição tipo GET ao endpoint de consultar detalhes de um evento;

[URL_BASE]/api/empresas/{empresa}/docs/{ambiente}/{chaveAcesso}/eventos/{tipoEvento}

Preencha as seguintes informações (path parameters):
- {empresa}*: CNPJ da empresa;
- {ambiente}*: hom ou prod;
- {chaveAcesso}*: chave de acesso do documento;
- {tipoEvento}*: código do tipo do evento. Exemplo: 110110 (carta de correção), 110111 (cancelamento) ou 110140 (EPEC);
Informe o x-auth-token no cabeçalho (header parameters) da requisição.

Exemplo de requisição

O exemplo abaixo traz um modelo de requisição preenchido para consultar os detalhes de um tipo específico de evento a partir de uma chave de acesso.

Observação

A requisição contém dados fictícios, somente para demonstração.

curl -L -X GET 'https://rest-teste.oobj.com.br/api/empresas/07385111000102/docs/hom/43230207385111000102555030007415671314477460/eventos/110130' \
-H 'Accept: */*' \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI3Yjc2OTg1ZGQ2MTNhOWVlYTFiN2RmZTNiZjRhMTRiZiIsImF1ZCI6IndlYiIsImV4cCI6MTYyOTI5MDcwNiwiaWF0IjoxNjI5Mjg4OTA2fQ.-Dj91d6fBZYcZpy1-zKzohAWd5dgW2CAS5BBfwGilemUYcOVDm8CnrDJHbwsFyixI5ohphy-65fqeobXkimtCg'

Exemplo de retorno

[
    {
        "sequencial": 1,
        "chaveAcesso": "43230207385111000102555030007415671314477460",
        "dataEvento": "2023-04-20T17:08:39-03:00",
        "codigoEvento": 110130,
        "descricaoEvento": "Comprovante de Entrega da NF-e",
        "status": "Homologado",
        "cStat": 135,
        "retornoSefaz": "Evento registrado e vinculado a NF-e",
        "conteudo": "<?xml ... />"
    }
]

Consultar eventos em um intervalo de datas

Para consultar todos os eventos cuja data esteja entre dataEventoInicial e dataEventoFinal, sendo o CNPJ da empresa emissora dos eventos, siga estes passos:

ATENÇÃO

Serão considerados eventos entre 00:00:00h da data inicial e 23:59:59h da data final.

Faça uma requisição tipo GET ao endpoint de consultar todos os eventos em um intervalo de datas;

[URL_BASE]/api/empresas/{empresa}/docs/{ambiente}/{codModelo}/eventos/data-inicial/{dataEventoInicial}/data-final/{dataEventoFinal}

Preencha as seguintes informações (path parameters):
- {empresa}*: CNPJ da empresa;
- {ambiente}*: hom ou prod;
- {codModelo}*: 55 (NFe), 57 (CTe), 58 (MDFe), 59 (CFe-SAT), 65 (NFCe), 66 (NF3e), 67 (CTeOS) ou 99 (NFSe);
- {dataEventoInicial}*: data inicial para pesquisa, no formato aaaa-mm-dd. Exemplo: '2018-03-26';
- {dataEventoFinal}*: data final para pesquisa, no formato aaaa-mm-dd. Exemplo: '2018-03-26';
Informe o x-auth-token no cabeçalho (header parameters) da requisição.

Exemplo de requisição

O exemplo abaixo traz um modelo de requisição preenchido para consultar eventos em um intervalo de datas.

Observação

A requisição contém dados fictícios, somente para demonstração.

curl -L -X GET 'https://rest-teste.oobj.com.br/api/empresas/07385111000102/docs/hom/55/eventos/data-inicial/2023-01-01/data-final/2023-04-25' \
-H 'Accept: */*' \
-H 'x-auth-token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI3Yjc2OTg1ZGQ2MTNhOWVlYTFiN2RmZTNiZjRhMTRiZiIsImF1ZCI6IndlYiIsImV4cCI6MTYyOTI5MDcwNiwiaWF0IjoxNjI5Mjg4OTA2fQ.-Dj91d6fBZYcZpy1-zKzohAWd5dgW2CAS5BBfwGilemUYcOVDm8CnrDJHbwsFyixI5ohphy-65fqeobXkimtCg'

Exemplo de retorno

[
    {
        "sequencial": 1,
        "chaveAcesso": "43230107385111000102555030007383471314477461",
        "dataEvento": "2023-01-04T10:58:40-03:00",
        "codigoEvento": 110110,
        "descricaoEvento": "Carta de Correção",
        "status": "Homologado",
        "cStat": 135,
        "retornoSefaz": "Evento registrado e vinculado a NF-e",
        "conteudo": "<?xml ... />"
    },
    {
        "sequencial": 1,
        "chaveAcesso": "43230107385111000102555030007384651314477465",
        "dataEvento": "2023-01-04T14:35:25-03:00",
        "codigoEvento": 210210,
        "descricaoEvento": "Ciência da Operação",
        "status": "Homologado",
        "cStat": 135,
        "retornoSefaz": "Evento registrado e vinculado a NF-e",
        "conteudo": "<?xml ... />"
    }
]

Pronto! Você acaba de completar a consulta de um evento fiscal de três formas diferentes.

Como consultar eventos de um DFe?

Consultar todos os eventos de um DFe​

Consultar detalhes de um tipo específico de evento​

Consultar eventos em um intervalo de datas​

Consultar todos os eventos de um DFe

Consultar detalhes de um tipo específico de evento

Consultar eventos em um intervalo de datas