API de desarrollador

Descripción general

La API de desarrollador de Nudgen brinda scripts, herramientas internas y agentes de IA una interfaz REST predecible para su espacio de trabajo. Utilice un token de acceso personal (PAT) para administrar los recursos del espacio de trabajo. Utilice una clave API de activación de equipo solo para activar una campaña de por vida desde su backend.

Por qué esto es importante

Puede automatizar los flujos de trabajo de marketing y retención basados en eventos sin compartir una sesión del panel. Las PAT mantienen la administración del espacio de trabajo revocable, mientras que una clave de activación de equipo estrecha permite que un servicio de producción envíe un empujón activado por evento sin acceso amplio al espacio de trabajo.

URL base

Establezca la URL de la aplicación para su entorno una vez y úsela en cada ejemplo. La producción suele utilizar https://app.nudgen.net; el desarrollo local comúnmente usa http://localhost:3000.

export NUDGEN_APP_URL="https://app.nudgen.net"

Autenticación

Token de acceso personal

Cree una PAT en Configuración → Claves API. Úselo para contactos, administración de campañas, configuración de marca y generación de IA.

Authorization: Bearer $NUDGEN_PAT

Las PAT se muestran solo una vez. Guárdelos de forma segura y revoque cualquier token antiguo o expuesto desde Configuración → Claves de API.

Clave de API de activación de equipo

Una clave de API de activación de equipo comienza con ndg_team_ y tiene un alcance limitado de campaigns:trigger. Solo puede activar campañas de por vida; una PAT no puede activarlas. Solo los propietarios y administradores del espacio de trabajo pueden crear, rotar o revocar estas claves. De forma predeterminada, una clave caduca después de 90 días. Configure expiresInDays en null para crear una clave que no caduque.

curl -X POST "$NUDGEN_APP_URL/api/v1/settings/team-api-keys" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"name":"Order service production","expiresInDays":90}'

La respuesta 201 contiene el texto sin formato key exactamente una vez. Guárdelo en un administrador secreto del lado del servidor. Las respuestas posteriores exponen solo keyPrefix.

Método	Punto final	Descripción
`POST`	`/api/v1/settings/team-api-keys`	Cree una clave API de activación de equipo.
`GET`	`/api/v1/settings/team-api-keys`	Enumere las claves API de activación del equipo.
`POST`	`/api/v1/settings/team-api-keys/:id`	Gire una clave activa y vigente.
`DELETE`	`/api/v1/settings/team-api-keys/:id`	Revocar una clave.

Puntos finales REST

Identidad y espacio de trabajo

Método	Punto final	Descripción
`GET`	`/api/v1/user/me`	Obtenga el usuario autenticado.
`GET`	`/api/v1/teams`	Enumera los espacios de trabajo disponibles para el propietario del token.

Contactos

Método	Punto final	Descripción
`GET`	`/api/v1/contacts`	Enumere contactos con filtros `page`, `limit`, `search`, `tags` y `status`.
`POST`	`/api/v1/contacts/add`	Crea un contacto.
`GET`	`/api/v1/contacts/:id`	Consigue un contacto.
`PATCH`	`/api/v1/contacts/:id`	Actualizar un contacto.
`DELETE`	`/api/v1/contacts/:id`	Eliminar un contacto.

curl -X POST "$NUDGEN_APP_URL/api/v1/contacts/add" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"email":"nathan@example.com","name":"Nathan Nguyen","tags":["api-test"]}'

Campañas únicas y por goteo

Método	Punto final	Descripción
`GET`	`/api/v1/campaigns`	Enumere las campañas en el espacio de trabajo activo.
`POST`	`/api/v1/campaigns`	Cree un borrador de campaña o una campaña programada.
`GET`	`/api/v1/campaigns/:id`	Obtenga detalles de la campaña.
`PUT`	`/api/v1/campaigns/:id`	Actualizar una campaña existente.
`POST`	`/api/v1/campaigns/:id/launch`	Lánzalo ahora o programa una campaña única o por goteo.
`GET`	`/api/v1/campaigns/:id/stats`	Obtenga estadísticas de entrega, apertura, clics, rebotes y quejas.
`GET`	`/api/v1/campaigns/:id/progress`	Obtenga el progreso del envío de la campaña.
`GET`	`/api/v1/campaigns/:id/recipients`	Enumere los destinatarios de la campaña.
`POST`	`/api/v1/campaigns/test-send`	Envíe un correo electrónico de prueba sin estadísticas de envío del panel.

