GUÍAS PARA DESARROLLADORES

// CONTENIDO

Inicio Rápido Autenticación SDKs Endpoints Límites y Planes Manejo de Errores Ejemplos por Lenguaje Agentes de IA →

// INICIO RÁPIDO

No necesitas API key para empezar. Los endpoints públicos tienen rate limiting generoso. Prueba la API directamente con curl:

$ curl https://xpequi.xyz/api/v1/properties?city=ibague&limit=3
$ curl https://xpequi.xyz/api/v1/barrios
$ curl https://xpequi.xyz/api/v1/geocode?address=Calle+10+Ibagu%C3%A9

Para endpoints que requieren autenticación, añade tu API key en el header:

$ curl -X POST https://xpequi.xyz/api/v1/contracts \
-H "Authorization: Bearer pk_live_tu_llave" \
-H "Content-Type: application/json" \
-d '{"landlordName": "Juan", ...}'

// AUTENTICACIÓN

Las llaves API se gestionan desde el portal de desarrolladores.

PASO 01

Crea una cuenta

Regístrate en xpequi.xyz. Es gratis y no requiere tarjeta de crédito.

PASO 02

Genera una llave

En el dashboard, crea una nueva llave API con un nombre descriptivo.

PASO 03

Copia la llave

La llave se muestra una sola vez. Guárdala de forma segura.

PASO 04

Úsala en tus requests

Añade el header Authorization: Bearer pk_live_tu_llave a cada request.

// SDKS

TypeScript / JavaScript

npm install @MCPVOT/api-client

import { PequiClient } from '@MCPVOT/api-client' const client = new PequiClient({ apiKey: 'pk_live_...' }) const props = await client .searchProperties({ city: 'ibague' })

Python

pip install pequi-api-client

from pequi_api_client import PequiClient client = PequiClient( api_key="pk_live_..." ) props = client.properties.search( city="ibague", limit=5 )

// ENDPOINTS

Método	Endpoint	Descripción
GET	/api/v1/properties	Buscar propiedades con filtros
GET	/api/v1/barrios	Listar barrios con estrato y coordenadas
GET	/api/v1/benchmarks	Precios de referencia por m²
GET	/api/v1/geocode	Convertir dirección en coordenadas
POST	/api/v1/contracts	Generar contrato Ley 820
POST	/api/v1/payments	Crear intento de pago Wompi
GET	/api/v1/payments/{id}	Consultar estado de pago
GET	/api/v1/complexes	Listar conjuntos residenciales
GET	/api/v1/complexes/{slug}	Detalle de conjunto
GET	/api/v1/complexes/{slug}/units	Unidades de un conjunto
POST	/api/v1/avm	Valoración automática (AVM) — estima el valor de una propiedad

📖 Prueba todos los endpoints en el playground interactivo.

// LÍMITES Y PLANES

Plan	Precio	Por minuto	Por día
GRATIS	$0/mes	30 req/min	150/día
AGENTE	$30K/mes	100 req/min	1,000/día
CONJUNTO	$150K/mes	300 req/min	5,000/día
EMPRESARIAL	Cotizar	Personalizado	50K+/día

El endpoint de chat (IA) tiene límites separados: 5 req/min en el plan GRATIS, 20 req/min en AGENTE. Esto protege los costos de IA mientras mantienes acceso completo a datos. Ver planes completos →

// MANEJO DE ERRORES

Todos los errores siguen una estructura estándar que los agentes de IA pueden parsear determinísticamente:

{ "error": "Demasiadas solicitudes.", "code": "RATE_LIMIT_EXCEEDED", "recoverable": true, "suggestedAction": "El límite se restablecerá automáticamente...", "retryAfter": 30, "requestId": "req_a1b_2c3" }

Código	HTTP	Significado	¿Reintentar?
INVALID_API_KEY	401	Llave revocada o inválida	No
EXPIRED_API_KEY	401	Llave expirada	No (renovar)
INSUFFICIENT_SCOPE	403	Sin permisos para este recurso	No
RATE_LIMIT_EXCEEDED	429	Demasiadas solicitudes	Sí (Retry-After)
QUOTA_EXCEEDED	429	Límite diario alcanzado	Sí (mejorar plan)
VALIDATION_ERROR	422	Parámetros inválidos	No
NOT_FOUND	404	Recurso no existe	No
INTERNAL_ERROR	500	Error interno del servidor	Sí (esperar)

¿Integras un agente de IA? Consulta la guía para agentes de IA →, con errores estructurados, selección de herramientas y patrones de reintento.

// EJEMPLOS POR LENGUAJE

curl

# Buscar propiedades curl https://xpequi.xyz/api/v1/properties?city=ibague&limit=5

TypeScript

import { PequiClient } from '@MCPVOT/api-client' const client = new PequiClient({ apiKey: 'pk_live_...' }) // Obtener barrios const barrios = await client.getBarrios('ibague')

Python

from pequi_api_client import PequiClient client = PequiClient( api_key="pk_live_..." ) # Obtener barrios barrios = client.barrios.list() print(f"{len(barrios)} barrios")

Node.js (fetch)

const res = await fetch( 'https://xpequi.xyz/api/v1/properties?city=ibague', { headers: { Authorization: 'Bearer pk_live_...' } } ) const data = await res.json()

// ¿LISTO PARA EMPEZAR?

Crea tu cuenta gratuita y obtén una API key en segundos.

CREAR CUENTA →PLAYGROUND →

▶ Portal ▶ API Ref ▶ Precios ▶ Docs