Mercately Retailers API (1.0.0)

Download OpenAPI specification:Download

E-mail: support@mercately.com URL: http://mercately.com/ License: MIT Terms of Service

Introduction

La plataforma para desarrolladores de Mercately, está creada para ayudar a todos nuestros clientes y empoderarlos para que crezcan mejor. Nuestras API están diseñadas para permitir que los equipos de cualquier forma o tamaño construyan integraciones y aprovechar al máximo Mercately. Todas las API de Mercately se construyen usando convenciones REST y están diseñadas para tener una estructura de URL predecible. U tilizan muchas funciones HTTP estándar, incluidos métodos (POST, GET, PUT, DELETE) y códigos de respuesta de error.

Agents

En Mercately, los agentes son conocidos como las personas que están en tu equipo de trabajo. Los agentes pueden estar atados a varios otros objetos como conversaciones, notas, tratos del embudo u órdenes. Este endpoint te devolverá datos necesarios del agente a ser usados en otros endpoints.

Agents

Obtén los datos de tus agentes

Securityapi-key

Responses

200

400

Unauthorized

get/retailers/api/v1/agents

Request samples

Response samples

application/json

{"agents": [{"id": 9,
"first_name": "Nicolas",
"last_name": "Mena Garzon",
"email": "nicolas@mercately.com",
"active": true,
"agent": false,
"admin": true,
"supervisor": true
}
]
}

Customers

En Mercately, todo contacto proveniente de conversaciones, compras o creados directamente se clasifica como cliente. Este endpoint proporciona y permite la actualización de datos del cliente.

Customers

Obtén los datos de todos tus clientes

Securityapi-key

Request

query Parameters

page	number busca la pagina específica de clientes
start_date	string <date> Fecha inicial de búsqueda en formato YYYY-MM-DD
end_date	string <date> Fecha final de búsqueda en formato YYYY-MM-DD
id_type	any especifica el tipo de documento a buscar Enum: "cedula" "pasaporte" "ruc" "rut" "otro"
id_number	string Número de documento a buscar

Responses

200

400

Unauthorized

get/retailers/api/v1/customers

Request samples

Response samples

application/json

