Introduction

Welcome to the Asteria Documentation! You can use our documentation to access Asterias services, which can give your clients insights in to there Cash Flow!

We have language bindings in Shell, JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Changelog

1.0.1

Added data layer along with graph handling
Restructure documentation
Add partner section

1.0.0

Public Release

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2020-04-05. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

Authentication

Asteria uses an client ID and client certificate to authenticate requests from partners. You can view and manage your certificates and client ID's inside OWL administration interface

Your client ID and client certificate carry many privileges, so be sure to keep them secure! Do not share your client certificate key in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

JWT Tokens are used for end user authentication, please see Client Certificates for partner authentication

JWT Token

There are three different JWT token used to authenticate against the API gateway. These token give you different modes of access and scopes inside the asteria platform.

All tokens are signed JWT token grants that are signed with secret that is stored securely inside the asteria platform

The three kinds of tokens are admin, user and integration tokens.

The token should be provided in the any and all request to the API gateway and should be placed inside the request header


curl 'https://stage.api.asteria.ai/api/v3/' -H 'Authorization: bearer TOKEN'

Client Certificate

Client certificates is an two way SSL certificate authentication flow. Where both request initiator and request receiver are using an valid SSL Certificate in an Mutual authentication flow.

To receive your client id connected to your certificate you need to provide your public key to Asteria via info@asteria.ai.

All calls to Asterias Partner Gateway need to be accompanied by your Client ID and Client Certificate


curl -X GET https://stage.partner-gateway.asteria.ai/api/integrations/ \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>'

Errors

The Asteria API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested is hidden for administrators only.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access a cashflow with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're requesting too many resources! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

API Gateway

Entry point for all of asterias end client API's. Provides an GraphQL API endpoint

API Authentication

Sensitive endpoints / methods are protected by asterias authentication system and highly sensitive data is fetched through the Partner Gateway

Public

Some methods are exposed publicly with no authentication required as they are used before the user is logged in.

For example: login, signup, and missing erp

JWT Token

There are three different JWT token used to authenticate against the API gateway. These token give you different modes of access and scopes inside the asteria platform.

All tokens are signed JWT token grants that are signed with secret that is stored securely inside the asteria platform

The three kinds of tokens are admin, user and integration tokens.

The token should be provided in the any and all request to the API gateway and should be placed inside the request header


curl 'https://stage.api.asteria.ai/api/v3/' -H 'Authorization: bearer TOKEN'

Ratelimit

All methods are protected with an ratelimiter to prevent overflow of the API

URI

Stage: https://stage.api.asteria.ai/api/v3/

Production: https://api.asteria.ai/api/v3

Requests

Method: POST

Payload:

query: string // The GraphQL query / mutation ( Required )
variables: json // Query / Mutation variables ( Optional )
operationName: string // The query / mutation to execute ( Optional )


curl 'https://stage.api.asteria.ai/api/v3/' -H 'Accept-Encoding: gzip, deflate, br' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Connection: keep-alive' -H 'DNT: 1' -H 'Origin: https://stage.api.asteria.ai' --data-binary '{"query":"mutation Login($username: String!, $password: String!, $partnerId: ID) {login(username: $username, password: $password, partnerId: $partnerId) {data {accessToken}}}", "variables": {"username":"USERNAME","password":"PASSWORD"}}' --compressed

Playground

You can access and Graphical Graphql Edtior and run queries against asterias API's

In the large Edtior window, enter the GraphQL Query

Query: Is the large editor window, example: query { me { id } }
HTTP Headers: Is located down to the left, example: {"authorization":"bearer #JWT_TOKEN#"}
Query Variables: Is located down to the left, example: {"username":"test@test.se"}

Authentication: None

Method: POST

// Query
mutation Signup($username: String!, $password: String!, $company: String!, $partnerId: ID, $signupKey: String) {
  signup(user: { username: $username, password: $password }, company: {name: $company}, partnerId: $partnerId, signupKey: $signupKey) {
    auth {accessToken}
  }
}

// Query Variables

{
    "username": "test@asteria.ai",
    "password": "PASSWORD",
    "company": "Test AB",
    "partnerId": "PARTNER_ID",
    "signupKey": "SIGNUP_KEY"
}

// HTTP Headers
none

Authentication: None

Method: POST

// Query
mutation Login($username: String!, $password: String!, $partnerId: ID) {
  login(username: $username, password: $password, partnerId: $partnerId) {
    data { accessToken }
  }
}

