amocrm

README

Go Package for amoCRM API

This package provides a Golang client for amoCRM API.

Disclaimer

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by amoCRM or any of its affiliates or subsidiaries. This is an independent and unofficial API client. Use at your own risk.

Installation

go get -u github.com/alexeykhan/amocrm

Quick Start

Step №1: Redirect user to the authorization page.

User grants access to their account and is redirected back with referer and code GET-parameters attached.

package main

import (
    "fmt"

    "github.com/alexeykhan/amocrm"
)

func main() {
    amoCRM := amocrm.New("clientID", "clientSecret", "redirectURL")
    
    state := amocrm.RandomState()  // store this state as a session identifier
    mode := amocrm.PostMessageMode // options: PostMessageMode, PopupMode
    
    authURL, err := amoCRM.AuthorizeURL(state, mode)
    if err != nil {
        fmt.Println("failed to get auth url:", err)
        return
    }
    
    fmt.Println("Redirect user to this URL:")
    fmt.Println(authURL)
}

Step №2: Exchange authorization code for token.

Use received referer and code parameters as account domain and authorization code respectively to make a handshake with amoCRM and Get a fresh set of access_token, refresh_token and token meta data.

package main

import (
    "fmt"

    "github.com/alexeykhan/amocrm"
)

func main() {
    amoCRM := amocrm.New("clientID", "clientSecret", "redirectURL")
    
    if err := amoCRM.SetDomain("example.amocrm.ru"); err != nil {
        fmt.Println("set domain:", err)
        return
    }
    
    token, err := amoCRM.TokenByCode("authorizationCode")
    if err != nil {
        fmt.Println("get token by code:", err)
        return
    }
    
    fmt.Println("access_token:", token.AccessToken())
    fmt.Println("refresh_token:", token.RefreshToken())
    fmt.Println("token_type:", token.TokenType())
    fmt.Println("expires_at:", token.ExpiresAt().Unix())
}

Step №3: Make your first API request.

Set amoCRM accounts domain and token to authorize your requests.

package main

import (
    "fmt"
    "time"

    "github.com/alexeykhan/amocrm"
)

func main() {
    amoCRM := amocrm.New("clientID", "clientSecret", "redirectURL")
    
    if err := amoCRM.SetDomain("example.amocrm.ru"); err != nil {
        fmt.Println("set domain:", err)
        return
    }
    
    token := amocrm.NewToken("accessToken", "refreshToken", "tokenType", time.Now())
    if err := amoCRM.SetToken(token); err != nil {
        fmt.Println("set token:", err)
        return
    }
    
    cfg := amocrm.AccountsConfig{
        Relations: []string{
            amocrm.WithUUID, 
            amocrm.WithVersion, 
            amocrm.WithAmojoID,
            amocrm.WithTaskTypes,
            amocrm.WithUserGroups,
            amocrm.WithAmojoRights,
            amocrm.WithDatetimeSettings,
        }, 
    }

    account, err := amoCRM.Accounts().Current(cfg)
    if err != nil {
        fmt.Println("fetch current accounts:", err)
        return
    }
    
    fmt.Println("current accounts:", account)
}

Development Status: In Progress

This package is under development so any methods, constants or types may be changed in newer versions without backward compatibility with previous ones. Use it at your own risk and feel free to fork it anytime.

---

Released under the MIT License.

Documentation

Overview

Example (GetAuthURL)

package main

import (
	"fmt"
	"time"

	"github.com/alexeykhan/amocrm"
)

var env = struct {
	clientID     string
	clientSecret string
	redirectURL  string
}{
	clientID:     "CLIENT_ID",
	clientSecret: "CLIENT_SECRET",
	redirectURL:  "REDIRECT_URI",
}

func main() {
	// Initialize amoCRM API Client.
	amoCRM := amocrm.New(env.clientID, env.clientSecret, env.redirectURL)

	// Save this random state as a session identifier to verify
	// user identity when they are redirected back with code.
	// Set required mode parameter: "post_message" or "popup".
	state := amocrm.RandomState()
	mode := amocrm.PostMessageMode

	// Redirect user to authorization URL.
	authURL, err := amoCRM.AuthorizeURL(state, mode)
	if err != nil {
		fmt.Println("Failed to Get auth url:", err)
		return
	}

	fmt.Println("Redirect user to this URL:")
	fmt.Println(authURL)
}

