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

# Introducción

> Empezá a usar la API de La Pyme con una API key, una primera request autenticada y las convenciones principales.

La API REST de La Pyme te permite integrar datos operativos de tu organización con sistemas externos. Podés consultar clientes, proveedores, productos, inventario, compras, ventas, cobranzas, pagos, reportes y configuración.

Esta página te lleva desde una API key nueva hasta tu primera request autenticada.

<Info>
  Necesitás una cuenta activa en La Pyme y acceso a **Configuración > Integraciones** para crear API keys.
</Info>

## Base URL

Todos los endpoints de la API están disponibles en:

```text theme={null}
https://api.lapyme.com.ar
```

## Obtener una API key

1. Iniciá sesión en [La Pyme](https://app.lapyme.com.ar).
2. Entrá a **Configuración > Integraciones > API Keys**.
3. Hacé click en **Crear nuevo API Key**.
4. Para esta primera prueba, seleccioná `warehouses:read` y `products:read`.
5. Dale un nombre descriptivo, por ejemplo `Mi primera integración`.
6. Hacé click en **Generar**.
7. Copiá el API key y guardalo en un lugar seguro.

<Warning>
  El API key solo se muestra una vez. Si lo perdés, vas a tener que crear uno nuevo.
</Warning>

## Verificar disponibilidad

El endpoint de health check no requiere autenticación:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lapyme.com.ar/health"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.lapyme.com.ar/health");
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://api.lapyme.com.ar/health", timeout=30)
  print(response.json())
  ```
</CodeGroup>

## Hacer la primera request autenticada

Pedí una ubicación con `GET /api/v1/warehouses?limit=1`. Es un buen smoke test porque valida credencial, scopes y formato de respuesta sin depender de datos comerciales sensibles.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lapyme.com.ar/api/v1/warehouses?limit=1" \
    -H "Authorization: Bearer TU_API_KEY_AQUI"
  ```

  ```typescript TypeScript theme={null}
  const apiKey = "TU_API_KEY_AQUI";

  const response = await fetch("https://api.lapyme.com.ar/api/v1/warehouses?limit=1", {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

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

  ```python Python theme={null}
  import requests

  api_key = "TU_API_KEY_AQUI"

  response = requests.get(
      "https://api.lapyme.com.ar/api/v1/warehouses",
      params={"limit": 1},
      headers={"Authorization": f"Bearer {api_key}"},
      timeout=30,
  )

  print(response.json())
  ```
</CodeGroup>

### Response esperada

```json theme={null}
{
  "request_id": "req_123",
  "object": "list",
  "url": "/api/v1/warehouses",
  "data": [
    {
      "object": "warehouse",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Depósito principal",
      "address": "Av. Corrientes 1234",
      "is_default": true,
      "is_active": true,
      "points_of_sale_count": 1,
      "member_count": 3,
      "register_count": 2
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Convenciones principales

* Todas las requests autenticadas usan `Authorization: Bearer ...`.
* Las respuestas incluyen `request_id` para trazabilidad.
* Los recursos incluyen `object` como discriminador de solo lectura.
* Los listados devuelven `has_more` y `next_cursor` para [paginar](/api-reference/paginacion).
* Los errores usan un objeto `error` con `type`, `code`, `message`, `retryable` y `details`.
* Los importes monetarios se envían y devuelven en centavos.
* Las escrituras que pueden crear duplicados usan [`Idempotency-Key`](/api-reference/idempotencia).

## Filtrar productos

Los listados aceptan filtros propios de cada recurso. Para productos podés usar `query`:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lapyme.com.ar/api/v1/products?query=almohada&limit=10" \
    -H "Authorization: Bearer TU_API_KEY_AQUI"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.lapyme.com.ar/api/v1/products?query=almohada&limit=10",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    }
  );
  ```
</CodeGroup>

## Ejemplo completo

```typescript theme={null}
const API_KEY = process.env.LAPYME_API_KEY;
const BASE_URL = "https://api.lapyme.com.ar";

async function apiRequest(path: string, options: RequestInit = {}) {
  const response = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!response.ok) {
    throw new Error(
      `API Error ${data.error.code}: ${data.error.message} (${data.request_id})`
    );
  }

  return data;
}

async function listProducts(query = "", cursor?: string) {
  const params = new URLSearchParams({
    limit: "25",
  });

  if (query) params.set("query", query);
  if (cursor) params.set("cursor", cursor);

  return apiRequest(`/api/v1/products?${params}`);
}

async function main() {
  const products = await listProducts("almohada");
  console.log(`Productos recibidos: ${products.data.length}`);

  if (products.has_more) {
    const nextPage = await listProducts("almohada", products.next_cursor);
    console.log(`Siguiente página: ${nextPage.data.length}`);
  }
}

main().catch((error) => {
  console.error(error.message);
  process.exit(1);
});
```

Para ejecutar este script:

```bash theme={null}
export LAPYME_API_KEY="tu_api_key_aqui"
node api-client.js
```

## Próximos pasos

1. Revisá [Autenticación](/api-reference/autenticacion) para elegir entre API keys y OAuth delegado.
2. Leé [Paginación](/api-reference/paginacion), [Idempotencia](/api-reference/idempotencia), [Errores](/api-reference/errores) y [Rate limits](/api-reference/rate-limits).
3. Instalá el [SDK TypeScript](/api-reference/sdk/typescript) si querés usar un cliente oficial.