Verificación de NF-e
Verificación de XML
Envía el XML de la NF-e; devuelve el veredicto de nivel 1 y los datos de la factura e inicia la verificación en la SEFAZ.
/openapi/v3/consultas/nf-e/xmltoken, timestamp y sign, vea Autenticación.Envía el XML sin procesar de la NF-e. Devuelve de forma síncrona el veredicto de nivel 1 y los datos de la factura ya interpretados; si el nivel 1 se aprueba, la verificación de nivel 2 en la SEFAZ empieza automáticamente y el veredicto final llega por el webhook invoice.verify.completed (vea Verificación de NF-e).
HTTP 200 significa que la solicitud fue aceptada, no que la factura fue aprobada. Un XML bien formado que no supera la validación también devuelve 200; el veredicto está en el bloque validation. Nunca decida la validez por el estado HTTP.
Cabeceras
Content-Type* | string | Tipo del cuerpo |
forceRevalidate | bool | Nueva verificación forzada |
* Campo obligatorio
validation con el veredicto de nivel 1. Incluye los casos en que la validación falló: compruebe validation.validationStatus y validation.errors.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 de nivel 1 |
- Preferible: el documento completo autorizado por la SEFAZ, con el protocolo de autorización. Una factura sin el protocolo también se acepta: genera un aviso
PROTOCOL_MISSING, pero se procesa con normalidad. - Límites estrictos: máximo 1 MB, solo UTF-8, DTD prohibido (cualquier
<!DOCTYPEse rechaza de inmediato). - Firma: el cuerpo participa en la firma tras eliminar todos los CR y LF, mientras que el cuerpo enviado permanece sin cambios:
sign = md5Hex(app_secret + "/openapi/v3/consultas/nf-e/xml" + xmlSinCrLf + timestamp)
La cabecera forceRevalidate no participa en la firma. Reglas completas en Autenticación.
El itens[].valorTotal de cada línea es el importe bruto de la línea, antes del descuento; el valorTotal de la raíz es el total neto de la factura, tras el descuento. La diferencia es el descuento total.
Importes y cantidades son números JSON tomados del documento sin ceros finales: 100.00 se devuelve como 100 y 94.90 como 94.9. Deles formato al mostrarlos. Los campos sin valor en el documento se omiten, nunca se devuelven como null.
El nivel 1 se decide en el momento y se devuelve en esta respuesta; el nivel 2 es la verificación en la SEFAZ y llega solo por el webhook. Los valores de validationStatus y de errors[].code están en las tablas de enumeraciones al final de la página.
Nivel 1 rechazado en la respuesta síncrona
HTTP 200 con validationStatus = REJECTED y al menos un elemento en errors. Es terminal: no hay nivel 2 y la nueva verificación exige reenviar el XML: un XML corregido se verifica de nuevo automáticamente; reenviar el mismo XML dentro de las 24 horas requiere forceRevalidate: true.
"validation": {"fileAccessible": true,"xmlWellFormed": true,"schemaValid": true,"signatureValid": false,"accessKeyValid": true,"protocolPresent": true,"protocolValid": true,"xmlVersion": "4.00","validationStatus": "REJECTED","validationStatusDescription": "Verification failed","errors": [ { "code": "SIGNATURE_INVALID", "field": "Signature", "message": "Digital signature verification failed: ..." } ],"warnings": []}
Nivel 2 por el webhook
Una vez aprobado el nivel 1 (PENDING_SEFAZ), el veredicto final llega por el webhook invoice.verify.completed con VALIDATED, REJECTED o VALIDATION_ERROR; cabeceras, carga y requisitos del receptor están en Verificación de NF-e. Si se pierde una entrega, la consulta por chave devuelve el validationStatus actual. No son errores HTTP.
- La verificación de XML es idempotente por la chave: mientras el nivel 2 está en curso, reenviar devuelve el progreso actual y no inicia otra comprobación;
forceRevalidate: truetampoco la reinicia ni la acelera. - Si el contenido cambia, se verifica de nuevo automáticamente: si el XML que envía para una chave no es el mismo que el anterior (comparado byte a byte), no se reutiliza nada y se ejecutan de nuevo el nivel 1 y el nivel 2 completos; no hace falta
forceRevalidate. La excepción son las facturas canceladas / denegadas / inutilizadas: su veredicto no cambia, así que se devuelve el resultado anterior aunque el contenido sea distinto. El punto anterior y la tabla siguiente solo aplican a reenvíos con contenido idéntico. - Los veredictos terminales se reutilizan según la tabla: un veredicto reutilizado se devuelve tal cual, sin consultar a la SEFAZ y sin un evento de webhook nuevo.
| Veredicto existente | Reenvío normal | Con forceRevalidate: true |
|---|---|---|
Cancelada / denegada / inutilizada (REJECTED con status Cancelada / Denegada / Inutilizada) | Se reutiliza mientras la plataforma conserve el registro de la verificación | Se sigue reutilizando: estas situaciones ya no cambian |
La SEFAZ no acepta consultas (VALIDATION_ERROR con status Desconhecida, por ejemplo cStat 526) | Se reutiliza mientras la plataforma conserve el registro de la verificación | Nueva verificación completa (nivel 1 + nivel 2) |
Cualquier otro veredicto (VALIDATED, los demás REJECTED y VALIDATION_ERROR) | Se reutiliza durante 24 horas desde el momento en que se obtuvo; después, nueva verificación completa | Nueva verificación completa (nivel 1 + nivel 2) |
- Cuando la plataforma ya no conserva el registro de la verificación, un nuevo envío se trata como un primer envío.
- Una respuesta reutilizada refleja el XML enviado originalmente con el
validationStatusactual; un XML corregido para la misma chave se verifica de nuevo automáticamente (salvo las facturas canceladas / denegadas / inutilizadas, cuyo veredicto no cambia). - Nueva verificación forzada: envíe la cabecera
forceRevalidate: true; según la tabla anterior, omite la reutilización, y el nuevo veredicto llega como un nuevo evento de webhook. La consulta por chave no puede forzar una comprobación y nunca la programa para las dos primeras filas de la tabla. - Un
REJECTEDbloqueante de nivel 1 no tiene registro de nivel 2; para verificar de nuevo, reenvíe el XML: un XML corregido se verifica de nuevo automáticamente; reenviar el mismo XML dentro de las 24 horas requiereforceRevalidate: true. - Las verificaciones pertenecen a su cuenta de integrador: que otro integrador verifique la misma factura no afecta a la suya, y cada cuenta recibe su propio veredicto.
Content-TypeTipo del cuerpo (cabecera)
| Valores | Significado |
|---|---|
| application/xml | Cuerpo XML |
| text/xml | Cuerpo XML; equivalente |
forceRevalidateNueva verificación forzada (cabecera)
Omitido vale false.
| Valores | Significado |
|---|---|
| true | Omite la reutilización y verifica de nuevo desde cero; los veredictos de factura cancelada, denegada o inutilizada se siguen reutilizando |
| false | Devuelve el veredicto terminal reutilizable, si lo hay: los de factura cancelada, denegada o inutilizada y aquellos en que la SEFAZ no acepta consultas valen mientras la plataforma conserve el registro, los demás durante 24 horas |
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; también cuando la SEFAZ no acepta consultas de la factura (por ejemplo, cStat 526) |
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 |
emitente.endereco.uf / destinatario.endereco.ufEstado
Copiado de la factura sin conversión.
| Valores | Significado |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
| EX | Exterior; solo en el destinatario |
itens[].cfopNaturaleza fiscal de la operación del ítem
4 dígitos, copiados de la factura. El primer dígito indica dirección y alcance; la lista completa es la tabla CFOP del Convênio s/nº de 1970, publicada en el Portal de la NF-e.
| Valores | Significado |
|---|---|
| 1xxx | Entrada dentro del estado |
| 2xxx | Entrada desde otro estado |
| 3xxx | Entrada desde el exterior |
| 5xxx | Salida dentro del estado |
| 6xxx | Salida hacia otro estado |
| 7xxx | Salida al exterior |
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 | Verificación no completada; terminal, no es un juicio sobre la factura. Dos tipos: limitación de la SEFAZ, fallos de consulta tras los reintentos o SEFAZ no disponible durante mucho tiempo, se reutiliza 24 horas, reenvíe más tarde con forceRevalidate: true; la SEFAZ no acepta consultas de la factura (por ejemplo, cStat 526), status Desconhecida, se reutiliza mientras la plataforma conserve el registro y reenviar no lo cambiará |
validation.errors[].code / validation.warnings[].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) |
validation.xmlVersionVersión del layout
Otras versiones se rechazan con XML_VERSION_UNSUPPORTED.
| Valores | Significado |
|---|---|
| 4.00 | Layout vigente de la NF-e y de la NFC-e |
| Código | HTTP | |
|---|---|---|
| 10015000 | 400 | Cuerpo de la solicitud vacío. Envíe el XML en el cuerpo. |
| 10015001 | 400 | El cuerpo supera 1 MB. Compruebe que no la está envolviendo ni codificando dos veces. |
| 10015002 | 400 | DTD detectado (<!DOCTYPE). Elimine los DTD. |
| 10015003 | 400 | La codificación no es UTF-8. Convierta a UTF-8 antes de enviar. |
