MLVAPIs
Iniciar Sesión Comenzar
REST API v1.0 · Base URL: https://api.mlvapis.com

Documentación Técnica

Guía completa para integrar consultas de RUC SUNAT, DNI RENIEC y cotizaciones de Tipo de Cambio en tus sistemas empresariales, ERPs y plataformas de checkout.

1. Autenticación

Todas las peticiones a la API REST de producción deben incluir tu token privado en la cabecera HTTP Authorization usando el esquema Bearer.

Authorization: Bearer mlv_live_xxxxxxxxxxxxxxxxxxxxxxxx
💡 Puedes generar, revocar o restringir por dirección IP tu API Token en tiempo real desde tu Dashboard.
GET

/v1/ruc/{ruc}

Consulta el padrón reducido oficial de SUNAT actualizado diariamente. Valida razón social, estado tributario, condición de domicilio, ubigeo y dirección estructurada para emisión de Facturas o Guías.

Parámetros de Ruta:

Parámetro Tipo Descripción
ruc String (11 dígitos) Número de RUC del contribuyente (ej. 20100070970)

Ejemplo de Respuesta (200 OK):

{
  "ruc": "20100070970",
  "razon_social": "SUPERMERCADOS PERUANOS SOCIEDAD ANONIMA",
  "estado": "ACTIVO",
  "condicion": "HABIDO",
  "ubigeo": "150140",
  "direccion": "CAL. MORELLI NRO. 181 INT. P-2",
  "departamento": "LIMA",
  "provincia": "LIMA",
  "distrito": "SAN BORJA",
  "es_agente_retencion": true,
  "actualizado_el": "2026-10-02T11:01:46Z"
}
GET

/v1/dni/{dni}

Valida y extrae datos de identidad para personas naturales desde fuentes públicas abiertas. Devuelve nombres, apellido paterno, apellido materno y dígito verificador.

Ejemplo de Respuesta (200 OK):

{
  "dni": "44781290",
  "nombres": "JUAN CARLOS",
  "apellido_paterno": "RODRIGUEZ",
  "apellido_materno": "QUISPE",
  "codigo_verificacion": "3"
}

4. Tipo de Cambio (SBS / SUNAT / BCRP)

Consulta en tiempo real e histórico de cotizaciones oficiales de compra y venta para Dólar Estadounidense (USD) y Euro (EUR) con respaldo legal para facturación electrónica y contabilidad en Perú. Conforme al Art. 50 del Reglamento de la Ley del IGV y Art. 61 de la Ley del Impuesto a la Renta, los días feriados o sin operaciones reflejan el tipo de cambio del último día hábil anterior.

GET

/v1/tipo-cambio/hoy y /v1/tipo-cambio/{fecha}

Moneda: USD

Obtiene la cotización oficial de compra y venta de Dólar estadounidense (USD a PEN). Puedes consultar la cotización vigente del día (/hoy) o consultar cualquier fecha histórica desde 1997 en formato ISO YYYY-MM-DD.

Parámetros de Ruta:

Parámetro Tipo Descripción
fecha Date (YYYY-MM-DD) Fecha de la cotización histórica (ej. 2026-10-02). Solo aplica para la ruta por fecha.

Ejemplo de Petición cURL:

curl -X GET "https://api.mlvapis.com/v1/tipo-cambio/hoy" \ -H "Authorization: Bearer TU_API_TOKEN"

Ejemplo de Respuesta (200 OK):

{
  "fecha": "2026-10-15",
  "compra": 3.426,
  "venta": 3.432,
  "moneda": "USD",
  "origen": "SBS/SUNAT"
}
GET

/v1/tipo-cambio/euro/hoy y /v1/tipo-cambio/euro/{fecha}

Moneda: EUR

Obtiene la cotización oficial de compra y venta de Euro (EUR a PEN) publicada por la SBS y Banco Central de Reserva (BCRP). Disponible para la cotización del día (/euro/hoy) o histórico desde febrero de 2002 (/euro/{fecha}).

Parámetros de Ruta:

Parámetro Tipo Descripción
fecha Date (YYYY-MM-DD) Fecha de la cotización histórica (ej. 2026-10-02). Histórico disponible desde febrero de 2002.

Ejemplo de Petición cURL:

curl -X GET "https://api.mlvapis.com/v1/tipo-cambio/euro/hoy" \ -H "Authorization: Bearer TU_API_TOKEN"

Ejemplo de Respuesta (200 OK):

{
  "fecha": "2026-10-15",
  "compra": 3.83,
  "venta": 3.858,
  "moneda": "EUR",
  "origen": "SBS/BCRP"
}
⚡ Microservicio SUNAT UBL 2.1