// Query Variables

{
    "username": "USERNAME",
    "password": "PASSWORD",
    "partnerId": "PARTNER_ID"
}

// HTTP Headers
none

Add Demo Bank Data

Authentication: JWT Token

Method: POST

// Query
mutation AddDemoData($input: IntegrationCreateInputType!) {
  addIntegration(input: $input) {ok}
}

// Query Variables

{
    "input": {
        "type": "bank",
        "key": "asteriaBank",
        "config": {
            "client": {
                "authorizationCode": "TestData"
            }
        }
    }
}

// HTTP Headers
{"authorization":"bearer #login.data.accessToken#"}

Add Demo ERP Data

Authentication: JWT Token

Method: POST

// Query
mutation AddDemoData($input: IntegrationCreateInputType!) {
  addIntegration(input: $input) {ok}
}

// Query Variables

{
    "input": {
        "type": "erp",
        "key": "testIntegration",
        "config": {
            "client": {
                "authorizationCode": "TestData"
            }
        }
    }
}

// HTTP Headers
{"authorization":"bearer #login.data.accessToken#"}

List Transactions

Authentication: JWT Token

Method: POST

// Query
query ListTransactions {
  transactions {
    pageInfo {
      count
    }
    edges {
      node {
        paymentDate
        sums {
          original {
            total
          }
        }
      }
    }
  }
}


// HTTP Headers
{"authorization":"bearer #login.data.accessToken#"}

Partners

Overview

The Asteria application is split into two subsystems: one targets partners, such as banks, while the other is aimed at end-users, specifically small corporations.

Partner Gateway - Targets Partners

The partner gateway is an essential component of the Asteria platform, providing a reliable and secure means for partners to manage and administer their SME users who have connected to Asteria through the partner's platform, such as a digital banking website. It is an HTTP-based service that uses the RESTful API standard to enable partners to integrate their platforms with Asteria seamlessly.

The partner gateway provides partners with access to a wide range of functionalities, including financial data management, transaction monitoring, and account information retrieval. Using these functionalities, partners can streamline their workflows, improve their operational efficiency, and enhance the overall user experience for their SME clients.

One of the key advantages of the partner gateway is its ability to provide partners with a standardized approach to data exchange. The RESTful API standard ensures that partners can easily and securely connect to Asteria, exchange data, and manage their SME clients' financial data with ease. This standardized approach not only improves the reliability and security of data exchange but also enables partners to integrate their platforms with Asteria in a more straightforward and hassle-free manner.

In addition to its robust set of functionalities, the partner gateway also provides partners with a powerful set of tools that enable them to track and analyze their SME clients' financial performance. Partners can use these tools to gain valuable insights into their SME clients' financial activities, monitor their performance, and make informed decisions based on the data.

API Gateway / Playground - Targets End Users

The Asteria platform features a GraphQL API gateway that is designed to provide an efficient and flexible means for delivering data to end-users, specifically via an HTML and JavaScript widget provided by Asteria. The GraphQL API gateway also supports custom integrations by Asteria's partners, enabling them to tailor the platform's functionality to their specific needs.

The GraphQL API gateway serves as a centralized data access layer, providing a single point of entry for accessing data from the Asteria platform. It enables clients to send requests for data to the platform, and receive responses in the form of JSON documents. This approach provides greater flexibility and control over data retrieval, enabling clients to specify precisely the data they require.

The HTML and JavaScript widget provided by Asteria is a pre-built solution that enables end-users to easily access and interact with data from the platform. The widget is highly customizable, allowing clients to tailor its appearance and functionality to their specific needs. The widget can be easily embedded into existing web applications, enabling clients to provide a seamless user experience for their end-users.

In addition to the pre-built widget, the GraphQL API gateway also supports custom integrations by Asteria's partners. Partners can use the GraphQL API to build custom applications that interact with data from the Asteria platform. The API provides a comprehensive set of query and mutation operations that enable partners to retrieve and modify data in a flexible and efficient manner.

Connecting

In order to connect to Asteria's partner gateway, you will need to follow a few steps:

Obtain a valid and signed SSL certificate from a trusted source, such as Digicert or GoDaddy. This certificate will be used to secure communications between your system and the Asteria platform.
Register as a partner with Asteria by sending an email or using an agreed upon communication channel. You will need to provide the following information:
- The public part of your SSL certificate
- The name of your company
- The name and email address of your primary contact

