smartbill-sdk 1.0.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 (85) hide show
  1. checksums.yaml +7 -0
  2. data/AGENTS.md +211 -0
  3. data/CHANGELOG.md +18 -0
  4. data/LICENSE.txt +21 -0
  5. data/README.md +265 -0
  6. data/Rakefile +22 -0
  7. data/Steepfile +6 -0
  8. data/docs/openapi.json +9741 -0
  9. data/examples/create_estimate_sync.rb +53 -0
  10. data/examples/create_invoice_eur_product_in_ron.rb +100 -0
  11. data/examples/create_invoice_sync.rb +57 -0
  12. data/examples/create_payment_sync.rb +36 -0
  13. data/examples/fiscal_receipt_sync.rb +50 -0
  14. data/examples/invoice_lifecycle_sync.rb +43 -0
  15. data/examples/list_series_sync.rb +27 -0
  16. data/examples/send_email_sync.rb +40 -0
  17. data/examples/taxes_and_stocks_sync.rb +48 -0
  18. data/lib/smartbill/sdk/api_error.rb +27 -0
  19. data/lib/smartbill/sdk/auth_error.rb +8 -0
  20. data/lib/smartbill/sdk/client.rb +68 -0
  21. data/lib/smartbill/sdk/contracts/base.rb +33 -0
  22. data/lib/smartbill/sdk/contracts/email_contract.rb +29 -0
  23. data/lib/smartbill/sdk/contracts/estimate_contract.rb +18 -0
  24. data/lib/smartbill/sdk/contracts/invoice_contract.rb +29 -0
  25. data/lib/smartbill/sdk/contracts/invoice_payment_contract.rb +18 -0
  26. data/lib/smartbill/sdk/contracts/invoice_ref_contract.rb +19 -0
  27. data/lib/smartbill/sdk/contracts/payment_contract.rb +37 -0
  28. data/lib/smartbill/sdk/contracts/storno_contract.rb +17 -0
  29. data/lib/smartbill/sdk/contracts.rb +19 -0
  30. data/lib/smartbill/sdk/error.rb +8 -0
  31. data/lib/smartbill/sdk/models/base_response.rb +16 -0
  32. data/lib/smartbill/sdk/models/client.rb +26 -0
  33. data/lib/smartbill/sdk/models/discount_type.rb +13 -0
  34. data/lib/smartbill/sdk/models/document_type.rb +13 -0
  35. data/lib/smartbill/sdk/models/email_document.rb +23 -0
  36. data/lib/smartbill/sdk/models/email_response.rb +12 -0
  37. data/lib/smartbill/sdk/models/email_status.rb +13 -0
  38. data/lib/smartbill/sdk/models/estimate.rb +32 -0
  39. data/lib/smartbill/sdk/models/fiscal_receipt_response.rb +16 -0
  40. data/lib/smartbill/sdk/models/invoice.rb +44 -0
  41. data/lib/smartbill/sdk/models/invoice_create_response.rb +10 -0
  42. data/lib/smartbill/sdk/models/invoice_payment.rb +15 -0
  43. data/lib/smartbill/sdk/models/invoice_ref.rb +24 -0
  44. data/lib/smartbill/sdk/models/payment.rb +49 -0
  45. data/lib/smartbill/sdk/models/payment_status_response.rb +19 -0
  46. data/lib/smartbill/sdk/models/payment_type.rb +22 -0
  47. data/lib/smartbill/sdk/models/product.rb +38 -0
  48. data/lib/smartbill/sdk/models/proforma_invoices_response.rb +13 -0
  49. data/lib/smartbill/sdk/models/series.rb +14 -0
  50. data/lib/smartbill/sdk/models/series_list_response.rb +14 -0
  51. data/lib/smartbill/sdk/models/stock_list.rb +13 -0
  52. data/lib/smartbill/sdk/models/stock_product.rb +15 -0
  53. data/lib/smartbill/sdk/models/stock_warehouse.rb +13 -0
  54. data/lib/smartbill/sdk/models/stocks_response.rb +14 -0
  55. data/lib/smartbill/sdk/models/storno_request.rb +17 -0
  56. data/lib/smartbill/sdk/models/storno_response.rb +14 -0
  57. data/lib/smartbill/sdk/models/struct.rb +102 -0
  58. data/lib/smartbill/sdk/models/tax.rb +14 -0
  59. data/lib/smartbill/sdk/models/taxes_response.rb +14 -0
  60. data/lib/smartbill/sdk/models.rb +17 -0
  61. data/lib/smartbill/sdk/net_http_adapter.rb +62 -0
  62. data/lib/smartbill/sdk/rate_limit_error.rb +9 -0
  63. data/lib/smartbill/sdk/response.rb +12 -0
  64. data/lib/smartbill/sdk/services/base_service.rb +39 -0
  65. data/lib/smartbill/sdk/services/configuration_service.rb +29 -0
  66. data/lib/smartbill/sdk/services/email_service.rb +18 -0
  67. data/lib/smartbill/sdk/services/estimates_service.rb +60 -0
  68. data/lib/smartbill/sdk/services/invoices_service.rb +69 -0
  69. data/lib/smartbill/sdk/services/payments_service.rb +50 -0
  70. data/lib/smartbill/sdk/services/stocks_service.rb +21 -0
  71. data/lib/smartbill/sdk/services.rb +30 -0
  72. data/lib/smartbill/sdk/transport/rate_limiter.rb +49 -0
  73. data/lib/smartbill/sdk/transport/request.rb +17 -0
  74. data/lib/smartbill/sdk/transport.rb +162 -0
  75. data/lib/smartbill/sdk/transport_error.rb +8 -0
  76. data/lib/smartbill/sdk/types.rb +22 -0
  77. data/lib/smartbill/sdk/validation_error.rb +8 -0
  78. data/lib/smartbill/sdk/version.rb +7 -0
  79. data/lib/smartbill/sdk.rb +31 -0
  80. data/sig/smartbill/sdk.rbs +661 -0
  81. data/skills/README.md +35 -0
  82. data/skills/smartbill-email/SKILL.md +120 -0
  83. data/skills/smartbill-invoices/SKILL.md +178 -0
  84. data/skills/smartbill-payments/SKILL.md +194 -0
  85. metadata +214 -0
