invoicexpress 0.0.0

data/lib/invoicexpress/client.rb

@@ -0,0 +1,56 @@
+require 'invoicexpress/authentication'
+require 'invoicexpress/connection'
+require 'invoicexpress/request'
+
+require 'invoicexpress/models'
+
+require 'invoicexpress/client/clients'
+require 'invoicexpress/client/invoices'
+require 'invoicexpress/client/cash_invoices'
+require 'invoicexpress/client/items'
+require 'invoicexpress/client/sequences'
+require 'invoicexpress/client/users'
+require 'invoicexpress/client/charts'
+require 'invoicexpress/client/taxes'
+require 'invoicexpress/client/schedules'
+require 'invoicexpress/client/purchase_orders'
+require 'invoicexpress/client/debit_notes'
+require 'invoicexpress/client/credit_notes'
+require 'invoicexpress/client/simplified_invoices'
+
+
+module Invoicexpress
+  # Please refer to each section inside the client for the respective documentation.
+  #
+  #
+  class Client
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+
+    def initialize(options={})
+      options = Invoicexpress.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include Invoicexpress::Authentication
+    include Invoicexpress::Connection
+    include Invoicexpress::Request
+
+    include Invoicexpress::Client::Clients
+    include Invoicexpress::Client::Invoices
+    include Invoicexpress::Client::CashInvoices
+    include Invoicexpress::Client::Items
+    include Invoicexpress::Client::Sequences
+    include Invoicexpress::Client::Users
+    include Invoicexpress::Client::Charts
+    include Invoicexpress::Client::Taxes
+    include Invoicexpress::Client::Schedules
+
+    include Invoicexpress::Client::PurchaseOrders
+    include Invoicexpress::Client::DebitNotes
+    include Invoicexpress::Client::CreditNotes
+    include Invoicexpress::Client::SimplifiedInvoices
+    
+  end
+end

data/lib/invoicexpress/client/cash_invoices.rb

@@ -0,0 +1,110 @@
+require 'invoicexpress/models'
+
+module Invoicexpress
+  class Client
+    module CashInvoices
+      
+      # Returns all your cash invoices
+      #
+      # @option options [Integer] page (1) You can ask a specific page of invoices
+      # @return [Invoicexpress::Models::CashInvoices] A structure with results (pagination) and all the cash invoices
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def cash_invoices(options={})
+        params = { :page => 1, :klass => Invoicexpress::Models::CashInvoices }
+
+        get("cash_invoices.xml", params.merge(options))
+      end
+
+      # Returns a specific cash invoice
+      #
+      # @param invoice_id [String] Requested invoice id
+      # @return [Invoicexpress::Models::CashInvoice] The requested cash invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the invoice doesn't exist
+      def cash_invoice(invoice_id, options={})
+        params = { :klass => Invoicexpress::Models::CashInvoice }
+
+        get("cash_invoices/#{invoice_id}.xml", params.merge(options))
+      end
+
+      # Creates a new cash invoice. Also allows to create a new client and/or new items in the same request.
+      # If the client name does not exist a new one is created.
+      # If items do not exist with the given names, new ones will be created.
+      # If item name  already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applyed to that item.
+      # Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items(IVA 0%)
+      #
+      # @param invoice [Invoicexpress::Models::CashInvoice] The cash invoice to create
+      # @return [Invoicexpress::Models::CashInvoice] The created cash invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def create_cash_invoice(invoice, options={})
+        raise(ArgumentError, "cash invoice has the wrong type") unless invoice.is_a?(Invoicexpress::Models::CashInvoice)
+
+        params = { :klass => Invoicexpress::Models::CashInvoice, :body  => invoice }
+        post("cash_invoices.xml", params.merge(options))
+      end
+
+      # Updates a cash invoice
+      # It also allows you to create a new client and/or items in the same request.
+      # If the client name does not exist a new client is created.
+      # Regarding item taxes, if the tax name is not found, no tax will be applied to that item.
+      # If item does not exist with the given name, a new one will be created.
+      # If item exists it will be updated with the new values
+      # Be careful when updating the document items, any missing items from the original document will be deleted.
+      #
+      # @param invoice [Invoicexpress::Models::CashInvoice] The cash invoice to update
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the invoice doesn't exist
+      def update_cash_invoice(invoice, options={})
+        raise(ArgumentError, "cash invoice has the wrong type") unless invoice.is_a?(Invoicexpress::Models::CashInvoice)
+
+        if !invoice.id
+          raise ArgumentError, "Sequence ID is required"
+        end
+        params = { :klass => Invoicexpress::Models::CashInvoice, :body  => invoice.to_core }
+        put("cash_invoices/#{invoice.id}.xml", params.merge(options))
+      end
+
+      # Changes the state of a cash invoice.
+      # Possible state transitions:
+      # - draft to settle – finalized
+      # - draft to deleted – deleted
+      # - settled to final – unsettled
+      # - final to second copy – second_copy
+      # - final or second copy to canceled – canceled
+      # - final or second copy to settled – settled
+      # Any other transitions will fail.
+      # When canceling a cash invoice you must specify a reason.
+      #
+      # @param invoice_id [String] The cash invoice id to change
+      # @param invoice_state [Invoicexpress::Models::InvoiceState] The new state
+      # @return [Invoicexpress::Models::CashInvoice] The updated cash invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the invoice doesn't exist
+      def update_cash_invoice_state(invoice_id, invoice_state, options={})
+        raise(ArgumentError, "invoice_state has the wrong type") unless invoice_state.is_a?(Invoicexpress::Models::InvoiceState)
+
+        params = { :klass => Invoicexpress::Models::CashInvoice, :body => invoice_state }
+        put("cash_invoices/#{invoice_id}/change-state.xml", params.merge(options))
+      end
+
+      # Sends the invoice by email
+      #
+      # @param invoice_id [String] The cash invoice id to change
+      # @param message [Invoicexpress::Models::Message] The message to send
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the invoice doesn't exist
+      def invoice_email(invoice_id, message, options={})
+        raise(ArgumentError, "message has the wrong type") unless message.is_a?(Invoicexpress::Models::Message)
+
+        params = { :body => message, :klass => Invoicexpress::Models::CashInvoice }
+        put("cash_invoices/#{invoice_id}/email-document.xml", params.merge(options))
+      end
+
+    end
+  end
+end

