AutenticaciónPróximamente

Cada solicitud a la API de Matchai actúa en nombre de una cuenta de Matchai. Hay dos formas de obtener la credencial que lo demuestra, y la adecuada depende de quién es la cuenta con la que trabajas.

Dos formas de entrarCopiar el enlace de esta sección

Ambas van en el mismo encabezado:

Authorization: Bearer matchai_…

Un token de acceso OAuth se envía de la misma forma, en lugar de la clave.

Lo que puede hacer una solicitudCopiar el enlace de esta sección

Una solicitud puede hacer lo mismo que el titular de la cuenta puede hacer en Matchai, con las mismas reglas y los mismos permisos, y nada más. Dos cosas la limitan todavía más:

• Los alcances limitan qué partes de la cuenta puede tocar la credencial.
• Las acciones finales esperan la aprobación del titular de la cuenta, a menos que haya permitido que tu app las ejecute.

GET /v1/me/connection (getConnection) le dice a tu app cómo está conectada: la app, los alcances concedidos, auth_type (api_key u oauth), approval_mode (ask_me o allowed) y si la conexión está en modo de prueba.

AlcancesCopiar el enlace de esta sección

Cada operación de la referencia de la API enumera los alcances que necesita. Pide solo lo que tu app usa: es más probable que un profesional presione Permitir cuando la lista es corta y cada línea tiene sentido.

Cuando a una credencial le falta un alcance, la llamada falla con 403 y el código scope_missing, y el mensaje nombra el alcance. Si es una clave, crea una clave nueva que tenga el alcance y revoca la anterior. Si es una conexión OAuth, haz que el profesional vuelva a pasar por el flujo de conexión de tu app, para que pueda aceptar la lista más larga.

Algunas operaciones no necesitan ningún alcance porque solo trabajan con lo que ya es público, como consultar el perfil publicado de un profesional. Están marcadas como Free (gratis) en la referencia, y para ellas la clave o el token son opcionales.

Acciones finalesCopiar el enlace de esta sección

Cuatro tipos de acciones son finales: enviarle algo a otra persona, publicar algo para el público, pagar y eliminar contenido de la cuenta. El Asistente de Matchai siempre pregunta antes de hacer cualquiera de ellas, y la API somete a tu app a la misma regla. Cada acción final está marcada como Final action (acción final) en la referencia.

El titular de la cuenta elige cómo maneja tu app estas acciones, por conexión:

Todo lo que no es una acción final se ejecuta según los alcances de la credencial, igual que la misma edición en la app: lecturas, borradores y cambios en los propios registros del titular de la cuenta. Eliminar la configuración de tu propia app, como una suscripción de webhook, tampoco es una acción final.

Escribe tu app para ambos ajustes. El titular de la cuenta puede cambiar el ajuste en cualquier momento, así que nunca des por hecho cuál vas a recibir.

Sigue una aprobaciónCopiar el enlace de esta sección

Una acción final en modo Preguntarme responde 202 y todavía no hace nada:

{
  "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"
}

Una aprobación tiene uno de cinco estados:

GET /v1/approvals (listApprovals) enumera las solicitudes que hizo tu conexión, y acepta un filtro status.

Envía un Idempotency-Key con cada acción final. Si tu solicitud excede el tiempo de espera y la repites con la misma clave, recibes la misma aprobación pendiente en lugar de una segunda.

Este ejemplo publica un anuncio y maneja ambos ajustes:

import { randomUUID } from 'node:crypto';

const response = await fetch(`https://api.matchai.co/v1/listings/${listingId}/publish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
});

if (response.status === 202) {
  // Ask me: nothing has happened yet.
  const pending = await response.json();
  console.log(`Waiting: ${pending.summary}`);
  console.log(`The account holder can answer at ${pending.approval_url}`);
} else if (response.ok) {
  // Allowed: the listing is published now.
  const listing = await response.json();
  console.log(`Published at ${listing.url}`);
} else {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

Límites de energíaCopiar el enlace de esta sección

Algunas acciones gastan Energía Matchai, igual que las funciones de IA en la app: escribir un anuncio con IA, editar fotos, traducir, redactar con IA, enviar un correo electrónico y los mensajes que salen por SMS. La referencia marca cada una de ellas e indica qué tan pesada es la acción: ligera, moderada, pesada o variable.

• La API nunca muestra la energía como un número. GET /v1/me devuelve su estado: full, comfortable, low o empty.
• Una llamada que necesita más de lo que queda no hace nada. Responde 402 con el código insufficient_energy, y no se gasta nada.
• El titular de la cuenta puede fijar un límite de energía para cada conexión, para que un script descontrolado se detenga en un tope que eligió. Cuando tu conexión lo alcanza, las llamadas que gastan energía responden 402 con el código energy_limit_reached, y GET /v1/me/connection informa energy_limit_reached: true.

Muéstrale a la persona el message de un 402: dice qué pasó y qué hacer a continuación. Consulta errores.

Terminar una conexiónCopiar el enlace de esta sección

Una conexión termina de una de tres formas, y cada una detiene todas las credenciales que le pertenecen:

• El profesional presiona Desconectar en la página Conectores.
• Revocas una clave de API.
• Tu app llama a DELETE /v1/me/connection (disconnect). Termina la conexión como si el profesional hubiera presionado Desconectar, y no elimina nada de la cuenta.

Después de que una conexión termina, sus suscripciones de webhook se desactivan y sus solicitudes responden 401. Interprétalo como "hay que volver a conectarse", no como una interrupción del servicio.

Modo de pruebaCopiar el enlace de esta sección

Una app que está conectada solo a la cuenta de su propio desarrollador está en modo de prueba. Las conexiones de prueba no se facturan, y los eventos que producen llevan test_mode: true. Crea una app de Matchai explica cómo funciona y quién paga cuando se conectan otros profesionales.