vatsense 0.1.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +14 -0
  3. data/README.md +57 -0
  4. data/lib/vatsense/client.rb +5 -0
  5. data/lib/vatsense/models/batch.rb +218 -0
  6. data/lib/vatsense/models/batch_delete_response.rb +41 -0
  7. data/lib/vatsense/models/batch_list_response.rb +51 -0
  8. data/lib/vatsense/models/batch_response.rb +23 -0
  9. data/lib/vatsense/models/batch_result.rb +133 -0
  10. data/lib/vatsense/models/batch_results_response.rb +42 -0
  11. data/lib/vatsense/models/create_invoice.rb +9 -1
  12. data/lib/vatsense/models/invoice.rb +11 -3
  13. data/lib/vatsense/models/invoice_create_params.rb +13 -1
  14. data/lib/vatsense/models/rate_list_params.rb +10 -1
  15. data/lib/vatsense/models/usage_retrieve_response.rb +4 -4
  16. data/lib/vatsense/models/validate_check_params.rb +48 -1
  17. data/lib/vatsense/models/validate_check_response.rb +70 -1
  18. data/lib/vatsense/models.rb +4 -0
  19. data/lib/vatsense/resources/batches.rb +249 -0
  20. data/lib/vatsense/resources/invoice.rb +8 -2
  21. data/lib/vatsense/resources/rates.rb +1 -1
  22. data/lib/vatsense/resources/validate.rb +7 -2
  23. data/lib/vatsense/version.rb +1 -1
  24. data/lib/vatsense/webhook.rb +104 -0
  25. data/lib/vatsense.rb +8 -0
  26. data/rbi/vatsense/models/create_invoice.rbi +9 -0
  27. data/rbi/vatsense/models/invoice.rbi +12 -2
  28. data/rbi/vatsense/models/invoice_create_params.rbi +17 -5
  29. data/rbi/vatsense/models/rate_list_params.rbi +13 -0
  30. data/rbi/vatsense/models/usage_retrieve_response.rbi +4 -4
  31. data/rbi/vatsense/models/validate_check_params.rbi +55 -0
  32. data/rbi/vatsense/models/validate_check_response.rbi +140 -0
  33. data/rbi/vatsense/resources/invoice.rbi +4 -0
  34. data/rbi/vatsense/resources/rates.rbi +2 -0
  35. data/rbi/vatsense/resources/validate.rbi +16 -1
  36. data/sig/vatsense/client.rbs +2 -0
  37. data/sig/vatsense/models/batch.rbs +57 -0
  38. data/sig/vatsense/models/batch_delete_response.rbs +17 -0
  39. data/sig/vatsense/models/batch_list_response.rbs +19 -0
  40. data/sig/vatsense/models/batch_response.rbs +10 -0
  41. data/sig/vatsense/models/batch_result.rbs +38 -0
  42. data/sig/vatsense/models/batch_results_response.rbs +17 -0
  43. data/sig/vatsense/models/create_invoice.rbs +6 -1
  44. data/sig/vatsense/models/invoice.rbs +8 -1
  45. data/sig/vatsense/models/invoice_create_params.rbs +13 -3
  46. data/sig/vatsense/models/rate_list_params.rbs +7 -1
  47. data/sig/vatsense/models/validate_check_params.rbs +37 -1
  48. data/sig/vatsense/models/validate_check_response.rbs +63 -0
  49. data/sig/vatsense/resources/batches.rbs +72 -0
  50. data/sig/vatsense/resources/invoice.rbs +2 -0
  51. data/sig/vatsense/resources/rates.rbs +1 -0
  52. data/sig/vatsense/resources/validate.rbs +6 -0
  53. data/sig/vatsense/webhook.rbs +28 -0
  54. metadata +18 -2
@@ -49,7 +49,9 @@ module Vatsense
49
49
  optional :invoice_number, String
50
50
 
51
51
  # @!attribute invoice_url
