Multi-Company Management

Overview

The API supports multi-company and multi-branch architecture, allowing you to manage electronic invoicing for multiple legal entities and their branches from a single integration.

Architecture

The system uses a hierarchical structure:

API Instance
└── Company 1 (RUC: 20123456789)
    ├── Branch 1 (Main Office)
    │   ├── Invoice Series: F001, F002
    │   ├── Boleta Series: B001
    │   └── Credit Note Series: FC01
    │
    └── Branch 2 (Store Lima)
        ├── Boleta Series: B002, B003
        └── Credit Note Series: BC01

└── Company 2 (RUC: 20987654321)
    └── Branch 1 (Headquarters)
        ├── Invoice Series: F001
        └── Boleta Series: B001

Creating a Company

Company Registration

{
  "ruc": "20123456789",
  "razon_social": "EMPRESA DEMO SAC",
  "nombre_comercial": "Demo Company",
  "direccion": "Av. Javier Prado 1234",
  "ubigeo": "150101",
  "distrito": "San Isidro",
  "provincia": "Lima",
  "departamento": "Lima",
  "telefono": "01-1234567",
  "email": "[email protected]",
  "web": "https://www.empresa.com",
  "usuario_sol": "20123456789MODDATOS",
  "clave_sol": "moddatos",
  "certificado_password": "password123",
  "modo_produccion": false,
  "activo": true
}

Success Response:

{
  "success": true,
  "message": "Empresa creada exitosamente",
  "data": {
    "id": 1,
    "ruc": "20123456789",
    "razon_social": "EMPRESA DEMO SAC",
    "nombre_comercial": "Demo Company",
    "direccion": "Av. Javier Prado 1234",
    "ubigeo": "150101",
    "distrito": "San Isidro",
    "provincia": "Lima",
    "departamento": "Lima",
    "telefono": "01-1234567",
    "email": "[email protected]",
    "web": "https://www.empresa.com",
    "usuario_sol": "20123456789MODDATOS",
    "modo_produccion": false,
    "activo": true,
    "created_at": "2024-03-15T10:30:00.000000Z"
  }
}

Required Company Fields

ruc

string

required

Company RUC (11 digits, must be unique)

Legal business name (as registered with SUNAT)

direccion

string

required

Complete legal address

ubigeo

string

required

UBIGEO code (6 digits) - Geographic code

distrito

string

required

District name

provincia

string

required

Province name

departamento

string

required

Department name

string

required

Company email for notifications

usuario_sol

string

required

SUNAT SOL username (format: RUC + username)

clave_sol

string

required

SUNAT SOL password

Optional Fields

nombre_comercial

string

Commercial/trade name

telefono

string

Phone number

web

string

Company website URL

certificado_pem

file

Digital certificate file (.pem, .crt, .cer)

certificado_password

string

Certificate password

logo_path

file

Company logo (PNG/JPG, max 2MB)

modo_produccion

boolean

default:"false"

Environment mode:

false: Beta/testing environment
true: Production environment

activo

boolean

default:"true"

Active status

Start with modo_produccion: false to test in SUNAT’s beta environment. Switch to production only after thorough testing.

Creating Branches

Branch Registration

{
  "company_id": 1,
  "codigo": "0001",
  "nombre": "Tienda Principal",
  "direccion": "Av. Javier Prado 1234",
  "ubigeo": "150101",
  "distrito": "San Isidro",
  "provincia": "Lima",
  "departamento": "Lima",
  "telefono": "01-1234567",
  "email": "[email protected]",
  "contacto_nombre": "Juan Perez",
  "series_factura": ["F001", "F002"],
  "series_boleta": ["B001", "B002"],
  "series_nota_credito": ["FC01", "BC01"],
  "series_nota_debito": ["FD01", "BD01"],
  "series_guia_remision": ["T001"],
  "activo": true
}

Success Response:

{
  "success": true,
  "message": "Sucursal creada exitosamente",
  "data": {
    "id": 1,
    "company_id": 1,
    "codigo": "0001",
    "nombre": "Tienda Principal",
    "direccion": "Av. Javier Prado 1234",
    "ubigeo": "150101",
    "distrito": "San Isidro",
    "provincia": "Lima",
    "departamento": "Lima",
    "series_factura": ["F001", "F002"],
    "series_boleta": ["B001", "B002"],
    "activo": true,
    "company": {
      "id": 1,
      "ruc": "20123456789",
      "razon_social": "EMPRESA DEMO SAC"
    }
  }
}

