URBANETAURBANETA
URBANETAURBANETA

Idioma

Tema

Developer Docs

Documentación de la API REST

Crea integraciones con Urbaneta. Automatiza la facturación, sincroniza residentes, lee datos de contadores y más.

Claves API

Genera claves API en la configuración de tu cuenta. Cada clave está vinculada a tu organización.

Autenticación Bearer

Todos los endpoints requieren un token Bearer válido. Los tokens expiran en 15 minutos — usa tokens de actualización para mantenerte autenticado.

Webhooks

Suscríbete a eventos (invoice.created, payment.received, reading.submitted) con cargas firmadas con HMAC.

URL base
https://testlnp.workizon.com/api

Todas las solicitudes deben realizarse por HTTPS. Reemplaza con la URL de tu instancia si aplica.

Autenticación

Incluye tu token de acceso en la cabecera Authorization en cada solicitud.

# Los tokens son de corta duración. Usa POST /auth/refresh con tu token de actualización para obtener automáticamente un nuevo token de acceso. Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Inicio rápido

Tres pasos para tu primera integración con la API.

1. Autenticarse y obtener el token

curl -X POST https://testlnp.workizon.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

# Response
{ "data": { "accessToken": "eyJ...", "refreshToken": "dGhp..." } }

2. Listar tus edificios

curl https://testlnp.workizon.com/api/buildings \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Generar facturas para un edificio

curl -X POST https://testlnp.workizon.com/api/invoices/generate-bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildingId":"<uuid>","periodStart":"2025-01-01","periodEnd":"2025-01-31"}'

Ejemplo en JavaScript / TypeScript

No se necesita SDK — la API usa REST estándar. Patrón para obtener facturas y registrar un pago.

# Fetch unpaid invoices
curl "https://testlnp.workizon.com/api/invoices?buildingId=<uuid>&status=sent" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Mark invoice as paid
curl -X PATCH "https://testlnp.workizon.com/api/invoices/<invoice-id>" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","paidDate":"2025-02-01"}'

Referencia de endpoints

Autenticación

POST/auth/loginIniciar sesión con email y contraseña, devuelve tokens de acceso y actualización
POST/auth/refreshRenovar un token de acceso caducado usando un token de actualización
POST/auth/logoutCerrar la sesión actual
POST/auth/magic-linkSolicitar un email con enlace mágico de inicio de sesión

Edificios

GET/buildingsListar todos los edificios del inquilino autenticado
POST/buildingsCrear un nuevo edificio
GET/buildings/:idObtener un edificio por ID
PATCH/buildings/:idActualizar configuración del edificio (nombre, dirección, facturación, etc.)
DELETE/buildings/:idEliminar un edificio (requiere confirmación de contraseña)

Apartamentos

GET/buildings/:id/apartmentsListar apartamentos en un edificio
POST/buildings/:id/apartmentsCrear un apartamento
PATCH/buildings/:id/apartments/:aptIdActualizar detalles del apartamento
DELETE/buildings/:id/apartments/:aptIdEliminar un apartamento

Facturas

GET/invoicesListar facturas con filtros (estado, edificio, rango de fechas)
GET/invoices/:idObtener detalles de factura incluyendo líneas de detalle
POST/invoices/generate-bulkGenerar facturas para un edificio y período
PATCH/invoices/:idActualizar estado, fecha de pago o referencia de la factura
POST/invoices/send-bulkEnviar facturas por email a los residentes
GET/invoices/:id/pdfDescargar factura en formato PDF

Contadores

GET/metersListar definiciones de contadores en un edificio
POST/metersCrear un nuevo contador
POST/meters/:id/readingsEnviar una lectura de contador
POST/meters/ocrExtraer lectura de una foto del contador usando OCR con IA

Residentes y usuarios

GET/residentsListar residentes vinculados a tus edificios
POST/invitationsInvitar a un usuario a un apartamento
GET/invitationsListar invitaciones pendientes
DELETE/invitations/:idCancelar una invitación

Pagos

POST/payments/banklinkIniciar un pago Paysera / Maksekeskus banklink
GET/paymentsListar pagos registrados del inquilino
POST/bank-statements/importImportar extracto bancario CSV/XML para reconciliación automática

Webhooks

GET/webhooksListar endpoints webhook configurados
POST/webhooksCrear un endpoint webhook (URL + tipos de eventos)
DELETE/webhooks/:idEliminar un endpoint webhook

Tipos de eventos webhook

Suscríbete a cualquier combinación de eventos al crear un endpoint webhook.

invoice.createdSe generó una nueva factura
invoice.sentLa factura fue enviada al residente por email
invoice.paidFactura marcada como pagada (manual o banklink)
invoice.overdueLa factura no fue pagada antes de la fecha de vencimiento
payment.receivedSe registró un pago contra una factura
reading.submittedUn residente envió una lectura de contador
reading.confirmedEl administrador confirmó una lectura de contador
maintenance.createdSe envió una nueva solicitud de mantenimiento
maintenance.updatedEl estado de la solicitud de mantenimiento cambió

Ejemplo de payload

POST https://your-server.com/webhook X-Urbaneta-Signature: sha256=... { "event": "invoice.paid", "timestamp": "2025-02-01T10:30:00Z", "tenantId": "550e8400-e29b-41d4-a716-...", "data": { "invoiceId": "...", "amount": 142.50 } }

Códigos de error HTTP

400Solicitud incorrectaCuerpo de solicitud inválido o campos requeridos faltantes
401No autorizadoToken de acceso ausente o caducado
403ProhibidoAutenticado pero con permisos insuficientes
404No encontradoRecurso no encontrado o no accesible para tu inquilino
409ConflictoRecurso duplicado (ej. el número de apartamento ya existe)
422Error de validaciónValidación fallida — revisa el array errors en la respuesta
429Límite de solicitudesDemasiadas solicitudes — reintenta después del valor del header Retry-After
500Error del servidorError inesperado — contacta con soporte si persiste

¿Listo para integrar?

Inicia sesión en tu cuenta de Urbaneta para generar claves API y configurar endpoints de webhooks.

Ir al panel de control