52
- # Unique URL to view the invoice. Append "/pdf" to download a PDF copy.
52
+ # Unique, unguessable URL to view the invoice. Append "/pdf" to download a PDF
53
+ # copy. Invoices created before the November 2026 relaunch keep their earlier
54
+ # style of link.
53
55
  #
54
56
  # @return [String, nil]
55
57
  optional :invoice_url, String
@@ -84,6 +86,12 @@ module Vatsense
84
86
  # @return [Symbol, Vatsense::Models::InvoiceAPI::Object, nil]
85
87
  optional :object, enum: -> { Vatsense::InvoiceAPI::Object }
86
88
 
89
+ # @!attribute original_invoice_id
90
+ # On a credit note that names the sale invoice it credits: that invoice's ID.
91
+ #
92
+ # @return [String, nil]
93
+ optional :original_invoice_id, String
94
+
87
95
  # @!attribute tax_point
88
96
  #
89
97
  # @return [String, nil]
@@ -114,7 +122,7 @@ module Vatsense
114
122
  # @return [Boolean, nil]
115
123
  optional :zero_rated, Vatsense::Internal::Type::Boolean
116
124
 
117
- # @!method initialize(id: nil, business: nil, conversion: nil, created: nil, currency_code: nil, customer: nil, date: nil, has_vat: nil, invoice_number: nil, invoice_url: nil, is_copy: nil, is_reverse_charge: nil, items: nil, notes: nil, num_items: nil, object: nil, tax_point: nil, tax_type: nil, totals: nil, type: nil, updated: nil, zero_rated: nil)
125
+ # @!method initialize(id: nil, business: nil, conversion: nil, created: nil, currency_code: nil, customer: nil, date: nil, has_vat: nil, invoice_number: nil, invoice_url: nil, is_copy: nil, is_reverse_charge: nil, items: nil, notes: nil, num_items: nil, object: nil, tax_point: nil, tax_type: nil, totals: nil, type: nil, updated: nil, zero_rated: nil, original_invoice_id: nil)
118
126
  # @param id [String]
119
127
  #
120
128
  # @param business [Vatsense::Models::InvoiceAPI::Business]
@@ -133,7 +141,7 @@ module Vatsense
133
141
  #
134
142
  # @param invoice_number [String]
135
143
  #
136
- # @param invoice_url [String] Unique URL to view the invoice. Append "/pdf" to download a PDF copy.
144
+ # @param invoice_url [String] Unique, unguessable URL to view the invoice. Append "/pdf" to download a PDF
137
145
  #
138
146
  # @param is_copy [Boolean]
139
147
  #
@@ -7,7 +7,19 @@ module Vatsense
7
7
  extend Vatsense::Internal::Type::RequestParameters::Converter
8
8
  include Vatsense::Internal::Type::RequestParameters
9
9
 
10
- # @!method initialize(request_options: {})
10
+ # @!attribute idempotency_key
11
+ # Sent as the `Idempotency-Key` header to retry a create safely: a repeat with the
12
+ # same key and the same body, byte for byte, creates nothing and returns the
13
+ # invoice the first request made. The same key with a different body gets `422`
14
+ # "Idempotency Key Reused". 1 to 255 characters, unique to this invoice (such as
15
+ # your order number or a UUID).
16
+ #
17
+ # @return [String, nil]
18
+ optional :idempotency_key, String
19
+
20
+ # @!method initialize(idempotency_key: nil, request_options: {})
21
+ # @param idempotency_key [String] Sent as the `Idempotency-Key` header to retry a create safely.
22
+ #
11
23
  # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}]
12
24
  end
13
25
  end
@@ -33,7 +33,16 @@ module Vatsense
33
33
  # @return [Time, nil]
34
34
  optional :period, Time
35
35
 
