Catálogo de endpoints
Todas las rutas de la API con un ejemplo listo para copiar en cURL, PHP y JavaScript, la respuesta de ejemplo y los errores posibles. Se genera desde el mismo contrato que la API, así que siempre coincide con lo publicado.
API desarrollada por FactosPerú (factosperu.com).
https://api.factosperu.comAuthorization: Bearer TU_TOKENJSON:
success, code, retryable, data o message, time¿Prefieres probar en vivo? Usa la referencia interactiva (Swagger) o descarga la colección de Postman y su entorno (ver manual de Postman). Los códigos de error están en Errores.
No hay endpoints que coincidan con la búsqueda. Prueba con otra palabra o revisa Errores.
Identidad (8)
Consultas de RUC y DNI en el formato propio de la API (`/api/v1/`). Es la forma recomendada para integraciones nuevas.
Consulta RUC
Consulta un RUC por un solo filtro: primero el Padrón Reducido oficial (`source: padron_reducido`, instantáneo; trae razón social, estado, condición y domicilio) y, si el RUC no está ahí o el padrón no está disponible, el portal público de SUNAT en línea (`source: sunat_en_linea`, ficha completa). Si la consulta en línea está desactivada, solo responde el padrón.
Campos obligatorios: ruc
cURL
curl -X POST "https://api.factosperu.com/api/v1/ruc" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/ruc', ['ruc' => '20123456789']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/ruc', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"ruc": "20123456789",
"nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
"estado": "ACTIVO",
"condicion": "HABIDO",
"direccion": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
"departamento": "LIMA",
"tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
"fecha_inscripcion": "01/01/2020",
"fecha_inicio_actividades": "01/01/2020",
"actividades_economicas": [
"Principal - 6201 - ACTIVIDADES DE PROGRAMACION INFORMATICA"
],
"sistema_emision": "MANUAL/COMPUTARIZADO",
"sistema_contabilidad": "COMPUTARIZADO",
"es_agente_de_retencion": "NO",
"es_buen_contribuyente": "NO"
},
"source": "padron_reducido",
"time": 0.42
}
Errores
404: El RUC no existe en SUNAT (`not_found`, `retryable: false`) o SUNAT no respondió (`retryable: true`). Distinga ambos casos con `code` y `retryable`.422: RUC inválido (`invalid_ruc`) o campos faltantes.502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta RUC (ficha SUNAT)
Consulta un RUC y devuelve la ficha con la dirección completa, tipo de contribuyente, fecha de inscripción y actividades económicas. Mismos datos que `/api/v1/ruc`, con el formato de respuesta publicado para integraciones tipo FactosPerú.
Campos obligatorios: ruc
cURL
curl -X POST "https://api.factosperu.com/api/v1/ruc-sunat" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/ruc-sunat', ['ruc' => '20123456789']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/ruc-sunat', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"ruc": "20123456789",
"nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
"estado": "ACTIVO",
"condicion": "HABIDO",
"direccion_completa": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
"tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
"fecha_inscripcion": "01/01/2020",
"actividades_economicas": [
"Principal - 6201 - ACTIVIDADES DE PROGRAMACION INFORMATICA"
]
},
"time": 0.42
}
Errores
400: RUC inválido (`invalid_input`, `retryable: false`).404: El RUC no existe (`document_not_found`, `retryable: false`).503: Servicio de consulta no disponible (`upstream_unavailable`, `retryable: true`). Reintentar en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta RUC por DNI
Devuelve el RUC asociado a un DNI. Si el DNI no tiene RUC, responde 404 `document_not_found`.
Campos obligatorios: dni
cURL
curl -X POST "https://api.factosperu.com/api/v1/dni-ruc" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"dni":"44556677"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/dni-ruc', ['dni' => '44556677']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/dni-ruc', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"dni":"44556677"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"ruc": "10445566778"
},
"time": 0.42
}
Errores
400: DNI inválido (`invalid_input`, `retryable: false`).404: El DNI no cuenta con RUC (`document_not_found`, `retryable: false`).503: Servicio de consulta no disponible (`upstream_unavailable`, `retryable: true`). Reintentar en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta DNI
Consulta el nombre asociado a un DNI por un solo filtro: primero el Padrón Reducido por el RUC 10 de la persona (`source: padron_reducido`) y, si no está, el portal público de SUNAT en línea (`source: sunat_en_linea`). Solo se encuentran personas registradas como contribuyentes en SUNAT. La respuesta trae apellidos y nombres por separado.
Campos obligatorios: dni
cURL
curl -X POST "https://api.factosperu.com/api/v1/dni" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"dni":"12345678"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/dni', ['dni' => '12345678']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/dni', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"dni":"12345678"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"numero": "12345678",
"nombre_completo": "PEREZ LOPEZ ANA MARIA",
"nombres": "ANA MARIA",
"apellido_paterno": "PEREZ",
"apellido_materno": "LOPEZ",
"codigo_verificacion": 0
},
"source": "padron_reducido",
"time": 0.42
}
Errores
404: No hay un contribuyente con ese DNI (`not_found`, `retryable: false`) o el proveedor no pudo completar la consulta (código del proveedor, `retryable: true`).422: DNI inválido (`invalid_dni`) o campos faltantes.502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta por Carnet de Extranjería
Busca en el portal público de SUNAT al contribuyente registrado con ese documento: nombre, RUC, estado y ubicación. Solo se encuentran personas inscritas en SUNAT. Si la consulta en línea está desactivada responde 503 `fuente_desactivada`.
Campos obligatorios: numero
cURL
curl -X POST "https://api.factosperu.com/api/v1/carnet-extranjeria" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"numero":"001234567"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/carnet-extranjeria', ['numero' => '001234567']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/carnet-extranjeria', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"numero":"001234567"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"tipo_documento": "carnet-extranjeria",
"numero": "001234567",
"nombre_completo": "PEREZ LOPEZ ANA MARIA",
"nombres": "ANA MARIA",
"apellido_paterno": "PEREZ",
"apellido_materno": "LOPEZ",
"ruc": "15600000001",
"estado": "ACTIVO",
"ubicacion": "LIMA - LIMA - MIRAFLORES"
},
"source": "sunat_en_linea",
"time": 0.42
}
Errores
404: No hay un contribuyente con ese documento (`not_found`, `retryable: false`).422: Número inválido (`invalid_documento`) o campo faltante.502: Error del proveedor (`proveedor_error`, reintentable).503: Consulta en línea desactivada (`fuente_desactivada`) o servicio no disponible (`no_disponible`, `servicio_no_disponible`); reintentable.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta por Pasaporte
Busca en el portal público de SUNAT al contribuyente registrado con ese documento: nombre, RUC, estado y ubicación. Solo se encuentran personas inscritas en SUNAT. Si la consulta en línea está desactivada responde 503 `fuente_desactivada`.
Campos obligatorios: numero
cURL
curl -X POST "https://api.factosperu.com/api/v1/pasaporte" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"numero":"X1234567"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/pasaporte', ['numero' => 'X1234567']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/pasaporte', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"numero":"X1234567"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"tipo_documento": "pasaporte",
"numero": "X1234567",
"nombre_completo": "PEREZ LOPEZ ANA MARIA",
"nombres": "ANA MARIA",
"apellido_paterno": "PEREZ",
"apellido_materno": "LOPEZ",
"ruc": "15600000001",
"estado": "ACTIVO",
"ubicacion": "LIMA - LIMA - MIRAFLORES"
},
"source": "sunat_en_linea",
"time": 0.42
}
Errores
404: No hay un contribuyente con ese documento (`not_found`, `retryable: false`).422: Número inválido (`invalid_documento`) o campo faltante.502: Error del proveedor (`proveedor_error`, reintentable).503: Consulta en línea desactivada (`fuente_desactivada`) o servicio no disponible (`no_disponible`, `servicio_no_disponible`); reintentable.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta por Cédula Diplomática de Identidad
Busca en el portal público de SUNAT al contribuyente registrado con ese documento: nombre, RUC, estado y ubicación. Solo se encuentran personas inscritas en SUNAT. Si la consulta en línea está desactivada responde 503 `fuente_desactivada`.
Campos obligatorios: numero
cURL
curl -X POST "https://api.factosperu.com/api/v1/cedula-diplomatica" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"numero":"123456"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/cedula-diplomatica', ['numero' => '123456']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/cedula-diplomatica', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"numero":"123456"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"tipo_documento": "cedula-diplomatica",
"numero": "123456",
"nombre_completo": "PEREZ LOPEZ ANA MARIA",
"nombres": "ANA MARIA",
"apellido_paterno": "PEREZ",
"apellido_materno": "LOPEZ",
"ruc": "15600000001",
"estado": "ACTIVO",
"ubicacion": "LIMA - LIMA - MIRAFLORES"
},
"source": "sunat_en_linea",
"time": 0.42
}
Errores
404: No hay un contribuyente con ese documento (`not_found`, `retryable: false`).422: Número inválido (`invalid_documento`) o campo faltante.502: Error del proveedor (`proveedor_error`, reintentable).503: Consulta en línea desactivada (`fuente_desactivada`) o servicio no disponible (`no_disponible`, `servicio_no_disponible`); reintentable.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consultas por GET (2)
Las mismas consultas de DNI y RUC que `/api/v1/`, pero por GET y con un formato de respuesta alterno. Úsalas si tu integración consulta por GET.
Cómo usarlas en tu sistema
- En la configuración de tu sistema, pon la URL base
https://api.factosperu.com. - Envía tu token con el encabezado
Authorization: Bearer TU_TOKEN. - No cambies nada más: la ruta y el formato de respuesta son los mismos de esta página.
DNI devuelve direccion (vacía si no hay dato) y ubigeo como códigos [departamento, provincia, distrito], o null si el proveedor no lo entrega.
RUC devuelve ubigeo como códigos [departamento, provincia, distrito], o null si no hay dato. direccion vale "" si no hay dato.
Sistemas compatibles: pro7, pro8 y Pro9 (formato verificado con su código de integración). SMART, QPOS y Facturador PRO: en verificación; no uses esta guía para ellos hasta que se publique su confirmación.
Errores: 404 cuando no existe el documento (no reintentar), 422 cuando el número no tiene el formato correcto, 503 cuando el servicio no está disponible (reintentar en unos minutos).
Consulta DNI por GET
Consulta los datos de una persona por su DNI. Es la misma consulta que `POST /api/v1/dni`, pero por GET y con un formato de respuesta alterno. **Campos que devuelve en `data`:** `numero`, `nombre_completo`, `nombres`, `apellido_paterno`, `apellido_materno` y `codigo_verificacion`. **Campos adicionales:** `direccion` (texto vacío `""` si el proveedor no la entrega) y `ubigeo` (`[departamento, provincia, distrito]` como códigos, o `null` si no hay dato). **Consumo:** 1 unidad por solicitud.
Campos obligatorios: dni
dni(en la ruta, obligatorio)
cURL
curl -X GET "https://api.factosperu.com/api/dni/{dni}" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/dni/{dni}');
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/dni/{dni}', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"numero": "44556677",
"nombre_completo": "PEREZ GARCIA JUAN CARLOS",
"nombres": "JUAN CARLOS",
"apellido_paterno": "PEREZ",
"apellido_materno": "GARCIA",
"codigo_verificacion": 3
},
"time": 0.42
}
Errores
422: DNI inválido: debe tener 8 dígitos (`invalid_dni`, `retryable: false`).404: No hay un contribuyente registrado en SUNAT con ese DNI (`not_found`, `retryable: false`).503: Servicio no disponible (`servicio_no_disponible`, `retryable: true`). Reintentar en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta RUC por GET
Consulta la ficha de un RUC. Es la misma consulta que `POST /api/v1/ruc`, pero por GET y con un formato de respuesta alterno. **Campos que devuelve en `data`:** `ruc`, `nombre_o_razon_social`, `estado`, `condicion`, `direccion`, `departamento`, `tipo_contribuyente`, `fecha_inscripcion`, `fecha_inicio_actividades`, `actividades_economicas`, `sistema_emision`, `sistema_contabilidad`, `es_agente_de_retencion` (`SI`/`NO`) y `es_buen_contribuyente`. **Campos adicionales:** `ubigeo` (`[departamento, provincia, distrito]` como códigos, o `null` si no hay dato). `direccion` vale `""` si no hay dato. El campo `source` va en el nivel superior de la respuesta, junto a `success`. **Consumo:** 1 unidad por solicitud.
Campos obligatorios: ruc
ruc(en la ruta, obligatorio)
cURL
curl -X GET "https://api.factosperu.com/api/ruc/20123456789" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/ruc/20123456789');
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/ruc/20123456789', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"ruc": "20123456789",
"nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
"estado": "ACTIVO",
"condicion": "HABIDO",
"direccion": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
"departamento": "LIMA",
"es_agente_de_retencion": "NO"
},
"time": 0.42
}
Errores
422: RUC inválido: debe tener 11 dígitos (`invalid_ruc`, `retryable: false`).404: El RUC no existe en SUNAT (`not_found`, `retryable: false`).502: Error del proveedor (`proveedor_error`, `retryable: true`).503: Servicio no disponible (`servicio_no_disponible`, `retryable: true`). Reintentar en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Comprobantes (3)
Consulta y descarga de CPE
Consulta comprobantes electrónicos con la Clave SOL del RUC y devuelve sus archivos PDF, XML y CDR en Base64.
Campos obligatorios: ruc, usuario_sol, clave_sol, comprobantes
cURL
curl -X POST "https://api.factosperu.com/api/v1/cpe" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","comprobantes":[{"tipo_consulta":"emitido","ruc_emisor":"20123456789","tipo":"01","serie":"F001","numero":"123","fecha":"FECHA_DE_EMISION","monto":"MONTO_DEL_COMPROBANTE"}]}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/cpe', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'comprobantes' => [0 => ['tipo_consulta' => 'emitido', 'ruc_emisor' => '20123456789', 'tipo' => '01', 'serie' => 'F001', 'numero' => '123', 'fecha' => 'FECHA_DE_EMISION', 'monto' => 'MONTO_DEL_COMPROBANTE']]]);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/cpe', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","comprobantes":[{"tipo_consulta":"emitido","ruc_emisor":"20123456789","tipo":"01","serie":"F001","numero":"123","fecha":"FECHA_DE_EMISION","monto":"MONTO_DEL_COMPROBANTE"}]}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"total": 1,
"exitosos": 1,
"fallidos": 0,
"comprobantes": [
{
"id": "1",
"estado": "ok",
"tipo": "01",
"serie": "F001",
"numero": "123",
"fecha_emision": "FECHA_DE_EMISION",
"total": "MONTO",
"moneda": "PEN",
"estado_cpe": "CODIGO_PROVEEDOR",
"emisor": {
"ruc": "20123456789",
"razon_social": "EMPRESA DEMOSTRACION S.A.C.",
"direccion": "AV. EJEMPLO 123"
},
"receptor": {
"documento": "20987654321",
"razon_social": "CLIENTE DEMOSTRACION S.A."
},
"items": [],
"archivos": {
"pdf": {
"ok": true,
"nombre": "F001-123.pdf",
"es_zip": false,
"contenido_base64": "BASE64",
"tamano_kb": 12.5
},
"xml": {
"ok": false,
"error": "No disponible"
},
"cdr": {
"ok": false,
"error": "No disponible"
}
}
}
]
},
"time": 0.42
}
Errores
422: Campos superiores inválidos (RUC no numérico, lote vacío o mayor a 100).500: El proveedor informó un error global (`cpe_error`, reintentable).502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Consulta CPE de un RUC excluido
Consulta un comprobante en el proveedor alternativo configurado para RUC excluidos (portal público de Sovos, p. ej. BCP). Entrega PDF y XML; el CDR se devuelve como null porque la fuente no lo proporciona. `documento` trae el estado en el proveedor, emisor y receptor; `fuente` indica `en_linea` o `cache` (un comprobante ya consultado se responde desde la caché sin volver al proveedor).
Campos obligatorios: ruc, tipo, folio, fecha, total
cURL
curl -X POST "https://api.factosperu.com/api/v1/ruc/excluido" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","tipo":"01","folio":"FA02-0000000","fecha":"2026-10-08","total":"0.00"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/ruc/excluido', ['ruc' => '20123456789', 'tipo' => '01', 'folio' => 'FA02-0000000', 'fecha' => '2026-10-08', 'total' => '0.00']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/ruc/excluido', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","tipo":"01","folio":"FA02-0000000","fecha":"2026-10-08","total":"0.00"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"provider": "bcp_sovos",
"datos": {
"ruc": "20123456789",
"tipo": "01",
"folio": "FA02-0000000",
"fecha": "2026-10-08",
"total": "0.00"
},
"archivos": {
"pdf": {
"base64": "BASE64_PDF",
"mime": "application/pdf",
"size": 12345
},
"xml": {
"base64": "BASE64_XML",
"mime": "application/xml",
"size": 6789
},
"cdr": null
},
"documento": {
"estado": "document.authorized",
"estado_descripcion": "Authorized",
"emisor": "BANCO DE CREDITO DEL PERU",
"receptor": "EMPRESA DEMO SAC"
},
"fuente": "en_linea"
},
"time": 0.42
}
Errores
404: El comprobante no existe en el proveedor (`not_found`, `retryable: false`): revise RUC, tipo, serie-número, fecha y total.422: Campos inválidos.502: El proveedor alternativo no pudo completar la consulta (`proveedor_error`) o excedió el tiempo de espera (`timeout`); ambos reintentables.503: El proveedor alternativo no está habilitado (`proveedor_no_disponible`).401/403/429: token inválido, acceso restringido o límite alcanzado.
Validación múltiple de CPE
Consulta el estado de varios comprobantes en SUNAT con la Clave SOL del RUC (estado del comprobante, del contribuyente y condición de domicilio).
Campos obligatorios: ruc, usuario_sol, clave_sol, comprobantes
cURL
curl -X POST "https://api.factosperu.com/api/v1/validacion-multiple-cpe" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","comprobantes":[{"tipo":"01","serie":"F001","numero":"123","fecha":"FECHA_DE_EMISION","monto":"MONTO_DEL_COMPROBANTE"}]}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/validacion-multiple-cpe', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'comprobantes' => [0 => ['tipo' => '01', 'serie' => 'F001', 'numero' => '123', 'fecha' => 'FECHA_DE_EMISION', 'monto' => 'MONTO_DEL_COMPROBANTE']]]);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/validacion-multiple-cpe', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","comprobantes":[{"tipo":"01","serie":"F001","numero":"123","fecha":"FECHA_DE_EMISION","monto":"MONTO_DEL_COMPROBANTE"}]}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"total": 1,
"exitosos": 1,
"fallidos": 0,
"comprobantes": [
{
"tipo": "01",
"serie": "F001",
"numero": "123",
"fecha": "FECHA_DE_EMISION",
"monto": "MONTO_DEL_COMPROBANTE",
"exito": true,
"estado_comprobante": "ESTADO_INFORMADO_POR_SUNAT",
"estado_contribuyente": "ACTIVO",
"condicion_domicilio": "HABIDO",
"observaciones": "",
"error": null,
"intentos": 1
}
],
"tiempo_ms": 1500
},
"time": 0.42
}
Errores
422: Campos superiores inválidos.500: El proveedor informó un error global (`validacion_error`, reintentable).502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Buzón SOL (1)
Consulta del buzón electrónico
Extrae notificaciones y mensajes del buzón SOL del RUC, con sus detalles y adjuntos.
Campos obligatorios: ruc, usuario_sol, clave_sol
cURL
curl -X POST "https://api.factosperu.com/api/v1/buzon" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","omitir_detalle":[[]]}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/buzon', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'omitir_detalle' => [0 => []]]);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/buzon', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","omitir_detalle":[[]]}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"timestamp": "2026-10-10T12:00:00-05:00",
"buzon_notificaciones": {
"nombre": "",
"contador": 0,
"mensajes": []
},
"buzon_mensajes": {
"nombre": "",
"contador": 0,
"mensajes": []
},
"mis_carpetas": [],
"mis_etiquetas": [],
"todos_los_mensajes": [],
"detalles_mensajes": [],
"ajax_notificaciones": [],
"ajax_mensajes": [],
"resumen": {
"total_mensajes": 0,
"total_detalles": 0,
"total_carpetas": 0,
"total_etiquetas": 0,
"ajax_noti": 0,
"ajax_msj": 0
}
},
"time": 0.42
}
Errores
422: Campos inválidos.500: El proveedor informó un error (`buzon_error` u otro código, reintentable).502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Casilla SUNAFIL (2)
Consulta de la casilla electrónica SUNAFIL
Lee las categorías de la casilla electrónica SUNAFIL del RUC (notificaciones, acciones previas, orientación) con las credenciales SOL.
Campos obligatorios: ruc, usuario_sol, clave_sol
cURL
curl -X POST "https://api.factosperu.com/api/v1/sunafil/casilla" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/sunafil/casilla', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/sunafil/casilla', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"total": 0,
"categorias": [
{
"nombre": "Orientación",
"total": 0,
"registros": []
}
]
},
"time": 0.42
}
Errores
422: Campos inválidos.500: El proveedor informó un error (`sunafil_error` u otro código, reintentable).502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Descarga de documento SUNAFIL (en memoria)
Devuelve en base64 los PDF de una fila de Acciones Previas (constancia de depósito y acuse). Cada uno trae su nombre y su huella SHA-256; el servicio no los almacena.
Campos obligatorios: ruc, usuario_sol, clave_sol, indice
cURL
curl -X POST "https://api.factosperu.com/api/v1/sunafil/documento" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","indice":0}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/sunafil/documento', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'indice' => 0]);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/sunafil/documento', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","indice":0}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"documentos": [
{
"nombre": "CONSTANCIA_DEPOSITO_EJEMPLO.pdf",
"bytes": 25580,
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
"pdf_base64": "JVBERi0x"
}
]
},
"time": 0.42
}
Errores
404: No existe documento en esa posición (`documento_no_disponible`).422: Campos inválidos.500: El proveedor informó un error (`sunafil_error` u otro código, reintentable).502: El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).503: El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Credenciales API SUNAT (3)
Extraer credenciales de API SUNAT
Abre «Gestión Credenciales de API SUNAT» del menú SOL y devuelve la aplicación registrada (ID y clave de la aplicación, alcance y APIs habilitadas) y el catálogo de APIs que se pueden elegir. Si el RUC no tiene aplicación, `tiene_aplicacion` es false: use `/credenciales-api/crear`. No cambia nada en SUNAT. Guarde la clave cifrada; esta API no la registra.
Campos obligatorios: ruc, usuario_sol, clave_sol
cURL
curl -X POST "https://api.factosperu.com/api/v1/credenciales-api" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/credenciales-api', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/credenciales-api', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"tiene_aplicacion": true,
"aplicacion": {
"id": "ID_INTERNO_SUNAT",
"codigo_aplicacion": "2020000000",
"nombre": "mi-sistema",
"url": "https://mi-sistema.pe",
"alcance": "desktop",
"client_id": "CLIENT_ID_EJEMPLO",
"client_secret": "CLIENT_SECRET_EJEMPLO",
"recursos": [
{
"recurso": "/v1/contribuyente/gem",
"nombre": "GRE Emision de Comprobantes"
}
]
},
"catalogo": [
{
"codigo": "2",
"nombre": "MIGE RCE y RVIE - SIRE",
"recurso": "/v1/contribuyente/migeigv",
"url_api": "https://api-sire.sunat.gob.pe"
},
{
"codigo": "3",
"nombre": "GRE Emision de Comprobantes",
"recurso": "/v1/contribuyente/gem",
"url_api": "https://api-cpe.sunat.gob.pe"
}
]
},
"time": 0.42
}
Errores
422: Campos inválidos.503: No se pudo iniciar sesión o abrir la gestión de credenciales (`servicio_no_disponible`, reintentable).401/403/429: token inválido, acceso restringido o límite alcanzado.
Crear aplicación y generar credenciales de API SUNAT
Registra la aplicación del RUC en «Gestión Credenciales de API SUNAT». Por defecto marca todas las APIs del catálogo y alcance `desktop` (como en la pantalla); envíe `recursos` solo para limitar la selección. SUNAT genera el ID y la clave, que se devuelven en la respuesta. Cambia la cuenta SOL: SUNAT permite una aplicación por RUC; si ya existe responde 409 y se usa `/credenciales-api/editar`.
Campos obligatorios: ruc, usuario_sol, clave_sol, nombre, url
cURL
curl -X POST "https://api.factosperu.com/api/v1/credenciales-api/crear" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","nombre":"mi-sistema","url":"https://mi-sistema.pe","alcance":"desktop","recursos":[[]]}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/credenciales-api/crear', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'nombre' => 'mi-sistema', 'url' => 'https://mi-sistema.pe', 'alcance' => 'desktop', 'recursos' => [0 => []]]);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/credenciales-api/crear', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","nombre":"mi-sistema","url":"https://mi-sistema.pe","alcance":"desktop","recursos":[[]]}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "created",
"retryable": false,
"data": {
"tiene_aplicacion": true,
"aplicacion": {
"id": "ID_INTERNO_SUNAT",
"codigo_aplicacion": "2020000000",
"nombre": "mi-sistema",
"url": "https://mi-sistema.pe",
"alcance": "desktop",
"client_id": "CLIENT_ID_EJEMPLO",
"client_secret": "CLIENT_SECRET_EJEMPLO",
"recursos": [
{
"recurso": "/v1/contribuyente/gem",
"nombre": "GRE Emision de Comprobantes"
}
]
},
"catalogo": [
{
"codigo": "2",
"nombre": "MIGE RCE y RVIE - SIRE",
"recurso": "/v1/contribuyente/migeigv",
"url_api": "https://api-sire.sunat.gob.pe"
},
{
"codigo": "3",
"nombre": "GRE Emision de Comprobantes",
"recurso": "/v1/contribuyente/gem",
"url_api": "https://api-cpe.sunat.gob.pe"
}
]
},
"time": 0.42
}
Errores
409: El RUC ya tiene una aplicación registrada (`aplicacion_existente`).422: Campos inválidos o APIs fuera del catálogo (`datos_invalidos`).502: SUNAT no aceptó los datos (`sunat_rechazo`).503: No se pudo iniciar sesión o abrir la gestión de credenciales (`servicio_no_disponible`, reintentable).401/403/429: token inválido, acceso restringido o límite alcanzado.
Editar aplicación de API SUNAT
Cambia nombre, URL, alcance o APIs habilitadas de la aplicación ya registrada. Envíe la lista completa de `recursos` que deben quedar. Cambia la cuenta SOL; si el RUC no tiene aplicación responde 404.
Campos obligatorios: ruc, usuario_sol, clave_sol, nombre, url, recursos
cURL
curl -X POST "https://api.factosperu.com/api/v1/credenciales-api/editar" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","nombre":"mi-sistema","url":"https://mi-sistema.pe","alcance":"desktop","recursos":[[]]}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/credenciales-api/editar', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'nombre' => 'mi-sistema', 'url' => 'https://mi-sistema.pe', 'alcance' => 'desktop', 'recursos' => [0 => []]]);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/credenciales-api/editar', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","nombre":"mi-sistema","url":"https://mi-sistema.pe","alcance":"desktop","recursos":[[]]}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "updated",
"retryable": false,
"data": {
"tiene_aplicacion": true,
"aplicacion": {
"id": "ID_INTERNO_SUNAT",
"codigo_aplicacion": "2020000000",
"nombre": "mi-sistema",
"url": "https://mi-sistema.pe",
"alcance": "desktop",
"client_id": "CLIENT_ID_EJEMPLO",
"client_secret": "CLIENT_SECRET_EJEMPLO",
"recursos": [
{
"recurso": "/v1/contribuyente/gem",
"nombre": "GRE Emision de Comprobantes"
}
]
},
"catalogo": [
{
"codigo": "2",
"nombre": "MIGE RCE y RVIE - SIRE",
"recurso": "/v1/contribuyente/migeigv",
"url_api": "https://api-sire.sunat.gob.pe"
},
{
"codigo": "3",
"nombre": "GRE Emision de Comprobantes",
"recurso": "/v1/contribuyente/gem",
"url_api": "https://api-cpe.sunat.gob.pe"
}
]
},
"time": 0.42
}
Errores
404: El RUC no tiene aplicación registrada (`sin_aplicacion`).422: Campos inválidos o APIs fuera del catálogo (`datos_invalidos`).502: SUNAT no aceptó los datos (`sunat_rechazo`).503: No se pudo iniciar sesión o abrir la gestión de credenciales (`servicio_no_disponible`, reintentable).401/403/429: token inválido, acceso restringido o límite alcanzado.
SIRE (1)
Obtener token de pantalla SIRE
Obtiene el token de Ventas o Compras mediante SOL. No presenta libros. No se garantiza equivalencia con el token OAuth de la API pública SIRE. La respuesta no debe almacenarse ni registrarse.
Campos obligatorios: ruc, usuario_sol, clave_sol, libro
cURL
curl -X POST "https://api.factosperu.com/api/v1/sire/token" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","libro":"ventas"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/sire/token', ['ruc' => '20123456789', 'usuario_sol' => 'USUARIO_SOL', 'clave_sol' => 'CLAVE_SOL', 'libro' => 'ventas']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/sire/token', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789","usuario_sol":"USUARIO_SOL","clave_sol":"CLAVE_SOL","libro":"ventas"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"access_token": "TOKEN_FICTICIO",
"token_type": "Bearer",
"libro": "ventas",
"menu": "60.2.1.1.1",
"origen": "menu_sol"
},
"time": 0.42
}
Errores
422: Campos inválidos.503: Token no disponible; error genérico sin secretos.401/403/429: token inválido, acceso restringido o límite alcanzado.
Padrón y datos públicos (9)
Consulta RUC en el Padrón Reducido
Busca el RUC en la copia local del Padrón Reducido oficial de SUNAT importada en el servicio. No usa navegador ni credenciales. Responde 404 si el RUC no figura en la copia local (incluido el caso de un padrón aún no importado).
Campos obligatorios: ruc
cURL
curl -X POST "https://api.factosperu.com/api/v1/padron/ruc" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"ruc":"20123456789"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->post('https://api.factosperu.com/api/v1/padron/ruc', ['ruc' => '20123456789']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/padron/ruc', {
method: 'POST',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
body: JSON.stringify({"ruc":"20123456789"}),
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"ruc": "20123456789",
"nombre_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
"estado": "ACTIVO",
"condicion": "HABIDO",
"ubigeo": "150101",
"domicilio_fiscal": "AV. EJEMPLO 123",
"updated_at": "2026-10-01T00:00:00+00:00"
},
"source": "sunat_padron_reducido",
"time": 0.42
}
Errores
404: Registro no encontrado en la fuente local (`not_found`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).502: Error del proveedor (`proveedor_error`).422: RUC inválido.401/403/429: token inválido, acceso restringido o límite alcanzado.
Búsqueda por razón social
Busca contribuyentes por razón social en la copia local del Padrón Reducido. Devuelve una lista (vacía si no hay coincidencias).
Campos obligatorios: q
q(query, obligatorio): Texto de la razón social.limit(query): Máximo de resultados.
cURL
curl -X GET "https://api.factosperu.com/api/v1/padron/buscar?q=DEMOSTRACION" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/padron/buscar', ['q' => 'DEMOSTRACION']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/padron/buscar?q=DEMOSTRACION', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": [
{
"ruc": "20123456789",
"nombre_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
"estado": "ACTIVO",
"condicion": "HABIDO",
"ubigeo": "150101",
"domicilio_fiscal": "AV. EJEMPLO 123",
"updated_at": "2026-10-01T00:00:00+00:00"
}
],
"source": "sunat_padron_reducido",
"time": 0.42
}
Errores
422: Texto de búsqueda ausente o fuera de rango.502: Error del proveedor (`proveedor_error`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).401/403/429: token inválido, acceso restringido o límite alcanzado.
Establecimientos anexos de un RUC
Lista los establecimientos anexos del RUC según el dataset oficial importado en el servicio.
Campos obligatorios: ruc
ruc(en la ruta, obligatorio)
cURL
curl -X GET "https://api.factosperu.com/api/v1/ruc/20123456789/establecimientos" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/ruc/20123456789/establecimientos');
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/ruc/20123456789/establecimientos', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": [
{
"ruc": "20123456789",
"codigo": "0001",
"tipo": "SUCURSAL",
"direccion": "AV. EJEMPLO 456"
}
],
"source": "sunat_establecimientos",
"time": 0.42
}
Errores
404: Registro no encontrado en la fuente local (`not_found`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).502: Error del proveedor (`proveedor_error`).422: RUC inválido.401/403/429: token inválido, acceso restringido o límite alcanzado.
Sujeto sin capacidad operativa (SSCO)
Indica si el RUC figura en el padrón oficial de Sujetos Sin Capacidad Operativa importado en el servicio. 404 significa que no figura en la copia importada.
Campos obligatorios: ruc
ruc(en la ruta, obligatorio)
cURL
curl -X GET "https://api.factosperu.com/api/v1/ssco/20123456789" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/ssco/20123456789');
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/ssco/20123456789', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"RUC": "20123456789",
"RAZON SOCIAL": "EMPRESA DEMOSTRACION S.A.C."
},
"source": "ssco",
"time": 0.42
}
Errores
404: Registro no encontrado en la fuente local (`not_found`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).502: Error del proveedor (`proveedor_error`).422: RUC inválido.401/403/429: token inválido, acceso restringido o límite alcanzado.
Ubigeos (INEI)
Busca códigos de ubigeo en el dataset oficial importado en el servicio.
Campos obligatorios: ninguno
q(query): Texto a buscar en el registro. Vacío devuelve los primeros registros.limit(query): Máximo de registros.
cURL
curl -X GET "https://api.factosperu.com/api/v1/ubigeos?q=LIMA" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/ubigeos', ['q' => 'LIMA']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/ubigeos?q=LIMA', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": [
{
"ubigeo": "150101",
"departamento": "LIMA",
"provincia": "LIMA",
"distrito": "LIMA"
}
],
"source": "ubigeos",
"time": 0.42
}
Errores
422: Parámetros inválidos.502: Error del proveedor (`proveedor_error`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).401/403/429: token inválido, acceso restringido o límite alcanzado.
Puertos (MTC)
Busca puertos en el dataset oficial del MTC importado en el servicio.
Campos obligatorios: ninguno
q(query): Texto a buscar en el registro. Vacío devuelve los primeros registros.limit(query): Máximo de registros.
cURL
curl -X GET "https://api.factosperu.com/api/v1/puertos?q=LIMA" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/puertos', ['q' => 'LIMA']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/puertos?q=LIMA', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": [
{
"codigo": "PECLL",
"nombre": "CALLAO"
}
],
"source": "puertos",
"time": 0.42
}
Errores
422: Parámetros inválidos.502: Error del proveedor (`proveedor_error`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).401/403/429: token inválido, acceso restringido o límite alcanzado.
Aeropuertos (MTC)
Busca aeropuertos en el dataset oficial del MTC importado en el servicio.
Campos obligatorios: ninguno
q(query): Texto a buscar en el registro. Vacío devuelve los primeros registros.limit(query): Máximo de registros.
cURL
curl -X GET "https://api.factosperu.com/api/v1/aeropuertos?q=LIMA" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/aeropuertos', ['q' => 'LIMA']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/aeropuertos?q=LIMA', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": [
{
"iata": "LIM",
"nombre": "JORGE CHAVEZ"
}
],
"source": "aeropuertos",
"time": 0.42
}
Errores
422: Parámetros inválidos.502: Error del proveedor (`proveedor_error`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).401/403/429: token inválido, acceso restringido o límite alcanzado.
Tipo de cambio
Devuelve el tipo de cambio de una fecha y moneda (SBS; historial en caché del proveedor). Si ese día no hubo publicación (fin de semana o feriado) responde 404. Para el último publicado usar `GET /api/v1/tipo-cambio/actual`.
Campos obligatorios: fecha
fecha(query, obligatorio): Fecha en formato AAAA-MM-DD.moneda(query): Código ISO de la moneda.
cURL
curl -X GET "https://api.factosperu.com/api/v1/tipo-cambio?fecha=2026-10-09" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/tipo-cambio', ['fecha' => '2026-10-09']);
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/tipo-cambio?fecha=2026-10-09', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"fecha": "2026-10-09",
"moneda": "USD",
"compra": "VALOR",
"venta": "VALOR"
},
"source": "tipo_cambio",
"time": 0.42
}
Errores
404: Registro no encontrado en la fuente local (`not_found`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).502: Error del proveedor (`proveedor_error`).422: Fecha o moneda inválida.401/403/429: token inválido, acceso restringido o límite alcanzado.
Tipo de cambio actual
Devuelve el último tipo de cambio publicado hasta hoy: el de hoy si ya está publicado; si no, el del día anterior más cercano. `data.fecha` indica a qué día corresponde.
Campos obligatorios: ninguno
moneda(query): Código ISO de la moneda.
cURL
curl -X GET "https://api.factosperu.com/api/v1/tipo-cambio/actual" \ -H "Authorization: Bearer TU_TOKEN" \ -H "Accept: application/json"
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
->acceptJson()
->get('https://api.factosperu.com/api/v1/tipo-cambio/actual');
$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/tipo-cambio/actual', {
method: 'GET',
headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json' },
});
const datos = await res.json();
Respuesta de ejemplo
{
"success": true,
"code": "found",
"retryable": false,
"data": {
"fecha": "2026-10-09",
"moneda": "USD",
"compra": "VALOR",
"venta": "VALOR"
},
"source": "tipo_cambio",
"time": 0.42
}
Errores
404: Registro no encontrado en la fuente local (`not_found`).503: El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`).502: Error del proveedor (`proveedor_error`).422: Moneda inválida.401/403/429: token inválido, acceso restringido o límite alcanzado.