Documentación

Autenticación

La autenticación permite el intercambio seguro de datos. La estructura de datos de autenticación es la siguiente:
Estructura de la petición

Tipo: POST

Tabla de parámetros
Parámetro Tipo Descripción
headers array Arreglo con la estructura de los encabezados de la petición
auth array Arreglo con la estructura de la autenticación del usuario
user_key int Clave de usuario de Zegucom Cómputo
password string Contraseña de API Zegucom
Estructura de la petición JSON
    {
    "headers" : {
        "auth" : {
            "user_key" : 999999,
            "password" : "XXXXXX"
            }
        },
    }
Respuesta de la petición

Tipo: JSON

Si la autenticación es correcta, no recibirás una respuesta directa de ello, en lugar de eso, se ejecutará el servicio especificado.

Si la autenticación falla, recibirás el código de error 202 y uno de los siguientes mensajes:

  • Request key is required and must be an array: El parámetro request no existe o está vacío. Debes hacer una petición para poder autenticarte.
  • Authentication failed. Incorrect password: La contraseña de API no es correcta
  • Authentication failed. User key not found: La clave de usuario no existe

Consultar producto

El servicio de productos permite obtener un listado de uno o más productos del inventario.
URL
https://api.zegucom.com.mx/services/get-product
URL de prueba
https://api.test.zegucom.com.mx/services/get-product
Estructura de la petición

Tipo: POST

Tabla de parámetros
Nombre Tipo Descripción
ignore_message bool (Opcional) Si es TRUE regresa un código 200 cuando la existencia es 0 y la clave existe
items array Arreglo de la estructura del listado de productos (Debe contener hasta 50 elementos por petición)
code string Clave del producto
store Int Clave de almacen del producto
El parámetro store también puede ser null, esto regresará la disponibilidad del producto en los almacenes autorizados de su cuenta.
Estructura de la petición JSON
Estructura de la petición para un solo producto. 
    {
        "headers" : {
            "auth" : {
                "user_key" : 123456,
                "password" : "XXXXX"
            }
        },
        "request" : {
            "items" : [
                {
                    "code" : "SA5DS1D5152",
                    "store" : 1
                }
            ]
        }
    }
Estructura de la petición para un solo producto con ignore_message. 
    {
        "headers" : {
            "auth" : {
                "user_key" : 123456,
                "password" : "XXXXX"
            }
        },
        "request" : {
            "ignore_message" : true,
            "items" : [
                {
                    "code" : "SA5DS1D5152",
                    "store" : 1
                }
            ]
        }
    }
Estructura de la petición para varios productos. 
    {
        "headers" : {
            "auth" : {
                "user_key" : 123456,
                "password" : "XXXXX"
            }
        },
        "request" : {
            "items" : [
                {
                    "code" : "SA5DS1D5152",
                    "store" : 1
                },
                {
                    "code" : "QWWW6QR7RR88R",
                    "store" : 4
                },
                {
                    "code" : "SA5DHJJKK52",
                    "store" : 1
                }
            ]
        }
    }
Respuesta de la petición

Tipo: JSON

La estructura de la respuesta dependerá del tipo de petición enviada (uno o varios productos).
Tabla de parámetros
Nombre Tipo Descripción
response array Arreglo de la estructura de la respuesta
result bool Indicador de estatus de transacción, TRUE si fue exitosa, FALSE en cualquier otro caso
message string Mensaje de éxito de transacción
data array Arreglo con la estructura de los datos del producto o los productos
code string Clave del producto
part_number string Número de parte del producto
upc string UPC del producto
description string Descripción del producto
brand string Marca del producto
price string Precio del producto * Sin IVA
store array Arreglo con la estructura de los datos de las existencias del producto donde la llave es la clave de la sucursal y el valor es el número de existencias en esta sucursal
A continuación se muestra la estructura de una respuesta exitosa de un solo producto. 
    {
        "response" : {
            "result" : true,
            "response_code" : 200,
            "message" : "Request successfull",
            "data" : [
                {
                    "result" : true,
                    "response_code" : 200,
                    "message" : "Match found",
                    "data" : {
                        "code" : "SA5DS1D5152",
                        "part_number" : "XXXXX",
                        "upc" : "XXXXX",
                        "description" : "XXXXX",
                        "brand" : "XXXXX",
                        "price" : "XXXXX",
                        "stores" : {
                            "1" : "5"
                        }
                    }
                }
            ]
        }
    }
