Prospectos

Esta guía explica cómo crear un prospecto en KintiSoft utilizando la API REST o el SDK oficial.

Un prospecto representa un posible cliente que ha mostrado interés en tus productos o servicios, por ejemplo:

• Leads de formularios web
• Registros desde landing pages
• Contactos capturados por campañas de marketing

---

Requisitos previos

• Tener un tenant activo en KintiSoft
• Contar con una Public API Key
• Acceso a internet para realizar peticiones HTTP

---

Autenticación

KintiSoft utiliza API Keys para autenticación.

La API Key debe enviarse en el header Authorization con el siguiente formato:

Authorization: Bearer pk_public_xxxxxx

---

Quick Start (SDK – recomendado)

Instalación

npm install @kintisoft/sdk

---

Crear el cliente

import { KintiSoftClient } from "@kintisoft/sdk";

const client = new KintiSoftClient({
  tenant: "acme",
  apiKey: "pk_public_xxxxxx"
});

---

Crear un prospecto

const response = await client.prospects.create({
  contact_name: "Juan Pérez",
  email: "juan@example.com",
  phone: "+593999999999",
  accept_ads: true,
  comment: "Lead generated from landing page"
});

console.log(response.message);

---

Quick Start (API REST)

Endpoint

POST /prospects

Base URL

https://api.kintisoft.com/v1

---

Request HTTP

POST https://api.kintisoft.com/v1/prospects
Authorization: Bearer pk_public_xxxxxx
Content-Type: application/json

{
  "contact_name": "Juan Pérez",
  "email": "juan@example.com",
  "phone": "+593999999999",
  "accept_ads": true,
  "comment": "Lead generated from landing page"
}

---

Request cURL

curl -X POST https://api.kintisoft.com/v1/prospects \
  -H "Authorization: Bearer pk_public_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_name": "Juan Pérez",
    "email": "juan@example.com",
    "phone": "+593999999999",
    "accept_ads": true,
    "comment": "Lead generated from landing page"
  }'

---

Flujo recomendado

1. El usuario completa un formulario
2. Tu aplicación valida los datos
3. Se crea el prospecto vía API
4. El prospecto queda disponible en el módulo de Personas

---

Parámetros

Campo	Tipo	Obligatorio	Descripción
contact_name	string	Sí	Nombre completo del contacto
email	string	Sí	Correo electrónico válido
phone	string	No	Teléfono en formato internacional
accept_ads	boolean	No	Indica si aceptó recibir comunicaciones
comment	string	No	Comentario interno o fuente del lead

---

Respuesta exitosa

{
  "success": true,
  "message": "Prospect created successfully",
  "data": {
    "id": "prsp_123456"
  }
}

---

Manejo de errores

Ejemplo de error de validación:

{
  "error": {
    "code": "validation_error",
    "message": "Email is invalid",
    "request_id": "req_abc123"
  }
}

Códigos de error comunes

Código	Descripción
validation_error	Datos inválidos
unauthorized	API Key inválida o ausente
forbidden	Sin permisos
rate_limited	Demasiadas solicitudes
server_error	Error interno

---

Buenas prácticas

• Valida los datos antes de enviarlos
• Maneja errores usando request_id para soporte
• No expongas tu API Key privada en el frontend
• Usa el SDK para reducir errores y código repetitivo

---

Siguientes pasos

• Listar prospectos
• Actualizar un prospecto
• Convertir un prospecto en cliente
• Suscribirse a webhooks de creación de prospectos

---

Referencias

• API: POST /prospects
• SDK: client.prospects.create
• Guía de Autenticación
• Guía de Errores

Usage in Angular

import { Injectable } from '@angular/core';
import { KintiSoftClient } from '@kintisoft/sdk';

@Injectable({ providedIn: 'root' })
export class ProspectService {
  client = new KintiSoftClient({
    tenant: 'acme',
    apiKey: 'pk_public_xxxxxx'
  });

  createProspect(data: any) {
    return this.client.prospects.create(data);
  }
}