36
- # @!method initialize(country_code: nil, eu: nil, ip_address: nil, period: nil, request_options: {})
36
+ # @!attribute provinces
37
+ # Whether to list province and territory rates (rate objects that carry a
38
+ # `province` property) in each country's `other` list. Pass false to leave them
39
+ # out, so only country-wide rates are listed; true, or omitting the parameter,
40
+ # lists them as before. The `standard` rate is always the country-wide one.
41
+ #
42
+ # @return [Boolean, nil]
43
+ optional :provinces, Vatsense::Internal::Type::Boolean
44
+
45
+ # @!method initialize(country_code: nil, eu: nil, ip_address: nil, period: nil, provinces: nil, request_options: {})
37
46
  # Some parameter documentations has been truncated, see
38
47
  # {Vatsense::Models::RateListParams} for more details.
39
48
  #
@@ -43,13 +43,13 @@ module Vatsense
43
43
  optional :remaining, Integer
44
44
 
45
45
  # @!attribute total
46
- # Total requests allowed on your plan.
46
+ # Requests available in the current billing period.
47
47
  #
48
48
  # @return [Integer, nil]
49
49
  optional :total, Integer
50
50
 
51
51
  # @!attribute used
52
- # Requests used in the last 30 days.
52
+ # Requests used so far in the current billing period.
53
53
  #
54
54
  # @return [Integer, nil]
55
55
  optional :used, Integer
@@ -57,9 +57,9 @@ module Vatsense
57
57
  # @!method initialize(remaining: nil, total: nil, used: nil)
58
58
  # @param remaining [Integer] Requests remaining before the limit is reached.
59
59
  #
60
- # @param total [Integer] Total requests allowed on your plan.
60
+ # @param total [Integer] Requests available in the current billing period.
61
61
  #
62
- # @param used [Integer] Requests used in the last 30 days.
62
+ # @param used [Integer] Requests used so far in the current billing period.
63
63
  end
64
64
  end
65
65
  end
@@ -14,6 +14,53 @@ module Vatsense
14
14
  # @return [String, nil]
15
15
  optional :eori_number, String
16
16
 
17
+ # @!attribute match_address
18
+ # The whole address you hold, as one line, matched against the registered
19
+ # address.
20
+ #
21
+ # @return [String, nil]
22
+ optional :match_address, String
23
+
24
+ # @!attribute match_city
25
+ # The town or city you hold, looked for in the registered address.
26
+ #
27
+ # @return [String, nil]
28
+ optional :match_city, String
29
+
30
+ # @!attribute match_company_name
31
+ # The company name you hold, matched against the registered name. Legal forms
32
+ # such as Ltd or GmbH, accents, punctuation and word order are ignored. Sending
33
+ # any `match_` parameter adds `match` to the response; matching costs nothing
34
+ # extra.
35
+ #
36
+ # @return [String, nil]
37
+ optional :match_company_name, String
38
+
39
+ # @!attribute match_postcode
40
+ # The postcode you hold, looked for in the registered address. Spaces are
41
+ # ignored.
42
+ #
43
+ # @return [String, nil]
44
+ optional :match_postcode, String
45
+
46
+ # @!attribute consultation_optional
47
+ # Send `true` with `requester_vat_number` if you would rather have an answer than
48
+ # wait for a consultation number. When VIES cannot answer for the number's
49
+ # country and that country has a national register fallback, the answer comes
50
+ # from the register with no `consultation_number`, instead of the `412`. If VIES
51
+ # cannot check your own `requester_vat_number`, the number is checked without it,
52
+ # again with no `consultation_number`. Leave it out if you need the consultation
53
+ # number as proof of the check.
54
+ #
55
+ # @return [Boolean, nil]
56
+ optional :consultation_optional, Vatsense::Internal::Type::Boolean
57
+
58
+ # @!attribute match_street
59
+ # The street line you hold, looked for in the registered address.
60
+ #
61
+ # @return [String, nil]
62
+ optional :match_street, String
63
+
17
64
  # @!attribute requester_vat_number
