--- title: "Inicio rápido" description: "Crea una clave de API, llama a GET /v1/me, lista tus anuncios y agrega un contacto con curl, JavaScript o Python. La API de Matchai llega pronto." last_updated: "2026-10-21" lang: "es" status: "coming-soon" canonical: "https://matchai.co/docs/es/developers/quickstart" --- # Inicio rápido > Crea una clave de API, llama a GET /v1/me, lista tus anuncios y agrega un contacto con curl, JavaScript o Python. La API de Matchai llega pronto. **Próximamente. Esto se documenta antes del lanzamiento para que puedas planificar tu integración; todavía no está disponible.** Source: https://matchai.co/docs/es/developers/quickstart Este inicio rápido te lleva de una clave de API nueva a tu primer contacto en cuatro llamadas. Funciona con tu propia cuenta de Matchai, así que no hay ninguna app que registrar ni nada que construir antes. La API de Matchai estará disponible próximamente. Las solicitudes de abajo muestran cómo funcionará cuando abra, para que puedas planificar tu integración. Hasta entonces, desarrolla sobre los [recursos públicos](https://matchai.co/docs/es/developers#what-is-live-today). ## Antes de empezar [#before-you-start] - Una cuenta de Matchai de un profesional inmobiliario. Todo lo que llames actúa en nombre de esa única cuenta. - Una forma de ejecutar una solicitud: `curl`, Node.js 20 o posterior, o Python 3 con el paquete `requests`. ## Haz tus primeras llamadas [#make-your-first-calls] **Crea una clave de API.** Abre **Configuración → Conectores**, despliega **Avanzado (para desarrolladores)** y ve a **Claves de API**. Crea una clave, ponle un nombre (por ejemplo, "Inicio rápido") y dale tres alcances: `profile:read`, `listings:read` y `contacts:write`. Copia la clave de inmediato. Matchai la muestra una sola vez. Empieza con `matchai_`. Guárdala en una variable de entorno, nunca en tu código: ```bash title="Terminal" export MATCHAI_API_KEY="matchai_…" ``` Cada clave pertenece a la conexión **Acceso a la API** de tu cuenta, que aparece en la página Conectores como cualquier otra conexión. Consulta [Claves de API](https://matchai.co/docs/es/developers/authentication/api-keys) para conocer los alcances, la rotación y la revocación. **Comprueba a qué cuenta llega la clave.** `GET /v1/me` devuelve la cuenta en cuyo nombre actúa tu clave. ```bash title="Terminal" curl https://api.matchai.co/v1/me \ -H "Authorization: Bearer $MATCHAI_API_KEY" ``` ```js title="me.mjs" const response = await fetch('https://api.matchai.co/v1/me', { headers: { Authorization: `Bearer ${process.env.MATCHAI_API_KEY}` }, }); if (!response.ok) { const { error } = await response.json(); const requestId = response.headers.get('Matchai-Request-Id'); throw new Error(`${error.code}: ${error.message} (request ${requestId})`); } const me = await response.json(); console.log(`Connected as ${me.display_name}. Energy: ${me.energy.balance_state}.`); ``` ```python title="me.py" import os import requests response = requests.get( "https://api.matchai.co/v1/me", headers={"Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}"}, timeout=30, ) response.raise_for_status() me = response.json() print(f"Connected as {me['display_name']}. Energy: {me['energy']['balance_state']}.") ``` Una respuesta abreviada: ```json title="Response" { "user_id": "3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d4a10", "professional_id": "8a2d4f6b-1c3e-4a5b-9d7f-0e2c4b6a8d1f", "username": "camilletremblay", "display_name": "Camille Tremblay", "job_title": "Residential real estate broker", "language": "fr-CA", "timezone": "America/Toronto", "site_id": "0f1a2b3c-4d5e-4f6a-9b7c-8d9e0f1a2b3c", "page_url": "https://camilletremblay.matchai.pro", "energy": { "balance_state": "comfortable" } } ``` `energy.balance_state` es `full`, `comfortable`, `low` o `empty`. La Energía Matchai nunca se muestra como un número. Los nombres y los ids de estos ejemplos son ficticios. **Lista tus anuncios.** `GET /v1/listings` devuelve los anuncios que puedes administrar, primero los que cambiaron más recientemente. Las listas vienen en páginas: pasa `limit` para definir el tamaño de una página, y el `next_cursor` de una página como el `cursor` de la siguiente. ```bash title="Terminal" curl -G https://api.matchai.co/v1/listings \ -H "Authorization: Bearer $MATCHAI_API_KEY" \ -d status=published \ -d limit=5 ``` ```js title="listings.mjs" const url = new URL('https://api.matchai.co/v1/listings'); url.searchParams.set('status', 'published'); url.searchParams.set('limit', '5'); const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.MATCHAI_API_KEY}` }, }); if (!response.ok) throw new Error(`Matchai answered ${response.status}`); const { data, next_cursor } = await response.json(); for (const listing of data) { console.log(`${listing.title} - ${listing.status} - ${listing.url}`); } console.log(next_cursor ? `More: cursor=${next_cursor}` : 'That is every listing.'); ``` ```python title="listings.py" import os import requests response = requests.get( "https://api.matchai.co/v1/listings", headers={"Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}"}, params={"status": "published", "limit": 5}, timeout=30, ) response.raise_for_status() page = response.json() for listing in page["data"]: print(f"{listing['title']} - {listing['status']} - {listing['url']}") print(f"More: cursor={page['next_cursor']}" if page["next_cursor"] else "That is every listing.") ``` Una respuesta abreviada, con un anuncio: ```json title="Response" { "data": [ { "id": "b7e4c2a1-9f3d-4e6b-8a5c-1d2f3e4a5b6c", "slug": "condo-rue-fabre-plateau-mont-royal", "url": "https://camilletremblay.matchai.co/listings/condo-rue-fabre-plateau-mont-royal", "status": "published", "availability": "available", "title": "Bright corner condo steps from Parc La Fontaine", "price": { "amount": 649000, "currency": "CAD" }, "updated_at": "2026-10-18T09:41:52Z" } ], "next_cursor": null } ``` Para mantener sincronizada una copia de tus anuncios, pasa `updated_since` con la hora de tu última sincronización. Consulta [paginación](https://matchai.co/docs/developers/api-reference#pagination) para ver el ciclo completo. **Agrega un contacto.** `POST /v1/contacts` agrega un prospecto, un cliente o un profesional. Envía un `Idempotency-Key` con cada `POST`: si tu solicitud excede el tiempo de espera, puedes repetirla con la misma clave y Matchai no agregará el contacto dos veces. ```bash title="Terminal" curl https://api.matchai.co/v1/contacts \ -H "Authorization: Bearer $MATCHAI_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "type": "lead", "first_name": "Julien", "last_name": "Bouchard", "email": "julien.bouchard@example.com" }' ``` ```js title="contact.mjs" import { randomUUID } from 'node:crypto'; const response = await fetch('https://api.matchai.co/v1/contacts', { method: 'POST', headers: { Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': randomUUID(), }, body: JSON.stringify({ type: 'lead', first_name: 'Julien', last_name: 'Bouchard', email: 'julien.bouchard@example.com', }), }); const body = await response.json(); if (response.status === 409 && body.error.code === 'contact_exists') { // The id of the contact that already has this email is in error.param. console.log(`Already a contact: ${body.error.param}`); } else if (!response.ok) { throw new Error(`${body.error.code}: ${body.error.message}`); } else { console.log(`Added ${body.display_name} as a ${body.type} (${body.id}).`); } ``` ```python title="contact.py" import os import uuid import requests response = requests.post( "https://api.matchai.co/v1/contacts", headers={ "Authorization": f"Bearer {os.environ['MATCHAI_API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "type": "lead", "first_name": "Julien", "last_name": "Bouchard", "email": "julien.bouchard@example.com", }, timeout=30, ) body = response.json() if response.status_code == 409 and body["error"]["code"] == "contact_exists": # The id of the contact that already has this email is in error.param. print(f"Already a contact: {body['error']['param']}") elif not response.ok: raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}") else: print(f"Added {body['display_name']} as a {body['type']} ({body['id']}).") ``` Una respuesta `201` devuelve el contacto nuevo, abreviado aquí: ```json title="Response" { "id": "c5d8e1f2-3a4b-4c6d-9e8f-7a6b5c4d3e2f", "type": "lead", "first_name": "Julien", "last_name": "Bouchard", "display_name": "Julien Bouchard", "email": "julien.bouchard@example.com", "created_at": "2026-10-16T19:12:44Z" } ``` Cuando el correo electrónico o el número de teléfono ya pertenece a uno de tus contactos, Matchai no agrega nada y responde `409` con el código `contact_exists`. Por eso el código de arriba lo comprueba. ## Cuando una llamada pregunta primero [#when-a-call-asks-first] Algunas acciones son **acciones finales**: enviar un mensaje, publicar un anuncio, eliminar algo. La conexión de tu clave empieza en **Preguntarme**, lo que significa que una acción final no se ejecuta cuando la llamas. Responde `202 Accepted` y espera a que la apruebes en Matchai: ```json title="Response (202)" { "status": "pending_approval", "approval_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b", "approval_url": "https://matchai.co/approvals/1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b", "expires_at": "2026-10-25T13:05:00Z", "summary": "Send a message to Julien Bouchard" } ``` Trata un `202` como "esperando a la persona", nunca como algo hecho. [Acciones finales](https://matchai.co/docs/es/developers/authentication#final-actions) explica cómo seguir el resultado. Alcances, acciones finales y cuándo usar Conectar con Matchai en lugar de una clave. Crea claves, define sus alcances, rótalas y revócalas. Cada código de error, y qué llamadas se pueden reintentar con seguridad. Cada endpoint previsto, empezando por GET /v1/me. ## Sitemap - [Todas las páginas de la documentación de Matchai](https://matchai.co/docs/sitemap.md) - [llms.txt](https://matchai.co/docs/es/llms.txt)