Required Branch Fields

company_id

integer

required

ID of the parent company

codigo

string

required

Branch code (max 10 characters, unique per company)

nombre

string

required

Branch name

direccion

string

required

Branch address

ubigeo

string

required

UBIGEO code (6 digits)

distrito

string

required

District

provincia

string

required

Province

departamento

string

required

Department

Series Configuration

Each branch can have multiple series for different document types:

series_factura

array

Invoice series (e.g., [“F001”, “F002”])

Must start with ‘F’ for facturas
4 characters max

series_boleta

array

Boleta series (e.g., [“B001”, “B002”])

Must start with ‘B’ for boletas
4 characters max

series_nota_credito

array

Credit note series (e.g., [“FC01”, “BC01”])

FC for invoice credit notes
BC for boleta credit notes

series_nota_debito

array

Debit note series (e.g., [“FD01”, “BD01”])

FD for invoice debit notes
BD for boleta debit notes

series_guia_remision

array

Dispatch guide series (e.g., [“T001”])

T for transport guides

Series must be registered with SUNAT before use. Each series maintains its own correlative number sequence.

Querying Companies

List All Companies

curl -X GET https://api.example.com/api/companies \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "ruc": "20123456789",
      "razon_social": "EMPRESA DEMO SAC",
      "modo_produccion": false,
      "activo": true,
      "branches": [
        {
          "id": 1,
          "nombre": "Tienda Principal"
        },
        {
          "id": 2,
          "nombre": "Tienda Lima"
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "active_count": 1,
    "production_count": 0
  }
}

Get Company Details

curl -X GET https://api.example.com/api/companies/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Company Branches

curl -X GET https://api.example.com/api/companies/1/branches \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "codigo": "0001",
      "nombre": "Tienda Principal",
      "activo": true
    },
    {
      "id": 2,
      "codigo": "0002",
      "nombre": "Tienda Lima",
      "activo": true
    }
  ],
  "meta": {
    "company_id": 1,
    "company_name": "EMPRESA DEMO SAC",
    "total_branches": 2,
    "active_branches": 2
  }
}

Updating Companies

curl -X PUT https://api.example.com/api/companies/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "razon_social": "EMPRESA DEMO SAC UPDATED",
    "email": "[email protected]",
    "telefono": "01-9876543"
  }'

Cannot change RUC after company creation. Create a new company if RUC needs to change.

Switching Environments

Toggle Production Mode

curl -X POST https://api.example.com/api/companies/1/toggle-production \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "modo_produccion": true
  }'

Response:

{
  "success": true,
  "message": "Modo de producción actualizado exitosamente",
  "data": {
    "company_id": 1,
    "modo_anterior": "beta",
    "modo_actual": "produccion"
  }
}

Before switching to production:

Test all document types in beta environment
Verify SUNAT credentials work correctly
Ensure certificate is valid for production
Confirm all series are registered with SUNAT

Activating/Deactivating

Deactivate Company

curl -X DELETE https://api.example.com/api/companies/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

This performs a soft delete (sets activo: false).

Reactivate Company

curl -X POST https://api.example.com/api/companies/1/activate \
  -H "Authorization: Bearer YOUR_TOKEN"

Correlative Numbers

Each branch + series combination maintains independent correlative numbers:

Company 1
  Branch 1
    F001: 1, 2, 3, 4, ...
    F002: 1, 2, 3, ...
    B001: 1, 2, 3, ...
  Branch 2
    F001: 1, 2, 3, ...  (independent from Branch 1 F001)
    B001: 1, 2, 3, ...

The system automatically generates the next correlative when creating documents.

Multi-Company Usage Example

Scenario: Accounting Firm

An accounting firm manages invoicing for 3 clients:

# Create Company 1
curl -X POST https://api.example.com/api/companies \
  -d '{"ruc": "20111111111", "razon_social": "CLIENT A SAC", ...}'