18
65
  # Your own VAT number. If supplied, the response will include a unique
19
66
  # consultation number issued by the relevant authority (VIES or HMRC). Must
@@ -32,7 +79,7 @@ module Vatsense
32
79
  # @return [String, nil]
33
80
  optional :vat_number, String
34
81
 
35
- # @!method initialize(eori_number: nil, requester_vat_number: nil, vat_number: nil, request_options: {})
82
+ # @!method initialize(eori_number: nil, requester_vat_number: nil, vat_number: nil, match_address: nil, match_city: nil, match_company_name: nil, match_postcode: nil, match_street: nil, consultation_optional: nil, request_options: {})
36
83
  # Some parameter documentations has been truncated, see
37
84
  # {Vatsense::Models::ValidateCheckParams} for more details.
38
85
  #
@@ -31,6 +31,13 @@ module Vatsense
31
31
  # @return [Vatsense::Models::ValidateCheckResponse::Data::Company::ValidationCompany, Vatsense::Models::ValidateCheckResponse::Data::Company::EoriValidationCompany, nil]
32
32
  optional :company, union: -> { Vatsense::Models::ValidateCheckResponse::Data::Company }
33
33
 
34
+ # @!attribute confirmation_number
35
+ # VAT Sense's own reference for this check (beta, only for accounts in the
36
+ # beta). It is not an official number.
37
+ #
38
+ # @return [String, nil]
39
+ optional :confirmation_number, String, nil?: true
40
+
34
41
  # @!attribute consultation_number
35
42
  # Official consultation number (only returned when requester_vat_number is
36
43
  # provided).
@@ -38,13 +45,19 @@ module Vatsense
38
45
  # @return [String, nil]
39
46
  optional :consultation_number, String, nil?: true
40
47
 
48
+ # @!attribute match
49
+ # Only when a `match_` parameter was sent.
50
+ #
51
+ # @return [Vatsense::Models::ValidateCheckResponse::Data::Match, nil]
52
+ optional :match, -> { Vatsense::Models::ValidateCheckResponse::Data::Match }
53
+
41
54
  # @!attribute valid
42
55
  # Whether the VAT/EORI number is valid.
43
56
  #
44
57
  # @return [Boolean, nil]
45
58
  optional :valid, Vatsense::Internal::Type::Boolean
46
59
 
47
- # @!method initialize(company: nil, consultation_number: nil, valid: nil)
60
+ # @!method initialize(company: nil, consultation_number: nil, match: nil, valid: nil)
48
61
  # Some parameter documentations has been truncated, see
49
62
  # {Vatsense::Models::ValidateCheckResponse::Data} for more details.
50
63
  #
@@ -54,6 +67,62 @@ module Vatsense
54
67
  #
55
68
  # @param valid [Boolean] Whether the VAT/EORI number is valid.
56
69
 
