# Acceso y permisos

Crea, limita, rota y revoca las credenciales de integración de la empresa.

## Acceso de empresa

Un administrador de una empresa de Homito existente y verificada crea una clave en **Configuración → API y agentes**. Necesita una sesión de usuario de Homito y el permiso `settings.edit`. El secreto se muestra una sola vez: guárdalo en el gestor de secretos de tu servidor. La clave determina la empresa; enviar un ID de empresa distinto no amplía su acceso. El registro externo de empresas por autoservicio no está disponible. La gestión de claves utiliza el origen de la aplicación web de Homito y su sesión de usuario, no este origen de API externa.

## Elige una tarea y sus permisos

| Tarea | Permisos de la clave | Empieza aquí |
| --- | --- | --- |
| Consultar inmuebles y unidades | `read:properties` | `GET /api/v1/landlord/inventory/properties` |
| Consultar anuncios publicados y no publicados; sincronizar anuncios | `read:properties`; `write:properties` para la modificación correspondiente | `GET /api/v1/landlord/listings`, `GET /api/v1/landlord/listings/changes`, `PATCH /api/v1/landlord/listings/{unitId}/content`, `POST /api/v1/landlord/listings/{unitId}/media/uploads`, `POST /api/v1/landlord/listings/{unitId}/media/uploads/{uploadId}/complete`, `PATCH /api/v1/landlord/listings/{unitId}/media`, `PATCH /api/v1/landlord/listings/{unitId}/publication` |
| Consultar datos de contacto de inquilinos | `read:tenants` | `GET /api/v1/landlord/tenants` |
| Consultar la cronología de los contratos de arrendamiento | `read:leases` | `GET /api/v1/landlord/leases` |
| Consultar resúmenes de solicitudes | `read:applications` | `GET /api/v1/landlord/applications` |
| Previsualizar y confirmar inmuebles y unidades | `write:properties`; `read:properties` para consultar el resultado | `POST /api/v1/landlord/portfolio-imports/preview` |
| Consultar o importar cuadros de rentas comerciales | `read:rent-roll`; `write:rent-roll` para importar | `GET /api/v1/landlord/rent-roll` |
| Consultar o actualizar tareas operativas | `read:fault-reports`, `read:work-orders`; `write:fault-reports`, `write:work-orders` para la modificación correspondiente | `GET /api/v1/landlord/fault-reports`, `GET /api/v1/landlord/work-orders` |
| Consultar o realizar inspecciones comerciales | `read:inspections`; `write:inspections` para las modificaciones | `GET /api/v1/landlord/commercial-inspections` |
| Consultar o utilizar la asistencia a inquilinos comerciales | `read:commercial-assistance`; `write:commercial-assistance` para las modificaciones | `GET /api/v1/landlord/commercial-assistance` |
| Iniciar una evaluación y consultar el estado certificado | `write:screenings`, `read:screenings`; `read:applications` para seleccionar un candidato | `POST /api/v1/landlord/screenings` |
| Registrar webhooks y supervisar las entregas | `write:webhooks`, `read:webhooks` | `POST /api/v1/landlord/webhooks` |
| Usar el cupo de solicitudes del servidor del cliente o la transferencia eID alojada | `write:applications` en una clave de servidor independiente | `POST /api/v1/public/units/{slug}/application-eid/handoffs` |

## Conoce los límites humanos y del portal

| Acción | Vía disponible | Límite humano o del portal |
| --- | --- | --- |
| Primer acceso de empresa; crear, rotar o revocar una clave | Plano de control de administrador autenticado | Requiere una empresa existente verificada, una sesión de usuario y `settings.edit` |
| Consultas autorizadas y escrituras compatibles habituales | API REST externa; herramientas MCP compatibles tras verificar la distribución | No requiere interactuar con el panel para cada operación habitual |
| Editar el nombre del anuncio y el texto de la unidad | PATCH de contenido de anuncios; herramienta MCP compatible tras verificar la distribución | Requiere `write:properties` vigente; los medios y la publicación requieren su delegación explícita de anuncios |
| Ejecución de evaluaciones, Detective y gestión de casos por operadores | Servicio StaySafe independiente | La integración de Homito devuelve únicamente la proyección certificada permitida para el arrendador |
| Decisiones sobre solicitantes y revisión de inspecciones | Sus operaciones de decisión o revisión expresamente autorizadas | Poseer una clave o recibir instrucciones de un agente no sustituye la autoridad humana ni la separación de funciones |

## Rota y retira las credenciales

Para rotar una clave, crea otra con los mismos permisos o menos, impleméntala en la integración y verifica una consulta autenticada. Antes de revocar la anterior, termina o determina el resultado de sus previsualizaciones y trabajos pendientes utilizando la clave anterior. La clave de sustitución no hereda sus ID de trabajo ni su historial. Después, revoca la clave anterior. El administrador utiliza **Configuración → API y agentes** o su plano de control autenticado `/api/v1/settings/api-keys`. Una clave de integración de empresa no es una sesión de administrador. Los ID de clave son referencias no secretas, no credenciales; la clave en texto sin procesar no puede recuperarse más adelante. Verifica que se rechaza la clave retirada.

## Mantén los datos privados fuera de las cachés públicas

Mantén los datos personales, los recibos y las capacidades de carga fuera de las cachés públicas de anuncios. Las consultas de inquilinos y solicitudes devuelven deliberadamente proyecciones operativas mínimas; no deduzcas campos privados ausentes ni conclusiones de evaluación. Distingue los valores null o desconocidos de cero o de un resultado completado.

## Usa la versión publicada del contrato

Usa la versión de API y el ciclo de vida indicados en la referencia, los esquemas de cada operación y cualquier versión de formulario o recurso requerida al actualizar una integración. Conserva las versiones opacas sin cambios y fija una versión MCP aprobada. Los nombres de evento proceden del mismo catálogo que la API; el orden de llegada y una versión de producto no sustituyen la consulta actual del recurso.