Ir al contenido

Beta privada · apertura 23 de diciembre

Emite una factura, boleta o nota

POST /v1/emisores/{ruc}/comprobantes

Emite y envía a SUNAT. El número lo asigna el servidor. Reserva el precio del saldo y lo cobra solo si SUNAT acepta; si SUNAT rechaza, se libera. Si SUNAT no responde, queda en_cola (202) y se envía solo. Según tu clave, notas, bajas o montos altos esperan la aprobación de una persona (202 requiere_confirmacion).

Dato Valor
Permiso comprobantes:emitir
Cobro Reserva el precio de tu saldo y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta).
Idempotency-Key Obligatoria
Aprobación humana Según la configuración de tu clave puede responder 202 requiere_confirmacion.
Credenciales en la llamada Si envías credenciales, la clave necesita credenciales:por_llamada.
Herramienta MCP comprobante_emitir (Próximamente)
Nombre En Requerido Tipo Descripción
ruc path Sí string RUC del emisor o contribuyente.
Idempotency-Key header Sí string Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, idempotencia_en_conflicto. Se guarda 24 horas.
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" \
-H "Authorization: Bearer onx_test_…" \
-H "Idempotency-Key: $(uuidgen)" \
-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"
}
]
}'

Aceptado por SUNAT (o aceptado con observaciones).

Campo Tipo Requerido Descripción
id string Sí Identificador que empieza con cmp_.
emisor_ruc string Sí RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT).
tipo “01” | “03” | “07” | “08” Sí 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.
serie string Sí
numero integer Sí Asignado por el servidor.
numero_completo string Sí Serie y número, por ejemplo F001-124.
fecha_emision string (date) Sí 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 | null Sí
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 Sí Contado o crédito con cuotas. Si no la envías, es al contado.
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.
referencia object | null Sí
referencia.tipo “01” | “03” Sí
referencia.serie string Sí
referencia.numero integer Sí
motivo object | null Sí
motivo.codigo string Sí Catálogo 09 (crédito) o 10 (débito), por ejemplo 01.
motivo.descripcion string Sí
estado “en_cola” | “aceptado” | “observado” | “rechazado” | “en_baja” | “anulado” Sí en_cola: guardado y esperando a SUNAT. observado: aceptado con observaciones. en_baja: anulación en curso.
sunat object | null Sí
sunat.codigo string Sí Código de respuesta de SUNAT; 0 es aceptado.
sunat.descripcion string Sí
sunat.observaciones string[] Sí
hash string | null Sí Valor del resumen (DigestValue) de la firma, el que va en el QR.
enlaces object Sí
enlaces.xml string Sí
enlaces.cdr string | null Sí null mientras SUNAT no responde.
enlaces.pdf string Sí
creado_en string (date-time) Sí Fecha y hora ISO 8601 con la zona de Lima (-05:00).
actualizado_en string (date-time) Sí Fecha y hora ISO 8601 con la zona de Lima (-05:00).

En cola por SUNAT o esperando aprobación humana.

Campo Tipo Requerido Descripción
estado “requiere_confirmacion” Sí
operacion_id string No Úsalo en GET /v1/confirmaciones/{id} para saber si se aprobó.
confirmacion_url string (uri) No Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual.
consulta_url string Sí Ruta para consultar el estado.
expira_en string (date-time) No Antes de esta hora hay que aprobarla Y repetir la petición; si no, vence y no se hace.
mensaje string Sí Qué falta, en palabras para una persona.
recurso object No Lo que se creó y queda en proceso.
recurso.tipo “comprobante” | “baja” | “resumen” | “guia” | “sire_propuesta” | “mensaje” | “entrega” | “clave” | “conexion” | “webhook” No
recurso.id string No
reintento_en string (date-time) No Próximo intento estimado, si aplica.

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