API de Blacklist

Descripción

La API de Blacklist permite gestionar la lista de teléfonos que no deben ser contactados.

Endpoints

Listar Teléfonos en Blacklist

http

GET /v1/phone-blacklist

Parámetros de Query:

page (number, opcional): Página actual (default: 1)
limit (number, opcional): Registros por página (default: 20)
sortBy (string, opcional): Campo para ordenar
filter[riskLevel] (string, opcional): Filtrar por nivel de riesgo
filter[detectionMethod] (string, opcional): Filtrar por método de detección

Respuesta:

json

{
  "data": [
    {
      "id": "uuid",
      "phone": "+34123456789",
      "personId": "uuid",
      "reason": "Solicitud explícita de no contacto",
      "riskLevel": "high",
      "detectionMethod": "automatic",
      "originCallId": "uuid",
      "originVoiceAgentCallId": "uuid",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1,
  "statusCode": 200,
  "error": null
}

Obtener Registro por ID

http

GET /v1/phone-blacklist/:id

Parámetros:

id (string, required): ID del registro

Respuesta:

json

{
  "data": {
    "id": "uuid",
    "phone": "+34123456789",
    "reason": "Solicitud explícita de no contacto",
    "riskLevel": "high",
    "detectionMethod": "automatic",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "statusCode": 200,
  "error": null
}

Verificar si un Teléfono está en Blacklist

http

GET /v1/phone-blacklist/check/:phone

Parámetros:

phone (string, required): Número de teléfono a verificar

Respuesta:

json

{
  "data": {
    "isBlacklisted": true,
    "record": {
      "id": "uuid",
      "phone": "+34123456789",
      "reason": "Solicitud explícita de no contacto",
      "riskLevel": "high",
      "detectionMethod": "automatic",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  },
  "statusCode": 200,
  "error": null
}

Agregar Teléfono a Blacklist

http

POST /v1/phone-blacklist

Body:

json

{
  "phone": "+34123456789",
  "personId": "uuid",
  "reason": "Cliente solicitó no ser contactado",
  "riskLevel": "high",
  "detectionMethod": "manual",
  "originCallId": "uuid",
  "originVoiceAgentCallId": "uuid"
}

Campos:

phone (string, required): Número de teléfono
personId (string, optional): ID de la persona asociada
reason (string, required): Razón del bloqueo (mínimo 10 caracteres)
riskLevel (enum, required): high | medium | low
detectionMethod (enum, required): automatic | manual
originCallId (string, optional): ID de la llamada que originó el bloqueo
originVoiceAgentCallId (string, optional): ID de la llamada de voice agent

Respuesta:

json

{
  "data": {
    "id": "uuid",
    "phone": "+34123456789",
    "reason": "Cliente solicitó no ser contactado",
    "riskLevel": "high",
    "detectionMethod": "manual",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "statusCode": 201,
  "error": null
}

Errores:

json

{
  "data": null,
  "statusCode": 409,
  "error": "Phone number is already blacklisted"
}

Actualizar Registro de Blacklist

http

POST /v1/phone-blacklist/:id

Parámetros:

id (string, required): ID del registro

Body:

json

{
  "reason": "Razón actualizada",
  "riskLevel": "medium"
}

Respuesta:

json

{
  "data": {
    "id": "uuid",
    "phone": "+34123456789",
    "reason": "Razón actualizada",
    "riskLevel": "medium",
    "updatedAt": "2024-01-15T11:00:00Z"
  },
  "statusCode": 200,
  "error": null
}

Remover Teléfono de Blacklist

http

DELETE /v1/phone-blacklist/:id

Parámetros:

id (string, required): ID del registro

Respuesta:

json

{
  "data": null,
  "statusCode": 200,
  "error": null
}

Modelos de Datos

PhoneBlacklist

typescript

interface PhoneBlacklist {
  id: string;
  phone: string;
  personId?: string;
  reason: string;
  riskLevel: 'high' | 'medium' | 'low';
  detectionMethod: 'automatic' | 'manual';
  originCallId?: string;
  originVoiceAgentCallId?: string;
  tenantId: string;
  createdAt: Date;
  updatedAt: Date;
  deletedAt?: Date;
}

CallPostProcessing

typescript

interface CallPostProcessing {
  id: string;
  callId?: string;
  voiceAgentCallId?: string;
  tenantId: string;
  variables: {
    blacklistDetection?: {
      shouldBlacklist: boolean;
      reason: string;
      riskLevel: 'high' | 'medium' | 'low';
      confidence: number;
    };
    sentiment?: {
      overall: 'positive' | 'neutral' | 'negative';
      score: number;
    };
  };
  processingStatus: 'pending' | 'processing' | 'completed' | 'failed';
  errorMessage?: string;
  createdAt: Date;
  updatedAt: Date;
}

Autenticación

Todos los endpoints requieren autenticación mediante JWT token:

http

Authorization: Bearer <token>

Rate Limiting

Límite: 1000 requests por minuto
Headers de respuesta:
- X-RateLimit-Limit: Límite total
- X-RateLimit-Remaining: Requests restantes
- X-RateLimit-Reset: Timestamp de reset

Códigos de Error

400 - Bad Request: Parámetros inválidos
401 - Unauthorized: Token inválido o ausente
404 - Not Found: Recurso no encontrado
409 - Conflict: Teléfono ya existe en blacklist
429 - Too Many Requests: Rate limit excedido
500 - Internal Server Error: Error del servidor

Ejemplos de Uso

cURL

bash

# Verificar si un teléfono está en blacklist
curl -X GET \
  'https://api.salescaling.com/v1/phone-blacklist/check/+34123456789' \
  -H 'Authorization: Bearer <token>'

# Agregar teléfono a blacklist
curl -X POST \
  'https://api.salescaling.com/v1/phone-blacklist' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone": "+34123456789",
    "reason": "Cliente solicitó no ser contactado",
    "riskLevel": "high",
    "detectionMethod": "manual"
  }'

JavaScript/TypeScript

typescript

import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.salescaling.com',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

// Verificar blacklist
const checkBlacklist = async (phone: string) => {
  const response = await api.get(`/v1/phone-blacklist/check/${phone}`);
  return response.data;
};

// Agregar a blacklist
const addToBlacklist = async (data: any) => {
  const response = await api.post('/v1/phone-blacklist', data);
  return response.data;
};

Python

python

import requests

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

# Verificar blacklist
response = requests.get(
    'https://api.salescaling.com/v1/phone-blacklist/check/+34123456789',
    headers=headers
)
data = response.json()

# Agregar a blacklist
payload = {
    'phone': '+34123456789',
    'reason': 'Cliente solicitó no ser contactado',
    'riskLevel': 'high',
    'detectionMethod': 'manual'
}
response = requests.post(
    'https://api.salescaling.com/v1/phone-blacklist',
    headers=headers,
    json=payload
)