Skip to main content
POST
/
api
/
compras
Crear Compra
curl --request POST \
  --url https://api.example.com/api/compras \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "id_proveedor": 123,
  "tipo_doc": 123,
  "serie": "<string>",
  "numero": "<string>",
  "fecha_emision": "<string>",
  "fecha_vencimiento": "<string>",
  "id_tipo_pago": 123,
  "moneda": "<string>",
  "direccion": "<string>",
  "observaciones": "<string>",
  "productos": [
    {
      "id_producto": 123,
      "cantidad": 123,
      "costo": 123
    }
  ],
  "empresas_ids": [
    {}
  ],
  "cuotas": [
    {
      "monto": 123,
      "fecha": "<string>"
    }
  ]
}
'
{
  "400": {},
  "422": {},
  "500": {},
  "success": true,
  "message": "<string>",
  "data": {
    "id_compra": 123,
    "documento": "<string>"
  }
}
Registra una nueva compra de proveedor. Crea automáticamente:
  • Entrada de stock para todos los productos
  • Movimientos de stock con trazabilidad
  • Cuentas por pagar si es a crédito
  • Actualización del costo de productos

​
Autenticación

Requiere token Bearer y permiso compras.create.

​
Headers

​
Authorization
string
required
Token de autenticación Bearer
​
Content-Type
string
required
application/json

​
Body Parameters

​
Información del Comprobante

​
id_proveedor
integer
required
ID del proveedor (debe existir en tabla proveedores)
​
tipo_doc
integer
required
Tipo de documento del proveedor (debe existir en documentos_sunat)
  • 1: Factura
  • 3: Boleta
  • Otros códigos SUNAT
​
serie
string
required
Serie del comprobante del proveedor (1-4 caracteres alfanuméricos en MAYÚSCULAS)
  • Ejemplo: F001, B002, E123
​
numero
string
required
Número del comprobante del proveedor (solo dígitos, máximo 8)
​
fecha_emision
string
required
Fecha de emisión del comprobante (formato: YYYY-MM-DD)
​
fecha_vencimiento
string
Fecha de vencimiento de pago (requerido si id_tipo_pago = 2)

​
Pago

​
id_tipo_pago
integer
required
Forma de pago:
  • 1: Contado
  • 2: Crédito (requiere cuotas)
​
moneda
string
required
Moneda: PEN (Soles) o USD (Dólares)

​
Información Adicional

​
direccion
string
Dirección de entrega (opcional)
​
observaciones
string
Notas u observaciones adicionales

​
Productos

​
productos
array
required
Lista de productos comprados (mínimo 1)

​
Distribución Multi-Empresa

​
empresas_ids
array
IDs de empresas adicionales asociadas a esta compra (opcional)
  • Los IDs deben existir en la tabla empresas
  • Permite distribuir compras entre múltiples empresas

​
Cuotas (Solo si es a Crédito)

​
cuotas
array
Plan de pagos (requerido si id_tipo_pago = 2)

​
Validaciones

  • Formato de serie: Solo letras mayúsculas y números (1-4 caracteres)
  • Formato de número: Solo dígitos (1-8 caracteres)
  • Unicidad: No puede existir otra compra del mismo proveedor con el mismo tipo_doc, serie y numero

​
Proceso Automático

Al crear la compra, el sistema:
  1. Calcula totales:
    • Subtotal = Suma de (cantidad × costo) de todos los productos
    • IGV = 0 (las compras normalmente no llevan IGV)
    • Total = Subtotal + IGV
  2. Crea la compra con estado 1 (Activo)
  3. Para cada producto:
    • Guarda el detalle en productos_compra
    • Actualiza el stock: stock_nuevo = stock_anterior + cantidad
    • Actualiza el costo del producto en la tabla productos
    • Registra movimiento de stock:
      • tipo_movimiento: entrada
      • tipo_documento: compra
      • motivo: “Compra a proveedor”
      • Incluye stock_anterior y stock_nuevo para auditoría
  4. Si es a crédito: Crea las cuotas en dias_compras con estado 1 (Pendiente)
  5. Asocia empresas: Si se proporcionan empresas_ids, vincula la compra con esas empresas

​
Respuesta Exitosa

​
success
boolean
true si la compra se registró exitosamente
​
message
string
“Compra registrada exitosamente”
​
data
object
Información de la compra creada

​
Ejemplo de Solicitud

{
  "id_proveedor": 12,
  "tipo_doc": 1,
  "serie": "F001",
  "numero": "00000125",
  "fecha_emision": "2026-03-06",
  "fecha_vencimiento": "2026-04-06",
  "id_tipo_pago": 2,
  "moneda": "PEN",
  "direccion": "Almacén Principal - Jr. Los Olivos 234",
  "observaciones": "Incluye transporte",
  "productos": [
    {
      "id_producto": 45,
      "cantidad": 50,
      "costo": 25.50
    },
    {
      "id_producto": 78,
      "cantidad": 100,
      "costo": 12.80
    }
  ],
  "empresas_ids": [1, 3],
  "cuotas": [
    {
      "monto": 1000.00,
      "fecha": "2026-03-21"
    },
    {
      "monto": 1555.00,
      "fecha": "2026-04-06"
    }
  ]
}

​
Ejemplo de Respuesta

{
  "success": true,
  "message": "Compra registrada exitosamente",
  "data": {
    "id_compra": 88,
    "documento": "F001-00000125"
  }
}

​
Movimientos de Stock Generados

Para cada producto, se crea un registro en movimientos_stock: 
{
  "id_producto": 45,
  "tipo_movimiento": "entrada",
  "cantidad": 50,
  "stock_anterior": 120,
  "stock_nuevo": 170,
  "tipo_documento": "compra",
  "id_documento": 88,
  "documento_referencia": "F001-00000125",
  "motivo": "Compra a proveedor",
  "id_almacen": 1,
  "id_empresa": 1,
  "id_usuario": 3,
  "fecha_movimiento": "2026-03-06 10:45:23"
}

​
Códigos de Error

​
400
error
Errores de validación específicos:
  • Serie inválida (formato incorrecto)
  • Número inválido (no numérico)
  • Documento duplicado (ya existe para ese proveedor)
​
422
error
Errores de validación de campos requeridos o tipos de datos
​
500
error
Error interno al guardar la compra. Se hace rollback de la transacción.

​
Notas de Implementación

  • La operación es transaccional: si falla algún paso, se revierte todo (DB::rollBack)
  • El stock se actualiza inmediatamente en la tabla productos
  • El costo del producto se actualiza con el costo de la última compra
  • El campo sucursal se establece por defecto en 1
  • Para anular una compra (revertir stock), usa: POST /api/compras/{id}/anular

Build docs developers (and LLMs) love

Get started for freeTalk to us