smartbill-sdk 1.0.0

data/examples/create_estimate_sync.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Exemplu: emiterea unei proforme (sincron).
+#
+# Proforma se creează cu Estimate și se trimite prin
+# client.estimates.create(estimate) (POST /estimate). Structura este foarte
+# asemănătoare cu o factură: client, serie, produse.
+#
+# Documentul poate fi convertit ulterior în factură; starea conversiei se
+# verifică cu client.estimates.invoices_status(...).
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+def main
+  Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN").with_client do |client|
+    estimate = Smartbill::Sdk::Models::Estimate.new(
+      company_vat_code: "RO12345678",
+      client: Smartbill::Sdk::Models::Client.new(
+        name: "Intelligent IT",
+        vat_code: "RO12345678",
+        email: "office@intelligent.ro"
+      ),
+      series_name: "PFC",
+      is_draft: false,
+      products: [
+        Smartbill::Sdk::Models::Product.new(
+          name: "Serviciu dezvoltare",
+          measuring_unit_name: "ore",
+          currency: "RON",
+          quantity: 10,
+          price: 150,
+          is_tax_included: false,
+          tax_name: "Normala",
+          tax_percentage: 19
+        )
+      ]
+    )
+
+    resp = client.estimates.create(estimate)
+    puts "Proforma emisa: seria #{resp.series}, numarul #{resp.number}"
+
+    # Verificăm dacă proforma a fost deja convertită în factură.
+    status = client.estimates.invoices_status("RO12345678", resp.series, resp.number)
+    if status.are_invoices_created
+      status.invoices.each { |inv| puts "  Factura generata: #{inv.series_name} #{inv.number}" }
+    else
+      puts "  Proforma nu a fost inca convertita in factura."
+    end
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/create_invoice_eur_product_in_ron.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Exemplu: emiterea unei facturi în RON cu un produs cu preț de referință în
+# EUR (sincron).
+#
+# Acest script arată cum se emite o factură a cărei monedă este RON, dar al
+# cărei produs are prețul de referință în EUR. SmartBill convertește
+# automat folosind cursul BNR din data emiterii (când nu se specifică
+# `exchange_rate` pe produs), sau se poate da un curs explicit.
+#
+# Tiparul corespunde definiției `exempluFacturaPreturiValuta` din
+# `docs/openapi.json`: produsul are `currency: "EUR"`, iar factura are
+# `currency: "RON"`.
+#
+# `is_draft: true` salvează factura ca ciornă (fără număr, neemitcă către
+# ANAF) — sigur pentru teste pe cont real. Pentru emitere finală, folosește
+# `is_draft: false`.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+# TODO: înlocuiește cu datele tale.
+USERNAME = "you@example.com"
+TOKEN = "YOUR_TOKEN"
+COMPANY_VAT_CODE = "52859275"     # CIF-ul firmei tale (emitentul)
+CLIENT_VAT_CODE = "RO46548525"    # CIF-ul clientului
+SERIES_NAME = "ABC"
+
+# Cursul EUR->RON. Lasă-l `nil` pentru a lăsa SmartBill să folosească cursul
+# BNR din data emiterii. Dacă API-ul cere un curs explicit, setează-l aici,
+# de ex. `EXCHANGE_RATE = 5.05`.
+EXCHANGE_RATE = nil
+
+def build_product(name:, price_eur:, quantity:, exchange_rate:)
+  attrs = {
+    name: name,
+    is_service: true,
+    measuring_unit_name: "ore",
+    currency: "EUR",            # moneda prețului de referință
+    price: price_eur,           # preț unitar în EUR (fără TVA)
+    quantity: quantity,
+    is_tax_included: false,     # B2B: preț fără TVA
+    tax_name: "Normala",
+    tax_percentage: 19
+  }
+  attrs[:exchange_rate] = exchange_rate unless exchange_rate.nil?
+  Smartbill::Sdk::Models::Product.new(**attrs)
+end
+
+def build_invoice
+  product = build_product(
+    name: "Servicii de dezvoltare software",
+    price_eur: 31,
+    quantity: 168,
+    exchange_rate: EXCHANGE_RATE
+  )
+
+  Smartbill::Sdk::Models::Invoice.new(
+    company_vat_code: COMPANY_VAT_CODE,
+    client: Smartbill::Sdk::Models::Client.new(
+      name: "Intelligent IT",
+      vat_code: CLIENT_VAT_CODE,
+      city: "Sibiu",
+      county: "Sibiu",
+      country: "Romania",
+      address: "str. Sperantei, nr. 5",
+      email: "office@intelligent.ro"
+    ),
+    series_name: SERIES_NAME,
+    is_draft: true,             # ciornă: salvată, nefinalizată, fără număr
+    issue_date: Time.now.strftime("%Y-%m-%d"),
+    due_date: (Time.now + (86_400 * 15)).strftime("%Y-%m-%d"),
+    currency: "RON",            # moneda documentului
+    mentions: "Nota Comanda Nr. 1 din 11.05.2026, Contract WP271",
+    products: [product]
+  )
+end
+
+def main
+  Smartbill::Sdk::Client.new(username: USERNAME, token: TOKEN).with_client do |client|
+    invoice = build_invoice
+    resp = client.invoices.create(invoice)
+
+    if resp.number && !resp.number.empty?
+      puts "Factura finalizată: seria #{resp.series}, numărul #{resp.number}"
+    else
+      # La ciornă, `number` este gol — factura a fost doar salvată.
+      puts "Factura salvată în ciornă (seria #{resp.series})."
+    end
+    puts "Mesaj API: #{resp.message}" if resp.message
+  end
+rescue Smartbill::Sdk::AuthError => e
+  warn "Eroare autentificare (401): #{e.message}"
+rescue Smartbill::Sdk::APIError => e
+  warn "Eroare API [#{e.status_code}]: #{e.error_text}"
+rescue Smartbill::Sdk::ValidationError => e
+  warn "Eroare validare: #{e.message}"
+end
+
+main