El lanzamiento de una campaña programa un correo electrónico real. Utilice /api/v1/campaigns/test-send para obtener vistas previas de la bandeja de entrada.

Campañas de por vida

Las campañas de por vida se activan mediante eventos: cada activador aceptado crea como máximo una ejecución y envía un empujón al contacto proporcionado. Consulte Usar campañas de por vida para obtener información sobre el flujo de trabajo del panel y orientación sobre contratos variables.

Crear una campaña de por vida

Crear campañas de por vida como draft. No envíe sendNow: true, status: "active" o status: "scheduled"; En su lugar, active la campaña con su punto final del ciclo de vida.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "Order confirmation",
  "type": "lifetime",
  "status": "draft",
  "goal": "Confirm an order and direct the customer to its details.",
  "subject": "Your order {{data.order_id}} was received",
  "html": "<p>Hello {{contact.firstName}},</p><p>Order {{data.order_id}} totals {{data.total}} VND.</p><p><a href=\"{{data.order_url}}\">View your order</a></p>",
  "link": "https://example.com/orders",
  "variableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ],
  "generatedVariableManifest": [
    { "path": "data.order_id", "type": "string", "required": true, "description": "Order ID" },
    { "path": "data.total", "type": "number", "required": true, "description": "Order total in VND" },
    { "path": "data.order_url", "type": "url", "required": true, "description": "Order details URL" }
  ]
}
JSON

variableManifest define hasta 100 variables data.*. Debe incluir todos los tokens data.* utilizados en el asunto o HTML. Los valores predeterminados deben coincidir con el tipo declarado y una variable utilizada en HTML href debe tener el tipo url. Cuando genere contenido de correo electrónico, guarde el generatedVariableManifest coincidente. Nudgen bloquea la activación si difiere del manifiesto actual o si los parámetros declarados requeridos no están en el correo electrónico.

Cambiar el ciclo de vida

Método	Punto final	Autenticación	Descripción
`PATCH`	`/api/v1/campaigns/:campaignId/lifecycle`	palmadita	Cambie una campaña de por vida a `active`, `paused` o `archived`.

curl -X PATCH "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/lifecycle" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"status":"active"}'

Las transiciones válidas son draft → active → paused → active y active|paused → archived. Pausar o archivar cancela las ejecuciones que aún son pending o queued y libera sus reservas de cuota. Es posible que aún se envíe una ejecución que ya se está procesando.

Activar un empujón

Método	Punto final	Autenticación	Descripción
`POST`	`/api/v1/campaigns/:campaignId/triggers`	Clave API de activación del equipo	Cree una ejecución de evento y ponga en cola un empujón.

curl -X POST "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/triggers" \
  -H "Authorization: Bearer $NUDGEN_TEAM_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "eventId": "order_123",
  "eventName": "order.created",
  "occurredAt": "2026-08-23T10:00:00Z",
  "contact": {
    "email": "an@example.com",
    "externalId": "customer_456",
    "name": "An Nguyen",
    "phone": "+84901234567",
    "metadata": { "company": "Nudgen" }
  },
  "data": {
    "order_id": "order_123",
    "total": 490000,
    "order_url": "https://example.com/orders/order_123"
  }
}
JSON

