API de validación de documentos XML

Validación de comprobantes electrónicos SRI (Ecuador) y SUNAT (Perú) en una llamada HTTP. Stateless — no se almacena el XML.

• 1
  Esquema XSD oficial del SRI y SUNAT.
• 2
  Firma XAdES, cadena de confianza y vencimiento del certificado.
• 3
  Reglas de negocio: Ficha Técnica SRI v2.32, Reglas SUNAT v2.0.
• 4
  Cálculos tributarios: catálogo IVA/IGV e identidad valor = base × tarifa/100.
• 5
  Estado fiscal: autorizacionComprobante (SRI), validarcomprobante (SUNAT).
• 6
  Estado del emisor: catastro obtenerPorNumerosRuc (SRI), estado_ruc y cond_domicilio (SUNAT).

curl https://detecno.datil.tax/v1/validations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "country": "ec",
    "xml": "<factura ...>...</factura>"
  }'

Validaciones

Cada capa se ejecuta de forma independiente: una puede fallar sin detener a las demás, y la respuesta detalla el resultado de cada una por separado.

Parseo XML

Verifica que el documento sea XML bien formado y que la codificación declarada coincida con el contenido. La resolución de entidades externas y la carga de DTDs remotos están deshabilitadas.

Esquema XSD

Valida el documento contra los XSD oficiales publicados por el SRI (Ecuador) y la SUNAT (Perú). Cada error incluye la línea, el código y el mensaje del validador, sin reescritura.

Firma electrónica (XAdES-BES)

Comprueba la presencia de ds:Signature, la integridad del digest, la cadena de confianza hasta una autoridad de certificación reconocida, y la vigencia del certificado al momento de la fecha_emision del comprobante (no al momento del request).

Reglas de negocio

Ecuador: Ficha Técnica del SRI v2.32 — clave de acceso, dígito verificador módulo 11, secuencial y campos obligatorios por tipo de comprobante. Perú: Reglas SUNAT v2.0 sobre UBL 2.1. Cada falla incluye un código, una ruta XPath y un mensaje.

Cálculos tributarios

Esta capa cubre únicamente el IVA (código 2 del catálogo del SRI). Para cada nodo <impuesto> con codigo=2 se verifica:

• El codigoPorcentaje existe en el catálogo 24 vigente.
• La tarifa declarada coincide con la del catálogo.
• valor = baseImponible × tarifa / 100, con tolerancia de redondeo.
• A nivel documento, importeTotal ≈ totalSinImpuestos + Σ impuestos.

Los demás impuestos (ICE código 3, IRBPNR código 5, entre otros) se ignoran en esta capa: no se les aplica la verificación aritmética y no generan warnings ni errores. Si el documento usa un codigoPorcentaje de IVA que no está en el catálogo, se emite un warning (EC-IVA-CODE-UNKNOWN); la validación no falla por sí sola.

Estado fiscal

Consulta en línea a la autoridad emisora. Ecuador: autorizacionComprobante del SRI con la clave de acceso de 49 dígitos. Perú: validarcomprobante de la SUNAT con RUC, tipo, serie, número, fecha y monto. Si la consulta falla por timeout o indisponibilidad de la autoridad, el error se reporta bajo tax_status.error y el resto del veredicto no se ve afectado.

Estado del emisor

Estado del RUC del emisor en ambos países. Ecuador: consulta independiente al catastro del SRI (obtenerPorNumerosRuc) — devuelve ACTIVO, SUSPENDIDO, PASIVO o BAJA DEFINITIVA. Perú: los campos estado_ruc y cond_domicilio ya forman parte de la respuesta de validarcomprobante, por lo que no se hace una segunda consulta.

{
  "valid": true,
  "parsed":        true,
  "schema":        { "ok": true, "errors": [] },
  "signature":     { "present": true,
                     "integrity_ok": true,
                     "chain_trusted": true },
  "rules":         { "ok": true,
                     "errors": [], "warnings": [] },
  "calculations":  { "ok": true, "errors": [] },
  "tax_status":    { "accepted": true,
                     "state": "AUTORIZADO" },
  "issuer_status": { "status": "ACTIVO" }
}