Example (GetCurrentAccount)

package main

import (
	"fmt"
	"time"

	"github.com/alexeykhan/amocrm"
)

var (
	env = struct {
		clientID     string
		clientSecret string
		redirectURL  string
	}{
		clientID:     "CLIENT_ID",
		clientSecret: "CLIENT_SECRET",
		redirectURL:  "REDIRECT_URI",
	}

	storage = struct {
		domain       string
		accessToken  string
		refreshToken string
		tokenType    string
		expiresAt    time.Time
	}{
		domain:       "example.amocrm.ru",
		accessToken:  "access_token",
		refreshToken: "refresh_token",
		tokenType:    "bearer",
		expiresAt:    time.Now(),
	}
)

func main() {
	// Initialize amoCRM API Client.
	amoCRM := amocrm.New(env.clientID, env.clientSecret, env.redirectURL)

	// Retrieve domain from storage.
	if err := amoCRM.SetDomain(storage.domain); err != nil {
		fmt.Println("set domain:", err)
		return
	}

	// Retrieve token from storage.
	token := amocrm.NewToken(storage.accessToken, storage.refreshToken, storage.tokenType, storage.expiresAt)
	if err := amoCRM.SetToken(token); err != nil {
		fmt.Println("set token:", err)
		return
	}

	// Set up accounts request config.
	cfg := amocrm.AccountsConfig{
		Relations: []string{
			amocrm.WithUUID,
			amocrm.WithVersion,
			amocrm.WithAmojoID,
			amocrm.WithTaskTypes,
			amocrm.WithUserGroups,
			amocrm.WithAmojoRights,
			amocrm.WithDatetimeSettings,
		},
	}

	// Fetch current accounts with AccountsRepository.
	account, err := amoCRM.Accounts().Current(cfg)
	if err != nil {
		fmt.Println("fetch current accounts:", err)
		return
	}

	fmt.Println("current accounts:", account)
}

Example (GetTokenByCode)

package main

import (
	"fmt"
	"time"

	"github.com/alexeykhan/amocrm"
)

var env = struct {
	clientID     string
	clientSecret string
	redirectURL  string
}{
	clientID:     "CLIENT_ID",
	clientSecret: "CLIENT_SECRET",
	redirectURL:  "REDIRECT_URI",
}

func main() {
	// Initialize amoCRM API Client.
	amoCRM := amocrm.New(env.clientID, env.clientSecret, env.redirectURL)

	// Use the accounts domain and authorization code that are
	// pushed to the redirect URL as "referer" and "code GET
	// parameters respectively. AccessTokenByCode will do the
	// handshake to retrieve tokens.
	domain := "example.amocrm.ru"
	authCode := "def502000ba3e1724cac79...92146f93b70fd4ca31"

	// Set amoCRM API accounts domain.
	if err := amoCRM.SetDomain(domain); err != nil {
		fmt.Println("set domain:", err)
		return
	}

	// Exchange authorization code for token.
	token, err := amoCRM.TokenByCode(authCode)
	if err != nil {
		fmt.Println("Get token by code:", err)
		return
	}

	// Store received token.
	fmt.Println("access_token:", token.AccessToken())
	fmt.Println("refresh_token:", token.RefreshToken())
	fmt.Println("token_type:", token.TokenType())
	fmt.Println("expires_at:", token.ExpiresAt().Unix())
}

Index

• Constants
• func RandomState() string
• type Account
• type Accounts
• type AccountsConfig
• type Client
  • func New(clientID, clientSecret, redirectURL string) Client
• type GrantType
• type Token
  • func NewToken(accessToken, refreshToken, tokenType string, expiresAt time.Time) Token

Examples

• Package (GetAuthURL)
• Package (GetCurrentAccount)
• Package (GetTokenByCode)

Constants