70
+ # @see Vatsense::Models::ValidateCheckResponse::Data#match
71
+ class Match < Vatsense::Internal::Type::BaseModel
72
+ # @!attribute fields
73
+ # One entry for each detail sent (company_name, address, street, postcode,
74
+ # city).
75
+ #
76
+ # @return [Hash{Symbol=>Vatsense::Models::ValidateCheckResponse::Data::Match::Field}, nil]
77
+ optional :fields,
78
+ -> { Vatsense::Internal::Type::HashOf[Vatsense::Models::ValidateCheckResponse::Data::Match::Field] }
79
+
80
+ # @!attribute result
81
+ # likely (a score of 80 or more, and the name, if sent, is not a no_match),
82
+ # possible (50 to 79), unlikely (under 50), or not_applicable when nothing could
83
+ # be compared.
84
+ #
85
+ # @return [String, nil]
86
+ optional :result, String
87
+
88
+ # @!attribute score
89
+ # The average of the details sent, with the name counting twice. nil when
90
+ # not_applicable.
91
+ #
92
+ # @return [Integer, nil]
93
+ optional :score, Integer, nil?: true
94
+
95
+ # @!method initialize(fields: nil, result: nil, score: nil)
96
+ # @param fields [Hash{Symbol=>Vatsense::Models::ValidateCheckResponse::Data::Match::Field}]
97
+ # @param result [String]
98
+ # @param score [Integer, nil]
99
+
100
+ class Field < Vatsense::Internal::Type::BaseModel
101
+ # @!attribute result
102
+ # One of "match", "partial", "no_match" or "not_applicable".
103
+ #
104
+ # @return [String, nil]
105
+ optional :result, String
106
+
107
+ # @!attribute score
108
+ #
109
+ # @return [Integer, nil]
110
+ optional :score, Integer, nil?: true
111
+
112
+ # @!attribute vies
113
+ # VIES's own answer for that detail on a live EU check ("valid", "invalid" or
114
+ # "not_processed"); nil when VIES said nothing.
115
+ #
116
+ # @return [String, nil]
117
+ optional :vies, String, nil?: true
118
+
119
+ # @!method initialize(result: nil, score: nil, vies: nil)
120
+ # @param result [String]
121
+ # @param score [Integer, nil]
122
+ # @param vies [String, nil]
123
+ end
124
+ end
125
+
57
126
  # @see Vatsense::Models::ValidateCheckResponse::Data#company
58
127
  module Company
59
128
  extend Vatsense::Internal::Type::Union
@@ -93,6 +93,10 @@ module Vatsense
93
93
 
94
94
  SandboxGenerateKeyParams = Vatsense::Models::SandboxGenerateKeyParams
95
95
 
96
+ Batch = Vatsense::Models::Batch
97
+
98
+ BatchResult = Vatsense::Models::BatchResult
99
+
96
100
  TaxRate = Vatsense::Models::TaxRate
97
101
 
98
102
  UsageRetrieveParams = Vatsense::Models::UsageRetrieveParams
