Usar la API REST

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 se llama igual que lo hace el panel, con /v1 adelante.

Autenticación

Mandá la clave como Bearer token en cada solicitud:

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:

curl https://api.nubea.com.ar/v1/operations \
  -H "Authorization: Bearer $NUBEA_API_KEY"

{
  "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 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 figuran como esquema. Para el resto, el cuerpo es el mismo que envía el panel.

Ejemplos

Ventas recuperadas por día, semana o mes

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.

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.

Listar y enviar una campaña

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.

Contactos de una lista y altas

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"}'

Configurar un widget

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.

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.

Errores

Todos los errores vuelven con el mismo envoltorio:

{ "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

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.

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.

​Autenticación

​Descubrir operaciones

​Ejemplos

​Errores

​Límites

Autenticación

Descubrir operaciones

Ejemplos

Errores

Límites