const (
	PostMessageMode = "post_message"
	PopupMode       = "popup"
)

PostMessageMode and PopupMode are the only options for amoCRM OAuth2.0 "mode" request parameter.

const (
	WithUUID             = "uuid"
	WithVersion          = "version"
	WithAmojoID          = "amojo_id"
	WithTaskTypes        = "task_types"
	WithUserGroups       = "users_groups"
	WithAmojoRights      = "amojo_rights"
	WithDatetimeSettings = "datetime_settings"
)

Account relations.

Functions

func RandomState

func RandomState() string

RandomState generates a new random state.

Types

type Account

type Account struct {
	ID                      int    `json:"id"`
	Name                    string `json:"name"`
	Subdomain               string `json:"subdomain"`
	CreatedAt               int    `json:"created_at"`
	CreatedBy               int    `json:"created_by"`
	UpdatedAt               int    `json:"updated_at"`
	UpdatedBy               int    `json:"updated_by"`
	CurrentUserID           int    `json:"current_user_id"`
	Country                 string `json:"country"`
	Currency                string `json:"currency"`
	CustomersMode           string `json:"customers_mode"`
	IsUnsortedOn            bool   `json:"is_unsorted_on"`
	MobileFeatureVersion    int    `json:"mobile_feature_version"`
	IsLossReasonEnabled     bool   `json:"is_loss_reason_enabled"`
	IsHelpbotEnabled        bool   `json:"is_helpbot_enabled"`
	IsTechnicalAccount      bool   `json:"is_technical_account"`
	ContactNameDisplayOrder int    `json:"contact_name_display_order"`
	AmojoID                 string `json:"amojo_id"`
	UUID                    string `json:"uuid"`
	Version                 int    `json:"version"`
	Links                   struct {
		Self struct {
			Href string `json:"href"`
		} `json:"self"`
	} `json:"_links"`
	Embedded struct {
		AmojoRights struct {
			CanDirect       bool `json:"can_direct"`
			CanCreateGroups bool `json:"can_create_groups"`
		} `json:"amojo_rights"`
		UsersGroups []struct {
			ID   int         `json:"id"`
			Name string      `json:"name"`
			UUID interface{} `json:"uuid"`
		} `json:"users_groups"`
		TaskTypes []struct {
			ID     int         `json:"id"`
			Name   string      `json:"name"`
			Color  interface{} `json:"color"`
			IconID interface{} `json:"icon_id"`
			Code   string      `json:"code"`
		} `json:"task_types"`
		DatetimeSettings struct {
			DatePattern      string `json:"date_pattern"`
			ShortDatePattern string `json:"short_date_pattern"`
			ShortTimePattern string `json:"short_time_pattern"`
			DateFormat       string `json:"date_format"`
			TimeFormat       string `json:"time_format"`
			Timezone         string `json:"timezone"`
			TimezoneOffset   string `json:"timezone_offset"`
		} `json:"datetime_settings"`
	} `json:"_embedded"`
}

Account represents amoCRM Account entity json DTO.

type Accounts

type Accounts interface {
	Current(cfg AccountsConfig) (*Account, error)
}

Accounts describes methods available for Accounts entity.

type AccountsConfig

type AccountsConfig struct {
	Relations []string
}

Use AccountsConfig to set account parameters.

type Client

type Client interface {
	AuthorizeURL(state, mode string) (*url.URL, error)
	TokenByCode(code string) (Token, error)
	SetToken(token Token) error
	SetDomain(domain string) error
	Accounts() Accounts
}

Provider is a wrapper for authorization and making requests.

func New

func New(clientID, clientSecret, redirectURL string) Client

New allocates and returns a new amoCRM API Client.

type GrantType

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

type Token

type Token interface {
	AccessToken() string
	RefreshToken() string
	ExpiresAt() time.Time
	TokenType() string
	Expired() bool
}

GetToken stores a set of GetToken, RefreshToken and meta data.

func NewToken

func NewToken(accessToken, refreshToken, tokenType string, expiresAt time.Time) Token

NewToken allocates and returns a new TokenSource.