5. Facturación Electrónica (SUNAT UBL 2.1)

Plataforma multi-tenant de emisión y gestión tributaria para Perú. Construye el XML UBL 2.1 estándar, aplica firma digital XMLDSig, interactúa directamente con los Web Services SOAP de SUNAT (BETA y PRODUCCIÓN), procesa la Constancia de Recepción (CDR) y genera la representación gráfica en PDF (Ticket de 80mm o formato A4) con código QR oficial.

🔒
Seguridad de Grado Militar (AES-256-GCM): Los certificados digitales (.pfx) y contraseñas SOL nunca se almacenan en texto plano en la base de datos. Se encriptan con AES-256 en reposo y se desencriptan en memoria al momento de la firma digital, garantizando aislamiento total entre empresas emisoras.
POST

/v1/fe/empresas

Registra o actualiza una empresa emisora con sus credenciales SOL secundarias y carga su certificado digital .pfx en Base64. Valida automáticamente la fecha de vigencia y emisor del certificado.

Payload de Solicitud (JSON):

{
  "ruc": "20609999991",
  "razon_social": "MI TALLER AUTOMOTRIZ SAC",
  "nombre_comercial": "CENTRAL AUTO REPAIR",
  "direccion": "Av. Nicolas Arriola 1540",
  "ubigeo": "150115",
  "departamento": "LIMA",
  "provincia": "LIMA",
  "distrito": "LA VICTORIA",
  "sol_user": "MODDATOS",
  "sol_pass": "moddatos123",
  "gre_client_id": "9b123456-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "gre_client_secret": "wXyZ1234567890==",
  "cert_pfx_base64": "MIIKwgIBAzCCCm8GCSqGSIb3DQEHA...",
  "cert_password": "clave_del_certificado",
  "environment": "BETA"
}

* Los campos gre_client_id y gre_client_secret son opcionales y se generan desde el Portal Clave SOL para habilitar la emisión de Guías de Remisión Electrónica vía API REST.

POST

/v1/fe/empresas/{ruc}/probar-conexion

Prueba en tiempo real la validez del certificado digital, la capacidad de firma XMLDSig y la autenticación de las credenciales secundarias SOL ante los servidores de SUNAT.

Ejemplo de Respuesta (200 OK):

{
  "success": true,
  "sunat_reachable": true,
  "credentials_valid": true,
  "message": "Conexión exitosa con el servicio de SUNAT (BETA). Certificado y firma digital verificados."
}
POST

/v1/fe/comprobantes/emitir

Emisión sincrónica de Facturas Electrónicas (tipo_doc: "01") y Boletas de Venta (tipo_doc: "03"). Devuelve el estado directo de SUNAT (ACEPTADO / RECHAZADO), el código hash de la firma digital, el código QR y enlaces para descargar XML, CDR y PDF.

Payload de Solicitud (JSON):

{
  "company_ruc": "20609999991",
  "tipo_doc": "01",
  "serie": "F001",
  "correlativo": 3,
  "fecha_emision": "2026-10-04",
  "moneda": "PEN",
  "forma_pago": { "tipo": "Contado" },
  "cliente": {
    "tipo_doc": "6",
    "num_doc": "20555666777",
    "rzn_social": "TRANSPORTE Y LOGISTICA SANTA ROSA SAC",
    "direccion": "AV. ARGENTINA 450, CALLAO"
  },
  "detalles": [
    {
      "codigo": "MANT01",
      "descripcion": "Mantenimiento Preventivo y Cambio de Aceite Sintético",
      "unidad_medida": "NIU",
      "cantidad": 1.0,
      "valor_unitario": 100.0,
      "precio_unitario": 118.0,
      "subtotal": 100.0,
      "igv": 18.0,
      "total_impuestos": 18.0,
      "valor_total": 100.0,
      "importe_total": 118.0,
      "tipo_afectacion_igv": "10"
    }
  ],
  "totales": {
    "mto_oper_gravadas": 100.0,
    "mto_igv": 18.0,
    "total_impuestos": 18.0,
    "valor_venta": 100.0,
    "sub_total": 118.0,
    "mto_imp_venta": 118.0,
    "leyendas": [
      { "codigo": "1000", "valor": "SON CIENTO DIECIOCHO CON 00/100 SOLES" }
    ]
  },
  "opciones": {
    "generar_pdf": true,
    "formato_pdf": "ticket"
  }
}

Ejemplo de Respuesta (200 OK):

