Papierkram API Client

Der erste illegale inoffizielle API Client in Ruby für Papierkram.de als Gem für dein Projekt!

Aufruf zur Mitarbeit für NodeJS/JavaScript 🫠
Das Gleiche, nur in grün, also für NodeJS ein Papierkram Api Client 😬

WICHTIG Dieses Projekt befindet sich im Entwicklungsstatus bis V1.0.0! Ich werde versuchen, die Änderungen so gut wie möglich zu dokumentieren. Wenn du einen Fehler findest, kannst du gerne einen Issue erstellen oder einen Pull Request mit einer Verbesserung erstellen. Ich freue mich über jede Hilfe!

🚨 Bitte beachte, dass DU UNBEDINGT die Requests/Responses der VCR Cassettes (die ausschliesslich bei Nutzung der Testsuite angelegt werden) von privaten Daten befreien musst, bevor du einen Pull Request erstellst oder einen Commit ins Web lädst! Ich werde die Cassettes auch nochmal durchgehen, bevor ich die Version 1.0.0 veröffentliche. ABER BITTE, BITTE, BITTE, mach das selbst auch! Ich habe keine Lust, dass irgendwelche Daten von dir oder deinen Kunden auf Github landen. Danke! 🙏

Check das CHANGELOG.md, Baby!
Schau in UPGRADING.md, 💃🕺!

Hier geht es zu den offiziellen API Docs.
Schau bitte dort um alle Rückgabefelder/-werte zu checken, bis ich (oder du mit deiner Zeit und Hingabe) die Dokumentation hier komplett habe.

WENN DU PROBLEME HAST, bitte ich dich erstmal die offiziellen API Docs zu durchstöbern. Dann lohnt es sich hier die Beispiele (weiter unten) zu lesen und von dort sowohl mal in die Methoden im Code zu springen, oder noch besser in die Tests schauen.
Wenn du dann immer noch nicht weiterkommst, kannst du gerne einen Issue erstellen. Poste dabei so viele Informationen wie möglich, damit ich dir bestmöglich weiterhelfen kann. Achte dabei bitte darauf, dass du keine privaten Daten postest. 🙏

• Banking::BankConnection
• Banking::BankTransaction
• Contact::Company (Unternehmen)
• Contact::Company (Kontaktpersonen)
• Expense::Voucher (Ausgabe Belege)
• Income::Estimate (Angebote)
• Income::Invoice (Rechnungen)
• Income::PaymentTerms (Zahlungsbedingungen)
• Income::Proposition (Waren / Dienstleistungen)
• Info
• Settings::CustomAttribute (Datenfelder)
• Project (Projekte)
• Tracker::Task (Aufgaben)
• Tracker::TimeEntry (Zeiterfassung)
• User

Papierkram.de hat nun eine API Schnittstelle für die Programmierung von eigenen Anwendungen. Die Dokumentation dazu findest du hier.

Ziele:

• Rückgabe von Hashes, Arrays, etc. statt von komplexeren Objekten (der gefürchtete DIY-Ansatz).
• Einfach zu testen und zu erweitern.

