Merge pull request #10083 from turbo124/v5-develop

Update API docs

app/Jobs/Company/CreateCompany.php

@@ -84,6 +84,7 @@ class CreateCompany
             '724' => $company = $this->spanishSetup($company),
             '36'  => $company = $this->australiaSetup($company),
             '710' => $company = $this->southAfticaSetup($company),
+            '554' => $company = $this->newZealandSetup($company),
             default => $company->save(),
         };
 
@@ -131,6 +132,22 @@ class CreateCompany
 
     }
 
+    private function newZealandSetup($company): Company
+    {
+
+        $company->enabled_tax_rates = 1;
+
+        $settings = $company->settings;
+        $settings->currency_id = '15';
+        $settings->timezone_id = '113';
+
+        $company->settings = $settings;
+
+        $company->save();
+
+        return $company;
+    }
+
     private function spanishSetup(Company $company): Company
     {
         try {

app/Models/Company.php

@@ -120,6 +120,8 @@ use Laracasts\Presenter\PresentableTrait;
  * @property bool $inbound_mailbox_allow_unknown
  * @property string|null $inbound_mailbox_whitelist
  * @property string|null $inbound_mailbox_blacklist
+ * @property string|null $e_invoice_certificate_passphrase
+ * @property string|null $e_invoice_certificate
  * @property int $deleted_at
  * @property string|null $smtp_username
  * @property string|null $smtp_password

app/Repositories/ExpenseRepository.php

@@ -121,6 +121,7 @@ class ExpenseRepository extends BaseRepository
             $exchange_rate = new CurrencyApi();
 
             $expense->exchange_rate = $exchange_rate->exchangeRate($expense_currency, $company_currency, Carbon::parse($expense->date));
+            $expense->invoice_currency_id = $company_currency;
             
             return $expense;
         }

app/Services/Company/CompanyService.php

@@ -56,6 +56,9 @@ class CompanyService
                 case '724': // Spain
                     $taxes[] = ['name' => 'IVA', 'rate' => 21];
                     break;
+                case '554': // New Zealand                    
+                    $taxes[] = ['name' => 'GST', 'rate' => 15];
+                    break;
     
                 default:
                     return;

app/Utils/Traits/Pdf/PDF.php

@@ -19,7 +19,7 @@ class PDF extends FPDI
 
     public function Footer()
     {
-        $this->SetXY(0, -6);
+        $this->SetXY(config('ninja.pdf_page_numbering_x_alignment'), config('ninja.pdf_page_numbering_y_alignment'));
 
         $this->SetFont('Arial', 'I', 9);
 

config/ninja.php

@@ -255,4 +255,7 @@ return [
     'storecove_api_key' => env('STORECOVE_API_KEY', false), 
     'qvalia_api_key' => env('QVALIA_API_KEY', false),   
     'qvalia_partner_number' => env('QVALIA_PARTNER_NUMBER', false), 
+    'pdf_page_numbering_x_alignment' => env('PDF_PAGE_NUMBER_X', 0),
+    'pdf_page_numbering_y_alignment' => env('PDF_PAGE_NUMBER_Y', -6),
+    
 ];

lang/fr_CA/texts.php

@@ -2361,7 +2361,7 @@ Lorsque les montant apparaîtront sur votre relevé, veuillez revenir sur cette
     'currency_gold_troy_ounce' => 'Once troy d\'or',
     'currency_nicaraguan_córdoba' => 'Cordoba nicaraguayen',
     'currency_malagasy_ariary' => 'Ariary malgache',
-    "currency_tongan_paanga" => "Pa'anga tongien",
+    "currency_tongan_pa_anga" => "Pa'anga tongien",
 
     'review_app_help' => 'Nous espérons que votre utilisation de cette application vous est agréable.<br/>Un commentaire de votre part serait grandement apprécié!',
     'writing_a_review' => 'rédiger un commentaire',
@@ -5353,7 +5353,8 @@ Développe automatiquement la section des notes dans le tableau de produits pour
     'inbound_mailbox_allow_unknown' => 'Autoriser tous les envois',
     'inbound_mailbox_allow_unknown_help' => 'Autoriser n\'importe qui à envoyer un courriel de dépenses pour traitement.',
     'quick_actions' => 'Actions rapides',
-    'end_all_sessions_help' => 'Déconnecte tous les utilisateurs et oblige tous les utilisateurs actifs à se réauthentifier.'
+    'end_all_sessions_help' => 'Déconnecte tous les utilisateurs et oblige tous les utilisateurs actifs à se réauthentifier.',
+    'updated_records' => 'Enregistrements mis à jour',
 );
 
 return $lang;

openapi/components/schemas/client_request.yaml

@@ -135,7 +135,6 @@
           description: 'Flag which defines if the client has a valid VAT number'
           type: boolean
           example: false
-          readOnly: true
         classification:
           description: 'The classification of the client'
           type: string

openapi/components/schemas/company.yaml

@@ -361,6 +361,81 @@
           type: boolean
           example: true
   
+        expense_mailbox:
+          description: "The email address for the expense mailbox"
+          type: string
+          example: "expenses@company.com"
+
+        expense_mailbox_active:
+          description: "Whether the expense mailbox is active"
+          type: boolean
+          example: true
+
+        inbound_mailbox_allow_company_users:
+          description: "Whether company users are allowed to use the inbound mailbox"
+          type: boolean
+          example: true
+
+        inbound_mailbox_allow_vendors:
+          description: "Whether vendors are allowed to use the inbound mailbox"
+          type: boolean
+          example: false
+
+        inbound_mailbox_allow_clients:
+          description: "Whether clients are allowed to use the inbound mailbox"
+          type: boolean
+          example: true
+
+        inbound_mailbox_allow_unknown:
+          description: "Whether unknown senders are allowed to use the inbound mailbox"
+          type: boolean
+          example: false
+
+        inbound_mailbox_whitelist:
+          description: "Comma-separated list of whitelisted email addresses for the inbound mailbox"
+          type: string
+          example: "user1@example.com,user2@example.com"
+
+        inbound_mailbox_blacklist:
+          description: "Comma-separated list of blacklisted email addresses for the inbound mailbox"
+          type: string
+          example: "spam@example.com,unwanted@example.com"
+
+        smtp_host:
+          description: "The SMTP host for sending emails"
+          type: string
+          example: "smtp.gmail.com"
+
+        smtp_port:
+          description: "The SMTP port for sending emails"
+          type: integer
+          example: 587
+
+        smtp_encryption:
+          description: "The encryption method for SMTP"
+          type: string
+          enum: [tls, ssl, null]
+          example: "tls"
+
+        smtp_local_domain:
+          description: "The local domain for SMTP"
+          type: string
+          example: "company.com"
+
+        smtp_verify_peer:
+          description: "Whether to verify the SMTP peer"
+          type: boolean
+          example: true
+
+        e_invoice:
+          description: "E-invoice settings for the company"
+          type: object
+          additionalProperties: true
+
+        legal_entity_id:
+          description: "The ID of the legal entity associated with the company"
+          type: integer
+          example: 1234
         settings:
           $ref: '#/components/schemas/CompanySettings'
       type: object

openapi/components/schemas/company_settings.yaml

@@ -113,8 +113,9 @@
                 example: "Please approve quote"
             lock_invoices:
                 description: "Toggles whether invoices are locked once sent and cannot be modified further"
-                type: boolean
+                type: enum
-                example: true
+                enum: [off, when_sent, when_paid, end_of_month]
+                example: 'off'
             auto_archive_invoice:
                 description: "Toggles whether a invoice is archived immediately following payment"
                 type: boolean
@@ -252,7 +253,7 @@
                 type: string
                 example: "Quote Terms are..."
             invoice_taxes:
-                description: "Taxes can be applied to the invoice"
+                description: "The number of Taxes that can be applied to the invoice"
                 type: number
                 example: "1"
             invoice_design_id:
@@ -310,7 +311,8 @@
             email_sending_method:
                 description: "The email driver to use to send email, options include default, gmail, client_postmark, client_mailgun, client_brevo, office365"
                 type: string
-                example: default
+                enum: [default, gmail, office365, client_postmark, client_mailgun, mailgun, client_brevo]
+                example: 'default'
             gmail_sending_user_id:
                 description: "The hashed_id of the user account to send email from"
                 type: string
@@ -839,4 +841,13 @@
                 description: "The classification for the company"
                 type: string
                 example: "individual"
+            valid_until:
+                description: 'Default validity period for quotes'
+                type: string
+            credit_terms:
+                description: 'Default terms for credit notes'
+                type: string
+            credit_footer:
+                description: 'Default footer for credit notes'
+                type: string
         type: object

openapi/info.yaml

@@ -3,53 +3,46 @@ info:
   title: 'Invoice Ninja API Reference.'
   description: |
         ---
+          ![Invoice Ninja](https://invoicing.co/images/new_logo.png)
           ## Introduction
           Welcome to the Invoice Ninja API documentation, your comprehensive guide to integrating Invoice Ninja's powerful features into your applications. Whether you're building a custom client, automating workflows, or integrating with other systems, our API provides the tools you need to streamline your invoicing and billing processes.
-
+          ### What is Invoice Ninja?
-          ## What is Invoice Ninja?
           Invoice Ninja is a robust source-available platform designed to simplify invoicing, billing, and payment management for freelancers, small businesses, and enterprises alike. With a user-friendly interface, customizable templates, and a suite of powerful features, Invoice Ninja empowers businesses to create professional invoices, track expenses, manage clients, and get paid faster.
-
+          ### Why use the Invoice Ninja API?
-          ## Why use the Invoice Ninja API?
           The Invoice Ninja API allows developers to extend the functionality of Invoice Ninja by programmatically accessing and manipulating data within their Invoice Ninja accounts. With the API, you can automate repetitive tasks, integrate with third-party services, and build custom solutions tailored to your specific business needs.
-
+          ### Getting Started
-          ## Getting Started
           To get started with the Invoice Ninja API, you'll need an active Invoice Ninja account (or your own self hosted installation) and API credentials. If you haven't already done so, sign up for an account at Invoice Ninja and generate your API keys from the settings section.
 
           Once you have your API credentials, you can start exploring the API endpoints, authentication methods, request and response formats, and more using the documentation provided here.
-
+          ### Explore the Documentation  
-          ## Explore the Documentation  
           This documentation is organized into sections to help you navigate and understand the various aspects of the Invoice Ninja API:
 
-          Authentication: Learn how to authenticate your requests to the API using API tokens.
+          - Authentication: Learn how to authenticate your requests to the API using API tokens.
-          Endpoints: Explore the available API endpoints for managing invoices, clients, payments, expenses, and more.
+          - Endpoints: Explore the available API endpoints for managing invoices, clients, payments, expenses, and more.
-          Request and Response Formats: Understand the structure of API requests and responses, including parameters, headers, and payloads.
+          - Request and Response Formats: Understand the structure of API requests and responses, including parameters, headers, and payloads.
-          Error Handling: Learn about error codes, status messages, and best practices for handling errors gracefully.
+          - Error Handling: Learn about error codes, status messages, and best practices for handling errors gracefully.
-          Code Examples: Find code examples and tutorials to help you get started with integrating the Invoice Ninja API into your applications.      
+          - Code Examples: Find code examples and tutorials to help you get started with integrating the Invoice Ninja API into your applications.      
-          
+          ### Need Help?     
-          ## Need Help?     
 
           If you have any questions, encounter any issues, or need assistance with using the Invoice Ninja API, don't hesitate to reach out to our support team or join our community forums. We're here to help you succeed with Invoice Ninja and make the most of our API.    
 
           Let's start building together!
-        
+          ### Endpoints
-          ## Endpoints
           
           <div style="background-color: #2D394E; color: #fff padding: 20px; border-radius: 5px; border: 4px solid #212A3B; box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);">
               <p style="padding:10px; color: #DBDBDB;"">Production: https://invoicing.co</p>
               <p style="padding:10px; color: #DBDBDB;">Demo: https://demo.invoiceninja.com</p>
           </div>
 
-          ## Client Libraries
+          ### Client Libraries
 
           PHP SDK can be found [here](https://github.com/invoiceninja/sdk-php)
-
+          ### Authentication:
-          ## Authentication:
 
           Invoice Ninja uses API tokens to authenticate requests. You can view and manage your API keys in Settings > Account Management > Integrations > API tokens
 
           API requests must be made over HTTPS. Calls made to HTTP will fail.
-
+          ### Errors:
-          ## Errors:
 
           Invoice Ninja uses standard HTTP response codes to indicate the success or failure of a request. below is a table of standard status codes and responses
 
@@ -67,10 +60,9 @@ info:
           | 422         | Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors. |
           | 429         | Too Many Requests: The user has sent too many requests in a given amount of time ("rate limiting"). |
           | 500         | Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
+          ### Pagination
 
-          ## Pagination
+          When using index routes to retrieve lists of data, by default we limit the number of records returned to 20. You can using standard pagination to paginate results, ie: ?per_page=50
-
-          When using index routes to retrieve lists of data, by default we limit the number of records returned to 20. You can using standard pagination to paginate results, ie:
   termsOfService: 'https://invoiceninja.github.io/docs/legal/terms_of_service/#page-content'
   contact:
     email: contact@invoiceninja.com
@@ -79,7 +71,7 @@ info:
   license:
     name: 'Elastic License'
     url: 'https://www.elastic.co/licensing/elastic-license'
-  version: 5.9.2
+  version: 5.10.31
 servers:
   -  url: 'https://demo.invoiceninja.com'
      description: |

openapi/misc/misc.yaml

@@ -1,14 +1,12 @@
 tags:
   - name: login
-    description: |
+    # description: |
-      Attempts to authenticate with the API using a email/password combination.
+    #   Attempts to authenticate with the API using a email/password combination.
-    externalDocs:
+    
-      description: "Find out more"
-      url: "https://invoiceninja.github.io"
   - name: clients
-    x-tag-expanded: true
+    x-tag-expanded: false
-    description: |
+    # description: |
-      Endpoint definitions for interacting with clients.
+    #   Endpoint definitions for interacting with clients.
   - name: products
     description: |
       Endpoint definitions for interacting with products.

openapi/paths/clients.yaml

@@ -3,17 +3,19 @@
       tags:
         - clients
       summary: 'List clients'
-      x-code-samples:
+      x-codeSamples:
-      - lang: go
+      - lang: php
         label: php
         source: |
           $ninja = new InvoiceNinja("your_token");
           $invoices = $ninja->clients->all();
-      x-custom-element:
+      - lang: curl
-            type: markdown
+        label: curl
-            value: |
+        source: |
-              ### Custom Response Description
+          curl --request GET \
-              This is a custom description for the response returned by the `/example` endpoint.
+            --url 'https://invoicing.co/api/v1/clients?per_page=10&page=1&sort=name&sort_dir=asc' \
+            --header 'X-API-TOKEN: YOUR_API_TOKEN_HERE' \
+            --header 'Accept: application/json'
       description: |
             When retrieving a list of clients you can also chain query parameters in order to filter the dataset that is returned. For example, you can send a request to the following URL to retrieve clients that have a balance greater than 1000:\
               
@@ -129,19 +131,7 @@
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  data: 
-                    type: array
-                    items:
                 $ref: '#/components/schemas/Client'
-                    example:
-                      $ref: '#/components/schemas/Client'
-                  meta:
-                    type: object
-                    $ref: '#/components/schemas/Meta'
-                    example:
-                      $ref: '#/components/schemas/Meta'
         401:
           $ref: '#/components/responses/401'
         403:
@@ -410,7 +400,43 @@
       tags:
         - clients
       summary: 'Bulk client actions'
-      description: 'Archive / Restore / Delete in bulk'
+      description: |
+        Bulk actions allow to make changes to multiple clients in a single request the following actions are supported
+        
+        - archive
+        - restore
+        - delete
+        - template _requires template,template_id properties also_
+        - assign_group _requires group_settings_id also_
+        - bulk_update _ requires column,new_value also_
+
+        All of these actions require an array of client ids to perform the requested action on ie.
+
+        "ids":['id1','id2']
+
+        actions such as template, assign_group and bulk_update also require additional properties to be passed in the request
+
+        - template
+
+        The template bulk action allows the creation of a custom template using the provided template_id to be run against the array of clients provided.
+
+        - assign_group
+        
+        Allows the setting of multiple clients to a single group
+
+        - bulk_update
+
+        Allows updating certain columns on the client model in bulk. the current list of supported columns that can be updated archived_at:
+
+        - public_notes
+        - industry_id
+        - size_id
+        - country_id
+        - custom_value1
+        - custom_value2
+        - custom_value3
+        - custom_value4
+
       operationId: bulkClients
       parameters:
         - $ref: '#/components/parameters/X-API-TOKEN'
@@ -426,7 +452,7 @@
               
       responses:
         200:
-          description: 'The Client listresponse'
+          description: 'The Client list Response of the updated clients that were bulk updated'
           headers:
             X-MINIMUM-CLIENT-VERSION:
               $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
@@ -511,7 +537,7 @@
         - clients
       summary: 'Purge client'
       description: |
-            Handles purging a clients.
+            Handles purging a client.
 
             Please note this is a destructive action.
 

openapi/paths/products.yaml

@@ -3,7 +3,7 @@
       tags:
         - products
       summary: "List products"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |
@@ -96,7 +96,7 @@
       tags:
         - products
       summary: "Create Product"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |
@@ -159,7 +159,7 @@
       tags:
         - products
       summary: "Show product"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |
@@ -215,7 +215,7 @@
       tags:
         - products
       summary: "Update product"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |
@@ -287,7 +287,7 @@
       tags:
         - products
       summary: "Delete product"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |
@@ -340,7 +340,7 @@
       tags:
         - products
       summary: "Edit product"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |
@@ -435,7 +435,7 @@
       tags:
         - products
       summary: "Bulk product actions"
-      x-code-samples:
+      x-codeSamples:
       - lang: curl
         label: Curl
         source: |