Movimientos financieros de una comunidad¶

Este recurso gestiona movimientos financieros generales de una comunidad. Los movimientos creados aquí no están vinculados a una propiedad concreta.

/communities/{community_reference}/finances

Todas las operaciones requieren autenticación Business.

Identificación y saldo¶

community_reference es la referencia externa de la comunidad en Onzane. La comunidad debe pertenecer a la administración asociada al token.

En este recurso, balance es un saldo acumulado calculado por Onzane como charge - payment. No se almacena el valor enviado por el consumidor. El cálculo sigue el orden estable utilizado por el listado: referencia ascendente, fecha ascendente e ID ascendente; los movimientos sin referencia aparecen al final.

Objeto movimiento¶

{
  "id": 7812,
  "community_id": 45,
  "property_id": null,
  "date": "2026-08-01T00:00:00.000000Z",
  "reference": "RC-2026-001",
  "concept": "Cuota general de agosto",
  "charge": 125.5,
  "payment": 0,
  "balance": 325.5,
  "created_at": "2026-08-01T09:10:00.000000Z",
  "updated_at": "2026-08-01T09:10:00.000000Z"
}

Campo	Tipo	Descripción
`id`	entero	ID interno del movimiento, necesario para detalle, actualización y borrado.
`community_id`	entero	ID interno de la comunidad. No debe usarse para resolver la comunidad en otras rutas.
`property_id`	`null`	Siempre `null` en este recurso.
`date`	fecha ISO 8601	Fecha contable del movimiento.
`reference`	cadena o `null`	Referencia aportada por la integración.
`concept`	cadena	Concepto del movimiento.
`charge`	número	Cargo.
`payment`	número	Pago o abono.
`balance`	número	Saldo acumulado calculado por Onzane.
`created_at`	fecha ISO 8601	Fecha de creación.
`updated_at`	fecha ISO 8601	Última modificación.

Listar movimientos¶

GET /communities/{community_reference}/finances

Parámetros de consulta:

Parámetro	Tipo	Descripción
`date_from`	`YYYY-MM-DD`	Incluye movimientos desde esta fecha.
`date_to`	`YYYY-MM-DD`	Incluye movimientos hasta esta fecha.
`search`	cadena	Busca parcialmente en `reference` y `concept`.
`min_charge`	número	Cargo mínimo.
`max_charge`	número	Cargo máximo.
`min_payment`	número	Pago mínimo.
`max_payment`	número	Pago máximo.
`page`	entero	Página solicitada. Predeterminado: `1`.
`per_page`	entero	Elementos por página. Predeterminado recomendado: `25`; no envíe más de `100`.

Ejemplo:

curl --request GET \
  --url 'https://api.onzane.com/bus/v1/communities/COM-001/finances?date_from=2026-01-01&date_to=2026-12-31&search=cuota&per_page=25' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Respuesta 200 OK:

{
  "current_page": 1,
  "data": [
    {
      "id": 7812,
      "community_id": 45,
      "property_id": null,
      "date": "2026-08-01T00:00:00.000000Z",
      "reference": "RC-2026-001",
      "concept": "Cuota general de agosto",
      "charge": 125.5,
      "payment": 0,
      "balance": 325.5,
      "created_at": "2026-08-01T09:10:00.000000Z",
      "updated_at": "2026-08-01T09:10:00.000000Z"
    }
  ],
  "first_page_url": "https://api.onzane.com/bus/v1/communities/COM-001/finances?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://api.onzane.com/bus/v1/communities/COM-001/finances?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://api.onzane.com/bus/v1/communities/COM-001/finances?page=1",
      "label": "1",
      "active": true
    },
    {
      "url": null,
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://api.onzane.com/bus/v1/communities/COM-001/finances",
  "per_page": 25,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

El listado se ordena por reference ascendente, después por date ascendente y finalmente por id ascendente. Las referencias null aparecen al final.

Los enlaces de paginación generados contienen el parámetro page. Si utiliza filtros, conserve también esos parámetros al solicitar la página siguiente.

Crear un movimiento¶

POST /communities/{community_reference}/finances

Cuerpo:

{
  "date": "2026-08-01",
  "reference": "RC-2026-001",
  "concept": "Cuota general de agosto",
  "charge": 125.5,
  "payment": 0
}

Campo	Obligatorio	Validación y comportamiento
`date`	Sí	Fecha válida. Se recomienda `YYYY-MM-DD`.
`reference`	No	Cadena o `null`; utilice como máximo 40 caracteres.
`concept`	Sí	Cadena; utilice como máximo 250 caracteres.
`charge`	No	Número. Si se omite, se guarda `0`.
`payment`	No	Número. Si se omite, se guarda `0`.
`balance`	No	Se acepta por compatibilidad, pero se ignora; Onzane lo calcula.

community_id y property_id no se aceptan del cuerpo. El ámbito se obtiene de la URL y del token.

Respuesta 201 Created: devuelve el movimiento completo con el saldo calculado.

curl --request POST \
  --url 'https://api.onzane.com/bus/v1/communities/COM-001/finances' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2026-08-01",
    "reference": "RC-2026-001",
    "concept": "Cuota general de agosto",
    "charge": 125.5,
    "payment": 0
  }'

Consultar un movimiento¶

GET /communities/{community_reference}/finances/{id}

Devuelve 200 OK con el objeto movimiento. Devuelve 404 Not Found si el movimiento no existe, pertenece a otra comunidad o no es un movimiento general de comunidad.

Actualizar un movimiento¶

PUT /communities/{community_reference}/finances/{id}
PATCH /communities/{community_reference}/finances/{id}

Actualmente PUT y PATCH comparten el mismo contrato: ambos requieren date y concept. No utilice PATCH como una actualización parcial.

Además, si omite charge o payment, ese valor se sustituye por 0. Envíe siempre el estado completo que desea conservar:

{
  "date": "2026-08-01",
  "reference": "RC-2026-001-REV",
  "concept": "Cuota general de agosto corregida",
  "charge": 120,
  "payment": 0
}

El campo balance se ignora y se vuelve a calcular. La respuesta es 200 OK con el movimiento actualizado.

Eliminar un movimiento¶

DELETE /communities/{community_reference}/finances/{id}

Respuesta correcta: 204 No Content sin cuerpo.

La eliminación es física y no puede deshacerse mediante la API. Compruebe la comunidad y el ID antes de enviar la petición.

Errores¶

Código	Situación
`401`	Token ausente, inválido o revocado.
`404`	Comunidad o movimiento no encontrado dentro del ámbito autorizado.
`422`	Cuerpo de creación o actualización no válido.