• Installation
• Schnellstart
• API Client
  • Initialisierung
  • Banking::BankConnection (Bankverbindung)
    • alle Bankverbindungen
    • eine Bankverbindung
  • Banking::Transaction (Kontoumsatz)
    • alle Kontoumsätze einer Bankverbindung
    • einen Kontoumsatz
  • Contact::Company (Unternehmen)
    • alle Unternehmen
    • ein Unternehmen
    • erstelle ein Unternehmen
    • aktualisiere ein Unternehmen
    • lösche ein Unternehmen
    • archiviere ein Unternehmen
    • unarchiviere ein Unternehmen
  • Contact::Company (Kontaktperson eines Unternehmens)
    • alle Kontaktpersonen (eines Unternehmens)
    • eine Kontaktperson (eines Unternehmens)
    • erstelle eine Kontaktperson (eines Unternehmens)
    • aktualisiere eine Kontaktperson (eines Unternehmens)
    • lösche eine Kontaktperson (eines Unternehmens)
  • Expense::Voucher (Ausgabe Beleg)
    • alle Ausgabe Belege
    • einen Ausgabe Beleg
    • einen Ausgabe Beleg als PDF
    • einen Ausgabe Beleg erstellen
    • einen Ausgabe Beleg aktualisieren
    • einen Ausgabe Beleg löschen
    • einen Ausgabe Beleg archivieren
    • einen Ausgabe Beleg unarchivieren
    • einen Ausgabe Beleg stornieren
    • einen Ausgabe Beleg rückwirkend stornieren
    • einen Ausgabe Beleg als bezahlt markieren
    • einem Ausgabe Beleg ein Dokument hinzufügen
    • einem Ausgabe Beleg ein Dokument entfernen
  • Income::Estimate (Angebot)
    • alle Angebote
    • ein Angebot
    • ein Angebot als PDF
  • Income::Invoice (Rechnung)
    • alle Rechnungen
    • eine Rechnung
    • eine Rechnung als PDF
    • eine Rechnung erstellen
    • eine Rechnung aktualisieren
    • eine Rechnung löschen
    • eine Rechnung archivieren
    • eine Rechnung unarchivieren
    • eine Rechnung stornieren
    • eine Rechnung verschicken
  • Income::PaymentTerms (Zahlungsbedingungen)
    • eine Zahlungsbedingung
    • alle Zahlungsbedingungen
  • Income::Proposition (Waren / Dienstleistungen)
    • alle Waren / Dienstleistungen
    • eine Ware / Dienstleistung
    • eine Ware / Dienstleistung erstellen
    • eine Ware / Dienstleistung aktualisieren
    • eine Ware / Dienstleistung löschen
    • eine Ware / Dienstleistung archivieren
    • eine Ware / Dienstleistung unarchivieren
  • Info
  • Project::Project (Projekt)
    • alle Projekte
    • ein Projekt
    • erstelle ein Projekt
    • aktualisiere ein Projekt
    • lösche ein Projekt
    • archiviere ein Projekt
    • unarchiviere ein Projekt
  • Tracker::Task (Aufgabe)
    • alle Aufgaben
    • eine Aufgabe
    • erstelle eine Aufgabe
    • aktualisiere eine Aufgabe
    • lösche eine Aufgabe
    • archiviere eine Aufgabe
    • unarchiviere eine Aufgabe
  • Tracker::TimeEntry (Zeiteintrag)
    • alle Zeiteinträge
    • einen Zeiteintrag
    • erstelle einen Zeiteintrag
    • aktualisiere einen Zeiteintrag
    • lösche einen Zeiteintrag
    • archiviere einen Zeiteintrag
    • unarchiviere einen Zeiteintrag
  • Verbleibendes Quota
• Business Intelligence
  • Business::Intelligence (BI) ExpenseByCategory (Ausgaben nach Kategorie)
    • alle Ausgaben eines Monats nach Kategorie
    • alle Ausgaben eines Monats nach Kategorie gefiltert nach Steuersatz
• Helpers
  • Generiere ein PDF aus Response
• Development / Mitentwickeln
  • Localhost 3000! 🤫
• Contributing
• Releasing
• License

Install the gem and add to the application's Gemfile by executing:

$ bundle add papierkram_api_client

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install papierkram_api_client

1. Repository klonen
2. bundle install
3. bin/console

# client instanziieren

# wenn ENV gesetzt sind (siehe Readme)
client = PapierkramApi::Client.new

# ODER per Variablen
client = PapierkramApi::Client.new('subdomain', "YOUR-API-KEY");

# info Endpunkt abfragen
info_details = client.info.details
puts info_details.headers
puts info_details.body

# erste Seite von "allen Rechnungen" abfragen
invoices = client.income_invoices.all(page: 1, page_size: 5)
puts invoices.headers
puts invoices.body

Der API Client ist die Hauptklasse für die Kommunikation mit der Papierkram API. Er wird mit den Zugangsdaten initialisiert.