Once Asteria has received this information, they will register you as a partner and provide you with the following:

A ClientID, which is used when communicating with the partner gateway
A PartnerID, which is used when communicating with the end user API

Test your connection to the Asteria partner gateway by attempting to create a user using the following curl command.

By completing these steps, you will be able to establish a secure and reliable connection to Asteria's partner gateway, and begin integrating your system with the Asteria platform.

curl -X POST https://stage.partner-gateway.asteria.ai/api/auth/login \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'userId=<UUID of the user>&companyId=<UUID of the company>'

The foloowing 5 values will need to be changed to the foloowing

<Your private key file> : The private key of the SSL Certificate that you sent to Asteria
<Your public cert file> : The certificate part of the SSL Certificate that you sent to Asteria
<Your client id> : Your client id recived after registering as a partner with Asteria
<UUID of the user> : You internal unique idenfitifer for the end user
<UUID of the company> : You internal unique idenfitifer for the end users company

User registration flow

To register and log in a user, the Asteria platform utilizes an HTTP request that can be used for both new and existing users. The backend of the Asteria platform is responsible for handling new and existing users on its side, ensuring a seamless and efficient user experience.

The HTTP request is designed to provide a flexible and intuitive means of registering and logging in users, allowing them to quickly and easily access the platform's features and functionality. The request is implemented using a standard RESTful API architecture, which enables clients to send requests to the Asteria platform using a variety of different programming languages and frameworks.

Upon receiving the HTTP request, the Asteria backend performs a number of key tasks, including user authentication, session management, and user data validation. These tasks are critical to ensuring the security and reliability of the platform, and are handled automatically by the Asteria backend.

curl -X POST https://stage.partner-gateway.asteria.ai/api/auth/login \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'userId=<UUID of the user>&companyId=<UUID of the company>'

Authentication and registration flow

The HTTP request in question is designed to create a new user within the Asteria platform, using the UserId and CompanyId values provided in the request. Notably, this request does not involve the use of a password or username, as the user registration process occurs through the partner's system, with the user already authenticated and logged in.

As a result, Asteria relies on partners to handle the end user authentication and approval process, as this information is not passed through the HTTP request. This approach ensures that partners are able to maintain control over the user authentication process, and can ensure that their own security and compliance requirements are met.

Once the HTTP request is received by the Asteria platform, the new user is automatically linked to the provided UserId and CompanyId values, and their account is created within the Asteria system. From there, the user can access the full range of features and functionality offered by the Asteria platform, using the partner's system as the primary means of authentication and access control.

The user registration flow can be broken down into the following steps:

The user navigates to the partner's website, such as https://www.partners_website.com.
The user logs in using their credentials on the partner's website.
The user navigates to a specific page, such as https://www.partners_website.com/cashflow.
1. The partner's backend executes an HTTP POST request to https://stage.partner-gateway.asteria.ai/api/auth/login, passing the user's internal ID and company ID as parameters.
2. The Asteria API verifies the credentials and returns an Access Token to the partner's backend.
3. The partner's backend injects the Asteria Widget into the webpage, passing the Access Token received from Asteria as a parameter.
The user gains access to their cash flow data via the Asteria Widget embedded in the partner's webpage.

Data Request flow ( ERP or Bank )

When a request is made to Asteria's backend to obtain either banking or accounting data for a company, the backend automatically handles both new and existing users. This request triggers the creation of a new company and links it to the provided companyId. Once the company is successfully created, an automated email or SMS is sent to the associated contact person or persons requesting them to connect their bank or ERP system.

The contact email or SMS includes detailed instructions on how to connect their bank or ERP system to Asteria, as well as guidelines and documentation for the integration process. Any necessary credentials required for authentication and secure data transmission are also provided in the message.

curl -X POST https://stage.partner-gateway.asteria.ai/api/service/request \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'companyId=<UUID of the company>&type=<ERP or BANK>&contactEmail=<Email to contact>&contactPhone=<Phone number to contact>&service=<Detailed information about request>'

Gateway

Introduction

As an partner to Asteria you need to integrate towards the Partner Gateway to enable seamless user signup and login.

The partner gateway uses an client certificate and client id authentication flow to enable high security and mutual authentication between partners services and asterias.

Authentication

Please see Client Certificate in the Authentication Section


