Saltar al contenido principal
Docs Sitio Planes

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

URL base
https://api.factosperu.com
Autenticación
Authorization: Bearer TU_TOKEN
Formato
JSON: 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.

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

POST /api/v1/ruc · 1 por solicitud

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.
Más detalle

Consulta RUC (ficha SUNAT)

POST /api/v1/ruc-sunat · 1 por solicitud

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.
Más detalle

Consulta RUC por DNI

POST /api/v1/dni-ruc · 1 por solicitud

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.
Más detalle

Consulta DNI

POST /api/v1/dni · 1 por solicitud

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.
Más detalle

Consulta por Carnet de Extranjería

POST /api/v1/carnet-extranjeria · 1 por solicitud

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.
Más detalle

Consulta por Pasaporte

POST /api/v1/pasaporte · 1 por solicitud

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.
Más detalle

Consulta por Cédula Diplomática de Identidad

POST /api/v1/cedula-diplomatica · 1 por solicitud

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.
Más detalle

Búsqueda por razón social en línea

POST /api/v1/razon-social · 1 por solicitud

Busca contribuyentes por nombre o razón social en el portal público de SUNAT. Para una búsqueda sin navegador, usar `/api/v1/padron/buscar`.

Campos obligatorios: razon_social

cURL

curl -X POST "https://api.factosperu.com/api/v1/razon-social" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"razon_social":"EMPRESA DEMOSTRACION"}'
PHP (Laravel)
$respuesta = Http::withToken('TU_TOKEN')
    ->acceptJson()
    ->post('https://api.factosperu.com/api/v1/razon-social', ['razon_social' => 'EMPRESA DEMOSTRACION']);

$datos = $respuesta->json();
JavaScript
const res = await fetch('https://api.factosperu.com/api/v1/razon-social', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TU_TOKEN', 'Accept': 'application/json', 'Content-Type': 'application/json' },
  body: JSON.stringify({"razon_social":"EMPRESA DEMOSTRACION"}),
});
const datos = await res.json();

Respuesta de ejemplo

{
    "success": true,
    "code": "found",
    "retryable": false,
    "data": {
        "resultados": [
            {
                "ruc": "20123456789",
                "razon_social": "EMPRESA DEMOSTRACION S.A.C."
            }
        ]
    },
    "time": 0.42
}

Errores

  • 404: Sin coincidencias (`not_found`).
  • 422: Texto ausente, menor de 3 caracteres o mayor de 120.
  • 502: El proveedor no pudo completar la consulta (código del proveedor, `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.
Más detalle

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

  1. En la configuración de tu sistema, pon la URL base https://api.factosperu.com.
  2. Envía tu token con el encabezado Authorization: Bearer TU_TOKEN.
  3. 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

GET /api/dni/{dni} · 1 por solicitud

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.
Más detalle

Consulta RUC por GET

GET /api/ruc/{ruc} · 1 por solicitud

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.
Más detalle

Comprobantes (3)

Consulta y descarga de CPE

POST /api/v1/cpe · 1 por comprobante del lote (máximo 100)

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.
Más detalle

Consulta CPE de un RUC excluido

POST /api/v1/ruc/excluido · 1 por solicitud

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.
Más detalle

Validación múltiple de CPE

POST /api/v1/validacion-multiple-cpe · 1 por comprobante del lote (máximo 100)

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.
Más detalle

Buzón SOL (1)

Consulta del buzón electrónico

POST /api/v1/buzon · 1 por solicitud

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.
Más detalle

Casilla SUNAFIL (2)

Consulta de la casilla electrónica SUNAFIL

POST /api/v1/sunafil/casilla · 1 por solicitud

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.
Más detalle

Descarga de documento SUNAFIL (en memoria)

POST /api/v1/sunafil/documento · 1 por solicitud

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.
Más detalle

Credenciales API SUNAT (3)

Extraer credenciales de API SUNAT

POST /api/v1/credenciales-api · 1 por solicitud

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.
Más detalle

Crear aplicación y generar credenciales de API SUNAT

POST /api/v1/credenciales-api/crear · 1 por solicitud

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.
Más detalle

Editar aplicación de API SUNAT

POST /api/v1/credenciales-api/editar · 1 por solicitud

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.
Más detalle

SIRE (1)

Obtener token de pantalla SIRE

POST /api/v1/sire/token · 1 por solicitud

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.
Más detalle

Padrón y datos públicos (9)

Consulta RUC en el Padrón Reducido

POST /api/v1/padron/ruc · 1 por solicitud

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.
Más detalle

Búsqueda por razón social

GET /api/v1/padron/buscar · 1 por solicitud

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.
Más detalle

Establecimientos anexos de un RUC

GET /api/v1/ruc/{ruc}/establecimientos · 1 por solicitud

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.
Más detalle

Sujeto sin capacidad operativa (SSCO)

GET /api/v1/ssco/{ruc} · 1 por solicitud

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.
Más detalle

Ubigeos (INEI)

GET /api/v1/ubigeos · 1 por solicitud

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.
Más detalle

Puertos (MTC)

GET /api/v1/puertos · 1 por solicitud

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.
Más detalle

Aeropuertos (MTC)

GET /api/v1/aeropuertos · 1 por solicitud

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.
Más detalle

Tipo de cambio

GET /api/v1/tipo-cambio · 1 por solicitud

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.
Más detalle

Tipo de cambio actual

GET /api/v1/tipo-cambio/actual · 1 por solicitud

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.
Más detalle