Client

Wenn du etwas hinter die Kulissen sehen willst, schau dir diese Faraday Klasse an Faraday::Response.

Entweder werden die Zugangsdaten als Argumente übergeben:

# usage with subdomain and api key
client = PapierkramApi::Client.new('subdomain', "SUPER-LONG-API-KEY")

Oder es werden die Umgebungsvariablen PAPIERKRAM_API_SUBDOMAIN und PAPIERKRAM_API_KEY gesetzt und der Client ohne Argumente initialisiert.

Ich kann dir wärmstes https://direnv.net/ empfehlen, um die Umgebungsvariablen zu setzen. 🤓

# usage with environment variables
client = PapierkramApi::Client.new

Der Endpunkt /papierkram_api/v1/endpoints/banking/bank_connections liefert Informationen über die Bankverbindungen. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe BankConnections für mögliche Parameter.

bank_connections = client.banking_bank_connections.all
puts bank_connections.headers
puts bank_connections.body

# body
{
  "type"=>"list",
  "page"=>1,
  "page_size"=>100,
  "total_pages"=>1,
  "total_entries"=>1,
  "has_more"=>false,
  "entries"=>[
    { "type"=>"bank_connection",
      "id"=>4,
      "name"=>"Standard" }
  ]
}

bank_connection = client.banking_bank_connections.find_by(id: 1)
puts bank_connection.headers
puts bank_connection.body

# body
{
  "type"=>"bank_connection",
  "id"=>4,
  "name"=>"Standard",
  "account_no"=>nil,
  "account_type"=>"default",
  "bic"=>nil,
  "blz"=>nil,
  "connection_type"=>"default",
  "created_at"=>"2019-12-31T13:29:19.000+01:00",
  "customer_id"=>nil,
  "hbci"=>nil,
  "hbci_host_url"=>nil,
  "hbci_version"=>nil,
  "primary"=>nil,
  "title"=>"Standard",
  "updated_at"=>"2020-11-03T10:31:56.000+01:00",
  "user_id"=>nil,
  "iban"=>""
}

Der Endpunkt /papierkram_api/v1/endpoints/banking/transactions liefert Informationen über die Kontoumsätze. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Transactions für mögliche Parameter.

bank_connection_id = 4
transactions = client.banking_transactions.all(bank_connection_id: bank_connection_id,
                                               page: 1,
                                               page_size: 2)
puts transactions.headers
puts transactions.body

transactions = client.banking_transactions.find_by(id: bank_connection_id)
puts transactions.headers
puts transactions.body

Der Endpunkt /papierkram_api/v1/endpoints/contact/companies liefert Informationen über die Unternehmen. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Companies für mögliche Parameter.

companies = client.contact_companies.all
puts companies.headers
puts companies.body

company = client.contact_companies.find_by(id: 1)
puts company.headers
puts company.body

# supplier
company = client.contact_companies.create_supplier(name: 'Test GmbH')
puts company.headers
puts company.body

# customer
company = client.contact_companies.create_customer(name: 'Test GmbH')
puts company.headers
puts company.body

Siehe Companies#create_customer und Companies#create_supplier für mögliche Parameter.

company = client.contact_companies.update_by(
  id: 1,
  name: 'Test GmbH'
)
puts company.headers
puts company.body

company = client.contact_companies.delete_by(id: 1)
puts company.headers
puts company.body

company = client.contact_companies.archive_by(id: 1)
puts company.headers
puts company.body

company = client.contact_companies.unarchive_by(id: 1)
puts company.headers
puts company.body

Der Endpunkt /papierkram_api/v1/endpoints/contact/companies/{company_id} liefert Informationen über die Kontaktpersonen. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe CompaniesPersons für mögliche Parameter.

companies = client.contact_companies_persons.all(company_id: 1)
puts companies.headers
puts companies.body

company = client.contact_companies_persons.find_by(company_id: 1, id: 1)
puts company.headers
puts company.body

