Acceso gobernado, exportación y operación por tenant
Use siempre una API key con privilegio mínimo.
La API pública permite consultar y exportar información comercial gobernada sin acceder a las pantallas internas. Cada respuesta está limitada al tenant, al usuario de servicio y a los permisos asignados.
La versión documentada es v1 y mantiene envelopes, códigos de error y cursores estables.
La base productiva es https://revup.cl/{slug}/api/public/v1 y la documentación interactiva es https://revup.cl/{slug}/api-docs/. Reemplace {slug} por la ruta pública entregada a la empresa.
El slug forma parte de la ruta y nunca debe enviarse como query string, header o dato libre.
Un administrador crea un usuario de servicio activo, habilita public_api y emite una API key vinculada a ese usuario. Luego concede solo los scopes necesarios.
El scope habilita una capacidad, pero no amplía el RBAC: la integración ve únicamente los clientes, equipos y oportunidades visibles para su usuario de servicio.
La clave completa se muestra una sola vez. Debe guardarse en un vault y enviarse como Authorization: Bearer <apiKey>.
Use una clave por integración, rótela periódicamente, revoque las claves sin uso y nunca la incluya en código, documentación, tickets o repositorios.
Swagger permite explorar el contrato y ejecutar llamadas autorizadas sin persistir el token tras la sesión. La colección Postman contiene ejemplos, tests, cursores y todos los formatos de exportación.
Los manuales, OpenAPI y Postman se sirven desde el mismo tenant y no dependen de CDN.
Las listas aceptan limit y cursor. El cursor es opaco: no lo modifique ni lo reutilice con otro recurso o tenant.
Los filtros de fechas usan ISO 8601. Los filtros desconocidos o combinaciones inválidas reciben un error sanitizado.
Cree un job con recurso, formato y filtros; consulte su estado; descargue al finalizar y elimínelo cuando deje de ser necesario. Los formatos soportados son CSV, JSONL y XLSX.
Cada archivo admite hasta 100.000 filas, se almacena fuera del document root y expira a las 24 horas.
401 indica credencial inválida; 403 entitlement, usuario o scope insuficiente; 409 recurso todavía no listo; 422 dato inválido; 429 límite excedido.
Conserve X-Correlation-ID al solicitar soporte. Los mensajes están sanitizados y nunca deben revelar SQL, rutas privadas o secretos.
El slug resuelve una instalación de tenant; el bootstrap autentica la clave por hash, valida estado, entitlement, scope y usuario de servicio, y recién entonces abre el acceso al repositorio del tenant.
No existe selección de base mediante input del cliente. Los archivos exportados viven en un root privado.
OpenAPI 3.1 es generado desde el mismo registro que el runtime. Las respuestas JSON usan un envelope estable con ok, data y meta; los errores usan ok=false y un objeto error sanitizado.
La clave Bearer identifica tenant, ambiente, prefijo y secreto. Solo se persiste el hash. La autorización combina entitlement, scope y visibilidad del usuario de servicio.
La revocación, expiración o inactividad se evalúan en cada request.
Los cursores están firmados y ligados a tenant y recurso. Los jobs se reclaman con locks de base de datos, admiten reintentos acotados y no publican un archivo parcial.
CSV usa encabezado estable y escaping RFC 4180; JSONL emite un objeto por línea; XLSX limita fórmulas y neutraliza valores peligrosos. Todas las salidas respetan el mismo conjunto de campos.
Ejemplos equivalentes: curl, JavaScript fetch, Python requests, PHP cURL y PowerShell Invoke-RestMethod. Todos usan variables de entorno y omiten secretos reales.
El worker procesa jobs en lotes, actualiza progreso, publica con rename atómico y registra errores sanitizados. Un timer evita solapamientos; las garantías definitivas residen en locks de filas.
El mismo bundle inmutable instala runtime, OpenAPI, Swagger, Postman, manuales y migraciones. QA debe aprobar antes de producción. Se preservan .revup-instance.php, private/, vaults y secretos del tenant.
Registre operationId, status, duración, correlation ID y una identidad no reversible de la clave. Nunca registre Authorization, filas exportadas ni secretos. Métricas mínimas: tasa, latencia, errores, jobs y bytes.
Valide slug, reloj, estado de la clave, scopes, entitlement y RBAC. Ante 429 respete Retry-After. Ante exportaciones fallidas use correlation ID y error sanitizado; no inspeccione ni exponga datos del archivo.
| operationId | Método y ruta | Scope | Descripción |
|---|---|---|---|
createExport | POST /exports | exports:write | Devuelve un trabajo de exportación dentro del tenant autorizado. |
deleteExport | DELETE /exports/{id} | exports:delete | Devuelve la eliminación de una exportación dentro del tenant autorizado. |
downloadExport | GET /exports/{id}/download | exports:read | Devuelve el archivo exportado dentro del tenant autorizado. |
getActivity | GET /activities/{id} | activities:read | Devuelve una actividad dentro del tenant autorizado. |
getCatalog | GET /catalogs/{type} | products:read | Devuelve un catálogo dentro del tenant autorizado. |
getClient | GET /clients/{id} | clients:read | Devuelve un cliente dentro del tenant autorizado. |
getClientTimeline | GET /clients/{id}/timeline | clients:read | Devuelve la línea de tiempo del cliente dentro del tenant autorizado. |
getContact | GET /contacts/{id} | contacts:read | Devuelve un contacto dentro del tenant autorizado. |
getCustomerSuccess | GET /customer-success/{clientId} | customer_success:read | Devuelve el resumen de customer success del cliente dentro del tenant autorizado. |
getExport | GET /exports/{id} | exports:read | Devuelve el estado de una exportación dentro del tenant autorizado. |
getHealth | GET /health | health:read | Devuelve estado de la API dentro del tenant autorizado. |
getOpportunity | GET /opportunities/{id} | opportunities:read | Devuelve una oportunidad dentro del tenant autorizado. |
getProduct | GET /products/{id} | products:read | Devuelve un producto dentro del tenant autorizado. |
listActivities | GET /activities | activities:read | Devuelve actividades dentro del tenant autorizado. |
listAiUsage | GET /ai/usage | ai_usage:read | Devuelve consumo agregado de IA dentro del tenant autorizado. |
listAuditEvents | GET /audit-events | audit:read | Devuelve eventos de auditoría sanitizados dentro del tenant autorizado. |
listChanges | GET /changes | changes:read | Devuelve cambios incrementales dentro del tenant autorizado. |
listClients | GET /clients | clients:read | Devuelve clientes dentro del tenant autorizado. |
listCommitments | GET /commitments | commitments:read | Devuelve compromisos dentro del tenant autorizado. |
listContacts | GET /contacts | contacts:read | Devuelve contactos dentro del tenant autorizado. |
listCustomerSuccess | GET /customer-success | customer_success:read | Devuelve resúmenes de customer success dentro del tenant autorizado. |
listFeedback | GET /feedback | feedback:read | Devuelve feedback dentro del tenant autorizado. |
listForecast | GET /forecast | forecast:read | Devuelve pronóstico comercial dentro del tenant autorizado. |
listGoals | GET /goals | goals:read | Devuelve metas dentro del tenant autorizado. |
listKpis | GET /kpis | kpis:read | Devuelve indicadores KPI dentro del tenant autorizado. |
listMarketIntelligence | GET /market-intelligence | market_intelligence:read | Devuelve hallazgos de inteligencia de mercado dentro del tenant autorizado. |
listOpportunities | GET /opportunities | opportunities:read | Devuelve oportunidades dentro del tenant autorizado. |
listPipelineSnapshots | GET /pipeline/snapshots | pipeline:read | Devuelve instantáneas del pipeline dentro del tenant autorizado. |
listProducts | GET /products | products:read | Devuelve productos dentro del tenant autorizado. |
listUsers | GET /users | users:read | Devuelve usuarios autorizados dentro del tenant autorizado. |
clients:readDatos públicos gobernados de clientes.
| Campos | Filtros | Exportación |
|---|---|---|
| id, company_code, legal_name, trade_name, tax_identifier, country_code, region, municipality, industry_code, billing_method, payment_method, status, owner_user_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status | CSV, JSONL, XLSX |
contacts:readDatos públicos gobernados de contactos.
| Campos | Filtros | Exportación |
|---|---|---|
| id, client_id, first_name, last_name, job_title, email, phone, is_primary, status, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, client_id | CSV, JSONL, XLSX |
products:readDatos públicos gobernados de productos y catálogos.
| Campos | Filtros | Exportación |
|---|---|---|
| id, code, name, description, product_type, billing_period, currency, unit_price, status, valid_from, valid_to, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, currency, billing_period, product_type | CSV, JSONL, XLSX |
opportunities:readDatos públicos gobernados de oportunidades.
| Campos | Filtros | Exportación |
|---|---|---|
| id, client_id, name, stage, status, currency, amount, probability_percent, expected_close_date, owner_user_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, client_id, owner_user_id, currency | CSV, JSONL, XLSX |
activities:readDatos públicos gobernados de actividades.
| Campos | Filtros | Exportación |
|---|---|---|
| id, client_id, opportunity_id, activity_type, subject, description, occurred_at, due_at, status, owner_user_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, client_id, owner_user_id, activity_type | CSV, JSONL, XLSX |
commitments:readDatos públicos gobernados de compromisos.
| Campos | Filtros | Exportación |
|---|---|---|
| id, client_id, opportunity_id, title, description, due_at, completed_at, status, owner_user_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, client_id, owner_user_id | CSV, JSONL, XLSX |
pipeline:readDatos públicos gobernados de instantáneas del pipeline.
| Campos | Filtros | Exportación |
|---|---|---|
| id, snapshot_at, stage, currency, opportunity_count, weighted_amount, unweighted_amount, owner_user_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, owner_user_id, currency, period | CSV, JSONL, XLSX |
forecast:readDatos públicos gobernados de pronóstico.
| Campos | Filtros | Exportación |
|---|---|---|
| id, period, currency, category, forecast_amount, committed_amount, best_case_amount, owner_user_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, owner_user_id, currency, period | CSV, JSONL, XLSX |
kpis:readDatos públicos gobernados de indicadores KPI.
| Campos | Filtros | Exportación |
|---|---|---|
| id, code, name, period, value, unit, target_value, owner_user_id, status, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, owner_user_id, period | CSV, JSONL, XLSX |
goals:readDatos públicos gobernados de metas.
| Campos | Filtros | Exportación |
|---|---|---|
| id, name, description, period, target_value, actual_value, unit, owner_user_id, status, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, owner_user_id, period | CSV, JSONL, XLSX |
users:readDatos públicos gobernados de usuarios.
| Campos | Filtros | Exportación |
|---|---|---|
| id, display_name, email, role_code, team_code, is_active, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, role_code, team_code | CSV, JSONL, XLSX |
customer_success:readDatos públicos gobernados de customer success.
| Campos | Filtros | Exportación |
|---|---|---|
| id, client_id, health_status, health_score, risk_level, last_contact_at, next_action_at, owner_user_id, status, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, client_id, owner_user_id, health_status, risk_level | CSV, JSONL, XLSX |
feedback:readDatos públicos gobernados de feedback.
| Campos | Filtros | Exportación |
|---|---|---|
| id, client_id, feedback_code, category, title, description, status, submitted_by_user_id, assigned_to_user_id, resolved_at, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, client_id, category | CSV, JSONL, XLSX |
audit:readDatos públicos gobernados de eventos de auditoría.
| Campos | Filtros | Exportación |
|---|---|---|
| id, action, actor_user_id, resource_type, resource_id, correlation_id, result, occurred_at, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, actor_user_id, resource_type, resource_id, correlation_id | CSV, JSONL, XLSX |
ai_usage:readDatos públicos gobernados de consumo de IA.
| Campos | Filtros | Exportación |
|---|---|---|
| id, period, provider, model, operation_count, model_usage_units, error_count, currency, provider_cost, billable_amount, is_billable, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, period, provider, currency | CSV, JSONL, XLSX |
market_intelligence:readDatos públicos gobernados de inteligencia de mercado.
| Campos | Filtros | Exportación |
|---|---|---|
| id, source, finding_type, title, summary, published_at, relevance_score, status, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, source, finding_type | CSV, JSONL, XLSX |
changes:readDatos públicos gobernados de cambios.
| Campos | Filtros | Exportación |
|---|---|---|
| id, resource_type, resource_id, change_type, changed_at, correlation_id, created_at, updated_at | limit, cursor, created_from, created_to, updated_from, updated_to, status, resource_type, change_type | No aplica |