# Procuret Python
A Python library for interfacing with Procuret API.
[Procuret](https://procuret.com) is a
business - to - business payment platform that allows customers to pay
for purchases over time, while the supplier is paid upfront.
## Contents
1. [Installation](#installation)
2. [Documentation](#documentation)
3. [Support](#support)
## Installation
Procuret Python may be [installed via PIP](https://pypi.org/project/procuret):
```bash
$ pip install procuret
```
To update Procuret Python to the latest version, use `pip --upgrade`:
```bash
$ pip install --upgrade procuret
```
## Documentation
Procuret Python offers a library of classes that map to services provided
by the Procuret API.
### `Session`
Sessions are the means of authenticating requests to the Procuret API. All
requests to Procuret API, save for those creating Sessions themselves, require
a Session.
In Procuret Python, the `Session` class will handle all authentication for you.
For example, it will compute the SHA256 signature that must be included
in your HTTP headers.
#### Properties
- `.session_id: int` - A 63-bit positive integer uniquely identifying this
`Session`. `Session` will include this number in requests to Procuret API, so
that Procuret API can identify you.
- `.api_key` - A 192-bit random number encoded in urlsafe base64 and generated
in a cryptographically secure manner. `Session` will use this key to sign your
requests to Procuret API using the SHA256 algorithm.
#### Methods
##### `.create_with_email(...) -> Session`
Use `.create_with_email()` to create a new `Session`. This is analogous to
"logging in" to the Procuret API.
###### Parameters
1. `email: str` - Your account email
2. `plaintext_secret: str` - Your plaintext passphrase
3. `perspective: Perspective` - an instance of `Perspective`
4. `code: str` - A two factor authentication code. Obtain via `SecondFactorCode`
5. `lifecycle: Lifecycle` - Defaults to `.LONG_LIVED`
###### Example Usage
```python
session = Session.create_with_email(
email='me@somedomain.com',
plaintext_secret='excellent passphrase',
perspective=Perspective.SUPPLIER,
code='123456'
)
```
##### `.from_interactive_prompt() -> Session`
Call this method to use an interactive `Session` creation procedure.
### `SecondFactorCode`
`SecondFactorCode` allows you to generate two-factor authentication codes for
use in creating `Session` instances.
#### Methods
##### `.create_with_email(...) -> None`
This method will cause a two-factor authorisation code to be sent to the
communication method associated with your Procuret account. You can then
use that code as the `code` parameter when creating a `Session`.
###### Parameters
1. `email: str` - Your account email
2. `plaintext_secret: str` - Your plaintext passphrase
3. `perspective: Perspective` - an instance of `Perspective`
###### Example Usage
```python
SecondFactorCode.create_with_email(
email='someone@somewhere.com',
plaintext_secret='excellent passphrase',
perspective=Perspective.BUSINESS
)
```
### `InstalmentLink`
`InstalmentLink` facilitates the creation of customised links to the Procuret
Instalment Product (PIP). PIP allows a customer Business to pay for a purchase
over time, while you the Supplier are paid upfront.
When you create an `InstalmentLink`, you can ask Procuret to send an email
to the customer Business on your behalf.
#### Properties
- `.invitee_email: str` - The email address you associated with the link
- `.invoice_amount: Decimal` - The invoice amount presented by the link
- `.invoice_identifier: str` - The invoice ID presented by the link
- `.url: str` - The URL of the link
#### Methods
##### `.create(...) -> InstalmentLink`
###### Parameters
1. `supplier: Union[int, EntityHeadline]` - Either the unique integer
identifier of your Supplier entity in Procuret, or an instead of
`EntityHeadline` describing your Supplier entity.
2. `invoice_amount: Decimal` - The amount that you wish to charge the customer,
in Australian dollars.
3. `invoice_email: str` - The email address you wish to associate with this
link.
4. `invoice_identifier: str` - Your own identifier for the invoice. For
example, you might use an invoice number from your accounting system.
5. `communication: CommunicationOption` - An instance of `CommunicationOption`,
which will tell Procuret API what you want it to do with the supplied email
address.
6. `session: Session` - An instance of `Session`, which will be used to
authenticate your request.
###### Example usage
```python
# First we get a Session. In this case we authenticate with email and
# passphrase. In a real integration, you might store the Session elsehwhere.
session = Session.create_with_email(
email=email,
plaintext_secret=secret,
perspective=Perspective.SUPPLIER,
code='12346' # Obtained via `SecondFactorCode`
)
# Now we use the Session in an InstalmentLink.create() call, along with
# the parameters describing the link. By supplying
# CommunicationOption.EMAIL_CUSTOMER, we tell Procuret that we would like
# Procuret to send an email to the customer on our behalf inviting them
# to pay using the link.
link = InstalmentLink.create(
supplier=supplier_id,
invoice_amount=Decimal('422.42'),
invitee_email='someone@great-domain.org',
invoice_identifier='T 055',
communication=CommunicationOption.EMAIL_CUSTOMER,
session=session
)
```
### `Perspective`
Perspective is an enumeration of possible angles from which a client
can engage with Procuret. If you wish to use Procuret services from
the perspective of a Supplier, you will create a `Session` with the
`Perspective.SUPPLIER` case.
#### Cases
- `.SUPPLIER`
- `.BUSINESS`
### Lifecycle
An enumeration of possible `Session` lifecycles - A "short lived" `Session` will
expire after a period of disuse. A "long lived" `Session` will never expire,
and must be manually deleted.
Consider opting for a short-lived `Session` wherever practical, to reduce the
probability of the stored credential being compromised.
#### Cases
- `.LONG_LIVED`
- `.SHORT_LIVED`
### `CommunicationOption`
An enumeration of instructions you can send Procuret in some contexts, to
tell it how you wish for it to contact (or not contact) the a customer.
#### Cases
- `.EMAIL_CUSTOMER` - Procuret will contact the customer by email
- `.DO_NOT_CONTACT_CUSTOMER` - Procuret will not try to contact the customer
## Support
Please contact us anytime at [support@procuret.com](mailto:support@procuet.com)
with any questions. To chat with us less formally, please feel free to tweet
[@hugh_jeremy](https://twitter.com/hugh_jeremy).
For more general information about Procuret, please visit
[procuret.com](https://procuret.com).
Raw data
{
"_id": null,
"home_page": "https://github.com/procuret/procuret-python",
"name": "procuret",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "library http api web payments finance",
"author": "Procuret",
"author_email": "hugh@procuret.com",
"download_url": "https://files.pythonhosted.org/packages/1a/a9/2c0f70dc49eacdc9d342ac92563921225fea93a22e55ddf4145a9a26cb3b/procuret-0.0.43.tar.gz",
"platform": null,
"description": "# Procuret Python\n\nA Python library for interfacing with Procuret API.\n[Procuret](https://procuret.com) is a\nbusiness - to - business payment platform that allows customers to pay\nfor purchases over time, while the supplier is paid upfront.\n\n## Contents\n\n1. [Installation](#installation)\n2. [Documentation](#documentation)\n3. [Support](#support)\n\n## Installation\n\nProcuret Python may be [installed via PIP](https://pypi.org/project/procuret):\n\n```bash\n$ pip install procuret\n```\n\nTo update Procuret Python to the latest version, use `pip --upgrade`:\n\n```bash\n$ pip install --upgrade procuret\n```\n\n## Documentation\n\nProcuret Python offers a library of classes that map to services provided\nby the Procuret API.\n\n### `Session`\n\nSessions are the means of authenticating requests to the Procuret API. All\nrequests to Procuret API, save for those creating Sessions themselves, require\na Session.\n\nIn Procuret Python, the `Session` class will handle all authentication for you.\nFor example, it will compute the SHA256 signature that must be included\nin your HTTP headers.\n\n#### Properties\n\n- `.session_id: int` - A 63-bit positive integer uniquely identifying this\n`Session`. `Session` will include this number in requests to Procuret API, so\nthat Procuret API can identify you.\n- `.api_key` - A 192-bit random number encoded in urlsafe base64 and generated\nin a cryptographically secure manner. `Session` will use this key to sign your\nrequests to Procuret API using the SHA256 algorithm.\n\n#### Methods\n\n##### `.create_with_email(...) -> Session`\n\nUse `.create_with_email()` to create a new `Session`. This is analogous to\n\"logging in\" to the Procuret API.\n\n###### Parameters\n\n1. `email: str` - Your account email\n2. `plaintext_secret: str` - Your plaintext passphrase\n3. `perspective: Perspective` - an instance of `Perspective`\n4. `code: str` - A two factor authentication code. Obtain via `SecondFactorCode`\n5. `lifecycle: Lifecycle` - Defaults to `.LONG_LIVED`\n\n###### Example Usage\n\n```python\nsession = Session.create_with_email(\n email='me@somedomain.com',\n plaintext_secret='excellent passphrase',\n perspective=Perspective.SUPPLIER,\n code='123456'\n)\n```\n\n##### `.from_interactive_prompt() -> Session`\n\nCall this method to use an interactive `Session` creation procedure.\n\n### `SecondFactorCode`\n\n`SecondFactorCode` allows you to generate two-factor authentication codes for\nuse in creating `Session` instances.\n\n#### Methods\n\n##### `.create_with_email(...) -> None`\n\nThis method will cause a two-factor authorisation code to be sent to the\ncommunication method associated with your Procuret account. You can then\nuse that code as the `code` parameter when creating a `Session`.\n\n###### Parameters\n\n1. `email: str` - Your account email\n2. `plaintext_secret: str` - Your plaintext passphrase\n3. `perspective: Perspective` - an instance of `Perspective`\n\n###### Example Usage\n\n```python\nSecondFactorCode.create_with_email(\n email='someone@somewhere.com',\n plaintext_secret='excellent passphrase',\n perspective=Perspective.BUSINESS\n)\n```\n\n### `InstalmentLink`\n\n`InstalmentLink` facilitates the creation of customised links to the Procuret\nInstalment Product (PIP). PIP allows a customer Business to pay for a purchase\nover time, while you the Supplier are paid upfront.\n\nWhen you create an `InstalmentLink`, you can ask Procuret to send an email\nto the customer Business on your behalf.\n\n#### Properties\n\n- `.invitee_email: str` - The email address you associated with the link\n- `.invoice_amount: Decimal` - The invoice amount presented by the link\n- `.invoice_identifier: str` - The invoice ID presented by the link\n- `.url: str` - The URL of the link\n\n#### Methods\n\n##### `.create(...) -> InstalmentLink`\n\n###### Parameters\n\n1. `supplier: Union[int, EntityHeadline]` - Either the unique integer\nidentifier of your Supplier entity in Procuret, or an instead of\n`EntityHeadline` describing your Supplier entity.\n2. `invoice_amount: Decimal` - The amount that you wish to charge the customer,\nin Australian dollars.\n3. `invoice_email: str` - The email address you wish to associate with this\nlink.\n4. `invoice_identifier: str` - Your own identifier for the invoice. For\nexample, you might use an invoice number from your accounting system.\n5. `communication: CommunicationOption` - An instance of `CommunicationOption`,\nwhich will tell Procuret API what you want it to do with the supplied email\naddress.\n6. `session: Session` - An instance of `Session`, which will be used to\nauthenticate your request.\n\n###### Example usage\n\n```python\n# First we get a Session. In this case we authenticate with email and\n# passphrase. In a real integration, you might store the Session elsehwhere.\nsession = Session.create_with_email(\n email=email,\n plaintext_secret=secret,\n perspective=Perspective.SUPPLIER,\n code='12346' # Obtained via `SecondFactorCode`\n)\n\n# Now we use the Session in an InstalmentLink.create() call, along with\n# the parameters describing the link. By supplying\n# CommunicationOption.EMAIL_CUSTOMER, we tell Procuret that we would like\n# Procuret to send an email to the customer on our behalf inviting them\n# to pay using the link.\nlink = InstalmentLink.create(\n supplier=supplier_id,\n invoice_amount=Decimal('422.42'),\n invitee_email='someone@great-domain.org',\n invoice_identifier='T 055',\n communication=CommunicationOption.EMAIL_CUSTOMER,\n session=session\n)\n```\n\n### `Perspective`\n\nPerspective is an enumeration of possible angles from which a client\ncan engage with Procuret. If you wish to use Procuret services from\nthe perspective of a Supplier, you will create a `Session` with the\n`Perspective.SUPPLIER` case.\n\n#### Cases\n\n- `.SUPPLIER`\n- `.BUSINESS`\n\n### Lifecycle\n\nAn enumeration of possible `Session` lifecycles - A \"short lived\" `Session` will\nexpire after a period of disuse. A \"long lived\" `Session` will never expire,\nand must be manually deleted.\n\nConsider opting for a short-lived `Session` wherever practical, to reduce the\nprobability of the stored credential being compromised.\n\n#### Cases\n\n- `.LONG_LIVED`\n- `.SHORT_LIVED`\n\n### `CommunicationOption`\n\nAn enumeration of instructions you can send Procuret in some contexts, to\ntell it how you wish for it to contact (or not contact) the a customer.\n\n#### Cases\n\n- `.EMAIL_CUSTOMER` - Procuret will contact the customer by email\n- `.DO_NOT_CONTACT_CUSTOMER` - Procuret will not try to contact the customer\n\n\n## Support\n\nPlease contact us anytime at [support@procuret.com](mailto:support@procuet.com)\nwith any questions. To chat with us less formally, please feel free to tweet\n[@hugh_jeremy](https://twitter.com/hugh_jeremy).\n\nFor more general information about Procuret, please visit\n[procuret.com](https://procuret.com).\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Procuret API Library",
"version": "0.0.43",
"project_urls": {
"About": "https://github.com/procuret/procuret-python",
"Github Repository": "https://github.com/procuret/procuret-python",
"Homepage": "https://github.com/procuret/procuret-python"
},
"split_keywords": [
"library",
"http",
"api",
"web",
"payments",
"finance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8b3de5d148b5cd0851884a035f45430ba2380baeb1fa2e51379c17f796dd8ec",
"md5": "8253e0f0ed8ec1b81c6ab8323fb6343d",
"sha256": "88c60cd7019d8288c502aaf51345408b3b40dc83eabbfabc422c5e7416887ef5"
},
"downloads": -1,
"filename": "procuret-0.0.43-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8253e0f0ed8ec1b81c6ab8323fb6343d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 57478,
"upload_time": "2024-04-05T04:09:18",
"upload_time_iso_8601": "2024-04-05T04:09:18.055615Z",
"url": "https://files.pythonhosted.org/packages/f8/b3/de5d148b5cd0851884a035f45430ba2380baeb1fa2e51379c17f796dd8ec/procuret-0.0.43-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1aa92c0f70dc49eacdc9d342ac92563921225fea93a22e55ddf4145a9a26cb3b",
"md5": "ef15fd2df33830494a0baca4d0ac98f2",
"sha256": "ec605420008bc6a0d95a5b5484c3e34cce8977cfff1678cfa38ee22122087821"
},
"downloads": -1,
"filename": "procuret-0.0.43.tar.gz",
"has_sig": false,
"md5_digest": "ef15fd2df33830494a0baca4d0ac98f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 36387,
"upload_time": "2024-04-05T04:09:20",
"upload_time_iso_8601": "2024-04-05T04:09:20.349382Z",
"url": "https://files.pythonhosted.org/packages/1a/a9/2c0f70dc49eacdc9d342ac92563921225fea93a22e55ddf4145a9a26cb3b/procuret-0.0.43.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-05 04:09:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "procuret",
"github_project": "procuret-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "procuret"
}
JSON
