Saltar a contenido

API Business de Onzane

La API Business permite integrar aplicaciones de terceros con Onzane mediante peticiones HTTPS y respuestas JSON. Actualmente ofrece operaciones financieras sobre comunidades y propiedades, además de consultas sobre la situación de residentes.

URL base

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

Todas las rutas de esta referencia son relativas a esa URL.

Autenticación

El API Business utiliza tokens Bearer de Laravel Sanctum. El token Business se define para cada usuario desde el panel de administración de Onzane, lo que permite controlar qué credenciales usa cada integración y revocarlas cuando sea necesario.

Incluya el token Business en todas las peticiones:

Authorization: Bearer <token>
Accept: application/json

Cuando envíe un cuerpo JSON, añada también:

Content-Type: application/json

Ejemplo:

curl --request GET \
  --url 'https://api.onzane.com/bus/v1/communities/COM-001/finances' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Un token ausente, inválido o revocado produce una respuesta 401 Unauthorized:

{
  "message": "Unauthenticated."
}

Ámbito de acceso

El token queda asociado al usuario que lo tiene configurado y a su administración de Onzane. Las referencias de comunidades, propiedades, residentes y movimientos se resuelven dentro de ese ámbito.

No debe utilizar una respuesta 404 Not Found para deducir si un recurso existe en otra administración: el mismo código se utiliza para recursos inexistentes y recursos fuera del ámbito autorizado.

Formato y convenciones

  • Las peticiones y respuestas utilizan JSON codificado en UTF-8.
  • Los importes se envían como números JSON y admiten hasta cuatro decimales en almacenamiento.
  • Las fechas de entrada de movimientos usan el formato YYYY-MM-DD.
  • Las fechas serializadas por la API pueden aparecer como instantes ISO 8601, por ejemplo 2026-08-01T00:00:00.000000Z.
  • Los valores null se representan explícitamente cuando el campo no tiene valor.
  • Los endpoints de listado están paginados.
  • Las nuevas propiedades que se añadan a una respuesta de v1 deben ignorarse de forma tolerante.

Errores habituales

Código Significado
200 OK Lectura o actualización completada. Algunas rutas originales también responden así al crear.
201 Created Recurso creado mediante los endpoints REST.
204 No Content Recurso eliminado; la respuesta no contiene JSON.
401 Unauthorized Token ausente, inválido o revocado.
404 Not Found Recurso inexistente, fuera del ámbito del token o fuera del contexto solicitado.
422 Unprocessable Entity Algún parámetro o campo no supera la validación.

En los endpoints REST, un error de validación tiene esta forma:

{
  "message": "The date field is required.",
  "errors": {
    "date": [
      "The date field is required."
    ]
  }
}

Catálogo de recursos

Finanzas

Residentes

Endpoints disponibles

Método Ruta Referencia
GET /communities/{community_reference}/finances Finanzas de comunidad
POST /communities/{community_reference}/finances Finanzas de comunidad
GET /communities/{community_reference}/finances/{id} Finanzas de comunidad
PUT / PATCH /communities/{community_reference}/finances/{id} Finanzas de comunidad
DELETE /communities/{community_reference}/finances/{id} Finanzas de comunidad
GET /properties/{property_reference}/finances Finanzas de propiedad
POST /properties/{property_reference}/finances Finanzas de propiedad
GET /properties/{property_reference}/finances/{id} Finanzas de propiedad
PUT / PATCH /properties/{property_reference}/finances/{id} Finanzas de propiedad
DELETE /properties/{property_reference}/finances/{id} Finanzas de propiedad
GET / POST /finances/{com_ref} Rutas originales
GET / POST /finances/{com_ref}/{prop_ref} Rutas originales
GET /communities/{community_reference}/properties/{property_reference}/residents Situación de residentes
GET /communities/{community_reference}/properties/{property_reference}/residents/{resident_reference}/status Situación de residentes

Rutas recomendadas para integraciones nuevas

Para nuevas integraciones financieras utilice las rutas REST bajo /communities/.../finances y /properties/.../finances. Las rutas /finances/{com_ref} y /finances/{com_ref}/{prop_ref} permanecen disponibles por compatibilidad, pero ofrecen menos operaciones y un contrato de respuesta diferente.

Especificación OpenAPI

La versión técnica del contrato se mantiene en formato OpenAPI 3.0.3. Antes de integrar una operación, se recomienda usar conjuntamente la especificación y estas guías, que explican los comportamientos funcionales y las diferencias de compatibilidad.