Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pondersource/CYB

PHP code to Connect Your Books
https://github.com/pondersource/CYB

Last synced: 3 months ago
JSON representation

PHP code to Connect Your Books

Host: GitHub
URL: https://github.com/pondersource/CYB
Owner: pondersource
License: mit
Created: 2022-10-04T14:12:53.000Z (about 2 years ago)
Default Branch: main
Last Pushed: 2023-03-28T09:28:51.000Z (over 1 year ago)
Last Synced: 2024-06-21T13:30:33.457Z (5 months ago)
Language: PHP
Size: 1.1 MB
Stars: 2
Watchers: 5
Forks: 0
Open Issues: 20
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-starred - pondersource/CYB - PHP code to Connect Your Books (others)

README

# CYB
PHP code to Connect Your Books

Under construction.

This gateway will let you connect various data sources and sinks for bookkeeping data in the domains of:
* time tracking
* issue tracking
* invoicing
* mutual credit networks
* budget tracking

The name CYB stands for "Connect Your Books".

See [Federated Bookkeeping](https://federatedbookkeeping.org) for more info on the vision behind it.

## Usage

### for developing on local machine:
```sh
cd cyb-app
chmod u+x ./run-docker.sh
./run-docker.sh dev pull
./run-docker.sh dev up --detach
```

### for developing on Gitpod:
```sh
cd cyb-app
chmod u+x ./run-docker.sh
./run-docker.sh gitpod pull
./run-docker.sh gitpod up --detach
```

### for deploying on VPS:
```sh
cd cyb-app
chmod u+x ./run-docker.sh
./run-docker.sh prod pull
./run-docker.sh prod up --detach
```

## Development
### How to add a new connector
1. Pick a name for your connector. Must be all lowercase and url safe. Ex. time_mld, github
2. Create a new folder under `app/Connectors` and name it in the studly form of your connector name. Ex. TimeMld, Github
3. Put an implementation of `\app\Core\Connector` in the newly created folder. Ex. GithubConnector.php
4. Modify `\app\Core\ApplicationManager::getConnectors` and add an instance of your Connector to it.

### Routes
In order to support custom routes for your connector, create a folder named `routes` under your connector's root folder. Then you can create `api.php` and `web.php` files there to define your routes. The newly added routes will be under `/api/connector/{connector name}` and `/connector/{connector name}` respectively. And the routes can be addressed under the name `connector.{connector name}`.

### Returning views for your connector web routes
Suggested approach is to create a `resources\views` folder under your connector's root folder. Then you can reference those views by using the View facade (`Illuminate\Support\Facades\View`) and calling `View::file` method with the full address to your view file.

# Let's Peppol
Let's peppol is a CYB connector that provides free access to the PEPPOL network.

## How to integrate
In order to take advantage of Let's Peppol in your software you have to create a CYB connector for `invoice` data type. This connector should be included in the main running CYB instance. Then for each user, go through the following steps:

1. Call `POST /api/register` with `name`, `email` and `password` in the request body.
2. Call `POST /api/generateToken` with `email` and `password` to get a permanent bearer authorization token for all the other calls.
3. Call `POST /api/connector/lets_peppol/identity` with `name`, `address`, `city`, `region`, `country` code, `zip` in the request body. You will get the created `Identity` object in the response. You'll need to store the Identity id.
4. Keep calling `GET /api/connector/lets_peppol/identity/{identity_id}` to check the `kyc_status`. `0` means pending approval, `1` means rejected and `2` means approved. Approval is currently a manual process that takes time. After being approved, you can retrieve `identifier_scheme` and `identifier_value` from the identity object.
5. After getting approved, call `GET /api/authentication?app_code_name=lets_peppol&app_user_id={identity_id}` to get the relevant `Authentication` object for the created Let's Peppol Identity and store its id.
6. Call `POST /api/read/{authentication_id}/invoice` with `read` set as `true` in the request body to enable receiving invoices for Let's Peppol.
7. Call `POST /api/write/{authentication_id}/invoice` with `write` set as `true` in the request body to enable auto sending of out going invoices?
8. You can always call `GET /api/function/{auth_id}/invoice` to check the `read` and `write` status of the authentication.
9. Create an authentication in your connector for the user. To do this you'll need to define your own API endpoints and eventually call `ApplicationManager::createAuthentication($auth_info)`.
10. Repeat steps 6 and 7 for your application's authentication to enable read and write functionalities.
11. You can always call `POST /api/connector/lets_peppoo/message/{identity_id}` with an UBL as the request body to directly send invoices through Let's Peppol. If `read` is turned on, you'll receive the event upon delivery of the invoice.

## UBL
A sample UBL invoice looks like the following:
``` xml

2.1
urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0
urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
1234
2022-09-06
380
invoice note
EUR
4217:2323:2323
BUYER_REF

2022-09-06

5009567
tRST-tKhM

asdffbddsf

99887766

PonderSource

Lisk Center Utreht
De Burren
Utreht
3521

NL

NL123456789

VAT

PonderSource
NL123456789

phase4-test-sender

9988217

Client Company Name

Lisk Center Utreht
De Burren
Utreht
3521

NL

BE123456789

VAT

Client Company Name
Client Company Registration

Client name
908-99-74-74

2022-09-06

Delivery street 2
Building 56
Utreht
3521

NL

31
our invoice 1234

NL00RABO0000000000
Customer Account Holder

RABONL2U

30 days net

2.10

10.00
2.10

S
21.00

VAT

10.00
10.00
12.10
0.00
12.10

0
1.00
10.00

2022-09-06

Product Description
Product Name

S
21.00

VAT

10.00
1.00

```