Skip to content

Mercately Retailers API (1.0.0)

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.

Download OpenAPI description
index.json
index.yaml
Overview
URL
http://mercately.com/
E-mail
soporte@mercately.com
License
MIT
Terms of Service
Languages
Servers
Production server
https://app.mercately.com/
Shops API Production server
https://mercately.shop/

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.

Operations

Customers

En Mercately, todo contacto proveniente de conversaciones, compras o creados directamente se clasifica como cliente.

Operations

Customers

Request

Obtén los datos de tus clientes

Security
api-key
Query
pagenumber

Busca la página específica de clientes

Example: page=1
start_datestring(date)

Fecha inicial de búsqueda en formato YYYY-MM-DD

Example: start_date=2024-01-01
end_datestring(date)

Fecha final de búsqueda en formato YYYY-MM-DD

Example: end_date=2024-12-31
id_typestring

Especifica el tipo de documento a buscar

Enum"cedula""pasaporte""ruc""rut""otro"
id_numberstring

Número de documento a buscar

Example: id_number=1234567890
platformstring

Plataforma de interacción

Enum"whatsapp""messenger""instagram"
order_by_last_interactionstring

Ordena los clientes por la última interacción según la plataforma

Enum"asc""desc"
curl -i -X GET \
  'https://app.mercately.com/retailers/api/v1/customers?page=1&start_date=2024-01-01&end_date=2024-12-31&id_type=cedula&id_number=1234567890&platform=whatsapp&order_by_last_interaction=asc' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
resultsinteger

Número total de resultados

Example: 1
total_pagesinteger

Número total de páginas

Example: 1
customersArray of objects

Lista de clientes

Response
application/json
{
  "results": 1,
  "total_pages": 1,
  "customers": [
    { … }
  ]
}

Create Customers

Request

Crea un nuevo cliente

Security
api-key
Bodyapplication/jsonrequired
customerobject

Datos del cliente

agent_idinteger

ID del agente asignado al cliente (puede estar en nivel raíz o dentro de customer)

Example: 1
tagsArray of objects

Array de etiquetas del cliente (puede estar en nivel raíz o dentro de customer)

custom_fieldsArray of objects

Array de campos personalizados del cliente (puede estar en nivel raíz o dentro de customer)

curl -i -X POST \
  https://app.mercately.com/retailers/api/v1/customers \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "customer": {
      "first_name": "Juan",
      "last_name": "Pérez",
      "email": "juan@example.com",
      "phone": "+593999999999",
      "id_type": "cedula",
      "id_number": "1234567890",
      "address": "Av. Principal 123",
      "city": "Quito",
      "state": "Pichincha",
      "zip_code": "170101",
      "customer_addresses_attributes": [
        {
          "address": "Calle Secundaria 456",
          "city": "Guayaquil",
          "state": "Guayas",
          "zip_code": "090101",
          "country_id": 1,
          "latitude": "-2.1894",
          "longitude": "-79.8891",
          "description": "Oficina principal",
          "main": true
        }
      ],
      "notes": "Cliente VIP"
    },
    "agent_id": 1,
    "tags": [
      {
        "name": "VIP",
        "value": true
      }
    ],
    "custom_fields": [
      {
        "field_name": "preferencia_contacto",
        "field_content": "WhatsApp"
      }
    ]
  }'

Responses

OK - Cliente creado con éxito