Campo	Tipo	Requerido	Límites y comportamiento
`eventId`	cadena	Sí	1–128 caracteres. Clave de idempotencia única dentro de la campaña; reutilícelo para reintentos.
`eventName`	cadena	No	De 1 a 100 caracteres, por ejemplo `order.created`.
`occurredAt`	Fecha y hora ISO 8601	No	Hora del evento fuente.
`contact.email`	correo electrónico	Sí	En minúsculas. Nudgen crea o actualiza el contacto por correo electrónico.
`contact.externalId`	cadena	No	Entre 1 y 200 caracteres y no puede pertenecer a otro correo electrónico de contacto en el espacio de trabajo.
`contact.name`	cadena	No	Hasta 200 caracteres.
`contact.phone`	cadena	No	Hasta 50 caracteres.
`contact.metadata`	objeto	No	Datos adicionales del perfil de contacto.
`data`	objeto	Sí	Debe coincidir con `variableManifest`; máximo 32 KiB.

Todo el cuerpo de la solicitud está limitado a 64 KiB, el anidamiento JSON en ocho niveles y las claves no seguras como __proto__, constructor y prototype se rechazan. Un nuevo activador devuelve 201 con { "execution": { "id": "...", "status": "queued" }, "duplicate": false }. Reutilizar un eventId devuelve la ejecución existente con 200 y duplicate: true.

Listar ejecuciones

Método	Punto final	Autenticación	Descripción
`GET`	`/api/v1/campaigns/:campaignId/executions`	palmadita	Enumere las ejecuciones de campañas de por vida.

curl "$NUDGEN_APP_URL/api/v1/campaigns/$CAMPAIGN_ID/executions?limit=25&status=sent&search=an@example.com" \
  -H "Authorization: Bearer $NUDGEN_PAT"

Utilice limit del 1 al 100 (predeterminado 25), cursor para la página siguiente, status para filtrar por estado de ejecución y search para coincidir. un correo electrónico o una identificación externa. La respuesta incluye executions y nextCursor.

Errores, reintentos y límites de velocidad

Los activadores de por vida permiten 600 solicitudes por minuto para cada clave API de activación del equipo. Las respuestas incluyen x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset. Una respuesta 429 también incluye Retry-After.

Estado	Significado	Qué hacer
`200`	Duplicado `eventId`	Utilice la ejecución devuelta; no enviar de nuevo.
`201`	Nueva ejecución en cola	Espere a que el trabajador lo procese.
`400`	JSON, cuerpo o campo básico no válido	Corrija la carga útil; no lo vuelva a intentar sin cambios.
`401`	Clave faltante, no válida, revocada, vencida o con alcance incorrecto	Gire o corrija la configuración de la clave.
`402` / `403`	Cuota o suscripción impide escrituras	Resolver el problema de cuota o suscripción. Los errores de cuota incluyen `code`, `required`, `available` y `checkoutUrl`.
`404`	Falta la campaña o está fuera del espacio de trabajo de la clave	Verifique el ID y la clave de la campaña.
`409`	La campaña no está activa/no es de por vida o hay conflictos de identidad de contacto	Activar la campaña o corregir la identidad del contacto.
`413`	La solicitud supera los 64 KiB	Reducir el tamaño de la carga útil.
`415`	Falta `Content-Type: application/json`	Agregue el encabezado requerido.
`422`	`data` no coincide con la variable manifiesto	Corregir los datos; Inspeccione `details` en busca de rutas y códigos de error.
`429`	Límite de tarifa excedido	Espere a `Retry-After`, luego vuelva a intentarlo con el mismo `eventId`.
`503`	La ejecución no se pudo poner en cola	Vuelva a intentarlo con retroceso y el mismo `eventId`.

Para 429, 503 y errores de red, vuelva a intentarlo con un retroceso exponencial y el mismo eventId. El trabajo en cola es determinista para una ejecución, por lo que los reintentos no crean correos electrónicos duplicados.

Configuración de marca

Método	Punto final	Descripción
`GET`	`/api/v1/settings/brand`	Lea el nombre de la marca, el sitio web, el correo electrónico del remitente, el logotipo y la configuración de diseño.
`PATCH`	`/api/v1/settings/brand`	Actualizar la configuración de la marca.

Generación de borradores de IA

Método	Punto final	Descripción
`POST`	`/api/v1/ai/generate`	Genere un asunto de correo electrónico y un borrador HTML a partir del contexto de la campaña.