@@ -0,0 +1,249 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Vatsense
4
+ module Resources
5
+ # Bulk validation: check many VAT numbers in one batch.
6
+ #
7
+ # Batch calls are free and work even when your requests are used up; each
8
+ # number a batch checks counts as one request. With a test key a batch is
9
+ # answered from the test numbers, is free and holds at most 1,000 numbers.
10
+ class Batches
11
+ BODY_KEYS = [:numbers, :rows, :reference, :start, :shortfall, :auto_continue, :consultation].freeze
12
+ private_constant :BODY_KEYS
13
+
14
+ # Create a batch of VAT numbers and, by default, start checking it. Pass
15
+ # exactly one of `numbers:` or `rows:`.
16
+ #
17
+ # @overload create(numbers: nil, rows: nil, reference: nil, start: nil, shortfall: nil, auto_continue: nil, consultation: nil, idempotency_key: nil, request_options: {})
18
+ #
19
+ # @param numbers [Array<String>] The VAT numbers to check, each with its 2-character country code.
20
+ #
21
+ # @param rows [Array<Hash{Symbol=>String}>] Rows with `vat_number:` and, for company matching, any of
22
+ # `country_code:`, `company_name:`, `address:`, `street:`, `address_line_2:`, `postcode:` and `city:`.
23
+ #
24
+ # @param reference [String] Your own label for the batch, at most 255 characters.
25
+ #
26
+ # @param start [Boolean] Defaults to true. False keeps a draft for 24 hours, to start with `start`.
27
+ #
28
+ # @param shortfall [Symbol, String] When your requests do not cover the batch: `:wait` (the default)
29
+ # starts nothing and returns the `quote`, `:pause` checks what is covered and pauses the rest,
30
+ # `:overage` runs into overage (it must already be on in the dashboard).
31
+ #
32
+ # @param auto_continue [Boolean] Defaults to true. With `:pause`, continue when your requests renew.
33
+ #
34
+ # @param consultation [Boolean] Defaults to false. Send the requester VAT number from your account
35
+ # settings with each check.
36
+ #
37
+ # @param idempotency_key [String] Sent as the `Idempotency-Key` header, at most 64 characters. The
38
+ # same key again returns the batch already made.
39
+ #
40
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
41
+ #
42
+ # @return [Vatsense::Models::BatchResponse]
43
+ def create(params = {})
44
+ params = params.dup
45
+ options = params.delete(:request_options)
46
+ key = params.delete(:idempotency_key)
47
+ @client.request(
48
+ method: :post,
49
+ path: "batches",
50
+ headers: key.nil? ? {} : {"idempotency-key" => key},
51
+ body: body_of(params),
52
+ model: Vatsense::Models::BatchResponse,
53
+ options: options
54
+ )
55
+ end
56
+
57
+ # The account's batches, newest first.
58
+ #
59
+ # @overload list(page: nil, limit: nil, status: nil, request_options: {})
60
+ #
61
+ # @param page [Integer] The page, from 1.
62
+ #
63
+ # @param limit [Integer] Batches a page, 1 to 100 (default 25).
64
+ #
65
+ # @param status [Symbol, String] `:draft` lists the drafts not yet started instead.
66
+ #
67
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
68
+ #
69
+ # @return [Vatsense::Models::BatchListResponse]
70
+ def list(params = {})
71
+ params = params.dup
72
+ options = params.delete(:request_options)
73
+ @client.request(
74
+ method: :get,
75
+ path: "batches",
76
+ query: query_of(params, [:page, :limit, :status]),
77
+ model: Vatsense::Models::BatchListResponse,
78
+ options: options
79
+ )
80
+ end
81
+
82
+ # A batch and its progress. Poll until `status` is `complete`, or take the
83
+ # `batch.completed` webhook.
84
+ #
85
+ # @overload retrieve(batch_id, request_options: {})
86
+ #
87
+ # @param batch_id [String]
88
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
89
+ #
90
+ # @return [Vatsense::Models::BatchResponse]
91
+ def retrieve(batch_id, params = {})
92
+ action(:get, batch_id, nil, nil, params)
93
+ end
94
+
95
+ # Delete a draft. A batch that has started cannot be deleted (409).
96
+ #
97
+ # @overload delete(batch_id, request_options: {})
98
+ #
99
+ # @param batch_id [String]
100
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
101
+ #
102
+ # @return [Vatsense::Models::BatchDeleteResponse]
103
+ def delete(batch_id, params = {})
104
+ @client.request(
105
+ method: :delete,
106
+ path: ["batches/%1$s", id_of(batch_id)],
107
+ model: Vatsense::Models::BatchDeleteResponse,
108
+ options: params[:request_options]
109
+ )
110
+ end
111
+
112
+ # Start a draft, with the same options as `create`.
113
+ #
114
+ # @overload start(batch_id, shortfall: nil, auto_continue: nil, consultation: nil, request_options: {})
115
+ #
116
+ # @param batch_id [String]
117
+ # @param shortfall [Symbol, String]
118
+ # @param auto_continue [Boolean]
119
+ # @param consultation [Boolean]
120
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
121
+ #
122
+ # @return [Vatsense::Models::BatchResponse]
123
+ def start(batch_id, params = {})
124
+ action(:post, batch_id, "start", [:shortfall, :auto_continue, :consultation], params)
125
+ end
126
+
127
+ # Pause a running batch.
128
+ #
129
+ # @overload pause(batch_id, request_options: {})
130
+ #
131
+ # @param batch_id [String]
132
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
133
+ #
134
+ # @return [Vatsense::Models::BatchResponse]
135
+ def pause(batch_id, params = {})
136
+ action(:post, batch_id, "pause", [], params)
137
+ end
138
+
139
+ # Continue a paused batch. Pass `shortfall: :overage` to run into overage.
140
+ #
141
+ # @overload continue(batch_id, shortfall: nil, request_options: {})
142
+ #
143
+ # @param batch_id [String]
144
+ # @param shortfall [Symbol, String]
145
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
146
+ #
147
+ # @return [Vatsense::Models::BatchResponse]
148
+ def continue(batch_id, params = {})
149
+ action(:post, batch_id, "continue", [:shortfall], params)
150
+ end
151
+
152
+ # Mark a paused batch complete, leaving the rest unchecked.
153
+ #
154
+ # @overload complete(batch_id, request_options: {})
155
+ #
156
+ # @param batch_id [String]
157
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
158
+ #
159
+ # @return [Vatsense::Models::BatchResponse]
160
+ def complete(batch_id, params = {})
161
+ action(:post, batch_id, "complete", [], params)
162
+ end
163
+
164
+ # The batch's checked rows as JSON, in row order. Follow `next_after` while
165
+ # `has_more` is true.
166
+ #
167
+ # @overload results(batch_id, after: nil, limit: nil, request_options: {})
168
+ #
169
+ # @param batch_id [String]
170
+ # @param after [Integer] Return rows after this row number (default 0).
171
+ # @param limit [Integer] Rows a page, 1 to 1,000 (default 100).
172
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
173
+ #
174
+ # @return [Vatsense::Models::BatchResultsResponse]
175
+ def results(batch_id, params = {})
176
+ params = params.dup
177
+ options = params.delete(:request_options)
178
+ @client.request(
179
+ method: :get,
180
+ path: ["batches/%1$s/results", id_of(batch_id)],
181
+ query: query_of(params, [:after, :limit]),
182
+ model: Vatsense::Models::BatchResultsResponse,
183
+ options: options
184
+ )
185
+ end
186
+
187
+ # The batch's CSV report, the same file the dashboard gives.
188
+ #
189
+ # @overload results_csv(batch_id, request_options: {})
190
+ #
191
+ # @param batch_id [String]
192
+ # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
193
+ #
194
+ # @return [String]
195
+ def results_csv(batch_id, params = {})
196
+ body = @client.request(
197
+ method: :get,
198
+ path: ["batches/%1$s/results.csv", id_of(batch_id)],
199
+ headers: {"accept" => "text/csv"},
200
+ model: StringIO,
201
+ options: params[:request_options]
202
+ )
203
+ body.respond_to?(:read) ? body.read : body.to_s
204
+ end
205
+
206
+ # @api private
207
+ #
208
+ # @param client [Vatsense::Client]
209
+ def initialize(client:)
210
+ @client = client
211
+ end
212
+
213
+ private
214
+
215
+ def action(method, batch_id, suffix, keys, params)
216
+ params = params.dup
217
+ options = params.delete(:request_options)
218
+ path = suffix.nil? ? "batches/%1$s" : "batches/%1$s/#{suffix}"
219
+ @client.request(
220
+ method: method,
221
+ path: [path, id_of(batch_id)],
222
+ body: keys.nil? ? nil : body_of(params.slice(*keys)),
223
+ model: Vatsense::Models::BatchResponse,
224
+ options: options
225
+ )
226
+ end
227
+
228
+ def id_of(batch_id)
229
+ raise ArgumentError, "batch_id must not be empty" if batch_id.nil? || batch_id.to_s.empty?
230
+
231
+ batch_id
232
+ end
233
+
234
+ def body_of(params)
235
+ unknown = params.keys - BODY_KEYS
236
+ raise ArgumentError, "unknown batch parameters: #{unknown.join(', ')}" unless unknown.empty?
237
+
238
+ params.compact.transform_values { _1.is_a?(Symbol) ? _1.to_s : _1 }
239
+ end
240
+
241
+ def query_of(params, keys)
242
+ unknown = params.keys - keys
243
+ raise ArgumentError, "unknown batch parameters: #{unknown.join(', ')}" unless unknown.empty?
244
+
245
+ params.compact.transform_values(&:to_s)
246
+ end
247
+ end
248
+ end
249
+ end
@@ -16,7 +16,11 @@ module Vatsense
16
16
  #