data/lib/invoicexpress/client/charts.rb

@@ -0,0 +1,57 @@
+module Invoicexpress
+  class Client
+    module Charts
+
+      # Returns the invoicing chart data.
+      #
+      # @return [Array<Invoicexpress::Models::Chart>] An array with all the charting results
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def invoicing_chart(options = {})
+        params = { :klass => Invoicexpress::Models::Chart }
+        get("api/charts/invoicing.xml", params.merge(options))
+      end
+
+      # Returns the treasury chart data.
+      #
+      # @return [Array<Invoicexpress::Models::Chart>] An array with all the charting results
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def treasury_chart(options = {})
+        params = { :klass => Invoicexpress::Models::Chart }
+        get("api/charts/treasury.xml", params.merge(options))
+      end
+
+      # Returns your 5 top clients for which you have invoiced more. 
+      #
+      # @return [Array<Invoicexpress::Models::TopClient>] An array with all the charting results
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def top_clients(options = {})
+        params = { :klass => Invoicexpress::Models::TopClient }
+        get("api/charts/top-clients.xml", params.merge(options))
+      end
+
+      # Returns your 5 top debtors. Values are calculated based on the due amount.
+      #
+      # @return [Array<Invoicexpress::Models::TopClient>] An array with all the charting results
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def top_debtors(options = {})
+        params = { :klass => Invoicexpress::Models::TopDebtor }
+        get("api/charts/top-debtors.xml", params.merge(options))
+      end
+
+      # This method allows you to obtain the quarterly results.
+      # Each quarter has:
+      # The amount invoiced before taxes
+      # Taxes amount
+      # Year to date (YTD) which consists on the difference between the invoiced on the current quarter less the invoiced on the same quarter one year ago
+      #
+      # @param year [Integer] By default year is the current year. It should obey the format YYYY (ex.: 2010)
+      # @return [Array<Invoicexpress::Models::TopClient>] An array with all the charting results
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def quarterly_results(year=Date.today.year , options = {})
+        #params = { :klass => Invoicexpress::Models::QuaterlyResult }
+        params = {  :klass => Invoicexpress::Models::QuarterlyResult, :year => year }
+        get("api/charts/quarterly-results.xml", params.merge(options))
+      end
+    end
+  end
+end