# Create Company 2
curl -X POST https://api.example.com/api/companies \
  -d '{"ruc": "20222222222", "razon_social": "CLIENT B SAC", ...}'

# Create Company 3
curl -X POST https://api.example.com/api/companies \
  -d '{"ruc": "20333333333", "razon_social": "CLIENT C SAC", ...}'

# Create branch for Client A
curl -X POST https://api.example.com/api/branches \
  -d '{"company_id": 1, "nombre": "Main Office", ...}'

# Issue invoice for Client A
curl -X POST https://api.example.com/api/invoices \
  -d '{"company_id": 1, "branch_id": 1, ...}'

Implementation Details

From app/Http/Controllers/Api/CompanyController.php and BranchController.php:

Company Creation (Line 54-68)

Validates RUC uniqueness
Processes boolean fields
Stores certificate file if provided
Stores logo file if provided
Creates company record
Returns company with configurations

Branch Creation (Line 56-98)

Validates company exists and is active
Validates branch code unique per company
Creates branch with series configuration
Returns branch with company relationship

Validation Rules

From app/Http/Requests/Company/StoreCompanyRequest.php:

RUC: Exactly 11 digits, unique
UBIGEO: Exactly 6 digits
Email: Valid email format
Certificate: .pem, .crt, .cer, .txt (max 2MB)
Logo: PNG/JPG (max 2MB)

Best Practices

Use descriptive branch codes: “0001”, “LIMA”, “CUSCO”
Configure series upfront: Set all series when creating branch
Test in beta first: Always test with modo_produccion: false
One company per RUC: Don’t duplicate companies
Logical branch structure: Match physical locations
Keep credentials secure: Store SOL credentials encrypted
Upload company logos: Better PDF presentation
Use consistent naming: Standard naming for branches/series

Common Errors

Error	Cause	Solution
RUC already exists	Duplicate company	Use existing company or different RUC
Branch code exists	Duplicate code in company	Use unique code per company
Company not active	Deactivated company	Activate company first
Invalid UBIGEO	Wrong format	Use valid 6-digit UBIGEO
Branch belongs to different company	Wrong company_id	Verify company_id matches

Get Started

Core Concepts

Guides

Advanced

Overview

Architecture

Creating a Company

Company Registration

Required Company Fields

Optional Fields

Creating Branches

Branch Registration

Required Branch Fields

Series Configuration

Querying Companies

List All Companies

Get Company Details

Get Company Branches

Updating Companies

Switching Environments

Toggle Production Mode

Activating/Deactivating

Deactivate Company

Reactivate Company

Correlative Numbers

Multi-Company Usage Example

Scenario: Accounting Firm

Implementation Details

Company Creation (Line 54-68)

Branch Creation (Line 56-98)

Validation Rules

Best Practices

Common Errors

Next Steps

Creating Invoices

PDF Generation

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Overview

​Architecture

​Creating a Company

​Company Registration

​Required Company Fields

​Optional Fields

​Creating Branches

​Branch Registration

​Required Branch Fields

​Series Configuration

​Querying Companies

​List All Companies

​Get Company Details

​Get Company Branches

​Updating Companies

​Switching Environments

​Toggle Production Mode

​Activating/Deactivating

​Deactivate Company

​Reactivate Company

​Correlative Numbers

​Multi-Company Usage Example

​Scenario: Accounting Firm

​Implementation Details

​Company Creation (Line 54-68)

​Branch Creation (Line 56-98)

​Validation Rules

​Best Practices

​Common Errors

​Next Steps

Creating Invoices

PDF Generation

Build docs developers (and LLMs) love

Overview

Architecture

Creating a Company

Company Registration

Required Company Fields

Optional Fields

Creating Branches

Branch Registration

Required Branch Fields

Series Configuration

Querying Companies

List All Companies

Get Company Details

Get Company Branches

Updating Companies

Switching Environments

Toggle Production Mode

Activating/Deactivating

Deactivate Company

Reactivate Company

Correlative Numbers

Multi-Company Usage Example

Scenario: Accounting Firm

Implementation Details

Company Creation (Line 54-68)

Branch Creation (Line 56-98)

Validation Rules

Best Practices

Common Errors

Next Steps