Crear contacto

POST /api/v1/contacts

Este endpoint permite registrar un nuevo contacto en la plataforma.

Además de los datos básicos como nombre y documento, permite registrar múltiples vías de contacto (teléfonos, correos) y campos adicionales personalizados, lo que lo convierte en un punto de entrada flexible para la creación de nuevos registros. El sistema valida la unicidad de las vías de contacto dentro del equipo y aplica las reglas de negocio definidas para los campos adicionales.

ℹ 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).
Content-Type	String	✅ Sí	Debe ser application/json.

Cuerpo de la solicitud (Body)

Atributo	Tipo	Obligatorio	Descripción
name	String	✅ Sí	Nombre(s) del contacto. Máximo 255 caracteres.
last_name	String	✅ Sí	Apellido(s) del contacto. Máximo 255 caracteres.
doc_type	String	✅ Sí	Tipo de documento. Valores permitidos: DNI, RUC, PASAPORTE, OTROS.
doc_num	String	❌ No	Número del documento. La validación de la longitud depende del doc_type: DNI (8 caracteres), RUC (11 caracteres), PASAPORTE (mínimo 6).
company_id	Integer	✅ Sí	Identificador de la empresa a la que se asociará el contacto, Si no requiere asociar un contacto con una empresa, se debe enviar el valor 0.
contact_sources	Array	✅ Sí	Lista de vías de contacto. Debe contener al menos un elemento. Vea la estructura detallada más adelante.
extra_fields	Array	❌ No	Lista de campos adicionales personalizados. Importante: Si su equipo tiene campos adicionales configurados como obligatorios, deben ser incluidos en esta lista.
details	String	❌ No	Notas o detalles adicionales sobre el contacto.
is_vip	Boolean	❌ No	Marcar el contacto como VIP. Por defecto es false.

Estructura de contact_sources

Es un array de objetos, donde cada objeto representa una vía de contacto y debe tener la siguiente estructura:

Atributo	Tipo	Descripción
type	String	Tipo de vía de contacto. Valores permitidos: CELL_PHONE, PHONE, EMAIL.
source	String	El valor de la vía de contacto (el número de teléfono o el correo).

🛑 Mínimo una Vía de Contacto

Tenga en cuenta que no se permite enviar un arreglo vacío ([]) para contact_sources, ya que el contacto siempre debe tener al menos una vía de contacto de tipo (CELL_PHONE, PHONE o EMAIL).

Estructura de extra_fields

Es un array de objetos para los campos adicionales. Cada objeto debe contener el id del campo preconfigurado y su value.

Atributo	Tipo	Descripción
id	Integer	ID del campo adicional configurado en el sistema.
value	String/Array	Valor a asignar. Para campos tipo checkbox, puede ser un array de strings.

Ejemplo de solicitud

POST /api/v1/contacts

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

{
  "name": "Juan",
  "last_name": "Pérez",
  "doc_type": "DNI",
  "doc_num": "45678912",
  "details": "Cliente frecuente de Lima con interés en tecnología.",
  "contact_sources": [
    {
      "type": "CELL_PHONE",
      "source": "+51987654321"
    },
    {
      "type": "EMAIL",
      "source": "juan.perez20@example.com"
    }
  ],
  "company_id": 2,
  "extra_fields": [
    {
      "id": 23,
      "name": "Nivel de interés",
      "value": "Alto"
    },
    {
      "id": 25,
      "name": "Género",
      "value": "M"
    }
  ],
  "is_vip": true
}

Respuesta

En caso de éxito, la API devuelve el objeto del contacto recién creado.

Respuesta Exitosa 201

{
	"message": "Contacto creado exitósamente.",
	"data": {
		"id": 73,
		"name": "Juan",
		"last_name": "Pérez",
		"doc_type": "DNI",
		"doc_num": "45678912",
		"active": true,
		"details": "Cliente frecuente de Lima con interés en tecnología.",
		"company": {
			"id": 2,
			"name": "Elemental Solutions SAC",
			"ruc": "20567898766"
		},
		"extra_fields": [
			{
				"id": 23,
				"name": "Nivel de interés",
				"value": "Alto"
			},
			{
				"id": 25,
				"name": "Género",
				"value": "M"
			}
		],
		"contact_sources": [
			{
				"type": "CELL_PHONE",
				"source": "+51987654321"
			},
			{
				"type": "EMAIL",
				"source": "juan.perez20@example.com"
			}
		],
		"created_at": "2025-09-09T15:57:16.000000Z",
		"addresses": [],
		"is_vip": true
	}
}

Definición de atributos

Campo	Tipo	Descripción
message	String	Mensaje de respuesta del servidor.
data	Object	Objeto que contiene todos los datos del contacto recién creado.
data.id	Integer	Identificador único del nuevo contacto.
data.name	String	Nombre(s) del contacto.
data.last_name	String	Apellido(s) del contacto.
data.doc_type	String	Tipo de documento de identidad.
data.doc_num	String	Número del documento de identidad.
data.active	Boolean	Indica el estado del contacto.
data.details	String	Notas o detalles adicionales.
data.company	Object	Objeto con la información de la empresa asociada.
data.extra_fields	Array	Lista de campos adicionales con su id, name (nombre visible) y value.
data.contact_sources	Array	Lista de las vías de contacto registradas.
data.created_at	String	Fecha y hora de creación del registro
data.addresses	Array	Lista de direcciones.
data.is_vip	Boolean	Indica si el contacto fue marcado como VIP.

Errores Específicos

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 con otro contacto" }	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).
422	{ "message": "Error de validación", "data": { "name": [ "El campo name es obligatorio." ], "doc_num": [ "El campo doc num debe tener 8 caracteres para DNI." ] } }	Faltan campos obligatorios (como name o company_id), un valor no cumple el formato esperado (ej. doc_type inválido), o se viola una regla de longitud (ej. doc_num).
422	{ "message": "Error de validación en campos dinámicos", "data": { "extra_field_id_99": [ "El campo con ID 99 no es válido o está inactivo." ] } }	Un campo en extra_fields es obligatorio según la configuración del equipo y no fue enviado, el valor proporcionado no cumple con sus reglas de validación (ej. no es numérico), o se envió un id de campo que no existe o está inactivo para ese equipo.

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.