Beta privada · apertura 23 de diciembre
Ensaya un comprobante sin emitirlo
POST /v1/emisores/{ruc}/comprobantes/validar
Calcula los totales y revisa las reglas de SUNAT con el mismo cuerpo de la emisión, sin numerar, sin enviar y sin cobrar. Úsalo antes de emitir algo dudoso.
| Dato | Valor |
|---|---|
| Permiso | comprobantes:emitir |
| Cobro | No cobra. |
Idempotency-Key |
No aplica |
| Credenciales en la llamada | Si envías credenciales, la clave necesita credenciales:por_llamada. |
| Herramienta MCP | comprobante_validar (Próximamente) |
Parámetros
Sección titulada «Parámetros»| Nombre | En | Requerido | Tipo | Descripción |
|---|---|---|---|---|
ruc |
path | Sí | string | RUC del emisor o contribuyente. |
X-Request-Id |
header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. |
application/json, obligatorio. Los campos anidados van con punto y los de listas con []. No se aceptan campos desconocidos.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
tipo |
“01” | “03” | “07” | “08” | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. |
serie |
string | Sí | Serie registrada del emisor. El número lo asigna el servidor. |
fecha_emision |
string (date) | No | Por defecto, hoy en Lima. SUNAT acepta pocos días hacia atrás. |
fecha_vencimiento |
string (date) | No | Fecha AAAA-MM-DD (día en Lima). |
moneda |
“PEN” | “USD” | Sí | Código ISO 4217: PEN (soles) o USD (dólares). |
tipo_cambio |
string | No | Obligatorio en dólares; no va en soles. |
cliente |
object | Sí | A quién se le emite. |
cliente.tipo_documento |
“0” | “1” | “4” | “6” | “7” | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. |
cliente.numero_documento |
string | Sí | Número del documento; en tipo 0 puede ir «-». |
cliente.nombre |
string | Sí | Razón social o nombre completo. |
cliente.direccion |
string | No | |
cliente.correo |
string (email) | No | Si lo envías, le mandamos el PDF y el XML. |
items |
object[] | Sí | |
items[].descripcion |
string | Sí | |
items[].cantidad |
string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. |
items[].unidad |
string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. |
items[].codigo |
string | No | Tu código interno del producto. |
items[].codigo_sunat |
string | No | Código de producto SUNAT (catálogo 25). |
items[].precio_unitario |
string | Sí | Precio por unidad con IGV incluido, el que paga tu cliente. En exonerado e inafecto es el valor por unidad; en gratuitas, el valor referencial (mayor que cero). |
items[].afectacion_igv |
“10” | “11” | “12” | “13” | “14” | “15” | “16” | “20” | “30” | “31” | “32” | “33” | “34” | “35” | “36” | “37” | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. |
items[].icbper |
boolean | No | true si la línea son bolsas plásticas: se suma el ICBPER por bolsa. |
forma_pago |
object | object | No | Contado o crédito con cuotas. Si no la envías, es al contado. |
detraccion |
object | No | Detracción (SPOT). Solo en facturas. |
detraccion.codigo_bien_servicio |
string | Sí | Catálogo 54, por ejemplo 022 (otros servicios). |
detraccion.porcentaje |
string | Sí | Porcentaje con dos decimales, por ejemplo “12.00”. |
detraccion.monto |
string | Sí | Monto de la detracción en soles. |
detraccion.cuenta_banco_nacion |
string | Sí | Cuenta de detracciones del Banco de la Nación. |
detraccion.medio_pago |
string | No | Catálogo 59; por defecto 001 (depósito en cuenta). |
referencia |
object | No | Solo notas: el comprobante que modificas. |
referencia.tipo |
“01” | “03” | Sí | |
referencia.serie |
string | Sí | |
referencia.numero |
integer | Sí | |
motivo |
object | No | Solo notas: el motivo con su código de catálogo. |
motivo.codigo |
string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. |
motivo.descripcion |
string | Sí | |
observacion |
string | No | |
orden_compra |
string | No | |
credenciales |
object | No | Credenciales por llamada: se usan solo en esta petición y no se guardan. Requiere el permiso credenciales:por_llamada. Si tu RUC usa la bóveda, no las envíes. Para emitir, dar de baja y resúmenes. |
credenciales.certificado |
object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. |
credenciales.certificado.pfx_base64 |
string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. |
credenciales.certificado.clave |
string (password) | Sí | Contraseña del archivo .pfx. |
credenciales.sol |
object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. |
credenciales.sol.usuario |
string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). |
credenciales.sol.clave |
string (password) | Sí | Clave SOL del usuario secundario. |
Ejemplo
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/validar" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "tipo": "01", "serie": "texto", "moneda": "PEN", "cliente": { "tipo_documento": "0", "numero_documento": "texto", "nombre": "texto" }, "items": [ { "descripcion": "texto", "cantidad": "2", "precio_unitario": "1250.50", "afectacion_igv": "10" } ]}'Respuestas
Sección titulada «Respuestas»Resultado del ensayo.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
valido |
boolean | Sí | |
totales |
object | Sí | Totales calculados por el servidor. |
totales.gravado |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
totales.exonerado |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
totales.inafecto |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
totales.gratuito |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
totales.igv |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
totales.icbper |
string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. “1250.50” es S/ 1,250.50. |
totales.total |
string | Sí | Importe total que paga el cliente. |
problemas |
object[] | Sí | Reglas de negocio o de SUNAT que fallarían al emitir. |
problemas[].campo |
string | Sí | |
problemas[].mensaje |
string | Sí |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 403
permiso_faltante - 403
emisor_obligado_ose - 404
no_encontrado - 422
credenciales_sunat - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 503
no_disponible