{ "info": { "name": "WhatsMarketing API", "description": "API pública de WhatsMarketing: contactos, campañas, conversaciones, automatizaciones e informes, con claves de API y webhooks firmados.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://micuenta.whatsmarketing.es/api/v1" }, { "key": "apiKey", "value": "wm_live_..." } ], "item": [ { "name": "Contactos", "item": [ { "name": "Listar contactos", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/contacts", "host": [ "{{baseUrl}}" ], "path": [ "contacts" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true }, { "key": "tab", "value": "", "disabled": true }, { "key": "lifecycleStageId", "value": "", "disabled": true }, { "key": "ownerId", "value": "", "disabled": true }, { "key": "source", "value": "", "disabled": true }, { "key": "channelType", "value": "", "disabled": true }, { "key": "tag", "value": "", "disabled": true }, { "key": "q", "value": "", "disabled": true }, { "key": "search", "value": "", "disabled": true }, { "key": "days", "value": "", "disabled": true }, { "key": "ids", "value": "", "disabled": true } ], "variable": [] }, "description": "Contactos de la organización, paginados y con filtros: pestaña (`tab`), etapa, propietario (`ownerId`, o `none` para los que no tienen), origen, canal, etiqueta, búsqueda libre (`q`) o actividad reciente (`days`). Además de `data` y `meta` trae `tabs` (cuántos hay en cada pestaña) y `summary` (las cifras de cabecera del panel)." } }, { "name": "Crear un contacto", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/contacts", "host": [ "{{baseUrl}}" ], "path": [ "contacts" ], "query": [], "variable": [] }, "description": "Crea la ficha. El teléfono va en formato internacional con prefijo (`+34…`). Si ya existe un contacto con ese teléfono, responde `409 CONTACT_PHONE_EXISTS` con el `contactId` del existente. `consent` registra cuándo y cómo dio consentimiento para recibir mensajes; `note` deja una primera nota interna.", "body": { "mode": "raw", "raw": "{\n \"fullName\": \"Laura Pérez\",\n \"primaryPhone\": \"+34612345678\",\n \"primaryEmail\": \"laura@ejemplo.com\",\n \"company\": \"Clínica Sol\",\n \"country\": \"ES\",\n \"source\": \"WEBSITE_FORM\",\n \"tags\": [\n \"web\"\n ],\n \"consent\": {\n \"given\": true,\n \"at\": \"2026-10-14T10:20:00.000Z\",\n \"how\": \"WEBSITE_FORM\"\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Actualizar contactos en lote", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/contacts/bulk", "host": [ "{{baseUrl}}" ], "path": [ "contacts", "bulk" ], "query": [], "variable": [] }, "description": "Hasta 500 contactos por llamada: cambiar de etapa, añadir etiquetas (hasta 20) o reasignar el propietario (`ownerId: null` lo quita). Al menos una de las tres. `skipped` son los ids que no pertenecen a tu organización.", "body": { "mode": "raw", "raw": "{\n \"ids\": [\n \"0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e\",\n \"4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b\"\n ],\n \"addTags\": [\n \"evento-madrid\"\n ],\n \"lifecycleStageId\": \"9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Ver un contacto", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/contacts/{id}", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "La ficha completa: identidades por canal, consentimiento, etiquetas, propietario, etapa y oportunidades abiertas." } }, { "name": "Editar un contacto", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/contacts/{id}", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Todos los campos son opcionales; solo cambia lo que mandas. Cambiar el teléfono a uno que ya tiene otro contacto responde `409 CONTACT_PHONE_EXISTS`. Responde con la ficha actualizada.", "body": { "mode": "raw", "raw": "{\n \"company\": \"Clínica Sol Fuengirola\",\n \"tags\": [\n \"web\",\n \"cliente\"\n ],\n \"lifecycleStageId\": \"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Eliminar un contacto", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/contacts/{id}", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Solo si el contacto no tiene conversaciones, campañas ni ventas; si las tiene, responde `409 CONTACT_HAS_HISTORY` y conviene retirarle el consentimiento (`optedOut: true`) en lugar de borrarlo. Las notas e identidades se eliminan con él." } }, { "name": "Línea de tiempo de un contacto", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/contacts/{id}/timeline", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id", "timeline" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true }, { "key": "type", "value": "", "disabled": true } ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Conversaciones, campañas recibidas, notas, cambios de etapa, consentimiento y alta, en orden cronológico inverso. `type` filtra por `conversations`, `campaigns` o `notes`; cada entrada lleva su `type`." } }, { "name": "Añadir una identidad de canal", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/contacts/{id}/identities", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id", "identities" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Vincula otro canal a la misma ficha: `channelType` es el tipo de canal (`WHATSAPP`, `INSTAGRAM`, `MESSENGER`, `EMAIL`…) y `externalId` el identificador del contacto en ese canal (teléfono sin `+` para WhatsApp, usuario para Instagram, correo para email). Si esa identidad ya pertenece a otro contacto, responde 409.", "body": { "mode": "raw", "raw": "{\n \"channelType\": \"INSTAGRAM\",\n \"externalId\": \"laura.perez\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Listar notas de un contacto", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/contacts/{id}/notes", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id", "notes" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true } ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Notas internas del equipo, de la más reciente a la más antigua, con autor y fecha." } }, { "name": "Añadir una nota", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/contacts/{id}/notes", "host": [ "{{baseUrl}}" ], "path": [ "contacts", ":id", "notes" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "La nota queda a nombre del usuario que creó la clave de API.", "body": { "mode": "raw", "raw": "{\n \"body\": \"Llamada hecha: le interesa el plan Pyme.\"\n}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Conversaciones", "item": [ { "name": "Listar conversaciones", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/conversations", "host": [ "{{baseUrl}}" ], "path": [ "conversations" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true }, { "key": "filter", "value": "", "disabled": true }, { "key": "status", "value": "", "disabled": true }, { "key": "channelId", "value": "", "disabled": true }, { "key": "channelType", "value": "", "disabled": true }, { "key": "contactId", "value": "", "disabled": true }, { "key": "assignedToUserId", "value": "", "disabled": true }, { "key": "q", "value": "", "disabled": true } ], "variable": [] }, "description": "Referencias a las conversaciones de la bandeja con filtros por pestaña (`filter`: `all`, `unassigned`, `mine`, `resolved`), estado, canal, contacto, persona asignada y búsqueda. Trae `tabs` y `summary` con las cifras de la bandeja." } }, { "name": "Ver una conversación", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/conversations/{id}", "host": [ "{{baseUrl}}" ], "path": [ "conversations", ":id" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "La referencia de la conversación: contacto, canal, estado, quién la abrió y quién la atiende. Los mensajes no se devuelven: viven en la bandeja." } } ] }, { "name": "Campañas", "item": [ { "name": "Listar campañas", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/campaigns", "host": [ "{{baseUrl}}" ], "path": [ "campaigns" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true }, { "key": "tab", "value": "", "disabled": true }, { "key": "category", "value": "", "disabled": true }, { "key": "phoneNumberId", "value": "", "disabled": true }, { "key": "q", "value": "", "disabled": true }, { "key": "days", "value": "", "disabled": true } ], "variable": [] }, "description": "Campañas con su estado, número emisor, plantilla y cifras (`stats`: enviados, entregados, leídos, respondidos, fallidos). Pestañas (`tab`): `all`, `sending`, `scheduled`, `drafts`, `errors`, `finished`. `summary` resume el periodo (`days`)." } }, { "name": "Crear una campaña (borrador)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/campaigns", "host": [ "{{baseUrl}}" ], "path": [ "campaigns" ], "query": [], "variable": [] }, "description": "Nombre, número emisor y plantilla aprobada. Si la plantilla tiene variables, `variables` dice de dónde sale cada una (campo del contacto como `{{fullName}}` o texto fijo); sin ellas, el envío responde `400 CAMPAIGN_VARIABLES_REQUIRED`. La campaña nace en borrador: después añade la audiencia, consulta el coste y envía.", "body": { "mode": "raw", "raw": "{\n \"name\": \"Octubre: promo\",\n \"phoneNumberId\": \"c4d5e6f7-a8b9-4c0d-8e1f-2a3b4c5d6e7f\",\n \"templateId\": \"e6f7a8b9-c0d1-4e2f-8a3b-4c5d6e7f8a9b\",\n \"variables\": {\n \"1\": \"{{fullName}}\",\n \"2\": \"15 %\"\n }\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Ver una campaña", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/campaigns/{id}", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Detalle con cifras, plantilla, número, programación, coste estimado y real, errores agrupados por motivo y últimas respuestas." } }, { "name": "Destinatarios de una campaña", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/campaigns/{id}/recipients", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id", "recipients" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true }, { "key": "filter", "value": "", "disabled": true } ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Cada destinatario con su estado (`PENDING`, `SENT`, `DELIVERED`, `READ`, `REPLIED`, `FAILED`), el mercado por el que se tarifó, el coste y el motivo del fallo si lo hubo. `filter` acota por estado." } }, { "name": "Añadir audiencia", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/campaigns/{id}/recipients", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id", "recipients" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Una de cuatro fuentes: lista de ids (`contactIds`, hasta 20.000), una etapa (`lifecycleStageId`), una etiqueta (`tag`) o `all: true` para todos. Solo entran los contactos con consentimiento y teléfono; la respuesta dice cuántos quedaron fuera y por qué, cuántos entraron (`added`) y cuántos ya estaban (`alreadyIn`).", "body": { "mode": "raw", "raw": "{\n \"tag\": \"campaña-octubre\"\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Coste previsto", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/campaigns/{id}/preview-cost", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id", "preview-cost" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Antes de enviar: cuántos destinatarios se cobran, el precio final por mensaje en cada mercado destino (según el prefijo del número que recibe) y el total en la moneda de tu organización. Los teléfonos sin prefijo válido no se envían ni se cobran. `wallet.sufficient` dice si el saldo alcanza; `includedUtilityRemaining` son los mensajes Utility incluidos que quedan (solo plantillas Utility)." } }, { "name": "Enviar, programar o escalonar", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/campaigns/{id}/send", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id", "send" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "`when: now` (o sin cuerpo) envía al momento; `scheduled` con `scheduledAt` (ISO 8601 con zona, al menos un minuto en el futuro) la deja programada; `staggered` la reparte en tandas de `batchSize` (10 a 5.000) cada `batchIntervalMin` minutos (1 a 1.440). El coste del lote se cobra de la wallet antes de llamar a Meta; si el saldo no alcanza, responde 400 «Saldo insuficiente en la wallet.» y la campaña queda como estaba. Responde con la campaña y su nuevo estado.", "body": { "mode": "raw", "raw": "{\n \"when\": \"staggered\",\n \"batchSize\": 200,\n \"batchIntervalMin\": 10\n}", "options": { "raw": { "language": "json" } } } } }, { "name": "Pausar", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/campaigns/{id}/pause", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id", "pause" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Detiene el envío de lo que falta; lo ya enviado no se puede retirar. Solo con campañas que están enviando." } }, { "name": "Reanudar", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/campaigns/{id}/resume", "host": [ "{{baseUrl}}" ], "path": [ "campaigns", ":id", "resume" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Continúa una campaña pausada desde donde se quedó (también las que se pausaron por falta de saldo, una vez recargada la wallet)." } } ] }, { "name": "Automatizaciones", "item": [ { "name": "Listar automatizaciones", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/automations", "host": [ "{{baseUrl}}" ], "path": [ "automations" ], "query": [ { "key": "tab", "value": "", "disabled": true }, { "key": "trigger", "value": "", "disabled": true }, { "key": "q", "value": "", "disabled": true }, { "key": "includeArchived", "value": "", "disabled": true } ], "variable": [] }, "description": "Las automatizaciones de la organización con su disparador, pasos, una descripción en palabras (`triggerLabel`, `stepsSummary`) y las ejecuciones de la última semana. Filtra por pestaña (`tab`), disparador o búsqueda; `includeArchived=true` incluye las archivadas. No se pagina." } }, { "name": "Ver una automatización", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/automations/{id}", "host": [ "{{baseUrl}}" ], "path": [ "automations", ":id" ], "query": [], "variable": [ { "key": "id", "value": "" } ] }, "description": "Disparador, configuración y pasos (condición, acción, espera) tal como se definieron en el panel, más las ejecuciones de la última semana." } }, { "name": "Ejecuciones de una automatización", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/automations/{id}/logs", "host": [ "{{baseUrl}}" ], "path": [ "automations", ":id", "logs" ], "query": [ { "key": "page", "value": "", "disabled": true }, { "key": "pageSize", "value": "", "disabled": true }, { "key": "result", "value": "", "disabled": true } ], "variable": [ { "key": "id", "value": "" } ] }, "description": "Cada vez que el disparador se cumplió para un contacto: estado (`COMPLETED`, `WAITING`, `CONDITION_NOT_MET`, `SKIPPED_NO_CONSENT`, `FAILED`), explicación en palabras y plantillas enviadas con su coste. Filtra por `result`. `summary` resume la última semana." } } ] }, { "name": "Informes", "item": [ { "name": "Informe comercial", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reports/comercial", "host": [ "{{baseUrl}}" ], "path": [ "reports", "comercial" ], "query": [ { "key": "days", "value": "", "disabled": true } ], "variable": [] }, "description": "Oportunidades abiertas, ganadas y perdidas en el periodo (`days`: 7, 30 o 90), con su importe, la tasa de conversión y el periodo anterior para comparar." } }, { "name": "Informe de ciclo de vida", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reports/lifecycle", "host": [ "{{baseUrl}}" ], "path": [ "reports", "lifecycle" ], "query": [], "variable": [] }, "description": "Cuántos contactos hay en cada etapa; `stage: null` son los que no tienen etapa." } }, { "name": "Informe de campañas", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reports/campanas", "host": [ "{{baseUrl}}" ], "path": [ "reports", "campanas" ], "query": [ { "key": "days", "value": "", "disabled": true } ], "variable": [] }, "description": "Campañas del periodo, destinatarios por estado y gasto total, con el periodo anterior para comparar." } }, { "name": "Informe de la wallet", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reports/wallet", "host": [ "{{baseUrl}}" ], "path": [ "reports", "wallet" ], "query": [ { "key": "days", "value": "", "disabled": true } ], "variable": [] }, "description": "Saldo actual y movimientos del periodo agrupados por tipo (recargas, campañas, mensajes Service fuera de la franquicia, agentes IA…). Importes finales." } }, { "name": "Informe del equipo", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reports/agentes", "host": [ "{{baseUrl}}" ], "path": [ "reports", "agentes" ], "query": [], "variable": [] }, "description": "Por cada persona del equipo: contactos de los que es propietaria, conversaciones abiertas y oportunidades abiertas y ganadas." } }, { "name": "Informe de conversaciones", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/reports/conversaciones", "host": [ "{{baseUrl}}" ], "path": [ "reports", "conversaciones" ], "query": [ { "key": "days", "value": "", "disabled": true } ], "variable": [] }, "description": "Conversaciones por estado y por canal, nuevas en el periodo y el periodo anterior para comparar." } } ] } ] }