API REST de GestionShop

Introducción

La API REST de GestionShop permite a desarrolladores y sistemas externos consultar información de clientes, artículos y contratos de compraventa de manera programática. Está diseñada para integraciones con ERPs, sistemas contables, aplicaciones móviles y cualquier plataforma que necesite acceder a los datos de tu negocio.

La API utiliza el protocolo HTTPS, acepta y retorna datos en formato JSON, y requiere autenticación mediante API Key para cada solicitud.

Características

La API de GestionShop está construida siguiendo las mejores prácticas de diseño RESTful:

Autenticación

Todas las solicitudes a la API deben incluir el header x-api-key con tu clave de acceso. Esta clave es única por almacén y se genera desde el panel de administración.

x-api-key: tu_api_key_aquí

Endpoints

La API expone los siguientes endpoints para consultar información de tu compraventa:

Consultar cliente por cédula

Parámetros

Ejemplo de solicitud

curl -X GET "https://micompraventa.gestionshop.co/api/v2/external/client-data?cedula=1234567890" \
  -H "x-api-key: tu_api_key_aquí" \
  -H "Content-Type: application/json"

Respuesta exitosa (200)

{
  "cliente": {
    "cedula": "1234567890",
    "nombre": "Juan Pérez Gómez",
    "direccion": "Calle 45 #12-34, Centro",
    "telefono": "3104567890",
    "correo": "juanperez@example.com",
    "fecha_nacimiento": "1985-06-12",
    "genero": "Masculino",
    "estado": "Activo"
  },
  "contratos": [
    {
      "codigo_contrato": "17-12345",
      "articulo": "Cadena Oro 18k",
      "precio_contrato": 1200000,
      "categoria": "Joyas",
      "estado_contrato": "Activo",
      "tasa": 2.5,
      "fecha_creacion": "2025-04-10",
      "capital_adeudado": 1200000,
      "fecha_vencimiento": "2025-10-30",
      "prorrogas_pendientes": 2,
      "valor_prorroga_mensual": 60000,
      "pago_total_retiro": 1260000
    }
  ],
  "resumen_contratos": {
    "cantidad_contratos": 1,
    "suma_total_contratos": 1200000
  }
}

Códigos HTTP

La API utiliza códigos de estado HTTP estándar para indicar el resultado de cada solicitud:

Rate Limiting

Para garantizar la estabilidad del servicio, la API limita a 500 solicitudes por minuto por API Key. Si excedes este límite, recibirás una respuesta 429:

{
  "error": "Límite de peticiones excedido",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after_seconds": 45
}

Recomendaciones

• Implementa un sistema de cache local para evitar solicitudes repetidas
• Usa backoff exponencial al recibir un 429
• Revisa los headers X-RateLimit-Remaining y X-RateLimit-Reset
• Si necesitas más capacidad, contacta a soporte para un plan con límite superior

Probador en Vivo

Prueba la API directamente desde esta página. Ingresa tu API Key y una cédula para hacer una consulta real.

// La respuesta aparecerá aquí...

Ejemplos de Código

Consulta un cliente por cédula en tu lenguaje de programación preferido:

const response = await fetch(
  'https://micompraventa.gestionshop.co/api/v2/external/client-data?cedula=1234567890',
  {
    headers: {
      'x-api-key': 'tu_api_key_aquí',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);

const axios = require('axios');

const { data } = await axios.get(
  'https://micompraventa.gestionshop.co/api/v2/external/client-data',
  {
    params: { cedula: '1234567890' },
    headers: {
      'x-api-key': 'tu_api_key_aquí',
      'Content-Type': 'application/json'
    }
  }
);

console.log(data);

import requests

response = requests.get(
    'https://micompraventa.gestionshop.co/api/v2/external/client-data',
    params={'cedula': '1234567890'},
    headers={
        'x-api-key': 'tu_api_key_aquí',
        'Content-Type': 'application/json'
    }
)

data = response.json()
print(data)

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://micompraventa.gestionshop.co/api/v2/external/client-data?cedula=1234567890',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: tu_api_key_aquí',
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

Notas Importantes