# Primeros Pasos (ES)
## Getting Started
Esta es una API de estilo REST que utiliza JSON para la serialización.
Para comenzar a utilizar la API necesitará:
* Inicie sesión en WoowUp y obtenga su clave API en la sección Configuración / Mi cuenta.
{% hint style="info" %}
Recuerda que debes tener permisos de Super Admin para ver las claves.
{% endhint %}
* Lea los documentos de la API para comprender lo que puede hacer.
### Elementos esenciales a tener en cuenta
* Toda solicitud recibe y devuelve datos en formato JSON.
* Recuerde incluir en el header Basic Authentication al llamar a cualquier endpoint. [Aquí](https://docs.woowup.com/#authentication) encontrarás cómo hacerlo.
* Para identificar a un cliente use el campo "service\_uid". Normalmente, usará el correo electrónico o la ID (DNI, CPF, RUT, Pasaporte) para identificar al cliente.
* Cada vez que vaya a usar service\_uid como parte de la URL, primero deberá codificarlo con base64 y luego con URL encode. Puedes leer aquí una explicación detallada [aquí](https://docs.woowup.com/#how-to-encode-service_uid).
* Los formatos de fecha válidos son: AAAA-mm-dd HH: mm: ss (predeterminado en UTC) o formato ISO 8601 que incluye la zona horaria Ej .: 2004-02-12T15: 19: 21 + 03: 00
* Normalmente, incluirá toda la Información del producto (sku, título, categoría, stock, etc.) en el punto final de Crear pedido de compra. Pero si lo prefiere, hay un endpoint específico para sincronizar [productos](https://docs.woowup.com/api/products#products).
* Antes de enviar una orden de compra, debe crear el cliente si no existe. En el ejemplo, puede ver cómo funciona este proceso en el archivo "import\_from\_csv.php".
* Por favor, preste atención a los mensajes de las respuestas de nuestra API porque le informaremos si algo está mal con sus solicitudes o con la información que envía.
### Rate Limiting
La API limita la cantidad de requests por cuenta para garantizar la estabilidad del servicio. El límite por defecto es de **140 requests por minuto.**
El sistema divide el tiempo en segmentos de 30 segundos y siempre evalúa dos segmentos: el actual y el anterior. Los requests del segmento actual cuentan al 100%, mientras que los del segmento anterior se ponderan según el tiempo transcurrido — cuanto más tiempo pasó, menos pesan.
Esto genera una transición suave entre ventanas, evitando el problema clásico de los contadores fijos donde un cliente puede duplicar el límite en el borde del reset.
{% code lineNumbers="true" %}
```java
peso = 1 - (segundos_transcurridos / duración_segmento)
estimación = (requests_anteriores × peso) + requests_actuales
if estimación ≥ límite → HTTP 429
```
{% endcode %}
**Ejemplo:** El segmento anterior terminó con 60 requests y el actual lleva 25, estando a los 15 segundos del segmento:
peso = 1 - (15 / 30) = 0.5
estimación = (60 × 0.5) + 25 = 55 → Permitido (< 70)
#### Headers de respuesta
Todas las respuestas de la API incluyen headers de rate limiting para que puedas monitorear tu consumo en tiempo real:
| Header | Descripcion | Ejemplo |
|---|
x-rate-limit-limit | Máximo de requests por ventana | 70 |
x-rate-limit-remaining | Requests restantes en la ventana actual | 45 |
x-rate-limit-reset | Timestamp Unix de cuándo se renueva la ventana | 1742121660 |
Cuando se supera el límite, la API responde con **HTTP 429 Too Many Requests** e incluye:
| Header | Descripcion | Ejemplo |
|---|
Retry-After | Segundos que debés esperar antes de reintentar | 18 |
**Ejemplos de Respuestas:**
{% tabs %}
{% tab title="Normal" %}
`HTTP/1.1 200 OK x-rate-limit-limit: 70 x-rate-limit-remaining: 45 x-rate-limit-reset: 1742121660`
{% endtab %}
{% tab title="Bloqueada" %} `HTTP/1.1 429 Too Many Requests x-rate-limit-limit: 70 x-rate-limit-remaining: 0 x-rate-limit-reset: 1742121660 Retry-After: 18`
`{"payload": [], "message": "too many request", "code": "too_many_request"}`
{% endtab %}
{% endtabs %}
#### Buenas prácticas
* **Monitoreá los headers:** Revisá x-rate-limit-remaining en cada respuesta para conocer tu consumo antes de alcanzar el límite.
* **Reintentá con backoff:** Cuando recibas un 429, esperá la cantidad de segundos indicada en el header Retry-After antes de reintentar.
* **Distribuí los requests:** Repartí las llamadas de forma uniforme en el tiempo en lugar de enviar ráfagas.
* **Usá paginación eficiente:** Usá valores altos de limit (ej: ?limit=100) para reducir la cantidad de requests necesarios.
Si necesitás un límite más alto, contactá a tu account manager o a nuestro equipo de soporte.
### Autenticación
En cualquier llamada a la API, debe enviar el API Key en la cadena de consulta como un parámetro.
Por ejemplo, si su API Key es 'abcdefghijklmnopqrstuvwxyz', debe hacer una solicitud para
```http
https://api.woowup.com/apiv3/users?apikey=abcdefghijklmnopqrstuvwxyz
```
Otro método, y el recomendado, es a través del encabezado de autenticación, en cada llamada debe enviar el encabezado
```
Authorization: Basic abcdefghijklmnopqrstuvwxyz
```
#### Cuentas Eliminadas
Las solicitudes desde cuentas eliminadas reciben `410 Gone` con código `account_deleted`. Una vez que una cuenta ha sido dada de baja, su API key deja de ser válida y\
todas las solicitudes serán rechazadas.
{% code lineNumbers="true" %}
```
{
"payload": [],
"message": "gone: account deleted",
"code": "account_deleted"
}
```
{% endcode %}
### Paginación
Cuando estás haciendo una búsqueda, paginamos los resultados. En todos los puntos finales paginados, los parámetros de la paginación son:
| Parameter | Description | Default |
| --------- | ----------------------------------- | ------- |
| limit | Items per page returned. Max: 100 | 25 |
| page | Number of the page. First page is 0 | 0 |
### Returned Format
Todos los endpoints devuelven datos en formato JSON, con el encabezado:
```
Content-Type: application / json
```
Para un uso correcto tienes que enviar en todas las solicitudes el encabezado
```
Accept: application / json.
```
### Codificar 'service\_uid'
Cuando intenta encontrar un usuario, puede identificarlo por su id o su service\_uid (comúnmente es el correo electrónico), cuando usa service\_uid debe codificar esto en Base64 y codificar el resultado como URL seguro, por ejemplo, si necesita hacer esto en php:
```php
para cualquier consulta, estaremos encantados de atenderle.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://woowup-docs.gitbook.io/woowup-developer-docs/getting-started-es.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.