Complete API Documentation

Full reference guide for all API endpoints and features

API Overview

The BrainPrices API is a RESTful API that allows you to programmatically interact with our marketplace platform.

Secure

JWT authentication with refresh tokens

Multi-language

Support for 6 languages

Fast

Optimized for performance

Base URL

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

Request Format

All requests must include the Content-Type header:

Content-Type: application/json

Products Endpoints

Method Endpoint Description Auth
GET /productos List all products with filters No
GET /productos/{id} Get product details No
POST /productos Create new product Yes
PUT /productos/{id} Update product Yes
DELETE /productos/{id} Delete product Yes
POST /productos/{id}/imagenes Upload product images Yes
PUT /productos/{id}/stock Update stock quantity Yes
POST /productos/importar Bulk import products Yes
For detailed examples of each endpoint, visit the main documentation or code examples page.

Authentication Endpoints

Method Endpoint Description
POST /auth/login Authenticate and get access token
POST /auth/refresh Refresh expired access token
POST /auth/logout Invalidate current token

Pagination

All list endpoints support pagination with consistent parameters:

?page=1&per_page=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 500,
    "total_pages": 25,
    "has_more": true
  }
}

Categories Endpoints

Method Endpoint Description Auth
GET /categorias List all categories No
GET /categorias/{id} Get category details No
GET /categorias/{id}/productos Get products in category No
POST /categorias Create category Yes
PUT /categorias/{id} Update category Yes
DELETE /categorias/{id} Delete category Yes

Orders Endpoints

Method Endpoint Description Auth
GET /pedidos List orders Yes
GET /pedidos/{id} Get order details Yes
POST /pedidos Create order No
PUT /pedidos/{id}/estado Update order status Yes
GET /pedidos/{id}/factura Get invoice Yes

Shopping Cart Endpoints

Method Endpoint Description
GET /carrito/{sessionId} Get cart contents
POST /carrito/{sessionId}/agregar Add item to cart
PUT /carrito/{sessionId}/actualizar Update item quantity
DELETE /carrito/{sessionId}/eliminar/{itemId} Remove item from cart
DELETE /carrito/{sessionId}/limpiar Clear entire cart

Customers Endpoints

Method Endpoint Description Auth
GET /clientes List customers Yes
GET /clientes/{id} Get customer details Yes
GET /clientes/{id}/pedidos Get customer orders Yes

Associates Endpoints

Method Endpoint Description Auth
GET /asociados List associates Yes
GET /asociados/{id}/productos Get associate products Yes
GET /asociados/{id}/ventas Get associate sales Yes
GET /asociados/{id}/comisiones Get associate commissions Yes

Payments Endpoints

Method Endpoint Description
GET /pagos/metodos Get available payment methods
POST /pagos/procesar Process payment
POST /pagos/webhook/{provider} Payment gateway webhook
GET /pagos/{id}/estado Get payment status

Shipping Endpoints

Method Endpoint Description
GET /envios/metodos Get shipping methods
POST /envios/calcular Calculate shipping cost
GET /envios/{id}/seguimiento Track shipment

Coupons Endpoints

Method Endpoint Description Auth
GET /cupones/validar/{code} Validate coupon code No
GET /cupones List coupons Yes
POST /cupones Create coupon Yes

Reviews Endpoints

Method Endpoint Description
GET /reseñas/producto/{productId} Get product reviews
POST /reseñas Submit review
PUT /reseñas/{id} Update review

Attributes Endpoints

Method Endpoint Description Auth
GET /atributos List attributes No
GET /atributos/grupos Get attribute groups No

Manufacturers Endpoints

Method Endpoint Description Auth
GET /fabricantes List manufacturers No
GET /fabricantes/{id}/productos Get manufacturer products No

Synchronization Endpoints

Method Endpoint Description Auth
POST /sync/productos Sync products from external platform Yes
POST /sync/pedidos Sync orders Yes
GET /sync/estado/{jobId} Check sync job status Yes

Webhooks Endpoints

Method Endpoint Description
POST /webhooks/woocommerce WooCommerce webhook receiver
POST /webhooks/prestashop PrestaShop webhook receiver
POST /webhooks/shopify Shopify webhook receiver
POST /webhooks/magento Magento webhook receiver
Security: All webhooks verify signatures to ensure authenticity.

Error Handling

All API errors follow a consistent format:

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

HTTP Status Codes

200 OK
201 Created
400 Bad Request
401 Unauthorized
404 Not Found
422 Validation Failed
429 Too Many Requests
500 Server Error

Rate Limiting

The API implements rate limits 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

Ready to Start?

Check out our interactive examples or go back to the main documentation.

Main Docs View Examples