Saltar al contenido principal
Docs Sitio Planes

Documentación de la API

Manual de FactosPerú API: consultas a SUNAT (RUC, DNI, comprobantes, buzón SOL, casilla SUNAFIL) y datos públicos oficiales (padrón, tipo de cambio, ubigeos y más).

URL base de producción

https://api.factosperu.com/api/v1

Todas las rutas de este manual se escriben a partir de ese dominio. Las solicitudes van siempre por HTTPS.

Referencia interactiva (OpenAPI 3.1)

Cada ruta con ejemplos listos en cURL, PHP y JavaScript en el catálogo de endpoints. Catálogo completo con esquemas, ejemplos y prueba de solicitudes en la referencia interactiva. Descarga la especificación openapi.json o la colección Postman con su entorno (manual de Postman); se generan desde el contrato del código.

Autenticación

Las rutas de consulta requieren el token de tu cuenta en el encabezado Bearer.

Authorization: Bearer TU_TOKEN
Content-Type: application/json

El token nuevo se muestra una sola vez al generarlo. Administrar token.

Las consultas también están disponibles temporalmente en las rutas sin versión /api/ruc, /api/dni, /api/cpe y /api/validacion-multiple-cpe; comparten autenticación, límites y contrato con /api/v1. No hay ruta legacy de buzón.

Ejemplo de integración con cURL

Define API_BASE_URL con el dominio principal y proporciona tu token mediante la variable API_TOKEN; no lo guardes en el código fuente.

API_BASE_URL="https://api.factosperu.com"

curl --request POST "${API_BASE_URL}/api/v1/ruc" \
  --header "Authorization: Bearer ${API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"ruc":"20123456789"}'

En Windows PowerShell usa curl.exe para invocar el ejecutable cURL.

Rutas disponibles

MétodoRutaEntrada requeridaReferencia
POST https://api.factosperu.com/api/v1/ruc ruc · 1 por solicitud RUC
POST https://api.factosperu.com/api/v1/ruc-sunat ruc · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/dni/{dni} dni · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/ruc/{ruc} ruc · 1 por solicitud Padrón y datos públicos
POST https://api.factosperu.com/api/v1/dni-ruc dni · 1 por solicitud Padrón y datos públicos
POST https://api.factosperu.com/api/v1/dni dni · 1 por solicitud DNI
POST https://api.factosperu.com/api/v1/carnet-extranjeria numero · 1 por solicitud Otros documentos
POST https://api.factosperu.com/api/v1/pasaporte numero · 1 por solicitud Otros documentos
POST https://api.factosperu.com/api/v1/cedula-diplomatica numero · 1 por solicitud Otros documentos
POST https://api.factosperu.com/api/v1/razon-social razon_social · 1 por solicitud Referencia OpenAPI
POST https://api.factosperu.com/api/v1/cpe ruc, usuario_sol, clave_sol, comprobantes · 1 por comprobante del lote (máximo 100) CPE
POST https://api.factosperu.com/api/v1/ruc/excluido ruc, tipo, folio, fecha, total · 1 por solicitud Referencia OpenAPI
POST https://api.factosperu.com/api/v1/validacion-multiple-cpe ruc, usuario_sol, clave_sol, comprobantes · 1 por comprobante del lote (máximo 100) Validación múltiple CPE
POST https://api.factosperu.com/api/v1/buzon ruc, usuario_sol, clave_sol · 1 por solicitud Buzón
POST https://api.factosperu.com/api/v1/sunafil/casilla ruc, usuario_sol, clave_sol · 1 por solicitud Casilla SUNAFIL
POST https://api.factosperu.com/api/v1/sunafil/documento ruc, usuario_sol, clave_sol, indice · 1 por solicitud Casilla SUNAFIL
POST https://api.factosperu.com/api/v1/credenciales-api ruc, usuario_sol, clave_sol · 1 por solicitud Padrón y datos públicos
POST https://api.factosperu.com/api/v1/sire/token ruc, usuario_sol, clave_sol, libro · 1 por solicitud Padrón y datos públicos
POST https://api.factosperu.com/api/v1/credenciales-api/crear ruc, usuario_sol, clave_sol, nombre, url · 1 por solicitud Padrón y datos públicos
POST https://api.factosperu.com/api/v1/credenciales-api/editar ruc, usuario_sol, clave_sol, nombre, url, recursos · 1 por solicitud Padrón y datos públicos
POST https://api.factosperu.com/api/v1/padron/ruc ruc · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/padron/buscar q · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/ruc/{ruc}/establecimientos ruc · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/ssco/{ruc} ruc · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/ubigeos Sin campos obligatorios · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/puertos Sin campos obligatorios · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/aeropuertos Sin campos obligatorios · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/tipo-cambio fecha · 1 por solicitud Padrón y datos públicos
GET https://api.factosperu.com/api/v1/tipo-cambio/actual Sin campos obligatorios · 1 por solicitud Padrón y datos públicos
GET/api/statusSin tokenRespuesta informativa

La estructura y los campos internos de cada elemento comprobantes dependen de la integración externa y no se describen aquí mientras su contrato no esté confirmado.

Consulta también la referencia de errores y códigos HTTP para interpretar respuestas de autenticación, validación, cuota y proveedor.

Límites y respuestas

La API aplica un límite operativo de 60 solicitudes por minuto por usuario, configurable con API_RATE_LIMIT_PER_MINUTE. Su 429 incluye Retry-After, X-RateLimit-Limit y X-RateLimit-Remaining. Se aplica a las rutas /api/v1 y sus alias legacy; /api/status queda excluido. Este límite es independiente de la cuota del plan: el rechazo por cuota también responde 429 y conserva X-RateLimit-Limit/X-RateLimit-Remaining, pero no incluye Retry-After.

Si el contador operativo no está disponible, la API falla de forma cerrada con 503 (error.tipo: rate_limit_unavailable) y Retry-After: 1; la consulta no continúa hacia el consumo.

Las validaciones de entrada responden 422. Puedes enviar opcionalmente Idempotency-Key: si una clave no vacía se repite para la misma cuenta, la petición posterior recibe 409; la API no reproduce la primera respuesta. Las claves no vacías se comparten entre los endpoints de consulta de esa cuenta.

Cada consulta válida enviada al servicio externo consume la cuota del plan aunque el resultado sea “no encontrado” o el proveedor devuelva un error. Los lotes descuentan una unidad por cada consulta/comprobante enviado. Los rechazos de validación anteriores al envío no consumen; esta cuota no representa un cobro monetario.

GET /api/status devuelve success, service y timestamp. Es una respuesta informativa; la ruta actual no consulta el proveedor Python ni verifica dependencias externas.

El formulario de contacto (POST /contacto) permite 5 intentos por minuto por IP, configurable con CONTACT_RATE_LIMIT_PER_MINUTE. Las solicitudes que excedan el límite reciben 429 antes de guardar el contacto.