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

# Guía de la API

> Cómo usar la API de Esolbay: ambientes, autenticación, patrones comunes y mejores prácticas

## Ambientes y base URL

<ResponseField name="Ambiente" type="string" required>
  <Expandable title="Ambientes soportados">
    * Local: `http://localhost:3000/api/v1`
    * Staging: `https://staging.esolbay.com/api/v1`
    * Producción: `https://api.esolbay.com/api/v1`
  </Expandable>
</ResponseField>

<Tip>
  Consulta los endpoints y esquemas en <a href="/api-reference/introduction">API Reference</a>.
</Tip>

## Autenticación

Todas las solicitudes deben incluir `x-api-key`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.esolbay.com/api/v1/items/" \
    -H "x-api-key: $ESOLBAY_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.esolbay.com/api/v1/orders/", {
    headers: { "x-api-key": process.env.ESOLBAY_API_KEY },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const data = await res.json();
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.get(
    'https://api.esolbay.com/api/v1/providers/',
    headers={'x-api-key': os.environ['ESOLBAY_API_KEY']}
  )
  res.raise_for_status()
  data = res.json()
  ```
</CodeGroup>

## Paginación y ordenado

Muchos listados soportan parámetros `limit`, `offset`, `orderBy`, `order`.

```text theme={null}
?limit=20&offset=0&orderBy=createdAt&order=desc
```

## Versionado y estabilidad

* Versionado vía prefijo de ruta (`/api/v1`).
* Cambios incompatibles se publican en versiones mayores.

## Errores

* 400: solicitud inválida (valida tu payload)
* 401: no autorizado (revisa `x-api-key`)
* 404: recurso no encontrado
* 500: error interno

## Webhooks

Para recibir eventos (p. ej., `order.create`), configura un Webhook en el panel y valida firmas HMAC-SHA256. Revisa la guía de <a href="/webhooks">Webhooks</a> y los esquemas en `x-webhooks` dentro de <a href="/api-reference/openapi.json">OpenAPI</a>.

## Mejores prácticas

* Almacena `x-api-key` y secretos en un gestor seguro.
* Implementa idempotencia con `x-esolbay-event-id` en Webhooks.
* Limita y valida inputs en la integración.