{ "openapi": "3.1.0", "servers": [ { "url": "https://app.mercately.com", "description": "Production server" }, { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "info": { "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "1.0.0", "title": "Mercately Retailers API", "termsOfService": "https://mercately.com/terms/", "contact": { "email": "soporte@mercately.com", "url": "http://mercately.com/" }, "description": "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.\nTodas 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." }, "tags": [ { "name": "Agents", "description": "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." }, { "name": "Customers", "description": "En Mercately, todo contacto proveniente de conversaciones, compras o creados directamente se clasifica como cliente." }, { "name": "Deals", "description": "En Mercately, los embudos permiten visualizar el recorrido que sigues a tus clientes a traves de las negociaciones." }, { "name": "Messenger", "description": "En Mercately, una vez vinculado con Messenger, este api permite realizar múltiples operaciones para acceder a las conversaciones de Messenger." }, { "name": "WhatsApp", "description": "En Mercately, una vez vinculado con WhatsApp, este api permite realizar múltiples operaciones para acceder a las conversaciones de WhatsApp y enviar mensajes." }, { "name": "Flows", "description": "En Mercately, una vez creado uno o más flows, esta api permite realizar múltiples operaciones para obtener todos los flows." }, { "name": "Orders", "description": "Crea, actualiza y elimina órdenes en Mercately" }, { "name": "Products", "description": "Crea, actualiza y elimina productos en Mercately" }, { "name": "Product Variants", "description": "Actualiza variantes de productos en Mercately" }, { "name": "Categories", "description": "Obtén todas las categorías creadas en Mercately" } ], "paths": { "/retailers/api/v1/agents": { "get": { "summary": "List all agents", "operationId": "listAgents", "tags": [ "Agents" ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "Lista todos los agentes", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/agents" } } } } } } }, "400": { "description": "Unauthorized" } } } }, "/retailers/api/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "Customers", "description": "Obtén los datos de tus clientes", "operationId": "getCustomers", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de clientes", "required": false, "schema": { "type": "number", "example": 1 } }, { "name": "start_date", "in": "query", "description": "Fecha inicial de búsqueda en formato YYYY-MM-DD", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "end_date", "in": "query", "description": "Fecha final de búsqueda en formato YYYY-MM-DD", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "id_type", "in": "query", "description": "Especifica el tipo de documento a buscar", "required": false, "schema": { "type": "string", "enum": [ "cedula", "pasaporte", "ruc", "rut", "otro" ] } }, { "name": "id_number", "in": "query", "description": "Número de documento a buscar", "required": false, "schema": { "type": "string", "example": "1234567890" } }, { "name": "platform", "in": "query", "description": "Plataforma de interacción", "required": false, "schema": { "type": "string", "enum": [ "whatsapp", "messenger", "instagram" ] } }, { "name": "order_by_last_interaction", "in": "query", "description": "Ordena los clientes por la última interacción según la plataforma", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "integer", "description": "Número total de resultados", "example": 1 }, "total_pages": { "type": "integer", "description": "Número total de páginas", "example": 1 }, "customers": { "type": "array", "description": "Lista de clientes", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID interno del cliente", "example": 12345 }, "first_name": { "type": "string", "description": "Nombre del cliente", "example": "Juan" }, "last_name": { "type": "string", "description": "Apellido del cliente", "example": "Pérez" }, "email": { "type": "string", "format": "email", "description": "Correo electrónico del cliente", "example": "juan@example.com" }, "phone": { "type": "string", "description": "Teléfono del cliente en formato internacional", "example": "+593999999999" }, "id_type": { "type": "string", "description": "Tipo de documento de identidad", "enum": [ "cedula", "pasaporte", "ruc", "rut", "otro" ], "example": "cedula" }, "id_number": { "type": "string", "description": "Número de documento de identidad", "example": "1234567890" }, "address": { "type": "string", "description": "Dirección del cliente", "example": "Av. Principal 123" }, "city": { "type": "string", "description": "Ciudad del cliente", "example": "Quito" }, "state": { "type": "string", "description": "Estado/Provincia del cliente", "example": "Pichincha" }, "zip_code": { "type": "string", "description": "Código postal", "example": "170101" }, "notes": { "type": "string", "description": "Notas adicionales del cliente", "example": "Cliente preferencial" }, "created_at": { "type": "string", "format": "date-time", "description": "Fecha de creación del cliente", "example": "2024-01-15T10:30:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Fecha de última actualización", "example": "2024-01-20T15:45:00.000Z" } } } } } }, "examples": { "response": { "value": { "results": 1, "total_pages": 1, "customers": [ { "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 preferencial", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-20T15:45:00.000Z" } ] } } } } } }, "400": { "description": "Bad Request - Parámetros inválidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Bad Request" } } }, "examples": { "bad_request": { "value": { "message": "Bad Request" } } } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create Customers", "description": "Crea un nuevo cliente", "operationId": "createCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "object", "description": "Datos del cliente", "properties": { "first_name": { "type": "string", "description": "Nombre del cliente", "example": "Juan" }, "last_name": { "type": "string", "description": "Apellido del cliente", "example": "Pérez" }, "email": { "type": "string", "format": "email", "description": "Correo electrónico del cliente", "example": "juan@example.com" }, "phone": { "type": "string", "description": "Teléfono del cliente en formato internacional", "example": "+593999999999" }, "id_type": { "type": "string", "description": "Tipo de documento de identidad", "enum": [ "cedula", "pasaporte", "ruc", "rut", "otro" ], "example": "cedula" }, "id_number": { "type": "string", "description": "Número de documento de identidad", "example": "1234567890" }, "address": { "type": "string", "description": "Dirección del cliente", "example": "Av. Principal 123" }, "city": { "type": "string", "description": "Ciudad del cliente", "example": "Quito" }, "state": { "type": "string", "description": "Estado/Provincia del cliente", "example": "Pichincha" }, "zip_code": { "type": "string", "description": "Código postal", "example": "170101" }, "customer_addresses_attributes": { "type": "array", "description": "Direcciones adicionales del cliente", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Dirección", "example": "Calle Secundaria 456" }, "city": { "type": "string", "description": "Ciudad", "example": "Guayaquil" }, "state": { "type": "string", "description": "Estado/Provincia", "example": "Guayas" }, "zip_code": { "type": "string", "description": "Código postal", "example": "090101" }, "country_id": { "type": "integer", "description": "ID del país", "example": 1 }, "latitude": { "type": "string", "description": "Latitud de la dirección", "example": "-2.1894" }, "longitude": { "type": "string", "description": "Longitud de la dirección", "example": "-79.8891" }, "description": { "type": "string", "description": "Descripción de la dirección", "example": "Oficina principal" }, "main": { "type": "boolean", "description": "Indica si es la dirección principal", "example": true } } } }, "notes": { "type": "string", "description": "Notas adicionales del cliente", "example": "Cliente VIP" } } }, "agent_id": { "type": "integer", "description": "ID del agente asignado al cliente (puede estar en nivel raíz o dentro de customer)", "example": 1 }, "tags": { "type": "array", "description": "Array de etiquetas del cliente (puede estar en nivel raíz o dentro de customer)", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre de la etiqueta", "example": "VIP" }, "value": { "type": "boolean", "description": "Valor de la etiqueta", "example": true } } } }, "custom_fields": { "type": "array", "description": "Array de campos personalizados del cliente (puede estar en nivel raíz o dentro de customer)", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "Nombre del campo personalizado", "example": "preferencia_contacto" }, "field_content": { "type": "string", "description": "Contenido del campo personalizado", "example": "WhatsApp" } } } } } }, "examples": { "create_customer": { "value": { "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" } ] } } } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK - Cliente creado con éxito", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Customer created successfully" }, "customer": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345 }, "first_name": { "type": "string", "example": "Juan" }, "last_name": { "type": "string", "example": "Pérez" }, "email": { "type": "string", "example": "juan@example.com" }, "phone": { "type": "string", "example": "+593999999999" }, "id_type": { "type": "string", "example": "cedula" }, "id_number": { "type": "string", "example": "1234567890" }, "address": { "type": "string", "example": "Av. Principal 123" }, "city": { "type": "string", "example": "Quito" }, "state": { "type": "string", "example": "Pichincha" }, "zip_code": { "type": "string", "example": "170101" }, "notes": { "type": "string", "example": "Cliente VIP" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" } } } } } } } }, "400": { "description": "Bad Request - Datos inválidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Bad Request" }, "errors": { "type": "array", "items": { "type": "string" } } } }, "examples": { "bad_request": { "value": { "message": "Bad Request", "errors": [ "Phone can't be blank", "Email is invalid" ] } } } } } } } } }, "/retailers/api/v1/customers/:id": { "get": { "tags": [ "Customers" ], "summary": "Customer/:id", "description": "Obtén los datos de un cliente en especifico buscado por ID", "operationId": "customer/:id", "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer" } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/customers/:email": { "get": { "tags": [ "Customers" ], "summary": "Customer/:email", "description": "Obtén los datos de un cliente en especifico buscado por email", "operationId": "customer/email", "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_customer" } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/customers/:phone": { "get": { "tags": [ "Customers" ], "summary": "Customer/:phone", "description": "Obtén los datos de un cliente en especifico buscado por phone", "operationId": "customer/phone", "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_customer" } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Customers" ], "summary": "Update Customer by email, id or phone", "description": "Actualiza un nuevo customer buscado por email, id o phone. Puedes realizar la busqueda igual que los métodos get", "operationId": "updateCustomer/email", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_customer" } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_customer-2" } } } }, "400": { "description": "Unauthorized" } } } }, "/retailers/api/v1/customers/:id/events": { "post": { "tags": [ "Customer events" ], "summary": "Create Customer Event", "description": "Crea un nuevo evento para el cliente", "operationId": "customer/:id/events", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_event" } } } }, "security": [ { "api-key": [] } ], "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_customer_event" } } } }, "401": { "description": "Unauthorized" } } } }, "/retailers/api/v1/customers/:id/whatsapp_conversations": { "get": { "tags": [ "Customers" ], "summary": "Customer/:id/whatsapp_conversations", "description": "Obtén la conversación de Whatsapp del cliente por ID", "operationId": "customer/id/whatsapp_conversations", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de conversaciónes", "schema": { "type": "number" } }, { "name": "results_per_page", "in": "query", "description": "Selecciona el número de mensajes que serán visualizados por página", "schema": { "type": "number" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "whatsapp_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/whatsapp_api_message" } }, "total_pages": { "type": "integer", "example": 1 } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/customers/:phone/whatsapp_conversations": { "get": { "tags": [ "Customers" ], "summary": "Customer/:phone/whatsapp_conversations", "description": "Obtén la conversación de Whatsapp del cliente por número de teléfono", "operationId": "customer/phone/whatsapp_conversations", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de conversaciónes", "schema": { "type": "number" } }, { "name": "results_per_page", "in": "query", "description": "Selecciona el número de mensajes que serán visualizados por página", "schema": { "type": "number" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "whatsapp_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/whatsapp_api_message" } }, "total_pages": { "type": "integer", "example": 1 } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/customers/:id/messenger_conversations": { "get": { "tags": [ "Customers" ], "summary": "Customer/:id/messenger_conversations", "description": "Obtén la conversación de Messenger del cliente", "operationId": "customer/id/messenger_conversations", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de conversaciónes", "schema": { "type": "number" } }, { "name": "results_per_page", "in": "query", "description": "Selecciona el número de mensajes que serán visualizados por página", "schema": { "type": "number" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messenger_conversations": { "type": "array", "items": { "$ref": "#/components/schemas/messenger_message" } }, "total_pages": { "type": "integer", "example": 1 } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/customers/:id/instagram_conversations": { "get": { "tags": [ "Customers" ], "summary": "Customer/:id/instagram_conversations", "description": "Obtén la conversación de Instagram del cliente", "operationId": "customer/id/instagram_conversations", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de conversaciónes", "schema": { "type": "number" } }, { "name": "results_per_page", "in": "query", "description": "Selecciona el número de mensajes que serán visualizados por página", "schema": { "type": "number" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "instagram_messages": { "type": "array", "items": { "$ref": "#/components/schemas/messenger_message" } }, "total_pages": { "type": "integer", "example": 1 } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/customers/:id/customer_events_history": { "get": { "tags": [ "Customer events" ], "summary": "Get Customer Events", "description": "Obtiene los eventos del cliente", "operationId": "customers/:id/customer_events", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de eventos", "schema": { "type": "number" } }, { "name": "results_per_page", "in": "query", "description": "Selecciona el número de eventos que serán visualizados por página", "schema": { "type": "number" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_customer_event" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/deals": { "get": { "summary": "Obtener deals", "tags": [ "Deals" ], "description": "Obtén la lista de negociaciones", "operationId": "ListDeal", "security": [ { "api-key": [] } ], "parameters": [ { "name": "funnel_name", "in": "query", "description": "Nombre del embudo", "required": true, "schema": { "type": "string", "example": "Negociaciones" } }, { "name": "stage", "in": "query", "description": "Nombre de la etapa", "required": true, "schema": { "type": "string", "example": "Calificado" } }, { "name": "page", "in": "query", "description": "número de pagina", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/index" } } } }, "404": { "description": "not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "stage not found" } } } } } } } }, "post": { "summary": "Create deal", "tags": [ "Deals" ], "description": "Crea una nueva negociación", "operationId": "CreateDeal", "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "funnel_name": { "type": "string", "example": "Negociaciones" }, "stage": { "type": "string", "example": "Calificado" }, "deal": { "type": "object", "properties": { "amount": { "type": "string", "example": "150000" }, "name": { "type": "string" }, "customer_id": { "type": "string", "example": "91989a87" }, "agent_id": { "type": "integer" }, "lead_status": { "type": "string", "enum": [ "cold", "warm", "hot" ], "example": "cold" }, "opening_date": { "type": "string", "format": "date", "example": "2024-05-16" }, "expected_close_date": { "type": "string", "format": "date", "example": "2024-05-23" } } } }, "required": [ "funnel_name", "stage", "deal" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create" } } } }, "422": { "description": "No se pudo procesar el recurso", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "string", "example": "unprocessable entity" } } } } } } } } }, "/retailers/api/v1/deals/{id}": { "get": { "summary": "deals/:id", "tags": [ "Deals" ], "description": "Obtén una negociacion", "operationId": "GetDeal", "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la negociación", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get" } } } }, "404": { "description": "La negociación no existe", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "deal not found" } } } } } } } }, "put": { "summary": "deals/:id", "tags": [ "Deals" ], "description": "Actualiza una negociación", "operationId": "UpdateDeal", "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la negociación", "schema": { "type": "string", "example": "9c6d04017" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "funnel_name": { "type": "string", "example": "Negociaciones" }, "stage": { "type": "string", "example": "Calificado" }, "deal": { "type": "object", "properties": { "amount": { "type": "string", "example": "150000" }, "name": { "type": "string", "example": "Ricardo - pavo" }, "customer_id": { "type": "string", "example": "91989a87" }, "lead_status": { "type": "string", "example": "cold" }, "opening_date": { "type": "string", "format": "date", "example": "2024-05-16" }, "expected_close_date": { "type": "string", "format": "date", "example": "2024-05-23" }, "funnel_name": { "type": "string", "example": "Negociaciones" }, "stage": { "type": "string", "example": "Calificado" } } } }, "required": [ "funnel_name", "stage", "deal" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update" } } } }, "404": { "description": "La negociación no existe", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "deal not found" } } } } } }, "422": { "description": "No se pudo procesar el recurso", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "string", "example": "unprocessable entity" } } } } } } } }, "delete": { "summary": "deals/:id", "tags": [ "Deals" ], "description": "Elimina una negociación", "operationId": "deleteDeal", "security": [ { "api-key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la negociación", "schema": { "type": "string", "example": 93390836 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "deal was deleted successfully" } } } } } }, "404": { "description": "negociación no existe", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "deal not found" } } } } } }, "422": { "description": "Error al procesar el recurso", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Error deleting deal" } } } } } } } } }, "/retailers/api/v1/messenger_conversations": { "get": { "tags": [ "Messenger" ], "summary": "Messenger conversations", "description": "Obtén los clients que te han escrito por messenger", "operationId": "messengerClients", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "Messenger conversations", "properties": { "page": { "type": "number" }, "results_per_page": { "type": "number" }, "unassigned": { "type": "boolean" } } } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "integer", "example": 155 }, "total_pages": { "type": "integer", "example": 2 }, "facebook_messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "621osgzy4696283" }, "first_name": { "type": "string", "example": "Claudia" }, "last_name": { "type": "string", "example": "Funnel" }, "email": { "type": [ "string", "null" ], "example": "null" }, "message_count": { "type": "integer", "example": 3 }, "last_interaction": { "type": "string", "example": "2023-04-17T05:08:17.085Z" }, "agent_id": { "type": "integer", "example": 4637 } } } } } } } } }, "400": { "description": "Unauthorized" } } } }, "/retailers/api/v1/whatsapp_templates": { "get": { "tags": [ "WhatsApp" ], "summary": "WhatsApp Business Api Templates", "description": "Obtén los templates/plantillas creadas en WhatsApp Business API", "operationId": "whatsappTemplates", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "WhatsApp Business Api templates" } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "example": "Hola *! ✋" }, "status": { "type": "string", "example": "accepted" }, "template_type": { "type": "string", "example": "text" }, "internal_id": { "type": "string", "example": "c0c040f6-9809-404a-961c-637b109ef410" } } } } } } } } }, "400": { "description": "Unauthorized" } } } }, "/retailers/api/v1/whatsapp/send_notification_by_id": { "post": { "tags": [ "WhatsApp" ], "summary": "Send WhatsApp Message for WhatsApp Business API", "description": "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.", "operationId": "sendWhatsAppApi", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_api_message" } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/whatsapp_api_message" } } } }, "400": { "description": "Unauthorized" } } } }, "/retailers/api/v1/whatsapp/send_message": { "post": { "tags": [ "WhatsApp" ], "summary": "Send WhatsApp Message for WhatsApp Business QR", "description": "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.", "operationId": "sendWhatsAppQr", "security": [ { "api-key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/send_qr_message" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/whatsapp_api_message" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Customer not found" }, "422": { "description": "Unprocessable Entity" }, "500": { "description": "Internal Server Error" } } } }, "/retailers/api/v1/flows": { "get": { "tags": [ "Flows" ], "summary": "Get all flows", "description": "Obtén todos los flows", "operationId": "flows", "parameters": [ { "name": "page", "in": "query", "description": "Busca la página específica de flows", "schema": { "type": "number" } }, { "name": "results_per_page", "in": "query", "description": "Selecciona el número de flows que serán visualizados por página", "schema": { "type": "number" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_flows" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/retailers/api/v1/flow_deactivation": { "post": { "tags": [ "Flows" ], "summary": "Deactivate flows by platform", "description": "Desactiva todos los flows que estén previamente activos por customer y plataforma específica", "operationId": "flow_deactivation", "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "d126hhh", "description": "ID del customer (web_id). Requerido si no se proporciona customer_phone" }, "customer_phone": { "type": "string", "example": "+573201548587", "description": "Teléfono del customer (formato internacional con +). Requerido si no se proporciona customer_id" }, "platform": { "type": "string", "enum": [ "whatsapp", "messenger", "instagram" ], "example": "whatsapp", "description": "Plataforma sobre la cual se realizará la búsqueda para desactivar flows específicos para el customer. Valores permitidos: 'whatsapp', 'messenger' o 'instagram'" } }, "required": [ "platform" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deactivate_flows" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } } } }, "/retailers/api/v1/flow_pre_activation": { "post": { "tags": [ "Flows" ], "summary": "Pre-activate flow by platform", "description": "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.", "operationId": "flow_pre_activation", "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "d126hhh", "description": "Id del customer(Opcional, siempre y cuando se busque por customer_phone)" }, "customer_phone": { "type": "string", "example": "+573201548587", "description": "Teléfono del customer(Opcional, siempre y cuando se busque por customer_id)" }, "flow_id": { "type": "string", "example": "d82ijd8", "description": "Id del flow" }, "platform": { "type": "string", "example": "whatsapp", "description": "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'" } }, "required": [ "customer_id", "customer_phone", "flow_id", "platform" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pre_activate_flow" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } } } }, "/retailers/api/v1/stats": { "get": { "tags": [ "Analítica" ], "summary": "Estadísticas de leads por canal", "description": "Obtiene el conteo y métricas de los leads generados agrupados por canal dentro de un rango de fechas. Si no se especifican las fechas, retorna los datos del último mes.", "operationId": "getLeadsStats", "security": [ { "api-key": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Fecha de inicio del reporte (Formato YYYY-MM-DD). Por defecto se calcula como el inicio del último mes.", "schema": { "type": "string", "format": "date", "example": "2026-06-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "Fecha de fin del reporte (Formato YYYY-MM-DD). Por defecto corresponde a la fecha actual.", "schema": { "type": "string", "format": "date", "example": "2026-07-01" } } ], "responses": { "200": { "description": "Estadísticas de leads obtenidas exitosamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2026-06-01" }, "end_date": { "type": "string", "example": "2026-07-01" }, "total_leads": { "type": "integer", "example": 30 }, "by_platform": { "type": "object", "description": "Desglose de los leads generados clasificados por cada plataforma/canal.", "properties": { "whatsapp": { "type": "integer", "example": 5 }, "instagram": { "type": "integer", "example": 1 }, "messenger": { "type": "integer", "example": 2 }, "no_channel": { "type": "integer", "example": 22 } } } } } } } }, "400": { "description": "Solicitud incorrecta (parámetros inválidos o formato de fecha erróneo).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "El formato de fecha provisto en start_date es inválido." } } } } } } } } }, "/retailers/api/v1/stats/funnel_stats": { "get": { "tags": [ "Analítica" ], "summary": "Estadísticas de oportunidades por embudo (Funnel)", "description": "Obtiene las métricas de conversión pasadas por las distintas etapas del embudo de ventas. Si no se especifican las fechas, retorna los datos del último mes.", "operationId": "getFunnelStats", "security": [ { "api-key": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Fecha de inicio para evaluar el embudo (Formato YYYY-MM-DD). Por defecto se calcula como el inicio del último mes.", "schema": { "type": "string", "format": "date", "example": "2026-06-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "Fecha de fin para evaluar el embudo (Formato YYYY-MM-DD). Por defecto corresponde a la fecha actual.", "schema": { "type": "string", "format": "date", "example": "2026-07-01" } } ], "responses": { "200": { "description": "Métricas del embudo obtenidas exitosamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2026-06-01" }, "end_date": { "type": "string", "example": "2026-07-01" }, "funnels": { "type": "array", "description": "Lista de embudos de venta disponibles con sus respectivas etapas.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador único del embudo.", "example": "1dcb040ecbcbe33-e0e3-47dc-ae23-db4013174384" }, "name": { "type": "string", "example": "Enbudo 1" }, "total_opportunities": { "type": "integer", "example": 2 }, "by_stage": { "type": "array", "description": "Desglose del rendimiento por cada etapa del embudo.", "items": { "type": "object", "properties": { "step_id": { "type": "string", "description": "Identificador único de la etapa.", "example": "1afea89142a5ab0-d76e-44a7-b4d5-bd322dba1548" }, "name": { "type": "string", "example": "Etapa 1" }, "type_step": { "type": "string", "example": "step" }, "position": { "type": "integer", "example": 1 }, "count": { "type": "integer", "example": 2 }, "amount": { "type": "number", "format": "float", "example": 378 } } } } } } } } } } } }, "400": { "description": "Solicitud incorrecta (parámetros inválidos o formato de fecha erróneo).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "El formato de fecha provisto en start_date es inválido." } } } } } } } } }, "/retailers/api/v1/stats/response_time_by_agent": { "get": { "tags": [ "Analítica" ], "summary": "Tiempos de respuesta por agente", "description": "Obtiene las métricas y promedios de tiempos de respuesta agrupados por cada agente de soporte/ventas. Si no se especifican las fechas, retorna los datos del último mes.", "operationId": "getAgentResponseTimeStats", "security": [ { "api-key": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Fecha de inicio del reporte (Formato YYYY-MM-DD). Por defecto se calcula como el inicio del último mes.", "schema": { "type": "string", "format": "date", "example": "2026-06-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "Fecha de fin del reporte (Formato YYYY-MM-DD). Por defecto corresponde a la fecha actual.", "schema": { "type": "string", "format": "date", "example": "2026-07-01" } } ], "responses": { "200": { "description": "Tiempos de respuesta por agente obtenidos exitosamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response_time_by_agent": { "type": "array", "description": "Listado de agentes con sus respectivos promedios de tiempo de respuesta (en minutos o segundos según la configuración).", "items": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Jhon" }, "last_name": { "type": "string", "example": "Doe" }, "tiempo_promedio_primera_respuesta": { "type": [ "number", "null" ], "format": "float", "example": 110.25 }, "tiempo_promedio_primera_respuesta_mia": { "type": [ "number", "null" ], "format": "float", "example": null }, "tiempo_promedio_respuesta_promedio": { "type": [ "number", "null" ], "format": "float", "example": 123.7 }, "tiempo_respuesta_horario_laboral": { "type": [ "number", "null" ], "format": "float", "example": null } } } } } } } } }, "400": { "description": "Solicitud incorrecta (parámetros inválidos o formato de fecha erróneo).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "El formato de fecha provisto en start_date es inválido." } } } } } } } } }, "/retailers/api/v1/ads_stats/leads_by_source": { "get": { "tags": [ "Analítica" ], "summary": "Leads por fuente de origen (Ads)", "description": "Obtiene el conteo de leads generados agrupados por su fuente de atribución (pago, orgánico, etc.) dentro de un rango de fechas. Si no se especifican las fechas, retorna los datos del último mes.", "operationId": "getAdsLeadsBySource", "security": [ { "api-key": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Fecha de inicio del reporte (Formato YYYY-MM-DD). Por defecto se calcula como el inicio del último mes.", "schema": { "type": "string", "format": "date", "example": "2025-07-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "Fecha de fin del reporte (Formato YYYY-MM-DD). Por defecto corresponde a la fecha actual.", "schema": { "type": "string", "format": "date", "example": "2026-08-01" } } ], "responses": { "200": { "description": "Estadísticas de leads por origen obtenidas exitosamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2025-07-01" }, "end_date": { "type": "string", "example": "2026-08-01" }, "total_leads": { "type": "integer", "example": 30 }, "by_source": { "type": "object", "description": "Desglose de leads agrupados por su fuente de atribución.", "properties": { "paid_social": { "type": "integer", "example": 0 }, "organic": { "type": "integer", "example": 0 }, "no_attribution": { "type": "integer", "example": 0 }, "no_channel": { "type": "integer", "example": 30 } } } } } } } }, "400": { "description": "Solicitud incorrecta (parámetros inválidos o formato de fecha erróneo).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "El formato de fecha provisto en start_date es inválido." } } } } } } } } }, "/retailers/api/v1/ads_stats/campaign_funnel": { "get": { "tags": [ "Analítica" ], "summary": "Embudo por campaña de anuncios (Ads)", "description": "Obtiene las métricas del embudo desglosadas por cada campaña publicitaria dentro de un rango de fechas. Si no se especifican las fechas, retorna los datos del último mes.", "operationId": "getAdsCampaignFunnelStats", "security": [ { "api-key": [] } ], "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Fecha de inicio del reporte (Formato YYYY-MM-DD). Por defecto se calcula como el inicio del último mes.", "schema": { "type": "string", "format": "date", "example": "2026-05-01" } }, { "name": "end_date", "in": "query", "required": false, "description": "Fecha de fin del reporte (Formato YYYY-MM-DD). Por defecto corresponde a la fecha actual.", "schema": { "type": "string", "format": "date", "example": "2026-06-01" } } ], "responses": { "200": { "description": "Métricas del embudo por campaña obtenidas exitosamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2026-06-01" }, "end_date": { "type": "string", "example": "2026-07-01" }, "total_leads": { "type": "integer", "example": 30 }, "by_campaing": { "type": "object", "description": "Métricas desglosadas por campaña (las claves representan el nombre de cada campaña).", "additionalProperties": { "type": "object", "description": "Conteos de prospectos por cada etapa del embudo.", "additionalProperties": { "type": "integer" } }, "example": { "Campaña 1": { "etapa_1": 5, "etapa_2": 23, "ganados": 3 } } } } } } } }, "400": { "description": "Solicitud incorrecta (parámetros inválidos o formato de fecha erróneo).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "El formato de fecha provisto en start_date es inválido." } } } } } } } } }, "/retailers/api/v1/stats/leads_report": { "get": { "tags": [ "Analítica" ], "summary": "Reporte detallado de leads", "description": "Obtiene el listado paginado y detallado de leads registrados con métricas de agente, canal de origen, embudo, IA (MIA) y conversación.", "operationId": "getLeadsReportStats", "security": [ { "api-key": [] } ], "parameters": [ { "name": "date", "in": "query", "required": false, "description": "Fecha específica para filtrar el reporte de leads (Formato YYYY-MM-DD).", "schema": { "type": "string", "format": "date", "example": "2026-06-03" } }, { "name": "page", "in": "query", "required": false, "description": "Número de página. Paginación fija de 10 clientes por página (no se acepta per_page; el tamaño de página no es configurable).", "schema": { "type": "integer", "example": 1 } }, { "name": "agent_id", "in": "query", "required": false, "description": "Identificador único del agente para filtrar los leads.", "schema": { "type": "integer", "example": 1204 } } ], "responses": { "200": { "description": "Reporte de leads obtenido exitosamente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-08-01" }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 10 }, "total": { "type": "integer", "example": 84 }, "total_pages": { "type": "integer", "example": 9 } } }, "leads": { "type": "array", "description": "Lista detallada de leads del periodo.", "items": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "web_id": { "type": "string", "example": "483abc920" }, "phone": { "type": "string", "example": "+593991234567" }, "id_number": { "type": [ "string", "null" ], "example": "1712345678" }, "first_name": { "type": "string", "example": "Ana" }, "last_name": { "type": "string", "example": "Ramírez" }, "whatsapp_name": { "type": "string", "example": "Ana R." }, "email": { "type": [ "string", "null" ], "example": "ana@gmail.com" }, "city": { "type": [ "string", "null" ], "example": "Quito" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-15T20:10:35-05:00" } } }, "agent": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "example": 1204 }, "name": { "type": "string", "example": "Sonia Patiño" }, "email": { "type": "string", "example": "sonia@mastermoto.com" }, "assigned_at": { "type": "string", "format": "date-time", "example": "2026-05-15T20:14:02-05:00" }, "assignment_reason": { "type": "string", "example": "automatic" } } }, "agent_metrics": { "type": "object", "properties": { "avg_response_after_mia_seconds": { "type": [ "integer", "null" ], "example": 1218 }, "responded_after_assignment": { "type": [ "boolean", "null" ], "example": true }, "first_agent_message_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-05-15T20:34:20-05:00" }, "last_agent_message_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-05-16T09:45:12-05:00" }, "agent_management_seconds": { "type": [ "integer", "null" ], "example": 47452 } } }, "lead_source": { "type": "object", "properties": { "channel": { "type": "string", "example": "ctwa" }, "utm_source": { "type": [ "string", "null" ], "example": null }, "campaign_name": { "type": [ "string", "null" ], "example": "MM || Tráfico Abril 26" }, "ad_name": { "type": [ "string", "null" ], "example": "Sukida Joy 150 - Crédito Fácil" }, "ad_headline": { "type": [ "string", "null" ], "example": "Estrena tu Sukida Joy 150 con $99 de entrada" } } }, "funnel": { "type": "array", "items": { "type": "object", "properties": { "funnel_name": { "type": "string", "example": "Ventas Motos" }, "step_name": { "type": "string", "example": "Oportunidad / Lead" }, "step_changed_at": { "type": "string", "format": "date-time", "example": "2026-05-16T10:02:44-05:00" }, "deal_created_at": { "type": "string", "format": "date-time", "example": "2026-05-15T20:11:08-05:00" } } } }, "mia": { "type": "object", "properties": { "first_mia_message_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-05-15T20:10:41-05:00" }, "last_mia_message_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-05-15T20:31:55-05:00" }, "mia_management_seconds": { "type": [ "integer", "null" ], "example": 1274 }, "buy_intention": { "type": "boolean", "example": true }, "human_help": { "type": "boolean", "example": false }, "active": { "type": "boolean", "example": false } } }, "conversation_metrics": { "type": "object", "properties": { "customer_messages_count": { "type": "integer", "example": 18 }, "mia_messages_count": { "type": "integer", "example": 9 }, "agent_messages_count": { "type": "integer", "example": 14 }, "total_messages_count": { "type": "integer", "example": 41 }, "first_customer_message_at": { "type": "string", "format": "date-time", "example": "2026-05-15T20:10:35-05:00" }, "last_message_at": { "type": "string", "format": "date-time", "example": "2026-05-16T09:45:12-05:00" } } }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "MODELO ESPECÍFICO", "ASESORÍA", "CRÉDITO" ] }, "custom_fields": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "example": { "modelo_interes_final": "Pulsar 125 N", "marca_interes": "Bajaj", "forma_pago": "Crédito" } } } } } } } } } }, "400": { "description": "Solicitud incorrecta (parámetros inválidos o formato de fecha erróneo).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "El formato de fecha provisto en date es inválido." } } } } } } } } }, "/api/v1/orders": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "get": { "tags": [ "Orders" ], "summary": "Orders", "description": "Obtén los datos de tus órdenes", "operationId": "orders", "parameters": [ { "name": "created_from", "in": "query", "description": "busca las órdenes creadas desde una fecha en especifico", "schema": { "type": "string", "format": "date", "example": "2023-05-17" } }, { "name": "created_to", "in": "query", "description": "busca las órdenes creadas hasta una fecha en especifico", "schema": { "type": "string", "format": "date", "example": "2023-05-17" } }, { "name": "page", "in": "query", "description": "busca la pagina específica de órdenes", "schema": { "type": "integer", "default": 1 } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "web_id": { "type": "string" }, "status": { "type": "string" }, "subtotal": { "type": "string" }, "tax_amount": { "type": "string" }, "total": { "type": "string" }, "shipping_value": { "type": "string" }, "notes": { "type": "string" }, "sales_channel": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "archived": { "type": "boolean" }, "customer": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country_id": { "type": "string" }, "zip_code": { "type": "string" }, "id_number": { "type": "string" }, "document_label": { "type": "string" }, "web_id": { "type": "string" } } }, "order_items": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "total": { "type": "string" }, "title": { "type": "string" }, "sku": { "type": "string" }, "image_url": { "oneOf": [ { "type": "string", "description": "Cadena vacía cuando no hay producto asociado", "example": "" }, { "type": "object", "description": "Objeto vacío cuando hay producto pero sin imágenes, o objeto con url y fileName cuando hay imágenes", "properties": { "url": { "type": "string" }, "fileName": { "type": "string" } } } ] } } } } } } }, "total_pages": { "type": "integer" } } }, "examples": { "response": { "value": { "orders": [ { "web_id": "EzLGaK0YZa", "status": "pending", "subtotal": "200.0", "tax_amount": "0.0", "total": "200.0", "shipping_value": "0.0", "notes": "", "sales_channel": null, "created_at": "2023-05-17T01:42:57.624Z", "archived": false, "customer": { "first_name": "Henry ", "last_name": "Tonato", "email": "henry@gmail.com", "phone": "593995141472", "address": "", "city": "", "state": "", "country_id": "EC", "zip_code": "", "id_number": "", "document_label": null, "web_id": "EleO7OTOer" }, "order_items": [ { "quantity": 1, "unit_price": "200.0", "total": "200.0", "title": "Mensajes", "sku": "Col.2556", "image_url": {} } ] } ], "total_pages": 1 } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "Orders" ], "summary": "Create Order", "description": "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.", "operationId": "createOrder", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "Order", "properties": { "order": { "type": "object", "properties": { "sales_channel": { "type": "string" }, "notes": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "delivery_method": { "type": "string", "enum": [ "send_order", "store_pickup" ] }, "status": { "type": "string", "enum": [ "pending", "canceled", "success" ] }, "shipping_value": { "type": "number", "format": "float" }, "customer_attributes": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "order_items_attributes": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number", "format": "float" } } } } } } } } } } }, "security": [ { "api-key": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "order": { "type": "object", "properties": { "web_id": { "type": "string" }, "status": { "type": "string" }, "subtotal": { "type": "string" }, "tax_amount": { "type": "string" }, "total": { "type": "string" }, "shipping_value": { "type": "string" }, "sales_channel": { "type": "string" }, "notes": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "archived": { "type": "boolean" }, "customer": { "type": "object" }, "order_items": { "type": "array", "items": { "type": "object" } } } } } }, "examples": { "response": { "value": { "message": "Órden creada con éxito", "order": { "web_id": "aAKpT9laN5", "status": "pending", "subtotal": "400.0", "tax_amount": "0.0", "total": "405.0", "shipping_value": "5.0", "sales_channel": null, "notes": "New notes", "created_at": "2023-06-12T18:26:58.534Z", "archived": false, "customer": { "first_name": "Juan", "last_name": "Campos", "email": "juan@email42.com", "phone": "593996459124", "address": "", "city": "", "state": "", "country_id": "EC", "zip_code": "", "id_number": "", "document_label": "cedula", "web_id": "bReccZpRjO" }, "order_items": [ { "quantity": 2, "unit_price": "200.0", "total": "400.0", "title": "Mensajes", "sku": "Col.2556", "image_url": {} } ] } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/v1/orders/web_id": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "put": { "tags": [ "Orders" ], "summary": "Order", "description": "Actualiza una órden buscada su id", "operationId": "updateOrder", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "title": "Order", "properties": { "order": { "type": "object", "properties": { "sales_channel": { "type": "string" }, "notes": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "delivery_method": { "type": "string", "enum": [ "send_order", "store_pickup" ] }, "status": { "type": "string", "enum": [ "pending", "canceled", "success" ] }, "shipping_value": { "type": "number", "format": "float" }, "customer_attributes": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string", "description": "Must be in international format, including the international dialing code." } }, "required": [ "email", "phone" ] }, "order_items_attributes": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number", "format": "float" } }, "required": [ "product_id", "quantity" ] } } } } } } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" }, "examples": { "response": { "value": { "message": "Órden actualizada con éxito", "order": { "web_id": "4Bs2mKblN3", "status": "success", "subtotal": "60.0", "tax_amount": "0.0", "total": "65.0", "shipping_value": "5.0", "sales_channel": null, "notes": "New notes", "created_at": "2023-06-13T03:31:06.825Z", "archived": false, "customer": { "first_name": "Henry", "last_name": "Campos", "email": null, "phone": null, "address": null, "city": null, "state": null, "country_id": null, "zip_code": null, "id_number": null, "document_label": null, "web_id": "sVnez19hSa" }, "order_items": [ { "quantity": 3, "unit_price": "20.0", "total": "60.0", "title": "Mensajes", "sku": "Col.2556", "image_url": {} } ] } } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Orders" ], "summary": "Orders", "description": "Borra una órden", "operationId": "deleteOrder", "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" }, "examples": { "response": { "value": { "message": "Órden borrada con éxito" } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/v1/products": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "get": { "tags": [ "Products" ], "summary": "Products", "description": "Obtén los datos de tus productos", "operationId": "products", "parameters": [ { "name": "page", "in": "query", "description": "busca la pagina específica de productos", "schema": { "type": "integer", "default": 1 } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object" } }, "total_pages": { "type": "integer" } } }, "example": { "products": [ { "web_id": "CRasFSldo7", "title": "Camiseta Gráfica Premium", "description": "Camiseta con diseño gráfico exclusivo", "quantity": 85, "price": "39.99", "active": true, "url": null, "sku": "CAM-GRA-010", "wholesale_price": "20.0", "images": [], "subcategory": { "name": "Camisetas", "web_id": "GETPvRKnBD" }, "category": { "name": "Ropa", "web_id": "ljsJpi0fTR" }, "product_variants": [ { "name": "Color", "web_id": "pv123abc", "product_variant_options": [ { "name": "Negro", "web_id": "BEYaSU7yTH" }, { "name": "Blanco", "web_id": "vftzaNsoI3" } ] }, { "name": "Talla", "web_id": "pv456def", "product_variant_options": [ { "name": "S", "web_id": "nCbIHF5EGT" }, { "name": "M", "web_id": "QboGUaqrOl" } ] } ], "product_variant_combinations": [ { "web_id": "xa6d2qprcI", "name": "Negro/S", "price": "45.86", "wholesale_price": "22.94", "sku": "CAM-GRA-010-NEGRO-S", "quantity": 8, "variant_option_web_ids": [ "BEYaSU7yTH", "nCbIHF5EGT" ], "image": "", "variant_url": null }, { "web_id": "aD8EI424Tx", "name": "Negro/M", "price": "43.60", "wholesale_price": "21.81", "sku": "CAM-GRA-010-NEGRO-M", "quantity": 20, "variant_option_web_ids": [ "BEYaSU7yTH", "QboGUaqrOl" ], "image": "", "variant_url": null } ] } ], "total_pages": 4 } } } }, "400": { "description": "Unauthorized" } } }, "post": { "tags": [ "Products" ], "summary": "Create Product", "description": "Crea un nuevo producto. \nEnvía máximo 3 opciones. \n\n**Ejemplo de `options`:**\n\"options\": [\n { \"name\": \"Talla\", \"values\": [\"SM\", \"LG\", \"XL\", \"MD\"] },\n { \"name\": \"Color\", \"values\": [\"Red\", \"Blue\"] }\n]\n Para las variantes, combina los valores de las opciones.\n\n**Ejemplo de `variants`:**\n\"variants\": [\n { \"price\": 12, \"wholesale_price\": 10, \"sku\": \"VAR-001\", \"option1\": \"SM\", \"option2\": \"Red\" },\n { \"price\": 14, \"wholesale_price\": 10, \"sku\": \"VAR-002\", \"option1\": \"LG\", \"option2\": \"Red\" },\n { \"price\": 25, \"wholesale_price\": 13, \"sku\": \"VAR-003\", \"option1\": \"XL\", \"option2\": \"Blue\" }\n]\n operationId: createProduct\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "active": { "type": "boolean" }, "price": { "type": "number" }, "subcategory_id": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "description": "Máximo 3 opciones", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "wholesale_price": { "type": "number" }, "sku": { "type": "string" }, "quantity": { "type": "number" }, "image": { "type": "string" }, "variant_url": { "type": "string" }, "option1": { "type": "string" }, "option2": { "type": "string" }, "option3": { "type": "string" } } } } } } } } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Producto creado con éxito", "product": { "web_id": "FzOWVvUwbC", "title": "Product 001", "description": "Product 001", "quantity": 20, "price": "1.5", "active": true, "url": null, "sku": "p004", "wholesale_price": "0.0", "images": [ "https://d3a4wxp51vazl1.cloudfront.net/uploads/506/product_attachment/FzOWVvUwbC/qrewrwYdhfNDCqW3hv4MTiwFq.jpg" ], "subcategory": { "name": "Alámbricos", "web_id": "GETPvRKnBD" }, "category": { "name": "Tecnología", "web_id": "ljsJpi0fTR" }, "product_variants": [ { "name": "Talla", "web_id": "AbHj6GqcMF", "product_variant_options": [ { "name": "SM", "web_id": "3I6zc3DGMY" }, { "name": "LG", "web_id": "57gl2i88SZ" }, { "name": "XL", "web_id": "J7PFMLX9wA" } ] }, { "name": "Color", "web_id": "vVlmXsA2Bm", "product_variant_options": [ { "name": "Azul", "web_id": "Xe9QkMiD1i" }, { "name": "Negro", "web_id": "Y8zjQ7BPY4" } ] } ], "product_variant_combinations": [ { "web_id": "x0wsCBTIMI", "name": "SM/Azul", "price": "33.0", "wholesale_price": null, "sku": "SKU-EX1", "quantity": 10, "variant_option_web_ids": [ "3I6zc3DGMY", "Xe9QkMiD1i" ], "image": "https://dc2p3rqc7bvrd.cloudfront.net/uploads/1/product_variant_combination/x0wsCBTIMI/camisa-del-producto_40x403x.webp", "variant_url": null }, { "web_id": "y1xtDUITNJ", "name": "XL/Azul", "price": "33.0", "wholesale_price": null, "sku": "SKU-EX5", "quantity": 10, "variant_option_web_ids": [ "J7PFMLX9wA", "Xe9QkMiD1i" ], "image": "", "variant_url": null } ] } } } } }, "400": { "description": "Unauthorized" } } } }, "/api/v1/products/:id_or_sku": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "get": { "tags": [ "Products" ], "summary": "Product", "description": "Obtén los datos de un producto en especifico buscado su id", "operationId": "searchProduct", "parameters": [ { "name": "web_id", "in": "query", "description": "The web_id of the product", "required": false, "schema": { "type": "string" } }, { "name": "sku", "in": "query", "description": "The SKU of the product", "required": false, "schema": { "type": "string" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "web_id": "CRasFSldo7", "title": "Camiseta Gráfica Premium", "description": "Camiseta con diseño gráfico exclusivo", "quantity": 85, "price": "39.99", "active": true, "url": null, "sku": "CAM-GRA-010", "wholesale_price": "20.0", "images": [], "subcategory": { "web_id": "GETPvRKnBD", "name": "Camisetas", "description": "", "products_count": 5, "active_products_count": 2 }, "category": { "web_id": "ljsJpi0fTR", "name": "Ropa", "description": "", "products_count": 11, "active_products_count": 6 }, "product_variants": [ { "name": "Color", "web_id": "pv123abc", "product_variant_options": [ { "name": "Negro", "web_id": "BEYaSU7yTH" }, { "name": "Blanco", "web_id": "vftzaNsoI3" } ] }, { "name": "Talla", "web_id": "pv456def", "product_variant_options": [ { "name": "S", "web_id": "nCbIHF5EGT" }, { "name": "M", "web_id": "QboGUaqrOl" } ] } ], "product_variant_combinations": [ { "web_id": "xa6d2qprcI", "name": "Negro/S", "price": "45.86", "wholesale_price": "22.94", "sku": "CAM-GRA-010-NEGRO-S", "quantity": 8, "variant_option_web_ids": [ "BEYaSU7yTH", "nCbIHF5EGT" ], "image": "", "variant_url": null }, { "web_id": "aD8EI424Tx", "name": "Negro/M", "price": "43.60", "wholesale_price": "21.81", "sku": "CAM-GRA-010-NEGRO-M", "quantity": 20, "variant_option_web_ids": [ "BEYaSU7yTH", "QboGUaqrOl" ], "image": "", "variant_url": null } ] } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/v1/products/web_id": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "put": { "tags": [ "Products" ], "summary": "Product", "description": "Actualiza un producto buscado su id. \nEnvía máximo 3 opciones.\n\n### Comportamiento de actualización parcial\n\nEste endpoint soporta **actualizaciones parciales** (partial updates):\n\n- Si **no envías** los keys `\"options\"` ni `\"variants\"`, las variantes existentes **se preservan**.\n- Si envías `\"options\": []` o `\"variants\": []`, las variantes existentes **también se preservan** (no se eliminan por omisión).\n- Si envías nuevas opciones o variantes, estas se **agregan** a las existentes sin eliminar las anteriores.\n\n### Ejemplos\n\n**Actualizar solo precio y título (preserva variantes):**\n\n{\n \"product\": {\n \"title\": \"Nuevo título\",\n \"price\": 29.99\n }\n}\n **Agregar nueva opción sin eliminar existentes:**\n{\n \"product\": {\n \"options\": [\n { \"name\": \"Material\", \"values\": [\"Algodón\", \"Poliéster\"] }\n ]\n }\n}\n **Ejemplo completo de `options`:**\n\"options\": [\n { \"name\": \"Talla\", \"values\": [\"SM\", \"LG\", \"XL\", \"MD\"] },\n { \"name\": \"Color\", \"values\": [\"Red\", \"Blue\"] }\n]\n Para las variantes, combina los valores de las opciones.\n\n**Ejemplo completo de `variants`:**\n\n\"variants\": [\n { \"price\": 12, \"wholesale_price\": 10, \"sku\": \"VAR-001\", \"option1\": \"SM\", \"option2\": \"Red\" },\n { \"price\": 14, \"wholesale_price\": 10, \"sku\": \"VAR-002\", \"option1\": \"LG\", \"option2\": \"Red\" },\n { \"price\": 25, \"wholesale_price\": 13, \"sku\": \"VAR-003\", \"option1\": \"XL\", \"option2\": \"Blue\" }\n]\n **Agregar nueva combinación sin eliminar existentes:**\n{\n \"product\": {\n \"options\": [\n { \"name\": \"Talla\", \"values\": [\"SM\", \"LG\", \"XL\", \"XXL\"] }\n ],\n \"variants\": [\n { \"option1\": \"XXL\", \"sku\": \"VAR-XXL\", \"price\": 35, \"quantity\": 10 }\n ]\n }\n}\n operationId: updateProduct\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "integer" }, "active": { "type": "boolean" }, "price": { "type": "number" }, "subcategory_id": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "description": "Opciones del producto (ej: Talla, Color). Si se envía, las nuevas opciones se agregan a las existentes.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } } } }, "variants": { "type": "array", "description": "Combinaciones de variantes. Si se envía, las nuevas combinaciones se agregan a las existentes.", "items": { "type": "object", "properties": { "price": { "type": "number" }, "wholesale_price": { "type": "number" }, "sku": { "type": "string" }, "quantity": { "type": "number" }, "image": { "type": "string" }, "variant_url": { "type": "string" }, "option1": { "type": "string" }, "option2": { "type": "string" }, "option3": { "type": "string" } } } } } } } } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Producto actualizado con éxito", "product": { "web_id": "FzOWVvUwbC", "title": "Product 001", "description": "Product 001", "quantity": 20, "price": "1.5", "active": true, "url": null, "sku": "p004", "wholesale_price": "0.0", "images": [ "https://d3a4wxp51vazl1.cloudfront.net/uploads/506/product_attachment/FzOWVvUwbC/qrGZwYdhfewrW3hv4MTiwFq.jpg" ], "subcategory": { "name": "Alámbricos", "web_id": "GETPvRKnBD" }, "category": { "name": "Tecnología", "web_id": "ljsJpi0fTR" }, "product_variants": [ { "name": "Talla", "web_id": "AbHj6GqcMF", "product_variant_options": [ { "name": "SM", "web_id": "3I6zc3DGMY" }, { "name": "LG", "web_id": "57gl2i88SZ" }, { "name": "XL", "web_id": "J7PFMLX9wA" } ] }, { "name": "Color", "web_id": "vVlmXsA2Bm", "product_variant_options": [ { "name": "Azul", "web_id": "Xe9QkMiD1i" }, { "name": "Negro", "web_id": "Y8zjQ7BPY4" } ] } ], "product_variant_combinations": [ { "web_id": "x0wsCBTIMI", "name": "SM/Azul", "price": "33.0", "wholesale_price": null, "sku": "SKU-EX1", "quantity": 10, "variant_option_web_ids": [ "3I6zc3DGMY", "Xe9QkMiD1i" ], "image": "https://dc2p3rqc7bvrd.cloudfront.net/uploads/1/product_variant_combination/x0wsCBTIMI/camisa-del-producto_40x403x.webp", "variant_url": null }, { "web_id": "y1xtDUITNJ", "name": "XL/Azul", "price": "33.0", "wholesale_price": null, "sku": "SKU-EX5", "quantity": 10, "variant_option_web_ids": [ "J7PFMLX9wA", "Xe9QkMiD1i" ], "image": "", "variant_url": null } ] } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Products" ], "summary": "Product", "description": "Borra un producto buscado su id", "operationId": "deleteProduct", "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Producto eliminado con éxito", "product": { "web_id": "tUCJZrCUs5", "title": "Abrigo borrego", "description": "Abrigo crema con lana de borrego.\r\nTallas: XS, S, M, L, XL, XXL.", "quantity": 41, "price": "8.0", "active": true, "url": null, "sku": "AB.577", "wholesale_price": "6.0", "images": [ "https://d3a4wxp51vazl1.cloudfront.net/uploads/506/product_attachment/tUCJZrCUs5/7-01.jpg", "https://d3a4wxp51vazl1.cloudfront.net/uploads/506/product_attachment/tUCJZrCUs5/8-01.jpg", "https://d3a4wxp51vazl1.cloudfront.net/uploads/506/product_attachment/tUCJZrCUs5/9-01.jpg" ], "subcategory": { "name": "Abrigos", "web_id": "EM5FJCF7sY" }, "category": { "name": "Abrigos y chaquetas", "web_id": "maFDOHylFB" } } } } } }, "400": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/v1/products/product_web_id/variants": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "post": { "operationId": "createVariant", "tags": [ "Product Variants" ], "summary": "Create Variant", "description": "Crea una nueva variante (ProductVariantCombination) para un producto existente.\n\n### Creación incremental\n\nEste endpoint permite agregar **una sola variante** a un producto sin afectar las variantes existentes.\n\n**Ideal para integraciones POS** que necesitan agregar SKUs uno por uno sin reenviar todo el catálogo.\n\n### Ejemplo: Crear variante con una opción\n{\n \"variant\": {\n \"option1\": \"XXL\",\n \"price\": 35.00,\n \"quantity\": 10,\n \"sku\": \"CAMISETA-XXL\"\n }\n}\n ### Ejemplo: Crear variante con múltiples opciones\n{\n \"variant\": {\n \"option1\": \"XXL\",\n \"option2\": \"Azul\",\n \"price\": 35.00,\n \"quantity\": 10,\n \"sku\": \"CAMISETA-XXL-AZUL\"\n }\n}\n ### Notas importantes\n- Los valores de `option1`, `option2`, `option3` deben existir en las opciones del producto.\n- Si la combinación ya existe, retorna error `409 Conflict`.\n- Las variantes existentes no se ven afectadas.\n", "parameters": [ { "name": "product_web_id", "in": "path", "required": true, "description": "El web_id del producto al que se agregará la variante", "schema": { "type": "string" }, "example": "FzOWVvUwbC" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "variant" ], "properties": { "variant": { "type": "object", "required": [ "option1" ], "properties": { "option1": { "type": "string", "description": "Valor de la primera opción (debe existir en el producto)", "example": "XXL" }, "option2": { "type": "string", "description": "Valor de la segunda opción (opcional)", "example": "Azul" }, "option3": { "type": "string", "description": "Valor de la tercera opción (opcional)", "example": "Algodón" }, "price": { "type": "number", "description": "Precio de venta", "example": 35 }, "wholesale_price": { "type": "number", "description": "Precio mayorista", "example": 28 }, "quantity": { "type": "integer", "description": "Cantidad en stock", "example": 10 }, "sku": { "type": "string", "description": "Código SKU único", "example": "CAMISETA-XXL-AZUL" }, "selling_without_stock": { "type": "boolean", "description": "Permitir venta sin stock", "example": false }, "variant_url": { "type": "string", "description": "URL de la variante", "example": "https://example.com/product?variant=123" } } } } } } } }, "security": [ { "api-key": [] } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Variante creada con éxito", "variant": { "web_id": "newVariantId", "name": "XXL/Azul", "price": "35.0", "wholesale_price": "28.0", "sku": "CAMISETA-XXL-AZUL", "quantity": 10, "variant_option_web_ids": [ "optionWebId1", "optionWebId2" ], "image": "", "variant_url": "https://example.com/product?variant=123" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "message": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "message": "Producto no encontrado" } } } }, "409": { "description": "Conflict - Combination already exists", "content": { "application/json": { "example": { "message": "La combinación ya existe", "errors": [ "Una variante con el nombre 'XXL/Azul' ya existe para este producto" ] } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "examples": { "invalid_options": { "summary": "Opciones inválidas", "value": { "message": "Opciones inválidas", "errors": [ "option1 'XXL' no existe en las opciones del producto" ] } }, "validation_error": { "summary": "Error de validación", "value": { "message": "No fue posible crear la variante", "errors": [ "Sku Ya está en uso" ] } } } } } } } } }, "/api/v1/variants/{web_id}": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "get": { "operationId": "getVariant", "tags": [ "Product Variants" ], "summary": "Get Variant", "description": "Obtiene una variante (ProductVariantCombination) por su web_id.\n\n### Consulta individual\n\nEste endpoint retorna **una sola variante** sin traer el producto completo.\n\n**Ideal para integraciones POS** que necesitan verificar el estado de una variante específica.\n", "parameters": [ { "name": "web_id", "in": "path", "required": true, "description": "El web_id de la variante a consultar", "schema": { "type": "string" }, "example": "x0wsCBTIMI" } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "variant": { "web_id": "x0wsCBTIMI", "name": "SM/Azul", "price": "100.0", "wholesale_price": "80.0", "sku": "VAR-SM-001", "quantity": 50, "variant_option_web_ids": [ "3I6zc3DGMY", "Xe9QkMiD1i" ], "image": "https://example.com/image.webp", "variant_url": "https://example.com/variant" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "message": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "message": "Variante no encontrada" } } } } } }, "patch": { "operationId": "updateVariant", "tags": [ "Product Variants" ], "summary": "Update Variant", "description": "Actualiza una variante (ProductVariantCombination) de forma parcial.\n\n### Actualización parcial\n\nEste endpoint permite actualizar **solo los campos enviados** sin afectar otros atributos de la variante, otras variantes del producto, ni el producto padre.\n\n**Ideal para integraciones POS** que necesitan actualizar precio o stock de una variante específica sin reenviar el producto completo.\n\n### Ejemplo: Actualizar solo el precio\n{\n \"variant\": {\n \"price\": 150.00\n }\n}\n ### Ejemplo: Actualizar precio y stock\n{\n \"variant\": {\n \"price\": 150.00,\n \"quantity\": 25\n }\n}\n ### Ejemplo: Actualizar múltiples atributos\n{\n \"variant\": {\n \"price\": 200.00,\n \"wholesale_price\": 150.00,\n \"quantity\": 100,\n \"sku\": \"NEW-SKU-001\",\n \"selling_without_stock\": true\n }\n}\n parameters:\n- name: web_id\n in: path\n required: true\n description: El web_id de la variante a actualizar\n schema:\n type: string\n example: \"x0wsCBTIMI\"\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "type": "object", "description": "Solo envía los campos que deseas actualizar", "properties": { "price": { "type": "number", "description": "Precio de venta", "example": 150 }, "wholesale_price": { "type": "number", "description": "Precio mayorista", "example": 120 }, "quantity": { "type": "integer", "description": "Cantidad en stock", "example": 50 }, "sku": { "type": "string", "description": "Código SKU único", "example": "VAR-SM-001" }, "selling_without_stock": { "type": "boolean", "description": "Permitir venta sin stock", "example": false }, "variant_url": { "type": "string", "description": "URL de la variante", "example": "https://example.com/product?variant=123" }, "image": { "type": "string", "format": "binary", "description": "Imagen de la variante" } } } } } } } }, "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Variante actualizada con éxito", "variant": { "web_id": "x0wsCBTIMI", "name": "SM/Azul", "price": "150.0", "wholesale_price": "120.0", "sku": "VAR-SM-001", "quantity": 50, "variant_option_web_ids": [ "3I6zc3DGMY", "Xe9QkMiD1i" ], "image": "https://dc2p3rqc7bvrd.cloudfront.net/uploads/1/product_variant_combination/x0wsCBTIMI/image.webp", "variant_url": "https://example.com/product?variant=123" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "message": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "message": "Variante no encontrada" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "example": { "message": "No fue posible actualizar la variante", "errors": [ "Sku Ya está en uso" ] } } } } } }, "delete": { "operationId": "deleteVariant", "tags": [ "Product Variants" ], "summary": "Delete Variant", "description": "Elimina una variante (ProductVariantCombination) de forma explícita.\n\n### Borrado inteligente\n\nEste endpoint elimina **solo la variante indicada** sin afectar otras variantes del producto ni el producto padre.\n\n**Comportamiento según integridad:**\n- Si la variante **no tiene** órdenes asociadas → **Hard delete** (eliminación permanente)\n- Si la variante **tiene** órdenes asociadas → **Soft delete** (marca `deleted_at`, preserva historial)\n\n**Ideal para integraciones POS** que necesitan eliminar SKUs descontinuados sin afectar el catálogo completo.\n\n### Notas importantes\n- El producto padre permanece intacto\n- Las demás variantes no se ven afectadas\n- Los `ProductVariant` y `ProductVariantOption` no se eliminan\n- El borrado es **explícito**, nunca por omisión\n", "parameters": [ { "name": "web_id", "in": "path", "required": true, "description": "El web_id de la variante a eliminar", "schema": { "type": "string" }, "example": "x0wsCBTIMI" } ], "security": [ { "api-key": [] } ], "responses": { "204": { "description": "No Content - Variante eliminada exitosamente" }, "401": { "description": "Unauthorized", "content": { "application/json": { "example": { "message": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "example": { "message": "Variante no encontrada" } } } }, "422": { "description": "Unprocessable Entity - No se pudo eliminar por restricciones de integridad", "content": { "application/json": { "example": { "message": "No fue posible eliminar la variante", "errors": [ "La variante tiene dependencias que impiden su eliminación" ] } } } } } } }, "/api/v1/categories": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "get": { "tags": [ "Categories" ], "summary": "List Categories", "description": "Obtén los datos de tus categorías con sus subcategorías", "operationId": "listCategories", "parameters": [ { "name": "page", "in": "query", "description": "Número de página para la paginación", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "web_id": { "type": "string", "description": "Identificador único de la categoría", "example": "ljsJpi0fTR" }, "name": { "type": "string", "description": "Nombre de la categoría", "example": "Tecnología" }, "description": { "type": "string", "description": "Descripción de la categoría", "example": "" }, "products_count": { "type": "integer", "description": "Número de productos activos en la categoría", "example": 7 }, "order": { "type": "integer", "description": "Orden de visualización de la categoría", "example": 1 }, "subcategories": { "type": "array", "description": "Lista de subcategorías", "items": { "type": "object", "properties": { "web_id": { "type": "string", "description": "Identificador único de la subcategoría", "example": "GETPvRKnBD" }, "name": { "type": "string", "description": "Nombre de la subcategoría", "example": "Alámbricos" }, "description": { "type": "string", "description": "Descripción de la subcategoría", "example": "" }, "products_count": { "type": "integer", "description": "Número de productos activos en la subcategoría", "example": 3 }, "order": { "type": "integer", "description": "Orden de visualización de la subcategoría", "example": 1 } } } } } } }, "total_pages": { "type": "integer", "description": "Total de páginas disponibles", "example": 1 } } }, "examples": { "response": { "value": { "categories": [ { "web_id": "ljsJpi0fTR", "name": "Tecnología", "description": "", "products_count": 7, "order": 1, "subcategories": [ { "web_id": "GETPvRKnBD", "name": "Alámbricos", "description": "", "products_count": 3, "order": 1 }, { "web_id": "8Kncn44rQD", "name": "3 en 1", "description": "", "products_count": 4, "order": 2 } ] } ], "total_pages": 1 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Resource not found" } } } } } } } }, "post": { "tags": [ "Categories" ], "summary": "Create Category", "description": "Crea una nueva categoría con sus subcategorías", "operationId": "createCategory", "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category" ], "properties": { "category": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Nombre de la categoría (requerido)", "example": "Electrónica" }, "description": { "type": "string", "maxLength": 250, "description": "Descripción de la categoría (máximo 250 caracteres)", "example": "Productos electrónicos y dispositivos tecnológicos" }, "order": { "type": "integer", "description": "Orden de visualización. Si no se proporciona, se asigna automáticamente", "example": 1 }, "subcategories_attributes": { "type": "array", "description": "Array de subcategorías a crear", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Nombre de la subcategoría (requerido)", "example": "Smartphones" }, "description": { "type": "string", "description": "Descripción de la subcategoría", "example": "Teléfonos inteligentes y accesorios" }, "order": { "type": "integer", "description": "Orden de visualización", "example": 1 } } } } } } } }, "examples": { "create_with_subcategories": { "value": { "category": { "name": "Electrónica", "description": "Productos electrónicos y dispositivos tecnológicos", "order": 1, "subcategories_attributes": [ { "name": "Smartphones", "description": "Teléfonos inteligentes y accesorios", "order": 1 }, { "name": "Laptops", "description": "Computadoras portátiles", "order": 2 } ] } } } } } } }, "responses": { "200": { "description": "Category created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "web_id": { "type": "string", "description": "Identificador único de la categoría", "example": "I7ROmS7Jui" }, "name": { "type": "string", "description": "Nombre de la categoría", "example": "Electrónica" }, "description": { "type": "string", "description": "Descripción de la categoría", "example": "Productos electrónicos y dispositivos tecnológicos" }, "products_count": { "type": "integer", "description": "Número de productos activos en la categoría", "example": 0 }, "order": { "type": "integer", "description": "Orden de visualización de la categoría", "example": 1 }, "subcategories": { "type": "array", "description": "Lista de subcategorías", "items": { "type": "object", "properties": { "web_id": { "type": "string", "example": "bas9UxSaUq" }, "name": { "type": "string", "example": "Smartphones" }, "description": { "type": "string", "example": "Teléfonos inteligentes y accesorios" }, "products_count": { "type": "integer", "example": 0 }, "order": { "type": "integer", "example": 1 } } } } } }, "examples": { "success": { "value": { "web_id": "I7ROmS7Jui", "name": "Electrónica", "description": "Productos electrónicos y dispositivos tecnológicos", "products_count": 0, "order": 1, "subcategories": [ { "web_id": "bas9UxSaUq", "name": "Smartphones", "description": "Teléfonos inteligentes y accesorios", "products_count": 0, "order": 1 }, { "web_id": "VqpkV7TLd5", "name": "Laptops", "description": "Computadoras portátiles", "products_count": 0, "order": 2 } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } }, "examples": { "validation_error": { "value": { "errors": [ "Name can't be blank" ] } } } } } } } } }, "/api/v1/categories/web_id": { "servers": [ { "url": "https://mercately.shop", "description": "Shops API Production server" } ], "put": { "tags": [ "Categories" ], "summary": "Update Category", "description": "Actualiza una categoría existente y sus subcategorías. Puedes actualizar, crear o eliminar subcategorías.", "operationId": "updateCategory", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Web ID de la categoría", "schema": { "type": "string", "example": "I7ROmS7Jui" } } ], "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category" ], "properties": { "category": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre de la categoría", "example": "Electrónica" }, "description": { "type": "string", "maxLength": 250, "description": "Descripción de la categoría (máximo 250 caracteres)", "example": "Productos electrónicos actualizados" }, "order": { "type": "integer", "description": "Orden de visualización", "example": 1 }, "subcategories_attributes": { "type": "array", "description": "Array de subcategorías. \n- Para actualizar: incluye el campo 'id' con el web_id de la subcategoría\n- Para crear: omite el campo 'id'\n- Para eliminar: incluye el campo 'id' y '_destroy: true'\n", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Web ID de la subcategoría (requerido para actualizar o eliminar)", "example": "bas9UxSaUq" }, "name": { "type": "string", "description": "Nombre de la subcategoría", "example": "Smartphones" }, "description": { "type": "string", "description": "Descripción de la subcategoría", "example": "Teléfonos inteligentes actualizados" }, "order": { "type": "integer", "description": "Orden de visualización", "example": 1 }, "_destroy": { "type": "boolean", "description": "Si es true, elimina la subcategoría", "example": false } } } } } } } }, "examples": { "update_with_subcategories": { "value": { "category": { "name": "Electrónica", "description": "Productos electrónicos actualizados", "order": 1, "subcategories_attributes": [ { "web_id": "bas9UxSaUq", "name": "Smartphones", "description": "Teléfonos inteligentes actualizados", "order": 1 }, { "web_id": "VqpkV7TLd5", "name": "Laptops", "description": "Computadoras portátiles actualizadas", "order": 2 } ] } } }, "delete_subcategory": { "value": { "category": { "name": "Electrónica", "subcategories_attributes": [ { "id": "bas9UxSaUq", "_destroy": true } ] } } } } } } }, "responses": { "200": { "description": "Category updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "web_id": { "type": "string", "description": "Identificador único de la categoría", "example": "I7ROmS7Jui" }, "name": { "type": "string", "description": "Nombre de la categoría", "example": "Electrónica" }, "description": { "type": "string", "description": "Descripción de la categoría", "example": "Productos electrónicos actualizados" }, "products_count": { "type": "integer", "description": "Número de productos activos en la categoría", "example": 7 }, "order": { "type": "integer", "description": "Orden de visualización de la categoría", "example": 1 }, "subcategories": { "type": "array", "description": "Lista de subcategorías", "items": { "type": "object", "properties": { "web_id": { "type": "string", "example": "bas9UxSaUq" }, "name": { "type": "string", "example": "Smartphones" }, "description": { "type": "string", "example": "Teléfonos inteligentes actualizados" }, "products_count": { "type": "integer", "example": 3 }, "order": { "type": "integer", "example": 1 } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Resource not found" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } }, "examples": { "validation_error": { "value": { "errors": [ "Name can't be blank" ] } } } } } } } }, "patch": { "tags": [ "Categories" ], "summary": "Update Category (Partial)", "description": "Actualiza parcialmente una categoría existente", "operationId": "patchCategory", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Web ID de la categoría", "schema": { "type": "string", "example": "I7ROmS7Jui" } } ], "security": [ { "api-key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category" ], "properties": { "category": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre de la categoría", "example": "Electrónica" }, "description": { "type": "string", "maxLength": 250, "description": "Descripción de la categoría (máximo 250 caracteres)", "example": "Productos electrónicos actualizados" }, "order": { "type": "integer", "description": "Orden de visualización", "example": 1 }, "subcategories_attributes": { "type": "array", "description": "Array de subcategorías", "items": { "type": "object", "properties": { "web_id": { "type": "string", "description": "Web ID de la subcategoría", "example": "bas9UxSaUq" }, "name": { "type": "string", "description": "Nombre de la subcategoría", "example": "Smartphones" }, "description": { "type": "string", "description": "Descripción de la subcategoría", "example": "Teléfonos inteligentes actualizados" }, "order": { "type": "integer", "description": "Orden de visualización", "example": 1 }, "_destroy": { "type": "boolean", "description": "Si es true, elimina la subcategoría", "example": false } } } } } } } } } } }, "responses": { "200": { "description": "Category updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "web_id": { "type": "string", "example": "I7ROmS7Jui" }, "name": { "type": "string", "example": "Electrónica" }, "description": { "type": "string", "example": "Productos electrónicos actualizados" }, "products_count": { "type": "integer", "example": 7 }, "order": { "type": "integer", "example": 1 }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "web_id": { "type": "string", "example": "bas9UxSaUq" }, "name": { "type": "string", "example": "Smartphones" }, "description": { "type": "string", "example": "Teléfonos inteligentes actualizados" }, "products_count": { "type": "integer", "example": 3 }, "order": { "type": "integer", "example": 1 } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Resource not found" } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } } } } } }, "delete": { "tags": [ "Categories" ], "summary": "Delete Category", "description": "Elimina una categoría y todas sus subcategorías", "operationId": "deleteCategory", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Web ID de la categoría", "schema": { "type": "string", "example": "I7ROmS7Jui" } } ], "security": [ { "api-key": [] } ], "responses": { "200": { "description": "Category deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "web_id": { "type": "string", "example": "I7ROmS7Jui" }, "name": { "type": "string", "example": "Electrónica" }, "description": { "type": "string", "example": "Productos electrónicos y dispositivos tecnológicos" }, "products_count": { "type": "integer", "example": 0 }, "order": { "type": "integer", "example": 1 }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "web_id": { "type": "string", "example": "bas9UxSaUq" }, "name": { "type": "string", "example": "Smartphones" }, "description": { "type": "string", "example": "Teléfonos inteligentes y accesorios" }, "products_count": { "type": "integer", "example": 0 }, "order": { "type": "integer", "example": 1 } } } } } }, "examples": { "response": { "value": { "web_id": "I7ROmS7Jui", "name": "Electrónica", "description": "Productos electrónicos y dispositivos tecnológicos", "products_count": 0, "order": 1, "subcategories": [ { "web_id": "bas9UxSaUq", "name": "Smartphones", "description": "Teléfonos inteligentes y accesorios", "products_count": 0, "order": 1 } ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "404": { "description": "Category not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Resource not found" } } } } } } } } } }, "components": { "securitySchemes": { "api-key": { "type": "apiKey", "name": "api-key", "in": "header", "description": "API Key authentication" } }, "schemas": { "agents": { "type": "object", "title": "Agent", "properties": { "id": { "type": "integer", "example": 9 }, "first_name": { "type": "string", "example": "Nicolas" }, "last_name": { "type": "string", "example": "Mena Garzon" }, "email": { "type": "string", "example": "nicolas@mercately.com" }, "active": { "type": "boolean", "example": true }, "agent": { "type": "boolean", "example": false }, "admin": { "type": "boolean", "example": true }, "supervisor": { "type": "boolean", "example": true } } }, "customer": { "type": "object", "title": "Customer", "properties": { "id": { "type": "string", "description": "ID único del cliente (web_id)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "id_type": { "type": "string", "enum": [ "cedula", "pasaporte", "ruc", "rut", "otro" ] }, "id_number": { "type": "string" }, "address": { "type": "string", "description": "Dirección individual del cliente" }, "city": { "type": "string", "description": "Ciudad individual del cliente" }, "state": { "type": "string", "description": "Estado/Provincia individual del cliente" }, "zip_code": { "type": "string", "description": "Código postal individual del cliente" }, "country_id": { "type": "string", "description": "ID del país del cliente" }, "notes": { "type": "string" }, "whatsapp_opt_in": { "type": "boolean", "description": "Si el cliente ha optado por recibir mensajes de WhatsApp" }, "whatsapp_name": { "type": "string", "description": "Nombre del cliente en WhatsApp" }, "customer_addresses": { "type": "array", "description": "Array de direcciones adicionales del cliente", "items": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "description": { "type": "string" }, "main": { "type": "boolean" } } } }, "tags": { "type": "array", "description": "Array de etiquetas del cliente", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Nombre de la etiqueta" }, "web_id": { "type": "string", "description": "ID único de la etiqueta" } } } }, "custom_fields": { "type": "array", "description": "Array de campos personalizados del cliente", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "Identificador del campo personalizado" }, "field_content": { "type": "string", "description": "Contenido del campo personalizado" } } } }, "agent": { "type": "object", "description": "Agente asignado al cliente", "properties": { "id": { "type": "integer", "description": "ID del agente" }, "email": { "type": "string", "description": "Email del agente" } } }, "outbound_status": { "type": "string", "enum": [ "error", "submitted", "enqueued", "sent", "delivered", "read" ], "description": "Estado del último mensaje outbound enviado al cliente" }, "campaign_id": { "type": "integer", "description": "ID de la campaña asociada al cliente" }, "error_message": { "type": "string", "description": "Mensaje de error si hubo un problema con el último mensaje enviado" }, "campaign_url": { "type": "string", "description": "URL de la campaña asociada (vacío si no hay campaña)" }, "creation_date": { "type": "string", "format": "date-time", "description": "Fecha de creación del cliente" }, "sent_at": { "type": "string", "format": "date-time", "description": "Fecha en que se envió el último mensaje outbound" }, "delivered_at": { "type": "string", "format": "date-time", "description": "Fecha en que se entregó el último mensaje outbound" }, "read_at": { "type": "string", "format": "date-time", "description": "Fecha en que se leyó el último mensaje outbound" }, "last_chat_interaction": { "type": "string", "format": "date-time", "description": "Fecha de la última interacción en el chat" } } }, "get_customer": { "type": "object", "properties": { "message": { "type": "string", "example": "Customer found successfully" }, "customer": { "$ref": "#/components/schemas/customer" } } }, "update_customer": { "type": "object", "title": "UpdateCustomerRequest", "properties": { "customer": { "type": "object", "title": "Customer", "properties": { "first_name": { "type": "string", "description": "Nombre del cliente" }, "last_name": { "type": "string", "description": "Apellido del cliente" }, "email": { "type": "string", "description": "Email del cliente" }, "phone": { "type": "string", "description": "Teléfono del cliente" }, "id_type": { "type": "string", "enum": [ "cedula", "pasaporte", "ruc", "rut", "otro" ], "description": "Tipo de documento de identificación" }, "id_number": { "type": "string", "description": "Número de documento de identificación" }, "address": { "type": "string", "description": "Dirección del cliente" }, "city": { "type": "string", "description": "Ciudad del cliente" }, "state": { "type": "string", "description": "Estado/Provincia del cliente" }, "zip_code": { "type": "string", "description": "Código postal del cliente" }, "customer_addresses_attributes": { "type": "array", "description": "Array de direcciones adicionales del cliente", "items": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "country_id": { "type": "integer" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "description": { "type": "string" }, "main": { "type": "boolean" } } } }, "notes": { "type": "string", "description": "Notas sobre el cliente" } } }, "agent_id": { "type": "integer", "description": "ID del agente asignado al cliente (puede estar en nivel raíz o dentro de customer)" }, "tags": { "type": "array", "description": "Array de etiquetas del cliente (puede estar en nivel raíz o dentro de customer)", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre de la etiqueta" }, "value": { "type": "boolean", "description": "true para asignar la etiqueta, false para removerla" } } } }, "custom_fields": { "type": "array", "description": "Array de campos personalizados del cliente (puede estar en nivel raíz o dentro de customer)", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "Identificador del campo personalizado" }, "field_content": { "type": "string", "description": "Contenido del campo personalizado" } } } } } }, "update_customer-2": { "type": "object", "title": "UpdateCustomerResponse", "properties": { "message": { "type": "string", "description": "Mensaje de confirmación", "example": "Customer updated successfully" }, "customer": { "type": "object", "title": "Customer", "properties": { "id": { "type": "string", "description": "ID único del cliente (web_id)" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "id_type": { "type": "string", "enum": [ "cedula", "pasaporte", "ruc", "rut", "otro" ] }, "id_number": { "type": "string" }, "address": { "type": "string", "description": "Dirección individual del cliente" }, "city": { "type": "string", "description": "Ciudad individual del cliente" }, "state": { "type": "string", "description": "Estado/Provincia individual del cliente" }, "zip_code": { "type": "string", "description": "Código postal individual del cliente" }, "country_id": { "type": "string", "description": "ID del país del cliente" }, "notes": { "type": "string" }, "whatsapp_opt_in": { "type": "boolean", "description": "Si el cliente ha optado por recibir mensajes de WhatsApp" }, "whatsapp_name": { "type": "string", "description": "Nombre del cliente en WhatsApp" }, "customer_addresses": { "type": "array", "description": "Array de direcciones adicionales del cliente", "items": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip_code": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "description": { "type": "string" }, "main": { "type": "boolean" } } } }, "tags": { "type": "array", "description": "Array de etiquetas del cliente", "items": { "type": "object", "properties": { "tag": { "type": "string", "description": "Nombre de la etiqueta" }, "web_id": { "type": "string", "description": "ID único de la etiqueta" } } } }, "custom_fields": { "type": "array", "description": "Array de campos personalizados del cliente", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "Identificador del campo personalizado" }, "field_content": { "type": "string", "description": "Contenido del campo personalizado" } } } }, "agent": { "type": "object", "description": "Agente asignado al cliente", "properties": { "id": { "type": "integer", "description": "ID del agente" }, "email": { "type": "string", "description": "Email del agente" } } }, "outbound_status": { "type": "string", "enum": [ "error", "submitted", "enqueued", "sent", "delivered", "read" ], "description": "Estado del último mensaje outbound enviado al cliente" }, "campaign_id": { "type": "integer", "description": "ID de la campaña asociada al cliente" }, "error_message": { "type": "string", "description": "Mensaje de error si hubo un problema con el último mensaje enviado" }, "campaign_url": { "type": "string", "description": "URL de la campaña asociada (vacío si no hay campaña)" }, "creation_date": { "type": "string", "format": "date-time", "description": "Fecha de creación del cliente" }, "sent_at": { "type": "string", "format": "date-time", "description": "Fecha en que se envió el último mensaje outbound" }, "delivered_at": { "type": "string", "format": "date-time", "description": "Fecha en que se entregó el último mensaje outbound" }, "read_at": { "type": "string", "format": "date-time", "description": "Fecha en que se leyó el último mensaje outbound" }, "last_chat_interaction": { "type": "string", "format": "date-time", "description": "Fecha de la última interacción en el chat" } } } } }, "customer_event": { "type": "object", "title": "CreateCustomerEventRequest", "required": [ "customer_event" ], "properties": { "customer_event": { "type": "object", "title": "CustomerEvent", "required": [ "category", "subcategory", "action" ], "properties": { "category": { "type": "string", "description": "Categoría del evento", "example": "purchase" }, "subcategory": { "type": "string", "description": "Subcategoría del evento", "example": "order_placed" }, "action": { "type": "string", "description": "Acción del evento", "example": "created" }, "type_event": { "type": "string", "description": "Tipo de evento (opcional)", "example": "order" }, "source": { "type": "string", "description": "Fuente del evento (opcional)", "example": "api" }, "url_spec": { "type": "string", "description": "URL específica relacionada con el evento (opcional)", "example": "https://example.com/order/123" }, "created_at": { "type": "string", "format": "date-time", "description": "Fecha y hora de creación del evento (opcional). Si no se proporciona, se usa la fecha actual", "example": "2024-01-15T10:30:00Z" } } } } }, "create_customer_event": { "type": "object", "properties": { "messages": { "type": "string", "example": "Customer event created successfully" } } }, "whatsapp_api_message": { "type": "object", "title": "SendWhatsAppNotificationByIdResponse", "properties": { "message": { "type": "string", "description": "Mensaje de confirmación", "example": "Ok" }, "info": { "type": "object", "title": "MessageInfo", "properties": { "channel": { "type": "string", "description": "Canal del mensaje", "example": "whatsapp" }, "content": { "type": "object", "title": "MessageContent", "properties": { "text": { "type": "string", "description": "Texto del mensaje enviado", "example": "Your OTP for test 1 is test 2. This is valid for test 3." }, "media_url": { "type": "string", "description": "URL del archivo multimedia (solo si se envió media)", "example": "https://mercately.com/example.png" } } }, "direction": { "type": "string", "description": "Dirección del mensaje", "example": "outbound" }, "status": { "type": "string", "description": "Estado del mensaje", "example": "submitted" }, "destination": { "type": "string", "description": "Número de teléfono de destino", "example": "+593999999999" }, "country": { "type": "string", "description": "Código de país del destinatario", "example": "EC" }, "created_time": { "type": "string", "format": "date-time", "description": "Fecha y hora de creación del mensaje", "example": "2022-09-23T16:34:16.768-04:00" }, "error": { "type": [ "null", "string" ], "description": "Mensaje de error (null si no hay error)", "example": null } } } } }, "messenger_message": { "type": "object", "title": "MessengerConversationsResponse", "properties": { "facebook_messages": { "type": "array", "description": "Array de mensajes de Messenger del cliente", "items": { "type": "object", "title": "FacebookMessage", "properties": { "id": { "type": "string", "description": "ID del mensaje" }, "customer_id": { "type": "integer", "description": "ID del cliente" }, "text": { "type": "string", "description": "Texto del mensaje" }, "created_at": { "type": "string", "format": "date-time", "description": "Fecha y hora de creación del mensaje" }, "sent_by_retailer": { "type": "boolean", "description": "Si el mensaje fue enviado por el retailer" }, "file_type": { "type": "string", "description": "Tipo de archivo (si aplica)" }, "mid": { "type": "string", "description": "ID del mensaje en Facebook" }, "message_identifier": { "type": "string", "description": "Identificador del mensaje" }, "note": { "type": "string", "description": "Nota asociada al mensaje" }, "order_note": { "type": "string", "description": "Nota de orden asociada" }, "order_summary": { "type": "string", "description": "Resumen de orden asociado" }, "replied_message": { "type": "object", "description": "Mensaje al que se está respondiendo (objeto completo del mensaje respondido, solo si existe)" }, "error_message": { "type": "string", "description": "Mensaje de error (si aplica)" }, "internal_url": { "type": "string", "description": "URL interna del archivo" }, "payload": { "type": "object", "description": "Payload del mensaje" }, "mia_flag": { "type": "boolean", "description": "Flag de MIA" }, "sent_by_mia": { "type": "boolean", "description": "Si el mensaje fue enviado por MIA" }, "mia_client_data": { "type": "boolean", "description": "Datos de cliente MIA" }, "customer_related_data": { "type": "array", "description": "Datos relacionados del cliente" }, "customer_tags": { "type": "array", "description": "Etiquetas del cliente" }, "mia_assignment": { "type": "boolean", "description": "Asignación MIA" }, "assignment_data": { "type": "object", "description": "Datos de asignación" }, "event_data": { "type": "object", "description": "Datos del evento" }, "mia_event": { "type": "boolean", "description": "Evento MIA" }, "sender_full_name": { "type": "string", "description": "Nombre completo del remitente (solo si fue enviado desde Mercately)" }, "filename": { "type": "string", "description": "Nombre del archivo (solo si hay file_type)" }, "url": { "type": "string", "description": "URL del archivo (solo si hay file_type)" }, "date_read": { "type": "string", "format": "date-time", "description": "Fecha en que se leyó el mensaje (solo si sent_by_retailer es true)" } } } }, "total_pages": { "type": "integer", "description": "Número total de páginas", "example": 1 } } }, "get_customer_event": { "type": "object", "properties": { "results": { "type": "integer", "description": "Número total de eventos", "example": 10 }, "total_pages": { "type": "integer", "description": "Número total de páginas", "example": 2 }, "customer_events": { "type": "array", "description": "Array de eventos del cliente", "items": { "type": "object", "title": "CustomerEvent", "properties": { "category": { "type": "string", "description": "Categoría del evento", "example": "purchase" }, "subcategory": { "type": "string", "description": "Subcategoría del evento", "example": "order_placed" }, "event": { "type": "string", "description": "Acción del evento", "example": "created" }, "creation_date": { "type": "string", "description": "Fecha y hora de creación del evento (formato: DD-MM-YYYY HH:MM)", "example": "15-01-2024 10:30" }, "agent": { "type": "string", "description": "Nombre del agente asociado al evento", "example": "John Doe" } } } } } }, "agent": { "type": "object", "title": "Agent", "properties": { "id": { "type": "integer", "example": 9 }, "first_name": { "type": "string", "example": "Nicolas" }, "last_name": { "type": "string", "example": "Mena Garzon" }, "email": { "type": "string", "example": "nicolas@mercately.com" }, "active": { "type": "boolean", "example": true }, "agent": { "type": "boolean", "example": false }, "admin": { "type": "boolean", "example": true }, "supervisor": { "type": "boolean", "example": true } } }, "customer_lite": { "type": "object", "title": "CustomerLite", "properties": { "id": { "type": "string", "example": "91989a87" }, "first_name": { "type": "string", "example": "javier" }, "last_name": { "type": "string", "example": "Salinas" }, "email": { "type": "string", "format": "email", "example": "javier@example.com" }, "phone": { "type": "string", "example": 5933505692996 } } }, "deal": { "type": "object", "properties": { "id": { "type": "string", "example": "9fb882221" }, "name": { "type": "string", "example": "Neptu" }, "amount": { "type": "string", "example": "150000.0" }, "currency": { "type": "string", "example": "$" }, "funnel_name": { "type": "string", "example": "Negociaciones" }, "stage": { "type": "string", "example": "Calificado!" }, "agent": { "$ref": "#/components/schemas/agent" }, "customer": { "$ref": "#/components/schemas/customer_lite" }, "channel": { "type": [ "string", "null" ] } } }, "index": { "type": "object", "properties": { "total": { "type": "integer", "example": 2 }, "total_page": { "type": "integer", "example": 1 }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/deal" } } } }, "create": { "type": "object", "properties": { "message": { "type": "string", "example": "deal was created successfully" }, "deal": { "$ref": "#/components/schemas/deal" } } }, "get": { "type": "object", "properties": { "message": { "type": "string", "example": "deal found successfully" }, "deal": { "$ref": "#/components/schemas/deal" } } }, "update": { "type": "object", "properties": { "message": { "type": "string", "example": "deal was updated successfully" }, "deal": { "$ref": "#/components/schemas/deal" } } }, "send_api_message": { "type": "object", "title": "SendWhatsAppNotificationByIdRequest", "required": [ "phone_number", "internal_id", "template_params" ], "properties": { "phone_number": { "type": "string", "description": "Número de teléfono del destinatario (formato internacional con +)", "example": "+593999999999" }, "internal_id": { "type": "string", "description": "ID interno del template de WhatsApp (gupshup_template_id)", "example": "997dd550-c8d8-4bf7-ad98-a5ac4844a1ed" }, "template_params": { "type": "array", "description": "Array de parámetros para rellenar el template", "items": { "type": "string" }, "example": [ "test 1", "test 2", "test 3" ] }, "media_url": { "type": "string", "description": "URL del archivo multimedia (solo si el template incluye media)", "example": "https://mercately.com/example.png" }, "agent_id": { "type": "integer", "description": "ID del agente al que se asignará el cliente", "example": 980 }, "tags": { "type": "array", "description": "Array de etiquetas para asignar al cliente", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre de la etiqueta" }, "value": { "type": "boolean", "description": "true para asignar la etiqueta, false para removerla" } }, "example": [ { "name": "at", "value": true } ] } } } }, "send_qr_message": { "type": "object", "title": "SendWhatsAppQrMessageRequest", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "description": "Número de teléfono del destinatario (formato internacional con +)", "example": "+593999999999" }, "message": { "type": "string", "description": "Mensaje de texto a enviar (requerido si no se envía media_url)", "example": "Hello, this is a test message" }, "media_url": { "type": "string", "description": "URL del archivo multimedia (requerido si no se envía message). Solo se permiten imágenes JPG/JPEG/PNG y archivos PDF", "example": "https://mercately.com/example.png" }, "first_name": { "type": "string", "description": "Nombre del cliente (opcional)", "example": "John" }, "last_name": { "type": "string", "description": "Apellido del cliente (opcional)", "example": "Doe" }, "email": { "type": "string", "description": "Email del cliente (opcional)", "example": "john@example.com" }, "address": { "type": "string", "description": "Dirección del cliente (opcional)", "example": "123 Main St" }, "city": { "type": "string", "description": "Ciudad del cliente (opcional)", "example": "Quito" }, "state": { "type": "string", "description": "Estado/Provincia del cliente (opcional)", "example": "Pichincha" }, "zip_code": { "type": "string", "description": "Código postal del cliente (opcional)", "example": "170101" }, "notes": { "type": "string", "description": "Notas sobre el cliente (opcional)", "example": "Customer notes" }, "agent_id": { "type": "integer", "description": "ID del agente al que se asignará el cliente (opcional)", "example": 980 }, "tags": { "type": "array", "description": "Array de etiquetas para asignar al cliente (opcional)", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nombre de la etiqueta" }, "value": { "type": "boolean", "description": "true para asignar la etiqueta, false para removerla" } } }, "example": [ { "name": "at", "value": true } ] }, "custom_fields": { "type": "array", "description": "Array de campos personalizados del cliente (opcional)", "items": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Identificador del campo personalizado" }, "value": { "type": "string", "description": "Valor del campo personalizado" } } }, "example": [ { "identifier": "custom_field_1", "value": "Some value" } ] }, "funnel_name": { "type": "string", "description": "Nombre del embudo para crear un deal (opcional, requiere stage)", "example": "Sales Funnel" }, "stage": { "type": "string", "description": "Etapa del embudo para crear un deal (opcional, requiere funnel_name)", "example": "Lead" } } }, "flow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "integer", "example": 2 }, "enabled": { "type": "boolean" }, "whatsapp": { "type": "boolean" }, "messenger": { "type": "boolean" }, "instagram": { "type": "boolean" } } }, "get_flows": { "type": "object", "properties": { "results": { "type": "integer", "example": 1 }, "total_pages": { "type": "integer", "example": 1 }, "flows": { "type": "array", "items": { "$ref": "#/components/schemas/flow" } } } }, "deactivate_flows": { "type": "object", "properties": { "message": { "type": "string", "example": "Flows by platform successfully deactivated" }, "info": { "type": "object", "properties": { "data": { "type": "object" } }, "example": { "data": {} } } } }, "pre_activate_flow": { "type": "object", "properties": { "message": { "type": "string", "example": "Flow successfully preactivated" }, "info": { "type": "array" } } } } } }