{"results": 1,
"total_pages": 1,
"customers": [{"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}
]
}

Create Customers

Crea un nuevo cliente

Securityapi-key

Request

Request Body schema: application/json

first_name	string
last_name	string
email	string
phone	string
id_type	string Enum: "cedula" "pasaporte" "ruc" "rut" "otro"
id_number	string
address	string
city	string
state	string
zip_code	string
notes	string
agent_id	integer
	Array of objects
	Array of objects
outbound_status	string Enum: "error" "submitted" "enqueued" "sent" "delivered" "read"
campaign_id	integer
campaign_url	string
error_message	string
creation_date	string <date>
sent_at	string <date>
delivered_at	string <date>
read_at	string <date>

Responses

200

400

Unauthorized

post/retailers/api/v1/customers

Request samples

application/json

{"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}

Response samples

application/json

{"message": "Customer created successfully",
"customer": {"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}
}

Customer/:id

Obtén los datos de un cliente en especifico buscado por ID

Securityapi-key

Responses

200

400

Unauthorized

404

Not found

get/retailers/api/v1/customers/:id

Request samples

Response samples

application/json

{"message": "Customer found successfully",
"customer": {"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}
}

Customer/:email

Obtén los datos de un cliente en especifico buscado por email

Securityapi-key

Responses

200

400

Unauthorized

404

Not found

get/retailers/api/v1/customers/:email

Request samples

Response samples

application/json

{"message": "Customer found successfully",
"customer": {"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}
}

Customer/:phone

Obtén los datos de un cliente en especifico buscado por phone

Securityapi-key

Responses

200

400

Unauthorized

404

Not found

get/retailers/api/v1/customers/:phone

Request samples

Response samples

application/json

{"message": "Customer found successfully",
"customer": {"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}
}

Update Customer by email, id or phone

Actualiza un nuevo customer buscado por email, id o phone. Puedes realizar la busqueda igual que los métodos get

Securityapi-key

Request

Request Body schema: application/json

first_name	string
last_name	string
email	string
phone	string
id_type	string Enum: "cedula" "pasaporte" "ruc" "rut" "otro"
id_number	string
address	string
city	string
state	string
zip_code	string
notes	string
agent_id	integer
	Array of objects
	Array of objects
outbound_status	string Enum: "error" "submitted" "enqueued" "sent" "delivered" "read"
campaign_id	integer
campaign_url	string
error_message	string
creation_date	string <date>
sent_at	string <date>
delivered_at	string <date>
read_at	string <date>

Responses

200

400

Unauthorized

put/retailers/api/v1/customers/:phone

Request samples

application/json

{"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}

Response samples

application/json

{"message": "Customer updated successfully",
"customer": {"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"id_type": "cedula",
"id_number": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"field_name": "string",
"field_content": "string"
}
],
"outbound_status": "error",
"campaign_id": 0,
"campaign_url": "string",
"error_message": "string",
"creation_date": "2019-08-24",
"sent_at": "2019-08-24",
"delivered_at": "2019-08-24",
"read_at": "2019-08-24"
}
}

Deals

En Mercately, los embudos permiten visualizar el recorrido que sigues a tus clientes a traves de las negociaciones. Este endpoint proporciona y permite el manejo de datos de las negociaciones en los diferentes embundos.

deals

Obtén la lista de negociaciones

Securityapi-key

Request

query Parameters

funnel_name required	string Nombre del embudo Example: funnel_name=Negociaciones
stage required	string Nombre de la etapa Example: stage=Calificado
page	integer número de pagina Example: page=1

Responses

200

404

not found

get/retailers/api/v1/deals

Request samples

Response samples

application/json

{"total": 2,
"total_page": 1,
"deals": [{"id": "9fb882221",
"name": "Neptu",
"amount": "150000.0",
"currency": "$",
"funnel_name": "Negociaciones",
"stage": "Calificado!",
"agent": {"id": 9,
"first_name": "Nicolas",
"last_name": "Mena Garzon",
"email": "nicolas@mercately.com",
"active": true,
"agent": false,
"admin": true,
"supervisor": true
},
"customer": {"id": "91989a87",
"first_name": "javier",
"last_name": "Salinas",
"email": "javier@example.com",
"phone": 5933505692996
},
"channel": "string"
}
]
}

deals

Crea una nueva negociación

Securityapi-key

Request

Request Body schema: application/json
required

funnel_name required	string
stage required	string
required	object

Responses

200

422

No se pudo procesar el recurso

post/retailers/api/v1/deals

Request samples

application/json

{"funnel_name": "Negociaciones",
"stage": "Calificado",
"deal": {"amount": "150000",
"name": "string",
"customer_id": "91989a87",
"agent_id": 0,
"lead_status": "cold",
"opening_date": "2024-05-16",
"expected_close_date": "2024-05-23"
}
}

Response samples

application/json

{"message": "deal was created successfully",
"deal": {"id": "9fb882221",
"name": "Neptu",
"amount": "150000.0",
"currency": "$",
"funnel_name": "Negociaciones",
"stage": "Calificado!",
"agent": {"id": 9,
"first_name": "Nicolas",
"last_name": "Mena Garzon",
"email": "nicolas@mercately.com",
"active": true,
"agent": false,
"admin": true,
"supervisor": true
},
"customer": {"id": "91989a87",
"first_name": "javier",
"last_name": "Salinas",
"email": "javier@example.com",
"phone": 5933505692996
},
"channel": "string"
}
}

deals/:id

Obtén una negociacion

Securityapi-key

Request

path Parameters

required

string

ID de la negociación

Responses

200

404

La negociación no existe

get/retailers/api/v1/deals/{id}

Request samples

Response samples

application/json

{"message": "deal found successfully",
"deal": {"id": "9fb882221",
"name": "Neptu",
"amount": "150000.0",
"currency": "$",
"funnel_name": "Negociaciones",
"stage": "Calificado!",
"agent": {"id": 9,
"first_name": "Nicolas",
"last_name": "Mena Garzon",
"email": "nicolas@mercately.com",
"active": true,
"agent": false,
"admin": true,
"supervisor": true
},
"customer": {"id": "91989a87",
"first_name": "javier",
"last_name": "Salinas",
"email": "javier@example.com",
"phone": 5933505692996
},
"channel": "string"
}
}

deals/:id

Actualiza una negociación

Securityapi-key

Request

path Parameters

required

string

ID de la negociación

Example: 9c6d04017

Request Body schema: application/json
required

funnel_name required	string
stage required	string
required	object

Responses

200

404

La negociación no existe

422

No se pudo procesar el recurso

put/retailers/api/v1/deals/{id}

Request samples

application/json

{"funnel_name": "Negociaciones",
"stage": "Calificado",
"deal": {"amount": "150000",
"name": "Ricardo - pavo",
"customer_id": "91989a87",
"lead_status": "cold",
"opening_date": "2024-05-16",
"expected_close_date": "2024-05-23",
"funnel_name": "Negociaciones",
"stage": "Calificado"
}
}

Response samples

application/json

{"message": "deal was updated successfully",
"deal": {"id": "9fb882221",
"name": "Neptu",
"amount": "150000.0",
"currency": "$",
"funnel_name": "Negociaciones",
"stage": "Calificado!",
"agent": {"id": 9,
"first_name": "Nicolas",
"last_name": "Mena Garzon",
"email": "nicolas@mercately.com",
"active": true,
"agent": false,
"admin": true,
"supervisor": true
},
"customer": {"id": "91989a87",
"first_name": "javier",
"last_name": "Salinas",
"email": "javier@example.com",
"phone": 5933505692996
},
"channel": "string"
}
}

deals/:id

Elimina una negociación

Securityapi-key

Request

path Parameters

required

string

ID de la negociación

Example: 93390836

Responses

200

404

negociación no existe

422

Error al procesar el recurso

delete/retailers/api/v1/deals/{id}

Request samples

Response samples

application/json

{"message": "deal was deleted successfully"
}

Messenger

En Mercately, una vez vinculado con Messenger, este api permite realizar múltiples operaciones para acceder a las conversaciones de Messenger.

Messenger conversations

Obtén los clients que te han escrito por messenger

Securityapi-key

Request

Request Body schema: application/json

page	number
results_per_page	number
unassigned	boolean

Responses

200

400

Unauthorized

get/retailers/api/v1/messenger_conversations

Request samples

application/json

{"page": 0,
"results_per_page": 0,
"unassigned": true
}

Response samples

application/json

{"results": 155,
"total_pages": 2,
"messenger_conversations": [{"id": "621osgzy4696283",
"first_name": "Claudia",
"last_name": "Funnel",
"email": null,
"message_count": 3,
"last_interaction": "2023-04-17T05:08:17.085Z",
"agent_id": 4637
}
]
}

En Mercately, una vez vinculado con WhatsApp, este api permite realizar múltiples operaciones para acceder a las conversaciones de WhatsApp y enviar mensajes.

Whatsapp conversations

Obtén los clients que te han escrito por whatsapp

Securityapi-key

Request

Request Body schema: application/json

page	number
results_per_page	number
unassigned	boolean

Responses

200

400

Unauthorized

get/retailers/api/v1/whatsapp_conversations

Request samples

application/json

{"page": 0,
"results_per_page": 0,
"unassigned": true
}

Response samples

application/json

{"results": 155,
"total_pages": 2,
"messenger_conversations": {"id": "621osgzy4696283",
"first_name": "Claudia",
"last_name": "Funnel",
"email": null,
"message_count": 3,
"last_interaction": "2023-04-17T05:08:17.085Z",
"agent_id": 4637
}
}

WhatsApp Business Api Templates

Obtén los templates/plantillas creadas en WhatsApp Business API

Securityapi-key

Request

Request Body schema: application/json

object (WhatsApp Business Api templates)

Responses

200

400

Unauthorized

get/retailers/api/v1/whatsapp_templates

Request samples

application/json

{ }

Response samples

application/json

{"templates": [{"text": "Hola *! ✋",
"status": "accepted",
"template_type": "text",
"internal_id": "c0c040f6-9809-404a-961c-637b109ef410"
}
]
}

Send WhatsApp Message for WhatsApp Business API

Para enviar un mensaje de WhatsApp cuando se tiene una conexión oficial al API de WhatsApp, sólo se requieren los parámetros phone_number, internal_id y template_params; los demás son opcionales. Si se tiene una conexión vía QR, por favor revisa la sección de envío de mensajes vía QR.

Securityapi-key

Request

Request Body schema: application/json

phone_number	string
internal_id	string
template_params	Array of strings
media_url	string
first_name	string
last_name	string
email	string
address	string
city	string
state	string
zip_code	string
notes	string
agent_id	number
funnel_name	string
stage	string
	Array of objects
	Array of objects

Responses

200

400

Unauthorized

post/retailers/api/v1/whatsapp/send_notification_by_id

Request samples

application/json

{"phone_number": "string",
"internal_id": "string",
"template_params": ["string"
],
"media_url": "string",
"first_name": "string",
"last_name": "string",
"email": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"funnel_name": "string",
"stage": "string",
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"identifier": "string",
"value": "string"
}
]
}

Response samples

application/json

{"message": "Ok",
"info": {"channel": "whatsapp",
"content": {"text": "Hola Juan! ✋"
},
"direction": "outbound",
"status": "submitted",
"destination": "593999999999",
"country": "EC",
"created_time": "2022-09-23T16:34:16.768-04:00",
"error": null
}
}

Send WhatsApp Message for WhatsApp Business QR

Enviar un mensaje de WhatsApp cuando tienes una conexión oficial por QR. Los únicos parametros requeridos son phone_number y message, el resto de parámetros son opcionales.

Securityapi-key

Request

Request Body schema: application/json

phone_number	string
message	string
media_url	string
first_name	string
last_name	string
email	string
address	string
city	string
state	string
zip_code	string
notes	string
agent_id	number
funnel_name	string
stage	string
	Array of objects
	Array of objects

Responses

200

400

Unauthorized

post/retailers/api/v1/whatsapp/send_message

Request samples

application/json

{"phone_number": "string",
"message": "string",
"media_url": "string",
"first_name": "string",
"last_name": "string",
"email": "string",
"address": "string",
"city": "string",
"state": "string",
"zip_code": "string",
"notes": "string",
"agent_id": 0,
"funnel_name": "string",
"stage": "string",
"tags": [{"name": "string",
"value": true
}
],
"custom_fields": [{"identifier": "string",
"value": "string"
}
]
}

Response samples

application/json

{"message": "Ok",
"info": {"channel": "whatsapp",
"content": {"text": "Hola Juan! ✋"
},
"direction": "outbound",
"status": "submitted",
"destination": "593999999999",
"country": "EC",
"created_time": "2022-09-23T16:34:16.768-04:00",
"error": null
}
}

Flows

En Mercately, una vez creado uno o más flows, esta api permite realizar múltiples operaciones para obtener todos los flows que tengas creados, desactivar flows activos por plataforma y pre-activar flows específicos para un customer específico por plataforma.

Get all flows

Obtén todos los flows

Securityapi-key

Request

query Parameters

page	number Busca la página específica de flows
results_per_page	number Selecciona el número de flows que serán visualizados por página

Responses

200

401

Unauthorized

404

Not found

get/retailers/api/v1/flows

Request samples

Response samples

application/json

{"results": 1,
"total_pages": 1,
"flows": [{"id": "string",
"name": "string",
"version": 2,
"enabled": true,
"whatsapp": true,
"messenger": true,
"instagram": true
}
]
}

Deactivate flows by platform

Desactiva todos los flows que estén previamente activos por customer y plataforma específica

Securityapi-key

Request

Request Body schema: application/json
required

customer_id required	string Id del customer(Opcional, siempre y cuando se busque por customer_phone)
customer_phone required	string Teléfono del customer(Opcional, siempre y cuando se busque por customer_id)
platform required	string Plataforma sobre la cual se realizará la búsqueda para pre-activar un flow específico para el customer. Sólo se permiten los valores de 'whatsapp', 'messenger' o 'instagram'

Responses

200

400

Bad Request

401

Unauthorized

404

Not Found

post/retailers/api/v1/flow_deactivation

Request samples

application/json

{"customer_id": "d126hhh",
"customer_phone": "+573201548587",
"platform": "whatsapp"
}

Response samples

application/json

{"message": "Flows by platform successfully deactivated",
"info": [ ]
}

Pre-activate flow by platform

Pre-activa un flow en específico para un customer y plataforma específica, siempre y cuando el flow esté activo, tenga un paso inicial configurado y la plataforma para dicho flow esté activa. Esta operación solo está habilitada para flows con versión 2. Si deseas usar un flow con versión 1, debes hacer upgrade del mismo.

Securityapi-key

Request

Request Body schema: application/json
required

customer_id required	string Id del customer(Opcional, siempre y cuando se busque por customer_phone)
customer_phone required	string Teléfono del customer(Opcional, siempre y cuando se busque por customer_id)
flow_id required	string Id del flow
platform required	string Plataforma sobre la cual se realizará la búsqueda para pre-activar un flow específico para el customer. Sólo se permiten los valores de 'whatsapp', 'messenger' o 'instagram'

Responses

200

400

Bad Request

401

Unauthorized

404

Not Found

post/retailers/api/v1/flow_pre_activation

Request samples

application/json

{"customer_id": "d126hhh",
"customer_phone": "+573201548587",
"flow_id": "d82ijd8",
"platform": "whatsapp"
}

Response samples

application/json

{"message": "Flow successfully preactivated",
"info": [ ]
}

Customer events

Create Customer Event

Crea un nuevo evento para el cliente

Securityapi-key

Request

Request Body schema: application/json

category	string
subcategory	string
type_event	string
action	string
source	string
url_spec	string
created_at	string

Responses

201

CREATED

401

Unauthorized

post/retailers/api/v1/customers/:id/events

Request samples

application/json

{"category": "string",
"subcategory": "string",
"type_event": "string",
"action": "string",
"source": "string",
"url_spec": "string",
"created_at": "string"
}

Response samples

application/json

{"messages": "Customer event created successfully"
}

Get Customer Events

Obtiene los eventos del cliente

Securityapi-key

Request

query Parameters

page	number Busca la página específica de eventos
results_per_page	number Selecciona el número de eventos que serán visualizados por página

Responses

200

401

Unauthorized

404

Not found

get/retailers/api/v1/customers/:id/customer_events_history

Request samples

Response samples

application/json

{"results": 1,
"total_pages": 1,
"customer_events": [{"category": "string",
"subcategory": "string",
"event": "string",
"creation_date": "string",
"agent": "string"
}
]
}

Mercately Retailers API (1.0.0)

Introduction

Agents

Agents

Customers

Customers

query Parameters

Create Customers

Request Body schema: application/json

Customer/:id

Customer/:email

Customer/:phone

Update Customer by email, id or phone

Request Body schema: application/json

Deals

deals

query Parameters

deals

Request Body schema: application/jsonrequired

deals/:id

path Parameters

deals/:id

path Parameters

Request Body schema: application/jsonrequired

deals/:id

path Parameters

Messenger

Messenger conversations

Request Body schema: application/json

WhatsApp

Whatsapp conversations

Request Body schema: application/json

WhatsApp Business Api Templates

Request Body schema: application/json

Send WhatsApp Message for WhatsApp Business API

Request Body schema: application/json

Send WhatsApp Message for WhatsApp Business QR

Request Body schema: application/json

Flows

Get all flows

query Parameters

Deactivate flows by platform

Request Body schema: application/jsonrequired

Pre-activate flow by platform

Request Body schema: application/jsonrequired

Customer events

Create Customer Event

Request Body schema: application/json

Get Customer Events

query Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required