def list_templates(
self,
page: int = 1,
page_size: int = 20,
fields: InvoiceListRequestField = InvoiceListRequestField.ALL
) -> PaypalApiBulkResponse[Invoice]:
""" Calls the paypal API to lists merchant-created templates with associated details. The associated details include
the emails, addresses, and phone numbers from the user's PayPal profile.
The user can select which values to show in the business information section of their template.
Keyword Arguments:
page {int} -- current page index (default: {1})
page_size {int} -- page size (how many elements per page) (default: {20})
fields {InvoiceListRequestField} -- The fields to return in the response (default: {InvoiceListRequestField.NONE})
Returns:
PaypalApiBulkResponse[Invoice] -- A list of invoices
"""
# TODO: There might be an error in the docs, the most logical response would be
# a page of templates, with the desired fields. This response must be tested.
params = {
'page': page,
'page_size': page_size,
'fields': fields.name.lower()
}
response = self._session.get(self._base_url, params)
if response.status_code != 200:
return PaypalApiBulkResponse.error(response)
return PaypalApiBulkResponse.success(
response, Invoice.serialize_from_json(response.json()))
def send_invoice(
self,
invoice_id: str,
subject: str,
note: str,
send_to_invoicer: bool,
send_to_recipient: bool,
additional_recipients: List[str] = [],
paypal_request_id: str = None) -> PaypalApiResponse[Invoice]:
"""Calls the paypal API to send or schedule an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:
If the invoice issue date is current or in the past, sends the invoice immediately.
If the invoice issue date is in the future, schedules the invoice to be sent on that date.
To suppress the merchant's email notification, set the send_to_invoicer body parameter to false.
To send the invoice through a share link and not through PayPal, set the send_to_recipient parameter to false in the notification object.
The send_to_recipient parameter does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.
Arguments:
invoice_id {str} -- invoice id
subject {str} -- The subject of the email that is sent as a notification to the recipient.
note {str} -- A note to the payer.
send_to_invoicer {bool} -- Indicates whether to send a copy of the email to the merchant.
send_to_recipient {bool} -- Indicates whether to send a copy of the email to the recipient.
Keyword Arguments:
paypal_request_id {str} -- Paypal request id for idempotence. (default: {None})
additional_recipients {List[str]} -- An array of one or more CC: emails to which notifications are sent. (default: {[]})
Returns:
PaypalApiResponse -- Api operation response status with parsed objects within
"""
response = None
url = parse_url(self._base_url, 'invoices', invoice_id, 'send')
body = json.dumps({
'subject': subject,
'note': note,
'send_to_invoicer': send_to_invoicer,
'send_to_recipient': send_to_recipient
})
if additional_recipients:
body['additional_recipients'] = [{
'email_address': x
} for x in additional_recipients]
if paypal_request_id:
response = self._session.post(
url, body, headers={'PayPal-Request-Id': paypal_request_id})
else:
response = self._session.post(url, body)
if response.status_code // 100 != 2:
return PaypalApiResponse.error(response)
if response.status_code == 200:
return PaypalApiResponse.success(
response, Invoice.serialize_from_json(response.json()))
return PaypalApiResponse.success(response)
def fully_update_invoice(
self,
invoice_id: str,
invoice: Invoice,
send_to_recipient: bool = True,
send_to_invoicer: bool = True) -> PaypalApiResponse[Invoice]:
"""Calls the paypal API to fully update an invoice. This call does not support partial updates
Arguments:
invoice_id {str} -- invoice id
invoice {Invoice} -- invoice with the updated info
Keyword Arguments:
send_to_recipient {bool} -- Indicates whether to send the invoice update notification to the recipient. (default: {True})
send_to_invoicer {bool} -- Indicates whether to send the invoice update notification to the merchant. (default: {True})
Returns:
PaypalApiResponse -- Api operation response status with parsed objects within
"""
params = {
'send_to_recipient': send_to_recipient,
'send_to_invoicer': send_to_invoicer
}
response = self._session.put(parse_url(self._base_url, 'invoices',
invoice_id),
json.dumps(invoice.to_dict()),
params=params)
# There seems to be a copy/paste mistake in the docs
# It says no content but has a response within it.
if response.status_code // 100 != 2:
return PaypalApiResponse.error(response)
json_response = response.json()
if json_response:
return PaypalApiResponse.success(
response, Invoice.serialize_from_json(json_response))
return PaypalApiResponse.success(response)
def create_draft_invoice(self, invoice: Invoice) -> PaypalApiResponse:
"""Calls the paypal API to generate an invoice draft.
Arguments:
invoice {Invoice} -- the invoice information
Returns:
PaypalApiResponse -- The paypal API response
"""
response = self._session.post(parse_url(self._base_url, 'invoices'),
json.dumps(invoice.to_dict()))
if response.status_code != 201:
return PaypalApiResponse.error(response)
return PaypalApiResponse.success(response)
def show_template_details(self,
template_id: str) -> PaypalApiResponse[Template]:
"""Shows the details for a template by it's id
Arguments:
template_id {str} -- The template id
Returns:
PaypalApiResponse[Template] -- Response status with a Template object
"""
response = self._session.get(parse_url(self._base_url, template_id))
if response.status_code != 200:
return PaypalApiResponse.error(response)
return PaypalApiResponse.success(
response, Invoice.serialize_from_json(response.json()))
def show_invoice_details(self,
invoice_id: str) -> PaypalApiResponse[Invoice]:
"""Calls the paypal API to show details for an invoice.
Arguments:
invoice_id {str} -- invoice id
Returns:
PaypalApiResponse -- Api operation response status with parsed objects within
"""
response = self._session.get(
parse_url(self._base_url, 'invoices', invoice_id))
if response.status_code != 200:
return PaypalApiResponse.error(response)
return PaypalApiResponse.success(
response, Invoice.serialize_from_json(response.json()))
def list_invoices(self,
page: int = 1,
page_size: int = 10,
total_required: bool = True,
fields: List[str] = []) -> PaypalPage[Invoice]:
"""Calls the paypal API to get an invoice page.
Arguments:
page {int} -- current page
page_size {int} -- page size
total_required {bool} -- total count required
fields {List[str]} -- fields to be searched
Returns:
PaypalPage -- The paged elements in paypal API paged response
"""
query_params = {
'page': page,
'page_size': page_size,
'total_required': total_required
}
if fields:
query_params['fields'] = ','.join(fields)
response = self._session.get(parse_url(self._base_url, 'invoices'),
query_params)
if response.status_code != 200:
return PaypalPage.error(response)
json_response = response.json()
items = [
Invoice.serialize_from_json(x)
for x in json_response.get('items', [])
]
links = [
ActionLink(x['href'], x['rel'], x.get('method', 'GET'))
for x in json_response.get('links', [])
]
return PaypalPage.success(response, json_response.get('total_items'),
json_response.get('total_pages'), items,
links)
def search_invoices(self, page: int, page_size: int, total_required: bool,
search: InvoiceSearchRequest) -> PaypalPage[Invoice]:
"""Searches for and lists invoices that match search criteria.
If you pass multiple criteria, the response lists invoices
that match all criteria.
Arguments:
page {int} -- current page
page_size {int} -- page size
total_required {bool} -- total count required
search {InvoiceSearchRequest} -- search criteria to be matched
Returns:
PaypalPage[Invoice] -- The paged elements in paypal API paged response
"""
query_params = {
page: page,
page_size: page_size,
total_required: total_required
}
response = self._session.post(parse_url(self._base_url,
'search-invoices'),
json.dumps(search.to_dict()),
params=query_params)
if response.status_code != 200:
return PaypalPage.error(response)
json_response = response.json()
items = [
Invoice.serialize_from_json(x) for x in json_response['items']
]
links = [
ActionLink(x['href'], x['rel'], x.get('method', 'GET'))
for x in json_response['links']
]
return PaypalPage.success(response, json_response.get('total_items'),
json_response.get('total_pages'), items,
links)