Class: Wfirma::Contractors

Inherits:
Object
  • Object
show all
Defined in:
lib/wfirma/contractors.rb

Overview

Contractors (CRM) resource.

An invoice can carry the buyer inline, but that data never reaches the contractor catalogue - each invoice only gets its own contractor_detail snapshot (verified against the live API). Resolving the customer through this resource and passing the resulting id as contractor_id: is what puts them in the wFirma contractor list, with one record reused across their invoices.

contractor = client.contractors.upsert(name: "ACME Sp. z o.o.", nip: "…", …)
raise contractor.errors.join(", ") unless contractor.success?

client.invoices.create(contractor_id: contractor.record_id, items: [...])

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Contractors

Returns a new instance of Contractors.



16
17
18
 
# File 'lib/wfirma/contractors.rb', line 16

def initialize(client)
  @client = client
end

Instance Method Details

#create(attrs) ⇒ Object 



40
41
42
 
# File 'lib/wfirma/contractors.rb', line 40

def create(attrs)
  call("add", stringify_keys(attrs))
end

#find_by(field, value) ⇒ Object

contractors/find narrowed by a single equality condition, which is all a tax-id lookup needs. Returns the matching contractor hashes (possibly empty); a failed query returns [] as well, so check the tax id you pass.



23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/wfirma/contractors.rb', line 23

def find_by(field, value)
  payload = {
    "contractors" => {
      "parameters" => {
        "conditions" => {
          "condition" => { "field" => field.to_s, "operator" => "eq", "value" => value.to_s }
        }
      }
    }
  }
  records(@client.call("contractors", "find", payload))
end

#find_by_nip(nip) ⇒ Object 



36
37
38
 
# File 'lib/wfirma/contractors.rb', line 36

def find_by_nip(nip)
  find_by("nip", nip)
end

#update(contractor_id, attrs) ⇒ Object 



44
45
46
 
# File 'lib/wfirma/contractors.rb', line 44

def update(contractor_id, attrs)
  call("edit", stringify_keys(attrs), contractor_id)
end

#upsert(attrs, match_on = nil) ⇒ Object

Reuses the catalogue record carrying this tax id, overwriting any of the given fields whose value differs, and creates one when there is none. Fields not passed are left alone, so edits made in the wFirma panel survive. Returns a Result either way - check success? before using record_id, since wFirma validates on write (postal code format, VIES).

By default it recognises a returning customer by tax id, falling back to email for consumers who have none - see #recognise. Pass match_on to match on exactly one field instead. wFirma does not treat any of these as unique, so the first match wins; with nothing to match on, every call creates a new contractor.

match_on is positional so that the customer can be passed as a bare hash

  • upsert(name: "…", nip: "…") would otherwise be read as keywords.


62
63
64
65
66
67
68
69
70
71
 
# File 'lib/wfirma/contractors.rb', line 62

def upsert(attrs, match_on = nil)
  attrs = stringify_keys(attrs)
  existing = match_on ? match(attrs, match_on.to_s) : recognise(attrs)
  return create(attrs) unless existing

  changed = attrs.reject { |field, value| existing[field].to_s == value.to_s }
  return unchanged_result(existing) if changed.empty?

  update(existing["id"], changed)
end