A continuación se muestra la estructura de una respuesta exitosa de varios productos. 
    {
        "response" : {
            "result" : true,
            "response_code" : 200,
            "message" : "Request successfull",
            "data" : [
                {
                    "result" : true,
                    "response_code" : 200,
                    "message" : "Match found",
                    "data" : {
                        "code" : "SA5DS1D5152",
                        "part_number" : "XXXXX",
                        "upc" : "XXXXX",
                        "description" : "XXXXX",
                        "brand" : "XXXXX",
                        "price" : "XXXXX",
                        "stores" : {
                            "1" : "5"
                        }
                    }
                },
                {
                    "result" : true,
                    "response_code" : 200,
                    "message" : "Match found",
                    "data" : {
                        "code" : "SA5DS1D5152",
                        "part_number" : "XXXXX",
                        "upc" : "XXXXX",
                        "description" : "XXXXX",
                        "brand" : "XXXXX",
                        "price" : "XXXXX",
                        "stores" : {
                            "1" : "5"
                        }
                    }
                },
                {
                    "result" : true,
                    "response_code" : 200,
                    "message" : "Match found",
                    "data" : {
                        "code" : "SA5DS1D5152",
                        "part_number" : "XXXXX",
                        "upc" : "XXXXX",
                        "description" : "XXXXX",
                        "brand" : "XXXXX",
                        "price" : "XXXXX",
                        "stores" : {
                            "1" : "5"
                        }
                    }
                }
            ]
        }
    }

Generar compra

Las compras permiten el registro de transacciones monetarias representativas de productos o servicios. La estructura de datos de petición de compras es la siguiente:
URL
https://api.zegucom.com.mx/services/create-purchase
URL de prueba
https://api.test.zegucom.com.mx/services/create-purchase
Estructura de la petición

Tipo: POST

Tabla de parámetros
Parámetro Tipo Descripción
order array Arreglo con la estructura de la orden de compra
id string Identificador de una transacción generada por el usuario
store int Identificador de almacén de inventario
items array Arreglo con los productos solicitados
code string Identificador del producto
quantity int Cantidad de piezas solicitadas del producto
price float Precio del producto proporcionado anteriormente por Zegucom Cómputo * Sin IVA
Estructura de la petición JSON
    {
        "headers" : {
            "auth" : {
                "user_key" : 999999,
                "password" : "XXXXXX"
            }
        },
        "request": {
            "order": {
                "id": "XXXXXXXXX",
                "store": 0,
                "items": [{
                    "code" : "XXXXXXXXX",
                    "quantity": 1,
                    "price": 9516.548
                }]
            }
        }
    }
Respuesta de la petición

Tipo: JSON

Si la petición es correcta, recibirás una respuesta en formato JSON con la siguiente estructura:

Tabla de parámetros
Parámetro Tipo Descripción
response array Arreglo con la estructura de la respuesta
result boolean Indicador de estatus de transacción, TRUE si fue exitosa, FALSE en cualquier otro caso
msg string Mensaje de éxito de transacción
response_code int Código de éxito de la petición
data array Arreglo con la estructura de los datos de la compra
purchase_id int Número de venta generado
invoice_number int Folio de CFDI 
    {
        "response": {
            "result": true,
            "msg": "Purchase successfully created",
            "response_code": 200,
            "data": {
                "purchase_id": 9999999,
                "invoice_number": 999999
            }
        }
    }

Si la petición falla, recibirás un código de error y uno de los siguientes mensajes:

  • Invalid product code provided. El código del producto no es válido.
  • Invalid store provided. La clave de la sucursal no es válida o la sucursal no existe.
  • Product not found. No se encontró el producto o el producto no existe.
  • Quantity must be greater than 0 for product. Se especificó una cantidad inválida (menor a una unidad) del producto.
  • Store without any stock data for product. La sucursal especificada no tiene información de stock del producto.
  • Malformed request. Request array is not set. El arreglo de petición no contiene la llave "request".
  • Missing required parameter "{parámetro}". No se encuentra el parámetro especificado en el mensaje.
  • No items found on request. El arreglo de petición no contiene la llave "items" o está vacía.
  • Unable to validate payment. No fue posible cobrar la compra por un error interno.
  • Unable to generate purchase. No fue posible guardar la compra por un error interno.

Consultar compra

Consultar compra te permite ver el detalle de una compra previamente efectuada. La estructura de datos de petición es la siguiente:
URL
https://api.zegucom.com.mx/services/get-purchase
URL de prueba
https://api.test.zegucom.com.mx/services/get-purchase
Estructura de la petición

Tipo: POST

Tabla de parámetros
Parámetro Tipo Descripción
identifier int Identificador único de la compra. Puede ser el número de compra (purchase_id) o el Folio de CFDI (invoice_number)
Estructura de la petición JSON
    {
    "headers" : {
        "auth" : {
            "user_key" : 999999,
            "password" : "XXXXXX"
            }
        },
        "request": {
            "identifier": 999999
        }
    }
