API de puntos de captura

Un punto de captura expone un endpoint público de plataforma a plataforma (Zapier, Make, tu backend) que convierte un envío en contacto + consentimiento, con su origen registrado y, si la conectas, una automatización de bienvenida.

Los puntos se crean y gestionan en la app, en Captación → API. La URL exacta de cada punto está en su propia fila.

El endpoint#

POST https://app.konverda.com/webhooks/capture/<token-del-punto>
Content-Type: application/json

Se recomienda application/json; también se acepta application/x-www-form-urlencoded. La respuesta es SIEMPRE JSON.

Probarlo con curl#

curl -X POST 'https://app.konverda.com/webhooks/capture/<token-del-punto>' \
  -H 'Content-Type: application/json' \
  -d '{ "phone": "+34612345678", "name": "Ana Pérez", "consent": true }'

Respuestas#

Código	Cuerpo	Significado
200	{"ok":true}	Registrado — o recibido sin teléfono (cuenta, no crea contacto) — o bot silenciosamente filtrado (_hp relleno). Un bot recibe el mismo 200 a propósito: un rechazo le enseñaría qué campo lo delató.
400	{"error":"bad_payload","message":"…"}	El cuerpo no se pudo leer o no es un objeto con campos (JSON inválido, text/plain, {} vacío).
403	{"error":"verification_failed"}	Turnstile no verificado (el punto lo exige y el token no valida).
404	{"error":"not_found"}	Token desconocido o punto desactivado.
422	{"error":"consent_required","message":"…"}	El payload no afirma el consentimiento (consent ausente o no afirmativo). El message explica en una frase qué falta.
422	{"error":"invalid_phone"}	phone presente pero irreconocible. (Ausente NO es un error: ver campos.)
429	{"error":"rate_limited"}	Más de 10 envíos por minuto por IP y punto.

Cada rechazo (400, 403, 422) queda contado en las analíticas del punto con su motivo — «Rechazados en la puerta» — para que una integración mal configurada se vea en el embudo y no solo en este código de error.

Consentimiento: qué nivel de contacto crea cada envío#

Un contacto tiene DOS niveles posibles. «Marketing» = puede recibir campañas, oleadas, automatizaciones proactivas y plantillas 1

. «No» = solo podemos responderle cuando escribe él, y ningún mensaje que iniciemos nosotros le llega (el intento queda registrado como not_marketing).

Aquí el nivel no lo decide solo tu payload: lo decide la configuración del punto («Consentimiento explícito», en la fila del punto) combinada con el consent que envías.

Configuración del punto	Base registrada	Opt-in resultante	Qué puede recibir
«Consentimiento explícito» ACTIVADO + consent afirmativo	checkbox	Marketing	Todo: campañas, oleadas, la automatización de bienvenida y plantillas 1 . Al ser un acto explícito de la propia persona, levanta una baja anterior.
«Consentimiento explícito» DESACTIVADO + consent afirmativo	form	No	Solo respuestas cuando la persona escribe. La automatización de bienvenida de este punto NO se envía (queda registrada como not_marketing). Una baja anterior se respeta siempre.
consent ausente o falso, con phone	— (no se procesa)	No se crea contacto	422 consent_required.
Sin phone	—	No se crea contacto	200: el envío se cuenta como «sin teléfono» en las analíticas del punto.

Un contacto en nivel «No» no es un contacto perdido#

En cuanto te escribe, la conversación se abre y puedes responderle. Ahí es donde entran las palabras clave: una palabra que la persona escribe es una puerta que abre ella, así que funciona con cualquier nivel de consentimiento. Si captas leads por este endpoint, dales una palabra que escribir.

Seguir leyendo#

• El opt-in de marketing y «Añadir a marketing»
• La baja y qué recuerda la plataforma
• API de pedidos (conexión genérica) — el otro endpoint público, para ventas.