API externa de SmartPyme: guía de acceso a datos B2B

La API externa de SmartPyme es una API REST diseñada para integraciones B2B: permite a proveedores, plataformas de analítica y otros terceros acceder de forma programática a los datos de ventas, inventario y devoluciones de los negocios que usan SmartPyme, y crear o actualizar ventas desde sistemas externos. Todas las solicitudes utilizan HTTPS estándar y devuelven respuestas en JSON.

Qué ofrece la API

La API te da acceso a tres dominios de datos principales: ventas, inventario y devoluciones. Los endpoints de lectura exponen vistas de listado, detalle y resumen para que puedas obtener exactamente el nivel de detalle que tu integración necesite. Los endpoints de escritura sobre sales permiten que sistemas externos (POS, e-commerce, marketplaces) registren transacciones en SmartPyme y actualicen ventas o cotizaciones pendientes. La API está construida específicamente para escenarios como reportes de sell-through para proveedores, dashboards de analítica externos, conciliación automatizada de inventarios y sincronización bidireccional de ventas.

URL base

Todas las solicitudes se dirigen a la siguiente URL base:

https://api.smartpyme.site/api/external/v1/

Endpoints disponibles

Endpoint	Descripción
`GET /sales`	Lista ventas con filtros
`POST /sales`	Crea y procesa una venta (o cotización)
`GET /sales/{id}`	Obtiene una venta específica
`PUT /sales/{id}`	Actualiza una venta pendiente o cotización
`GET /sales/summary`	Estadísticas de resumen de ventas
`GET /inventory`	Lista productos con stock
`GET /inventory/{id}`	Obtiene un producto específico
`GET /inventory/summary`	Estadísticas de resumen de inventario
`GET /returns`	Lista devoluciones
`GET /returns/{id}`	Obtiene una devolución específica
`GET /returns/summary`	Estadísticas de resumen de devoluciones
`GET /system/rate-limit`	Consulta tu estado actual de límite de uso
`POST /packages/import`	Importa datos de paquetes desde un sistema externo

Envoltura estándar de respuesta

Cada respuesta exitosa de la API envuelve su contenido en una envoltura consistente. El campo data contiene los registros que solicitaste, pagination describe la página actual de resultados y meta proporciona contexto sobre la empresa y los filtros aplicados.

{
  "success": true,
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "total": 1250,
    "total_pages": 13,
    "has_next": true,
    "has_prev": false,
    "from": 1,
    "to": 100
  },
  "meta": {
    "empresa": "Mi Empresa S.A.",
    "timestamp": "2025-01-15T10:30:00Z",
    "filters_applied": {}
  }
}

Formato de respuesta de error

Cuando una solicitud falla, la API devuelve una envoltura con success: false, un mensaje error legible para humanos y el código HTTP code correspondiente.

{
  "success": false,
  "error": "API key inválido o empresa inactiva",
  "code": 401
}

Códigos de estado HTTP

Código	Significado
`200`	Éxito
`400`	Bad Request — parámetros inválidos
`401`	Unauthorized — API Key inválida o ausente
`403`	Forbidden — empresa inactiva
`404`	Not Found
`429`	Too Many Requests — límite de uso excedido
`500`	Internal Server Error

La mayoría de los endpoints son de solo lectura. Las operaciones de escritura se limitan a POST /sales y PUT /sales/{id} (crear y actualizar ventas o cotizaciones) y POST /packages/import (importación masiva de datos de paquetes desde sistemas externos).

​Qué ofrece la API

​URL base

​Endpoints disponibles

​Envoltura estándar de respuesta

​Formato de respuesta de error

​Códigos de estado HTTP

Qué ofrece la API

URL base

Endpoints disponibles

Envoltura estándar de respuesta

Formato de respuesta de error

Códigos de estado HTTP