Crear vía de contacto

POST /api/v1/contacts/{id}/contact-sources

Este endpoint permite añadir una nueva vía de contacto (como un número de teléfono o correo electrónico) a un contacto existente identificado por su id.

La plataforma valida que el valor de la nueva vía de contacto (source) no esté duplicado dentro del mismo equipo para mantener la integridad de los datos. Además, los números de teléfono son normalizados automáticamente a un formato estándar.

Al crear la vía de contacto exitosamente, se registra un evento en el historial del contacto para auditar la adición de la nueva información.

ℹ Recuerda que:

La URL base para todas las solicitudes es: https://tu-dominio.c3.pe

Importante: reemplaza tu-dominio por el nombre de dominio específico que te haya proporcionado C3.

Solicitud

Cabeceras

Encabezado	Tipo	Obligatorio	Descripción
Authorization	String	✅ Sí	Token de autenticación (Bearer Token).

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción
id	Integer	✅ Sí	Identificador único del contacto al que se le añadirá la vía.

Cuerpo de la solicitud

Atributo	Tipo	Obligatorio	Descripción
type	String	✅ Sí	Tipo de vía de contacto. Valores permitidos: CELL_PHONE, PHONE, EMAIL, PHONE.
source	String	✅ Sí	El valor de la vía de contacto (ej: 987654321 o juan@example.com). Máximo 255 caracteres.

Ejemplo de solicitud

POST /api/v1/contacts/66/contact-sources

El cuerpo de la solicitud debe enviarse en formato JSON e incluir los siguientes campos:

{
  "type": "CELL_PHONE",
  "source": "987654321"
}

Respuesta

Respuesta base 201 Created

{
    "message": "Vía de contacto creada exitósamente.",
    "data": {
        "type": "CELL_PHONE",
        "source": "+51987654321",
        "contact_id": 45
    }
}

Definición de atributos

Campo	Tipo	Descripción
message	String	Mensaje de éxito de la operación.
data	Object	Objeto que contiene la nueva vía de contacto creada.
data.id	Integer	ID único de la vía de contacto.
data.type	String	Tipo de la vía de contacto (CELL_PHONE, EMAIL, PHONE).
data.source	String	Valor normalizado de la vía de contacto.
data.contact_id	Integer	ID del contacto al que pertenece esta vía.

Errores específicos del endpoint

Además de los errores generales, este endpoint puede devolver los siguientes errores específicos de validación y lógica de negocio:

Código HTTP	Ejemplo	Causa Común
400	{ "message": "El teléfono +51987654321 ya está registrado" }	El teléfono o email proporcionado en contact_sources ya pertenece a otro contacto dentro de su equipo.
400	{ "message": "El email 'juan.perez20@' no es válido." }	Una de las vías de contacto (source) no tiene un formato válido (ej. un email incompleto o un número de teléfono con caracteres no permitidos).
404	{ "message": "Contacto no encontrado" }	El id proporcionado en la URL no corresponde a ningún contacto existente.

Errores generales

Código HTTP	Tipo	Causa común
401	Unauthorized	El token de acceso no fue proporcionado en el encabezado Authorization, es inválido o ha sido revocado. Verifique que el token sea correcto y esté activo.
422	Unprocessable Entity	La solicitud fue entendida, pero contiene errores semánticos que impiden su procesamiento. Esto puede deberse a: 1. Parámetros faltantes o inválidos (ej, from_date no es una fecha válida); 2. Recurso inexistente (wa_number no registrado en el sistema); 3. Violación de reglas de negocio (el rango de fechas excede el límite permitido).
500	Server Error	Error interno del servidor. Intenta nuevamente más tarde o contacta soporte técnico.