data/examples/create_invoice_sync.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Exemplu: emiterea unei facturi simple (sincron).
+#
+# Acest script arată cum se creează și se emite o factură nouă folosind
+# clientul sincron Smartbill::Sdk::Client. Factura conține un singur produs
+# cu TVA inclus (cota redusă) și este emisă direct (is_draft: false).
+#
+# Câmpurile din modele folosesc snake_case în Ruby, dar sunt serializate
+# automat în camelCase către API (ex. company_vat_code devine companyVatCode).
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+def main
+  # 1. Autentificare (HTTP Basic Auth: username:token).
+  client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN")
+
+  # 2. Construirea facturii.
+  invoice = Smartbill::Sdk::Models::Invoice.new(
+    company_vat_code: "RO12345678",
+    client: Smartbill::Sdk::Models::Client.new(
+      name: "Intelligent IT",
+      vat_code: "RO12345678",
+      address: "str. Sperantei, nr. 5",
+      city: "Sibiu",
+      county: "Sibiu",
+      country: "Romania",
+      email: "office@intelligent.ro"
+    ),
+    series_name: "FCT",
+    is_draft: false,
+    issue_date: "2024-05-01",
+    due_date: "2024-05-15",
+    products: [
+      Smartbill::Sdk::Models::Product.new(
+        name: "Produs 1",
+        code: "ccd1",
+        measuring_unit_name: "buc",
+        currency: "RON",
+        quantity: 2,
+        price: 10,
+        is_tax_included: true,
+        tax_name: "Redusa",
+        tax_percentage: 9
+      )
+    ]
+  )
+
+  # 3. Emiterea facturii.
+  client.with_client do |c|
+    resp = c.invoices.create(invoice)
+    puts "Factura emisa: seria #{resp.series}, numarul #{resp.number}"
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/create_payment_sync.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Exemplu: înregistrarea unei încasări pe o factură (sincron).
+#
+# Aici se emite o încasare de tip „Chitanta” care este legată de o factură
+# existentă prin invoices_list (perechi serie + număr).
+#
+# Endpoint: POST /payment. Modelul Payment acoperă toate tipurile de
+# încasări (chitanță, bon, card, ordin de plată etc.) prin câmpul type.
+# Câmpurile care nu se aplică tipului ales se lasă nil.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+def main
+  Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN").with_client do |client|
+    payment = Smartbill::Sdk::Models::Payment.new(
+      company_vat_code: "RO12345678",
+      client: Smartbill::Sdk::Models::Client.new(name: "Intelligent IT", vat_code: "RO12345678"),
+      value: 62.0,
+      type: Smartbill::Sdk::Models::PaymentType::CHITANTA,
+      is_cash: true,
+      invoices_list: [
+        Smartbill::Sdk::Models::InvoiceRef.new(series_name: "FCT", number: "0040")
+      ]
+    )
+
+    resp = client.payments.create(payment)
+    puts "Incasare inregistrata: seria #{resp.series}, numarul #{resp.number}"
+
+    # Ștergere chitanță (dacă ulterior se anulează).
+    # client.payments.delete_chitanta("RO12345678", resp.series, resp.number)
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/fiscal_receipt_sync.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Exemplu: emiterea unui bon fiscal cu încasare mixtă (sincron).
+#
+# Bonul fiscal se emite tot prin POST /payment cu type='Bon'. Pe lângă
+# produsele vândute, se pot specifica sumele încasate pe fiecare metodă
+# de plată (cash, card, tichete de masă etc.) prin câmpurile received_*.
+# Dacă return_fiscal_printer_text: true, API-ul returnează textul
+# destinat imprimantei fiscale (în message).
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+def main
+  Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN").with_client do |client|
+    payment = Smartbill::Sdk::Models::Payment.new(
+      company_vat_code: "RO12345678",
+      value: 260.0,
+      type: "Bon",
+      is_cash: false,
+      use_stock: false,
+      return_fiscal_printer_text: true,
+      products: [
+        Smartbill::Sdk::Models::Product.new(
+          name: "Produs 1", measuring_unit_name: "buc", currency: "RON",
+          quantity: 1, price: 200, is_tax_included: true,
+          tax_name: "Normala", tax_percentage: 19
+        ),
+        Smartbill::Sdk::Models::Product.new(
+          name: "Produs 2", measuring_unit_name: "buc", currency: "RON",
+          quantity: 1, price: 60, is_tax_included: true,
+          tax_name: "Normala", tax_percentage: 19
+        )
+      ],
+      received_cash: 200.0,
+      received_card: 60.0
+    )
+
+    receipt = client.payments.create(payment)
+    puts "Bon fiscal emis: id=#{receipt.id}"
+    puts "  Text imprimanta fiscala: #{receipt.message}"
+
+    # Starea plății pentru o factură deja existentă.
+    status = client.invoices.payment_status("RO12345678", "FCT", "0040")
+    puts "Stare plata factura: total=#{status.invoice_total_amount}, " \
+         "platit=#{status.paid_amount}, rest=#{status.unpaid_amount}"
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/invoice_lifecycle_sync.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Exemplu: stornare, anulare, restaurare factură și descărcare PDF (sincron).
+#
+# Acest exemplu ilustrează operațiile secundare pe facturi:
+#   * client.invoices.reverse(StornoRequest)  -> POST /invoice/reverse
+#   * client.invoices.cancel(cif, series, number) -> PUT /invoice/cancel
+#   * client.invoices.restore(cif, series, number) -> PUT /invoice/restore
+#   * client.invoices.pdf(cif, series, number) -> GET /invoice/pdf (binary String)
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+def main
+  Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN").with_client do |client|
+    cif = "RO12345678"
+    series = "FCT"
+    number = "0040"
+
+    # 1. Stornare.
+    storno = Smartbill::Sdk::Models::StornoRequest.new(
+      company_vat_code: cif, series_name: series, number: number
+    )
+    st = client.invoices.reverse(storno)
+    puts "Factura storno: #{st.series} #{st.number}"
+    puts "  Document URL: #{st.document_url}"
+
+    # 2. Anulare factură originală.
+    client.invoices.cancel(cif, series, number)
+    puts "Factura a fost anulata."
+
+    # 3. Restaurare factură (se poate face ulterior).
+    client.invoices.restore(cif, series, number)
+    puts "Factura a fost restaurata."
+
+    # 4. Descărcare PDF.
+    pdf_bytes = client.invoices.pdf(cif, series, number)
+    File.binwrite("factura.pdf", pdf_bytes)
+    puts "PDF salvat (#{pdf_bytes.bytesize} bytes)."
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/list_series_sync.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Exemplu: listarea seriilor de documente (sincron).
+#
+# Endpoint: GET /series. Returnează seriile (și următorul număr liber)
+# pentru documentele din cont. Parametrul opțional type filtrează după
+# tipul documentului:
+#   f - facturi, c - chitanțe, p - proforme, i - bonuri fiscale, n - avize
+# Dacă type nu este dat, se returnează toate seriile.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+def main
+  Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN").with_client do |client|
+    # Doar seriile de facturi.
+    facturi = client.series.series("RO12345678", type: "f")
+    puts "Serii facturi:"
+    facturi.list.each { |s| puts "  - #{s.name}: urmatorul numar #{s.next_number}" }
+
+    # Toate seriile (fără filtru).
+    toate = client.series.series("RO12345678")
+    puts "Total serii (orice tip): #{toate.list.size}"
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/send_email_sync.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Exemplu: trimiterea pe e-mail a unui document (sincron).
+#
+# Endpoint: POST /document/send. Modelul EmailDocument identifică
+# documentul prin serie + număr + tip (factura sau proforma) și permite
+# specificarea destinatarilor (to, cc, bcc) și a conținutului.
+#
+# Important: câmpurile subject și body_text trebuie să fie codificate
+# Base64 de către apelant, conform cerințelor API-ului SmartBill.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+require "base64"
+
+# Codifică un text în Base64 (necesar pentru subject/bodyText).
+def b64(text)
+  Base64.strict_encode64(text)
+end
+
+def main
+  Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN").with_client do |client|
+    email = Smartbill::Sdk::Models::EmailDocument.new(
+      company_vat_code: "RO12345678",
+      series_name: "FCT",
+      number: "0040",
+      type: Smartbill::Sdk::Models::DocumentType::INVOICE,
+      to: "client@example.ro",
+      cc: "contabilitate@example.ro",
+      subject: b64("Factura FCT0040"),
+      body_text: b64("Va trimitem Factura FCT0040. Multumim!")
+    )
+
+    resp = client.email.send(email)
+    # status.code este "0" la succes.
+    puts "Status cod: #{resp.status.code}, mesaj: #{resp.status.message}"
+  end
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/taxes_and_stocks_sync.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Exemplu: listarea taxelor (TVA) și a stocurilor (sincron, concurent).
+#
+# Echivalentul Ruby al exemplelor asincrone din Python. Ruby nu are un
+# client async dedicat în acest SDK, dar operațiile independente pot fi
+# rulate concurent cu thread-uri (fiecare thread folosește propriul
+# Smartbill::Sdk::Client, sau clientul shared — Net::HTTP deschide o
+# conexiune nouă per request, deci este thread-safe în această privință).
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "smartbill/sdk"
+
+CIF = "RO12345678"
+
+def fetch_taxes(client)
+  client.taxes.taxes(CIF)
+end
+
+def fetch_stocks(client)
+  client.stocks.get(CIF, "2024-05-01")
+end
+
+def main
+  client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "YOUR_TOKEN")
+
+  taxes_thread = Thread.new { fetch_taxes(client) }
+  stocks_thread = Thread.new { fetch_stocks(client) }
+
+  taxes = taxes_thread.value
+  stocks = stocks_thread.value
+
+  puts "Taxe:"
+  taxes.taxes.each { |t| puts "  - #{t.name}: #{t.percentage}%" }
+
+  puts "Stocuri:"
+  stocks.list.each do |entry|
+    wh = entry.warehouse
+    puts "  Gestiune: #{wh&.warehouse_name} (#{wh&.warehouse_type})"
+    entry.products.each do |p|
+      puts "    - #{p.product_name} [#{p.product_code}]: #{p.quantity} #{p.measuring_unit}"
+    end
+  end
+ensure
+  client&.close
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/lib/smartbill/sdk/api_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    # Raised when the SmartBill API returns an error envelope or a non-2xx
+    # response.
+    #
+    # @!attribute [r] error_text
+    #   @return [String] the +errorText+ field from the API response.
+    # @!attribute [r] message_field
+    #   @return [String, nil] the optional +message+ field from the API.
+    # @!attribute [r] status_code
+    #   @return [Integer, nil] the HTTP status code, if available.
+    class APIError < Error
+      attr_reader :error_text, :message_field, :status_code
+
+      def initialize(error_text: "", message: nil, status_code: nil)
+        @error_text = error_text.to_s
+        @message_field = message
+        @status_code = status_code
+        detail = @error_text.empty? ? (message || "SmartBill API error") : @error_text
+        detail = "[#{status_code}] #{detail}" unless status_code.nil?
+        super(detail)
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/auth_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    # Raised on HTTP 401 (bad credentials / company CIF).
+    class AuthError < Error; end
+  end
+end

