Movimientos financieros de una propiedad¶

Este recurso gestiona movimientos financieros asociados a una propiedad concreta.

/properties/{property_reference}/finances

Todas las operaciones requieren autenticación Business.

Identificación y saldo¶

property_reference debe identificar de forma unívoca una propiedad dentro de la administración asociada al token. La API resuelve automáticamente su comunidad; no se envían community_id ni property_id en el cuerpo.

En este recurso, balance es un valor aportado y almacenado por la integración. A diferencia de los movimientos de comunidad, Onzane no recalcula el saldo de una propiedad en estas operaciones.

Objeto movimiento¶

{
  "id": 9921,
  "community_id": 45,
  "property_id": 318,
  "date": "2026-08-01T00:00:00.000000Z",
  "reference": "REC-2026-883",
  "concept": "Recibo ordinario de agosto",
  "charge": 85.25,
  "payment": 0,
  "balance": 170.5,
  "created_at": "2026-08-01T10:20:00.000000Z",
  "updated_at": "2026-08-01T10:20:00.000000Z"
}

Campo	Tipo	Descripción
`id`	entero	ID interno del movimiento, usado en las rutas de detalle, actualización y borrado.
`community_id`	entero	ID interno de la comunidad de la propiedad.
`property_id`	entero	ID interno de la propiedad.
`date`	fecha ISO 8601	Fecha contable.
`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 o `null`	Saldo aportado por la integración.
`created_at`	fecha ISO 8601	Fecha de creación.
`updated_at`	fecha ISO 8601	Última modificación.

Los IDs internos se devuelven como parte del recurso, pero las propiedades deben localizarse por property_reference.

Listar movimientos¶

GET /properties/{property_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/properties/VIV-1A/finances?date_from=2026-01-01&date_to=2026-12-31&per_page=25' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Respuesta 200 OK:

{
  "current_page": 1,
  "data": [
    {
      "id": 9921,
      "community_id": 45,
      "property_id": 318,
      "date": "2026-08-01T00:00:00.000000Z",
      "reference": "REC-2026-883",
      "concept": "Recibo ordinario de agosto",
      "charge": 85.25,
      "payment": 0,
      "balance": 170.5,
      "created_at": "2026-08-01T10:20:00.000000Z",
      "updated_at": "2026-08-01T10:20:00.000000Z"
    }
  ],
  "first_page_url": "https://api.onzane.com/bus/v1/properties/VIV-1A/finances?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://api.onzane.com/bus/v1/properties/VIV-1A/finances?page=1",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://api.onzane.com/bus/v1/properties/VIV-1A/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/properties/VIV-1A/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 /properties/{property_reference}/finances

Cuerpo:

{
  "date": "2026-08-01",
  "reference": "REC-2026-883",
  "concept": "Recibo ordinario de agosto",
  "charge": 85.25,
  "payment": 0,
  "balance": 170.5
}

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	Número o `null`. Se almacena sin recalcularlo.

Respuesta 201 Created: devuelve el movimiento completo.

curl --request POST \
  --url 'https://api.onzane.com/bus/v1/properties/VIV-1A/finances' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2026-08-01",
    "reference": "REC-2026-883",
    "concept": "Recibo ordinario de agosto",
    "charge": 85.25,
    "payment": 0,
    "balance": 170.5
  }'

Consultar un movimiento¶

GET /properties/{property_reference}/finances/{id}

Devuelve 200 OK con el objeto movimiento. Devuelve 404 Not Found si el movimiento no existe o no pertenece a la propiedad indicada.

Actualizar un movimiento¶

PUT /properties/{property_reference}/finances/{id}
PATCH /properties/{property_reference}/finances/{id}

PUT y PATCH comparten actualmente el mismo contrato: ambos requieren date y concept, por lo que PATCH no funciona como actualización parcial.

Si omite charge o payment, el valor se sustituye por 0. balance solo cambia cuando se incluye. Para evitar cambios involuntarios, envíe el estado completo:

{
  "date": "2026-08-01",
  "reference": "REC-2026-883-REV",
  "concept": "Recibo ordinario de agosto corregido",
  "charge": 80,
  "payment": 80,
  "balance": 90.5
}

Respuesta correcta: 200 OK con el movimiento actualizado.

Eliminar un movimiento¶

DELETE /properties/{property_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 referencia de la propiedad y el ID antes de enviar la petición.

Errores¶

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