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::Document.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::Document,
  GOBL::Envelope
].freeze

Instance Method Summary collapse

Instance Method Details

#build(struct, envelop: nil, draft: nil) ⇒ GOBL::Envelope, GOBL::Document

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

Examples:

Build a document without enveloping it.

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

Build a document and wrap in a draft envelope.

invoice = GOBL::Document.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::Document.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::Document, GOBL::Envelope) —

    the document or envelope to build.

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

    whether the operation should envelop the document.

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

    whether the envelope should be flagged as a draft.

Returns:

Raises:



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

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

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

  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:



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

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::Document.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:



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

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