Class: MOCO::Invoice

Inherits:
BaseEntity show all
Defined in:
lib/moco/entities/invoice.rb

Overview

Represents a MOCO invoice

Required attributes for create:

customer_id       - Integer, customer company ID
recipient_address - String, full address (use \n for line breaks)
date              - String, "YYYY-MM-DD" invoice date
due_date          - String, "YYYY-MM-DD" payment due date
title             - String, invoice title (e.g., "Invoice")
tax               - Float, tax rate percentage (e.g., 19.0)
currency          - String, 3-letter code (e.g., "EUR")
items             - Array of Hashes, invoice line items (see below)

Item types (for items array):

{ type: "title", title: "Section Title" }
{ type: "description", description: "Some description text" }
{ type: "item", title: "Service", quantity: 10, unit: "h", unit_price: 150.0 }
{ type: "item", title: "Fixed Fee", net_total: 500.0 }  # lump sum
{ type: "subtotal" }
{ type: "separator" }
{ type: "page-break" }

Optional attributes:

project_id        - Integer, associated project ID
status            - String, "created" or "draft" (default: "created")
service_period_from - String, "YYYY-MM-DD"
service_period_to   - String, "YYYY-MM-DD"
change_address    - String, "invoice", "project", or "customer"
salutation        - String, greeting text (HTML allowed)
footer            - String, footer text (HTML allowed)
discount          - Float, discount percentage
cash_discount     - Float, early payment discount percentage
cash_discount_days - Integer, days for early payment discount
tags              - Array of Strings
custom_properties - Hash

Read-only attributes:

id, identifier, status, net_total, gross_total, payments, reminders,
created_at, updated_at

Example:

moco.invoices.create(
  customer_id: 123456,
  recipient_address: "Acme Corp\n123 Main St\n12345 City",
  date: "2024-01-15",
  due_date: "2024-02-15",
  title: "Invoice",
  tax: 19.0,
  currency: "EUR",
  items: [
    { type: "title", title: "Services January 2024" },
    { type: "item", title: "Development", quantity: 40, unit: "h", unit_price: 150.0 },
    { type: "item", title: "Project Management", quantity: 8, unit: "h", unit_price: 120.0 }
  ]
)

Instance Attribute Summary

Attributes inherited from BaseEntity

#attributes, #client

Instance Method Summary collapse

Methods inherited from BaseEntity

#==, #association, #destroy, #eql?, #has_many, #hash, #id, #initialize, #inspect, #reload, #save, #to_h, #to_json, #update

Constructor Details

This class inherits a constructor from MOCO::BaseEntity

Instance Method Details

#attachments ⇒ Object

Fetches attachments for this invoice as a NestedCollectionProxy. Supports .all, .find(id), .create(attachment: { filename:, base64: }), and .destroy.



95
96
97
 
# File 'lib/moco/entities/invoice.rb', line 95

def attachments
  MOCO::NestedCollectionProxy.new(client, self, :attachments, "InvoiceAttachment")
end

#company ⇒ Object

Associations



110
111
112
 
# File 'lib/moco/entities/invoice.rb', line 110

def company
  association(:customer, "Company")
end

#expenses ⇒ Object 



78
79
80
 
# File 'lib/moco/entities/invoice.rb', line 78

def expenses
  client.get("invoices/#{id}/expenses")
end

#payments ⇒ Object

Fetches payments for this invoice



100
101
102
 
# File 'lib/moco/entities/invoice.rb', line 100

def payments
  MOCO::NestedCollectionProxy.new(client, self, :payments, "InvoicePayment")
end

#pdf ⇒ Object 



66
67
68
 
# File 'lib/moco/entities/invoice.rb', line 66

def pdf
  client.get("invoices/#{id}.pdf")
end

#project ⇒ Object 



114
115
116
 
# File 'lib/moco/entities/invoice.rb', line 114

def project
  association(:project)
end

#reminders ⇒ Object

Fetches reminders for this invoice



105
106
107
 
# File 'lib/moco/entities/invoice.rb', line 105

def reminders
  MOCO::NestedCollectionProxy.new(client, self, :reminders, "InvoiceReminder")
end

#send_email(recipient:, subject:, text:, **options) ⇒ Object 



82
83
84
85
86
87
88
89
90
91
 
# File 'lib/moco/entities/invoice.rb', line 82

def send_email(recipient:, subject:, text:, **options)
  payload = {
    recipient:,
    subject:,
    text:
  }.merge(options)

  client.post("invoices/#{id}/send_email", payload)
  self
end

#timesheet ⇒ Object 



70
71
72
 
# File 'lib/moco/entities/invoice.rb', line 70

def timesheet
  client.get("invoices/#{id}/timesheet")
end

#timesheet_pdf ⇒ Object 



74
75
76
 
# File 'lib/moco/entities/invoice.rb', line 74

def timesheet_pdf
  client.get("invoices/#{id}/timesheet.pdf")
end

#to_s ⇒ Object 



118
119
120
 
# File 'lib/moco/entities/invoice.rb', line 118

def to_s
  "#{identifier} - #{title} (#{date})"
end

#update_status(status) ⇒ Object

Instance methods for invoice-specific operations



61
62
63
64
 
# File 'lib/moco/entities/invoice.rb', line 61

def update_status(status)
  client.put("invoices/#{id}/update_status", { status: })
  self
end