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étodo | Ruta | Entrada requerida | Referencia |
|---|---|---|---|
| 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/status | Sin token | Respuesta 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.