company = client.contact_companies_persons.create(
  company_id: 1,
  first_name: 'Max',
  last_name: 'Mustermann'
)
puts company.headers
puts company.body

Siehe CompaniesPersons#create für mögliche Parameter.

company = client.contact_companies_persons.update_by(
  id: 1,
  company_id: 1,
  first_name: 'Moritz'
)
puts company.headers
puts company.body

Siehe CompaniesPersons#update_by für mögliche Parameter.

company = client.contact_companies_persons.delete_by(company_id: 1, id: 1)
puts company.headers
puts company.body

Der Endpunkt /papierkram_api/v1/endpoints/expense/vouchers liefert Informationen über die Ausgabe Belege. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Vouchers für mögliche Parameter.

vouchers = client.expense_vouchers.all
puts vouchers.headers
puts vouchers.body

voucher = client.expense_vouchers.find_by(id: 1)
puts voucher.headers
puts voucher.body

voucher = client.expense_vouchers.find_by(id: 1, pdf: true)
puts PapierkramApi::V1::Helpers::PdfFromResponse.new(voucher).to_pdf
# => {response: Faraday::Response, path_to_pdf_file: 'path/to/tempfile_pdf.pdf'}

Siehe Vouchers#create für mögliche Parameter.

voucher = client.expense_vouchers.create(
  name: "Restaurant visit",
  due_date: "2020-06-30",
  document_date: "2020-06-14",
  description: "Took customer for dinner.",
  entertainment_reason: "sales meeting",
  flagged: true,
  provenance: "domestic",
  entertainment_persons: [
    "Carl Customer"
  ],
  creditor_id: 85,
  line_items: [
    {
      amount: 150.8,
      name: "restaurant bill",
      vat_rate: 0.19,
      category: "Bewirtungskosten"
    },
    {
      amount: 15,
      name: "tip",
      vat_rate: 0.19,
      category: "Bewirtungskosten"
    }
  ]
)

Siehe Vouchers#update_by für mögliche Parameter.

voucher = client.expense_vouchers.update_by(
  id: 1,
  document_date: "2020-06-13",
  creditor_id: 102,
  line_items: [
    {
      amount: 170.8,
      name: "restaurant bill",
      vat_rate: 0.19,
      category: "Bewirtungskosten",
      billing: null,
      depreciation: null
    },
    {
      amount: 15,
      name: "tip",
      vat_rate: 0.19,
      category: "Bewirtungskosten"
    }
  ]
)

voucher = client.expense_vouchers.delete_by(id: 1)

voucher = client.expense_vouchers.archive_by(id: 1)

voucher = client.expense_vouchers.unarchive_by(id: 1)

voucher = client.expense_vouchers.cancel_by(id: 1)

voucher = client.expense_vouchers.cancel_with_reverse_entry_by(id: 1)

Siehe Vouchers#mark_as_paid_by für mögliche Parameter.

voucher = client.expense_vouchers.mark_as_paid_by(
  id: 1,
  value: 119.0
)

Siehe Vouchers#add_document_by für mögliche Parameter.

Um ein PDF hinzuzufügen:

voucher = client.expense_vouchers.add_document_by(
  id: 1,
  path_to_file: 'path/to/file.pdf',
  file_type: 'application/pdf'
)

oder mit einem Bild im jpeg Format

voucher = client.expense_vouchers.add_document_by(
  id: 1,
  path_to_file: 'path/to/file.jpeg',
  file_type: 'image/jpeg'
)

voucher = client.expense_vouchers.delete_document_by(
  id: 1,
  document_id: 1
)

Der Endpunkt /papierkram_api/v1/endpoints/income/estimates liefert Informationen über die Angebote. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Estimates für mögliche Parameter.

estimates = client.income_estimates.all
puts estimates.headers
puts estimates.body

estimate = client.income_estimates.find_by(id: 1)
puts estimate.headers
puts estimate.body