# Documento bien formado, firma sin cadena confiable,
# autorizado por SRI igualmente.
parsed        ✓
schema        ✓
signature     ✗   chain_trusted: false
rules         ✓
calculations  ✓
tax_status    ✓   AUTORIZADO
issuer_status ✓   ACTIVO

valid         ✗   # porque la firma falló

Autenticación

Bearer token en la cabecera Authorization. Prefijos sk_live_ (producción) y sk_test_ (pruebas). HTTPS obligatorio.

Authorization: Bearer sk_live_4f8a...c21b

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se proporcionó un API key."
  }
}

URL base

https://detecno.datil.tax

POST /v1/validations    # Validar un documento XML

Convenciones

• JSON, UTF-8. Content-Type y Accept: application/json.
• Fechas. ISO 8601 UTC (2026-05-06T14:23:11Z).
• Montos. Decimales en la moneda del documento, sin separadores de miles.
• Idempotente salvo cambios de estado en SRI/SUNAT.
• request_id en cada respuesta para soporte.

Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Bearer sk_live_...

El objeto validation

Campo	Tipo	Descripción
object	string	Siempre "validation".
request_id	string	Identificador de la solicitud.
country	string	ec, pe.
valid	boolean	true sólo si pasan todas las verificaciones solicitadas.
validated_at	string	ISO 8601 UTC.
document	object	Forma unificada EC + PE. Detalle abajo.
checks	object	Resumen booleano. Catálogo.
failure	object	Sólo si valid: false. {stage, code, message}. Catálogo.
errors	array	{source, code, message, path?}.
warnings	array	No afectan valid. Misma forma que errors.

El objeto document — campo por campo

Campos vacíos se omiten. La columna Origen marca aplicabilidad EC / PE.

Identificadores del documento

Campo	Tipo	Origen	Descripción
type	string	EC, PE	Tipo, sin prefijo de país. Ver catálogo.
serial	string	EC, PE	EC: estab-ptoEmi-secuencial (ej. 001-001-000000123). PE: cbc:ID tal cual (ej. F001-001).
issue_date	string	EC, PE	EC: dd/mm/yyyy (formato SRI). PE: yyyy-mm-dd (ISO 8601).
environment	string, null	EC, PE	"live", "test", null. Ver catálogo.

document.issuerEmisor

Campo	Tipo	Descripción
issuer.id	string	RUC del emisor. EC: 13 dígitos. PE: 11 dígitos.
issuer.name	string	Razón social del emisor.

document.signatureFirma electrónica

Presente sólo si el documento lleva firma XAdES.

Campo	Tipo	Descripción
signature.signed_at	string	Fecha de la firma, ISO 8601 con offset.
signature.signer	string	Common Name del certificado firmante.
signature.certificate	object	Detalle del certificado X.509 usado para firmar.

document.signature.certificate

Campo	Tipo	Descripción
certificate.serial	string	Serial hex con separadores : (ej. 01:23:45:67).
certificate.subject	object	DN del titular. Ver desglose abajo.
certificate.issuer	object	DN de la AC emisora. Mismo desglose que subject.
certificate.not_before	string	Inicio de validez (ISO 8601 UTC).
certificate.not_after	string	Fin de validez (ISO 8601 UTC).
certificate.signature_algorithm	string	Algoritmo de firma (ej. "SHA-256 with RSA").
certificate.key_usage	array<string>	Usos permitidos ("Digital Signature", "Non Repudiation", …).
certificate.extended_key_usage	array<string>	EKU declarados.
certificate.subject_alt_names	array<string>	SAN (DNS, email, URI…) prefijado con su tipo.
certificate.crl_urls	array<string>	Puntos de distribución de CRL.
certificate.ocsp_urls	array<string>	Endpoints OCSP del emisor.
certificate.policies	array<string>	OIDs de políticas de certificación.
certificate.thumbprint_sha256	string	Huella SHA-256 del certificado, hex con :.

certificate.subject y certificate.issuerDistinguished Name

