API para desarrolladores

Versión 1 · openapi.json (OpenAPI 3.1)

Con la API, n8n, Make, Zapier o un agente de IA pueden crear leads, mover negocios, programar tareas y actividades, consultar el inventario y la disponibilidad de unidades, y responder en la Bandeja. Importa el documento OpenAPI en tu herramienta (Postman, Make, el nodo HTTP de n8n…) para tener todas las rutas.

Tokens

• Un administrador crea el token en Configuración → Integraciones → n8n y API, con un nombre, los permisos que necesita y, si quieres, un vencimiento. El token se muestra una sola vez.
• Cada llamada lleva la cabecera Authorization: Bearer np_… y envía y recibe JSON. URL base: https://app.novoprospect.io/api/v1
• El token es de una empresa: solo ve y cambia los datos de esa empresa. Lo que hace queda en el historial con el nombre del token.

curl "https://app.novoprospect.io/api/v1/contactos?q=ana" \
  -H "Authorization: Bearer np_…"

Permisos

Límites, listas y errores

• Hasta 120 peticiones por minuto por token. Las respuestas traen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset; al pasarte, 429 con Retry-After.
• Las listas usan ?limit= y ?offset= y responden { data, total, limit, offset, hasMore }.
• Los errores responden { "error": "texto", "code": "not_found", "requestId": "…" }. El code no cambia; el texto puede cambiar. Códigos: invalid_request, unauthorized, token_expired, forbidden, insufficient_scope, api_paused, not_found, conflict, unprocessable, rate_limited, internal_error.
• Fechas de tareas y actividades en hora de República Dominicana: YYYY-MM-DD y HH:MM.

Privacidad

Solo se exponen los canales de la empresa: las conversaciones de los canales personales de los agentes nunca salen de NovoProspect. Las propiedades no incluyen comisiones, notas privadas ni datos del propietario, y un negocio no se puede marcar Ganado desde la API (eso abre el cierre y la comisión en el CRM).

Webhooks

NovoProspect avisa a tu URL cuando pasa algo: un POST JSON con { id, event, createdAt, data }. En data llega el registro con los mismos campos que la API (en el OpenAPI, sección webhooks, está el cuerpo de cada evento).

• Se crean en Integraciones → n8n y API o por la API (POST /webhooks, permiso webhooks:manage), que es lo que usan Zapier y Make: la suscripción se crea al activar el flujo y se borra al apagarlo o si tu URL responde 410.
• Cabeceras: X-NovoProspect-Event, X-NovoProspect-Delivery (id de la entrega, el mismo en cada reintento: úsalo para no procesarla dos veces), X-NovoProspect-Timestamp y X-NovoProspect-Signature = sha256= HMAC-SHA256 con el secreto del webhook de timestamp + "." + cuerpo.
• Responde 2xx en menos de 10 segundos. Si no, se reintenta a los 1 min, 5 min, 30 min, 2 h, 12 h. Tras 15 entregas fallidas seguidas el webhook se pausa y se avisa al administrador. Cada entrega queda 30 días en el registro, con su botón «Reenviar».
• Solo salen datos de la empresa: nada de los canales personales de los agentes ni de comisiones.

Servidor MCP

Para Claude, ChatGPT, Cursor, n8n y cualquier cliente MCP: https://app.novoprospect.io/mcp (Streamable HTTP, sin estado). Se entra con OAuth 2.1 (registro dinámico y PKCE: así lo hacen los conectores de Claude.ai y ChatGPT; lo aprueba un administrador) o con un token de la API en Authorization: Bearer np_…. En los dos casos, con los mismos permisos, límites y privacidad que la API: tools/list muestra solo las herramientas que el token puede usar, y cada herramienta llama a la ruta de la API del mismo nombre.

Claude.ai: Configuración → Conectores → Agregar conector personalizado
ChatGPT: Configuración → Conectores (modo desarrollador) → Crear
URL: https://app.novoprospect.io/mcp
Sin token: se abre NovoProspect para iniciar sesión como administrador y elegir los permisos.

claude mcp add --transport http novoprospect https://app.novoprospect.io/mcp \
  --header "Authorization: Bearer np_…"

{
  "mcpServers": {
    "novoprospect": {
      "url": "https://app.novoprospect.io/mcp",
      "headers": {
        "Authorization": "Bearer np_…"
      }
    }
  }
}

Endpoint: https://app.novoprospect.io/mcp
Server Transport: HTTP Streamable
Authentication: Bearer Auth → el token np_…

Referencia