estimate = client.income_estimates.find_by(id: 1, pdf: true)
puts PapierkramApi::V1::Helpers::PdfFromResponse.new(estimate).to_pdf
# => {response: Faraday::Response, path_to_pdf_file: 'path/to/tempfile_pdf.pdf'}

Der Endpunkt /papierkram_api/v1/endpoints/income/invoices liefert Informationen über die Rechnungen. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Invoices für mögliche Parameter.

invoices = client.income_invoices.all
puts invoices.headers
puts invoices.body

invoice = client.income_invoices.find_by(id: 1)
puts invoice.headers
puts invoice.body

invoice = client.income_invoices.find_by(id: 1, pdf: true)
puts PapierkramApi::V1::Helpers::PdfFromResponse.new(invoice).to_pdf
# => {response: Faraday::Response, path_to_pdf_file: 'path/to/tempfile_pdf.pdf'}

Siehe Invoices#create für mögliche Parameter.

invoice = client.income_invoices.create(
  name: 'Neuausstattung des Büros',
  supply_date: '01.01.2024 - 14.01.2024',
  document_date: '2024-01-15',
  payment_term_id: 46,
  customer_id: 3,
  project_id: 15,
  line_items: [
    {
      name: 'Anlieferung',
      description: 'Anlieferung der neuen Möbel',
      quantity: 1.25,
      unit: 'Stunden',
      vat_rate: 0.19,
      price: 100
    },
    {
      name: 'Bestuhlung',
      description: 'Bestuhlung des Bürogebäudes',
      quantity: 1.25,
      unit: 'Arbeitstage',
      vat_rate: 0.19,
      price: 800
    },
    {
      name: 'Büroartikel',
      description: 'Neue Bürostühle',
      quantity: 200,
      unit: 'Stühle',
      vat_rate: 0.19,
      price: 125
    }
  ]
)

Siehe Invoices#update_by für mögliche Parameter.

response = client.income_invoices.update_by(
  id: 9,
  name: 'Neuausstattung eines Büros',
  line_items: [
    {
      name: 'Anlieferung',
      description: 'Anlieferung der neuen Möbel',
      quantity: 1.5,
      unit: 'Stunden',
      vat_rate: 0.19,
      price: 100
    },
    {
      name: 'Bestuhlung',
      description: 'Bestuhlung des Bürogebäudes',
      quantity: 1.5,
      unit: 'Arbeitstage',
      vat_rate: 0.19,
      price: 800
    },
    {
      name: 'Büroartikel',
      description: 'Neue Bürostühle',
      quantity: 200,
      unit: 'Stühle',
      vat_rate: 0.19,
      price: 125
    }
  ]
)

Siehe Invoices#delete_by für mögliche Parameter.

invoice = client.income_invoices.delete_by(id: 1)

Siehe Invoices#archive_by für mögliche Parameter.

invoice = client.income_invoices.archive_by(id: 1)

Siehe Invoices#unarchive_by für mögliche Parameter.

invoice = client.income_invoices.unarchive_by(id: 1)

Siehe Invoices#cancel_by für mögliche Parameter.

invoice = client.income_invoices.cancel_by(id: 1)

Siehe Invoices#send_by für mögliche Parameter.

Per E-Mail:

invoice = client.income_invoices.deliver_by(
  id: 1,
  send_via: 'email',
  email_recipient: "test@test.test",
  email_subject: "Ich verkaufe was du brauchst",
  email_body: "Sag einfach was du brauchst und ich verkaufe es dir.",
)

Per PDF:

invoice = client.income_invoices.deliver_by(
  id: 1,
  send_via: 'pdf'
)

Der Endpunkt /papierkram_api/v1/endpoints/income/payment_terms liefert Informationen über die Zahlungsbedingungen. Die Informationen werden als Faraday::Response zurückgegeben.

payment_term = client.income_payment_terms.find_by(id: 1)
puts payment_term.headers
puts payment_term.body

Siehe PaymentTerms für mögliche Parameter.

payment_terms = client.income_payment_terms.all
puts payment_terms.headers
puts payment_terms.body

