Ir al contenido
WhatsMarketingDeveloper Hub

Primeros pasos

En diez minutos tendrás una clave, una petición que funciona y un webhook recibido.

1. Crea una clave de API

  1. Entra en micuenta con un usuario administrador.
  2. Ve a Integraciones → Webhooks y API y pulsa Nueva clave. El panel te pedirá confirmar que eres tú (contraseña o código) antes de seguir.
  3. Ponle un nombre que diga para qué es («CRM HubSpot», «Web Shopify»), elige los permisos que necesita y, si quieres, una caducidad.
  4. Copia la clave. Empieza por wm_live_ y se muestra una sola vez: en la base solo guardamos su huella.

Si pierdes la clave, revócala y crea otra. Revocar corta el acceso al instante y queda en el registro de actividad.

2. Tu primera petición

La API vive en https://micuenta.whatsmarketing.es/api/v1 y la clave va en la cabecera Authorization:

curl
curl https://micuenta.whatsmarketing.es/api/v1/contacts?pageSize=5 \
  -H "Authorization: Bearer wm_live_TU_CLAVE"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts?pageSize=5', {
  headers: { Authorization: `Bearer ${process.env.WM_API_KEY}` },
});
const { data, meta } = await res.json();
console.log(meta.total, 'contactos');
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/contacts",
    params={"pageSize": 5},
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["meta"]["total"], "contactos")
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts?pageSize=5');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WM_API_KEY')],
]);
$res = json_decode(curl_exec($ch), true);
echo $res['meta']['total'], " contactos\n";

La respuesta trae data (los contactos), meta (página, tamaño, total), tabs y summary. Si ves 401 API_KEY_INVALID, revisa la clave; si ves 403 API_KEY_SCOPE_MISSING, la clave no tiene el permiso contacts:read.

3. Crea un contacto desde tu web

curl
curl -X POST https://micuenta.whatsmarketing.es/api/v1/contacts \
  -H "Authorization: Bearer wm_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Laura Pérez",
    "primaryPhone": "+34612345678",
    "primaryEmail": "laura@ejemplo.com",
    "source": "WEBSITE_FORM",
    "tags": ["web"],
    "consent": { "given": true, "how": "WEBSITE_FORM" }
  }'

El teléfono va siempre con prefijo internacional. Si ya existía un contacto con ese teléfono, recibes 409 CONTACT_PHONE_EXISTS con su contactId: usa PATCH /contacts/{id} para completarlo.

4. Recibe tu primer webhook

  1. En Integraciones → Webhooks y API → Nuevo webhook, pon la URL https de tu servidor y marca contact.created.
  2. Guarda el secreto whsec_… (también se muestra una vez).
  3. Crea un contacto como en el paso 3: en segundos llega un POST a tu URL con el evento.
  4. Verifica la firma antes de hacer nada con el cuerpo: está explicado en Webhooks.

Para probar en local sin abrir puertos, usa un túnel (ngrok, Cloudflare Tunnel) y pon esa URL en el webhook.

5. Siguientes pasos