Bodyapplication/json
messagestring
Example: "Customer created successfully"
customerobject
Response
application/json
{
  "message": "Customer created successfully",
  "customer": {
    "id": 12345,
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@example.com",
    "phone": "+593999999999",
    "id_type": "cedula",
    "id_number": "1234567890",
    "address": "Av. Principal 123",
    "city": "Quito",
    "state": "Pichincha",
    "zip_code": "170101",
    "notes": "Cliente VIP",
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

Customer/:id

Request

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

Security
api-key
curl -i -X GET \
  https://app.mercately.com/retailers/api/v1/customers/:id \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring

ID único del cliente (web_id)

first_namestring
last_namestring
emailstring
phonestring
id_typestring
Enum"cedula""pasaporte""ruc""rut""otro"
id_numberstring
addressstring

Dirección individual del cliente

citystring

Ciudad individual del cliente

statestring

Estado/Provincia individual del cliente

zip_codestring

Código postal individual del cliente

country_idstring

ID del país del cliente

notesstring
whatsapp_opt_inboolean

Si el cliente ha optado por recibir mensajes de WhatsApp

whatsapp_namestring

Nombre del cliente en WhatsApp

customer_addressesArray of objects

Array de direcciones adicionales del cliente

tagsArray of objects

Array de etiquetas del cliente

custom_fieldsArray of objects

Array de campos personalizados del cliente

agentobject

Agente asignado al cliente

outbound_statusstring

Estado del último mensaje outbound enviado al cliente

Enum"error""submitted""enqueued""sent""delivered""read"
campaign_idinteger

ID de la campaña asociada al cliente

error_messagestring

Mensaje de error si hubo un problema con el último mensaje enviado

campaign_urlstring

URL de la campaña asociada (vacío si no hay campaña)

creation_datestring(date-time)

Fecha de creación del cliente

sent_atstring(date-time)

Fecha en que se envió el último mensaje outbound

delivered_atstring(date-time)

Fecha en que se entregó el último mensaje outbound

read_atstring(date-time)

Fecha en que se leyó el último mensaje outbound

last_chat_interactionstring(date-time)

Fecha de la última interacción en el chat

Response
application/json
{
  "id": "string",
  "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",
  "country_id": "string",
  "notes": "string",
  "whatsapp_opt_in": true,
  "whatsapp_name": "string",
  "customer_addresses": [
    { … }
  ],
  "tags": [
    { … }
  ],
  "custom_fields": [
    { … }
  ],
  "agent": {
    "id": 0,
    "email": "string"
  },
  "outbound_status": "error",
  "campaign_id": 0,
  "error_message": "string",
  "campaign_url": "string",
  "creation_date": "2019-08-24T14:15:22Z",
  "sent_at": "2019-08-24T14:15:22Z",
  "delivered_at": "2019-08-24T14:15:22Z",
  "read_at": "2019-08-24T14:15:22Z",
  "last_chat_interaction": "2019-08-24T14:15:22Z"
}

Customer/:email

Request

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

Security
api-key
curl -i -X GET \
  https://app.mercately.com/retailers/api/v1/customers/:email \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
messagestring
Example: "Customer found successfully"
customerobject(customer)
Response
application/json
{
  "message": "Customer found successfully",
  "customer": {
    "id": "string",
    "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",
    "country_id": "string",
    "notes": "string",
    "whatsapp_opt_in": true,
    "whatsapp_name": "string",
    "customer_addresses": [ … ],
    "tags": [ … ],
    "custom_fields": [ … ],
    "agent": { … },
    "outbound_status": "error",
    "campaign_id": 0,
    "error_message": "string",
    "campaign_url": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "sent_at": "2019-08-24T14:15:22Z",
    "delivered_at": "2019-08-24T14:15:22Z",
    "read_at": "2019-08-24T14:15:22Z",
    "last_chat_interaction": "2019-08-24T14:15:22Z"
  }
}

Customer/:phone

Request

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

Security
api-key
curl -i -X GET \
  https://app.mercately.com/retailers/api/v1/customers/:phone \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
messagestring
Example: "Customer found successfully"
customerobject(customer)
Response
application/json
{
  "message": "Customer found successfully",
  "customer": {
    "id": "string",
    "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",
    "country_id": "string",
    "notes": "string",
    "whatsapp_opt_in": true,
    "whatsapp_name": "string",
    "customer_addresses": [ … ],
    "tags": [ … ],
    "custom_fields": [ … ],
    "agent": { … },
    "outbound_status": "error",
    "campaign_id": 0,
    "error_message": "string",
    "campaign_url": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "sent_at": "2019-08-24T14:15:22Z",
    "delivered_at": "2019-08-24T14:15:22Z",
    "read_at": "2019-08-24T14:15:22Z",
    "last_chat_interaction": "2019-08-24T14:15:22Z"
  }
}

Update Customer by email, id or phone

Request

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

Security
api-key
Bodyapplication/json
customerobject(Customer)
agent_idinteger

ID del agente asignado al cliente (puede estar en nivel raíz o dentro de customer)

tagsArray of objects

Array de etiquetas del cliente (puede estar en nivel raíz o dentro de customer)

custom_fieldsArray of objects

Array de campos personalizados del cliente (puede estar en nivel raíz o dentro de customer)

curl -i -X PUT \
  https://app.mercately.com/retailers/api/v1/customers/:phone \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "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",
      "customer_addresses_attributes": [
        {
          "address": "string",
          "city": "string",
          "state": "string",
          "zip_code": "string",
          "country_id": 0,
          "latitude": "string",
          "longitude": "string",
          "description": "string",
          "main": true
        }
      ],
      "notes": "string"
    },
    "agent_id": 0,
    "tags": [
      {
        "name": "string",
        "value": true
      }
    ],
    "custom_fields": [
      {
        "field_name": "string",
        "field_content": "string"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
messagestring

Mensaje de confirmación

Example: "Customer updated successfully"
customerobject(Customer)
Response
application/json
{
  "message": "Customer updated successfully",
  "customer": {
    "id": "string",
    "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",
    "country_id": "string",
    "notes": "string",
    "whatsapp_opt_in": true,
    "whatsapp_name": "string",
    "customer_addresses": [ … ],
    "tags": [ … ],
    "custom_fields": [ … ],
    "agent": { … },
    "outbound_status": "error",
    "campaign_id": 0,
    "error_message": "string",
    "campaign_url": "string",
    "creation_date": "2019-08-24T14:15:22Z",
    "sent_at": "2019-08-24T14:15:22Z",
    "delivered_at": "2019-08-24T14:15:22Z",
    "read_at": "2019-08-24T14:15:22Z",
    "last_chat_interaction": "2019-08-24T14:15:22Z"
  }
}

Customer/:id/whatsapp_conversations

Request

Obtén la conversación de Whatsapp del cliente por ID

Security
api-key
Query
pagenumber

Busca la página específica de conversaciónes

results_per_pagenumber

Selecciona el número de mensajes que serán visualizados por página

curl -i -X GET \
  'https://app.mercately.com/retailers/api/v1/customers/:id/whatsapp_conversations?page=0&results_per_page=0' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
whatsapp_conversationsArray of objects(whatsapp_api_message)
total_pagesinteger
Example: 1
Response
application/json
{
  "whatsapp_conversations": [
    { … }
  ],
  "total_pages": 1
}

Customer/:phone/whatsapp_conversations

Request

Obtén la conversación de Whatsapp del cliente por número de teléfono

Security
api-key
Query
pagenumber

Busca la página específica de conversaciónes

results_per_pagenumber

Selecciona el número de mensajes que serán visualizados por página

curl -i -X GET \
  'https://app.mercately.com/retailers/api/v1/customers/:phone/whatsapp_conversations?page=0&results_per_page=0' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
whatsapp_conversationsArray of objects(whatsapp_api_message)
total_pagesinteger
Example: 1
Response
application/json
{
  "whatsapp_conversations": [
    { … }
  ],
  "total_pages": 1
}

Customer/:id/messenger_conversations

Request

Obtén la conversación de Messenger del cliente

Security
api-key
Query
pagenumber

Busca la página específica de conversaciónes

results_per_pagenumber

Selecciona el número de mensajes que serán visualizados por página

curl -i -X GET \
  'https://app.mercately.com/retailers/api/v1/customers/:id/messenger_conversations?page=0&results_per_page=0' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
messenger_conversationsArray of objects(messenger_message)
total_pagesinteger
Example: 1
Response
application/json
{
  "messenger_conversations": [
    { … }
  ],
  "total_pages": 1
}

Customer/:id/instagram_conversations

Request

Obtén la conversación de Instagram del cliente

Security
api-key
Query
pagenumber

Busca la página específica de conversaciónes

results_per_pagenumber

Selecciona el número de mensajes que serán visualizados por página

curl -i -X GET \
  'https://app.mercately.com/retailers/api/v1/customers/:id/instagram_conversations?page=0&results_per_page=0' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
instagram_messagesArray of objects(messenger_message)
total_pagesinteger
Example: 1
Response
application/json
{
  "instagram_messages": [
    { … }
  ],
  "total_pages": 1
}

Deals

En Mercately, los embudos permiten visualizar el recorrido que sigues a tus clientes a traves de las negociaciones.

Operations

Messenger

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

Operations

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.

Operations

Flows

En Mercately, una vez creado uno o más flows, esta api permite realizar múltiples operaciones para obtener todos los flows.

Operations

Orders

Crea, actualiza y elimina órdenes en Mercately

Operations

Products

Crea, actualiza y elimina productos en Mercately

Operations

Categories

Obtén todas las categorías creadas en Mercately

Operations

Customer events

Operations
Copyleft © Mercately Inc.