Verificación de NF-e
Consulta por chave
Devuelve los datos de la factura para una clave de acceso de 44 dígitos y, si usted envió esa chave a verificación, el veredicto actual.
/openapi/v3/consultas/nf-e/{chave}token, timestamp y sign, vea Autenticación.Devuelve los datos de la factura para una clave de acceso de 44 dígitos. Para una chave enviada por la verificación de XML, la respuesta también trae el bloque validation con el validationStatus actual: úselo como alternativa de sondeo cuando se pierda una entrega del webhook invoice.verify.completed (vea Verificación de NF-e). Las facturas encontradas solo en la emisión de la plataforma o en la fuente oficial no se verificaron y llegan sin ese bloque.
Parámetros de ruta
chave* | string | Clave de acceso |
* Campo obligatorio
validation solo viene para chaves enviadas por allí.tipo | string | Tipo de documento |
modelo | string | Modelo del documento |
status | string | Situación fiscal |
statusDescription | string | Descripción del estado |
ambienteEmissao | string | Ambiente de emisión |
numero | string | Número de la factura |
serie | string | Serie |
dataEmissao | string | Fecha de emisión |
tipoOperacao | string | Tipo de operación (tpNF), el sentido de la mercancía visto por el emisor |
chaveAcesso | string | Clave de acceso |
| object | Emisor |
| object | Destinatario |
| array | Ítems |
dataAutorizacao | string | Fecha de autorización |
| object | Protocolo de autorización |
valorTotal | number | Importe neto de la factura |
| object | Veredicto actual de la verificación |
Con app_secret = sk_live_9f8e7d6c5b4a, la chave 35260764962869000108550990001366171195929648 y timestamp = 1784906308, la cadena firmada es (GET, cuerpo vacío; la chave está en la ruta):
sign_input = "sk_live_9f8e7d6c5b4a"+ "/openapi/v3/consultas/nf-e/35260764962869000108550990001366171195929648"+ ""+ "1784906308"sign = md5Hex(sign_input)
La plataforma resuelve la chave por los niveles siguientes, en este orden; se devuelve el primer acierto.
Ya enviada para verificación
La plataforma conserva el registro de la verificación de XML y devuelve los datos completos de la factura más el bloque validation con el validationStatus actual.
Factura emitida por esta plataforma
Datos completos interpretados del XML autorizado, sin bloque validation.
Chave desconocida
Datos autorizados completos obtenidos de la fuente oficial, según la política de la plataforma, sin bloque validation.
Sin acierto en ninguna fuente
HTTP 400 con 10015004. Una chave malformada devuelve 10015104 sin consultar ninguna fuente.
{ "code": 10015004, "message": "Invoice not found: 35260764962869000108550990001366171195929648" }
- Alternativa de sondeo: para una chave enviada por la verificación de XML, el bloque
validationtrae elvalidationStatusactual (PENDING_SEFAZ,VALIDATINGo el veredicto final). Úselo cuando se pierda una entrega del webhookinvoice.verify.completed. - Comprobación en segundo plano: cuando la última respuesta de la SEFAZ para esa chave tiene más de 24 horas, la consulta programa una nueva verificación de nivel 2 (salvo facturas ya
Cancelada,DenegadaoInutilizada, cuya situación ya no cambia). Esa respuesta ya muestravalidationStatus=VALIDATINGy el nuevo veredicto llega por el webhook como un evento nuevo. - Sin nueva verificación forzada: este endpoint no puede forzar una comprobación. Para ello, reenvíe el XML por la verificación de XML con la cabecera
forceRevalidate: true.
tipoTipo de documento
| Valores | Significado |
|---|---|
| NF-e | Factura electrónica usada entre empresas y en ventas con entrega |
| NFC-e | Factura electrónica al consumidor, venta en mostrador |
modeloModelo del documento
| Valores | Significado |
|---|---|
| 55 | NF-e |
| 65 | NFC-e |
statusSituación fiscal
| Valores | Significado |
|---|---|
| Autorizada | Autorizada por la SEFAZ y sin evento de cancelación |
| Cancelada | Cancelada, incluso por cancelación sustitutiva |
| Denegada | Denegada por la SEFAZ |
| Inutilizada | Numeración inutilizada |
| NaoEncontrada | No encontrada en la SEFAZ; puede ser retraso de sincronización |
| Desconhecida | Situación no clasificable a partir de la respuesta de la SEFAZ |
ambienteEmissaoAmbiente de emisión
| Valores | Significado |
|---|---|
| Producao | Ambiente oficial |
| Homologacao | Ambiente de prueba de la SEFAZ; la factura no tiene validez |
tipoOperacaoTipo de operación
| Valores | Significado |
|---|---|
| Saida | Salida de mercancía del emisor (tpNF=1), como una venta |
| Entrada | Entrada de mercancía en el emisor (tpNF=0), como una devolución del consumidor o una importación |
validation.validationStatusEstado de la verificación
La primera respuesta síncrona trae solo PENDING_SEFAZ o REJECTED; los demás llegan por el webhook invoice.verify.completed y también aparecen en respuestas reutilizadas y en la consulta por chave.
| Valores | Significado |
|---|---|
| PENDING_SEFAZ | Nivel 1 aprobado, verificación en la SEFAZ en cola |
| REJECTED | Rechazada; terminal. En el nivel 1 por error bloqueante, en el nivel 2 por la situación en la SEFAZ (cancelada, denegada, inutilizada, no encontrada, protocolo divergente); no continúe |
| VALIDATING | Nivel 2 en curso, consultando a la SEFAZ |
| VALIDATED | Factura auténtica y regular en la SEFAZ; terminal, seguro continuar |
| VALIDATION_ERROR | Fallo técnico del lado de la plataforma, no es un juicio sobre la factura; se reutiliza 24 horas como cualquier veredicto, reenvíe más tarde con forceRevalidate: true |
validation.errors[].codeCódigos de problema de nivel 1
Todos son bloqueantes y llevan a REJECTED, salvo PROTOCOL_MISSING, que va a warnings[]. El número entre paréntesis es el código numérico equivalente.
| Valores | Significado |
|---|---|
| XML_MALFORMED | Sintaxis XML inválida (10015100) |
| XSD_INVALID | No conforme al layout oficial de la NF-e 4.00 (10015101) |
| SIGNATURE_INVALID | Firma digital inválida: contenido alterado o certificado caducado al firmar (10015102) |
| SIGNATURE_CERT_MISMATCH | CNPJ del certificado de firma distinto del emisor (10015103) |
| ACCESS_KEY_INVALID | Estructura o dígito verificador de la clave inválidos (10015104) |
| ACCESS_KEY_MISMATCH | Segmentos de la clave distintos de los campos del documento (10015105) |
| PROTOCOL_MISMATCH | Protocolo de autorización incoherente con la factura (10015106) |
| PROTOCOL_MISSING | Sin protocolo de autorización; aviso, no bloquea (10015107) |
| XML_VERSION_UNSUPPORTED | Versión del layout distinta de 4.00 (10015108) |
| Código | HTTP | |
|---|---|---|
| 10015104 | 400 | Chave malformada (longitud / caracteres / dígito verificador). Se rechaza localmente, sin realizar consulta. |
| 10015004 | 400 | Factura no encontrada en ninguna fuente. La chave es desconocida para la plataforma y para la fuente oficial; confirme la chave con el emisor. No debe confundirse con el estado NaoEncontrada del nivel 2, que es la respuesta 217 de la SEFAZ. |