Company API Reference

The HUMANCE Company API is organized around REST . Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.


Всі запити повинні використовувати https протокл, домен humance.io, та починатися з /company/integration/.

Наприклад https://humance.io/company/integration/orders/make

Authorization

Авторизація запитів здійснюється шляхом передачі двох HTTP заголовків "Api-Key" та "Api-Secret" .

Їх можна взяти в особистому кабінеті компанії, розділ Integration. Для цього необхідно, якщо це не було зроблено, натиснути Connect для API, після чого зʼявляться пари ключів одні тестові інші бойові(продакшн).

Endpoint: Request headers example

HEADERS
authorize your company

Api-Key: <Your api key>
Api-Secret: <Your api secret key>
X-Locale: <Locale>

Errors

Всі успішні API запити повертають код 200, у разі виникнення будь-яких помилок абощо, буде повернуто код відмінний від 200

Перелік можливих кодів помилок та їх опис. Структура відповіді у разі помилки.

HTTP STATUS CODE SUMMARY
200 OK Everything worked as expected. Do not return error object
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
402 Request Failed The parameters were valid but the request failed.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
409 Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
422 Validation error Errors of transferred parameters
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
RESPONSE
Error response object

{
    // A few words about the error
	"message": "This action is unauthorized.",

    // Error code
	"code": 40300,

    // A hint of a possible solution to the problem
	"fix": "You don't have access to the resource",

    // Errors of transferred parameters
    "params": {
		"parameter_1": [
			"Error message 1",
			"Error message 2"
		],
        "parameter_2": [
			"Error message 1",
			"Error message 2"
		],
        ...
	}
}

Make an order

Створити оплату для підримки проекту

Endpoint: /orders/make

HEADERS
authorize your company

Api-Key: <Your api key>
Api-Secret: <Your api secret key>
X-Locale: <Locale>

POST
supported formats: application/json; multipart/form-data;
copy

{
    // Required. Project id for which you want to create a payment 
    "project_id": 4,
    // Required. The amount of the payment is indicated by dot
    "amount": "100.20",
    // Required. Email of the customer
    "email": "[email protected]"
    // Name of the customer
    "name": "user"
}

RESPONSE
Status 200 OK. Payment object returned

{
    "id": 23,
    "amount": "100.00",
    "status": "done",
    "project_id": 23,
    "created_at": "23/23/422",

    // Project object
    "project": {
        "id": 23,
        "name": "Project name",
        "group_id": 10,

        // Group object
        "group": {
            "id": 10,
            "name": "Group name",
            ...
        },
    }
    "cancel_details": "some text",

    // Reason object
    "reason_id": {
        "id": 1,
        "reason": "reason name"
    }
    ...
}

Cancel an order

Скасувати оплату для підримки проекту

Endpoint: /orders/cancel

HEADERS
authorize your company

Api-Key: <Your api key>
Api-Secret: <Your api secret key>
X-Locale: <Locale>

POST
supported formats: application/json; multipart/form-data;
copy

{
    // Required. Payment id for which you want to cancel 
    "payment_id": 4,
    // Required. A brief description of why you are canceling the payment
    "cancel_description": "some text",
    // Reason id
    "cancel_reason_id": "1"
}

RESPONSE
Status 200 OK

{
    "id": 23,
    "amount": "100.00",
    "status": "done",
    "project_id": 23,
    "created_at": "23/23/422",

    // Project object
    "project": {
        "id": 23,
        "name": "Project name",
        "group_id": 10,

        // Group object
        "group": {
            "id": 10,
            "name": "Group name",
            ...
        },
    }
    "cancel_details": "some text",

    // Reason object
    "reason_id": {
        "id": 1,
        "reason": "reason name"
    }
    ...
}

Get project groups

Отримати список груп проектів

Endpoint: /public/groups

HEADERS
authorize your company

Api-Key: <Your api key>
Api-Secret: <Your api secret key>
X-Locale: <Locale>

GET
supported formats: form-query;
copy
    
    {
        // Set country_code in ISO format to get projects priority for your country
        "country_code": "UA",
        // Set count in integer format to get count of projects, default you will get 4 projects
        "count": 3,
    }
    
RESPONSE
Status 200 OK

{
    "id": 1,
    "name": "Group name",
    "projects": {
        "id": 31,
        "name": "Project name",
        "status": "published",
        "image": "image url",
        "background_image": "background image url"
        "total_cost": "26229.00",
        "collected_cost": "100.35",
        "percent": "0.38",
        "short_description": "project short description",
        "project_url": "project url on humance.io",
        "tree_price": "3.25"
    },
},
{
    "id": 2,
    "name": "Group name",
    "projects": {
        "id": 25,
        "name": "Project name",
        "status": "published",
        "image": null,
        "background_image": "background image url",
        "total_cost": "59621.00",
        "collected_cost": "0.00",
        "percent": "0.00",
        "short_description": "project short description",
        "project_url": "project url on humance.io",
        "tree_price": "3.25"
    },
    ...
}

    

Get cancel reasons

Отримати список причин для відмови оплати

Endpoint: /get/reasons

HEADERS
authorize your company

Api-Key: <Your api key>
Api-Secret: <Your api secret key>
X-Locale: <Locale>

GET
without any params
copy
RESPONSE
Status 200 OK

{
    "id": 1,
    "reason": "Reason name",
}

Get counter

Отримати кількість посаджених дерев

Endpoint: /public/counter

HEADERS
authorize your company
    
    Public-Key: <Your public key>
    
GET
without any params
copy
RESPONSE
Status 200 OK
    
    {
        "count": 653,
    }
    
    

Init component

Для того щоб ініціалізувати компонент в проекті потрібно вставити цей код та передати "order-id"

copy
                <div class="component-humance" data-order-id="You order ID"></div>
            

Також потрібно підключити зовнішні скрипти та стилі

Style
copy
                <link rel="stylesheet" href="https://humance.io/company/cdn/css/my-file.css/'public_api_key'" referrerpolicy="no-referrer">
            
Script
copy
                <script rel="stylesheet" href="https://humance.io/company/cdn/js/my-file.js/'public_api_key'" referrerpolicy="no-referrer"></script>