Como usar

Descrever os processos e padrões de integração com o WebService de consulta de NFE e o modelo de retorno das consultas.

WEBSERVICE – ENVIO DE LOTE DE CONSULTA

Responsável por receber as requisições de consulta de lote de NFe.

AUTENTICAÇÃO

A autenticação é feita com o padrão oauth, realizando o envio de usuário e senha e recebendo o Token de autenticação e informações de cadastro.

O Usuário e Senha solicitado nas requisições é disponibilizado pela equipe da QuickSoft.

Definições de Autenticação

Realizar um POST com um JOSN contendo o Usuário e a Senha.

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	Username	Usuário para autenticação	Alfanumérico	Obrigatório	String
2	Password	Senha para autenticação	Alfanumérico	Obrigatório	String

Retorno da autenticação

O retorno da autenticação contém o Bearer Token para ser utilizado nos envios de lotes de consulta junto com algumas informações do cadastro.

Nota	Campo	Conteúdo/Significado	Tipo	Esquema
1	token	Bearer token	Alfanumérico	String
2	expiredTime	Tempo de expiração do Token	Data e Hora	DateTime
3	urlPadrao	Url padrão para retornos cadastrada	Alfanumérico	String
4	idcReutiliza	Identificador se esse cadastro está utilizando o reaproveitamento de consultas	Booleano	Bool

Exemplos

Envio para Autenticação

{
    "Username": "nome_de_usuario",
    "Password": "senha123"
}

Retorno

{
    "token": "BEARER TOKEN",
    "expiredTime": "2022-04-22T12:24:48.0274379Z",
    "urlPadrao": "https://URL-RETORNO-PADRAO/api/retorno",
    "idcReutiliza": true
}

DEFINIÇÕES DE ENVIO

O envio de lotes para consulta deve seguir o seguinte padrão REST:

Limitado a 50 números de NFe por lote.

LoteConsulta

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	IdRequisicao	Código identificador do lote	Alfanumérico	Obrigatório	String
2	TipoConsulta	Código do Tipo da consulta: 1 – Protocolo 2 – Evento 3 – Completa	Numérico	Obrigatório	Int
3	URLRetorno	Endereço do WebService REST para onde devemos enviar o resultado da consulta.*	Alfanumérico	Opcional	String
4	ListaNfe	Lista com as chaves das notas fiscais eletrônicas que devem ser consultadas	Lista do tipo DadosNFe	Obrigatório	ICollection< DadosNFe >

Caso não for informado será utilizado o endereço do webservice que está informado nos parâmetros do contratante.

DadosNfe

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	NroNfe	Código da chave NFe	Alfanumérico	Obrigatório	String

Retorno da requisição

A resposta da requisição de consulta de lote de NFe segue o seguinte padrão:

RetornoSolicitacaoConsulta

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	Mensagem	Descrição da mensagem de retorno	Alfanumérico	Obrigatório	String
2	Situacao	Código de retorno: 0 - Sucesso 1 - Erro	Numérico	Obrigatório	Int

Exemplos

Envio Lote de consulta (LoteConsulta)

{
    "IdRequisicao": "de932c6b-ce03-44bb-be39-4d7aff0d8aa3",
    "tipoConsulta": "3",
    "urlRetorno": "https://testeretornonfe.com.br/retornoNfe",
    "listaNfe": [
        {
            "nroNFe": "42160620677692000114550010000003491000000001"
        },
        {
            "nroNFe": "42160620677692000114550010000003491000000002"
        },
        {
            "nroNFe": "42160620677692000114550010000003491000000003"
        },
        {
            "nroNFe": "42160620677692000114550010000003491000000004"
        }
    ]
}

Retorno da requisição (RetornoSolicitacaoConsulta):

{
"mensagem": "O lote foi importado com sucesso e está em nossa fila para processamento",
"situacao": 0
}

DEFINIÇÕES DE RETORNO