data/lib/invoicexpress/client/clients.rb

@@ -0,0 +1,215 @@
+require 'invoicexpress/models'
+
+module Invoicexpress
+  class Client
+    module Clients
+
+      # Returns all your clients
+      #
+      # @option options [Integer] per_page (30) You can specify how many results you want to fetch
+      # @option options [Integer] page (1) You can ask a specific page of clients
+      #
+      # @return [Array<Invoicexpress::Models::Client>] An array with all your clients
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def clients(options={})
+        params = { :per_page => 30, :page => 1, :klass => Invoicexpress::Models::Client }
+
+        get("clients.xml", params.merge(options))
+      end
+
+      # Creates a new client.
+      #
+      # @param client [Invoicexpress::Models::Client] The client to create
+      # @return [Invoicexpress::Models::Client] The new client from the server
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def create_client(client, options={})
+        if !client || !client.is_a?(Invoicexpress::Models::Client)
+          raise ArgumentError, "Need a Invoicexpress::Models::Client instance"
+        end
+
+        if !client.name
+          raise ArgumentError, "Client's name is required"
+        end
+
+        params = { :body => client, :klass => Invoicexpress::Models::Client }
+        post("clients.xml", params.merge(options))
+      end
+
+      # Updates a client.
+      #
+      # @param client [Invoicexpress::Models::Client] The client to update
+      # @return [Invoicexpress::Models::Client] The new client from the server
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the Client's ID is not found
+      def update_client(client, options={})
+        if !client || !client.is_a?(Invoicexpress::Models::Client)
+          raise ArgumentError, "Need a Invoicexpress::Models::Client instance"
+        end
+
+        if !client.id
+          raise ArgumentError, "Client's ID is required"
+        end
+
+        params = { :body => client, :klass => Invoicexpress::Models::Client }
+        put("clients/#{client.id.to_s}.xml", params.merge(options))
+      end
+
+      # Returns a specific client
+      #
+      # @param client_id [String] The client's ID
+      # @return [Invoicexpress::Models::Client] The remote client from the server
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the client ID is not found
+      def client(client_id, options={})
+        params = { :klass => Invoicexpress::Models::Client }
+
+        get("clients/#{client_id.to_s}.xml", params.merge(options))
+      end
+
+      # This method allows you to obtain the invoices for a specific client.
+      # Allowing filtering aswell.
+      #
+      # @param client_id [String] The client's ID
+      # @param filter [Invoicexpress::Models::Filter] An optional filter
+      # @option options [Integer] per_page (10) You can specify how many results you want to fetch
+      # @option options [Integer] page (1) You can ask a specific page of clients
+      # @return [Invoicexpress::Models::ClientInvoices] The invoices result
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the client ID is not found
+      def client_invoices(client_id, filter=Invoicexpress::Models::Filter.new, options={})
+        raise(ArgumentError, "filter has the wrong type") unless filter.is_a?(Invoicexpress::Models::Filter)
+
+        params = {
+          :klass    => Invoicexpress::Models::ClientInvoices,
+          :per_page => 10,
+          :page     => 1,
+          :body     => filter
+        }
+
+        post("clients/#{client_id.to_s}/invoices.xml", params.merge(options))
+      end
+
+      # Use this method to obtain a client by name. Partial searches are not supported
+      #
+      # @param client_name [String] The client's name
+      # @return [Invoicexpress::Models::Client] The client
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When there are no clients with that name
+      def client_by_name(client_name, options={})
+        params = {
+          :klass       => Invoicexpress::Models::Client,
+          :client_name => client_name
+        }
+
+        get("clients/find-by-name.xml", params.merge(options))
+      end
+
+      # Use this method to obtain a client by your code. Partial searches are not supported
+      #
+      # @param client_code [String] The client's code (your code)
+      # @return [Invoicexpress::Models::Client] The client
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When there are no clients with that name
+      def client_by_code(client_code, options={})
+        params = {
+          :klass       => Invoicexpress::Models::Client,
+          :client_code => client_code
+        }
+
+        get("clients/find-by-code.xml", params.merge(options))
+      end
+
+      # This method allows you to create a new invoice for a specific client.
+      # When creating the invoice:
+      # - If items do not exist with the given names, new ones will be created.
+      # - If item name already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applied to that item.
+      #
+      # @param client_id [String] The ID of the client
+      # @return [Invoicexpress::Models::Invoice] The invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When there are no clients with that name
+      def client_create_invoice(client_id, invoice, options={})
+        raise(ArgumentError, "invoice has the wrong type") unless invoice.is_a?(Invoicexpress::Models::Invoice)
+
+        params = {
+          :klass => Invoicexpress::Models::Invoice,
+          :body  => invoice
+        }
+
+        post("clients/#{client_id}/create/invoice.xml", params.merge(options))
+      end
+      
+      # This method allows you to create a new cash invoice for a specific client.
+      # When creating the invoice:
+      # - If items do not exist with the given names, new ones will be created.
+      # - If item name already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applied to that item.
+      #
+      # @param client_id [String] The ID of the client
+      # @return [Invoicexpress::Models::CashInvoice] The invoice
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When there are no clients with that name
+      def client_create_cash_invoice(client_id, invoice, options={})
+        raise(ArgumentError, "invoice has the wrong type") unless invoice.is_a?(Invoicexpress::Models::CashInvoice)
+
+        params = {
+          :klass => Invoicexpress::Models::CashInvoice,
+          :body  => invoice
+        }
+
+        post("clients/#{client_id}/create/cash-invoice.xml", params.merge(options))
+      end
+      
+      # This method allows you to create a new Credit Note for a specific client.
+      # When creating the invoice:
+      # - If items do not exist with the given names, new ones will be created.
+      # - If item name already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applied to that item.
+      #
+      # @param client_id [String] The ID of the client
+      # @return [Invoicexpress::Models::CreditNote] The credit note
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When there are no clients with that name
+      def client_create_credit_note(client_id, invoice, options={})
+        raise(ArgumentError, "credit note has the wrong type") unless invoice.is_a?(Invoicexpress::Models::CreditNote)
+
+        params = {
+          :klass => Invoicexpress::Models::CreditNote,
+          :body  => invoice
+        }
+
+        post("clients/#{client_id}/create/credit-note.xml", params.merge(options))
+      end
+
+      # This method allows you to create a new Debit Note for a specific client.
+      # When creating the invoice:
+      # - If items do not exist with the given names, new ones will be created.
+      # - If item name already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applied to that item.
+      #
+      # @param client_id [String] The ID of the client
+      # @return [Invoicexpress::Models::DebitNote] The debit note
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When there are no clients with that name
+      def client_create_debit_note(client_id, invoice, options={})
+        raise(ArgumentError, "debit note has the wrong type") unless invoice.is_a?(Invoicexpress::Models::DebitNote)
+
+        params = {
+          :klass => Invoicexpress::Models::DebitNote,
+          :body  => invoice
+        }
+
+        post("clients/#{client_id}/create/debit-note.xml", params.merge(options))
+      end
+
+    end
+  end
+end