Campo	Tipo	Descripción
common_name (CN)	string	Nombre común del titular o de la AC.
id_number	string	Cédula, DNI, RUC del titular (extraído de OID 2.5.4.45 o serialNumber).
organization (O)	string	Organización titular del certificado.
organizational_unit (OU)	string	Unidad organizacional.
country (C)	string	País, código ISO de 2 letras.
state (ST)	string	Provincia, departamento.
locality (L)	string	Ciudad.
email	string	Email asociado al titular (si está declarado).
raw	string	DN crudo, formato RFC 2253.

document.tax_statusEstado fiscal

Presente sólo si se incluyó tax_status en checks.

Campo	Tipo	Origen	Descripción
tax_status.authority	string	EC, PE	"sri", "sunat".
tax_status.status	object	EC, PE	{accepted, code, label}. Códigos en catálogo.
tax_status.status.accepted	boolean, null	EC, PE	true sólo si la autoridad lo autorizó. null si la consulta falló.
tax_status.status.code	string	EC, PE	Código literal de la autoridad (ej. AUTORIZADO, ACEPTADO).
tax_status.status.label	string	EC, PE	Etiqueta legible en español.
tax_status.authorized_at	string	EC	Fecha de autorización SRI (ISO 8601 con offset). SUNAT no la expone.
tax_status.number	string	EC	Número de autorización del SRI (= claveAcceso en e-fact 2.x).
tax_status.environment	string	EC	Entorno reportado por SRI: "live", "test".
tax_status.messages	array<object>	EC, PE	Avisos de la autoridad: {id, type, text, details}.
tax_status.details	object	EC, PE	Datos crudos. PE: estado_cp, estado_ruc, cond_domicilio, etc. EC: numero_comprobantes.
tax_status.error	string	EC, PE	Motivo si la consulta no se pudo completar (timeout, credenciales, RUC sin enrolar).

document.sriSólo Ecuador

Campo	Tipo	Descripción
sri.access_key	string	claveAcceso de 49 dígitos.
sri.version	string	Versión del esquema XSD (atributo version de la raíz).
sri.ambiente	string	"1" (pruebas), "2" (producción), tal cual viene en el XML.

document.sunatSólo Perú

Campo	Tipo	Descripción
sunat.ubl_version	string	cbc:UBLVersionID (ej. "2.1").
sunat.customization	string	cbc:CustomizationID (ej. "2.0").

{
  "object": "validation",
  "request_id": "req_01HXY2K9P3M7T8B",
  "country": "pe",
  "valid": true,
  "validated_at": "2026-05-06T14:23:11Z",
  "document": {
    "type":       "invoice",
    "serial":     "F001-001",
    "issue_date": "2026-04-01",
    "issuer": {
      "id":   "20100000001",
      "name": "EMPRESA DEMO PERU S.A.C."
    },
    "signature": {
      "signed_at":   "2026-05-05T08:14:02Z",
      "signer":      "MARIA RODRIGUEZ EJEMPLO",
      "certificate": {
        "serial":              "0A:0B:0C:0D",
        "subject": {
          "common_name":         "EMPRESA DEMO PERU S.A.C.",
          "id_number":           "20100000001",
          "organization":        "EMPRESA DEMO PERU S.A.C.",
          "organizational_unit": "FACTURACION ELECTRONICA",
          "country":             "PE",
          "locality":            "LIMA"
        },
        "issuer": {
          "common_name":         "AC DEMO PE",
          "organization":        "DEMO CERTIFICADORA PE S.A.C.",
          "organizational_unit": "AUTORIDAD DE CERTIFICACION",
          "country":             "PE",
          "locality":            "LIMA"
        },
        "not_before":          "2025-09-12T15:21:08Z",
        "not_after":           "2027-09-12T15:21:08Z",
        "signature_algorithm": "SHA-256 with RSA",
        "key_usage":           ["Digital Signature", "Non Repudiation"],
        "subject_alt_names":   ["Email: firmas@empresa-demo.example.pe"],
        "crl_urls":            ["http://crl.example.pe/demo.crl"],
        "ocsp_urls":           ["http://ocsp.example.pe"],
        "policies":            ["2.16.604.1.99999.1"],
        "thumbprint_sha256":   "AA:BB:CC:DD:EE:FF:00:11:..."
      }
    },
    "tax_status": {
      "authority": "sunat",
      "status": {
        "accepted": true,
        "code":     "ACEPTADO",
        "label":    "Aceptado"
      },
      "messages": [],
      "details": {
        "estado_cp":           "1",
        "estado_ruc":          "00",
        "estado_ruc_label":    "Activo",
        "cond_domicilio":      "00",
        "cond_domicilio_label": "Habido"
      }
    },
    "sunat": {
      "ubl_version":   "2.1",
      "customization": "2.0"
    }
  },
  "checks": {
    "format":     true,
    "signature":  true,
    "tax_status": true
  }
}

