https://github.com/orlo/example-crm-integration
https://github.com/orlo/example-crm-integration
crm example php
Last synced: 7 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/orlo/example-crm-integration
- Owner: orlo
- Created: 2016-09-02T11:10:08.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-11-07T09:24:13.000Z (about 3 years ago)
- Last Synced: 2025-02-07T15:45:01.700Z (12 months ago)
- Topics: crm, example, php
- Language: PHP
- Size: 104 KB
- Stars: 0
- Watchers: 9
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Example CRM Integration
This project aims to illustrate the functionality required for a custom CRM to integrate with SocialSignIn.
## SocialSignIn Configuration
Within the SocialSignIn application, head to https://app.socialsignin.net/#/settings/inbox and add a Custom CRM integration.
* Name - something of your choosing
* Search Endpoint URL - https://myserver.example.com/search
* Search Endpoint Secret - LongStringlyThingOfYourChoosing (aka SECRET)
* Iframe Endpoint URL - https://myserver.example.com/iframe
* Iframe Endpoint Secret - LongStringlyThingOfYourChoosing (aka SECRET)
( For this integration, the Search and Iframe Endpoint Secrets need to be the same, replace 'myserver.example.com' with a real hostname you have assigned to your deployment of this code ).
### SocialSignIn Secret
When SocialSignIn make requests on your integration, the requests are signed with a shared secret (SECRET) which you can check against, to ensure a third party isn't trying to access your pipedrive data.
You define this secret when adding the CRM integration within SocialSignIn. It can be a string of any length (although as with all passwords, longer is generally better).
## Sample Integration Installation
```bash
docker build -t crm-integration-image .
docker run -e SECRET=changeme --rm --name crm-integration crm-integration-image
```
Code should work on a generic-ish PHP 7.1 Linux server if you wish to deploy it manually. Sufficient setup instructions should be within the ```Dockerfile```.
It requires a SECRET environment variable to be set.
## Configuration
The SECRET environment variable is used to verify that SocialSignIn made the CRM request, and for SocialSignIn to verify responses.
The signing works by adding a sha256 hash\_hmac query parameter on all requests (see: http://php.net/hash\_hmac )
You can choose to ignore this parameter if you so wish.
## Required HTTP Interface
Any third party / custom integration needs to support the following :
## Search
* GET request, with signed parameters (see SECRET above)
* Endpoint is specified by you when adding the integration
* Parameter 'q' contains the search string.
* Return json (application/json mimetype).
* e.g. https://my.integration.com/search?q=bob
### Request
Assuming a shared secret of 'changeme!'
A request from SocialSignIn searching for users matching 'red' might look like :
```raw
GET $CustomUrl?q=red&expires=1500472622&sig=7c9a0a55dc2d1542ec736b8021f048da114fcba11ca1fb0219c122dfd789e48c HTTP/1.1
Host: ....
Accept: application/json
```
Where :
* expires - unix timestamp with a small TTL value added.
* sig - sha256 hash of GET query (q=red&expires=12345678)
* q - search term
#### Example request validation
You **should** check that the expires value in the URL is greater or equal to your current system timestamp.
You **should** check that the signature is valid.
```php
$our_timestamp = time();
// ... logic to check existance of expires/sig parameters in query string.
$url = parse_str($_SERVER['QUERY_STRING'], $params);
$actual_sig = $params['sig'];
$request_time = $params['expires'];
if($request_time < $our_timestamp) {
// request from too long ago?
}
unset($params['sig']);
// hash_hmac('sha256', 'q=red&expires=1500472622', 'changeme!');
$expected_sig = hash_hmac('sha256', http_build_query($params) , 'changeme!');
if($expected_sig != $actual_sig) {
// handle error
}
```
### Response
```json
{
"results" : [
{ "id": 1, "name": "Susan Red"} ,
{ "id": 4, "name": "Frank Redford"}
]
}
```
## Get Specific User
* GET request, with signed parameters
* Endpoint is specified by you when adding the integration
* Returns HTML (iframe content).
### Request
```raw
GET $CustomUrl/iframe?id=12345&expires=1234567&sig=hashhashhash HTTP/1.1
Host: .....
```
* You **should** verify the 'sig' URL parameter is correct (see above)
* You **should** verify the 'expires' URL parameter is greater or equal to the current system time.
### Response
HTML to render the user, as determined by your internal requirements.
For example :
````html
Some user
Fred Bloggs
Fred crm
Email: test@example.com
Sales (2017): £390.46
Sales (2016): £39.42
Notes
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce magna magna, convallis quis auctor bibendum, rutrum ut risus. Nulla dictum pulvinar turpis id sodales. Maecenas gravida quam nibh, accumsan egestas nisl mattis ut.
````
This is rendered as an iframe within the SSI webapp.