Skip to main content

​
Overview

The Purchases API handles the registration of inventory purchases from providers. When a purchase is created, the system automatically:
  • Updates product stock quantities (for products with inventory control enabled)
  • Updates product cost prices based on the latest purchase price
  • Records stock movements for audit trails
  • Calculates totals including IVA (19% tax for invoices)
All operations are atomic - if any part fails, the entire transaction is rolled back.

​
Create Purchase

​
Request Body

​
provider_id
integer
required
ID of the provider from whom the purchase is made.
​
folio
string
Document number (invoice or receipt number).
​
tipo_documento
string
Document type. Options: FACTURA, BOLETA, SIN_DOCUMENTO. Default: FACTURA.
​
items
array
required
Array of purchase items. Each item contains:
  • product_id (integer, required): Product identifier
  • cantidad (decimal, required): Quantity purchased
  • precio_costo_unitario (decimal, required): Unit cost price (net amount)
​
observacion
string
Additional notes or observations about the purchase.
​
fecha_compra
datetime
Purchase date. If not provided, current timestamp is used.

​
Response

​
id
integer
Unique purchase identifier.
​
provider_id
integer
Provider identifier.
​
folio
string
Document number.
​
tipo_documento
string
Document type (FACTURA, BOLETA, or SIN_DOCUMENTO).
​
fecha_compra
datetime
Purchase date.
​
monto_neto
decimal
Net amount (sum of all item subtotals).
​
iva
decimal
IVA tax amount (19% for FACTURA, 0 for other document types).
​
monto_total
decimal
Total amount (monto_neto + iva).
​
observacion
string
Additional notes.
​
created_at
datetime
Timestamp when the purchase was registered.
​
provider
object
Nested provider object with complete provider information.
​
details
array
Array of purchase detail items, each containing product information, quantity, unit cost, and subtotal.
curl -X POST https://api.example.com/purchases/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "provider_id": 1,
    "folio": "F-00123",
    "tipo_documento": "FACTURA",
    "items": [
      {
        "product_id": 10,
        "cantidad": 50,
        "precio_costo_unitario": 1500.00
      },
      {
        "product_id": 15,
        "cantidad": 30,
        "precio_costo_unitario": 2800.00
      }
    ],
    "observacion": "Compra de reposición mensual",
    "fecha_compra": "2026-03-08T10:00:00Z"
  }'

{
  "id": 1,
  "provider_id": 1,
  "folio": "F-00123",
  "tipo_documento": "FACTURA",
  "fecha_compra": "2026-03-08T10:00:00Z",
  "monto_neto": 159000.00,
  "iva": 30210.00,
  "monto_total": 189210.00,
  "observacion": "Compra de reposición mensual",
  "created_at": "2026-03-08T10:30:00Z",
  "provider": {
    "id": 1,
    "rut": "76543210-9",
    "razon_social": "Distribuidora Central S.A.",
    "giro": "Importación y distribución",
    "direccion": "Av. Industrial 2500",
    "ciudad": "Santiago",
    "email": "[email protected]",
    "telefono": "+56 2 2987 6543",
    "is_active": true,
    "created_at": "2026-03-01T10:30:00Z",
    "updated_at": null
  },
  "details": [
    {
      "id": 1,
      "product_id": 10,
      "cantidad": 50,
      "precio_costo_unitario": 1500.00,
      "subtotal": 75000.00,
      "product": {
        "id": 10,
        "codigo_interno": "PROD-010",
        "nombre": "Producto A",
        "precio_neto": 2000.00,
        "stock_actual": 150,
        "controla_stock": true
      }
    },
    {
      "id": 2,
      "product_id": 15,
      "cantidad": 30,
      "precio_costo_unitario": 2800.00,
      "subtotal": 84000.00,
      "product": {
        "id": 15,
        "codigo_interno": "PROD-015",
        "nombre": "Producto B",
        "precio_neto": 3500.00,
        "stock_actual": 80,
        "controla_stock": true
      }
    }
  ]
}

​
List Purchases

​
Response

Returns an array of purchase objects with full details including provider and items. 
curl -X GET https://api.example.com/purchases/ \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "id": 2,
    "provider_id": 1,
    "folio": "F-00124",
    "tipo_documento": "FACTURA",
    "fecha_compra": "2026-03-08T14:00:00Z",
    "monto_neto": 250000.00,
    "iva": 47500.00,
    "monto_total": 297500.00,
    "observacion": null,
    "created_at": "2026-03-08T14:15:00Z",
    "provider": { },
    "details": [ ]
  },
  {
    "id": 1,
    "provider_id": 1,
    "folio": "F-00123",
    "tipo_documento": "FACTURA",
    "fecha_compra": "2026-03-08T10:00:00Z",
    "monto_neto": 159000.00,
    "iva": 30210.00,
    "monto_total": 189210.00,
    "observacion": "Compra de reposición mensual",
    "created_at": "2026-03-08T10:30:00Z",
    "provider": { },
    "details": [ ]
  }
]

