Skip to main content
This guide will help you set up Torn and process your first sale in just a few minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.8+ installed
  • Node.js 16+ and npm
  • PostgreSQL 12+ running
  • A code editor

​
Quick Setup

1

Clone and Setup Backend

Clone the repository and set up the Python environment:
git clone https://github.com/AstralMoonlight/torn.git
cd torn

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
2

Configure Database

Create a .env file in the project root:
.env
# Database Configuration
TORN_DB_URL=postgresql://user:password@localhost/torn_db

# JWT Secret (generate a random string)
SECRET_KEY=your-secret-key-here-change-in-production

# Optional: SII Integration
SII_CERT_PATH=/path/to/certificate.pfx
SII_CERT_PASSWORD=your-cert-password
The database will be created automatically on first run.
3

Start the Backend

Launch the FastAPI backend:
uvicorn app.main:app --reload --port 8000
Your API is now running at http://localhost:8000. Visit http://localhost:8000/docs to see the interactive API documentation.
4

Create Your First Tenant

Create a tenant (business entity) using the API. First, you’ll need to authenticate as a global admin (this happens automatically on first startup):
curl -X POST http://localhost:8000/saas/tenants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "name": "Mi Tienda SpA",
    "rut": "76123456-7",
    "address": "Av. Providencia 1234",
    "commune": "Providencia",
    "city": "Santiago",
    "giro": "Venta al por menor",
    "billing_day": 15,
    "economic_activities": [
      {
        "code": "522900",
        "name": "Venta al por menor en comercios no especializados"
      }
    ]
  }'
This automatically provisions a new database schema for the tenant with complete isolation.
5

Add Products

Add some products to your catalog:
curl -X POST http://localhost:8000/products/ \
  -H "X-Tenant-ID: 1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Coca-Cola 1.5L",
    "precio_venta": 1500,
    "precio_compra": 900,
    "stock_actual": 100,
    "stock_minimo": 10,
    "controla_stock": true
  }'
6

Open Cash Session

Before making sales, open a cash session:
curl -X POST http://localhost:8000/cash/open \
  -H "X-Tenant-ID: 1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "initial_cash": 50000,
    "notes": "Turno matutino"
  }'
7

Create Your First Sale

Process a sale with automatic DTE generation:
curl -X POST http://localhost:8000/sales/ \
  -H "X-Tenant-ID: 1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_rut": "66666666-6",
    "document_type": 39,
    "items": [
      {
        "product_id": 1,
        "quantity": 2,
        "unit_price": 1500
      }
    ],
    "payments": [
      {
        "method": "EFECTIVO",
        "amount": 3000
      }
    ]
  }'
This single request:
  • Validates stock availability
  • Deducts inventory with Kardex tracking
  • Processes the payment
  • Generates a DTE (electronic tax document)
  • Returns the complete sale with folio number
Document type 39 is for “Boleta Electrónica” (retail receipt). Use type 33 for “Factura” (invoice).

​
What Just Happened?

Behind the scenes, Torn executed an atomic transaction that:
  1. ✅ Verified the cash session is open
  2. ✅ Validated product availability and stock
  3. ✅ Created the sale record
  4. ✅ Deducted inventory with FIFO/LIFO tracking
  5. ✅ Recorded the Kardex movement
  6. ✅ Processed payment method
  7. ✅ Assigned a fiscal folio (CAF)
  8. ✅ Generated the DTE XML
  9. ✅ Committed everything or rolled back on any error
All in milliseconds with complete data integrity.

​
Optional: Start the Frontend

For a complete POS experience, start the Next.js frontend: 
cd frontend
npm install
npm run dev
Access the UI at http://localhost:3000
The frontend requires the backend to be running on port 8000.

​
Troubleshooting

Ensure PostgreSQL is running and the connection string in .env is correct. The format is:
postgresql://username:password@host:port/database
You must open a cash session before creating sales. Use POST /cash/open with an initial cash amount.
Verify the product exists and has sufficient stock. Use GET /products/ to list all products and GET /inventory/ to check stock levels.
Make sure to include the JWT token in the Authorization: Bearer TOKEN header for all protected endpoints.

​
Next Steps

Multi-Tenancy

Learn about tenant isolation

Sales Process

Master the complete sales workflow

API Reference

Explore all endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us