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

# Usar la API REST

> Autenticación, descubrimiento de operaciones, errores, límites y ejemplos para integrar Nubea desde tu propio código.

La API vive en `https://api.nubea.com.ar/v1` y reutiliza, ruta por ruta, las
operaciones del panel: mismas validaciones, mismas reglas de suscripción y
mismas respuestas. Todo lo que ves en [la referencia](/api/referencia-rutas) se
llama igual que lo hace el panel, con `/v1` adelante.

## Autenticación

Mandá la clave como Bearer token en cada solicitud:

```bash theme={null}
curl https://api.nubea.com.ar/v1/store \
  -H "Authorization: Bearer $NUBEA_API_KEY"
```

La clave identifica la tienda y actúa con el rol de quien la creó. No hay
parámetro de tienda: una clave, una tienda.

## Descubrir operaciones

`GET /v1/operations` lista las operaciones que tu clave puede ejecutar, con su
identificador, método, ruta, permisos y parámetros de ruta:

```bash theme={null}
curl https://api.nubea.com.ar/v1/operations \
  -H "Authorization: Bearer $NUBEA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "get_campaigns",
      "method": "GET",
      "path": "/campaigns",
      "description": "List WhatsApp campaigns, filterable by status.",
      "scopes": ["platform:read"],
      "readOnly": true,
      "pathParameters": [],
      "input": { "query": { "type": "object", "properties": { "status": { "type": "string" } } } }
    }
  ]
}
```

La especificación OpenAPI está en
[`/v1/openapi.json`](https://api.nubea.com.ar/v1/openapi.json) y no requiere
clave. Cada operación trae una descripción en lenguaje claro y sus permisos.
Las que el panel valida con un esquema publican además el formato exacto del
cuerpo (`requestBody`) y de los parámetros de consulta; en la
[referencia](/api/referencia-rutas) figuran como **esquema**. Para el resto, el
cuerpo es el mismo que envía el panel.

## Ejemplos

<AccordionGroup>
  <Accordion title="Ventas recuperadas por día, semana o mes">
    ```bash theme={null}
    curl "https://api.nubea.com.ar/v1/conversions/summary?startDate=2026-01-01&endDate=2026-10-09&groupBy=day" \
      -H "Authorization: Bearer $NUBEA_API_KEY"
    ```

    Devuelve un bucket por período con pedidos e ingresos totales y por fuente
    (`automation`, `whatsapp-campaign`, `newsletter`, `stock-notification`).
    Hasta dos años por llamada. Es la forma de responder "qué día vendí más"
    sin listar cada pedido.

    ```bash theme={null}
    curl "https://api.nubea.com.ar/v1/conversions?sourceType=automation&startDate=2026-10-01&endDate=2026-10-09&page=1&limit=100" \
      -H "Authorization: Bearer $NUBEA_API_KEY"

    curl "https://api.nubea.com.ar/v1/statistics?startDate=2026-09-01&endDate=2026-09-30" \
      -H "Authorization: Bearer $NUBEA_API_KEY"
    ```

    La lista de conversiones trae cada pedido con sus productos: usá `page` y
    `limit` (hasta 500) o un rango corto. Las estadísticas cubren hasta 365
    días por llamada. Requieren Lectura.
  </Accordion>

  <Accordion title="Listar y enviar una campaña">
    ```bash theme={null}
    curl https://api.nubea.com.ar/v1/campaigns \
      -H "Authorization: Bearer $NUBEA_API_KEY"

    curl -X POST https://api.nubea.com.ar/v1/campaigns/123/send \
      -H "Authorization: Bearer $NUBEA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    El envío requiere Escritura y Mensajes, y pasa por las mismas comprobaciones
    y colas que el botón del panel. Cambiá `123` por una campaña de tu tienda.
  </Accordion>

  <Accordion title="Contactos de una lista y altas">
    ```bash theme={null}
    curl https://api.nubea.com.ar/v1/campaigns/lists/45/contacts \
      -H "Authorization: Bearer $NUBEA_API_KEY"

    curl -X POST https://api.nubea.com.ar/v1/campaigns/lists/45/contacts \
      -H "Authorization: Bearer $NUBEA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"phone": "+5491155551234", "name": "Ana"}'
    ```
  </Accordion>

  <Accordion title="Configurar un widget">
    ```bash theme={null}
    curl https://api.nubea.com.ar/v1/free-shipping-bar/settings \
      -H "Authorization: Bearer $NUBEA_API_KEY"
    ```

    Cada widget tiene su `GET` de configuración y su escritura. La ruta y el
    método están en la [referencia](/api/referencia-rutas#barras-y-alertas-en-la-tienda).
  </Accordion>
</AccordionGroup>

<Tip>
  Para saber qué cuerpo espera una operación, abrí la pantalla equivalente del
  panel con las herramientas de desarrollo del navegador: la API acepta
  exactamente el mismo JSON que manda el panel.
</Tip>

## Errores

Todos los errores vuelven con el mismo envoltorio:

```json theme={null}
{ "error": { "code": "forbidden", "message": "Insufficient permissions" } }
```

| Estado | `code` | Cuándo |
| - | - | - |
| `400` | `bad_request` | Cuerpo o parámetros inválidos. El mensaje es el mismo que mostraría el panel |
| `401` | `unauthorized` | Clave inválida, vencida, revocada, o su creador ya no es parte de la tienda |
| `403` | `forbidden` | La clave no tiene el permiso, el rol de quien la creó no alcanza, o el plan no incluye la función |
| `404` | `not_found` | La ruta no existe en la API pública o el recurso no es de esta tienda |
| `409` | `conflict` | La acción ya se hizo o el estado no la permite (por ejemplo, reenviar una campaña enviada) |
| `413` | `payload_too_large` | Cuerpo mayor a 15 MiB |
| `429` | `rate_limited` | Superaste el límite; esperá lo que indique `Retry-After` |
| `503` | `unavailable` | Problema temporal del lado de Nubea; reintentá más tarde |

<Warning>
  No reintentes automáticamente una escritura después de un corte de conexión:
  la solicitud puede haberse completado. Consultá primero el estado del recurso.
</Warning>

## Límites

| Límite | Valor |
| - | - |
| Solicitudes por tienda | 120 por minuto, sumando todas sus claves |
| Solicitudes por IP | 300 por minuto |
| Cuerpo de la solicitud | 15 MiB |
| Claves activas por tienda | 20 |

Cada respuesta trae `RateLimit-Limit` y `RateLimit-Remaining` para que tu
integración se regule sola.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.