Contatos — API Zyron Connect Suite

Primeros pasos

Módulo

Contactos

Registra, consulta y mueve contactos dentro del embudo del CRM.

GET/contacts/contacts GET/contacts/:id/contacts/:id POST/contacts/contacts PATCH/contacts/:id/contacts/:id

GET/contactsAlcance: readOficial + Básico

Lista contactos de la cuenta autenticada.

Úsalo para alimentar CRMs externos, sincronizar bases y buscar contactos por etapa.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`stage_id`opcional	uuid	Filtra contactos por una etapa del embudo.
`connection_id`opcional	uuid	Filtra por la conexión WhatsApp dueña de la identidad.
`phone`opcional	string	Filtra por teléfono con código de país (solo dígitos).
`username`opcional	string	Filtra por el identificador externo persistido.
`business_scoped_user_id`opcional	string	Filtra por la identidad BSUID de Meta.
`parent_business_scoped_user_id`opcional	string	Filtra por el parent BSUID de Meta.
`limit`opcional	number	Cantidad de registros por página. Predeterminado 50; máximo 200 en la mayoría de listas.
`offset`opcional	number	Índice inicial de la página. Usa pagination.next_offset para la siguiente página.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Lista devuelta con paginación.
401	Clave ausente o inválida.
403	La clave no tiene alcance read.

Ejemplo de respuesta

{
  "data": [
    {
      "id": "<CONTACT_ID>",
      "name": "Maria Silva",
      "phone": "5511999998888",
      "username": "maria",
      "stage_id": "<STAGE_ID>",
      "created_at": "2026-06-15T12:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 134,
    "next_offset": 20
  }
}

GET/contacts/:idAlcance: readOficial + Básico

Consulta un contacto con recorrido y ventas.

Devuelve datos del contacto, sesiones de origen Signal y ventas relacionadas a sus conversaciones.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	uuid	ID del contacto.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Contacto encontrado.
404	Contacto no encontrado en esta cuenta.

Ejemplo de respuesta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Maria Silva",
    "phone": "5511999998888",
    "username": "maria",
    "stage_id": "<STAGE_ID>",
    "sessions": [
      {
        "channel": "ctwa",
        "utm_source": null,
        "utm_campaign": null,
        "ad_id": "23800000000000000",
        "ad_source_type": "ad",
        "ad_headline": "Fale com a gente",
        "ad_name": "Criativo vídeo depoimento",
        "adset_id": "23700000000000000",
        "adset_name": "Lookalike 1% — 25-45",
        "campaign_id": "23600000000000000",
        "campaign_name": "Leads — Julho",
        "landing_url": "https://sua-pagina.com/oferta"
      }
    ],
    "sales": [
      {
        "id": "91c9fd84-b47f-44ee-9b5e-4e93fc35b912",
        "status": "paid",
        "gross_cents": 19700,
        "currency": "BRL",
        "product_name": "Produto principal"
      }
    ]
  }
}

POST/contactsAlcance: writeOficial + Básico

Crea o actualiza un contacto por identidad.

Informa al menos una identidad: phone, username, business_scoped_user_id o parent_business_scoped_user_id. El teléfono se normaliza solo con dígitos. Las identidades Meta exigen connection_id. Si la identidad ya existe, la API actualiza los campos enviados.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`phone`opcional	string	Teléfono con DDI, solo números. Obligatorio si no envías otra identidad.
`connection_id`opcional	uuid	Conexión dueña de la identidad. Obligatorio con username, BSUID o parent BSUID.
`name`opcional	string	Nombre mostrado en el CRM, hasta 120 caracteres.
`username`opcional	string	Identificador externo o usuario social.
`business_scoped_user_id`opcional	string	BSUID recibido de Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID recibido de Meta.
`stage_id`opcional	uuid	Etapa inicial del embudo. Debe pertenecer a la cuenta.

Ejemplos listos

curl -X POST "https://connect.zyronstack.com/api/v1/contacts" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "phone": "5511999998888",
  "name": "Joao Silva",
  "username": "joao",
  "stage_id": "<STAGE_ID>"
}'

Respuestas

201	Contacto creado.
200	Contacto existente actualizado.
422	phone ausente o stage_id inválido.

Ejemplo de respuesta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  },
  "created": true
}

PATCH/contacts/:idAlcance: writeOficial + Básico

Actualiza datos o mueve el contacto de etapa.

Envía solo los campos que deseas cambiar. stage_id se valida contra las etapas de la cuenta. Las identidades WhatsApp también pueden completarse aquí.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	uuid	ID del contacto.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`name`opcional	string	Nuevo nombre del contacto.
`phone`opcional	string	Nuevo teléfono con DDI (solo dígitos).
`username`opcional	string	Nuevo identificador externo.
`business_scoped_user_id`opcional	string	BSUID de Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID de Meta.
`stage_id`opcional	uuid	Nueva etapa del embudo.

Ejemplos listos

curl -X PATCH "https://connect.zyronstack.com/api/v1/contacts/<CONTACT_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "stage_id": "<STAGE_ID>",
  "name": "Joao Silva"
}'

Respuestas

200	Contacto actualizado.
404	Contacto no encontrado.
422	stage_id no pertenece a la cuenta.

Ejemplo de respuesta

{
  "data": {
    "id": "<CONTACT_ID>",
    "name": "Joao Silva",
    "phone": "5511999998888",
    "username": "joao",
    "stage_id": "<STAGE_ID>",
    "created_at": "2026-06-15T12:30:00.000Z"
  }
}