Documentazione API

API REST completa per l'integrazione con BrainPrices Marketplace

STABLE v1.0 Base URL: https://www.brainprices.com/api/v1

Introduction

Welcome to the BrainPrices Marketplace API documentation. Our REST API allows you to programmatically interact with our platform.

Quick Start

Get started in 3 simple steps:

  1. Get your API credentials
  2. Authenticate to receive a JWT token
  3. Make your first API call

Base URL

https://www.brainprices.com/api/v1

Content Type

All requests and responses use JSON format.

Content-Type: application/json

Authentication

The API uses JWT (JSON Web Tokens) for authentication. You need to login first to obtain a token, then include it in the Authorization header for all authenticated requests.

POST /auth/login

Authenticate user and obtain access token.

Request Body
Parameter Type Required Description
email string YES User email address
password string YES User password
Examples
curl -X POST https://www.brainprices.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
const response = await fetch('https://www.brainprices.com/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const data = await response.json();
const token = data.token;
console.log('Token:', token);
$ch = curl_init('https://www.brainprices.com/api/v1/auth/login');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => 'user@example.com',
    'password' => 'password123'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
$token = $data['token'];

echo "Token: $token";
import requests

response = requests.post(
    'https://www.brainprices.com/api/v1/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'password123'
    }
)

data = response.json()
token = data['token']
print(f'Token: {token}')
Response (200 OK)
{
  "success": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "expires_in": 3600,
  "user": {
    "id": 123,
    "email": "user@example.com",
    "role": "associate"
  }
}
Token Usage: Include the token in all authenticated requests: Authorization: Bearer {token}

Products

GET /productos

Get a paginated list of products with optional filters.

Query Parameters
Parameter Type Description
page integer Page number (default: 1)
per_page integer Items per page (default: 20, max: 100)
search string Search by name or SKU
category_id integer Filter by category
on_sale boolean Only products on sale
sort string Sort by: name, price, created_at, sales
Examples
curl -X GET "https://www.brainprices.com/api/v1/productos?page=1&per_page=20&on_sale=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
const response = await fetch(
  'https://www.brainprices.com/api/v1/productos?page=1&per_page=20&on_sale=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const data = await response.json();
console.log('Total products:', data.pagination.total);
data.data.forEach(product => {
  console.log(`${product.name}: €${product.price}`);
});
$ch = curl_init('https://www.brainprices.com/api/v1/productos?page=1&per_page=20');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

foreach ($data['data'] as $product) {
    echo "{$product['name']}: €{$product['price']}\n";
}
import requests

response = requests.get(
    'https://www.brainprices.com/api/v1/productos',
    params={'page': 1, 'per_page': 20, 'on_sale': True},
    headers={'Authorization': f'Bearer {token}'}
)

data = response.json()
for product in data['data']:
    print(f"{product['name']}: €{product['price']}")
Response (200 OK)
{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "Vino Rioja Reserva 2020",
      "slug": "vino-rioja-reserva-2020",
      "sku": "VIN-RIOJA-2020",
      "price": 24.99,
      "compare_price": 34.99,
      "stock_quantity": 50,
      "category_name": "Vinos",
      "primary_image": "/uploads/products/vino.jpg",
      "status": "active",
      "featured": true
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8,
    "has_more": true
  }
}
POST /productos Requires Auth

Create a new product.

Request Body
Parameter Type Required Description
name string YES Product name
sku string YES Stock Keeping Unit (unique)
price float YES Product price
stock_quantity integer YES Available stock
category_id integer YES Category ID
description string No Full product description (HTML allowed)
compare_price float No Original price (for discounts)
Example
const newProduct = await fetch('https://www.brainprices.com/api/v1/productos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    name: 'Aceite de Oliva Virgen Extra',
    sku: 'ACE-OLIVA-001',
    price: 12.50,
    compare_price: 15.99,
    stock_quantity: 100,
    category_id: 3,
    description: '

Aceite de máxima calidad...

' }) }); const result = await newProduct.json(); console.log('Product created:', result.data.id);
$ch = curl_init('https://www.brainprices.com/api/v1/productos');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Aceite de Oliva Virgen Extra',
    'sku' => 'ACE-OLIVA-001',
    'price' => 12.50,
    'stock_quantity' => 100,
    'category_id' => 3
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
Response (201 Created)
{
  "success": true,
  "message": "Producto creado correctamente",
  "data": {
    "id": 456,
    "uuid": "660e8400-e29b-41d4-a716-446655440000",
    "slug": "aceite-de-oliva-virgen-extra"
  }
}
PUT /productos/{id}/stock Requires Auth

Update product stock quantity.

Example
// Set stock to specific value
await fetch('https://www.brainprices.com/api/v1/productos/123/stock', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    stock_quantity: 75,
    operation: 'set'
  })
});