@@ -0,0 +1,120 @@
1
+ ---
2
+ name: smartbill-email
3
+ description: Send SmartBill documents (invoices/proformas) by email via smartbill-sdk (Ruby). POST /document/send, base64 subject/body, sync.
4
+ ---
5
+
6
+ # SmartBill Email (document/send)
7
+
8
+ Email an existing SmartBill invoice or proforma to recipients using the
9
+ `smartbill-sdk` Ruby gem. Synchronous usage. Ruby has no async client — for
10
+ concurrency, run independent requests on separate threads.
11
+
12
+ ## Setup
13
+
14
+ ```bash
15
+ gem install smartbill-sdk
16
+ ```
17
+
18
+ ```ruby
19
+ require "smartbill/sdk"
20
+
21
+ client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "...")
22
+ ```
23
+
24
+ Auth is HTTP Basic `username:token` (token from SmartBill Cloud →
25
+ **Contul Meu → Integrari → API**). JSON only. Rate limit: 30 calls / 10s.
26
+
27
+ ## The email service
28
+
29
+ `client.email` (`EmailService`) exposes:
30
+
31
+ | Method | Endpoint | Purpose |
32
+ |---------|-----------------------|-------------------------------|
33
+ | `send` | `POST /document/send` | email a document to recipients |
34
+
35
+ ## ⚠️ Base64 requirement
36
+
37
+ The SmartBill API requires `subject` and `body_text` to be **Base64-encoded**
38
+ by the caller. The SDK does **not** do this for you — encode before passing:
39
+
40
+ ```ruby
41
+ require "base64"
42
+
43
+ def b64(text)
44
+ Base64.strict_encode64(text)
45
+ end
46
+ ```
47
+
48
+ ## Send an invoice
49
+
50
+ ```ruby
51
+ require "smartbill/sdk"
52
+ require "base64"
53
+
54
+ def b64(text)
55
+ Base64.strict_encode64(text)
56
+ end
57
+
58
+ Smartbill::Sdk::Client.new(username: "you@example.com", token: "...").with_client do |client|
59
+ email = Smartbill::Sdk::Models::EmailDocument.new(
60
+ company_vat_code: "RO12345678",
61
+ series_name: "FCT",
62
+ number: "0040",
63
+ type: Smartbill::Sdk::Models::DocumentType::INVOICE, # or DocumentType::PROFORMA
64
+ to: "client@example.ro",
65
+ cc: "contabilitate@example.ro",
66
+ # bcc: "secret@example.ro",
67
+ subject: b64("Factura FCT0040"),
68
+ body_text: b64("Va trimitem factura FCT0040. Multumim!")
69
+ )
70
+ resp = client.email.send(email)
71
+ puts resp.status.code, resp.status.message # "0" == success
72
+ end
73
+ ```
74
+
75
+ `type` selects which document to send:
76
+ `Smartbill::Sdk::Models::DocumentType::INVOICE` (`"factura"`) or
77
+ `Smartbill::Sdk::Models::DocumentType::PROFORMA` (`"proforma"`). The document
78
+ is identified by `series_name` + `number` + `type` + `company_vat_code`.
79
+
80
+ ## Send a proforma
81
+
82
+ ```ruby
83
+ require "smartbill/sdk"
84
+ require "base64"
85
+
86
+ def b64(text)
87
+ Base64.strict_encode64(text)
88
+ end
89
+
90
+ Smartbill::Sdk::Client.new(username: "you@example.com", token: "...").with_client do |client|
91
+ email = Smartbill::Sdk::Models::EmailDocument.new(
92
+ company_vat_code: "RO12345678",
93
+ series_name: "PFC",
94
+ number: "0001",
95
+ type: Smartbill::Sdk::Models::DocumentType::PROFORMA,
96
+ to: "client@example.ro",
97
+ subject: b64("Proforma PFC0001"),
98
+ body_text: b64("Va trimitem proforma PFC0001.")
99
+ )
100
+ resp = client.email.send(email)
101
+ puts resp.status.code, resp.status.message
102
+ end
103
+ ```
104
+
105
+ ## Response
106
+
107
+ `send` returns an `EmailResponse` whose `status` is an `EmailStatus` with
108
+ `code` (`"0"` on success) and `message`.
109
+
110
+ ## Errors
111
+
112
+ `Smartbill::Sdk::APIError` carries `.error_text` (the API's `errorText`),
113
+ `.message_field`, and `.status_code`. See `lib/smartbill/sdk/exceptions.rb`.
114
+
115
+ ## Reference
116
+
117
+ - Source: `lib/smartbill/sdk/services.rb` (`EmailService`)
118
+ - Models: `lib/smartbill/sdk/models/email.rb`, `responses.rb`
119
+ (`EmailResponse`, `EmailStatus`), `enums.rb` (`DocumentType`)
120
+ - Worked example: `examples/send_email_sync.rb`
@@ -0,0 +1,178 @@
1
+ ---
2
+ name: smartbill-invoices
3
+ description: Issue and manage SmartBill invoices (and proformas/estimates) via smartbill-sdk (Ruby). Create, cancel, restore, storno, PDF, payment status.
4
+ ---
5
+
6
+ # SmartBill Invoices & Estimates
7
+
8
+ Create, manage, and download SmartBill invoices and proformas (`estimates`)
9
+ with the `smartbill-sdk` Ruby gem. Covers synchronous usage. Ruby has no
10
+ async client — for concurrency, run independent requests on separate
11
+ threads (see `examples/taxes_and_stocks_sync.rb`).
12
+
13
+ ## Setup
14
+
15
+ ```bash
16
+ gem install smartbill-sdk
17
+ ```
18
+
19
+ Auth is HTTP Basic with your SmartBill login e-mail and API token
20
+ (SmartBill Cloud → **Contul Meu → Integrari → API**).
21
+
22
+ ```ruby
23
+ require "smartbill/sdk"
24
+
25
+ client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "...")
26
+ ```
27
+
28
+ All date fields are `YYYY-MM-DD` strings. The SDK sends JSON only (no XML).
29
+ SmartBill rate-limits to 30 calls / 10s → 403 for 10 min if exceeded; opt
30
+ into a client-side preemptive limiter with `enforce_rate_limit: true`.
31
+
32
+ ## Drafts (ciornă)
33
+
34
+ Both `Invoice` and `Estimate` accept `is_draft` (API alias `isDraft`). When
35
+ `is_draft: true` the document is **saved but not finalized**: it gets **no
36
+ series number** and is not officially issued. It shows up in SmartBill Cloud
37
+ under **Rapoarte → Facturi / Proforme** so a human can review and finalize it
38
+ there. When `is_draft: false` (the default), the document is finalized and a
39
+ number is assigned — `resp.series` / `resp.number` are populated.
40
+
41
+ ```ruby
42
+ invoice = Smartbill::Sdk::Models::Invoice.new(
43
+ # ...,
44
+ series_name: "FCT",
45
+ is_draft: true
46
+ )
47
+ resp = client.invoices.create(invoice)
48
+ # resp.number / resp.series are empty until finalized in SmartBill Cloud
49
+ ```
50
+
51
+ ## Services available
52
+
53
+ | Attribute | Service | Covers |
54
+ |--------------------|--------------------------|----------------------------------------------|
55
+ | `client.invoices` | `InvoicesService` | `POST /invoice`, delete, reverse (storno), cancel, restore, payment status, PDF |
56
+ | `client.estimates` | `EstimatesService` | `POST /estimate`, delete, cancel, restore, PDF, invoices-status |
57
+ | `client.payments` | `PaymentsService` | see the `smartbill-payments` skill |
58
+ | `client.email` | `EmailService` | see the `smartbill-email` skill |
59
+ | `client.taxes` | `ConfigurationService` | `GET /tax` (taxes), `GET /series` (series) |
60
+ | `client.series` | `ConfigurationService` | alias of `client.taxes` — same instance |
61
+ | `client.stocks` | `StocksService` | `GET /stocks` |
62
+
63
+ Note: `client.taxes` and `client.series` are the **same**
64
+ `ConfigurationService` instance — call `client.taxes.taxes(cif)` /
65
+ `client.taxes.series(cif)`.
66
+
67
+ ## Create an invoice
68
+
69
+ ```ruby
70
+ require "smartbill/sdk"
71
+
72
+ Smartbill::Sdk::Client.new(username: "you@example.com", token: "...").with_client do |client|
73
+ invoice = Smartbill::Sdk::Models::Invoice.new(
74
+ company_vat_code: "RO12345678",
75
+ client: Smartbill::Sdk::Models::Client.new(
76
+ name: "Intelligent IT", vat_code: "RO12345678",
77
+ city: "Sibiu", country: "Romania"
78
+ ),
79
+ series_name: "FCT",
80
+ is_draft: false,
81
+ products: [
82
+ Smartbill::Sdk::Models::Product.new(
83
+ name: "Produs 1", measuring_unit_name: "buc", currency: "RON",
84
+ quantity: 2, price: 10, is_tax_included: true,
85
+ tax_name: "Redusa", tax_percentage: 9
86
+ )
87
+ ]
88
+ )
89
+ resp = client.invoices.create(invoice)
90
+ puts "#{resp.series} #{resp.number}" # series + assigned number
91
+ end
92
+ ```
93
+
94
+ Proformas use `Estimate` + `client.estimates.create(estimate)` — same shape,
95
+ and also support `is_draft: true` to save a proforma ciornă.
96
+
97
+ ## Lifecycle: storno / cancel / restore / PDF
98
+
99
+ ```ruby
100
+ cif = "RO12345678"
101
+ series = "FCT"
102
+ number = "0040"
103
+
104
+ # Storno (reversal) — returns document URLs.
105
+ storno = Smartbill::Sdk::Models::StornoRequest.new(
106
+ company_vat_code: cif, series_name: series, number: number
107
+ )
108
+ st = client.invoices.reverse(storno)
109
+ puts st.document_url
110
+
111
+ client.invoices.cancel(cif, series, number) # PUT /invoice/cancel
112
+ client.invoices.restore(cif, series, number) # PUT /invoice/restore
113
+
114
+ pdf_bytes = client.invoices.pdf(cif, series, number) # raw binary String
115
+ File.binwrite("factura.pdf", pdf_bytes)
116
+ ```
117
+
118
+ `pdf` returns a raw binary `String` (binary endpoint — not JSON).
119
+
120
+ ## Payment status of an invoice
121
+
122
+ ```ruby
123
+ status = client.invoices.payment_status(cif, series, number)
124
+ puts status.paid
125
+ puts status.invoice_total_amount
126
+ puts status.paid_amount
127
+ puts status.unpaid_amount
128
+ ```
129
+
130
+ ## Proforma → invoice conversion status
131
+
132
+ ```ruby
133
+ status = client.estimates.invoices_status(cif, "PFC", "0001")
134
+ puts status.are_invoices_created
135
+ status.invoices.each { |inv| puts "#{inv.series_name} #{inv.number}" }
136
+ ```
137
+
138
+ ## Concurrency (threads)
139
+
140
+ Ruby has no asyncio client. For independent calls, run them on threads —
141
+ `Net::HTTP` opens a fresh connection per request, so this is safe:
142
+
143
+ ```ruby
144
+ client = Smartbill::Sdk::Client.new(username: "...", token: "...")
145
+
146
+ t1 = Thread.new { client.invoices.payment_status("RO12345678", "FCT", "0040") }
147
+ t2 = Thread.new { client.taxes.taxes("RO12345678") }
148
+ status = t1.value
149
+ taxes = t2.value
150
+ ```
151
+
152
+ Always call `client.close` (or use `with_client { ... }`) when done.
153
+
154
+ ## Error handling
155
+
156
+ Errors are `Smartbill::Sdk::Error` subclasses from `Smartbill::Sdk::Exceptions`:
157
+
158
+ - `AuthError` — HTTP 401 (bad username/token/company CIF).
159
+ - `RateLimitError` — HTTP 403 (rate-limited, blocked 10 min).
160
+ - `APIError` — has `.error_text`, `.message_field`, `.status_code`
161
+ (the API's `errorText` is surfaced in `.error_text`).
162
+ - `TransportError` — network-level failure.
163
+ - `ValidationError` — a model is missing required fields.
164
+
165
+ ```ruby
166
+ rescue Smartbill::Sdk::AuthError => e
167
+ # ...
168
+ rescue Smartbill::Sdk::APIError => e
169
+ puts e.error_text, e.status_code
170
+ end
171
+ ```
172
+
173
+ ## Reference
174
+
175
+ - Source: `lib/smartbill/sdk/services.rb` (`InvoicesService`, `EstimatesService`)
176
+ - Models: `lib/smartbill/sdk/models/invoices.rb`, `estimates.rb`, `common.rb`
177
+ - Worked examples: `examples/create_invoice_sync.rb`,
178
+ `examples/create_estimate_sync.rb`, `examples/invoice_lifecycle_sync.rb`
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: smartbill-payments
3
+ description: Record payments and issue fiscal receipts (bon fiscal) via SmartBill using smartbill-sdk (Ruby). POST /payment, payment types, mixed cash/card, fiscal-printer text, delete.
4
+ ---
5
+
6
+ # SmartBill Payments & Fiscal Receipts
7
+
8
+ Record payments against invoices and issue fiscal receipts (`bon fiscal`)
9
+ with the `smartbill-sdk` Ruby gem. Synchronous usage. Ruby has no async
10
+ client — for concurrency, run independent requests on separate threads.
11
+
12
+ ## Setup
13
+
14
+ ```bash
15
+ gem install smartbill-sdk
16
+ ```
17
+
18
+ ```ruby
19
+ require "smartbill/sdk"
20
+
21
+ client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "...")
22
+ ```
23
+
24
+ Auth is HTTP Basic `username:token` (token from SmartBill Cloud →
25
+ **Contul Meu → Integrari → API**). JSON only. Rate limit: 30 calls / 10s.
26
+
27
+ ## Draft chitante (ciornă)
28
+
29
+ `Payment` accepts `is_draft` (API alias `isDraft`). This only applies to
30
+ `type: "Chitanta"`. When `is_draft: true` the chitanta is **saved but not
31
+ finalized** — it gets **no number** and appears in SmartBill Cloud under
32
+ **Rapoarte → Incasări** for a human to review and finalize. When
33
+ `is_draft: false` (the default), the chitanta is finalized and
34
+ `resp.number` / `resp.series` are populated.
35
+
36
+ ```ruby
37
+ payment = Smartbill::Sdk::Models::Payment.new(
38
+ company_vat_code: "RO12345678",
39
+ series_name: "CHT",
40
+ value: 260.0,
41
+ type: "Chitanta",
42
+ is_draft: true, # ← ciornă: saved, not finalized, no number
43
+ is_cash: true
44
+ )
45
+ resp = client.payments.create(payment)
46
+ # resp.number / resp.series are empty until finalized in SmartBill Cloud
47
+ ```
48
+
49
+ `is_draft` is **not** meaningful for `type: "Bon"` (fiscal receipts) — those
50
+ are always issued immediately via the fiscal printer.
51
+
52
+ ## The payments service
53
+
54
+ `client.payments` (`PaymentsService`) exposes:
55
+
56
+ | Method | Endpoint | Purpose |
57
+ |-------------------------|---------------------------|--------------------------------------|
58
+ | `create` | `POST /payment` | record a payment / issue bon fiscal |
59
+ | `delete_other` | `DELETE /payment/v2` | delete a non-chitanta payment |
60
+ | `delete_chitanta` | `DELETE /payment/chitanta`| delete a chitanta |
61
+ | `fiscal_receipt_text` | `GET /payment/text` | fetch base64 fiscal-printer text by id |
62
+
63
+ ## Payment types
64
+
65
+ `Payment#type=` is one of (string values, case-sensitive as documented):
66
+
67
+ `Chitanta`, `Bon`, `Card`, `Card online`, `CEC`, `Bilet ordin`,
68
+ `Ordin plata`, `Mandat postal`, `Extras de cont`, `Ramburs`,
69
+ `Alta incasare`.
70
+
71
+ (Also available as constants under `Smartbill::Sdk::Models::PaymentType`,
72
+ e.g. `Smartbill::Sdk::Models::PaymentType::CHITANTA` == `"Chitanta"`.)
73
+
74
+ ## Record a simple payment (chitanta / card / etc.)
75
+
76
+ ```ruby
77
+ payment = Smartbill::Sdk::Models::Payment.new(
78
+ company_vat_code: "RO12345678",
79
+ series_name: "FCT", # invoice series the payment applies to
80
+ number: "0040", # invoice number
81
+ value: 260.0,
82
+ type: "Chitanta",
83
+ is_cash: true
84
+ )
85
+ resp = client.payments.create(payment)
86
+ ```
87
+
88
+ ## Issue a fiscal receipt (bon fiscal) with mixed cash + card
89
+
90
+ A `Bon` is also created via `POST /payment`, but you add `products` and the
91
+ `received_*` breakdown. With `return_fiscal_printer_text: true` the response
92
+ includes the receipt `id` and the base64 fiscal-printer text in `message`.
93
+
94
+ ```ruby
95
+ payment = Smartbill::Sdk::Models::Payment.new(
96
+ company_vat_code: "RO12345678",
97
+ value: 260.0,
98
+ type: "Bon",
99
+ is_cash: false,
100
+ use_stock: false,
101
+ return_fiscal_printer_text: true,
102
+ products: [
103
+ Smartbill::Sdk::Models::Product.new(
104
+ name: "Produs 1", measuring_unit_name: "buc", currency: "RON",
105
+ quantity: 1, price: 200, is_tax_included: true,
106
+ tax_name: "Normala", tax_percentage: 19
107
+ ),
108
+ Smartbill::Sdk::Models::Product.new(
109
+ name: "Produs 2", measuring_unit_name: "buc", currency: "RON",
110
+ quantity: 1, price: 60, is_tax_included: true,
111
+ tax_name: "Normala", tax_percentage: 19
112
+ )
113
+ ],
114
+ received_cash: 200.0,
115
+ received_card: 60.0
116
+ )
117
+ resp = client.payments.create(payment)
118
+ puts resp.id # generated receipt id
119
+ puts resp.message # base64 fiscal-printer text (if requested)
120
+ ```
121
+
122
+ `create` returns a `FiscalReceiptResponse` (a `BaseResponse` + optional `id`),
123
+ so `resp.number`, `resp.series`, `resp.error_text` are also available.
124
+
125
+ ## Linking a payment to one or more invoices
126
+
127
+ Set `invoices_list:` to an array of `InvoiceRef` pairs to apply the payment
128
+ to specific invoice(s):
129
+
130
+ ```ruby
131
+ payment = Smartbill::Sdk::Models::Payment.new(
132
+ company_vat_code: "RO12345678",
133
+ client: Smartbill::Sdk::Models::Client.new(name: "Intelligent IT", vat_code: "RO12345678"),
134
+ value: 62.0,
135
+ type: Smartbill::Sdk::Models::PaymentType::ORDIN_PLATA,
136
+ is_cash: false,
137
+ invoices_list: [
138
+ Smartbill::Sdk::Models::InvoiceRef.new(series_name: "FCT", number: "0040")
139
+ ]
140
+ )
141
+ resp = client.payments.create(payment)
142
+ ```
143
+
144
+ ## Fetch fiscal-printer text by id (later)
145
+
146
+ ```ruby
147
+ r = client.payments.fiscal_receipt_text("RO12345678", "12345")
148
+ puts r.message # base64-encoded text
149
+ ```
150
+
151
+ ## Delete a payment
152
+
153
+ ```ruby
154
+ # Non-chitanta (uses query params to identify the payment):
155
+ client.payments.delete_other(
156
+ "RO12345678",
157
+ payment_type: "Card",
158
+ payment_date: "2026-06-21",
159
+ payment_value: 100.0,
160
+ client_name: "Intelligent IT",
161
+ client_cif: "RO12345678",
162
+ invoice_series: "FCT",
163
+ invoice_number: "0040"
164
+ )
165
+
166
+ # Chitanta (identified by its own series + number):
167
+ client.payments.delete_chitanta("RO12345678", "CHI", "0001")
168
+ ```
169
+
170
+ All `delete_other` keyword args except `payment_type:` are optional filters.
171
+
172
+ ## Concurrency (threads)
173
+
174
+ Ruby has no asyncio client. For independent calls, run them on threads:
175
+
176
+ ```ruby
177
+ t1 = Thread.new { client.payments.create(payment) }
178
+ t2 = Thread.new { client.invoices.payment_status("RO12345678", "FCT", "0040") }
179
+ receipt = t1.value
180
+ status = t2.value
181
+ ```
182
+
183
+ ## Errors
184
+
185
+ `Smartbill::Sdk::APIError` carries `.error_text` (the API's `errorText`),
186
+ `.message_field`, and `.status_code`. See `lib/smartbill/sdk/exceptions.rb`.
187
+
188
+ ## Reference
189
+
190
+ - Source: `lib/smartbill/sdk/services.rb` (`PaymentsService`)
191
+ - Models: `lib/smartbill/sdk/models/payments.rb`, `common.rb`,
192
+ `responses.rb` (`FiscalReceiptResponse`)
193
+ - Worked examples: `examples/create_payment_sync.rb`,
194
+ `examples/fiscal_receipt_sync.rb`
metadata ADDED
@@ -0,0 +1,214 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: smartbill-sdk
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0
5
+ platform: ruby
6
+ authors:
7
+ - Denis Nutiu
8
+ bindir: exe
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: base64
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '0.2'
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - "~>"
24
+ - !ruby/object:Gem::Version
25
+ version: '0.2'
26
+ - !ruby/object:Gem::Dependency
27
+ name: dry-inflector
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - "~>"
31
+ - !ruby/object:Gem::Version
32
+ version: '1.0'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - "~>"
38
+ - !ruby/object:Gem::Version
39
+ version: '1.0'
40
+ - !ruby/object:Gem::Dependency
41
+ name: dry-struct
42
+ requirement: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - "~>"
45
+ - !ruby/object:Gem::Version
46
+ version: '1.6'
47
+ type: :runtime
48
+ prerelease: false
49
+ version_requirements: !ruby/object:Gem::Requirement
50
+ requirements:
51
+ - - "~>"
52
+ - !ruby/object:Gem::Version
53
+ version: '1.6'
54
+ - !ruby/object:Gem::Dependency
55
+ name: dry-types
56
+ requirement: !ruby/object:Gem::Requirement
57
+ requirements:
58
+ - - "~>"
59
+ - !ruby/object:Gem::Version
60
+ version: '1.7'
61
+ type: :runtime
62
+ prerelease: false
63
+ version_requirements: !ruby/object:Gem::Requirement
64
+ requirements:
65
+ - - "~>"
66
+ - !ruby/object:Gem::Version
67
+ version: '1.7'
68
+ - !ruby/object:Gem::Dependency
69
+ name: dry-validation
70
+ requirement: !ruby/object:Gem::Requirement
71
+ requirements:
72
+ - - "~>"
73
+ - !ruby/object:Gem::Version
74
+ version: '1.10'
75
+ type: :runtime
76
+ prerelease: false
77
+ version_requirements: !ruby/object:Gem::Requirement
78
+ requirements:
79
+ - - "~>"
80
+ - !ruby/object:Gem::Version
81
+ version: '1.10'
82
+ - !ruby/object:Gem::Dependency
83
+ name: zeitwerk
84
+ requirement: !ruby/object:Gem::Requirement
85
+ requirements:
86
+ - - "~>"
87
+ - !ruby/object:Gem::Version
88
+ version: '2.6'
89
+ type: :runtime
90
+ prerelease: false
91
+ version_requirements: !ruby/object:Gem::Requirement
92
+ requirements:
93
+ - - "~>"
94
+ - !ruby/object:Gem::Version
95
+ version: '2.6'
96
+ description: A Ruby SDK for the SmartBill Cloud REST API, offering a synchronous client
97
+ with typed request/response models for invoices, proformas, payments, e-mail, taxes,
98
+ series and stocks.
99
+ email:
100
+ - dnutiu@hey.com
101
+ executables: []
102
+ extensions: []
103
+ extra_rdoc_files: []
104
+ files:
105
+ - AGENTS.md
106
+ - CHANGELOG.md
107
+ - LICENSE.txt
108
+ - README.md
109
+ - Rakefile
110
+ - Steepfile
111
+ - docs/openapi.json
112
+ - examples/create_estimate_sync.rb
113
+ - examples/create_invoice_eur_product_in_ron.rb
114
+ - examples/create_invoice_sync.rb
115
+ - examples/create_payment_sync.rb
116
+ - examples/fiscal_receipt_sync.rb
117
+ - examples/invoice_lifecycle_sync.rb
118
+ - examples/list_series_sync.rb
119
+ - examples/send_email_sync.rb
120
+ - examples/taxes_and_stocks_sync.rb
121
+ - lib/smartbill/sdk.rb
122
+ - lib/smartbill/sdk/api_error.rb
123
+ - lib/smartbill/sdk/auth_error.rb
124
+ - lib/smartbill/sdk/client.rb
125
+ - lib/smartbill/sdk/contracts.rb
126
+ - lib/smartbill/sdk/contracts/base.rb
127
+ - lib/smartbill/sdk/contracts/email_contract.rb
128
+ - lib/smartbill/sdk/contracts/estimate_contract.rb
129
+ - lib/smartbill/sdk/contracts/invoice_contract.rb
130
+ - lib/smartbill/sdk/contracts/invoice_payment_contract.rb
131
+ - lib/smartbill/sdk/contracts/invoice_ref_contract.rb
132
+ - lib/smartbill/sdk/contracts/payment_contract.rb
133
+ - lib/smartbill/sdk/contracts/storno_contract.rb
134
+ - lib/smartbill/sdk/error.rb
135
+ - lib/smartbill/sdk/models.rb
136
+ - lib/smartbill/sdk/models/base_response.rb
137
+ - lib/smartbill/sdk/models/client.rb
138
+ - lib/smartbill/sdk/models/discount_type.rb
139
+ - lib/smartbill/sdk/models/document_type.rb
140
+ - lib/smartbill/sdk/models/email_document.rb
141
+ - lib/smartbill/sdk/models/email_response.rb
142
+ - lib/smartbill/sdk/models/email_status.rb
143
+ - lib/smartbill/sdk/models/estimate.rb
144
+ - lib/smartbill/sdk/models/fiscal_receipt_response.rb
145
+ - lib/smartbill/sdk/models/invoice.rb
146
+ - lib/smartbill/sdk/models/invoice_create_response.rb
147
+ - lib/smartbill/sdk/models/invoice_payment.rb
148
+ - lib/smartbill/sdk/models/invoice_ref.rb
149
+ - lib/smartbill/sdk/models/payment.rb
150
+ - lib/smartbill/sdk/models/payment_status_response.rb
151
+ - lib/smartbill/sdk/models/payment_type.rb
152
+ - lib/smartbill/sdk/models/product.rb
153
+ - lib/smartbill/sdk/models/proforma_invoices_response.rb
154
+ - lib/smartbill/sdk/models/series.rb
155
+ - lib/smartbill/sdk/models/series_list_response.rb
156
+ - lib/smartbill/sdk/models/stock_list.rb
157
+ - lib/smartbill/sdk/models/stock_product.rb
158
+ - lib/smartbill/sdk/models/stock_warehouse.rb
159
+ - lib/smartbill/sdk/models/stocks_response.rb
160
+ - lib/smartbill/sdk/models/storno_request.rb
161
+ - lib/smartbill/sdk/models/storno_response.rb
162
+ - lib/smartbill/sdk/models/struct.rb
163
+ - lib/smartbill/sdk/models/tax.rb
164
+ - lib/smartbill/sdk/models/taxes_response.rb
165
+ - lib/smartbill/sdk/net_http_adapter.rb
166
+ - lib/smartbill/sdk/rate_limit_error.rb
167
+ - lib/smartbill/sdk/response.rb
168
+ - lib/smartbill/sdk/services.rb
169
+ - lib/smartbill/sdk/services/base_service.rb
170
+ - lib/smartbill/sdk/services/configuration_service.rb
171
+ - lib/smartbill/sdk/services/email_service.rb
172
+ - lib/smartbill/sdk/services/estimates_service.rb
173
+ - lib/smartbill/sdk/services/invoices_service.rb
174
+ - lib/smartbill/sdk/services/payments_service.rb
175
+ - lib/smartbill/sdk/services/stocks_service.rb
176
+ - lib/smartbill/sdk/transport.rb
177
+ - lib/smartbill/sdk/transport/rate_limiter.rb
178
+ - lib/smartbill/sdk/transport/request.rb
179
+ - lib/smartbill/sdk/transport_error.rb
180
+ - lib/smartbill/sdk/types.rb
181
+ - lib/smartbill/sdk/validation_error.rb
182
+ - lib/smartbill/sdk/version.rb
183
+ - sig/smartbill/sdk.rbs
184
+ - skills/README.md
185
+ - skills/smartbill-email/SKILL.md
186
+ - skills/smartbill-invoices/SKILL.md
187
+ - skills/smartbill-payments/SKILL.md
188
+ homepage: https://github.com/dnutiu/smartbill-sdk-ruby
189
+ licenses:
190
+ - MIT
191
+ metadata:
192
+ allowed_push_host: https://rubygems.org
193
+ homepage_uri: https://github.com/dnutiu/smartbill-sdk-ruby
194
+ source_code_uri: https://github.com/dnutiu/smartbill-sdk-ruby
195
+ changelog_uri: https://github.com/dnutiu/smartbill-sdk-ruby/blob/main/CHANGELOG.md
196
+ rubygems_mfa_required: 'true'
197
+ rdoc_options: []
198
+ require_paths:
199
+ - lib
200
+ required_ruby_version: !ruby/object:Gem::Requirement
201
+ requirements:
202
+ - - ">="
203
+ - !ruby/object:Gem::Version
204
+ version: 3.2.0
205
+ required_rubygems_version: !ruby/object:Gem::Requirement
206
+ requirements:
207
+ - - ">="
208
+ - !ruby/object:Gem::Version
209
+ version: '0'
210
+ requirements: []
211
+ rubygems_version: 4.0.6
212
+ specification_version: 4
213
+ summary: Ruby SDK for the SmartBill Cloud REST API.
214
+ test_files: []