{
  "success": true,
  "sunat_status": "ACEPTADO",
  "cdr_code": "0",
  "cdr_description": "La Factura numero F001-3, ha sido aceptada",
  "hash": "zMRwq5b19LO6MdfJ5Xm5tOlDzSw=",
  "qr_data": "20609999991|01|F001|00000003|18.00|118.00|2026-10-04|6|20555666777|zMRwq5b19LO6MdfJ5Xm5tOlDzSw=|",
  "pdf_url": "/v1/fe/comprobantes/20609999991/01/F001/3/descargar/pdf"
}
POST

/v1/fe/notas/emitir

Emisión de Notas de Crédito (tipo_doc: "07") o Notas de Débito (tipo_doc: "08"). Requiere especificar el comprobante original afectado y el motivo según el Catálogo 09 / 10 de SUNAT.

Payload de Solicitud (JSON):

{
  "company_ruc": "20609999991",
  "tipo_doc": "07",
  "serie": "FC01",
  "correlativo": 1,
  "fecha_emision": "2026-10-04",
  "moneda": "PEN",
  "cliente": {
    "tipo_doc": "6",
    "num_doc": "20555666777",
    "rzn_social": "TRANSPORTE Y LOGISTICA SANTA ROSA SAC"
  },
  "documento_modificado": {
    "tipo_doc": "01",
    "serie": "F001",
    "correlativo": 3,
    "motivo_codigo": "01",
    "motivo_descripcion": "ANULACION DE LA OPERACION"
  },
  "detalles": [ ... ],
  "totales": { ... }
}
POST

/v1/fe/bajas/emitir

Envía un resumen de Comunicación de Baja (RA) a SUNAT para anular formalmente una o varias facturas dentro del plazo legal de 7 días calendario. Retorna un identificador de ticket asíncrono.

Consulta de Estado de Ticket:

GET

/v1/fe/estado/ticket/{ruc}/{ticket}

SUNAT procesa las bajas de manera asíncrona. Con este endpoint se obtiene el estado final (ACEPTADO) y el CDR oficial emitido por SUNAT.

GET

/v1/fe/comprobantes/{ruc}/{tipo_doc}/{serie}/{correlativo}/descargar/{tipo_archivo}

Descarga los artefactos oficiales del comprobante emitido. El parámetro tipo_archivo puede ser:

  • pdf: Representación gráfica oficial (formato Ticket 80mm o A4).
  • xml: Archivo XML firmado digitalmente bajo estándar OASIS UBL 2.1.
  • cdr: Constancia de Recepción oficial comprimida en ZIP emitida por SUNAT.
GET https://api.mlvapis.com/v1/fe/comprobantes/20609999991/01/F001/3/descargar/pdf?token=TU_API_TOKEN
🚚 API REST SUNAT · R.S. N° 000123-2022/SUNAT

6. Guías de Remisión Electrónica (GRE)

Emisión y consulta de Guía de Remisión Remitente (tipo_doc: "09") y Guía de Remisión Transportista (tipo_doc: "31"). Cumple con el estándar obligatorio de SUNAT en UBL 2.1 (versión 2022) transmitido a través del canal oficial API REST con autenticación OAuth 2.0.

🔑
Credenciales API de SUNAT: A diferencia de las facturas, las guías de remisión requieren credenciales específicas de aplicación (client_id y client_secret). Estas se obtienen en el portal Clave SOL: Empresas > Comprobantes de Pago > Sistema de Emisión Electrónica > Envío de documentos a través de servicios API REST > Gestión de credenciales API.
POST

/v1/fe/guias/emitir

Construye el XML UBL 2.1, firma digitalmente con el certificado de la empresa, gestiona el token OAuth 2.0 y sube el paquete ZIP a SUNAT. Incluye un sondeo síncrono inteligente para entregar la constancia CDR ACEPTADO al instante si SUNAT ya procesó el envío, o el número de ticket para consulta asíncrona si está en cola.

Modalidad Transporte Privado (02): Requiere placa del vehículo y datos del conductor (DNI, nombres, apellidos y brevete/licencia).
Modalidad Transporte Público (01): Requiere datos de la empresa de transporte (RUC, razón social y registro MTC opcional).

Payload de Solicitud (Transporte Privado - JSON):

