Saltar a contenido

Situación de un residente

La API Business permite localizar a un residente dentro de una propiedad y consultar su situación actual. En esta primera versión, la situación incluye las incidencias abiertas por el propio residente en esa propiedad.

Autenticación

Todas las peticiones requieren un token Business de Laravel Sanctum en la cabecera Authorization:

Authorization: Bearer <token>
Accept: application/json

La URL base de producción es:

https://api.onzane.com/bus/v1

El token solo permite consultar comunidades pertenecientes a su administración. Cuando una comunidad, propiedad o residente no existe dentro de ese ámbito, la API responde con 404 Not Found; no se informa de si el recurso existe en otra administración.

Referencias necesarias

Las operaciones utilizan tres referencias:

  • community_reference: referencia externa de la comunidad en Onzane.
  • property_reference: referencia de la propiedad dentro de la comunidad.
  • resident_reference: identificador Business opaco y estable del residente, con formato res_….

No deben guardarse ni utilizarse los IDs numéricos internos de Onzane. Si todavía no dispone de la referencia Business del residente, puede obtenerla mediante el endpoint de descubrimiento.

1. Localizar al residente

GET /communities/{community_reference}/properties/{property_reference}/residents

El resultado está paginado. Para localizar a una persona concreta puede aplicar una coincidencia exacta por email:

curl --request GET \
  --url 'https://api.onzane.com/bus/v1/communities/COM-001/properties/VIV-1A/residents?email=ana%40example.com' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Parámetros de consulta:

Parámetro Tipo Obligatorio Descripción
email email No Coincidencia exacta; no distingue mayúsculas y minúsculas.
page entero No Página solicitada. Valor mínimo: 1.
per_page entero No Elementos por página. Predeterminado: 25; máximo: 100.

Respuesta 200 OK:

{
  "data": [
    {
      "reference": "res_01JY8K5VY3P8V3M76JDSN4MTQZ",
      "name": "Ana García López",
      "email": "ana@example.com",
      "membership": {
        "role": "owner",
        "since": "2025-02-10T09:30:00+00:00"
      }
    }
  ],
  "context": {
    "community": {
      "reference": "COM-001",
      "name": "Residencial Los Olivos"
    },
    "property": {
      "reference": "VIV-1A",
      "name": "1º A"
    }
  },
  "links": {
    "first": "https://api.onzane.com/bus/v1/communities/COM-001/properties/VIV-1A/residents?page=1",
    "last": "https://api.onzane.com/bus/v1/communities/COM-001/properties/VIV-1A/residents?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

El campo membership.role puede tener uno de estos valores:

Valor Significado
owner Propietario/a
tenant Inquilino/a
cohabitant Conviviente

Una respuesta válida con data: [] indica que la propiedad existe y es accesible, pero no hay ningún residente que coincida con el filtro.

2. Consultar la situación

GET /communities/{community_reference}/properties/{property_reference}/residents/{resident_reference}/status

Ejemplo:

curl --request GET \
  --url 'https://api.onzane.com/bus/v1/communities/COM-001/properties/VIV-1A/residents/res_01JY8K5VY3P8V3M76JDSN4MTQZ/status?per_page=25' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Los parámetros page y per_page controlan la paginación de open_incidents.data. per_page es 25 de forma predeterminada y admite un máximo de 100.

Respuesta 200 OK:

{
  "data": {
    "resident": {
      "reference": "res_01JY8K5VY3P8V3M76JDSN4MTQZ",
      "name": "Ana García López",
      "email": "ana@example.com",
      "membership": {
        "role": "owner",
        "since": "2025-02-10T09:30:00+00:00"
      }
    },
    "context": {
      "community": {
        "reference": "COM-001",
        "name": "Residencial Los Olivos"
      },
      "property": {
        "reference": "VIV-1A",
        "name": "1º A"
      }
    },
    "situation": {
      "open_incidents": {
        "total": 1,
        "data": [
          {
            "reference": "IN2500123",
            "status": "processing",
            "type": "maintenance",
            "visibility": "private",
            "is_urgent": false,
            "title": "Humedad en el techo del baño",
            "description": "La mancha ha aumentado durante la última semana.",
            "opened_at": "2026-08-07T10:15:00+00:00",
            "updated_at": "2026-08-08T08:40:00+00:00"
          }
        ],
        "links": {
          "first": "https://api.onzane.com/bus/v1/communities/COM-001/properties/VIV-1A/residents/res_01JY8K5VY3P8V3M76JDSN4MTQZ/status?page=1",
          "last": "https://api.onzane.com/bus/v1/communities/COM-001/properties/VIV-1A/residents/res_01JY8K5VY3P8V3M76JDSN4MTQZ/status?page=1",
          "prev": null,
          "next": null
        },
        "meta": {
          "current_page": 1,
          "from": 1,
          "last_page": 1,
          "per_page": 25,
          "to": 1,
          "total": 1
        }
      }
    }
  }
}

Qué se considera una incidencia abierta

open_incidents solo contiene incidencias abiertas por el residente consultado en la comunidad y propiedad de la URL. Los estados incluidos son:

Estado Significado
pending Pendiente de comenzar su gestión.
processing En proceso.
managed Gestionada, pendiente de cierre o resolución.
claimed Reclamada y todavía abierta.

Las incidencias resolved y cancelled no se incluyen. Las incidencias creadas como anónimas tampoco se devuelven, aunque internamente estén asociadas al residente, para preservar el anonimato ofrecido al crear la incidencia.

Si el residente no tiene incidencias abiertas, el endpoint devuelve 200 OK, total: 0 y data: [].

Campos de una incidencia

Campo Descripción
reference Número público y estable de la incidencia.
status Estado actual.
type Tipo funcional de incidencia.
visibility public o private. No equivale al anonimato.
is_urgent Indica si la incidencia se marcó como urgente.
title Título aportado al abrirla.
description Descripción aportada al abrirla.
opened_at Fecha y hora de apertura en formato ISO 8601.
updated_at Última modificación en formato ISO 8601.

Las fechas incluyen su desplazamiento horario. Se recomienda tratarlas como instantes ISO 8601 y convertirlas a la zona horaria deseada en el sistema consumidor.

Errores

Código Significado
401 Unauthorized El token falta, no es válido o ha sido revocado.
404 Not Found La comunidad, propiedad o residente no existe en el contexto solicitado, no pertenece a la administración del token o el residente ya no está vinculado a esa propiedad.
422 Unprocessable Entity email, page o per_page no tiene un formato o valor válido.

Ejemplo de error de validación:

{
  "message": "The per page field must not be greater than 100.",
  "errors": {
    "per_page": [
      "The per page field must not be greater than 100."
    ]
  }
}

Recomendaciones de integración

  • Guarde resident.reference como identificador de Onzane en su sistema; no utilice el email como clave permanente.
  • Trate nombres, emails y contenido de incidencias como datos personales y aplique los permisos y plazos de conservación acordados.
  • Siga los enlaces next y prev en lugar de construir manualmente las URLs de paginación.
  • Interprete de forma tolerante los objetos de respuesta: en futuras versiones se podrán añadir nuevos bloques dentro de situation sin retirar los existentes en v1.
  • No infiera que un 404 significa que el residente no existe en Onzane; también protege recursos fuera del ámbito autorizado.

Especificación OpenAPI

El contrato completo está disponible en formato OpenAPI 3.0.3. Los identificadores de operación son:

  • listBusinessResidents
  • getBusinessResidentStatus