Returns API - Inventario

Overview

The Returns API allows you to process customer returns (refunds) and supplier returns (returning defective items to suppliers). Returns automatically adjust inventory levels and maintain detailed transaction history.

Models

Devolucion (Customer Return)

Customer return from a sale transaction.

integer

Unique identifier for the return

venta

integer

ID of the original sale transaction

cliente

integer

ID of the client making the return

fecha

datetime

Timestamp when the return was created (auto-generated)

motivo

string

Reason for the return

usuario

integer

ID of the user who processed the return

total_devuelto

decimal

Total amount refunded (sum of all line items)

DetalleDevolucion (Customer Return Line Item)

Individual items returned in a customer return.

integer

Unique identifier for the line item

devolucion

integer

ID of the parent return transaction

producto

integer

ID of the product being returned

cantidad

integer

Quantity of items being returned

precio_unitario

decimal

Price per unit at the time of original sale

subtotal

decimal

Calculated as cantidad * precio_unitario (read-only property)

DevolucionCompra (Supplier Return)

Return of items to a supplier (e.g., defective products).

integer

Unique identifier for the supplier return

compra

integer

ID of the original purchase transaction

proveedor

integer

ID of the supplier receiving the return

usuario

integer

ID of the user who processed the return

motivo

string

Reason for returning items to supplier

fecha

datetime

Timestamp when the return was created (defaults to current time)

total_devuelto

decimal

Total value of items returned to supplier

DetalleDevolucionCompra (Supplier Return Line Item)

Individual items returned to a supplier.

integer

Unique identifier for the line item

devolucion

integer

ID of the parent supplier return transaction

producto

integer

ID of the product being returned to supplier

cantidad

integer

Quantity of items being returned

precio_unitario

decimal

Price per unit at the time of original purchase

Customer Return Endpoints

Create Customer Return

Process a customer return and refund.

POST /devoluciones/crear/

venta_id

integer

required

ID of the original sale transaction

cliente_id

integer

required

ID of the client making the return

motivo

string

Reason for the return

productos

array

required

Array of products being returned, each containing:

producto_id (integer): Product ID
cantidad (integer): Quantity to return
precio_unitario (decimal): Original unit price

Example Request:

curl -X POST https://your-domain.com/devoluciones/crear/ \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: your-csrf-token" \
  -d '{
    "venta_id": 123,
    "cliente_id": 45,
    "motivo": "Producto defectuoso",
    "productos": [
      {
        "producto_id": 10,
        "cantidad": 2,
        "precio_unitario": "25.00"
      }
    ]
  }'

Response:

{
  "id": 67,
  "venta": 123,
  "cliente": 45,
  "fecha": "2024-03-10T14:30:00Z",
  "motivo": "Producto defectuoso",
  "usuario": 5,
  "total_devuelto": "50.00",
  "detalles": [
    {
      "id": 89,
      "producto": 10,
      "cantidad": 2,
      "precio_unitario": "25.00",
      "subtotal": "50.00"
    }
  ]
}

List Customer Returns

Retrieve all customer returns for the current user.

GET /devoluciones/lista/

Query Parameters:

fecha_desde

date

Filter returns from this date (YYYY-MM-DD)

fecha_hasta

date

Filter returns until this date (YYYY-MM-DD)

cliente

integer

Filter by client ID

Get Customer Return Details

Retrieve details of a specific customer return.

GET /devoluciones/detalle/{id}/

Supplier Return Endpoints

Create Supplier Return

Return defective or incorrect items to a supplier.

POST /devoluciones/compras/crear/

compra_id

integer

required

ID of the original purchase transaction

proveedor_id

integer

ID of the supplier

motivo

string

Reason for returning items (e.g., “Productos defectuosos”, “Error en pedido”)

productos

array

required

Array of products being returned to supplier

Example Request:

curl -X POST https://your-domain.com/devoluciones/compras/crear/ \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: your-csrf-token" \
  -d '{
    "compra_id": 456,
    "proveedor_id": 12,
    "motivo": "Productos dañados en envío",
    "productos": [
      {
        "producto_id": 15,
        "cantidad": 5,
        "precio_unitario": "30.00"
      }
    ]
  }'

List Supplier Returns

Retrieve all supplier returns for the current user.

GET /devoluciones/compras/lista/

Stock Impact

Returns automatically adjust product inventory: Customer Returns (Devoluciones):

When a customer return is created, stock is increased by the returned quantity
Products are available for resale

Supplier Returns (DevolucionCompra):

When items are returned to a supplier, stock is decreased by the returned quantity
Products are removed from available inventory

Returns cannot be edited after creation. If a return was entered incorrectly, delete it and create a new one.

Permissions

Admin

Create customer returns
Create supplier returns
View all returns
Delete returns

Vendedor

Create customer returns
View returns they created
Cannot create supplier returns
Cannot delete returns

Business Rules

Customer Returns:
- Must reference a valid sale transaction
- Cannot return more items than were originally sold
- Stock is automatically restored upon return
- Total refund amount is calculated from line items
Supplier Returns:
- Must reference a valid purchase transaction
- Reduces available inventory
- Typically used for defective items or shipping errors
Deletion Protection:
- Returns use SET_NULL for sale references (allows sale deletion)
- Returns use PROTECT for client and product references (prevents deletion)
- Supplier returns use CASCADE for purchase (deleted if purchase is deleted)

Sales API - Original sale transactions for customer returns
Purchases API - Original purchase transactions for supplier returns
Products API - Product inventory affected by returns

Example: Complete Return Workflow

Customer Contacts You

Customer reports a defective product from sale #123

Verify Original Sale

GET /ventas/detalle/123/

Verify the product and quantity in the original sale

Process Return

POST /devoluciones/crear/

Create the return with product details and reason

Verify Stock Update

GET /productos/{product_id}/

Confirm product stock was restored

Issue Refund

Process the financial refund to the customer based on total_devuelto

Overview

Endpoints

​Overview

​Models

​Devolucion (Customer Return)

​DetalleDevolucion (Customer Return Line Item)

​DevolucionCompra (Supplier Return)

​DetalleDevolucionCompra (Supplier Return Line Item)

​Customer Return Endpoints

​Create Customer Return

​List Customer Returns

​Get Customer Return Details

​Supplier Return Endpoints

​Create Supplier Return

​List Supplier Returns

​Stock Impact

​Permissions

Admin

Vendedor

​Business Rules

​Related Endpoints

​Example: Complete Return Workflow

Build docs developers (and LLMs) love

Overview

Models

Devolucion (Customer Return)

DetalleDevolucion (Customer Return Line Item)

DevolucionCompra (Supplier Return)

DetalleDevolucionCompra (Supplier Return Line Item)

Customer Return Endpoints

Create Customer Return

List Customer Returns

Get Customer Return Details

Supplier Return Endpoints

Create Supplier Return

List Supplier Returns

Stock Impact

Permissions

Business Rules

Related Endpoints

Example: Complete Return Workflow