intellihr-pyxero 0.0.2

PyXero
======

[](https://travis-ci.org/freakboy3742/pyxero)

PyXero 是一个 Python API，用于访问 [Xero](https://developer.xero.com)
记账工具提供的 REST API。它允许访问公共、私有和合作伙伴应用程序。

## 快速入门：

使用 python 包管理器安装这个库：

```
pip install pyxero
```

你需要按照 [Xero 开发者文档](https://developer.xero.com/documentation/) 进行注册你的申请。执行以下操作：

### 部署

要将此库部署到 pypi，请增加 `xero/__init__.py` 中的版本号，并使用 `python3 -m twine upload dist/*` 参考以下 https://packaging.python.org/tutorials/packaging-projects/而不是 `python3 -m twine upload --repository-url https://test.pypi.org/legacy/dist/*`

### 公共应用程序

公共应用程序使用 3 步 OAuth 过程。

当您 [向 Xero 注册您的公共应用程序](https://developer.xero.com/documentation/auth-and-limits/public-applications/) 时，您将获得一个
**Consumer Key** 和一个 * *消费者秘密**。这两个都是字符串。

要访问 Xero API，您必须首先创建一些凭据：

```python
>>> from xero.auth import PublicCredentials
>>> credentials = PublicCredentials(<consumer_key>, <consumer_secret>)
>>> print credentials.url
'http://my.xero.com/.....'
```

你现在引导用户访问由 `credentials.url` 描述的 URL。他们
将被要求登录其 Xero 帐户，然后显示一个请求以
验证您访问用户帐户的请求。当允许访问时，
他们将被引导到一个页面，该页面为他们提供一个 6 位数的验证码。
将此验证器编号放入字符串中，然后在凭据
对象上调用 `verify()`:

```python
>>> credentials.verify(<verifier string>)
```

这将验证您的凭据，并检索访问权限令牌。你可以
然后使用您的凭据来实例化 Xero API 的实例::

```python
>>> from xero import Xero
>>> xero = Xero(credentials)
```

### 带有回调验证的

公共应用程序 公共应用程序也可以使用回调 URI 进行验证。如果使用这种
方法，用户将不会获得验证码。相反，
当他们授权 OAuth 请求时，他们的浏览器将被重定向到
预配置的回调 URI，这会将验证令牌
直接传递给您的应用程序。

要使用回调，您必须提供域作为 Xero 应用程序
注册的一部分；然后，您提供该域下的 URL 作为第三个参数
创建凭证时:

``python
>>> credentials = PublicCredentials(<consumer_key>, <consumer_secret>, <callback_uri>)
>>> print credentials.url
'http://my.xero.com/... ..'
```

当用户授权访问他们的 Xero 帐户时，
将使用三个 GET 参数调用 `callback_url`：

* `oauth_token`：此请求所属的 oauth_token
* `oauth_verifier`：验证者字符串
* ` org`：允许访问的组织的标识符。

然后可以使用验证器来验证凭据，就像手动
过程一样。

### 重建公共凭证

公共应用程序使用 3 步 OAuth 过程，如果您
Web 应用程序，您通常会在
验证步骤中丢失凭据对象。这意味着您需要能够
在提供验证后恢复凭证对象。

凭证对象的 `state` 属性包含
重建凭证实例所需的所有详细信息：

```python
>>> saved_state = credentials.state
>>> print saved_state
{'consumer_key': '...' , 'consumer_secret': '...', ...}

>>> new_credentials = PublicCredentials(**saved_state)
```

### Private Applications

如果使用 Private 应用程序，您需要安装 `PyCrypto`，一个纯
Python 加密模块。你'
证书，并提交该证书作为
向 Xero 注册您的应用程序的一部分。有关详细信息，请参阅 [Xero 开发人员文档](https://developer.xero.com/)
。

当您 [向 Xero 注册您的私人应用程序](https://developer.xero.com/documentation/auth-and-limits/private-applications/) 时，您将获得一个
**Consumer Key**。您还将获得一个 **Consumer secret** - 这可以
忽略。

使用私有凭证比公共凭证简单得多，
因为没有验证步骤——验证是使用 RSA
签名的 API 请求管理的：

```python
>>> from xero import Xero
>>> from xero.auth import PrivateCredentials
>>> with open(<path to rsa key file>) as keyfile:
... rsa_key = keyfile.read()
>>> credentials = PrivateCredentials(<consumer_key>, rsa_key)
>>> xero = Xero(credentials)
` ``

[按照这些步骤](https://developer.xero.com/documentation/api-guides/create-publicprivate-key/) 生成公钥/私钥对来签署您的请求。当您在 https://app.xero.com 创建您的 Xero Private 应用程序时，您将上传您的公钥。您将使用私钥（也称为 RSA 密钥）来生成您的 oAuth 签名。

RSA 密钥是一个多行字符串，类似于：

-----BEGIN RSA PRIVATE KEY-----
MIICXgIBAAKBgQDWJbmxJjQLGM76sZkk2EhsdpV0Gxtrhzh/wiNBGffa5JHV/Ex4
....
mtXGQjKqsOpuCw7HwgnRQUWKYbaJ3a+yTCFjVwa9keQhDQ==
-----END RSA PRIVATE KEY-----

您可以通过将私钥
文件的内容读入变量或将密钥值存储为常量来获取此字符串。如果您选择
将键值存储为常量，请记住两件事：

* **请勿在任何情况下**将此文件检查到公共
存储库中。这是您的身份，任何有权访问此文件的人
都可以伪装成您。 * 确保字符串的 ``-----BEGIN PRIVATE KEY-----`` 部分

之前没有前导空格。### 合作伙伴应用程序合作伙伴应用程序身份验证的工作方式与使用的 3 步 OAuth 类似






公共应用程序，但带有 RSA 签名的请求。合作伙伴 OAuth 令牌仍有
30 分钟的有效期，但可以随时换成新令牌。

当您[向 Xero 注册您的合作伙伴应用程序](https://developer.xero.com/documentation/auth-and-limits/partner-applications/) 时，您将拥有一个**Consumer Key**、**Consumer秘密** 和 **RSA 密钥**。这三个元素都是必需的。


```python
>>> from xero import Xero
>>> from xero.auth import PartnerCredentials
>>> credentials = PartnerCredentials(<consumer_key>, <consumer_secret>,
... <rsa_key>)
>>> xero = Xero(credentials )
```

长时间使用 API 时，
当它们到期时。

```python
>>> if credentials.expired():
... credentials.refresh()
```

**重要的**：``credentials.state`` 在令牌交换后发生变化。一定要坚持
新的状态。


## 使用 Xero API

*此 API 正在进行中。目前，没有包装层
来帮助创建真实对象，它只
是以 Xero API 提供的确切格式返回字典。
这将在 1.0 之前变为更有用

的 API* Xero API 对象公开了一个用于检索和更新对象的简单 API。
例如处理联系人::

```python
# 获取所有联系人对象
>>> xero.contacts.all()
[{...contact info...}, {...contact info...}, {...contact info...}, ...]

# 获取特定的联系人对象
>>> xero.contacts .get(u'b2b5333a-2546-4975-891f-d71a8a640d23')
{...contact info...}

# 检索自 2013 年 1 月 1 日以来更新的所有联系人
>>> xero.contacts.filter(since=datetime(2013, 1, 1))
[{...contact info...}, {...contact info...}, {...contact info...}]

# 检索所有姓名为 'John Smith' 的联系人
>>> xero.contacts.filter(Name='John Smith')
[{...联系信息...}, {...联系信息...}, {...联系信息...}]

# 检索名字以'John'开头的所有联系人
>>> xero.contacts.filter(Name__startswith='John')
[{...contact info...}, {...联系信息...}，{...联系信息...}]

# 检索名字以'Smith'结尾的所有联系人
>>> xero.contacts.filter(Name__endswith='Smith')
[{...contact info...}, {...contact info...}, { ...contact info...}]

# 获取所有以 'John' 开头并以 'Smith' 结尾的联系人
>>> xero.contacts.filter(Name__startswith='John', Name__endswith='Smith')
[{ ...contact info...}, {...contact info...}, {...contact info...}]

# 检索名称中包含'mit'的所有联系人
>>> xero.contacts.filter (Name__contains='mit')
[{...contact info...}, {...contact info...}, {...contact info...}]

# 创建一个新对象
>>> xero .contacts.put({...联系信息...})

# 创建多个新对象
>>> xero.contacts.put([{...contact info...}, {...contact info...}, {...contact info...}])

# 保存更新到现有对象
>>> c = xero.contacts.get(u'b2b5333a-2546-4975-891f-d71a8a640d23')
>>> c['Name'] = 'John Smith'
>>> xero.contacts.save(c )

# 保存多个对象
>>> xero.contacts.save([c1, c2])
```

可以用 Django 方式构建复杂的过滤器，例如检索联系人的发票：

```python
>>> xero .invoices.filter(Contact_ContactID='83ad77d8-48a7-4f77-9146-e6933b7fb63b')
```

此 API 不支持的过滤器也可以使用“原始”模式构建，如下所示：
```python
>>> xero.invoices.filter(raw='AmountDue > 0')
```

处理大量数据时要小心，Xero API 的
响应时间会越来越长，否则会返回错误。如果查询可能
返回超过 100 个结果，您应该使用 ``page`` 参数::

```python
# Grab 100 invoices created after 01-01-2013
>>> xero.invoices.filter(since= datetime(2013, 1, 1), page=1)
```

你也可以排序返回的结果::

```python
# 抓取按EmailAddress排序的联系人
>>> xero.contacts.filter(order='EmailAddress DESC')
```

对于发票（和其他可以作为 PDF 检索的对象），
通过设置 Accept 标头来访问 PDF：

```python
# Fetch a PDF
invoice = xero.invoices.get('af722e93-b64f-482d-9955-1b027bfec896', \
headers={'Accept': 'application/pdf'})
# 将 PDF 流式传输给用户（Django 特定示例）
response = HttpResponse (invoice, content_type='application/pdf')
response['Content-Disposition'] = 'attachment; filename="invoice.pdf"'
返回响应
```

使用相关对象的 Xero GUID 支持下载和上传附件::

```python
# 列出联系人上的附件
>>> xero.contacts.get_attachments(c[ 'ContactID'])
[{...attachment info...}, {...attachment info...}]

# 将 PDF 附加到联系人
>>> f = open('form.pdf', 'rb '
>>> xero.contacts.put_attachment(c['ContactID'], 'form.pdf', f, 'application/pdf')
>>> f.close()

>>> xero.contacts.put_attachment_data(c[' ContactID'], 'form.pdf', data, 'application/pdf')

# 下载附件
>>> f = open('form.pdf', 'wb')
>>> xero.contacts.get_attachment(c[ 'ContactID'], 'form.pdf', f)
>>> f.close()

>>> data = xero.contacts.get_attachment_data(c['ContactID'], 'form.pdf')
```

这个一样以下 API 对象存在 API 模式：

* 账户
* 附件
* 银行交易
* 银行转账
* BrandingThemes
* ContactGroups
* 联系人
* CreditNotes
* 货币
* 员工
* ExpenseClaims
* Invoices
* Items
* Journals
* ManualJournals
* Organization
* Overpayments
* Payments
* Prepayments
* Purchase Orders
* Receipts
* RepeatingInvoices
* Reports
* TaxRates
* TrackingCategories
* Users


## Payroll

为了从 Xero 访问工资单方法，您可以这样做像这样：

```
xero.payrollAPI.payruns.all()
```

在 payrollAPI 中，您可以访问：

* employees
* leaveapplications
* payitems
* payrollcalendars
* payruns
* payslip *
timesheets


## 在后台

在 Xero API 周围使用包装器是一个非常好的特性，但了解幕后究竟
发生了什么也很有趣。

### 过滤运算符

``filter`` 运算符在 Xero API 中包装了“where”关键字。

```python
# Retrieves all contacts name is "John"
>>> xero.contacts.filter(name="John")

# 触发这个 GET 请求：
Html 编码：<XERO_API_URL>/Contacts?where=name%3D% 3D%22John%22 未
编码：<XERO_API_URL>/Contacts?where=name=="John"
```

几个参数用编码的 '&&' 字符分隔：

``python
# 检索名字为“John”的所有联系人”，姓氏是“Doe”


# 触发这个 GET 请求：
Html 编码：<XERO_API_URL>/Contacts?where=lastname%3D%3D%22Doe%22%26%26firstname%3D%3D%22John%22
非编码：<XERO_API_URL>/Contacts?where=lastname =="Doe"&&firstname=="John"

```

下划线自动转换为“点”：
``python
# 检索所有名为“John”的联系人
>>> xero.contacts.filter(first_name="John ")

# 触发这个 GET 请求：
Html 编码：<XERO_API_URL>/Contacts?where=first.name%3D%3D%22John%22%
非编码：<XERO_API_URL>/Contacts?where=first.name=="John"
```

## Contributing

如果你要运行 PyXero 测试套件，除了依赖项
对于 PyXero，您需要将以下依赖项添加到您的环境中：

mock >= 1.0

Mock 不包含在正式依赖项中，因为它们不是
PyXero 正常操作所必需的。它仅用于测试目的。

一旦你安装了这些依赖项，你可以通过
从项目的根目录运行以下命令来运行

测试套件

： https://github.com/freakboy3742/pyxero/issues）。
报告问题时，如果您可以提供
重现说明，将非常有帮助——调用顺序和/或
可用于重现问题的测试数据。

可以通过拉取请求提交新功能或错误修复。如果您希望
快速合并您的拉取请求，请确保您包含
针对您正在添加/修复的行为的回归测试，或者提供一个
很好的解释，说明为什么无法进行回归测试。