Respuesta de la petición

Tipo: JSON

Si la petición es correcta, recibirás una respuesta en formato JSON con la siguiente estructura: .

Tabla de parámetros
Parámetro Tipo Descripción
response array Arreglo con la estructura de la respuesta
result boolean Indicador de estatus de transacción, TRUE si fue exitosa, FALSE en cualquier otro caso
msg string Mensaje de éxito de transacción
response_code int Código de éxito de la petición
data array Arreglo con la estructura de los datos de la compra
purchase_id int Número de venta generado
invoice_number int Folio de CFDI
order_id string Identificador de la transacción generada por el usuario
store int Identificador del almacén donde se realizó la compra
products array Arreglo con los productos de la compra
part_number string Número de parte del producto
code string Identificador del producto
description string Descripción del producto
quantity int Cantidad comprada del producto
price float Precio de venta del producto 
    {
        "response": {
            "result": true,
            "msg": "Match found",
            "response_code": 200,
            "data": {
                "purchase_id": 9999999,
                "invoice_number": 999999,
                "order_id": "XXXXXXXXX",
                "store": 99,
                "products"[{
                    "part_number": "XXXXXXXX",
                    "code": "XXXXXXXX",
                    "description": "XXXXXXXX",
                    "quantity": 99,
                    "price": 99.99,
                }]
            }
        }
    }

Si la petición falla, recibirás un código de error y uno de los siguientes mensajes:

  • Malformed request. Request array is not set. El arreglo de petición no contiene la llave "request".
  • Missing required parameter "{parámetro}". No se encuentra el parámetro especificado en el mensaje.
  • Purchase not found. No se encuentra la compra con el identificador especificado.
Ocasionalmente podrías recibir el mensaje "No invoice found for this purchase" en el parámetro invoice_number. No te preocupes, significa que tu factura aún no se ha timbrado pero está en espera de hacerlo. Recibirás un correo a la dirección que tengas configurada en tu cuenta de cliente Zegucom cuando sea timbrada.

Ingresar número de guía

Te permite ingresar un número de guía y rastreo a las órdenes generadas previamente por el usuario autenticado. La estructura de datos de inserción de números de guía es la siguiente:
URL
https://api.zegucom.com.mx/services/set-tracking
URL de prueba
https://api.test.zegucom.com.mx/services/set-tracking
Estructura de la petición

Tipo: POST

Tabla de parámetros
Parámetro Tipo Descripción
orders array Arreglo con la estructura de las órdenes a actualizar (Debe contener hasta 50 elementos por petición)
purchase_id int Identificador único de la compra generado por el servicio create-purchase
order_id string Identificador de una transacción proporcionado por el usuario en el servicio create-purchase
global_b64_pdf string Contenido del archivo pdf que contendrá todas las guías de la misma orden, codificado en base 64. Si el pdf es por guía, deberá usar el campo 'base64_pdf' en 'tracking_data' y enviar este valor como "0"
tracking_data array Array con la estructura de las guías de la misma orden
shipping_id string Número de guía para almacenar
tracking string Codigo de rastreo (En caso de no contar con el, ingresar el número de guía nuevamente)
base64_pdf string Contenido del archivo pdf que contendrá la información de la guía, codificado en base 64. Si es solo un archivo para todas las guías deberá usar el campo 'global_b64_pdf' fuera del array 'tracking_data' y enviar este con un valor de "0"
Estructura de la petición JSON
    {
        "headers" : {
            "auth" : {
                "user_key" : 999999,
                "password" : "XXXXXX"
            }
        },
        "request": {
            "orders": [{
                "purchase_id" : 9999999,
                "order_id": "XXXXXXXXX",
                "global_b64_pdf": "0",
                "tracking_data": [{
                    "shipping_id": "XXXXXXXXXXXXXXXXXXXX",
                    "tracking": "XXXXXXXXXXXXXXXXXXXX",
                    "base64_pdf": "XXXXXXXXXXXXXXXXXXXXXX"
                }]
            }]
        }
    }
Respuesta de la petición

Tipo: JSON

Para cada una de las guías ingresadas en la petición, recibirás una respuesta en formato JSON con la siguiente estructura:

Tabla de parámetros
Parámetro Tipo Descripción
result boolean Indicador de estatus de la guía, TRUE si fue almacenada de manera exitosa, FALSE en cualquier otro caso
response_code int Código de respuesta de la petición para esa guía
data array Arreglo con la estructura de los mensajes generados. (Puede ser uno o varios) 
    {
        "response": {
            "result": true,
            "response_code": 200,
            "data": [{
                "result": true
                "response_code": 200,
                "data": [
                    "Success. Tracking saved successfully"
                ]
            }]
        }
    }

