Class: Dolibarr::Invoices

Inherits:
Resource show all
Defined in:
lib/dolibarr/invoices.rb

Overview

Customer invoices — the heart of the monthly working set: list (with period, thirdparty and paid/unpaid filters), fetch by ref or id, create, validate.

Reads go through the raw connection with type: nil (the transport's typed get pins the placeholder Obj model and would drop the payload). Empty lists are normalised to []; a missing single invoice raises Client::NotFound.

Instance Method Summary collapse

Methods inherited from Resource

#initialize

Constructor Details

This class inherits a constructor from Dolibarr::Resource

Instance Method Details

#all(**filters) ⇒ Array<Invoice>

All matching invoices as an Array (auto-paginated).

Returns:



51
52
53
 
# File 'lib/dolibarr/invoices.rb', line 51

def all(**filters)
  each(**filters).to_a
end

#create(**attributes) ⇒ Integer

Create an invoice. Attributes are sent as the request body verbatim (Dolibarr's createInvoicesModel is a passthrough).

Parameters:

  • attributes (Hash) —

    invoice fields (socid, type, lines, …)

Returns:

  • (Integer) —

    the new invoice id returned by Dolibarr



79
80
81
 
# File 'lib/dolibarr/invoices.rb', line 79

def create(**attributes)
  call { connection.call(:POST, '/invoices', type: nil, auth: ['api_key'], body: attributes).data }
end

#each(limit: 100, **filters) {|invoice| ... } ⇒ Enumerator, void

Every matching invoice, paginating transparently. Returns an Enumerator when no block is given.

Parameters:

  • limit (Integer) (defaults to: 100) —

    page size used while walking

  • filters (Hash) —

    any #list filter

Yield Parameters:

Returns:

  • (Enumerator, void) 


44
45
46
47
 
# File 'lib/dolibarr/invoices.rb', line 44

def each(limit: 100, **filters, &block)
  enum = paginate(limit: limit) { |page, lim| list(page: page, limit: lim, **filters) }
  block ? enum.each(&block) : enum
end

#find(ref: nil, id: nil) ⇒ Invoice

Fetch a single invoice by ref or id (exactly one required).

Parameters:

  • ref (String, nil) (defaults to: nil) —

    invoice reference (e.g. "FA2601-0007")

  • id (Integer, String, nil) (defaults to: nil) —

    invoice rowid

Returns:

Raises:



62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/dolibarr/invoices.rb', line 62

def find(ref: nil, id: nil)
  raise ArgumentError, 'find requires exactly one of ref: or id:' unless ref.nil? ^ id.nil?

  raw =
    if ref
      get_one("/invoices/ref/#{encode(ref)}", "invoice #{ref}")
    else
      get_one("/invoices/#{encode(id)}", "invoice #{id}")
    end
  Invoice.from(raw)
end

#list(thirdparty_id: nil, status: nil, paid: nil, from: nil, to: nil, limit: 100, page: 0, sortfield: 't.rowid', sortorder: 'ASC') ⇒ Array<Invoice>

One page of invoices as Dolibarr::Invoice value objects.

Parameters:

  • thirdparty_id (Integer, String, nil) (defaults to: nil) —

    restrict to a customer

  • status (String, nil) (defaults to: nil) —

    Dolibarr status filter ("draft"/"unpaid"/"paid"/"cancelled")

  • paid (Boolean, nil) (defaults to: nil) —

    convenience: maps to the "paid"/"unpaid" status filter (ignored when status is given explicitly)

  • from (Date, String, nil) (defaults to: nil) —

    lower bound on the invoice date (inclusive)

  • to (Date, String, nil) (defaults to: nil) —

    upper bound on the invoice date (inclusive)

  • limit (Integer) (defaults to: 100) —

    page size

  • page (Integer) (defaults to: 0) —

    0-based page index

  • sortfield (String) (defaults to: 't.rowid') —

    Restler sort field (default "t.rowid")

  • sortorder (String) (defaults to: 'ASC') —

    "ASC" / "DESC"

Returns:



24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/dolibarr/invoices.rb', line 24

def list(thirdparty_id: nil, status: nil, paid: nil, from: nil, to: nil,
         limit: 100, page: 0, sortfield: 't.rowid', sortorder: 'ASC')
  raws = get_list(
    '/invoices',
    'sortfield' => sortfield, 'sortorder' => sortorder,
    'limit' => limit, 'page' => page,
    'thirdparty_ids' => thirdparty_id,
    'status' => status || paid_status(paid),
    'sqlfilters' => period_filter(from, to)
  )
  raws.map { |raw| Invoice.from(raw) }
end

#validate(id:, notrigger: nil) ⇒ Invoice

Validate a draft invoice (assigns its definitive ref).

Parameters:

  • id (Integer, String) —

    invoice rowid

  • notrigger (Integer, nil) (defaults to: nil) —

    1 to skip business triggers

Returns:

  • (Invoice) —

    the refreshed invoice



88
89
90
91
92
93
94
95
96
 
# File 'lib/dolibarr/invoices.rb', line 88

def validate(id:, notrigger: nil)
  raw = call do
    connection.call(
      :POST, "/invoices/#{encode(id)}/validate",
      type: nil, auth: ['api_key'], body: { 'notrigger' => notrigger }.compact
    ).data
  end
  Invoice.from(raw)
end