> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartpyme.app/llms.txt
> Use this file to discover all available pages before exploring further.

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

> La API externa de SmartPyme ofrece a proveedores externos acceso a datos de ventas, inventario y devoluciones, y permite crear y actualizar ventas mediante autenticación con API Key.

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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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                      |

<Note>
  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).
</Note>