Social Works Management

Overview

The Social Works Management feature handles insurance providers (obras sociales) in the Clínica Vitalis system. Social works represent health insurance organizations that provide coverage for patients, and each patient must be affiliated with a social work for billing and coverage purposes.

Data Model

Social works are structured with comprehensive information:

interface ISocialsWorks {
    id: number;
    name: string;       // Unique insurance provider name
    state?: string;     // active | inactive
    address: string;    // Physical address of the organization
    phone: string;      // Contact phone number
    webpage: string;    // Official website URL
}

Activa (Active): Insurance provider is currently accepted by the clinic
Inactiva (Inactive): Insurance provider is no longer accepted for new patients

Key Features

Administrators can register new insurance providers:

Enter Basic Information

Provide the insurance provider’s name (must be unique).

Add Contact Details

Enter physical address, phone number (10-20 characters), and website URL.

Validate Information

System validates:

Name uniqueness
Phone number format (numbers, spaces, dashes only)
All required fields are present

Create Record

Social work is created with “Active” state by default.

Social work names must be unique to prevent duplicate insurance provider registrations.

Validation Rules

Strict validation ensures data quality from backend/routes/socialsWorks.ts:29-43:

check("name", "El nombre es obligatorio").not().isEmpty()
check("name").custom(existNameSocialWork)  // Ensures uniqueness
check("address", "La dirección es obligatoria").not().isEmpty()
check("phone", "El teléfono es obligatorio")
    .not().isEmpty()
    .isLength({ min: 10, max: 20 })
    .withMessage("El teléfono debe tener entre 10 y 20 caracteres")
    .matches(/^[0-9\s\-\+]*$/)
    .withMessage("El teléfono solo puede contener números, guiones o espacios")
check("webpage", "La dirección es obligatoria").not().isEmpty()

Database Constraints

The model enforces important business rules:

// From backend/models/socialsWorks.ts:25-46
name: {
    type: DataTypes.STRING,
    allowNull: false,
    unique: true        // Database-level uniqueness
}
state: {
    type: DataTypes.ENUM(...Object.values(STATES_SOCIALSWORKS)),
    allowNull: false,
    defaultValue: STATES_SOCIALSWORKS.active
}
address: {
    type: DataTypes.STRING,
    allowNull: false,
}
phone: {
    type: DataTypes.STRING,
    allowNull: false,
}
webpage: {
    type: DataTypes.STRING,
    allowNull: false,
}

Social works can be retrieved:

All social works: Complete list including active and inactive providers
By ID: Specific social work details
With Patients: When viewing patients, their social work information is included

Administrators can modify insurance provider information:

Locate Social Work

Find the insurance provider by ID or from the list.

Update Information

Modify name, address, phone, webpage, or state as needed.

Validate Changes

System validates name uniqueness (excluding current record) and all required fields.

Save Changes

Updated information is persisted to the database.

When updating a social work’s name, the system ensures the new name doesn’t conflict with other social works.

Patient Integration

Social works are directly linked to patients:

Assignment

Each patient must be affiliated with a social work:

// From backend/models/patients.ts:66-73
socialWorkId: {
    type: DataTypes.INTEGER,
    allowNull: false,
    references: {
        model: "Obras_Sociales",
        key: "id"
    }
}

Validation

Before assigning a patient to a social work, the system validates:

Social work exists in the database
Social work ID is valid

This is performed by the existSocialWorkById custom validator in patient routes.

API Endpoints

GET `/api/socialsWorks`

Retrieve all social works. Response:

{
  "socialsWorks": [
    {
      "id": 1,
      "name": "OSDE",
      "state": "Activa",
      "address": "Av. Corrientes 1234, CABA",
      "phone": "+54 11 4567-8900",
      "webpage": "https://www.osde.com.ar"
    },
    {
      "id": 2,
      "name": "Swiss Medical",
      "state": "Activa",
      "address": "Av. Libertador 5678, CABA",
      "phone": "+54 11 5555-1234",
      "webpage": "https://www.swissmedical.com.ar"
    }
  ]
}

GET `/api/socialsWorks/:id`

Retrieve a specific social work by ID. Response:

{
  "socialWork": {
    "id": 1,
    "name": "OSDE",
    "state": "Activa",
    "address": "Av. Corrientes 1234, CABA",
    "phone": "+54 11 4567-8900",
    "webpage": "https://www.osde.com.ar"
  }
}

POST `/api/socialsWorks`

Create a new social work (Admin only). Required Fields:

name, address, phone, webpage

Example Request:

{
  "name": "Medicus",
  "address": "Av. del Libertador 6810, CABA",
  "phone": "+54 11 4000-7500",
  "webpage": "https://www.medicus.com.ar"
}

PATCH `/api/socialsWorks/:id`

Update a social work (Admin only). Required Fields:

name, state, address, phone, webpage

Example Request:

{
  "name": "Medicus",
  "state": "Activa",
  "address": "Av. del Libertador 6810, CABA",
  "phone": "+54 11 4000-7500",
  "webpage": "https://www.medicus.com.ar"
}

State Management

When the clinic stops accepting an insurance provider:

Update the social work state to “Inactive”
Existing patients keep their affiliation
New patients cannot be registered with inactive social works
Contact information remains accessible for billing and records

Never delete social works that have patients assigned to them. Use the state field to mark them as inactive.

If the clinic resumes accepting an insurance provider:

Update the state back to “Active”
The social work becomes available for new patient registrations

Phone Number Format

Phone numbers must meet specific criteria:

Length: Between 10 and 20 characters
Allowed characters: Numbers, spaces, dashes (-), and plus sign (+)
Examples:
- Valid: “+54 11 4567-8900”, “011-4567-8900”, “01145678900”
- Invalid: “123” (too short), “phone” (contains letters)

Use Cases

Adding New Insurance Provider

Clinic Signs Agreement

Clinic establishes a contract with a new insurance provider.

Gather Information

Collect provider’s name, contact details, and website.

Administrator creates the social work with all required information.

Available for Patients

Patients can now be registered with this insurance provider.

Updating Contact Information

When an insurance provider changes their contact details:

Locate the social work in the system
Update the address, phone, or webpage as needed
Save changes for future reference

Filtering Patients by Insurance

Staff can filter patients by their insurance provider:

GET /api/patients?socialWorkId=1

This is useful for:

Billing purposes
Insurance-specific reporting
Coverage verification

Typical insurance providers in Argentina:

OSDE - Organización de Servicios Directos Empresarios
Swiss Medical
OSECAC - Obra Social de Empleados de Comercio
IOMA - Instituto de Obra Médico Asistencial
PAMI - Programa de Atención Médica Integral
Medicus
Galeno
OSPE - Obra Social del Personal de la Edificación
OSDEPYM - Obra Social de Empresarios, Profesionales y Monotributistas

Security

All social work operations require JWT authentication. Create and update operations are restricted to administrators only.

Authentication Requirements:

GET requests: Authenticated users only
POST/PATCH requests: Administrator role required

Database Relationships

Social works connect to:

Patients (One-to-Many): Each social work can have multiple affiliated patients
Appointments (Indirectly): Through patients, appointments are linked to insurance providers

Reporting and Billing

Social work information is essential for:

Patient affiliation tracking
Insurance billing and claims
Coverage verification
Patient distribution by insurance provider
Insurance provider contact for authorizations

Best Practices

Keep contact information updated for effective communication with insurance providers
Validate insurance provider exists and is active before registering patients
Use consistent naming for insurance providers (official names)
Use state management instead of deleting social works
Maintain complete contact information including phone and website
Filter by active state when showing options for new patient registration
Document insurance agreements and update states when contracts change
Regularly review inactive social works for potential reactivation
Keep website URLs current for easy reference to coverage information

Get Started

Core Features

Authentication

Deployment

Overview

Data Model

Key Features

Validation Rules

Database Constraints

Patient Integration

Assignment

Validation

API Endpoints

GET `/api/socialsWorks`

GET `/api/socialsWorks/:id`

POST `/api/socialsWorks`

PATCH `/api/socialsWorks/:id`

State Management

Phone Number Format

Use Cases

Adding New Insurance Provider

Updating Contact Information

Filtering Patients by Insurance

Security

Database Relationships

Reporting and Billing

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Features

Authentication

Deployment

​Overview

​Data Model

​Social Work States

​Key Features

​Create Social Work

​Validation Rules

​Database Constraints

​View Social Works

​Update Social Work

​Patient Integration

​Assignment

​Validation

​API Endpoints

​GET /api/socialsWorks

​GET /api/socialsWorks/:id

​POST /api/socialsWorks

​PATCH /api/socialsWorks/:id

​State Management

​Inactivating Social Works

​Reactivating Social Works

​Phone Number Format

​Use Cases

​Adding New Insurance Provider

​Updating Contact Information

​Filtering Patients by Insurance

​Common Social Works (Argentina)

​Security

​Database Relationships

​Reporting and Billing

​Best Practices

Build docs developers (and LLMs) love

Overview

Data Model

Social Work States

Key Features

Create Social Work

Validation Rules

Database Constraints

View Social Works

Update Social Work

Patient Integration

Assignment

Validation

API Endpoints

GET `/api/socialsWorks`

GET `/api/socialsWorks/:id`

POST `/api/socialsWorks`

PATCH `/api/socialsWorks/:id`

State Management

Inactivating Social Works

Reactivating Social Works

Phone Number Format

Use Cases

Adding New Insurance Provider

Updating Contact Information

Filtering Patients by Insurance

Common Social Works (Argentina)

Security

Database Relationships

Reporting and Billing

Best Practices