diff --git a/README.md b/README.md index 247c464..a64ee60 100644 --- a/README.md +++ b/README.md @@ -1,136 +1,54 @@ -# Mifiel Python Library +# Mifiel Python API Client [![Build Status][travis-image]][travis-url] [![PyPI version][pypi-image]][pypi-url] -Python library for [Mifiel](https://www.mifiel.com) API. -Please read our [documentation](http://docs.mifiel.com) for instructions on how to start using the API. +Python SDK for the [Mifiel](https://www.mifiel.com) API. -## Installation - -```bash -pip install mifiel -``` - -## Usage +## Documentation -For your convenience Mifiel offers a Sandbox environment where you can confidently test your code. +API reference, guides, and examples: -To start using the API in the Sandbox environment you need to first create an account at [app-sandbox.mifiel.com](https://app-sandbox.mifiel.com). +- English: https://docs.mifiel.com/en/ +- Español: https://docs.mifiel.com/es/ -Once you have an account you will need an APP_ID and an APP_SECRET which you can generate in [app-sandbox.mifiel.com/settings/access-tokens](https://app-sandbox.mifiel.com/settings/access-tokens). +This README covers installation and client setup only. -By default the client talks to production (`https://app.mifiel.com`). For sandbox, call `client.use_sandbox()` (uses `https://app-sandbox.mifiel.com`), or override with `client.set_base_url(...)`. - -### Document methods: - -For now, the only methods available are **find** and **create**. Contributions are greatly appreciated. - -- Find: - -```python -from mifiel import Document, Client -client = Client(app_id='APP_ID', secret_key='APP_SECRET') +## Installation -doc = Document.find(client, 'id') -document.original_hash -document.file -document.file_signed -# ... +```bash +pip install mifiel ``` -- Create: - -```python -from mifiel import Document, Client -client = Client(app_id='APP_ID', secret_key='APP_SECRET') - -signatories = [ - { - 'name': 'Signer 1', - 'email': 'signer1@email.com', - 'tax_id': 'AAA010101AAA' - }, - { - 'name': 'Signer 2', - 'email': - 'signer2@email.com', - 'tax_id': 'AAA010102AAA' - } -] -doc = Document.create(client, signatories, file='test/fixtures/example.pdf') - -doc.id # -> '7500e528-ac6f-4ad3-9afd-74487c11576a' -``` +## Setup -- Save Document related files +1. Create an account (production or [sandbox](https://app-sandbox.mifiel.com)). +2. Generate an `APP_ID` and `APP_SECRET` in [Access Tokens](https://app-sandbox.mifiel.com/settings/access-tokens). +3. Configure the client: ```python -from mifiel import Document, Client -client = Client(app_id='APP_ID', secret_key='APP_SECRET') +from mifiel import Client -doc = Document.find(client, 'id') -# save the original file -doc.save_file('path/to/save/file.pdf') -# save the signed file (original file + signatures page) -doc.save_file_signed('path/to/save/file-signed.pdf') -# save the signed xml file -doc.save_xml('path/to/save/xml.xml') +client = Client(app_id='APP_ID', secret_key='APP_SECRET') +# Production is the default (https://app.mifiel.com). +# For sandbox: +client.use_sandbox() +# Or override the base URL: +# client.set_base_url('https://app-sandbox.mifiel.com') ``` ## Development -### Install dependencies - -This project uses [poetry](https://python-poetry.org/) which you can install [here](https://python-poetry.org/docs/#installation), the just run `install` command: +This project uses [Poetry](https://python-poetry.org/docs/#installation): ```bash poetry install -``` - -## Test - -Just clone the repo, install dependencies as you would in development and run: - -```bash poetry run pytest ``` -## Publish - -The package is published to [PyPI](https://pypi.org/project/mifiel/) as `mifiel` using Poetry. Bump the version in `pyproject.toml` (and `CHANGELOG.md`) first — PyPI will reject a version that already exists. - -Create an [API token](https://pypi.org/manage/account/token/) on PyPI (you need Maintainer or Owner on the project), then configure Poetry: - -```bash -poetry config pypi-token.pypi pypi-AgEIcHlwaS5vcmc... -``` - -Or set it for a single session: - -```bash -export POETRY_PYPI_TOKEN_PYPI=pypi-AgEIcHlwaS5vcmc... -``` - -Build and publish: - -```bash -poetry install --no-interaction -poetry run pytest -poetry publish --build -``` - -To dry-run against [TestPyPI](https://test.pypi.org/): - -```bash -poetry config repositories.testpypi https://test.pypi.org/legacy/ -poetry config pypi-token.testpypi pypi-... -poetry publish --repository testpypi --build -``` - ## Contributing -1. Fork it ( https://github.com/Mifiel/python-api-client/fork ) +1. Fork it (https://github.com/Mifiel/python-api-client/fork) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) diff --git a/mifiel/__init__.py b/mifiel/__init__.py index 9438db1..a37c86f 100644 --- a/mifiel/__init__.py +++ b/mifiel/__init__.py @@ -5,6 +5,7 @@ from .base import Base from .document import Document from .template import Template +from .webhook import Webhook __all__ = [ '__version__', @@ -13,4 +14,5 @@ 'Base', 'Document', 'Template', + 'Webhook', ] diff --git a/mifiel/webhook.py b/mifiel/webhook.py new file mode 100644 index 0000000..1ec8789 --- /dev/null +++ b/mifiel/webhook.py @@ -0,0 +1,69 @@ +from mifiel import Base + + +class Webhook(Base): + """Account-level webhook subscriptions. + + See https://docs.mifiel.com/en/#tag/Webhooks + """ + + def __init__(self, client): + Base.__init__(self, client, 'webhooks') + + @staticmethod + def find(client, webhook_id): + webhook = Webhook(client) + webhook.process_request('get', url=webhook.url(webhook_id)) + return webhook + + @staticmethod + def all(client): + base = Webhook(client) + response = base.execute_request('get', url=base.url()) + result = [] + for single in response.json(): + obj = Webhook(client) + obj.set_data(single) + result.append(obj) + return result + + @staticmethod + def create(client, url, callback_type): + webhook = Webhook(client) + webhook.process_request( + 'post', + json={ + 'url': url, + 'callback_type': callback_type, + }, + ) + return webhook + + @staticmethod + def delete(client, webhook_id): + base = Webhook(client) + response = base.execute_request('delete', url=base.url(webhook_id)) + if response.content: + return response.json() + return None + + def trigger(self, resource, instant=False): + """Trigger delivery for this webhook. + + Args: + resource: UUID of the related resource included in the callback payload. + instant: When True, deliver immediately once instead of enqueueing retries. + """ + if not self.id: + raise ValueError('Webhook id is required to trigger') + response = self.execute_request( + 'post', + url=self.url('{}/trigger'.format(self.id)), + json={ + 'resource': resource, + 'instant': instant, + }, + ) + if response.content: + return response.json() + return None