Casos de uso

1. Cliente atendido en persona → lead en una campaña de seguimiento

Tu punto de venta o sistema de recepción crea el lead y, en la misma solicitud, lo pone en una campaña de prospección o recontacto: el Empleado de IA de la campaña le hace seguimiento solo.

Cliente en el mostrador → Tu POS → POST /leads + campaign_id → El Empleado de IA hace seguimiento

1. Elige la campaña. GET /campaigns?type=prospecting y guarda el id de una campaña con enrollable: true.
2. Crea el lead con campaign_id. Envía external_id (el id del cliente en tu POS) para no necesitar nunca el id de SpaceKru.

   curl -X POST "https://app.spacekru.com/api/public/v1/leads" \
     -H "Authorization: Bearer $SPACEKRU_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: typeform-resp-8f2a1c" \
     -d '{
     "full_name": "Laura Gomez",
     "work_phone": "+573001112233",
     "external_id": "pos-88412",
     "campaign_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
     "tags": [
       "walk-in"
     ]
   }'

   const res = await fetch('https://app.spacekru.com/api/public/v1/leads', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.SPACEKRU_API_KEY}`,
       'Content-Type': 'application/json',
       'Idempotency-Key': 'typeform-resp-8f2a1c',
     },
     body: JSON.stringify({
       "full_name": "Laura Gomez",
       "work_phone": "+573001112233",
       "external_id": "pos-88412",
       "campaign_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
       "tags": [
         "walk-in"
       ]
     }),
   });
   const body = await res.json();
   if (!res.ok) {
     // Branch on body.error.code; quote body.error.request_id to support.
     throw new Error(`${body.error.code}: ${body.error.message} (request ${body.error.request_id})`);
   }
   console.log(body);

   import os
   
   import requests
   
   r = requests.post(
       "https://app.spacekru.com/api/public/v1/leads",
       headers={
           "Authorization": f"Bearer {os.environ['SPACEKRU_API_KEY']}",
           "Idempotency-Key": "typeform-resp-8f2a1c",
       },
       json={
           "full_name": "Laura Gomez",
           "work_phone": "+573001112233",
           "external_id": "pos-88412",
           "campaign_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
           "tags": ["walk-in"],
       },
       timeout=30,
   )
   body = r.json()
   if not r.ok:
       # Branch on body["error"]["code"]; quote body["error"]["request_id"] to support.
       raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} (request {body['error']['request_id']})")
   print(body)

3. Lee el resultado. La respuesta trae enrollment.status: enrolled, already_in_campaign o excluded con un reason (no_contact, no_channel_match, email_unverified).

2. Sincronización en ambos sentidos con tu CRM o plataforma

Un lead editado en tu plataforma actualiza SpaceKru, y un lead editado en SpaceKru (por tu equipo o un Empleado de IA) actualiza tu plataforma, sin bucles de eco.

Tu plataforma → PUT /leads/external/{id} → SpaceKru → lead.updated (triggered_by: app) → Tu plataforma

1. Escribe con PUT /leads/external/{external_id}: crea, actualiza o adopta el lead.
2. Suscríbete a lead.created y lead.updated con exclude_own_changes: true.
3. En cada webhook, actualiza tu registro por data.external_id (o guarda data.id la primera vez).

La receta completa: Sincronización en ambos sentidos.

3. Tu Empleado de IA dentro de tu app o sitio web

Tus clientes escriben en tu app; tu Empleado de IA de Customer Service responde con todo lo que puede hacer en WhatsApp: cotizar, agendar, consultar el catálogo y la base de conocimiento, o llamar a una persona.

El cliente escribe en tu app → POST /conversations/{id}/messages → El Empleado de IA responde → Tu app muestra la respuesta

Requisitos, ciclo de vida y costos: Conversaciones con IA.

4. Catálogo y stock desde tu e-commerce o ERP

Tus Empleados de IA cotizan y venden con los precios y el stock de tu catálogo real.

1. Crea cada producto una vez con POST /products y tu external_id (el id de tu SKU).
2. Cuando cambie el precio o el stock en tu sistema, envía PATCH /products/{id} (o PATCH /products/{id}/variants/{variant_id} para una variante).
3. Escucha product.updated para traer el stock que SpaceKru descuenta al crear órdenes.

5. Reservas desde tu sitio o sistema de reservas

GET /availability → El cliente elige un horario → POST /bookings → booking.created

1. GET /availability?date=2026-10-24&party_size=4 devuelve los horarios libres en la zona horaria del negocio.
2. POST /bookings con el resource_id y la hora del horario. Un horario ocupado responde 409 SLOT_UNAVAILABLE.
3. Las reservas que tus Empleados de IA hacen por WhatsApp te llegan como booking.created.

6. Sitio web o Typeform → lead en SpaceKru

Cada respuesta de un formulario se vuelve un lead de SpaceKru en segundos, sin duplicados.

Respuesta del formulario → Zapier / Make / n8n → POST /leads → Lead en SpaceKru

1. Crea una llave de API. En SpaceKru → Integraciones → API y Webhooks, crea una llave de Lectura y escritura. Llámala "Zapier — formularios".
2. Disparador. En Zapier, usa el disparador de tu herramienta de formularios, por ejemplo Typeform → New Entry.
3. Acción. Añade Webhooks by Zapier → POST. URL: https://app.spacekru.com/api/public/v1/leads. Payload Type: json. Header: Authorization = Bearer <tu llave>.
4. Mapea los campos. En Data, añade full_name, work_email, work_phone y tags (sirve un valor separado por comas como typeform, promo). Los campos vacíos se ignoran.
5. Actívalo. Pruébalo una vez y publícalo. Si la persona ya existe, SpaceKru responde 409 con existing_id en vez de crear un duplicado.

7. Lead nuevo en SpaceKru → contacto en HubSpot (o cualquier CRM)

Cada lead nuevo, de WhatsApp, Instagram, formularios, importaciones CSV o el Lead Finder, llega a tu otro CRM en segundos.

Lead nuevo en SpaceKru → lead.created → Zapier Catch Hook → Contacto en HubSpot

1. Catch Hook. En Zapier, crea un Zap con el disparador Webhooks by Zapier → Catch Hook y copia su URL.
2. Registra el webhook una vez. Ejecuta esta solicitud una vez con tu llave y la URL del Catch Hook. Guarda el secret que devuelve.

   curl -X POST "https://app.spacekru.com/api/public/v1/subscriptions" \
     -H "Authorization: Bearer $SPACEKRU_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "event_type": "lead.created",
     "target_url": "https://hooks.zapier.com/hooks/catch/1234567/abcdefg/"
   }'

   const res = await fetch('https://app.spacekru.com/api/public/v1/subscriptions', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.SPACEKRU_API_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       "event_type": "lead.created",
       "target_url": "https://hooks.zapier.com/hooks/catch/1234567/abcdefg/"
     }),
   });
   const body = await res.json();
   if (!res.ok) {
     // Branch on body.error.code; quote body.error.request_id to support.
     throw new Error(`${body.error.code}: ${body.error.message} (request ${body.error.request_id})`);
   }
   console.log(body);

   import os
   
   import requests
   
   r = requests.post(
       "https://app.spacekru.com/api/public/v1/subscriptions",
       headers={
           "Authorization": f"Bearer {os.environ['SPACEKRU_API_KEY']}",
       },
       json={
           "event_type": "lead.created",
           "target_url": "https://hooks.zapier.com/hooks/catch/1234567/abcdefg/",
       },
       timeout=30,
   )
   body = r.json()
   if not r.ok:
       # Branch on body["error"]["code"]; quote body["error"]["request_id"] to support.
       raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} (request {body['error']['request_id']})")
   print(body)

3. Mapea a HubSpot. Añade HubSpot → Create or Update Contact y mapea data.work_email, data.full_name, data.work_phone y data.company_name.

8. Deal ganado → mensaje en Slack

Deal marcado ganado → deal.stage_changed → Filtro: status es won → Mensaje en Slack

1. Suscríbete. Suscribe una URL de Catch Hook a deal.stage_changed.
2. Filtra. Continúa solo si data.status es won y existe changes.status.
3. Slack. Añade Slack → Send Channel Message: "🎉 {data.title} ganado — {data.value}".

9. Orden pagada → contabilidad o Google Sheets

Pago registrado → order.status_changed → Filtro: payment_status es paid → Fila nueva en Sheets

1. Suscribe una URL de Catch Hook a order.status_changed.
2. Continúa solo si existe changes.payment_status y su segundo valor es paid.
3. Añade la fila con data.number, data.total, data.amount_paid y data.items.

10. Sincronización nocturna a tu data warehouse o ERP

Tarea programada → GET con updated_since → Sigue next_cursor → Upsert por id

1. Guarda la hora en que empieza la tarea.
2. Llama GET /leads?updated_since=<última ejecución>&limit=100 y sigue next_cursor hasta que has_more sea false.
3. Haz upsert de cada registro por id. Repite con /deals, /quotes, /orders, /products y /bookings.
4. Guarda la hora de inicio como el próximo updated_since.

El código completo está en Paginación y sincronización. Usa una llave de Solo lectura para esta tarea.

11. Respuesta en campaña → aviso al vendedor

El lead responde a una campaña → campaign_lead.replied → Tu automatización → Correo, Slack o SMS al vendedor

1. Suscríbete a campaign_lead.replied.
2. Envía data.lead.full_name, data.lead.work_email y data.campaign_id al vendedor con tu herramienta.

12. Agencias: una integración por cliente

• Cada cuenta de cliente tiene sus propias llaves (hasta 5 activas) y sus propios webhooks. Una llave solo puede ver la cuenta a la que pertenece.
• Nombra las llaves por herramienta y cliente ("Zapier — Cliente A") para que el panel te diga qué hace cada una.
• Revocar una llave detiene esa herramienta y desactiva los webhooks que creó, sin tocar nada más.