Ir al contenido

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)
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.

Contra el sandbox, con una clave onx_test_…:

Ventana de terminal
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"
}
]
}'

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í

Cada código tiene su explicación en Errores.