SaleService

​

Overview

​

Dependencies

• InventoryMovementService - Manages inventory stock movements
• JournalEntryService - Creates accounting journal entries
• ReceivableService - Handles accounts receivable for credit sales
• InvoiceService - Generates invoices from sales
• NcfGeneratorInterface - Generates fiscal control numbers (NCF)

​

Methods

​

create()

public function create(array $data): Sale

1. Document Number Generation - Generates next sequential sale number from DocumentType
2. Sale Record Creation - Creates the sale record with status 'completed'
3. NCF Generation - If ncf_type_id provided, generates fiscal control number
4. Sale Items Creation - Creates all sale item records
5. Inventory Movements - Registers output movements for each product
6. Accounting Treatment:
   • Cash Sales: Creates immediate journal entry (Debit: Cash Account, Credit: Income Account 4.1)
   • Credit Sales: Creates receivable record with 30-day due date
7. Invoice Generation - Creates corresponding invoice record

​

Example Usage

use App\Services\Sales\SalesServices\SaleService;

public function __construct(
    protected SaleService $saleService
) {}

public function processSale()
{
    $sale = $this->saleService->create([
        'client_id' => 1,
        'warehouse_id' => 1,
        'total_amount' => 250.00,
        'payment_type' => 'cash',
        'tipo_pago_id' => 1,
        'cash_received' => 300.00,
        'cash_change' => 50.00,
        'sale_date' => now(),
        'items' => [
            [
                'product_id' => 10,
                'quantity' => 2,
                'price' => 75.00,
            ],
            [
                'product_id' => 15,
                'quantity' => 1,
                'price' => 100.00,
            ],
        ],
        'ncf_type_id' => 1,
        'notes' => 'Sale processed from POS terminal 3',
    ]);

    return $sale;
}

// Credit sale example
$creditSale = $this->saleService->create([
    'client_id' => 5,
    'warehouse_id' => 1,
    'total_amount' => 1500.00,
    'payment_type' => 'credit',
    'items' => [
        [
            'product_id' => 20,
            'quantity' => 5,
            'price' => 300.00,
        ],
    ],
]);

​

cancel()

public function cancel(Sale $sale, ?string $reason = null): bool

• Sale must not already be cancelled
• For credit sales, the receivable must not have any payments applied
• If receivable has partial payments, throws exception: “No se puede anular: El cliente ya tiene abonos.”

1. Receivable Cancellation - For credit sales, cancels the receivable if no payments exist
2. NCF Status Update - Updates NCF log status to 'voided' with cancellation reason
3. Accounting Reversal - Creates reversal journal entry:
   • Debit: Income Account (4.1)
   • Credit: Cash/Receivable Account (depending on original payment type)
4. Inventory Reversal - Creates adjustment movements to restore stock
5. Invoice Cancellation - Marks related invoice as cancelled
6. Sale Status Update - Sets sale status to 'canceled'

​

Example Usage

use App\Models\Sales\Sale;
use App\Services\Sales\SalesServices\SaleService;

public function __construct(
    protected SaleService $saleService
) {}

public function cancelSale($saleId)
{
    $sale = Sale::findOrFail($saleId);
    
    try {
        $result = $this->saleService->cancel(
            $sale,
            'Customer requested cancellation - duplicate order'
        );
        
        if ($result) {
            return response()->json([
                'message' => 'Sale cancelled successfully',
                'sale_number' => $sale->number,
            ]);
        }
    } catch (\Exception $e) {
        return response()->json([
            'error' => $e->getMessage()
        ], 400);
    }
}

​

Protected Methods

​

generateSaleAccountingEntry()

protected function generateSaleAccountingEntry(Sale $sale)

• Debits the payment method’s accounting account (or default 1.1.01 Cash)
• Credits Income Account 4.1 (Sales Revenue)
• Description format: “Venta Contado () - ”
• Status: 'posted' (immediately posted)

​

generateCancellationAccountingEntry()

protected function generateCancellationAccountingEntry(Sale $sale)

• Debits Income Account 4.1 (reverses revenue recognition)
• Credits:
  • Cash Account (1.1.01) for cash sales
  • Client’s accounting account or default Receivable Account (1.1.02) for credit sales
• Reference format: “REV-”
• Description: “Anulación Venta ”

​

Sale Model Constants

​

Payment Types

Sale::PAYMENT_CASH   // 'cash'
Sale::PAYMENT_CREDIT // 'credit'

​

Status Constants

Sale::STATUS_COMPLETED // 'completed'
Sale::STATUS_CANCELED  // 'canceled'

​

Exception Handling

​

Integration Points

​

InventoryMovementService

• On Sale Creation: Registers TYPE_OUTPUT movements for each product
• On Sale Cancellation: Registers TYPE_ADJUSTMENT movements to restore inventory
• See InventoryMovementService for details

​

JournalEntryService

• Cash Sales: Creates posted journal entries for immediate revenue recognition
• Sale Cancellation: Creates reversal entries to negate original transaction
• See JournalEntryService for details

​

ReceivableService

• Credit Sales: Creates receivable records with 30-day due date
• Cancellation: Cancels receivables if no payments have been applied
• See ReceivableService for details

​

InvoiceService

• Creates invoice record from completed sale
• Cancels invoice when sale is cancelled

​

NcfGeneratorInterface

• Generates fiscal control numbers (NCF) when ncf_type_id is provided
• Updates NCF log status on cancellation

​

Database Transaction Safety

​

Related Models

• Sale Model - Main sale entity
• SaleItem Model - Individual line items
• Receivable Model - Accounts receivable
• JournalEntry Model - Accounting entries
• InventoryMovement Model - Inventory tracking