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

OK

400

Unauthorized

get/retailers/api/v1/agents

Request samples

Response samples

200

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

Responses

200

OK

400

Unauthorized

get/retailers/api/v1/customers

Request samples

Response samples

200

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"
}
],
"creation_date": "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
creation_date	string <date>

Responses

200

OK

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"
}
],
"creation_date": "2019-08-24"
}

Response samples

200

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"
}
],
"creation_date": "2019-08-24"
}
}

Customer/:id

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

Securityapi-key

Responses

200

OK

400

Unauthorized

404

Not found

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

Request samples

Response samples

200

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"
}
],
"creation_date": "2019-08-24"
}
}

Customer/:email

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

Securityapi-key

Responses

200

OK

400

Unauthorized

404

Not found

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

Request samples

Response samples

200

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"
}
],
"creation_date": "2019-08-24"
}
}

Customer/:phone

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

Securityapi-key

Responses

200

OK

400

Unauthorized

404

Not found

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

Request samples

Response samples

200

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"
}
],
"creation_date": "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
creation_date	string <date>

Responses

200

OK

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"
}
],
"creation_date": "2019-08-24"
}

Response samples

200

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"
}
],
"creation_date": "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

OK

404

not found

get/retailers/api/v1/deals

Request samples

Response samples

200
404

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

OK

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

200
422

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

id

required

string

ID de la negociación

Responses

200

OK

404

La negociación no existe

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

Request samples

Response samples

200
404

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

id

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

OK

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

200
404
422

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

id

required

string

ID de la negociación

Example: 93390836

Responses

200

OK

404

negociación no existe

422

Error al procesar el recurso

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

Request samples

Response samples

200
404
422

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

OK

400

Unauthorized

get/retailers/api/v1/messenger_conversations

Request samples

application/json

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

Response samples

200

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

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

OK

400

Unauthorized

get/retailers/api/v1/whatsapp_conversations

Request samples

application/json

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

Response samples

200

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

OK

400

Unauthorized

get/retailers/api/v1/whatsapp_templates

Request samples

application/json

{ }

Response samples

200

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

OK

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

200

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

OK

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

200

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
}
}

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

201

application/json

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

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

Customer events

Create Customer Event

Request Body schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required