Beta privada · apertura 23 de diciembre
Emite una guía de remisión remitente
POST /v1/emisores/{ruc}/guias
Emite la guía (09) por la API de SUNAT. El número lo asigna el servidor. Reserva el precio y lo cobra solo si SUNAT la acepta; si SUNAT no responde, queda en_cola.
| Dato | Valor |
|---|---|
| Permiso | guias:emitir |
| Cobro | Reserva el precio de tu saldo y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta). |
Idempotency-Key |
Obligatoria |
| Credenciales en la llamada | Si envías credenciales, la clave necesita credenciales:por_llamada. |
| Herramienta MCP | guia_emitir (Próximamente) |
Parámetros
Sección titulada «Parámetros»| 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 |
|---|---|---|---|
serie |
string | Sí | |
fecha_emision |
string (date) | No | Fecha AAAA-MM-DD (día en Lima). |
destinatario |
object | Sí | |
destinatario.tipo_documento |
“1” | “4” | “6” | “7” | Sí | |
destinatario.numero_documento |
string | Sí | |
destinatario.nombre |
string | Sí | |
motivo_traslado |
object | Sí | |
motivo_traslado.codigo |
string | Sí | Catálogo 20, por ejemplo 01 venta. |
motivo_traslado.descripcion |
string | No | |
peso_bruto_kg |
string | Sí | |
numero_bultos |
integer | No | |
modalidad |
“01” | “02” | Sí | Catálogo 18: 01 transporte público, 02 transporte privado. |
fecha_inicio_traslado |
string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). |
transportista |
object | No | Obligatorio en transporte público (01). |
transportista.ruc |
string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). |
transportista.razon_social |
string | Sí | |
transportista.registro_mtc |
string | No | |
conductores |
object[] | No | Obligatorio en transporte privado (02). |
conductores[].tipo_documento |
“1” | “4” | “7” | Sí | |
conductores[].numero_documento |
string | Sí | |
conductores[].nombres |
string | Sí | |
conductores[].apellidos |
string | Sí | |
conductores[].licencia |
string | Sí | |
vehiculos |
object[] | No | Obligatorio en transporte privado (02). |
vehiculos[].placa |
string | Sí | |
partida |
object | Sí | |
partida.ubigeo |
string | Sí | Ubigeo INEI de 6 dígitos. |
partida.direccion |
string | Sí | |
partida.codigo_establecimiento |
string | No | |
llegada |
object | Sí | |
llegada.ubigeo |
string | Sí | Ubigeo INEI de 6 dígitos. |
llegada.direccion |
string | Sí | |
llegada.codigo_establecimiento |
string | No | |
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 | |
items[].codigo |
string | No | |
documentos_relacionados |
object[] | No | |
documentos_relacionados[].tipo |
“01” | “03” | Sí | |
documentos_relacionados[].serie |
string | Sí | |
documentos_relacionados[].numero |
integer | Sí | |
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 guías de remisión. |
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. |
credenciales.api_sunat |
object | Sí | Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve. |
credenciales.api_sunat.client_id |
string | Sí | |
credenciales.api_sunat.client_secret |
string (password) | Sí |
Ejemplo
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/guias" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "serie": "texto", "destinatario": { "tipo_documento": "1", "numero_documento": "texto", "nombre": "texto" }, "motivo_traslado": { "codigo": "texto" }, "peso_bruto_kg": "texto", "modalidad": "01", "fecha_inicio_traslado": "2026-11-15", "partida": { "ubigeo": "150101", "direccion": "texto" }, "llegada": { "ubigeo": "150101", "direccion": "texto" }, "items": [ { "descripcion": "texto", "cantidad": "2" } ]}'Respuestas
Sección titulada «Respuestas»Guía aceptada por SUNAT.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
id |
string | Sí | Identificador que empieza con gre_. |
emisor_ruc |
string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). |
serie |
string | Sí | |
numero |
integer | Sí | |
numero_completo |
string | Sí | |
fecha_emision |
string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). |
estado |
“en_cola” | “aceptada” | “rechazada” | Sí | |
destinatario |
object | Sí | |
destinatario.tipo_documento |
string | Sí | |
destinatario.numero_documento |
string | Sí | |
destinatario.nombre |
string | Sí | |
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í | |
enlaces |
object | Sí | |
enlaces.xml |
string | Sí | |
enlaces.cdr |
string | null | Sí | |
enlaces.pdf |
string | Sí | |
creada_en |
string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
actualizada_en |
string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). |
Guía en cola.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
estado |
“en_cola” | Sí | |
recurso |
object | Sí | Lo que se creó y queda en proceso. |
recurso.tipo |
“comprobante” | “baja” | “resumen” | “guia” | “sire_propuesta” | “mensaje” | “entrega” | “clave” | “conexion” | “webhook” | Sí | |
recurso.id |
string | Sí | |
consulta_url |
string | Sí | Ruta para consultar cómo va. |
mensaje |
string | Sí | |
reintento_en |
string (date-time) | No | Próximo intento estimado, si aplica. |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 402
saldo_insuficiente - 402
tope_alcanzado - 403
permiso_faltante - 403
emisor_obligado_ose - 404
no_encontrado - 409
idempotencia_en_conflicto - 409
solicitud_en_curso - 409
boveda_inactiva - 422
sunat_rechazo - 422
credenciales_sunat - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 503
no_disponible