17
17
  # Not available with sandbox API keys.
18
18
  #
19
- # @overload create(business:, currency_code:, date:, items:, tax_point:, conversion: nil, customer: nil, has_vat: nil, invoice_number: nil, is_copy: nil, is_reverse_charge: nil, notes: nil, pad_invoice_number: nil, serial: nil, tax_type: nil, type: nil, zero_rated: nil, request_options: {})
19
+ # Pass `idempotency_key:` to retry a create safely: a repeat with the same key and
20
+ # the same body, byte for byte, creates nothing and returns the invoice the first
21
+ # request made.
22
+ #
23
+ # @overload create(business:, currency_code:, date:, items:, tax_point:, conversion: nil, customer: nil, has_vat: nil, invoice_number: nil, is_copy: nil, is_reverse_charge: nil, notes: nil, pad_invoice_number: nil, serial: nil, tax_type: nil, type: nil, zero_rated: nil, original_invoice_id: nil, idempotency_key: nil, request_options: {})
20
24
  #
21
25
  # @param business [Vatsense::Models::InvoiceBusinessInput]
22
26
  #
@@ -59,10 +63,12 @@ module Vatsense
59
63
  # @see Vatsense::Models::InvoiceCreateParams
60
64
  def create(params)
61
65
  parsed, options = Vatsense::InvoiceCreateParams.dump_request(params)
