# 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:

<pre class="language-java" data-line-numbers><code class="lang-java"><strong>peso = 1 - (15 / 30) = 0.5
</strong>estimación = (60 × 0.5) + 25 = 55 → Permitido (&#x3C; 70)
</code></pre>

#### Headers de respuesta

Todas las respuestas de la API incluyen headers de rate limiting para que puedas monitorear tu consumo en tiempo real:

<table><thead><tr><th width="210.078125">Header</th><th width="418.53515625">Descripcion</th><th width="121.28125">Ejemplo</th></tr></thead><tbody><tr><td><code>x-rate-limit-limit</code></td><td><code>Máximo de requests por ventana</code></td><td><code>70</code></td></tr><tr><td><code>x-rate-limit-remaining</code></td><td><code>Requests restantes en la ventana actual</code> </td><td><code>45</code></td></tr><tr><td><code>x-rate-limit-reset</code></td><td><code>Timestamp Unix de cuándo se renueva la ventana</code></td><td><code>1742121660</code></td></tr></tbody></table>

Cuando se supera el límite, la API responde con **HTTP 429 Too Many Requests** e incluye:

<table><thead><tr><th>Header</th><th width="428.92578125">Descripcion</th><th width="145.015625">Ejemplo</th></tr></thead><tbody><tr><td><code>Retry-After</code> </td><td><code>Segundos que debés esperar antes de reintentar</code></td><td><code>18</code></td></tr></tbody></table>

**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" %} <sup>`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`</sup>

<sup>`{"payload": [], "message": "too many request", "code": "too_many_request"}`</sup>
{% 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&#x20;

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 <a href="#returned-format" id="returned-format"></a>

Todos los endpoints devuelven datos en formato JSON, con el encabezado:

```
Content-Type: application / json
```

&#x20;Para un uso correcto tienes que enviar en todas las solicitudes el encabezado

```
 Accept: application / json.
```

### Codificar 'service\_uid'&#x20;

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
<?php
​
$service_uid = 'example@email.com';
$encoded_uid = urlencode(base64_encode($service_uid));
$url = 'https://api.woowup.com/apiv3/users/'.$encoded_uid.'/exist';
​
```

### Código de muestra

Cómo empezar a enviarnos sus pedidos de compra En el siguiente enlace encontrará un ejemplo completamente funcional en PHP que procesa un archivo CSV con pedidos y clientes y utiliza la API para enviarlos a WoowUp: [Ejemplo de descarga](https://github.com/woowup/woowup-php-client/blob/master/dist/woowup-php-client-v1.zip)

{% hint style="info" %}
No dude en ponerse en contacto con nosotros escribiendo a <developers@woowup.com> para cualquier consulta, estaremos encantados de atenderle.
{% endhint %}