Module: GOBL::Operations

Included in:
GOBL
Defined in:
lib/gobl/operations.rb,
lib/gobl/operations/service_error.rb,
lib/gobl/operations/validation_result.rb

Overview

Provides the API to execute operations over GOBL structures. It implements them by sending HTTP requests to the bulk endpoint of the service that the GOBL CLI makes available via the ‘gobl serve` command. The server’s host and port must be configured using ‘GOBL.config.service_host` and `GOBL.config.service_port`.

Examples:

GOBL.config.service_host = 'localhost'
GOBL.config.service_port = 8080

doc = GOBL::Schema::Object.new(
  '$schema' => 'https://gobl.org/draft-0/bill/invoice',
  'code' => 'SAMPLE-001',
  'currency' => 'EUR',
  'issue_date' => '2022-02-01',
  'supplier' => { 'tax_id' => { 'country' => 'ES', 'code' => '54387763P' }, 'name' => 'Provide One S.L.' },
  'customer' => { 'tax_id' => { 'country' => 'ES', 'code' => '54387763P' }, 'name' => 'Sample Consumer' },
  'lines' => [ { 'quantity' => '20', 'item' => { 'name' => 'Development services', 'price' => '90.00' } } ]
)

built_doc = GOBL.build(doc)

invoice = built_doc.extract
invoice.totals.total.to_s #=> "1800.00"

Defined Under Namespace

Classes: ServiceError, ValidationResult

Constant Summary collapse

VALIDATABLE_TYPES =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

SIGNABLE_TYPES = BUILDABLE_TYPES = [
  GOBL::Envelope,
  GOBL::Schema::Object
].freeze

Instance Method Summary collapse

Instance Method Details

#build(struct, envelop: nil) ⇒ GOBL::Envelope, GOBL::Schema::Object

Calculates and validates an envelope or document, wrapping it in an envelope if requested.

Examples:

Build a document without enveloping it.

invoice = GOBL::Schema::Object.from_json!(File.read('invoice.json'))
GOBL.build(invoice) #=> A new, calculated `GOBL::Schema::Object`

Build a document and wrap in a draft envelope.

invoice = GOBL::Schema::Object.from_json!(File.read('invoice.json'))
GOBL.build(invoice, envelop: true) #=> A calculated, draft `GOBL::Envelope`

Build a document and wrap in a non-draft envelope.

invoice = GOBL::Schema::Object.from_json!(File.read('invoice.json'))
GOBL.build(invoice, envelop: true, draft: false) #=> A calculated, non-draft `GOBL::Envelope`

Build an envelope.

envelope = GOBL::Envelop.from_json!(File.read('envelope.json'))
GOBL.build(envelope) #=> A new, calculated GOBL::Envelope

Build an envelope forcing it to be a non-draft.

envelope = GOBL::Envelop.from_json!(File.read('draft_envelope.json'))
GOBL.build(envelope, draft: false) #=> A new, non-draft GOBL::Envelope

Parameters:

  • struct (GOBL::Schema::Object, GOBL::Envelope) —

    the document or envelope to build.

  • envelop (Boolean) (defaults to: nil) —

    whether the operation should envelop the document.

  • draft (Boolean) —

    whether the envelope should be flagged as a draft.

Returns:

Raises:



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/gobl/operations.rb', line 64

def build(struct, envelop: nil)
  check_struct_type struct, BUILDABLE_TYPES

  response = request_action(:build, struct: struct,
                                    envelop: envelop)

  raise ServiceError, response['error'] if response['error'].present?

  GOBL::Struct.from_data response['payload']
end

#sign(struct) ⇒ GOBL::Envelope

Signs a document or envelope, calculating, enveloping and validating it first if

needed. The signing key will be the one configured in the server.

Examples:

Sign an envelope.

envelope = GOBL::Envelop.from_json!(File.read('draft_envelope.json'))
GOBL.sign(envelope) #=> A new signed GOBL::Envelope

Parameters:

Returns:

Raises:



120
121
122
123
124
125
126
127
128
 
# File 'lib/gobl/operations.rb', line 120

def sign(struct)
  check_struct_type struct, SIGNABLE_TYPES

  response = request_action(:sign, struct: struct)

  raise ServiceError, response['error'] if response['error'].present?

  GOBL::Struct.from_data response['payload']
end

#validate(struct) ⇒ GOBL::ValidationResult

Checks whether or not a document or envelope is valid according to the GOBL schema

and rules.

Examples:

Validate an invalid document.

document =  GOBL::Schema::Object.from_json!(File.read('invalid_invoice.json'))
result = GOBL.validate(document)
result.valid? #=> false
result.errors #=> ['code: cannot be blank', 'totals: cannot be blank']

Validate a valid envelope.

envelope = GOBL::Envelop.from_json!(File.read('valid_envelope.json'))
result = GOBL.validate(envelope)
result.valid? #=> true
result.errors #=> []

Parameters:

Returns:



94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/gobl/operations.rb', line 94

def validate(struct)
  check_struct_type struct, VALIDATABLE_TYPES

  response = request_action(:validate, struct: struct)

  if response['error'].present?
    ValidationResult.from_service_error(response['error'])
  elsif response['payload']['ok']
    ValidationResult.valid
  else
    raise 'Unexpected response from the service'
  end
end