data/lib/invoicexpress/client/credit_notes.rb

@@ -0,0 +1,128 @@
+require 'invoicexpress/models'
+
+module Invoicexpress
+  class Client
+    module CreditNotes
+      
+      # Returns all your credit notes
+      #
+      # @option options [Integer] page (1) You can ask a specific page of credit notes
+      #
+      # @return [Invoicexpress::Models::CreditNotes] A struct with results (pagination) and all the credit notes
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      def credit_notes(options={})
+        params = { :page => 1, :klass => Invoicexpress::Models::CreditNote }
+
+        get("credit_notes.xml", params.merge(options))
+      end
+
+      # Returns all the information about a credit note:
+      # - Basic information (date, status, sequence number)
+      # - Client
+      # - Document items
+      # - Document timeline
+      # Document timeline is composed by:
+      # - Date, time and the user who created it
+      # - Type of the event
+      # The complete list of timeline events is:
+      # - create
+      # - edited
+      # - send_email
+      # - canceled
+      # - deleted
+      # - settled
+      # - second_copy
+      # - archived
+      # - unarchived
+      # - comment
+      #
+      # @param credit_note_id [String] Requested credit note id
+      # @return [Invoicexpress::Models::CreditNote] The requested credit note
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::NotFound When the credit_note doesn't exist
+      def credit_note(credit_note_id, options={})
+        params = { :klass => Invoicexpress::Models::CreditNote }
+
+        get("credit_notes/#{credit_note_id}.xml", params.merge(options))
+      end
+
+      # Creates a new credit note. Also allows to create a new client and/or new items in the same request.
+      # If the client name does not exist a new one is created.
+      # If items do not exist with the given names, new ones will be created.
+      # If item name  already exists, the item is updated with the new values.
+      # Regarding item taxes, if the tax name is not found, no tax is applyed to that item.
+      # Portuguese accounts should also send the IVA exemption reason if the invoice contains exempt items(IVA 0%)
+      #
+      # @param credit_note [Invoicexpress::Models::CreditNote] The credit note to create
+      # @return [Invoicexpress::Models::CreditNote] The created credit note
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      def create_credit_note(credit_note, options={})
+        raise(ArgumentError, "credit note has the wrong type") unless credit_note.is_a?(Invoicexpress::Models::CreditNote)
+
+        params = { :klass => Invoicexpress::Models::CreditNote, :body  => credit_note }
+        post("credit_notes.xml", params.merge(options))
+      end
+
+      # Updates a credit note
+      # It also allows you to create a new client and/or items in the same request.
+      # If the client name does not exist a new client is created.
+      # Regarding item taxes, if the tax name is not found, no tax will be applied to that item.
+      # If item does not exist with the given name, a new one will be created.
+      # If item exists it will be updated with the new values
+      # Be careful when updating the document items, any missing items from the original document will be deleted.
+      #
+      # @param credit_note [Invoicexpress::Models::CreditNote] The credit note to update
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the credit note doesn't exist
+      def update_credit_note(credit_note, options={})
+        raise(ArgumentError, "credit note has the wrong type") unless credit_note.is_a?(Invoicexpress::Models::CreditNote)
+        if !credit_note.id
+          raise ArgumentError, "CreditNote ID is required"
+        end
+        params = { :klass => Invoicexpress::Models::CreditNote, :body => credit_note.to_core }
+        put("credit_notes/#{credit_note.id}.xml", params.merge(options))
+      end
+
+      # Changes the state of a credit note.
+      # Possible state transitions:
+      # - draft to final – finalized
+      # - draft to deleted – deleted
+      # - settled to final – unsettled
+      # - final to second copy – second_copy
+      # - final or second copy to canceled – canceled
+      # - final or second copy to settled – settled
+      # Any other transitions will fail.
+      # When canceling a credit note you must specify a reason.
+      #
+      # @param credit_note_id [String] The credit note id to change
+      # @param credit_note_state [Invoicexpress::Models::InvoiceState] The new state
+      # @return [Invoicexpress::Models::CreditNote] The updated credit note
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the credit note doesn't exist
+      def update_credit_note_state(credit_note_id, credit_note_state, options={})
+        raise(ArgumentError, "credit note state has the wrong type") unless credit_note_state.is_a?(Invoicexpress::Models::InvoiceState)
+
+        params = { :klass => Invoicexpress::Models::CreditNote, :body => credit_note_state }
+        put("credit_notes/#{credit_note_id}/change-state.xml", params.merge(options))
+      end
+
+      # Sends the credit note through email
+      #
+      # @param credit_note_id [String] The credit note id to send
+      # @param message [Invoicexpress::Models::Message] The message to send
+      # @raise Invoicexpress::Unauthorized When the client is unauthorized
+      # @raise Invoicexpress::UnprocessableEntity When there are errors on the submission
+      # @raise Invoicexpress::NotFound When the credit note doesn't exist
+      def credit_note_mail(credit_note_id, message, options={})
+        raise(ArgumentError, "message has the wrong type") unless message.is_a?(Invoicexpress::Models::Message)
+
+        params = { :body => message, :klass => Invoicexpress::Models::CreditNote }
+        put("credit_notes/#{credit_note_id}/email-document.xml", params.merge(options))
+      end
+
+    end
+  end
+end