curl -X POST https://stage.partner-gateway.asteria.ai/api/auth/login \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'userId=<UUID of the user>&companyId=<UUID of the company>'


The above command returns JSON structured like this:

{
    "ok": true,
    "data": {
        "accessToken": "<JWT ACCESS TOKEN>",
        "accessTokenExpires": "<JWT ACCESS TOKEN EXPIRE TIME>",
        "refreshToken": "<JWT REFRESH TOKEN>",
        "acceptedTerms": false,
    }
}

When an users inside the partners platform accepts and wants to connect to Asterias Cashflow services an Access Token is needed for the user. The login API request should only be done from the partners backend and requires the Client Certificate Authentication flow.

Partners have the ability to seamlessly create and login users inside the Asteria platform. Login and Signup are the same API call.

An unique Company ID and User ID needs to be provided to prevent duplicates and seamless two way connectiong between partners user ids and Asterias

Delete Company


curl -X POST https://stage.partner-gateway.asteria.ai/api/erase/company \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'companyId=<UUID of the company>'


The above command returns status code 204 on success

When an company inside the partners platform is requesting to terminate there agreement with Asteria the partner can initiate and deletion of all data related to that user

An unique Company ID needs to be provided to ensure that the correct company data is removed from the system

This will remove all users along with all data associated with the company

Delete User


curl -X POST https://stage.partner-gateway.asteria.ai/api/erase/user \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'userId=<UUID of the company>'


The above command returns status code 204 on success

When an company inside the partners platform is requesting to terminate there agreement with Asteria the partner can initiate and deletion of all data related to that user

An unique Company ID needs to be provided to ensure that the correct company data is removed from the system

This will remove all users along with all data associated with the company

Bank Accounts

For fetching all accounts related to and given user, you can execute the following query


curl -X POST 'https://stage.partner-gateway.asteria.ai/api/company/accounts/' \
    --key "<Your private key file>" \
    --cert "<Your public cert file>" \
    -H 'x-asteria-client: <Your client id>' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'companyId=<UUID of the company>&partnerUUID[bankId]=<bankId>'


The above command returns status code 200 on success and the following response format

ok: Boolean,
data: [
    {
        account: String // The full bank account number
        number: String // The bank account number
        clearing: String // The bank account clearing number
    }
]

Webhook

A new webhook should be added into the Partner entity. Just administration users with ADMIN and PARTNER roles can add a new webhook. User can add webhooks via Single or Bulk request.

Currently no administration interface exists for managing your webhooks and therefor an request needs to be sent to Asteria Support.

The message needs to contain the following information

PartnerID: Provided to you by asteria

Event Type: CLIENT_CREATE, INVOICE_UPDATE, etc

Webhook URL: https://example.api/webhook/path

Header: Any required headers

Available Webhook / Websocket types

enum PARTNER_WEBHOOK_ENUM {
    # CLIENT
    CLIENT_CREATE
    CLIENT_UPDATE
    CLIENT_REMOVE

    # INVOICE
    INVOICE_CREATE
    INVOICE_UPDATE
    INVOICE_REMOVE

    # PRODUCT
    PRODUCT_CREATE
    PRODUCT_UPDATE
    PRODUCT_REMOVE

    # VOUCHER
    VOUCHER_CREATE
    VOUCHER_UPDATE
    VOUCHER_REMOVE

    # BANK_ACCOUNT
    BANK_ACCOUNT_CREATE
    BANK_ACCOUNT_UPDATE
    BANK_ACCOUNT_REMOVE

    # BANK_TRANSACTION
    BANK_TRANSACTION_CREATE
    BANK_TRANSACTION_UPDATE
    BANK_TRANSACTION_REMOVE

    # TAG
    TAG_UPDATE
    TAG_REMOVE

    # INTEGRATION
    INTEGRATION_CREATE
    INTEGRATION_UPDATE
    INTEGRATION_REMOVE

    # TRANSACTION
    TRANSACTION_CREATE
    TRANSACTION_UPDATE
    TRANSACTION_REMOVE

    # USER
    USER_CREATE
    USER_UPDATE
    USER_REMOVE
}

Websocket

An example is written using ws library.

const WebSocket = require('ws');

const https = require('https');
const fs = require('fs');
const path = require('path');

const httpsAgent = new https.Agent({
    rejectUnauthorized: false,
    key: '<private_key>',
    cert: '<crt_certificate>',
});