Der Endpunkt /papierkram_api/v1/endpoints/income/propositions liefert Informationen über die Waren / Dienstleistungen. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Propositions für mögliche Parameter.

propositions = client.income_propositions.all
puts propositions.headers
puts propositions.body

proposition = client.income_propositions.find_by(id: 1)
puts proposition.headers
puts proposition.body

proposition = client.income_propositions.create(
  name: 'Software design',
  article_no: '12345',
  description: 'Here, we can describe what "Software design" actually entails.',
  time_unit: 'hour',
  proposition_type: 'service',
  price: '150.0',
  vat_rate: 0.19
)
puts proposition.headers
puts proposition.body

Siehe Propositions#create für mögliche Parameter.

client.income_propositions.update_by(
  id: 1,
  name: 'Software design',
  vat_rate: 0.19 # verpflichtend bei Änderung
)

Siehe Propositions#update_by für mögliche Parameter.

client.income_propositions.delete_by(id: 1)

client.income_propositions.archive_by(id: 1)

client.income_propositions.unarchive_by(id: 1)

Der Endpunkt lib/papierkram_api/v1/endpoints/info.rb liefert Informationen über die API. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Info.

info = client.info.details
puts info.headers
puts info.body

Der Endpunkt /papierkram_api/v1/endpoints/projects liefert Informationen über die Projekte. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Projects für mögliche Parameter.

projects = client.projects.all
puts projects.headers
puts projects.body

project = client.projects.find_by(id: 1)
puts project.headers
puts project.body

project = client.projects.create(name: 'Projekt 1')
puts project.headers
puts project.body

Siehe Projects für mögliche Parameter.

project = client.projects.update_by(
  id: 1,
  name: 'Projekt 2'
)
puts project.headers
puts project.body

Siehe Projects für mögliche Parameter.

project = client.projects.delete_by(id: 1)
puts project.headers
puts project.body

project = client.projects.archive_by(id: 1)
puts project.headers
puts project.body

project = client.projects.unarchive_by(id: 1)
puts project.headers
puts project.body

Der Endpunkt /papierkram_api/v1/tracker/tasks liefert Informationen über die Aufgaben. Die Informationen werden als Faraday::Response zurückgegeben.

Siehe Tasks für mögliche Parameter.

tasks = client.tracker_tasks.all
puts tasks.headers
puts tasks.body

task = client.tracker_tasks.find_by(id: 1)
puts task.headers
puts task.body

Siehe Tasks#create für mögliche Parameter.

task = client.tracker_tasks.create(name: 'Aufgabe 1')
puts task.headers
puts task.body

Siehe Tasks#update_by für mögliche Parameter.

task = client.tracker_tasks.update_by(id: 1, name: 'Aufgabe 2' )
puts task.headers
puts task.body

task = client.tracker_tasks.delete_by(id: 1)
puts task.headers
puts task.body

task = client.tracker_tasks.archive_by(id: 1)
puts task.headers
puts task.body

task = client.tracker_tasks.unarchive_by(id: 1)
puts task.headers
puts task.body

Der Endpunkt /papierkram_api/v1/tracker/time_entries liefert Informationen über die Zeiteinträge. Die Informationen werden als Faraday::Response zurückgegeben.

TimeEntries

Siehe TimeEntries für mögliche Parameter.

time_entries = client.tracker_time_entries.all
puts time_entries.headers
puts time_entries.body

time_entry = client.tracker_time_entries.find_by(id: 1)
puts time_entry.headers
puts time_entry.body

Siehe TimeEntries für mögliche Parameter.

time_entry = client.tracker_time_entries.create(
  task_id: 1,
  date: '2020-01-01',
  duration: 60,
  description: 'Test'
)
puts time_entry.headers
puts time_entry.body

Siehe TimeEntries für mögliche Parameter.

time_entry = client.tracker_time_entries.update_by(
  id: 1,
 comments: 'Test'
)
puts time_entry.headers
puts time_entry.body

time_entry = client.tracker_time_entries.delete_by(id: 1)
puts time_entry.headers
puts time_entry.body