O retorno da consulta NFe será enviado para a URL (WebService REST) que foi informada no lote de consulta.
Será utilizada a URL padrão parametrizada para o contratante caso essa informação não tenha sido especificada no lote de consulta enviado.

Retorno de consultas de Protocolo e de Eventos

Os tipos de consulta de Protocolo e de Eventos seguirão o mesmo padrão de retorno:

Retorno

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	IdRequisicao	Código identificador do lote	Alfanumérico	Obrigatório	String
2	Nfes	Lista contendo cada NFe e seus Eventos	Lista do tipo DadosNfe	Obrigatório	ICollection< DadosNfe >

DadosNfe

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	NumeroNfe	Código da chave NFe	Alfanumérico	Obrigatório	String
2	Eventos	Lista contendo os Eventos	Lista do tipo EventosNfe	Obrigatório	ICollection< EventosNfe >

EventosNfe

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	sequenceCode	Código sequencial do Evento	Numérico	Obrigatório	Int
2	eventCode	Código do Evento	Numérico	Obrigatório	Int
3	eventDescription	Descrição do Evento	Alfanumérico	Obrigatório	String
4	eventDate	Data do Evento	DateTime	Obrigatório	DateTime
5	protocolNumber	Protocolo do Evento	Numérico	Obrigatório	Int

Exemplo

{
    "IdRequisicao": "de932c6b-ce03-44bb-be39-4d7aff0d8aa3",
    "nfes": [
        {
            "numeroNfe": "42160620677692000114550010000003491000000001",
            "eventos": [
                {
                    "sequenceCode": "01",
                    "eventCode": "123",
                    "eventDescription": "desc do evento",
                    "eventDate": "2021-12-30T15:32:00",
                    "protocolNumber": "123666321"
                },
                {
                    "sequenceCode": "02",
                    "eventCode": "321",
                    "eventDescription": "desc do evento",
                    "eventDate": "2021-12-31T23:59:00",
                    "protocolNumber": "321000123"
                }
            ]
        },
        {
            "nfeNumber": "42160620677692000114550010000003491000000002",
            "events": [
                {
                    "sequenceCode": "01",
                    "eventCode": "123",
                    "eventDescription": "desc do evento",
                    "eventDate": "2021-12-30T15:32:00",
                    "protocolNumber": "123666321"
                },
                {
                    "sequenceCode": "02",
                    "eventCode": "321",
                    "eventDescription": "desc do evento",
                    "eventDate": "2021-12-31T23:59:00",
                    "protocolNumber": "321000123"
                }
            ]
        }
    ]
}

Retorno de consultas completas

Retorno

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	IdRequisicao	Código identificador do lote	Alfanumérico	Obrigatório	String
2	Nfes	Lista contendo cada NFe e seus Eventos	Lista do tipo DadosNfe	Obrigatório	ICollection< DadosNfe >

DadosNfe

Nota	Campo	Conteúdo/Significado	Tipo	Obrigatoriedade	Esquema
1	NumeroNfe	Código da chave NFe	Alfanumérico	Obrigatório	String
2	Arquivo	JSON no padrão SERPRO*, contendo os dados completos da NFe. Arquivo em Base64	Alfanumérico	Obrigatório	String

A estrutura do Json de retorno segue as mesmas especificações dos esquemas XML dos Web Services, disponibilizados no link NF-e

Exemplo

{
    "IdRequisicao": "de932c6b-ce03-44bb-be39-4d7aff0d8aa3",
    "nfes": [
        {
            "numeroNfe": "42160620677692000114550010000003491000000001",
            "arquivo": "{BASE64 DO ARQUIVO}"
        },
        {
            "numeroNfe": "42160620677692000114550010000003491000000002",
            "arquivo": "{BASE64 DO ARQUIVO}"
        }
    ]
}

Exemplos#

Retorno de consultas de Protocolo e de Eventos#

Exemplo#

Retorno de consultas completas#

Exemplo#

Exemplos

Retorno de consultas de Protocolo e de Eventos

Exemplo

Retorno de consultas completas

Exemplo