Primeros Pasos (ES)

Aquí encontrará ejemplos y una lista detallada de puntos finales que le permitirá integrar WoowUp con los sistemas que utiliza via API.

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.

Recuerda que debes tener permisos de Super Admin para ver las claves.

• 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í 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í.

• 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.

• 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.

peso       = 1 - (segundos_transcurridos / duración_segmento)                                                                                                         
estimación = (requests_anteriores × peso) + requests_actuales 

if estimación ≥ límite → HTTP 429

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:

Normal

HTTP/1.1 200 OK x-rate-limit-limit: 70 x-rate-limit-remaining: 45 x-rate-limit-reset: 1742121660

Bloqueada

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

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.

{
    "payload": [],
    "message": "gone: account deleted",
    "code": "account_deleted"
}

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
​
$service_uid = '[e-mail]';
$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

No dude en ponerse en contacto con nosotros escribiendo a [e-mail] para cualquier consulta, estaremos encantados de atenderle.