lexoffice

README

lexoffice Go API

This module implements a Go REST client for the public API from lexoffice. With the help of the API one can work with entities from the cloud-based accounting software.

Setup

To work with the lexoffice API, you need to setup a lexoffice test instance and get an API key.
Thankfully these steps can be done online (without credit card) in some minutes.

To get the test instance (provided 30 days free of charge by lexoffice), just hit https://www.lexoffice.de and create your test-account. You have to verify your email address and setup your password on first login.

After you have successfully logged in, just go to https://app.lexoffice.de/settings/#/public-api to create your API key, attached to your instance and valid for 24 months.

You can find the vendor explanation for this in the cookbook.

This module needs this API key to connect. You'll provide the API key as an environment variable or in an .env file (you can also hard-code it in your project if you dare).

To export the API key in an environment variable, just define it, e.g.

~ export LEXOFFICE_API_KEY=########-####-####-####-############

Alternatively, To create the .env file, just run:

~ echo "LEXOFFICE_API_KEY=########-####-####-####-############" > .env

You can check the file content with:

~ cat .env
LEXOFFICE_API_KEY=########-####-####-####-############

Of course you can provide the API key in every command, also, eg.:

LEXOFFICE_API_KEY=########-####-####-####-############ go test -v -tags=integration

Install module

go get -u github.com/wolfgang-werner/lexoffice-go-api

Usage

import "github.com/wolfgang-werner/lexoffice-go-api"

// Replace API_KEY with your real key
client := lexoffice.NewClient("API_KEY")

// enable debug output
client.debug = true

Testing

Run integration tests with real API Key.

LEXOFFICE_API_KEY=########-####-####-####-############ go test -v -tags=integration

Links

The following resources have been very helpful in writing this module.

• lexoffice API Documentation and Getting Started

• Helpful advice from Alex Pliutau - thank you Alex! - good read Writing REST API Client in Go
  and the corresponding GitHub repository facest / factest-go

• JSON-to-Go, a cool online tool to convert JSON to Go type definition

• Some in-deep knowledge - how to deal with dynamic JSON structures in Go.
  Good starting points are Go JSON Cookbook and Representing JSON structures in Go, both from Eli Bendersky and Dynamic JSON in Go from Tommi Virtanen

Documentation

Index

• type Address
• type Addresses
• type Client
  • func NewClient(apiKey string) *Client
  • func (c *Client) CreateContact(contact *Contact) (*CreateContactResponse, error)
  • func (c *Client) GetContact(contactID string) (*Contact, error)
  • func (c *Client) LookupContacts(filters []Filter, pagination Pagination) (*LookupContactsResponse, error)
  • func (c *Client) UpdateContact(contact *Contact) (*CreateContactResponse, error)
• type Company
• type Contact
• type ContactPersons
• type CreateContactResponse
• type Customer
• type EmailAddresses
• type Filter
  • func NewFilter(k, v string) Filter
• type LookupContactsResponse
• type Pagination
• type Person
• type PhoneNumbers
• type Roles
• type Sort
• type Vendor

Types

type Address

type Address struct {
	Supplement  *string `json:"supplement"`
	Street      *string `json:"street"`
	Zip         *string `json:"zip"`
	City        *string `json:"city"`
	CountryCode string  `json:"countryCode"`
}

type Addresses

type Addresses struct {
	Billing  []Address `json:"billing"`
	Shipping []Address `json:"shipping"`
}

type Client

type Client struct {
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

func NewClient

func NewClient(apiKey string) *Client

NewClient creates new lexoffice.io client with given API key

func (*Client) CreateContact

func (c *Client) CreateContact(contact *Contact) (*CreateContactResponse, error)

CreateContact creates a new contact (person or company)

func (*Client) GetContact

func (c *Client) GetContact(contactID string) (*Contact, error)

GetContact returns contact object by ContactID

func (*Client) LookupContacts

func (c *Client) LookupContacts(filters []Filter, pagination Pagination) (*LookupContactsResponse, error)

func (*Client) UpdateContact

func (c *Client) UpdateContact(contact *Contact) (*CreateContactResponse, error)

UpdateContact creates a new contact (person or company)

type Company

type Company struct {
	Name                 string           `json:"name"`
	TaxNumber            *string          `json:"taxNumber"`
	VatRegistrationID    *string          `json:"vatRegistrationId"`
	AllowTaxFreeInvoices bool             `json:"allowTaxFreeInvoices"`
	ContactPersons       []ContactPersons `json:"contactPersons"`
}

type Contact

type Contact struct {
	ID             *string         `json:"id"`
	OrganizationID *string         `json:"organizationId"`
	Version        int             `json:"version"`
	Roles          Roles           `json:"roles"`
	Company        *Company        `json:"company"`
	Person         *Person         `json:"person"`
	Addresses      *Addresses      `json:"addresses"`
	EmailAddresses *EmailAddresses `json:"emailAddresses"`
	PhoneNumbers   *PhoneNumbers   `json:"phoneNumbers"`
	Note           *string         `json:"note"`
	Archived       bool            `json:"archived"`
}

type ContactPersons

type ContactPersons struct {
	Salutation   *string `json:"salutation"`
	FirstName    *string `json:"firstName"`
	LastName     string  `json:"lastName"`
	Primary      bool    `json:"primary"`
	EmailAddress *string `json:"emailAddress"`
	PhoneNumber  *string `json:"phoneNumber"`
}

type CreateContactResponse

type CreateContactResponse struct {
	ID          string    `json:"id"`
	ResourceURI string    `json:"resourceUri"`
	CreatedDate time.Time `json:"createdDate"`
	UpdatedDate time.Time `json:"updatedDate"`
	Version     int       `json:"version"`
}

type Customer

type Customer struct {
	Number *int `json:"number"`
}

type EmailAddresses

type EmailAddresses struct {
	Business []string `json:"business"`
	Office   []string `json:"office"`
	Private  []string `json:"private"`
	Other    []string `json:"other"`
}

type Filter

type Filter struct {
	// contains filtered or unexported fields
}

func NewFilter

func NewFilter(k, v string) Filter

NewFilter creates a new filter

type LookupContactsResponse

type LookupContactsResponse struct {
	Content          []Contact `json:"content"`
	First            bool      `json:"first"`
	Last             bool      `json:"last"`
	Number           int       `json:"number"`
	NumberOfElements int       `json:"numberOfElements"`
	Size             int       `json:"size"`
	Sort             []Sort    `json:"sort"`
	TotalElements    int       `json:"totalElements"`
	TotalPages       int       `json:"totalPages"`
}

type Pagination

type Pagination struct {
	// contains filtered or unexported fields
}

type Person

type Person struct {
	Salutation *string `json:"salutation"`
	FirstName  *string `json:"firstName"`
	LastName   string  `json:"lastName"`
}

type PhoneNumbers

type PhoneNumbers struct {
	Business []string `json:"business"`
	Office   []string `json:"office"`
	Mobile   []string `json:"mobile"`
	Private  []string `json:"private"`
	Fax      []string `json:"fax"`
	Other    []string `json:"other"`
}

type Roles

type Roles struct {
	Customer *Customer `json:"customer"`
	Vendor   *Vendor   `json:"vendor"`
}

type Sort

type Sort struct {
	Ascending    bool   `json:"ascending"`
	Direction    string `json:"direction"`
	IgnoreCase   bool   `json:"ignoreCase"`
	NullHandling string `json:"nullHandling"`
	Property     string `json:"property"`
}

type Vendor

type Vendor struct {
	Number *int `json:"number"`
}