Catálogo de valores

Identificadores snake_case, estables dentro de v1.x. Nuevos valores se agregan de forma aditiva.

document.type

Valor	País	Documento	Raíz XML
invoice	EC	Factura	<factura>
credit_note	EC	Nota de crédito	<notaCredito>
debit_note	EC	Nota de débito	<notaDebito>
withholding	EC	Comprobante de retención	<comprobanteRetencion>
liquidation	EC	Liquidación de compra	<liquidacionCompra>
waybill	EC	Guía de remisión	<guiaRemision>
invoice	PE	Factura (B2B, InvoiceTypeCode=01)	<Invoice>
receipt	PE	Boleta de venta (B2C, InvoiceTypeCode=03)	<Invoice>
credit_note	PE	Nota de crédito	<CreditNote>
debit_note	PE	Nota de débito	<DebitNote>
waybill	PE	Guía de remisión electrónica	<DespatchAdvice>
application_response	PE	CDR, respuesta SUNAT	<ApplicationResponse>
voided_documents	PE	Comunicación de baja	<VoidedDocuments>
summary_documents	PE	Resumen diario	<SummaryDocuments>
withholding	PE	Comprobante de retención	<Retention>
perception	PE	Comprobante de percepción	<Perception>

country

Valor	Significado
ec	Ecuador — SRI
pe	Perú — SUNAT

document.environment

Convención Stripe-style. Indica el entorno bajo el que fue emitido el documento.

Valor	Significado	Origen
live	Producción	EC: infoTributaria/ambiente=2
test	Pruebas	EC: infoTributaria/ambiente=1
null	No determinable	PE: el XML no codifica el entorno; se infiere del endpoint SUNAT donde se registró el emisor.

document.tax_status.authority y status.code

La forma del bloque es uniforme: authority + status: {accepted, code, label}. Los códigos provienen literalmente de la autoridad fiscal.

authority	status.code	status.accepted	Significado
sri	AUTORIZADO	true	Comprobante autorizado por el SRI.
sri	NO AUTORIZADO	false	Rechazado por el SRI.
sri	EN PROCESO	false	En cola de procesamiento.
sri	EN PROCESAMIENTO	false	Variante de EN PROCESO.
sri	RECHAZADA	false	Recepción rechazada por el SRI.
sri	NO_DEVUELTO	false	El SRI no devolvió ningún registro para la clave de acceso.
sunat	ACEPTADO	true	SUNAT aceptó el comprobante (estadoCp=1).
sunat	NO_EXISTE	false	SUNAT no encontró el comprobante (estadoCp=0).
sunat	ANULADO	false	Comprobante dado de baja (estadoCp=2).
sunat	AUTORIZADO_IMPRENTA	false	Autorizado a imprenta — ya no es válido para uso (estadoCp=3).
sunat	NO_AUTORIZADO	false	No autorizado por SUNAT (estadoCp=4).

Si la consulta no se pudo completar (timeout, credenciales inválidas, RUC sin enrolar), status.accepted es null y tax_status.error contiene el motivo.

checks (solicitud)

Valor	Verifica
format	XSD oficial + reglas de negocio del SRI / SUNAT.
signature	Firma electrónica XAdES, integridad y cadena de confianza.
calculations	Cálculos tributarios: catálogo de tarifas IVA/IGV, identidad valor = base × tarifa/100 por impuesto, totales de comprobante.
tax_status	Estado del comprobante ante SRI o SUNAT.
issuer_status	Solo Ecuador. Estado del contribuyente emisor consultado al catastro del SRI: activo/pasivo/suspensión, fantasma, transacciones inexistentes, régimen, obligaciones contables. En Perú la información equivalente ya viene incluida en tax_status.details. Fallas de red nunca rompen la validación: degradan a warning issuer_status_unavailable.
blacklist	Próximamente: listas negras del SRI.
all	Atajo para ejecutar todas las verificaciones aplicables.