Servidor MCP

Utilice Nudgen MCP cuando su agente admita herramientas del Protocolo de Contexto de Modelo. MCP utiliza OAuth vinculado al espacio de trabajo elegido; las campañas nuevas se guardan como borradores y el asistente las lanza directamente cuando autorizas el envío o la programación en el chat. La API REST utiliza un token de acceso personal (PAT).

MCP server setup

Instale Nudgen MCP en Claude Code, Cursor, Windsurf, Codex CLI o un cliente MCP genérico.

API de Map Leads

Usa un PAT del workspace activo. Las búsquedas nuevas consumen la cuota diaria; las páginas adicionales y los reintentos no. Se reinicia a medianoche UTC. Ampliar el radio inicia otra búsqueda. Los fallos del proveedor liberan la reserva; cancelar una búsqueda aceptada no. API y MCP usan 5 km por defecto y aceptan un entero radiusKm de 1 a 100, sin diálogo de confirmación. Mantén los parámetros al pasar nextPageToken como pageToken. Una página vacía puede tener una página siguiente. enrichmentPending indica investigación del sitio pendiente. Revisa businessSummary y businessSources cuando estén disponibles. El contexto importado puede apoyar introducciones personalizadas. Un correo ausente puede seguir pendiente de investigación.

Method	Endpoint
`POST`	`/api/v1/map-leads/suggest`
`POST`	`/api/v1/map-leads/place`
`POST`	`/api/v1/map-leads/search`
`POST`	`/api/v1/map-leads/enrichment-retry`
`POST`	`/api/v1/map-leads/import`
`GET`	`/api/v1/map-leads/quota`
`GET`	`/api/v1/map-leads/geolocate`

curl -X POST "$NUDGEN_APP_URL/api/v1/map-leads/search" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data '{"location":"Austin, TX","keywords":"marketing agency","radiusKm":5}'

Si recibes enrichmentRetryToken, llama a POST /api/v1/map-leads/enrichment-retry con token y PAT. El token está vinculado al workspace conectado, caduca en 15 minutos y se usa una vez. Combina los resultados por placeId antes de importar. Usa Accept: application/x-ndjson para búsqueda o reintento. Cada línea JSON tiene type: progress, complete o error. Combina data.leads por placeId. El resultado final es complete.data; el error está en error. Sin esta cabecera recibes JSON. POST /place resuelve una sugerencia de ubicación; GET /geolocate devuelve un centro fijo en Ciudad Ho Chi Minh y no obtiene tu ubicación.

curl -N -X POST "$NUDGEN_APP_URL/api/v1/map-leads/search" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  --data '{"location":"Austin, TX","keywords":"marketing agency","radiusKm":5}'

curl -X POST "$NUDGEN_APP_URL/api/v1/map-leads/enrichment-retry" \
  -H "Authorization: Bearer $NUDGEN_PAT" \
  -H "Content-Type: application/json" \
  --data "{\"token\":\"$ENRICHMENT_RETRY_TOKEN\"}"

​Descripción general

​Por qué esto es importante

​URL base

​Autenticación

​Token de acceso personal

​Clave de API de activación de equipo

​Puntos finales REST

​Identidad y espacio de trabajo

​Contactos

​Campañas únicas y por goteo

​Campañas de por vida

​Crear una campaña de por vida

​Cambiar el ciclo de vida

​Activar un empujón

​Listar ejecuciones

​Errores, reintentos y límites de velocidad

​Configuración de marca

​Generación de borradores de IA

​Servidor MCP

MCP server setup

​API de Map Leads

Descripción general

Por qué esto es importante

URL base

Autenticación

Token de acceso personal

Clave de API de activación de equipo

Puntos finales REST

Identidad y espacio de trabajo

Contactos

Campañas únicas y por goteo

Campañas de por vida

Crear una campaña de por vida

Cambiar el ciclo de vida

Activar un empujón

Listar ejecuciones

Errores, reintentos y límites de velocidad

Configuración de marca

Generación de borradores de IA

Servidor MCP

API de Map Leads