Actualizar contacto (parcial)

PATCH /api/v1/contacts/{id}

Este endpoint permite modificar los datos de un contacto existente de forma parcial. Solo necesita enviar los campos que desea cambiar.

El comportamiento de la actualización tiene consideraciones especiales:

• Vías de contacto (contact_sources): No se permite enviar el campo contact_sources. Para cambiar una vía de contacto debe:

  • Eliminar la vía de contacto existente.
  • Crear una nueva vía de contacto.

• Campos adicionales (extra_fields): Puede enviar solo los campos que desea modificar. Los campos que no incluya en la solicitud conservarán su valor actual.

El sistema registra un historial de cambios para los campos principales y 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.

Parámetros de URL

Parámetro	Tipo	Obligatorio	Descripción
id	Integer	✅ Sí	Identificador único del contacto a actualizar.

Cuerpo de la solicitud (Body)

Dado que es una actualización parcial (PATCH), solo necesita enviar los campos que desea modificar.

Atributo	Tipo	Obligatorio	Descripción
name	String	❌ No	Nuevo nombre(s) del contacto.
last_name	String	❌ No	Nuevo apellido(s) del contacto.
doc_type	String	❌ No	Nuevo tipo de documento. Valores permitidos: DNI, RUC, PASAPORTE, OTROS.
doc_num	String	❌ No	Nuevo número del documento. Su validación depende del doc_type.
company_id	Integer	❌ No	Nuevo identificador de la empresa a la que está asociado el contacto, puede enviar el valor 0 si requiere remover la asociación con una empresa.
extra_fields	Array	❌ No	Lista de campos adicionales a actualizar.
details	String	❌ No	Nuevas notas o detalles sobre el contacto.
is_vip	Boolean	❌ No	Actualizar el estado VIP del contacto.

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

Este ejemplo actualiza el apellido del contacto, cambia su estado a no-VIP y actualiza una de sus vías de contacto.

PATCH /api/v1/contacts/73

{
    "last_name": "García de Pérez",
    "is_vip": false,
}

Respuesta

Si la actualización es exitosa, la API devuelve el objeto completo del contacto con los datos actualizados.

Respuesta Exitosa 200

{
    "message": "Contacto actualizado exitósamente",
    "data": {
        "id": 73,
        "name": "Juan",
        "last_name": "García de Pérez",
        "doc_type": "DNI",
        "doc_num": "45678912",
        "active": true,
        "details": null,
        "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": "+51999888777"
            },
            {
                "type": "EMAIL",
                "source": "ana.garcia@example.com"
            }
        ],
        "created_at": "2025-09-09T15:57:16.000000Z",
        "addresses": [],
        "is_vip": false
    }
}

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 actualizado.
data.id	Integer	Identificador único del 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
404	{ "message": "Error de validación", "data": { "company_id2": [ "El campo no es permitido." ] }	Los campos envíados no son válidos.
404	{ "message": "El contacto existe pero se encuentra inactivo." }	El contacto que se intenta actualizar ha sido marcado como inactivo y no puede ser modificado.
422	{ "message": "Error de validación", "data": { "doc_num": [ "El campo doc num debe tener 8 caracteres para DNI." ] } }	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." ] } }	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.