time_entry = client.tracker_time_entries.archive_by(id: 1)
puts time_entry.headers
puts time_entry.body

time_entry = client.tracker_time_entries.unarchive_by(id: 1)
puts time_entry.headers
puts time_entry.body

Jede API Anfrage "kostet" 1 Quota. Das Quota wird bei jedem Request aktualisiert. Um das verbleibende Quota zu erhalten, kann die Methode remaining_quota aufgerufen werden.

Base

Du kannst dein Quota über die Papierkram Webseite einsehen. Die Anzahl der verbleibenden Anfragen wird dir dort angezeigt.

Oder nach jeder Anfrage per Client:

# `client.info` ist nur eine Möglichkeit, es kann jeder andere Endpoint verwendet werden ✌️
response = client.info.details
quota = client.info.remaining_quota(response)

DEPRECATED Bitte verwende dieses Modul nicht mehr, es wird in Zukunft entfernt werden.

Ich lasse diesen ersten Ausflug in Auswertungen erstmal hier im Gem. Aber sollte ich die Zeit finden und weitere KPIs wichtig finden, dann gehören die Auswertungen eigentlich in ein eigenes Package.

TODO ergänzen wie man SmartQueries erstellt und verwendet.
TODO ergänzen wie man SmartQueries funktioneren.
TODO ergänzen wie die Rückgabewerte von SmartQueries gestaltet werden sollten.

DEPRECATED Bitte verwende dieses Modul nicht mehr, es wird in Zukunft entfernt werden.

Der Endpunkt /papierkram_api/v1/business_intelligence/expense_by_categories liefert Informationen über die Ausgaben nach Kategorie. Die Informationen werden als Hash zurückgegeben.

client = PapierkramApi::Client.new
expense_voucher_data_service = client.expense_vouchers.data_service(:for_month_in_year_service)
expense_vouchers_in_date_range = expense_voucher_data_service.for_month_in_year(year: 2020, month: 8)

service = client.business_intelligence.expenses_by_category
result = service.call(expense_vouchers: expense_vouchers_in_date_range)
puts result

{"Betriebsbedarf"=>
  {"amount"=>476.0,
   "amount_by_creditor"=>{nil=>476.0},
   "line_items"=>
    [{"name"=>"2020-01-03",
      "amount"=>119.0,
      "category"=>"Betriebsbedarf",
      "vat_rate"=>"19%",
      "billing"=>nil,
      "depreciation"=>nil,
      "voucher_name"=>"B-00214 - 2020-08-01",
      "voucher_id"=>641,
      "creditor"=>nil},
     {"name"=>"2020-01-03",
      "amount"=>119.0,
      "category"=>"Betriebsbedarf",
      "vat_rate"=>"19%",
      "billing"=>nil,
      "depreciation"=>nil,
      "voucher_name"=>"B-00215 - 2020-08-02",
      "voucher_id"=>644,
      "creditor"=>nil},
     {"name"=>"2020-01-03",
      "amount"=>119.0,
      "category"=>"Betriebsbedarf",
      "vat_rate"=>"19%",
      "billing"=>nil,
      "depreciation"=>nil,
      "voucher_name"=>"B-00216 - 2020-08-03",
      "voucher_id"=>647,
      "creditor"=>nil},
     {"name"=>"2020-01-03",
      "amount"=>119.0,
      "category"=>"Betriebsbedarf",
      "vat_rate"=>"19%",
      "billing"=>nil,
      "depreciation"=>nil,
      "voucher_name"=>"B-00217 - 2020-08-04",
      "voucher_id"=>650,
      "creditor"=>nil}]}}

client = PapierkramApi::Client.new
expense_voucher_data_service = client.expense_vouchers.data_service(:for_month_in_year_service)
expense_vouchers_in_date_range = expense_voucher_data_service.for_month_in_year(year: 2020, month: 8)

