# Mercately Retailers API

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.

Version: 1.0.0
License: MIT

## Servers

Production server
```
https://app.mercately.com
```

Shops API Production server
```
https://mercately.shop
```

## Security

### api-key

API Key authentication

Type: apiKey
In: header
Name: api-key

## Download OpenAPI description

[Mercately Retailers API](https://mercately.redocly.app/_bundle/apis/index.yaml)

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

### List all agents

 - [GET /retailers/api/v1/agents](https://mercately.redocly.app/apis/agents/listagents.md)

## Customers

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

### Customers

 - [GET /retailers/api/v1/customers](https://mercately.redocly.app/apis/customers/getcustomers.md): Obtén los datos de tus clientes

### Create Customers

 - [POST /retailers/api/v1/customers](https://mercately.redocly.app/apis/customers/createcustomer.md): Crea un nuevo cliente

### Customer/:id

 - [GET /retailers/api/v1/customers/:id](https://mercately.redocly.app/apis/customers/customer/:id.md): Obtén los datos de un cliente en especifico buscado por ID

### Customer/:email

 - [GET /retailers/api/v1/customers/:email](https://mercately.redocly.app/apis/customers/customer/email.md): Obtén los datos de un cliente en especifico buscado por email

### Customer/:phone

 - [GET /retailers/api/v1/customers/:phone](https://mercately.redocly.app/apis/customers/customer/phone.md): Obtén los datos de un cliente en especifico buscado por phone

### Update Customer by email, id or phone

 - [PUT /retailers/api/v1/customers/:phone](https://mercately.redocly.app/apis/customers/updatecustomer/email.md): Actualiza un nuevo customer buscado por email, id o phone. Puedes realizar la busqueda igual que los métodos get

### Customer/:id/whatsapp_conversations

 - [GET /retailers/api/v1/customers/:id/whatsapp_conversations](https://mercately.redocly.app/apis/customers/customer/id/whatsapp_conversations.md): Obtén la conversación de Whatsapp del cliente por ID

### Customer/:phone/whatsapp_conversations

 - [GET /retailers/api/v1/customers/:phone/whatsapp_conversations](https://mercately.redocly.app/apis/customers/customer/phone/whatsapp_conversations.md): Obtén la conversación de Whatsapp del cliente por número de teléfono

### Customer/:id/messenger_conversations

 - [GET /retailers/api/v1/customers/:id/messenger_conversations](https://mercately.redocly.app/apis/customers/customer/id/messenger_conversations.md): Obtén la conversación de Messenger del cliente

### Customer/:id/instagram_conversations

 - [GET /retailers/api/v1/customers/:id/instagram_conversations](https://mercately.redocly.app/apis/customers/customer/id/instagram_conversations.md): Obtén la conversación de Instagram del cliente

## Deals

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

### Obtener deals

 - [GET /retailers/api/v1/deals](https://mercately.redocly.app/apis/deals/listdeal.md): Obtén la lista de negociaciones

### Create deal

 - [POST /retailers/api/v1/deals](https://mercately.redocly.app/apis/deals/createdeal.md): Crea una nueva negociación

### deals/:id

 - [GET /retailers/api/v1/deals/{id}](https://mercately.redocly.app/apis/deals/getdeal.md): Obtén una negociacion

### deals/:id

 - [PUT /retailers/api/v1/deals/{id}](https://mercately.redocly.app/apis/deals/updatedeal.md): Actualiza una negociación

### deals/:id

 - [DELETE /retailers/api/v1/deals/{id}](https://mercately.redocly.app/apis/deals/deletedeal.md): Elimina una negociación

## Messenger

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

### Messenger conversations

 - [GET /retailers/api/v1/messenger_conversations](https://mercately.redocly.app/apis/messenger/messengerclients.md): Obtén los clients que te han escrito por messenger

## 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 Business Api Templates

 - [GET /retailers/api/v1/whatsapp_templates](https://mercately.redocly.app/apis/whatsapp/whatsapptemplates.md): Obtén los templates/plantillas creadas en WhatsApp Business API

### Send WhatsApp Message for WhatsApp Business API

 - [POST /retailers/api/v1/whatsapp/send_notification_by_id](https://mercately.redocly.app/apis/whatsapp/sendwhatsappapi.md): 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.

### Send WhatsApp Message for WhatsApp Business QR

 - [POST /retailers/api/v1/whatsapp/send_message](https://mercately.redocly.app/apis/whatsapp/sendwhatsappqr.md): 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.

## Flows

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

### Get all flows

 - [GET /retailers/api/v1/flows](https://mercately.redocly.app/apis/flows/flows.md): Obtén todos los flows

### Deactivate flows by platform

 - [POST /retailers/api/v1/flow_deactivation](https://mercately.redocly.app/apis/flows/flow_deactivation.md): Desactiva todos los flows que estén previamente activos por customer y plataforma específica

### Pre-activate flow by platform

 - [POST /retailers/api/v1/flow_pre_activation](https://mercately.redocly.app/apis/flows/flow_pre_activation.md): 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.

## Orders

Crea, actualiza y elimina órdenes en Mercately

### Orders

 - [GET /api/v1/orders](https://mercately.redocly.app/apis/orders/orders.md): Obtén los datos de tus órdenes

### Create Order

 - [POST /api/v1/orders](https://mercately.redocly.app/apis/orders/createorder.md): Crea una nueva órden, puedes enviar el número de teléfono o email del cliente si ya esta creado en mercately, si no existe, creará el cliente.

### Order

 - [PUT /api/v1/orders/web_id](https://mercately.redocly.app/apis/orders/updateorder.md): Actualiza una órden buscada su id

### Orders

 - [DELETE /api/v1/orders/web_id](https://mercately.redocly.app/apis/orders/deleteorder.md): Borra una órden

## Products

Crea, actualiza y elimina productos en Mercately

### Products

 - [GET /api/v1/products](https://mercately.redocly.app/apis/products/products.md): Obtén los datos de tus productos

### Create Product

 - [POST /api/v1/products](https://mercately.redocly.app/apis/products/paths/~1api~1v1~1products/post.md): Crea un nuevo producto.  
Envía máximo 3 opciones.  

Ejemplo de options:
"options": [
  { "name": "Talla", "values": ["SM", "LG", "XL", "MD"] },
  { "name": "Color", "values": ["Red", "Blue"] }
]
    Para las variantes, combina los valores de las opciones.

Ejemplo de variants:
"variants": [
  { "price": 12, "wholesale_price": 10, "sku": "VAR-001", "option1": "SM", "option2": "Red" },
  { "price": 14, "wholesale_price": 10, "sku": "VAR-002", "option1": "LG", "option2": "Red" },
  { "price": 25, "wholesale_price": 13, "sku": "VAR-003", "option1": "XL", "option2": "Blue" }
]
  operationId: createProduct

### Product

 - [GET /api/v1/products/:id_or_sku](https://mercately.redocly.app/apis/products/searchproduct.md): Obtén los datos de un producto en especifico buscado su id

### Product

 - [PUT /api/v1/products/web_id](https://mercately.redocly.app/apis/products/paths/~1api~1v1~1products~1web_id/put.md): Actualiza un producto buscado su id.  
Envía máximo 3 opciones.

### Comportamiento de actualización parcial

Este endpoint soporta actualizaciones parciales (partial updates):

- Si no envías los keys "options" ni "variants", las variantes existentes se preservan.
- Si envías "options": [] o "variants": [], las variantes existentes también se preservan (no se eliminan por omisión).
- Si envías nuevas opciones o variantes, estas se agregan a las existentes sin eliminar las anteriores.

### Ejemplos

Actualizar solo precio y título (preserva variantes):

{
  "product": {
    "title": "Nuevo título",
    "price": 29.99
  }
}
    Agregar nueva opción sin eliminar existentes:
{
  "product": {
    "options": [
      { "name": "Material", "values": ["Algodón", "Poliéster"] }
    ]
  }
}
    Ejemplo completo de options:
"options": [
  { "name": "Talla", "values": ["SM", "LG", "XL", "MD"] },
  { "name": "Color", "values": ["Red", "Blue"] }
]
    Para las variantes, combina los valores de las opciones.

Ejemplo completo de variants:

"variants": [
  { "price": 12, "wholesale_price": 10, "sku": "VAR-001", "option1": "SM", "option2": "Red" },
  { "price": 14, "wholesale_price": 10, "sku": "VAR-002", "option1": "LG", "option2": "Red" },
  { "price": 25, "wholesale_price": 13, "sku": "VAR-003", "option1": "XL", "option2": "Blue" }
]
    Agregar nueva combinación sin eliminar existentes:
{
  "product": {
    "options": [
      { "name": "Talla", "values": ["SM", "LG", "XL", "XXL"] }
    ],
    "variants": [
      { "option1": "XXL", "sku": "VAR-XXL", "price": 35, "quantity": 10 }
    ]
  }
}
  operationId: updateProduct

### Product

 - [DELETE /api/v1/products/web_id](https://mercately.redocly.app/apis/products/deleteproduct.md): Borra un producto buscado su id

## Product Variants

Actualiza variantes de productos en Mercately

### Create Variant

 - [POST /api/v1/products/product_web_id/variants](https://mercately.redocly.app/apis/product-variants/createvariant.md): Crea una nueva variante (ProductVariantCombination) para un producto existente.

### Creación incremental

Este endpoint permite agregar una sola variante a un producto sin afectar las variantes existentes.

Ideal para integraciones POS que necesitan agregar SKUs uno por uno sin reenviar todo el catálogo.

### Ejemplo: Crear variante con una opción
{
  "variant": {
    "option1": "XXL",
    "price": 35.00,
    "quantity": 10,
    "sku": "CAMISETA-XXL"
  }
}
    ### Ejemplo: Crear variante con múltiples opciones
{
  "variant": {
    "option1": "XXL",
    "option2": "Azul",
    "price": 35.00,
    "quantity": 10,
    "sku": "CAMISETA-XXL-AZUL"
  }
}
    ### Notas importantes
- Los valores de option1, option2, option3 deben existir en las opciones del producto.
- Si la combinación ya existe, retorna error 409 Conflict.
- Las variantes existentes no se ven afectadas.

### Get Variant

 - [GET /api/v1/variants/{web_id}](https://mercately.redocly.app/apis/product-variants/getvariant.md): Obtiene una variante (ProductVariantCombination) por su web_id.

### Consulta individual

Este endpoint retorna una sola variante sin traer el producto completo.

Ideal para integraciones POS que necesitan verificar el estado de una variante específica.

### Update Variant

 - [PATCH /api/v1/variants/{web_id}](https://mercately.redocly.app/apis/product-variants/updatevariant.md): Actualiza una variante (ProductVariantCombination) de forma parcial.

### Actualización parcial

Este endpoint permite actualizar solo los campos enviados sin afectar otros atributos de la variante, otras variantes del producto, ni el producto padre.

Ideal para integraciones POS que necesitan actualizar precio o stock de una variante específica sin reenviar el producto completo.

### Ejemplo: Actualizar solo el precio
{
  "variant": {
    "price": 150.00
  }
}
    ### Ejemplo: Actualizar precio y stock
{
  "variant": {
    "price": 150.00,
    "quantity": 25
  }
}
    ### Ejemplo: Actualizar múltiples atributos
{
  "variant": {
    "price": 200.00,
    "wholesale_price": 150.00,
    "quantity": 100,
    "sku": "NEW-SKU-001",
    "selling_without_stock": true
  }
}
  parameters:
- name: web_id
  in: path
  required: true
  description: El web_id de la variante a actualizar
  schema:
    type: string
  example: "x0wsCBTIMI"

### Delete Variant

 - [DELETE /api/v1/variants/{web_id}](https://mercately.redocly.app/apis/product-variants/deletevariant.md): Elimina una variante (ProductVariantCombination) de forma explícita.

### Borrado inteligente

Este endpoint elimina solo la variante indicada sin afectar otras variantes del producto ni el producto padre.

Comportamiento según integridad:
- Si la variante no tiene órdenes asociadas → Hard delete (eliminación permanente)
- Si la variante tiene órdenes asociadas → Soft delete (marca deleted_at, preserva historial)

Ideal para integraciones POS que necesitan eliminar SKUs descontinuados sin afectar el catálogo completo.

### Notas importantes
- El producto padre permanece intacto
- Las demás variantes no se ven afectadas
- Los ProductVariant y ProductVariantOption no se eliminan
- El borrado es explícito, nunca por omisión

## Categories

Obtén todas las categorías creadas en Mercately

### List Categories

 - [GET /api/v1/categories](https://mercately.redocly.app/apis/categories/listcategories.md): Obtén los datos de tus categorías con sus subcategorías

### Create Category

 - [POST /api/v1/categories](https://mercately.redocly.app/apis/categories/createcategory.md): Crea una nueva categoría con sus subcategorías

### Update Category

 - [PUT /api/v1/categories/web_id](https://mercately.redocly.app/apis/categories/updatecategory.md): Actualiza una categoría existente y sus subcategorías. Puedes actualizar, crear o eliminar subcategorías.

### Update Category (Partial)

 - [PATCH /api/v1/categories/web_id](https://mercately.redocly.app/apis/categories/patchcategory.md): Actualiza parcialmente una categoría existente

### Delete Category

 - [DELETE /api/v1/categories/web_id](https://mercately.redocly.app/apis/categories/deletecategory.md): Elimina una categoría y todas sus subcategorías

## Customer events

### Create Customer Event

 - [POST /retailers/api/v1/customers/:id/events](https://mercately.redocly.app/apis/customer-events/customer/:id/events.md): Crea un nuevo evento para el cliente

### Get Customer Events

 - [GET /retailers/api/v1/customers/:id/customer_events_history](https://mercately.redocly.app/apis/customer-events/customers/:id/customer_events.md): Obtiene los eventos del cliente