{
  "company_ruc": "20609999991",
  "tipo_doc": "09",
  "serie": "T001",
  "correlativo": 12,
  "fecha_emision": "2026-10-08",
  "destinatario": {
    "tipo_doc": "6",
    "num_doc": "20555666777",
    "rzn_social": "TRANSPORTE Y LOGISTICA SANTA ROSA SAC",
    "direccion": "AV. ARGENTINA 450, CALLAO"
  },
  "envio": {
    "cod_traslado": "01",
    "mod_traslado": "02",
    "fec_traslado": "2026-10-09",
    "peso_total": 350.0,
    "und_peso_total": "KGM",
    "num_bultos": 10,
    "partida": {
      "ubigeo": "150115",
      "direccion": "Av. Nicolas Arriola 1540, La Victoria, Lima"
    },
    "llegada": {
      "ubigeo": "070101",
      "direccion": "Av. Argentina 450, Callao"
    },
    "vehiculo": {
      "placa": "ABC123",
      "placa_secundaria": "XYZ789"
    },
    "choferes": [
      {
        "tipo": "Principal",
        "tipo_doc": "1",
        "num_doc": "44556677",
        "nombres": "CARLOS ALBERTO",
        "apellidos": "RAMIREZ FLORES",
        "licencia": "Q44556677"
      }
    ]
  },
  "detalles": [
    {
      "codigo": "ACEITE-5W30",
      "descripcion": "Caja de Aceite Sintético 5W-30 (12 Unidades)",
      "unidad_medida": "BX",
      "cantidad": 5.0
    },
    {
      "codigo": "FIL-001",
      "descripcion": "Filtro de Aceite Automotriz Premium",
      "unidad_medida": "NIU",
      "cantidad": 20.0
    }
  ],
  "doc_relacionado": {
    "tipo_doc": "01",
    "num_doc": "F001-3"
  },
  "observaciones": "Traslado de repuestos para mantenimiento preventivo",
  "opciones": {
    "generar_pdf": true,
    "formato_pdf": "a4"
  }
}

Ejemplo de Respuesta (200 OK):

{
  "success": true,
  "sunat_status": "ACEPTADO",
  "ticket": "202600000000854",
  "cdr_code": "0",
  "cdr_description": "La Guía de Remisión número T001-00000012 ha sido aceptada.",
  "cdr_notes": [],
  "hash": "rT91KmqL5OPeYg91j0hF9kXwQ8k=",
  "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
  "cdr_zip_base64": "UEsDBAoAAAAAA...",
  "pdf_base64": "JVBERi0xLjQKJ..."
}
GET

/v1/fe/guias/status/{ticket}

Permite consultar el estado asíncrono de un ticket devuelto por SUNAT en caso de que el comprobante haya quedado en cola con estado PROCESANDO.

Parámetros de Query:

Parámetro Tipo Descripción
ticket Path (String) Número de ticket emitido por SUNAT (ej. 202600000000854)
company_ruc Query (String) RUC de la empresa emisora registrada (11 dígitos)

Ejemplo de Respuesta (200 OK):

{
  "success": true,
  "ticket": "202600000000854",
  "status": "ACEPTADO",
  "cdr_code": "0",
  "cdr_description": "La Guía de Remisión número T001-00000012 ha sido aceptada.",
  "cdr_zip_base64": "UEsDBAoAAAAAA..."
}
GET

/v1/fe/comprobantes/{ruc}/09/{serie}/{correlativo}/descargar/{formato}

Descarga directa de los archivos físicos de la Guía de Remisión usando el endpoint universal de descarga. Formatos admitidos: pdf, xml y cdr.

GET https://api.mlvapis.com/v1/fe/comprobantes/20609999991/09/T001/12/descargar/pdf?token=TU_API_TOKEN
📍 Padrón Oficial INEI 2026 · 1,893 Distritos

7. Ubigeos del Perú (INEI)

Catálogo geográfico oficial del Perú actualizado según el padrón INEI 2026 con 1,893 distritos, 196 provincias y 25 regiones/departamentos. Permite validar códigos de 6 dígitos, listar departamentos y provincias, e implementar selects en cascada y autocompletado en tus aplicaciones.

GET

/v1/ubigeos/{ubigeo}

Obtiene el nombre de departamento, provincia y distrito correspondiente a un código de ubigeo oficial de 6 dígitos.

Parámetros de Ruta:

Parámetro Tipo Descripción
ubigeo String (6 dígitos) Código oficial de distrito (ej. 150140)

Ejemplo de Respuesta (200 OK):

{
  "ubigeo": "150140",
  "departamento": "Lima",
  "provincia": "Lima",
  "distrito": "Santiago de Surco"
}
GET

/v1/ubigeos

Búsqueda libre por texto (q) o filtros combinados por departamento, provincia y distrito con paginación.

Parámetros de Consulta (Query):

Parámetro Tipo Descripción
q String (Opcional) Término de búsqueda libre por distrito, provincia, depto o prefijo de código (ej. Surco)
departamento String (Opcional) Nombre exacto de departamento (ej. Lima, Cusco)
limit Integer (Default 50) Límite de registros por página (1 a 2,000)
offset Integer (Default 0) Desplazamiento para paginación