const ws = new WebSocket('wss://stage.partner-gateway.asteria.ai', {
    headers: {
        'x-asteria-client': 'string',
    },
    agent: httpsAgent,
});

ws.on('open', function open() {
    console.log('connected');
    ws.send(Date.now());
});

ws.on('close', function close() {
    console.log('disconnected');
});

ws.on('message', function incoming(data) {
    console.log({ data });
});

Data examples

CLIENT_UPDATE

Method: POST
Headers:

{
    "accept": "application/json, text/plain, _/_",
    "content-type": "application/json;charset=utf-8",
    "x-asteria-topic": "CLIENT_UPDATE",
    "user-agent": "axios/0.19.2",
    "content-length": "415",
    "connection": "close"
}

Response:

{
    "info": { "accounts": [] },
    "meta": { "clientNumber": "1", "source": "5e3a6b2ae7731c00581951ba" },
    "analysis": { "dates": [], "trend": [], "seasonal": [], "remainder": [] },
    "active": true,
    "status": [],
    "_id": "5ef5add7c3cd659588c53242",
    "companyId": "5eafe37ddc7a940058c76479",
    "type": "CUSTOMER",
    "__v": 0,
    "createdAt": "2020-06-26T08:12:07.597Z",
    "name": "Stanton Cruickshank",
    "updatedAt": "2020-06-26T08:12:07.597Z",
    "id": "5ef5add7c3cd659588c53242"
}

INVOICE_UPDATE

Method: POST
Headers:

{
    "accept": "application/json, text/plain, */*",
    "content-type": "application/json;charset=utf-8",
    "x-asteria-topic": "INVOICE_UPDATE",
    "user-agent": "axios/0.19.2",
    "content-length": "1039",
    "connection": "close"
}

Response:

{
    "meta": {
        "invoiceNumber": "1",
        "source": "5e3a6b2ae7731c00581951ba",
        "clientNumber": "1"
    },
    "dates": {
        "invoiceDue": "2021-12-25T18:00:00.000Z",
        "invoicePaid": null,
        "invoiceSent": "2019-03-25T18:00:00.000Z"
    },
    "info": { "status": "PROCESSING", "isForecast": false },
    "contact": {
        "general": {
            "email": "Annabell18@yahoo.com",
            "name": "Jaylan Schuster"
        }
    },
    "active": true,
    "type": "invoice",
    "canceled": false,
    "credits": ["test"],
    "_id": "5ef5adfcc3cd659588c53295",
    "clientType": "CUSTOMER",
    "companyId": "5eafe37ddc7a940058c76479",
    "clientId": "5ef5add7c3cd659588c53242",
    "createdAt": "2020-06-26T08:12:44.119Z",
    "sums": {
        "original": {
            "tax": 0,
            "invoiceTotal": 100,
            "currency": "SEK"
        },
        "system": {
            "tax": 0,
            "invoiceTotal": 125,
            "currency": "EUR"
        }
    },
    "updatedAt": "2020-06-26T08:12:44.119Z",
    "payments": [],
    "id": "5ef5adfcc3cd659588c53295"
}

TRANSACTION_UPDATE

Method: POST
Headers:

{
    "accept": "application/json, text/plain, */*",
    "content-type": "application/json;charset=utf-8",
    "x-asteria-topic": "TRANSACTION_UPDATE",
    "user-agent": "axios/0.19.2",
    "content-length": "1148",
    "connection": "close"
}

Response:

{
    "meta": {
        "tags": ["5ef5adfcc3cd659588c532a2"],
        "categories": ["5ef5adfcc3cd659588c5329f"]
    },
    "parentId": null,
    "manual": false,
    "active": true,
    "viewed": false,
    "type": "DEPOSIT",
    "status": "UNPAID",
    "_id": "5ef5adfcc3cd659588c5329c",
    "companyId": "5eafe37ddc7a940058c76479",
    "links": [
        {
            "type": "INVOICE_PAYMENT",
            "id": "5ef5adfcc3cd659588c53295",
            "clientId": "5ef5add7c3cd659588c53242",
            "reference": "initial",
            "sums": {
                "original": {
                    "total": 100,
                    "currency": "SEK"
                },
                "system": {
                    "total": 125,
                    "currency": "EUR"
                }
            }
        }
    ],
    "__v": 0,
    "createdAt": "2020-06-26T08:12:44.229Z",
    "paymentDate": "2021-12-25T18:00:00.000Z",
    "sums": {
        "original": {
            "currency": "SEK",
            "total": 100
        },
        "system": {
            "currency": "EUR",
            "total": 125
        }
    },
    "updatedAt": "2020-06-26T08:12:44.338Z",
    "id": "5ef5adfcc3cd659588c5329c"
}

