Ir al contenido

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

Contra el sandbox, con una clave onx_test_…:

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

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.

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