Invoice Ninja Documentation

The client portal provides endpoints for user authentication, registration, and password management. These routes are used by clients to access their specific company data.

Authentication

• Login Form: GET /client/login/{company_key?}
• Login Submit: POST /client/login/{company_key?}
• Magic Link Login: GET /client/magic_link/{magic_link}
• Contact Key Login: GET /client/key_login/{contact_key}
• Logout: GET /logout (within authenticated session)

Registration

• Register Form: GET /client/register/{company_key?}
• Register Submit: POST /client/register/{company_key?}

Password Management

• Request Reset Link: GET /client/password/reset
• Send Reset Email: POST /client/password/email
• Reset Form: GET /client/password/reset/{token}
• Update Password: POST /client/password/reset
• Set Password (Invitation): GET /set_password and POST /set_password

The Cypress configuration for this project is defined in cypress.config.js. It uses defineConfig to set up the testing environment. Key settings include:

• chromeWebSecurity: Set to false to allow cross-origin requests during testing.
• retries: Configured to 2 to handle flaky tests.
• video: Disabled (false).
• defaultCommandTimeout: Set to 5000ms.
• watchForFileChanges: Disabled (false).
• videosFolder: Located at tests/cypress/videos.
• screenshotsFolder: Located at tests/cypress/screenshots.
• fixturesFolder: Located at tests/cypress/fixture.

End-to-End (e2e) specific settings:

• baseUrl: The default testing URL is http://ninja.test:8000/.
• specPattern: Tests are expected in tests/cypress/integration/**/*.cy.{js,jsx,ts,tsx}.
• supportFile: The support file is located at tests/cypress/support/index.js.
• setupNodeEvents: Hooks into ./tests/cypress/plugins/index.js to initialize plugin events.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
    chromeWebSecurity: false,
    retries: 2,
    video: false,
    defaultCommandTimeout: 5000,
    watchForFileChanges: false,
    videosFolder: 'tests/cypress/videos',
    screenshotsFolder: 'tests/cypress/screenshots',
    fixturesFolder: 'tests/cypress/fixture',
    e2e: {
        setupNodeEvents(on, config) {
            return require('./tests/cypress/plugins/index.js')(on, config)
        },
        baseUrl: 'http://ninja.test:8000/',
        specPattern: 'tests/cypress/integration/**/*.cy.{js,jsx,ts,tsx}',
        supportFile: 'tests/cypress/support/index.js',
    },
})

The main application configuration is driven by environment variables. You can set these in your .env file to control the behavior of Invoice Ninja. The following environment variables are used by config/app.php:

• APP_NAME: The name of your application (default: Invoice Ninja).
• APP_ENV: The application environment, e.g., production (default: production).
• APP_DEBUG: Enables detailed error messages and stack traces (default: false).
• APP_URL: The root URL of your application, used for generating URLs in Artisan tasks (default: http://localhost).
• MIX_ASSET_URL: The URL used for assets. Defaults to APP_URL if not specified.
• SERVER_TIMEZONE: The default timezone for PHP date/time functions (default: UTC).
• DEFAULT_LOCALE: The default locale for the translation service (default: en).
• APP_KEY: A random 32-character string used for encryption. This must be set before deploying.

These routes are used when a client interacts with an invitation link (e.g., via email) and may not be logged in yet. They use the invite_db middleware.

Invitation Routing

• Invoice Invitation: GET /client/invoice/{invitation_key}
• Recurring Invoice Invitation: GET /client/recurring_invoice/{invitation_key}
• Quote Invitation: GET /client/quote/{invitation_key}
• Credit Invitation: GET /client/credit/{invitation_key}
• Pay via Invitation: GET /client/pay/{invitation_key}
• Generic Entity Download: GET /{entity}/{invitation_key}/download

Invitation Downloads (PDF/E-Invoice)

• Invoice PDF: GET /client/invoice/{invitation_key}/download_pdf
• Invoice E-Invoice: GET /client/invoice/{invitation_key}/download_e_invoice
• Quote PDF: GET /client/quote/{invitation_key}/download_pdf
• Quote E-Quote: GET /client/quote/{invitation_key}/download_e_quote
• Credit PDF: GET /client/credit/{invitation_key}/download_pdf
• Credit E-Credit: GET /client/credit/{invitation_key}/download_e_credit
• Recurring Invoice PDF: GET /client/recurring_invoice/{invitation_key}/download_pdf

Email and Unsubscribe

• Email Preferences: GET /client/email_preferences/{entity}/{invitation_key}
• Update Email Preferences: PUT /client/email_preferences/{entity}/{invitation_key}
• Unsubscribe: GET /client/unsubscribe/{entity}/{invitation_key}

The App\/Models\/Client class is the primary data model for clients in Invoice Ninja. It manages client information, including contact details, addresses, settings, and financial balances. It supports soft deletes and is searchable via Scout.

Key Attributes

• Identification: id, client_hash, number, id_number.
• Financials: balance, paid_to_date, credit_balance, payment_balance.
• Contact Info: name, website, phone, email (via contacts), address1, address2, city, state, postal_code, country_id.
• Settings: settings (object), group_settings (object), is_tax_exempt, has_valid_vat_number.
• Custom Fields: custom_value1 through custom_value4.

Relationships

• Company: company() (BelongsTo)
• User/Staff: user() (BelongsTo), assigned_user() (BelongsTo)
• Contacts: contacts() (HasMany), primary_contact() (HasMany)
• Financial Documents: invoices() (HasMany), quotes() (HasMany), tasks() (HasMany), payments() (HasMany), credits() (HasMany), expenses() (HasMany)
• Other: locations() (HasMany), projects() (HasMany), documents() (MorphMany)