data/lib/smartbill/sdk/client.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    # Synchronous client for the SmartBill Cloud REST API.
+    #
+    # Usage:
+    #
+    #   client = Smartbill::Sdk::Client.new(username: "you@example.com", token: "...")
+    #   resp = client.invoices.create(invoice)
+    #   puts resp.series, resp.number
+    #   client.close
+    #
+    # Or with a block (closes automatically):
+    #
+    #   Smartbill::Sdk::Client.new(username: "...", token: "...").with_client do |client|
+    #     client.invoices.create(invoice)
+    #   end
+    class Client
+      attr_reader :username, :token, :base_url, :auth_header,
+                  :invoices, :estimates, :payments, :email, :taxes, :series, :stocks
+
+      def initialize(username:, token:, base_url: Transport::DEFAULT_BASE_URL,
+                     timeout: Transport::DEFAULT_TIMEOUT, enforce_rate_limit: false,
+                     http: nil)
+        @username = username
+        @token = token
+        @base_url = base_url
+        @auth_header = Transport.build_auth(username, token)
+        @rate_limiter = enforce_rate_limit ? Transport::RateLimiter.new : nil
+        @http = http || NetHttpAdapter.new(timeout: timeout)
+        @invoices  = Services::InvoicesService.new(self)
+        @estimates = Services::EstimatesService.new(self)
+        @payments  = Services::PaymentsService.new(self)
+        @email     = Services::EmailService.new(self)
+        @taxes     = Services::ConfigurationService.new(self)
+        @series    = @taxes # convenience alias: taxes + series share one service
+        @stocks    = Services::StocksService.new(self)
+      end
+
+      # Send a {Transport::Request} and return the parsed payload.
+      # When +binary+ is true, the raw body String is returned.
+      def execute(request, binary: false)
+        @rate_limiter&.acquire
+        response = begin
+          @http.call(request)
+        rescue Error, AuthError, APIError, RateLimitError, ValidationError => e
+          raise e
+        rescue StandardError => e
+          raise TransportError, "Transport error: #{e.message}"
+        end
+        @rate_limiter&.notify_403 if response.status == 403 && @rate_limiter
+        Transport.handle_response(response, binary: binary)
+      end
+
+      # Close the underlying HTTP adapter. A no-op for the default
+      # +Net::HTTP+ adapter (which opens a fresh connection per request).
+      def close; end
+
+      # Yield self to a block and ensure +#close+ is called afterwards.
+      def with_client
+        yield self
+      ensure
+        close
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/contracts/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Contracts
+      # Base class for every SmartBill validation contract.
+      #
+      # Declares shared type predicates (e.g. {DATE_REGEX}) and provides
+      # {validate}, the helper services call to run a struct's attributes
+      # through the contract and raise {ValidationError} on failure.
+      class Base < Dry::Validation::Contract
+        # `YYYY-MM-DD`, matching the SmartBill API date format.
+        DATE_REGEX = /\A\d{4}-\d{2}-\d{2}\z/
+
+        class << self
+          # Validate +struct+ (a {Models::Struct}) against this contract,
+          # raising {ValidationError} with the aggregated error messages
+          # when the contract fails. Returns the struct unchanged on success.
+          def validate!(struct)
+            result = new.call(struct.to_attributes)
+            return struct if result.success?
+
+            messages = result.errors.map do |err|
+              path = err.path.is_a?(Array) ? err.path.join(".") : err.path
+              "#{path} #{err.text}"
+            end
+            raise ValidationError, "Validation failed: #{messages.join("; ")}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/contracts/email_contract.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Contracts
+      # Validation contract for {Models::EmailDocument} (+POST /document/send+).
+      #
+      # Validates +type+ (factura / proforma) and a basic shape check on the
+      # recipient addresses. +subject+ and +body_text+ must be Base64-encoded
+      # by the caller — this contract does not verify the encoding.
+      class EmailContract < Base
+        DOCUMENT_TYPES = %w[factura proforma].freeze
+        # Very permissive e-mail shape check — the SmartBill API does the
+        # authoritative validation.
+        EMAIL_REGEX = /\A[^@\s]+@[^@\s]+\z/
+
+        params do
+          required(:company_vat_code).filled(:string)
+          required(:series_name).filled(:string)
+          required(:number).filled(:string)
+          optional(:type).maybe(:string, included_in?: DOCUMENT_TYPES)
+          optional(:to).maybe(:string, format?: EMAIL_REGEX)
+          optional(:cc).maybe(:string, format?: EMAIL_REGEX)
+          optional(:bcc).maybe(:string, format?: EMAIL_REGEX)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/contracts/estimate_contract.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Contracts
+      # Validation contract for {Models::Estimate} (proforma).
+      class EstimateContract < Base
+        params do
+          required(:company_vat_code).filled(:string)
+          optional(:issue_date).maybe(:string, format?: DATE_REGEX)
+          optional(:due_date).maybe(:string, format?: DATE_REGEX)
+          optional(:precision).maybe(:integer, gteq?: 0)
+          optional(:exchange_rate).maybe(:float, gt?: 0)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/contracts/invoice_contract.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Contracts
+      # Validation contract for {Models::Invoice}.
+      #
+      # Adds semantic rules on top of the struct's shape/coercion: date
+      # fields must match +YYYY-MM-DD+, +precision+ must be a non-negative
+      # integer, and the embedded +payment+ (when present) must satisfy the
+      # {InvoicePaymentContract} rules.
+      class InvoiceContract < Base
+        params do
+          required(:company_vat_code).filled(:string)
+          optional(:issue_date).maybe(:string, format?: DATE_REGEX)
+          optional(:due_date).maybe(:string, format?: DATE_REGEX)
+          optional(:delivery_date).maybe(:string, format?: DATE_REGEX)
+          optional(:payment_date).maybe(:string, format?: DATE_REGEX)
+          optional(:precision).maybe(:integer, gteq?: 0)
+          optional(:exchange_rate).maybe(:float, gt?: 0)
+          optional(:payment).maybe(:hash) do
+            required(:value).filled(:float, gt?: 0)
+            required(:type).filled(:string)
+          end
+        end
+      end
+    end
+  end
+end