checks (respuesta)

Resumen booleano por verificación. Sólo aparecen las que se ejecutaron.

Campo	Tipo	Significado
format	boolean	true sólo si XSD y reglas pasaron.
signature	boolean, null	null si el documento no lleva firma.
calculations	boolean, null	null si no se solicitó la verificación.
tax_status	boolean, null	null si la consulta no se pudo completar.
issuer_status	boolean, null	true si el RUC del emisor está activo y sin observaciones (no fantasma, no transacciones inexistentes). null si el catastro del SRI no respondió a tiempo o no se solicitó.
blacklist	null	Reservado.

failure.stage y failure.code

Causa primaria cuando valid: false. Una sola etapa por respuesta — la primera que falla.

stage	code	Significado
parse	xml_parse_error	XML mal formado o no UTF-8.
detect	unknown_document_type	País, tipo o versión no reconocidos.
schema	schema_invalid	No cumple con el XSD oficial.
signature	signature_invalid	El digest firmado no coincide con el contenido.
signature	signature_untrusted	Cadena de certificación no confiable.
signature	signature_expired	Certificado vencido o aún no válido.
rules	business_rules_failed	Falla en reglas de negocio del SRI / SUNAT.
calculations	calculations_failed	Inconsistencia en cálculos tributarios (tarifa IVA, identidad valor = base × tarifa).
unknown	validation_failed	Causa no clasificada.

error.type

Familia del error en respuestas 4xx (no aplica a 422, que devuelve validation).

Valor	HTTP típico	Significado
authentication_error	401, 403	API key faltante, inválida o revocada.
invalid_request_error	400, 413	Cuerpo malformado o parámetros inválidos.
api_error	500, 503	Falla interna o de un servicio dependiente.

error.code (4xx)

Código	Significado
missing_api_key	No se envió cabecera Authorization.
invalid_api_key	La clave no existe o fue revocada.
missing_xml	No se incluyó el XML del documento.
invalid_base64	El campo xml no es base64 válido.
invalid_country	Valor de country no soportado.
invalid_encoding	Valor de encoding no soportado.
request_too_large	El XML excede el tamaño máximo (5 MB).
validation_failed	Error interno al procesar la validación.

errors[].source

Valor	Origen del error
schema	Validación XSD.
signature	Verificación de firma XAdES.
rule	Reglas de negocio del SRI / SUNAT.
calculation	Cálculos tributarios (catálogo IVA/IGV, identidades aritméticas).

Prefijos de API key

Prefijo	Entorno
sk_live_…	Producción.
sk_test_…	Pruebas — sólo permite document.environment = "test".

Versiones de esquema

La API soporta todas las versiones vigentes publicadas por el SRI y SUNAT. Para SRI, la versión declarada en el atributo version de la raíz se devuelve en document.sri.version. Para SUNAT, la UBLVersionID y CustomizationID se devuelven en document.sunat.

Documento	Versiones soportadas
EC — factura	1.0.0, 1.1.0, 2.0.0, 2.1.0
EC — withholding	1.0.0, 2.0.0
EC — credit_note, debit_note	1.0.0, 1.1.0
EC — liquidation, waybill	1.0.0, 1.1.0
PE — invoice, credit_note, debit_note	UBL 2.0, 2.1
PE — voided, summary, withholding, perception	UBL 2.0 (SUNAT)

Errores

Dos formatos: errores de la solicitud (autenticación, formato) devuelven error; documentos inválidos devuelven validation con valid: false y un campo failure.

Errores de la solicitud (4xx)

Campo	Tipo	Descripción
type	string	Familia: authentication_error, invalid_request_error, api_error.
code	string	Código específico, estable y legible por máquina.
message	string	Descripción legible para humanos, en español.
request_id	string	Identificador de la solicitud para soporte.

Documentos inválidos (422)

failure resume la causa primaria; checks y errors tienen el detalle.

