--- updatedAt: 2026-07-30T14:51:22.000Z agentTools: projectIndex: https://doc.focusnfe.com.br/llms.txt --- # Consultar Quando a receita informa que uma nota fiscal foi emitida contra a empresa, recebemos apenas um resumo do xml da nota fiscal com os dados mais importantes. Caso a nota seja [manifestada](/reference/manifestar_nfe_recebida), recebemos um xml com todos os dados da nota. Da mesma forma, a receita poderá notificar quando a nota recebe uma carta de correção ou quando ela é cancelada. Por isso as notas fiscais recebidas possuem um campo chamado "**versao**" que é único entre todos os documentos do mesmo CNPJ e que é atualizado a cada alteração nesta nota fiscal. Isto facilita a busca apenas dos documentos que seu sistema ainda não conhece, sendo necessário que você armazene apenas um número por CNPJ. **Exemplo**: Se você recebe uma nota fiscal, com versao = 60, e ela posteriormente receber uma carta de correção ou for cancelada, sua versão será atualizada para algum número maior que 60. **Este endpoint retorna as 100 primeiras notas encontradas**. Para recuperar as demais notas você deverá fazer uma nova requisição alterando o parâmetro versao. Para auxiliar o processo de consultar a API irá devolver os seguintes cabeçalhos HTTP: * **X-Total-Count**: O número total de registros (incluindo aqueles que não foram devolvidos pelo limite de 100 registros) * **X-Max-Version**: Valor máximo da versão dos documentos devolvidos. Utilize este cabeçalho para utilizar na próxima busca de versão, caso seja necessário. Como retorno você receberá os campos descritos nos exemplos abaixo, de acordo com o status da nota. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "NFe Recebidas", "version": "2.0.0", "contact": { "name": "Focus NFe Suporte", "email": "suporte@focusnfe.com.br" }, "license": { "name": "Proprietary", "url": "https://focusnfe.com.br" } }, "servers": [ { "url": "https://api.focusnfe.com.br/v2", "description": "Servidor de Produção" }, { "url": "https://homologacao.focusnfe.com.br/v2", "description": "Servidor de Homologação" } ], "security": [ { "BasicAuth": [] } ], "tags": [ { "name": "NFe Recebidas", "description": "Operações relacionadas às NFe recebidas e manifestação do destinatário (MDe)." } ], "paths": { "/nfes_recebidas": { "get": { "tags": [ "NFe Recebidas" ], "summary": "Consultar", "description": "Quando a receita informa que uma nota fiscal foi emitida contra a empresa, recebemos apenas um resumo do xml da nota fiscal com os dados mais importantes. Caso a nota seja [manifestada](/reference/manifestar_nfe_recebida), recebemos um xml com todos os dados da nota. Da mesma forma, a receita poderá notificar quando a nota recebe uma carta de correção ou quando ela é cancelada.\n\nPor isso as notas fiscais recebidas possuem um campo chamado \"**versao**\" que é único entre todos os documentos do mesmo CNPJ e que é atualizado a cada alteração nesta nota fiscal. Isto facilita a busca apenas dos documentos que seu sistema ainda não conhece, sendo necessário que você armazene apenas um número por CNPJ.\n\n**Exemplo**: Se você recebe uma nota fiscal, com versao = 60, e ela posteriormente receber uma carta de correção ou for cancelada, sua versão será atualizada para algum número maior que 60.\n\n**Este endpoint retorna as 100 primeiras notas encontradas**. Para recuperar as demais notas você deverá fazer uma nova requisição alterando o parâmetro versao. \n\nPara auxiliar o processo de consultar a API irá devolver os seguintes cabeçalhos HTTP:\n* **X-Total-Count**: O número total de registros (incluindo aqueles que não foram devolvidos pelo limite de 100 registros)\n* **X-Max-Version**: Valor máximo da versão dos documentos devolvidos. Utilize este cabeçalho para utilizar na próxima busca de versão, caso seja necessário.\n\nComo retorno você receberá os campos descritos nos exemplos abaixo, de acordo com o status da nota.\n", "operationId": "consultar_nfes_recebidas", "parameters": [ { "name": "cnpj", "in": "query", "required": true, "description": "CNPJ da empresa recebedora", "schema": { "type": "string", "example": "12345678000123" } }, { "name": "versao", "in": "query", "required": false, "description": "Busca apenas os documentos cuja versão seja maior que o parâmetro recebido. Utilize este parâmetro para buscar apenas as notas que seu sistema ainda não conhece.", "schema": { "type": "number", "example": 1 } }, { "name": "pendente", "in": "query", "required": false, "description": "Lista apenas as notas que estão pendentes de manifestação final. São consideradas notas pendentes aquelas que não tem manifesto ou tem apenas manifesto de ciência (não havendo o manifesto final de operação de confirmação, desconhecimento ou operação não realizada)", "schema": { "type": "number", "example": 1 } }, { "name": "pendente_ciencia", "in": "query", "required": false, "description": "Lista apenas as notas que não tem a operação de ciência registrada", "schema": { "type": "number", "example": 1 } } ], "responses": { "200": { "description": "Requisição processada com sucesso", "headers": { "X-Total-Count": { "description": "O número total de registros (incluindo aqueles que não foram devolvidos pelo limite de 100 registros)", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "example": 10 } }, "X-Max-Version": { "description": "Valor máximo da versão dos documentos devolvidos. Utilize este cabeçalho para utilizar na próxima busca de versão, caso seja necessário", "schema": { "type": "integer", "minimum": 0, "example": 2 } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NfeRecebidaResumo" } }, "example": [ { "nome_emitente": "Empresa emitente Ltda.", "documento_emitente": "12345678000123", "chave_nfe": "41171179060190000182550010000002661875685069", "valor_total": "24560.00", "data_emissao": "2017-11-07T01:00:00-02:00", "situacao": "autorizada", "manifestacao_destinatario": "ciencia", "nfe_completa": true, "tipo_nfe": "1", "versao": 73, "digest_value": "/C5IuK5fCNVQV2rbwV0d8W12zsk=", "numero_carta_correcao": "1", "carta_correcao": "Algum texto da carta de correção.", "data_carta_correcao": "2017-11-07T14:31:48-02:00", "data_cancelamento": "2017-11-07T14:45:14-02:00", "justificativa_cancelamento": "Nota cancelada por algum motivo" }, { "nome_emitente": "Empresa emitente Ltda.", "documento_emitente": "12345678000123", "chave_nfe": "41171179060190000182550010000002661875685069", "valor_total": "24560.00", "data_emissao": "2017-11-07T01:00:00-02:00", "situacao": "autorizada", "manifestacao_destinatario": "ciencia", "nfe_completa": true, "tipo_nfe": "1", "versao": 73, "digest_value": "/C5IuK5fCNVQV2rbwV0d8W12zsk=", "numero_carta_correcao": "1", "carta_correcao": "Algum texto da carta de correção.", "data_carta_correcao": "2017-11-07T14:31:48-02:00", "data_cancelamento": "2017-11-07T14:45:14-02:00", "justificativa_cancelamento": "Nota cancelada por algum motivo" } ] } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "codigo": "requisicao_invalida", "mensagem": "CNPJ do emitente não autorizado ou não informado" } } } }, "401": { "$ref": "#/components/responses/AccessDenied" }, "403": { "description": "Ação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "codigo": "permissao_negada", "mensagem": "CNPJ do emitente não autorizado." } } } } } } } }, "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "Autenticação com usuário e senha (HTTP Basic). O usuário é o token da API e a senha deve ser deixada em branco." } }, "responses": { "AccessDenied": { "description": "Não autorizado", "content": { "text/html": { "schema": { "type": "string", "example": "HTTP Basic: Access denied" } } } } }, "schemas": { "NfeRecebidaResumo": { "title": "NFe recebida resumo", "type": "object", "properties": { "nome_emitente": { "type": "string", "description": "Nome do emitente da nota fiscal", "example": "EMPRESA FORNECEDORA LTDA" }, "documento_emitente": { "type": "string", "description": "CNPJ ou CPF do emitente da nota fiscal", "example": "123456780001233" }, "cnpj_destinatario": { "type": "string", "description": "CNPJ do destinatário da nota fiscal (o CNPJ de sua empresa)", "example": "123456780001234" }, "chave_nfe": { "type": "string", "description": "Chave da NFe", "example": "35122225222278000855550010000002821510931504" }, "valor_total": { "type": "string", "description": "Valor total da NFe", "example": "100.00" }, "data_emissao": { "type": "string", "format": "date-time", "description": "Data e hora de emissão da NFe", "example": "2024-01-15T10:00:00-03:00" }, "situacao": { "type": "string", "description": "Situação da NFe", "enum": [ "autorizada", "cancelada", "denegada" ], "example": "autorizada" }, "manifestacao_destinatario": { "type": "string", "description": "Situação atual da manifestação do destinatário:\n- **nulo**: Se não houve manifestação ainda\n- **ciencia**: Se foi confirmada a ciência da operação\n- **confirmacao**: Se foi manifestado confirmação da operação\n- **desconhecimento**: Se foi manifestado desconhecimento da operação\n- **nao_realizada**: Se foi manifestado que operação é conhecida, porém por algum motivo não foi realizada\n", "enum": [ "nulo", "ciencia", "confirmacao", "desconhecimento", "nao_realizada" ], "example": "ciencia" }, "nfe_completa": { "type": "string", "description": "Se verdadeiro, indica que temos o XML completo da nota, caso contrário o sistema possui apenas o cabeçalho da nota", "example": "12345678000123" }, "tipo_nfe": { "type": "string", "description": "Tipo da NFe:\n- 1: Saída\n- 0: Entrada\n", "enum": [ "1", "0" ], "example": "1" }, "versao": { "type": "number", "description": "Versão da nota fiscal. Este número irá mudar apenas se a nota fiscal for alterada de alguma forma", "example": 73 }, "digest_value": { "type": "string", "description": "Valor do resumo digital do XML da nota", "example": "/C5IuK5fCNVQV2rbwV0d8W12zsk=" }, "numero_carta_correcao": { "type": "string", "description": "Número sequencial da carta de correção, caso tenha sido emitida alguma", "example": "1" }, "carta_correcao": { "type": "string", "description": "Texto da carta de correção, caso tenha sido emitida alguma", "example": "Campo valor informado incorretamente. Onde lê-se R$ 100.00, deve ler-se R$ 100000,00." }, "data_carta_correcao": { "type": "string", "format": "date-time", "description": "Data da carta de correção, caso tenha sido emitida alguma", "example": "2024-01-15T10:00:00-03:00" }, "data_cancelamento": { "type": "string", "format": "date-time", "description": "Data de cancelamento da nota fiscal, caso ela tenha sido cancelada", "example": "2024-01-15T10:00:00-03:00" }, "justificativa_cancelamento": { "type": "string", "description": "Justificativa de cancelamento da nota fiscal, caso ela tenha sido cancelada", "example": "Venda cancelada" } } }, "ErrorResponse": { "title": "Erro", "type": "object", "properties": { "codigo": { "type": "string", "description": "Código do erro" }, "mensagem": { "type": "string", "description": "Mensagem do erro" } } } } } } ```