Skip to content

Commit

Permalink
rework doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexandre-abrioux
alexandre-abrioux committed Oct 20, 2021
1 parent a7635ee commit 16ce4ea
Showing 1 changed file with 58 additions and 44 deletions.
102 changes: 58 additions & 44 deletions packages/docs/docs/guides/3-Portal-API/3-create-an-invoice.md
View file
Expand Up @@ -5,29 +5,39 @@ description: Learn how to integrate Request network and its features.

---

## Request vs. Invoice, what's the difference?
## Request vs. Invoice, how do they differ?

You are now familiar with the [Request API](./1-create-and-share-request.md), but did you know you could also create, on
Portal, Invoices which supersede Requests? How do they differ?
You are now familiar with the [Request API](./1-create-and-share-request.md),
but did you know you could also create, on Portal, Invoices which supersede Requests?

Invoices are simply an implementation of Requests with a predefined schema for the `contentData` property.
Invoices are mainly used by the [Request Invoicing](https://invoicing.request.network/) application
as a way to practically represent general invoicing data.

Invoice API also differ by the layer of automation added on top of Request API.
Whenever an Invoice is created, an email is sent to the designated payer.
The Invoice creator (payee) will also get notified as soon as the corresponding Request has been paid.
Whenever an Invoice is created, it is possible to have an email sent to the designated payer.
The Invoice creator (payee) can also get notified as soon as the corresponding Request has been paid
(please [contact us](https://www.request.finance/contact-us) if you need more info on this feature).

Knowing if a Request has been paid [is not trivial](./2-payment-status.md).
But Invoices have an additional property: a status
But Invoices have an additional property: a `status`
; so knowing if the underlying Request has been paid is as easy as reading this property.

Invoices can also be scheduled to create duplicates at regular intervals.
This is useful to manage collaborators salaries.

Invoices can also be approved before being paid,
notifying the payee the intent of remuneration of the payer,
once the agreement between the two parties is settled for instance.
Invoices can also get approved before being paid,
notifying the payee of the payer's agreement to send funds
once—for instance—the contract between the two parties is settled.

To summarize:

| | Request | Invoice |
|---------------------|:-------------:|:-------------:|
| Portal API endpoint | `/requests` | `/invoices` |
| Schema | `contentData`<br/>not validated by API | Invoices extend Requests<br/> `contentData` schema validated by API |
| Automation | ✖️ | ✔ ️ |
| Recurrence | ✖️ | ✔ |

## Introduction

Expand Down Expand Up @@ -60,8 +70,8 @@ In the body part you can use the following example and replace the data accordin
"format": "rnf_invoice",
"version": "0.0.3"
},
"creationDate": "2021-09-22T14:38:16.916Z",
// ISO-8601 date
"creationDate": "2021-09-22T14:38:16.916Z",
"invoiceItems": [
{
"currency": "USD",
Expand All @@ -81,52 +91,53 @@ In the body part you can use the following example and replace the data accordin
// It is a string, so it can contain a number, or a more custom invoice identifier.
"invoiceNumber": "2",
"buyerInfo": {
"businessName": "Request Network",
"businessName": "Acme Wholesaler",
"address": {
"country-name": "France",
"street-address": "5 Av. Anatole France",
"extended-address": "Champ de Mars",
"postal-code": "75007",
"locality": "Paris"
"country-name": "United States of America",
"street-address": "4933 Oakwood Avenue",
"extended-address": "",
"postal-code": "10038",
"region": "New York",
"locality": "New York"
},
"email": "buyer-test@request.network",
"firstName": "Buyer First Name",
"lastName": "Buyer Last Name",
"taxRegistration": "Buyer Taxpayer Identification Number"
"email": "justin.j-ryan@acme-wholesaler.com",
"firstName": "Justin",
"lastName": "J Ryan",
"taxRegistration": "985-80-3313"
},
"sellerInfo": {
"businessName": "TV Seller Acme",
"businessName": "Acme TV Seller",
"address": {
"country-name": "AAA",
"country-name": "United States of America",
"street-address": "3521 Park Avenue",
"extended-address": "aaa address line 2",
"extended-address": "",
"postal-code": "00501",
"region": "New York",
"locality": "HOLTSVILLE"
},
"email": "seller-test@acme.com",
"firstName": "Seller First Name",
"lastName": "Seller Last Name",
"taxRegistration": "Seller Taxpayer Identification Number"
"email": "william.d-hays@acme-tv-seller.com",
"firstName": "William",
"lastName": "D Hays",
"taxRegistration": "965-65-3092"
},
"paymentTerms": {
// ISO-8601 date, last day the buyer can pay
"dueDate": "2021-10-22T21:59:59.999Z"
},
// address which will receive the payment
"paymentAddress": "0x4886E85E192cdBC81d42D89256a81dAb990CDD74",
// FAU is a fake ERC-20 that we deployed on Rinkeby that is used when we select the DAI currency on the UI. On mainnet for your use case it will be xDAI-xdai or USDC-xdai
// see https://api.request.network/currency for a list of currencies
"paymentCurrency": "USDC-xdai",
// optional, you can add several tags to the invoice
"tags": [
"Tag1",
// optional, you can add several tags to the invoice
"tag1",
"tag2"
]
}
```

In the JSON response you will get an “id” field. Please save it in a variable or in your database. You will need it in
the next section.
In the JSON response you will get an `id` field. Please save it in a variable or in your database.
You will need it in the next section.

### Convert the off-chain Invoice into an on-chain Request

Expand All @@ -138,19 +149,21 @@ Use the following endpoint to convert the previously created off-chain Invoice

You don't need to pass anything in the request body this time.

In the JSON response you will get a requestId field. This is the ID of the newly created Request. Please save it in your
database as you will need it to know when the Request has been paid.
In the JSON response you will get a `requestId` field.
This is the ID of the newly created Request.
Please save it in your database as you will need it to be informed of when the Request has been paid.

### Know when the Request has been paid

We don’t have a notion of webhooks implemented yet, you will need for now to poll our API regularly to be informed as to when the user
has paid its Request.
In order to be informed as to when the payer has fulfilled the Request you need to poll our API regularly.

Please use the following endpoint to retrieve the status of the Request:

`GET https://api.request.network/invoices/[id] `

Replace `[id]` with the ID of the Invoice, or the ID of the Request (requestId). You can check the status field of the
Replace `[id]` with the ID of the Invoice, or the ID of the Request `requestId`.

You can check the `status` field of the
JSON response. The different statuses of an Invoice are the following:
- `draft`
- `pending`
Expand All @@ -162,13 +175,14 @@ JSON response. The different statuses of an Invoice are the following:
- `paid`
- `canceled`

After creating the Request with the previously described process you should end-up with a `pending` status while the
Request is being created on-chain (as it is asynchronous), followed by an `open` status after the Request has actually
been created.
After creating the Request with the previously described process you should end-up with a `pending` status
while the Request is being created on-chain (as this process is asynchronous),
followed by an `open` status after the Request has actually been created.

You can use the values `paid` to classify the payment as done and stop polling for a new status.
You can use the value `paid` to classify the Request as "fulfilled" and stop polling for a new status.

When the value matches `rejected` or `canceled` you can also stop polling because it means that the Request has been
manually canceled out by someone (meaning by the buyer or by the aaa admin before the Request got paid).
When the value matches `rejected` or `canceled` you can also stop polling because
it means that the Request has been manually canceled out by the payer (or the payee via it's interface),
and thus will not get paid.

You should also terminate the polling process if the current date exceeds the `paymentTerms.dueDate` date.
You should also terminate the polling process if the current date exceeds `paymentTerms.dueDate` value.

0 comments on commit 16ce4ea

Please sign in to comment.