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.
- checksums.yaml +7 -0
- data/AGENTS.md +211 -0
- data/CHANGELOG.md +18 -0
- data/LICENSE.txt +21 -0
- data/README.md +265 -0
- data/Rakefile +22 -0
- data/Steepfile +6 -0
- data/docs/openapi.json +9741 -0
- data/examples/create_estimate_sync.rb +53 -0
- data/examples/create_invoice_eur_product_in_ron.rb +100 -0
- data/examples/create_invoice_sync.rb +57 -0
- data/examples/create_payment_sync.rb +36 -0
- data/examples/fiscal_receipt_sync.rb +50 -0
- data/examples/invoice_lifecycle_sync.rb +43 -0
- data/examples/list_series_sync.rb +27 -0
- data/examples/send_email_sync.rb +40 -0
- data/examples/taxes_and_stocks_sync.rb +48 -0
- data/lib/smartbill/sdk/api_error.rb +27 -0
- data/lib/smartbill/sdk/auth_error.rb +8 -0
- data/lib/smartbill/sdk/client.rb +68 -0
- data/lib/smartbill/sdk/contracts/base.rb +33 -0
- data/lib/smartbill/sdk/contracts/email_contract.rb +29 -0
- data/lib/smartbill/sdk/contracts/estimate_contract.rb +18 -0
- data/lib/smartbill/sdk/contracts/invoice_contract.rb +29 -0
- data/lib/smartbill/sdk/contracts/invoice_payment_contract.rb +18 -0
- data/lib/smartbill/sdk/contracts/invoice_ref_contract.rb +19 -0
- data/lib/smartbill/sdk/contracts/payment_contract.rb +37 -0
- data/lib/smartbill/sdk/contracts/storno_contract.rb +17 -0
- data/lib/smartbill/sdk/contracts.rb +19 -0
- data/lib/smartbill/sdk/error.rb +8 -0
- data/lib/smartbill/sdk/models/base_response.rb +16 -0
- data/lib/smartbill/sdk/models/client.rb +26 -0
- data/lib/smartbill/sdk/models/discount_type.rb +13 -0
- data/lib/smartbill/sdk/models/document_type.rb +13 -0
- data/lib/smartbill/sdk/models/email_document.rb +23 -0
- data/lib/smartbill/sdk/models/email_response.rb +12 -0
- data/lib/smartbill/sdk/models/email_status.rb +13 -0
- data/lib/smartbill/sdk/models/estimate.rb +32 -0
- data/lib/smartbill/sdk/models/fiscal_receipt_response.rb +16 -0
- data/lib/smartbill/sdk/models/invoice.rb +44 -0
- data/lib/smartbill/sdk/models/invoice_create_response.rb +10 -0
- data/lib/smartbill/sdk/models/invoice_payment.rb +15 -0
- data/lib/smartbill/sdk/models/invoice_ref.rb +24 -0
- data/lib/smartbill/sdk/models/payment.rb +49 -0
- data/lib/smartbill/sdk/models/payment_status_response.rb +19 -0
- data/lib/smartbill/sdk/models/payment_type.rb +22 -0
- data/lib/smartbill/sdk/models/product.rb +38 -0
- data/lib/smartbill/sdk/models/proforma_invoices_response.rb +13 -0
- data/lib/smartbill/sdk/models/series.rb +14 -0
- data/lib/smartbill/sdk/models/series_list_response.rb +14 -0
- data/lib/smartbill/sdk/models/stock_list.rb +13 -0
- data/lib/smartbill/sdk/models/stock_product.rb +15 -0
- data/lib/smartbill/sdk/models/stock_warehouse.rb +13 -0
- data/lib/smartbill/sdk/models/stocks_response.rb +14 -0
- data/lib/smartbill/sdk/models/storno_request.rb +17 -0
- data/lib/smartbill/sdk/models/storno_response.rb +14 -0
- data/lib/smartbill/sdk/models/struct.rb +102 -0
- data/lib/smartbill/sdk/models/tax.rb +14 -0
- data/lib/smartbill/sdk/models/taxes_response.rb +14 -0
- data/lib/smartbill/sdk/models.rb +17 -0
- data/lib/smartbill/sdk/net_http_adapter.rb +62 -0
- data/lib/smartbill/sdk/rate_limit_error.rb +9 -0
- data/lib/smartbill/sdk/response.rb +12 -0
- data/lib/smartbill/sdk/services/base_service.rb +39 -0
- data/lib/smartbill/sdk/services/configuration_service.rb +29 -0
- data/lib/smartbill/sdk/services/email_service.rb +18 -0
- data/lib/smartbill/sdk/services/estimates_service.rb +60 -0
- data/lib/smartbill/sdk/services/invoices_service.rb +69 -0
- data/lib/smartbill/sdk/services/payments_service.rb +50 -0
- data/lib/smartbill/sdk/services/stocks_service.rb +21 -0
- data/lib/smartbill/sdk/services.rb +30 -0
- data/lib/smartbill/sdk/transport/rate_limiter.rb +49 -0
- data/lib/smartbill/sdk/transport/request.rb +17 -0
- data/lib/smartbill/sdk/transport.rb +162 -0
- data/lib/smartbill/sdk/transport_error.rb +8 -0
- data/lib/smartbill/sdk/types.rb +22 -0
- data/lib/smartbill/sdk/validation_error.rb +8 -0
- data/lib/smartbill/sdk/version.rb +7 -0
- data/lib/smartbill/sdk.rb +31 -0
- data/sig/smartbill/sdk.rbs +661 -0
- data/skills/README.md +35 -0
- data/skills/smartbill-email/SKILL.md +120 -0
- data/skills/smartbill-invoices/SKILL.md +178 -0
- data/skills/smartbill-payments/SKILL.md +194 -0
- 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: []
|