Etiquetas de contacto

Esta sección documenta los endpoints disponibles para gestionar las etiquetas de los contactos. Las etiquetas permiten categorizar y organizar los contactos de forma flexible, agrupándolos según los criterios que maneje, por ejemplo estado comercial, prioridad de atención, origen u otros.

Las etiquetas asignadas a un contacto también se devuelven dentro de cada registro en el listado de contactos, por lo que no es necesaria una consulta adicional para conocer su categorización actual.

ℹ 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.

Listar etiquetas

GET /api/v1/contacts/labels

Este endpoint permite obtener el listado de etiquetas disponibles para usar en contactos.

Cabeceras

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

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`page`	Integer	❌ No	Página a consultar. Por defecto es `1`.
`per_page`	Integer	❌ No	El campo per_page no puede ser mayor a 20.

Ejemplo de solicitud

http

GET /api/v1/contacts/labels?page=1&per_page=15

Respuesta

Respuesta base 200

json

{
  "message": "Etiquetas obtenidas correctamente",
  "data": [
    {
      "id": 12,
      "title": "Cliente VIP",
      "description": null,
      "bg_color": "#0d6efd",
      "text_color": "#ffffff"
    }
  ],
  "pagination": {
    "total_items": 1,
    "items_per_page": 15,
    "current_page": 1,
    "total_pages": 1
  }
}

Definición de atributos

Campo	Tipo	Descripción
`message`	String	Mensaje de respuesta del servidor.
`data`	Array	Lista de etiquetas disponibles.
`data.id`	Integer	Identificador único de la etiqueta.
`data.title`	String	Título de la etiqueta.
`data.description`	String	Descripción de la etiqueta.
`data.bg_color`	String	Color de fondo de la etiqueta en formato hexadecimal.
`data.text_color`	String	Color del texto de la etiqueta en formato hexadecimal.
`pagination`	Object	Información de la paginación.
`pagination.total_items`	Integer	Total de elementos encontrados.
`pagination.items_per_page`	Integer	Elementos por página.
`pagination.current_page`	Integer	Página actual.
`pagination.total_pages`	Integer	Total de páginas.

Errores de validación

page o per_page no numéricos → "El parámetro page/per_page debe ser un número entero."
per_page mayor al máximo permitido → "El campo per_page no puede ser mayor a la cantidad máxima permitida de 20."

Agregar etiquetas a un contacto

POST /api/v1/contacts/{contactId}/labels

Este endpoint permite agregar etiquetas a un contacto existente. Al agregar etiquetas, la operación es acumulativa: las etiquetas indicadas se suman a las que el contacto ya tiene, sin afectar al resto. Enviar una etiqueta que el contacto ya posee no genera error ni la duplica. Cada contacto admite un máximo de 5 etiquetas.

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
`contactId`	Integer	✅ Sí	ID del contacto al que se le agregarán las etiquetas.

Cuerpo de la solicitud

Atributo	Tipo	Obligatorio	Descripción
`label_ids`	Array de Integer	✅ Sí	IDs de etiquetas a agregar (mínimo 1, sin repetidos).

Ejemplo de solicitud

http

POST /api/v1/contacts/73/labels

json

{
  "label_ids": [12, 45]
}

Respuesta

Respuesta exitosa 200

json

{
  "message": "Etiquetas agregadas al contacto correctamente",
  "data": [
    {
      "id": 12,
      "title": "Cliente VIP",
      "description": null,
      "bg_color": "#0d6efd",
      "text_color": "#ffffff"
    },
    {
      "id": 45,
      "title": "Moroso",
      "description": null,
      "bg_color": "#dc3545",
      "text_color": "#ffffff"
    }
  ]
}

Definición de atributos

Campo	Tipo	Descripción
`message`	String	Mensaje de respuesta del servidor.
`data`	Array	Etiquetas actuales del contacto después de agregar.
`data.id`	Integer	Identificador único de la etiqueta.
`data.title`	String	Título de la etiqueta.
`data.description`	String	Descripción de la etiqueta.
`data.bg_color`	String	Color de fondo de la etiqueta en formato hexadecimal.
`data.text_color`	String	Color del texto de la etiqueta en formato hexadecimal.

Errores de validación

label_ids vacío o ausente → "Debe indicar al menos una etiqueta."
Alguna etiqueta enviada no está disponible para asignar → "Etiqueta no encontrada."
El total de etiquetas del contacto supera 5 → "El contacto no puede tener más de 5 etiquetas."

Quitar etiquetas de un contacto

PUT /api/v1/contacts/{contactId}/labels

Este endpoint permite quitar etiquetas de un contacto existente. Al quitar etiquetas, la operación es selectiva: solo se eliminan las etiquetas indicadas y las demás se conservan. No es un reemplazo del conjunto completo.

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
`contactId`	Integer	✅ Sí	ID del contacto al que se le quitarán las etiquetas.

Cuerpo de la solicitud

Atributo	Tipo	Obligatorio	Descripción
`label_ids`	Array de Integer	✅ Sí	IDs de etiquetas a quitar (mínimo 1, sin repetidos).

Ejemplo de solicitud

http

PUT /api/v1/contacts/73/labels

json

{
  "label_ids": [45]
}

Respuesta

Respuesta exitosa 200

json

{
  "message": "Etiquetas quitadas del contacto correctamente",
  "data": [
    {
      "id": 12,
      "title": "Frecuente",
      "description": null,
      "bg_color": "#0d6efd",
      "text_color": "#ffffff"
    }
  ]
}

Definición de atributos

Campo	Tipo	Descripción
`message`	String	Mensaje de respuesta del servidor.
`data`	Array	Etiquetas que le quedan al contacto después de quitar.
`data.id`	Integer	Identificador único de la etiqueta.
`data.title`	String	Título de la etiqueta.
`data.description`	String	Descripción de la etiqueta.
`data.bg_color`	String	Color de fondo de la etiqueta en formato hexadecimal.
`data.text_color`	String	Color del texto de la etiqueta en formato hexadecimal.

Errores de validación

label_ids vacío o ausente → "Debe indicar al menos una etiqueta."
Alguna etiqueta enviada no existe → "Etiqueta no encontrada."
Alguna etiqueta enviada no está asignada al contacto → "La etiqueta no está asignada al contacto."

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.

Etiquetas de contacto ​

Listar etiquetas ​

Ejemplo de solicitud ​

Respuesta ​

Errores de validación ​

Agregar etiquetas a un contacto ​

Ejemplo de solicitud ​

Respuesta ​

Errores de validación ​

Quitar etiquetas de un contacto ​

Ejemplo de solicitud ​

Respuesta ​

Errores de validación ​

Errores generales ​

Etiquetas de contacto

Listar etiquetas

Ejemplo de solicitud

Respuesta

Errores de validación

Agregar etiquetas a un contacto

Ejemplo de solicitud

Respuesta

Errores de validación

Quitar etiquetas de un contacto

Ejemplo de solicitud

Respuesta

Errores de validación

Errores generales