​
Get Purchase

​
Path Parameters

​
purchase_id
integer
required
Unique purchase identifier.

​
Response

Returns a single purchase object with complete details. 
curl -X GET https://api.example.com/purchases/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": 1,
  "provider_id": 1,
  "folio": "F-00123",
  "tipo_documento": "FACTURA",
  "fecha_compra": "2026-03-08T10:00:00Z",
  "monto_neto": 159000.00,
  "iva": 30210.00,
  "monto_total": 189210.00,
  "observacion": "Compra de reposición mensual",
  "created_at": "2026-03-08T10:30:00Z",
  "provider": {
    "id": 1,
    "rut": "76543210-9",
    "razon_social": "Distribuidora Central S.A."
  },
  "details": [
    {
      "id": 1,
      "product_id": 10,
      "cantidad": 50,
      "precio_costo_unitario": 1500.00,
      "subtotal": 75000.00,
      "product": { }
    }
  ]
}

​
Update Purchase

​
Path Parameters

​
purchase_id
integer
required
Unique purchase identifier.

​
Request Body

Use the same structure as creating a purchase. All fields from PurchaseCreate are accepted.

​
Behavior

When updating a purchase:
  1. Old stock quantities are reversed (subtracted from inventory)
  2. Old purchase details are deleted
  3. New stock quantities are applied (added to inventory)
  4. New purchase details are created
  5. Product costs are updated based on new prices
  6. Stock movements are recorded for audit trail
curl -X PUT https://api.example.com/purchases/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "provider_id": 1,
    "folio": "F-00123-CORR",
    "tipo_documento": "FACTURA",
    "items": [
      {
        "product_id": 10,
        "cantidad": 60,
        "precio_costo_unitario": 1450.00
      }
    ],
    "observacion": "Compra corregida"
  }'

{
  "id": 1,
  "provider_id": 1,
  "folio": "F-00123-CORR",
  "tipo_documento": "FACTURA",
  "fecha_compra": "2026-03-08T10:00:00Z",
  "monto_neto": 87000.00,
  "iva": 16530.00,
  "monto_total": 103530.00,
  "observacion": "Compra corregida",
  "created_at": "2026-03-08T10:30:00Z",
  "provider": { },
  "details": [ ]
}

​
Delete Purchase

​
Path Parameters

​
purchase_id
integer
required
Unique purchase identifier.

​
Behavior

When deleting a purchase:
  1. Stock quantities are reversed (subtracted from current inventory)
  2. Stock movements are recorded with “AJUSTE” (adjustment) reason
  3. Purchase and all its details are permanently deleted

​
Response

Returns no content on success. 
curl -X DELETE https://api.example.com/purchases/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get Purchase PDF

​
Path Parameters

​
purchase_id
integer
required
Unique purchase identifier.

​
Response

Returns an HTML document formatted for printing, including:
  • Company (issuer) information
  • Provider details
  • Purchase items with quantities and prices
  • Totals (net, IVA, total)
curl -X GET https://api.example.com/purchases/1/pdf \
  -H "Authorization: Bearer YOUR_TOKEN"

<!DOCTYPE html>
<html>
<head>
  <title>Purchase Receipt</title>
</head>
<body>
  <!-- Formatted purchase document -->
</body>
</html>

​
Purchase Flow & Inventory Updates

​
Automatic Stock Updates

When a purchase is created:
  1. Product Validation: The system validates that products exist and don’t have variants (variant-parent products cannot be purchased directly)
  2. Cost Update: Each product’s costo_unitario is updated to match the latest precio_costo_unitario from the purchase
  3. Stock Increment: For products with controla_stock: true, the stock_actual is increased by the purchased quantity
  4. Stock Movement: A StockMovement record is created with:
    • tipo: “ENTRADA” (incoming)
    • motivo: “COMPRA” (purchase)
    • cantidad: Purchased quantity
    • balance_after: New stock level
    • description: Purchase folio reference

​
IVA Calculation

  • FACTURA: 19% IVA is applied to the net amount
  • BOLETA or SIN_DOCUMENTO: No IVA (iva = 0)

​
Transaction Safety

All purchase operations are atomic:
  • If any item fails validation, the entire purchase is rolled back
  • Stock updates and purchase records are committed together
  • No partial purchases are possible

​
Variant Products

Products that have variants (child products) cannot be purchased directly. You must purchase the specific variant. This prevents stock tracking issues with parent products.

Build docs developers (and LLMs) love

Get started for freeTalk to us