service = client.business_intelligence.expenses_by_category
result = service.call(expense_vouchers: expense_vouchers_in_date_range) do |line_items|
  line_items.select { |v| v['vat_rate'] == '19%' }
end
puts result

Es gibt einige Helper, die dir das Leben leichter machen.

Mit dem Helper PapierkramApi::V1::Helpers::PdfFromResponse kannst du für unterstützte Endpunkte aus einer Faraday::Response ein PDF schreiben.

Unterstützte Endpunkte sind beispielsweise: Income::Estimate, Income::Invoice, Expense::Voucher.

Api::V1::Helpers::PdfFromResponse

response = client.income_invoices.find_by(id: 1, pdf: true)
pdf = PapierkramApi::V1::Helpers::PdfFromResponse.new(response).to_pdf("Rechnung Nummer XXX")
puts pdf

# value of `pdf`
{
  response: Faraday::Response,
  path_to_pdf_file: 'path/to/temp/Rechnung Nummer XXX.pdf'
}

🇬🇧/🇺🇸

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

You need to have at least the following environment variables set to run the tests:

• MT_COMPAT=true or export MT_COMPAT=true (when in .envrc)

Please, see the .envrc.sample file for more (https://direnv.net/).

🇩🇪

Nachdem du das Repository überprüft hast, führe bin/setup aus, um Abhängigkeiten zu installieren. Anschließend führe rake test aus, um die Tests durchzuführen. Du kannst auch bin/console ausführen, um eine interaktive Konsole zu starten und Experimente durchzuführen.

Um dieses Gem auf deinem lokalen Rechner zu installieren, führe bundle exec rake install aus. Um eine neue Version zu veröffentlichen, aktualisiere die Versionsnummer in version.rb und führe dann bundle exec rake release aus. Dadurch wird ein Git-Tag für die Version erstellt, Git-Commits und das erstellte Tag werden gepusht, und die .gem-Datei wird nach rubygems.org gepusht.

Um die Tests auszuführen, muss die Umgebungsvariable MT_COMPAT=true gesetzt sein.

Bitte, schaue in die Datei .envrc.sample für mehr Details (https://direnv.net/).

Es gibt Menschen da draußen, die können gegen direkt gegen die Papierkram API entwickeln. 🤯
Und wie das geht, verrate ich hier allen Lesern! 🤫

DEBUG_LOCALHOST=true bin/console

siehe: test/test_api_v1_client.rb

OR to make it stick:

• Set export DEBUG_LOCALHOST=true in your .env or .envrc file.
• Enjoy the magic: bin/setup && bin/console 🎉

Bug reports and pull requests are welcome on GitHub at https://github.com/simonneutert/papierkram_api_client.

Bitte achte darauf, dass du die Tests ausführst und die Tests dann auch grün sind 🤓

🚨 SEHR WICHTIG! Dein API Key wird in den Tests verwendet werden. Bitte achte darauf, dass du den API Key nicht in deinen Commits hast! Wenn du per Environment Variable arbeitest, dann wird dein API Key nicht von VCR aufgezeichnet. Das bedeutet, dass du deine Tests nicht mit deinem API Key ausführen solltest. ⚠️

🚨 NOCH WICHTIGER! deine Kundendaten, also Klarnamen, E-Mails und Telefonnummern haben hier nichts verloren! Bitte sorge dafür, dass du deine Tests mit einem Testaccount ausführst. 🙏 ODER editiere deine Kundendaten in den VCR Cassettes nach dem Test. 🙏

Wenn du unsicher bist, sprich mich an oder erstelle ein Issue. Ich helfe dir gerne weiter. 🤗

1. checkout main
2. close the changelog
3. Set the correct/desired version number in version.rb and run bundle install just for sure
4. commit changes if needed
5. bundle exec rake release

After a successful release, the gem is pushed to rubygems.org.

Here are the steps you need to take after a successful release:

1. edit lib/papierkram_api_client/version.rb and bump the version number to the next patch version
2. run bundle install
3. open the changelog again
4. commit and push the changes

The gem is available as open source under the terms of the MIT License.