Si la petición falla, recibirás un código de error y uno de los siguientes mensajes:

  • Malformed request. Request array is not set. El arreglo de petición no contiene la llave "request".
  • Missing required parameter "{parámetro}". No se encuentra el parámetro especificado en el mensaje.
  • Invalid parameter. El tipo de dato ingresado no es válido
  • Order not found. La órden ingresada en la petición no existe en nuestros registros
  • Not allowed. No tiene permitido realizar esa acción.
  • File not created. El archivo no pudo ser creado.

Límites y restricciones

Con el fin de proteger la estabilidad y disponibilidad del servicio, la API aplica dos controles de acceso sobre todas las peticiones: la validación por dirección IP de cliente y el límite de tasa de peticiones. Ambos controles se evalúan después de una autenticación exitosa y de forma independiente para cada usuario.
Validación por dirección IP

Cuando esta validación está activa, cada petición debe originarse desde una dirección IP previamente registrada y autorizada para tu usuario. Las direcciones IP permitidas son dadas de alta por Zegucom; para registrar o actualizar tus IP públicas, contacta a tu agente.

Si la petición proviene de una dirección IP no autorizada, no se ejecutará el servicio y recibirás el código de error 213 con el siguiente mensaje:

  • Request IP address not allowed. Please contact your agent.: La dirección IP desde la que se realizó la petición no está registrada para tu usuario.
Límite de tasa de peticiones

El número de peticiones que puedes realizar está limitado de forma independiente por cada servicio (endpoint) y por usuario. El conteo se realiza sobre una ventana de tiempo: al recibir la primera petición se inicia la ventana y se cuentan las peticiones siguientes hasta alcanzar el límite o hasta que la ventana expira, momento en el cual el conteo se reinicia.

Los servicios que no tienen un límite específico utilizan un valor por defecto de 60 peticiones por minuto. Los límites por servicio son los siguientes:

Servicio Límite de peticiones Ventana de tiempo
Consultar productos 200 peticiones 1 minuto
Generar compra 100 peticiones 1 hora
Consultar compra 30 peticiones 1 minuto
Ingresar números de guía 250 peticiones 1 hora

Si superas el límite permitido, las peticiones adicionales serán rechazadas con el código de error 214 y el siguiente mensaje:

  • Rate limit exceeded. Please slow down your requests.: Se alcanzó el límite de peticiones para el servicio dentro de la ventana de tiempo actual.

Códigos de respuesta

Cuando se realice una petición a la API, ésta devolverá un código de respuesta, existen dos tipos de códigos; de éxito y de error.

A continuación se explican los códigos de éxito.

Códigos de éxito
Si la petición es exitosa, se mostrará el siguiente código de respuesta.
Código Significado Descripción
200 OK La petición se recibió y procesó exitosamente
Códigos de error

Si alguna petición falla, la respuesta de la API incluirá un código de error. A continuación, se muestran los códigos de error que la API puede devolver.

Código Significado Descripción
201 Malformed request Petición JSON mal formada. La petición contiene llaves no reconocidas o con nombres no válidos.
202 Authentication failed Error en el inicio de sesión. El usuario o la contraseña son incorrectos
203 Missing required parameter Falta de un parámetro obligatorio. El parámetro puede estar en cualquier nivel de la estructura.
204 Insufficient stock No hay inventario suficiente del producto.
205 Product not found El código de producto no arrojó ningún resultado
206 Service not found El servicio al que estás intentando acceder no existe.
207 Invalid parameter El formato o tipo de dato de al menos un parámetro es incorrecto.
208 Product temporarily disabled El producto esta deshabilitado temporalmente.
209 Blocked User El usuario que esta utilizando se encuentra bloqueado, debe contactar a su agente para recibir detalles.
210 Order Not Found El número de órden ingresado en la petición no existe en nuestros registros.
211 Tracking Already Exists El número de guía ingresado en la petición ya existe en nuestros registros.
212 File Not Created El archivo no pudo ser generado.
213 Not Allowed No tiene permiso para realizar esta acción. Por ejemplo, cuando la petición proviene de una dirección IP no autorizada para su usuario.
214 Rate limited Se superó el límite de peticiones permitidas para el servicio dentro de la ventana de tiempo. La respuesta incluye el encabezado Retry-After con los segundos de espera.
300 Service offline La API no está disponible en ese momento.
301 Unknown error Error desconocido. Generalmente un error de servidor, se usa como código de error genérico.
302 Unavailable service El servicio no se encuentra disponible.