66
+ header_params = {idempotency_key: "idempotency-key"}
62
67
  @client.request(
63
68
  method: :post,
64
69
  path: "invoice",
65
- body: parsed,
70
+ headers: parsed.slice(*header_params.keys).transform_keys(header_params),
71
+ body: parsed.except(*header_params.keys),
66
72
  model: Vatsense::InvoiceResponse,
67
73
  options: options
68
74
  )
@@ -13,7 +13,7 @@ module Vatsense
13
13
  #
14
14
  # You can optionally filter by country code, IP address, or EU membership.
15
15
  #
16
- # @overload list(country_code: nil, eu: nil, ip_address: nil, period: nil, request_options: {})
16
+ # @overload list(country_code: nil, eu: nil, ip_address: nil, period: nil, provinces: nil, request_options: {})
17
17
  #
18
18
  # @param country_code [String] A 2-character ISO 3166-1 alpha-2 country code (e.g. "GB", "FR").
19
19
  #
@@ -16,11 +16,16 @@ module Vatsense
16
16
  # **EORI validation** checks against UK and EU records only.
17
17
  #
18
18
  # If the external validation service is temporarily unavailable, the API returns a
19
- # `412` error and the request does not count against your usage quota.
19
+ # `412` error and the request does not count against your usage quota. It also
20
+ # returns the `412`, uncounted, when a check takes longer than 55 seconds for a
21
+ # number checked with VIES or the EU EORI service, or 25 seconds for any other.
22
+ # With a webhook endpoint taking `validation.completed`, a number that got the
23
+ # `412` keeps being checked and the answer is sent by webhook
24
+ # (https://vatsense.com/documentation#webhooks).
20
25
  #
21
26
  # Provide either `vat_number` or `eori_number`, but not both.
22
27
  #
23
- # @overload check(eori_number: nil, requester_vat_number: nil, vat_number: nil, request_options: {})
28
+ # @overload check(eori_number: nil, requester_vat_number: nil, vat_number: nil, match_address: nil, match_city: nil, match_company_name: nil, match_postcode: nil, match_street: nil, consultation_optional: nil, request_options: {})
24
29
  #
25
30
  # @param eori_number [String] The EORI number to validate. Must include the leading 2-character
26
31
  #
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Vatsense
4
- VERSION = "0.1.2"
4
+ VERSION = "0.3.0"
5
5
  end