// Increment stock
await fetch('https://www.brainprices.com/api/v1/productos/123/stock', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    quantity: 10,
    operation: 'increment'
  })
});
curl -X PUT https://www.brainprices.com/api/v1/productos/123/stock \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"stock_quantity": 75, "operation": "set"}'

Shopping Cart

POST /carrito/{sessionId}/agregar

Add product to shopping cart.

Example
const sessionId = localStorage.getItem('cart_session') || generateSessionId();

const response = await fetch(
  `https://www.brainprices.com/api/v1/carrito/${sessionId}/agregar`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      product_id: 123,
      quantity: 2
    })
  }
);

const data = await response.json();
console.log('Cart total:', data.data.totals.total);
$sessionId = session_id();

$ch = curl_init("https://www.brainprices.com/api/v1/carrito/{$sessionId}/agregar");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'product_id' => 123,
    'quantity' => 2
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

Categories

GET /categorias

Get category tree.

curl -X GET "https://www.brainprices.com/api/v1/categorias" \
  -H "Authorization: Bearer YOUR_TOKEN"

For complete reference, see full documentation.

Orders

GET /pedidos Requires Auth

List orders with filters.

curl -X GET "https://www.brainprices.com/api/v1/pedidos?status=processing" \
  -H "Authorization: Bearer YOUR_TOKEN"
POST /pedidos

Create new order.

{
  "customer": {
    "email": "customer@example.com",
    "first_name": "Juan",
    "last_name": "Pérez"
  },
  "items": [
    {"product_id": 123, "quantity": 2, "price": 24.99}
  ],
  "payment_method": "credit_card"
}

Customers

GET /clientes Requires Auth

List customers.

For detailed examples of customer management, visit the complete reference.

Payments

GET /pagos/metodos

Get available payment methods.

curl -X GET "https://www.brainprices.com/api/v1/pagos/metodos"

Coupons

GET /cupones/validar/{code}

Validate coupon code.

curl -X GET "https://www.brainprices.com/api/v1/cupones/validar/DESCUENTO10"

Reviews

GET /reseñas/producto/{productId}

Get product reviews.

curl -X GET "https://www.brainprices.com/api/v1/reseñas/producto/123"

Synchronization

POST /sync/productos Requires Auth

Synchronize products from external platforms.

Supported platforms: WooCommerce, PrestaShop, Shopify, Magento

{
  "source": "woocommerce",
  "source_url": "https://mitienda.com",
  "api_key": "ck_abc123",
  "api_secret": "cs_xyz789",
  "options": {
    "update_prices": true,
    "update_stock": true,
    "import_images": true
  }
}

Webhooks

Receive real-time notifications from external platforms.

POST /webhooks/woocommerce

Receive WooCommerce webhooks.

Configure this URL in your WooCommerce settings to receive order updates automatically.

Security: Webhooks are verified using signature headers from each platform.

Error Codes

Code Status Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request data
401 Unauthorized Invalid or expired token
403 Forbidden Insufficient permissions
404 Not Found Resource not found
422 Unprocessable Validation failed
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Error Response Format

{
  "success": false,
  "message": "Validation error",
  "errors": {
    "email": ["Email is required", "Email must be valid"],
    "price": ["Price must be greater than 0"]
  },
  "code": "VALIDATION_ERROR"
}

Rate Limiting

The API implements rate limiting to ensure fair usage:

Endpoint Type Rate Limit
Public endpoints 60 requests/minute
Authenticated endpoints 120 requests/minute
Webhooks 300 requests/minute

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1616161616

Additional Resources

OpenAPI Specification

Download the complete OpenAPI/Swagger specification.

Download YAML
Complete Documentation

Browse the full API reference guide with all endpoints.

View Documentation
Code Examples

Explore ready-to-use code in JavaScript, PHP, Python.

View Examples
Postman Collection

Import our API into Postman for easy testing.

Import to Postman

Need Help?

If you need assistance with API integration or have questions:

Contact Support