Ejemplo de Respuesta (200 OK):

{
  "total": 1,
  "limit": 50,
  "offset": 0,
  "items": [
    {
      "ubigeo": "150140",
      "departamento": "Lima",
      "provincia": "Lima",
      "distrito": "Santiago de Surco"
    }
  ]
}
GET

/v1/ubigeos/departamentos

Retorna los 25 departamentos/regiones del Perú con código de 2 dígitos. Ideal para dropdowns primarios. 

[
  {"codigo": "01", "nombre": "Amazonas"},
  {"codigo": "08", "nombre": "Cusco"},
  {"codigo": "15", "nombre": "Lima"}
]
GET

/v1/ubigeos/provincias

Retorna las 196 provincias con código de 4 dígitos. Filtrable por ?codigo_departamento=15. 

[
  {"codigo": "1501", "nombre": "Lima", "departamento": "Lima"},
  {"codigo": "1502", "nombre": "Barranca", "departamento": "Lima"}
]
GET

/v1/ubigeos/distritos

Retorna los distritos oficiales. Filtrables por código de provincia (?codigo_provincia=1501), nombre de provincia o departamento. 

[
  {"ubigeo": "150101", "nombre": "Lima", "provincia": "Lima", "departamento": "Lima"},
  {"ubigeo": "150140", "nombre": "Santiago de Surco", "provincia": "Lima", "departamento": "Lima"}
]
GET

/v1/vehiculos/{placa}

Consulta el registro vehicular oficial de la Superintendencia Nacional de los Registros Públicos (SUNARP). Retorna las especificaciones técnicas completas del vehículo a partir del número de placa de rodaje única (marca, modelo, color, número de motor, serie de chasis, VIN, titulares/propietarios, estado de circulación, sede registral y año de fabricación).

⚡ Almacenamiento y Caché de Alta Velocidad:

Los vehículos consultados se indexan automáticamente en el repositorio central de MLV APIs. Las consultas subsiguientes de una placa previamente registrada responden en menos de 15 ms directamente desde base de datos.

Parámetros de Ruta:

Parámetro Tipo Descripción
placa String (5 a 8 caracteres) Número de placa de rodaje (ej. CAF272 o CAF-272). Case-insensitive.

Parámetros de Consulta Opcionales (Query Params):

Parámetro Tipo Descripción
turnstile_token String (Opcional) Token de Cloudflare Turnstile para forzar o revalidar la consulta en vivo ante la pasarela de SUNARP.
forzar_actualizacion Boolean (Default: false) Si es true, omite el caché local y re-consulta en vivo ante SUNARP.

Ejemplo de Solicitud (cURL):

curl -X GET "https://api.mlvapis.com/v1/vehiculos/CAF272" \
     -H "Authorization: Bearer mlv_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Ejemplo de Respuesta (200 OK):

{
  "placa": "CAF272",
  "numero_serie": "WBAPF7109AA498101",
  "vin": "WBAPF7109AA498101",
  "numero_motor": "A1731519",
  "color": "NEGRO",
  "marca": "BMW",
  "modelo": "318I LIMOUSINE",
  "placa_vigente": "CAF272",
  "placa_anterior": "COV442",
  "estado": "EN CIRCULACION",
  "anotaciones": "NINGUNA",
  "sede": "LIMA",
  "anio_modelo": 2010,
  "propietarios": "LACUNZA VASQUEZ, MARIO EDUARDO",
  "fecha_consulta_sunarp": "03/10/2026 09:58:34",
  "actualizado_el": "2026-10-18T23:55:00Z"
}

9. Rate Limits y Cuotas

Cada plan de suscripción cuenta con una cuota mensual de consultas y una tasa máxima por minuto controlada en memoria por Redis con latencia inferior a 2 milisegundos:

Plan Básico
1,000 req/mes
30 req/minuto
Plan Desarrollador
10,000 req/mes
120 req/minuto
Corporativo
50,000+ req/mes
300 req/minuto

10. Códigos de Respuesta HTTP

200 OK

Petición procesada con éxito y datos encontrados.

400 Bad Request

Parámetros inválidos (ej. RUC no numérico o longitud distinta de 11 dígitos).

401 Unauthorized

Falta el token de autorización o no existe en el sistema.

403 Forbidden

Llamada rechazada por IP no permitida (restricción configurada por el usuario o lista negra).

404 Not Found

El número de RUC o DNI no existe en los padrones oficiales.

429 Too Many Requests

Has excedido el límite por minuto de tu plan o has agotado tu cuota de consultas del mes.