NidoCasa GroupNidoCasaGroup

Developers · v1

API de Nidocasa Group
para conectar con otras aplicaciones.

REST API JSON sobre HTTPS. Permite consultar propiedades, enviar leads desde sistemas externos (web partner, landing, CRM) y recibir notificaciones (webhooks) cuando ocurren eventos.

Base URL

https://nidocasagroup.com/api/public/v1

Autenticación

Todas las peticiones requieren una clave API en la cabecera X-API-Key (o como Authorization: Bearer ...). Las claves se crean desde la base de datos llamando a la función api_create_key con un usuario administrador. La clave se muestra una sola vez.

-- Crear una clave nueva (devuelve el secreto una sola vez)
select * from api_create_key('Integración Partner X');

-- Revocar una clave existente
update api_keys set revoked = true where id = '...';

Errores

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key"
  }
}

Códigos: missing_api_key (401), invalid_api_key (401), insufficient_scope (403), validation_failed (422), not_found (404), query_failed / insert_failed (500).

Endpoints

GET/properties

Lista de propiedades disponibles. Scope requerido: read:properties.

Query params opcionales

  • operation — venta | alquiler
  • type — piso, atico, villa, casa…
  • city — nombre de ciudad (coincidencia case-insensitive)
  • min_price, max_price — número
  • limit (máx 100, def. 20), offset (def. 0)
curl "https://nidocasagroup.com/api/public/v1/properties?operation=venta&city=Madrid&limit=10" \
  -H "X-API-Key: nck_live_..."
GET/properties/{slug}

Detalle completo de una propiedad por su slug. Scope: read:properties.

curl "https://nidocasagroup.com/api/public/v1/properties/atico-chamberi" \
  -H "X-API-Key: nck_live_..."
POST/leads

Crea un nuevo lead/contacto. Scope: write:leads. La cabecera Content-Type debe ser application/json.

Body

{
  "type": "contacto",            // contacto | propiedad | valoracion
  "name": "María García",        // requerido
  "email": "maria@example.com",  // requerido
  "phone": "+34 600 000 000",
  "message": "Me interesa el ático...",
  "city": "Madrid",
  "property_id": "uuid opcional",
  "source": "partner-x"
}

Ejemplo

curl -X POST "https://nidocasagroup.com/api/public/v1/leads" \
  -H "X-API-Key: nck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"María García","email":"maria@example.com","message":"Hola"}'

Webhooks salientes

Nidocasa enviará una petición POST a las URLs configuradas cada vez que ocurra un evento. Eventos disponibles: lead.created, property.created.

Cabeceras enviadas

X-Nidocasa-Event: lead.created
X-Nidocasa-Signature: sha256=<hmac_sha256(body, secret)>
Content-Type: application/json

Payload

{
  "event": "lead.created",
  "created_at": "2026-05-16T10:00:00Z",
  "data": {
    "id": "uuid",
    "type": "contacto",
    "name": "...",
    "email": "...",
    "phone": "...",
    "message": "...",
    "city": "...",
    "property_id": null,
    "source": "api"
  }
}

Verificación de firma (Node.js)

import { createHmac, timingSafeEqual } from "crypto";

const signature = req.headers["x-nidocasa-signature"].replace("sha256=", "");
const expected = createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

const valid = timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(expected)
);

Registrar un endpoint (admin)

insert into webhook_endpoints (name, url, events)
values ('CRM Partner', 'https://partner.example.com/hooks/nidocasa',
        array['lead.created','property.created'])
returning id, secret;

Notas

  • CORS habilitado para todos los orígenes (*).
  • Los leads enviados quedan registrados con source y la IP de origen.
  • Para limites/quotas o más eventos, contáctanos.