CLIENT_REMOVE

Method: POST
Headers:

{
    "accept": "application/json, text/plain, */*",
    "content-type": "application/json;charset=utf-8",
    "x-asteria-topic": "CLIENT_REMOVE",
    "user-agent": "axios/0.19.2",
    "content-length": "34",
    "connection": "close"
}

Response:

{
    "_id": "5ef5add7c3cd659588c53242"
}

Data Import

It's effortless and straightforward to import invoice or banking data for your end users using the following endpoint. The endpoint is designed to accept standard formats, as well as custom formats that have been agreed upon with Asteria.

When you make a call to this endpoint, the system automatically checks if the company already exists. If it doesn't, the system creates the company within the Asteria environment.

You don't need to create or register any users before importing data. This call is all that's required to create the user, company, and integration with your system. This streamlined process ensures a seamless onboarding and connection experience.

HTTP Import Request


curl -X POST https://stage.partner-gateway.asteria.ai/api/integrations/import \
--key <Your private key file> \
--cert <Your public cert file> \
-H 'x-asteria-client: <Your client id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d '{"type": "erp", "companyId": "YOUR_INTERNAL_UUID_FOR_COMPANY", "data": [{"type": "INVOICE","clientType": "SUPPLIER","client": {"number": "1234","name": "Client Name"},"number": "UNIQUE_INVOICE_NUMBER","dates": {"sent": "2020-10-10","due": "2020-11-10","paid": "2020-10-23"},"sums": {"total": 12345.12,"tax": 1427.12,"currency": "USD"},"payments": [{"date": "2020-10-22","total": 10000},{"date": "2020-10-22","total": 2345.12}]}]}'

Invoice Schema


Request Schema

{
    "type": String (erp or bank),
    "companyId": String (Your internal unique identifier for this company / user),
    "data": Array<Invoice || Transaction>
}


Invoice Schema