failure.stage	failure.code	Significado
parse	xml_parse_error	El XML está mal formado o no es UTF-8 válido.
detect	unknown_document_type	No se pudo identificar país, tipo o versión del documento.
schema	schema_invalid	El XML no cumple con el XSD oficial del SRI o SUNAT.
signature	signature_invalid	La firma electrónica no verifica (digest no coincide).
signature	signature_untrusted	La cadena de certificación no es de confianza.
signature	signature_expired	El certificado del firmante está vencido o aún no es válido.
rules	business_rules_failed	El documento no cumple con las reglas de negocio del SRI/SUNAT.

{
  "error": {
    "type":       "invalid_request_error",
    "code":       "invalid_country",
    "message":    "País no soportado: \"br\". Valores aceptados: 'ec', 'pe'.",
    "request_id": "req_01HXY2K9P3M7T8B"
  }
}

{
  "object": "validation",
  "valid": false,
  "request_id": "req_01HXY2K9P3M7T8B",
  "country": "ec",
  "failure": {
    "stage":   "signature",
    "code":    "signature_invalid",
    "message": "La firma electrónica no es válida (los datos firmados no coinciden con el resumen)."
  },
  "document": {
    "type": "invoice",
    "signature": {
      "signer": "JUAN PEREZ EJEMPLO"
    },
    "sri": {
      "version": "1.1.0"
    }
  },
  "checks": {
    "format":    true,
    "signature": false
  },
  "errors": [
    {
      "source":  "signature",
      "code":    "INTEGRITY",
      "message": "signature integrity check failed (digest mismatch or untrusted signer)"
    }
  ],
  "warnings": [],
  "validated_at": "2026-05-06T14:23:11Z"
}

Códigos HTTP

Código	Significado
200	La solicitud fue procesada. Revisa valid para conocer el resultado.
400	El cuerpo de la solicitud está malformado.
401	El API key falta o es inválido.
403	El API key no tiene permiso sobre el recurso o país solicitado.
422	El cuerpo es válido pero los datos no superan la validación.
429	Demasiadas solicitudes. Espera y reintenta con backoff.
500	Error interno. Contáctanos con el request_id.
503	Los servicios del SRI o SUNAT no están disponibles temporalmente.

# Backoff exponencial con jitter.
# No reintentar 4xx (excepto 429).

Límites

• Tamaño máximo del XML: 5 MB.
• Latencia típica: < 1 s (formato + firma); < 3 s con consulta SRI/SUNAT.

Planes

Plan	Precio	Incluye
Mensual	USD 299 / mes	Consultas ilimitadas, EC + PE.
Anual	USD 2,999 / año	Consultas ilimitadas + 2 meses gratis.

Precios sin impuestos.

X-Request-Id: req_01HXY2K9P3M7T8B
X-Response-Time: 412ms

Cumplimiento

Norma — Acreditación	Referencia
ISO/IEC 27001:2022 — Sistema de Gestión de Seguridad de la Información (SGSI) sobre los sistemas que soportan el proceso de facturación electrónica.	AENOR, IQNET, Reg. ES-SI-0062/2021, vigente hasta 2027-09-20.
ARCOTEL — Entidad de Certificación de Información acreditada (Ecuador).	Resolución ARCOTEL-2021-0923.
SUNAT — Proveedor de Servicios Electrónicos acreditado (Perú).	Resolución 034-005-0012054/SUNAT.
SRI — Proveedor reconocido de facturación electrónica (Ecuador).	Servicio de Rentas Internas.

Soporte

Si nedesitas soporte, contáctanos por los siguientes canales oficiales:

• WhatsApp: +593995007060
• Email: ayuda@datil.com
• Chat: datil.com

# conectando…

Code reference

La documentación interna del código tax-api se publica automáticamente desde master. Útil para clientes que ejecutan tax-api en su propia infraestructura (self-hosted) y para auditorías de implementación.

datil.github.io/datil/tax-api ↗

La superficie HTTP descrita arriba es la fuente de verdad para integraciones; los módulos internos pueden cambiar entre versiones sin previo aviso.

# Módulos públicos
TaxApi.TaxDocs       # pipeline de validación
TaxApi.SRI           # cliente catastro Ecuador
TaxApi.SUNAT         # cliente validarcomprobante
TaxApi.Tenants       # cuentas y API keys

# Generado con
mix docs