{
    "type": String (INVOICE || ORDER || CREDIT) // What type is this invoice,
    "clientType": String (SUPPLIER || CUSTOMER) // Is this a supplier or customer invoice,
    "client": { // Client information
        "number": String,
        "name": String ( Optional )
        "address": { Optonal client information
            "name": String,
            "email": String,
            "street": String,
            "street2": String,
            "city": String,
            "zipcode": String,
            "country": String,
            "phone": String,
            "mobile": String,
        }
    },
    "number": String, // Unique invoice number used to identify, this only needs to be unique for this user ( not client, but whole users company )
    "meta": { // Optional
        "paymentTerms": Int // Number of days from sent to dueDate
        "message": String // Message on invoice
    },
    "credits": [{"number": String // Inoice numbers that this invoice credits}],
    "dates": {
        "sent": Date, // When the invoice was sent
        "due": Date, // When the invoice is due to be paid
        "paid": Date ( Optional paid date, otherwise paid will be take from payments )
    },
    "sums": {
        "total": Float (Including taxes),
        "tax": Float ( Optional, taxes paid on invoice ),
        "currency": String ( EUR || SEK || USD || etc)
    },
    "payments": [ Optional (Either paid date or payments needs to be provided for paid invoices )
        {
            "date": Date,
            "total": Float,
            "currencty": String
            "rate": Float (Optinal currency conversion rate)
        },
    ]
}

Integration

React

The asteria widget contains all of asterias frontend functionality and can be easily added to your webpage

Getting Started

The asteria widget can easily be added with the following javascript


import { create } from '@asteria/widget-precompiled';

create(
    document.getElementById('asteria-widget'),
    {
        accessToken: 'ACCESS_TOKEN', // Asteria Accesstoken received from partner gateway
        partnerId: '', // Provided Partner id from asteria
        callback: (event, data) => { console.log(event, data ) }, // Event callback for whole widget
        languageCode: 'en', // Language code for widget
        demo: true || false, // Enable demo mode of widget, no accessToken necessary when this is provided
    }
);

This will load the asteria dashboard and display it at the provided DOM element

Clean up

The asteria widget needs to be cleaned up when being dynamicly removed from the DOM


import { cleanup } from '@asteria/widget-precompiled';

cleanup(document.getElementById('asteria-widget'));

This will trigger all necessary cleanup scripts and leave the DOM in a wonderful state

General

Demo

The widget can be placed in demo mode where no accessToken is needed and demo data will be provided.


import { create } from '@asteria/widget-precompiled';

create(
    document.getElementById('asteria-widget'),
    {
        ...
        partnerId: '', // Provided Partner id from asteria
        demo: true
    }
);

#### Language

The language of the widget can be changed by providing a different language code to the create function. The language codes are ISO_639-1 and the widget currently only supports swedish ( sv ) and english ( en )

```js

import { create } from '@asteria/widget-precompiled';

create(
    document.getElementById('asteria-widget'),
    {
        ...
        languageCode: 'en', // Language code for widget ISO_639-1
    }
);

Dashboard

Asterias dashboard is loaded with the following javascript and supports these params

accessToken: The asteria access token received from partner gateway
refreshToken: The asteria refresh token received from partner gateway
callback: Event callback handling activity, routing, errors, etc...
languageCode: ISO_639-1 language codes for language selection


import { create } from '@asteria/widget-precompiled';

create(
    document.getElementById('asteria-widget'),
    {
        accessToken: 'ACCESS_TOKEN', // Asteria Accesstoken received from partner gateway
        refreshToken: 'REFRESH_TOKEN',
        partnerId: '', // Provided Partner id from asteria
        callback: (event, data) => { console.log(event, data ) }, // Event callback for whole widget
        languageCode: 'en', // Language code for widget
    }
);

Routing

The target route that is displayed when the widget loads can be controlled via and simple argument to the widget create function

Available routes are

/home
/erp/add


import { create } from '@asteria/widget-precompiled';

create(
    document.getElementById('asteria-widget'),
    {
        accessToken: 'ACCESS_TOKEN', // Asteria Accesstoken received from partner gateway
        refreshToken: 'REFRESH_TOKEN',
        callback: (event, data) => { console.log(event, data ) }, // Event callback for whole widget
        languageCode: 'en', // Language code for widget
        route: '/erp/add'
    }
);

Events

All events are triggered on the callback property / attribute on the onboarding component with the following function and component definition


import { create } from '@asteria/widget-precompiled';

createErp(
    document.getElementById('asteria-widget'),
    {
        ...
        callback: (event, data) => { console.log(event, data ) }, // Event callback for whole widget
    }
);

ERROR

This event is triggered when an error occurs inside the onboarding flow

event: error
data: {
    event: 'error'
    path // Example of path ['onboarding', 'INTEGRATION_UUID', 'step', 'STEP_ID']
    message // Error message
    code // The error code of the message
}

Demo Mode

Asterias widget can be placed in demo mode where all data is generated locally and can be used for demo purposes. To place the widget in demo mode pass the demo = true option to the widget


import { create } from '@asteria/widget-precompiled';

create(
    document.getElementById('asteria-widget'),
    {
        accessToken: 'ACCESS_TOKEN', // Asteria Accesstoken received from partner gateway
        refreshToken: 'REFRESH_TOKEN',
        callback: (event, data) => { console.log(event, data ) }, // Event callback for whole widget
        languageCode: 'en', // Language code for widget
        demo: true // Enable, Place the widget in demo mode
    }
);

Introduction

Changelog

1.0.1

1.0.0

Versioning

Authentication

JWT Token

Client Certificate

Errors

API Gateway

API Authentication

Public

JWT Token

Ratelimit

URI

Requests

Playground

Signup

Login

Add Demo Bank Data

Add Demo ERP Data

List Transactions

Partners

Overview

Partner Gateway - Targets Partners

API Gateway / Playground - Targets End Users

Connecting

User registration flow

Authentication and registration flow

Data Request flow ( ERP or Bank )

Gateway

Introduction

Authentication

Login / Create User

Delete Company

Delete User

Bank Accounts

Webhook

Available Webhook / Websocket types

Websocket

Data examples

CLIENT_UPDATE

INVOICE_UPDATE

TRANSACTION_UPDATE

CLIENT_REMOVE

Data Import

Integration

React

Getting Started

Clean up

General

Demo

Dashboard

Routing

Events

ERROR

Demo Mode