Inspetor Antifraud library for Python.
Project description
Inspetor Antifraud
Inspetor Antifraud library for Python.
Description
This README file should help you to integrate the Inspetor Python library into your product.
Setup Guide
This is the step-by-step Inspetor integration:
PyPI
PyPI is the largest Python package repository there is and it's common to install python libraries with the "pip install" command. To install our library, you need to use the following command:
pip install inspetor
If you get no errors, you'll be able to see the Inspetor version installed using the "pip freeze" command (which will show every library you've installed in your environment).
Library setup
Now, you're almost able to call the library from inside your code. But first, you need to set some configuration values (app id, tracker name, and dev env):
inspetor_config = {
"APP_ID": "123",
"TRACKER_NAME": "123",
"DEV_ENV": True
}
The APP_ID is a unique identifier that the Inspetor Team will provide you when you start the paid integration with us. The TRACKER_NAME is a name that will help us find your data in our database and we'll provide you a couple of them. Lastly, DEV_ENV is a boolean statement that you set to inform if you want to use the development or production environment. It's false by default.
We strongly recommend you to create an Inspetor class in your code to start our library. That's where you're going to insert the Inspetor config you wrote and, with that, retrieve our client. Confusing? Relax, we're kind enough to show you how to do it.
import inspetor
class InspetorClass:
def __init__(self):
"""
Let's instantiate the library!
"""
self.inspetor = inspetor.InspetorClient(inspetor_config)
def get_client(self):
"""
return object of type InspetorClient
"""
return self.inspetor
...
Now, wherever you need to call some Inspetor function, you just need to import this Class and voilà.
P.S.: you can place your inspetor_config dictionary wherever you think is better - it could be just before instantiating InspetorClient or into a config file that you include in this class.
Library Calls
If you've already read the general Inspetor documentation, you should be aware of all of Inspetor requests and trackers, so our intention here is just to show you how to use the Python version of some of them.
Let's imagine that you want to put a tracker in your "create transaction" flow to send data to Inspetor. First, you need to create an InspetorSale
object (you can find more about Inspetor objects here) and then pass this object as an argument to the function track_inspetor_sale_creation
.
Here is the snippet of the example above:
from niceCompany.inspetor.inspetor_class import InspetorClass;
class Sale:
...
def some_company_function(self):
"""
company_sale is an example object you might have in your code, which contains sale data
"""
inspetor_sale = self.inspetor_sale_builder(company_sale)
self.inspetor = InspetorClass()
if inspetor_sale is not None:
inspetor.get_client.track_sale_creation(inspetor_sale)
def inspetor_sale_builder(self, company_sale):
model = inspetor.get_client.get_inspetor_sale()
model.id(company_sale.get_id());
model.account_id(company_sale.user_id)
model.status(company_sale.sale_status);
model.is_fraud(company_sale.fraud);
model....
return model
...
Following this code and assuming you've built your model with all the required parameters (find out each Model's required parameters here), whenever some_company_function
runs, the Inspetor code inside will send the information about the transaction to Inspetor.
We're using an auxiliary function inspetor_sale_builder
to build the Sale Model object but you could do it differently and place it where it suits your needs better. You could set this inspetor_sale_builder
inside your InspetorClass
that we talked about some lines above, for example. There are some more tips in the Best Practices & Tips section.
Models
The last snippet was a simple example to show how you should call our library and use our models. But now we're gonna talk about all of our Models, hoping you understand that some of them are not tracked themselves but they're needed inside others. Take a look!
Principal models:
- Auth: model you fill with login or logout data.
"""
Calling an instance of Model
"""
inspetor_auth = self.inspetor.get_inspetor_auth()
"""
Filling model with auth data
"""
inspetor_auth.account_email = "test@email.com"
inspetor_auth.account_id = "123" # you need only to pass the account_id if the login is successful
inspetor_auth.timestamp = datetime.timestamp(datetime.now())
- Account: model you fill with your user data. Account has
address
andbilling_address
as two non-required values and both are built with an object of theInspetorAddress
Model type.
"""
Calling an instance of Model
"""
inspetor_account = self.inspetor.get_inspetor_account();
"""
Filling model with account data
"""
inspetor_account.id = "123"
inspetor_account.name = "Test"
inspetor_account.email = "test@email.com"
inspetor_account.document = "12312312312"
inspetor_account.phoneNumber = "112345678"
inspetor_account.address = inspetor_account_address
inspetor_account.timestamp = datetime.timestamp(datetime.now())
- Event: model you fill with your event data (e.g. a party or forum info). The
address
is required here, so you must instantiate anInspetorAddress
Model object for an Event.
"""
Calling an instance of Model
"""
inspetor_event = self.inspetor.get_inspetor_event()
"""
Filling the model with event data
"""
inspetor_event.id = "123"
inspetor_event.name = "Name Test"
inspetor_event.description = "Description Test"
inspetor_event.sessions = [
inspetor_event_session1,
inspetor_event_session1
]
inspetor_event.status = inspetor_event.PRIVATE_STATUS
inspetor_event.slug = "slug-test"
inspetor_event.creator_id = "124"
inspetor_event.is_physical = True
inspetor_event.categories = [
inspetor_event_category1,
inspetor_event_category2
]
inspetor_event.address = inspetor_event_address
inspetor_event.admins_id = ["123"]
inspetor_event.seating_options = ["Seating Option"]
inspetor_event.timestamp = datetime.timestamp(datetime.now())
- PassRecovery: model that must contain data from a password recovery or password reset request in your API.
"""
Calling an instance of Model
"""
inspetor_pass = self.inspetor.get_inspetor_pass_recovery()
"""
Filling model with password recovery data
"""
inspetor_pass.recovery_email = "test@email.com"
inspetor_pass.timestamp = datetime.timestamp(datetime.now())
- Sale: model that should be filled with sale data. The sale status has a fixed list of allowed values :
- "accepted" but you can use the Sale const like
Sale.ACCEPTED_STATUS
- "rejected" but you can use the Sale const like
Sale.REJECTED_STATUS
- "pending" but you can use the Sale const like
Sale.PENDING_STATUS
- "refunded" but you can use the Sale const like
Sale.REFUNDED_STATUS
- "manual_analysis" but you can use the Sale const like
Sale.MANUAL_ANALYSIS_STATUS
- "accepted" but you can use the Sale const like
"""
Calling an instance of Model
"""
inspetor_sale = self.inspetor.get_inspetor_sale()
"""
Filling model with sale data
"""
inspetor_sale.id = "123"
inspetor_sale.account_id = "456"
inspetor_sale.total_value = "123,00"
inspetor_sale.status = inspetor_sale.PENDING_STATUS
inspetor_sale.timestamp = datetime.timestamp(datetime.now())
inspetor_sale.items = [
self.get_default_item()
]
inspetor_sale.payment = inspetor_payment
- Transfer: model you fill with the transference data of an item (e.g. transfer of a ticket). The transfer status has fixed allowed values:
- "accepted" but you can use the Transfer const like
Transfer.ACCEPTED_STATUS
- "rejected" but you can use the Transfer const like
Transfer.REJECTED_STATUS
- "pending" but you can use the Transfer const like
Transfer.PENDING_STATUS
- "accepted" but you can use the Transfer const like
"""
Calling an instance of Model
"""
inspetor_transfer = self.inspetor.get_inspetor_transfer()
"""
Filling model with transfer data
"""
inspetor_transfer.id = "123"
inspetor_transfer.timestamp = datetime.timestamp(datetime.now())
inspetor_transfer.item_id = "123"
inspetor_transfer.sender_account_id = "123"
inspetor_transfer.receiver_email = "test@email.com"
inspetor_transfer.status = inspetor_transfer.PENDING_STATUS
Auxiliar models:
- Address: this model appears inside
InspetorAccount
andInspetorEvent
models and should be filled with data for a user, a credit card or an event.
"""
Calling an instance of Model
"""
inspetor_address = self.inspetor.get_inspetor_address()
"""
Filling model with address data
"""
inspetor_address.street = "Test Street"
inspetor_address.number = "123"
inspetor_address.zip_code = "123456"
inspetor_address.city = "Test City"
inspetor_address.state = "Test State"
inspetor_address.country = "Test Country"
inspetor_address.latitude = "123"
inspetor_address.longitude = "123"
- CreditCard: when your API processes a payment done with a credit card, this model will be used. It should be filled with the buyer's creditcard secure data.
"""
Calling an instance of Model
"""
inspetor_cc = self.inspetor.get_inspetor_card()
"""
Filling model with credit card data
"""
credit_card.first_six_digits = "123456"
credit_card.last_four_digits = "1234"
credit_card.holder_name = "Holder Name Test"
credit_card.holder_cpf = "Holder CPF Test"
credit_card.billing_address = inspetor_billing_address
- Item: when someone buys a ticket, for instance, this Model will be instantiated and filled with that ticket data.
"""
Calling an instance of Model
"""
inspetor_item = self.inspetor.get_inspetor_item()
"""
Filling model with item data
"""
inspetor_item.id = "123"
inspetor_item.event_id = "123"
inspetor_item.session_id = "123"
inspetor_item.seating_option = "Seating Option Test"
inspetor_item.price = "10"
inspetor_item.quantity = "123"
- Payment: this Model holds the transaction data (e.g. payment method or installments). The payment status has fixed allowed values:
- "credit_card" but you can use the Payment const like
Payment.CREDIT_CARD
- "boleto" but you can use the Payment const like
Payment.BOLETO
- "other" but you can use the Payment const like
Payment.OTHER_METHOD
- "credit_card" but you can use the Payment const like
"""
Calling an instance of Model
"""
inspetor_payment = self.inspetor.get_inspetor_payment()
"""
Filling model with payment data
"""
inspetor_payment.id = "123"
inspetor_payment.method = inspetor_payment.CREDIT_CARD
inspetor_payment.installments = "1"
inspetor_payment.credit_card = inspetor_credit_card
- Session: model you fill with event date session data.
"""
Calling an instance of Model
"""
inspetor_session = self.inspetor.get_inspetor_session()
"""
Filling model with session data
"""
inspetor_session.id = "123"
inspetor_session.datetime = int(1562934682) # it's the date of that event session in unix timestamp format
- Category: model you fill with event category data. In an event context it could be, for instance, "Show", "Lecture", "Art Exposition", etc.
"""
Calling an instance of Model
"""
inspetor_category = self.inspetor.get_inspetor_category()
"""
Filling model with category data
"""
inspetor_category.id = "123"
inspetor_category.name = "Cooltegory"
What you should notice
Not all of the Model's attributes are required but we deeply recommend you try to pass them all. On the other hand, some of them are super important and you should pass it correctly. Let's talk about some of them.
- Sale:
- is_fraud: it's an attribute that you must pass to indicate if a sale is fraudulent or not, even if it's something that we're providing to you (as part of postback process).
- Event:
- sessions: it's an attribute that you must pass even if you don't use the session's context. If that is the case, you just need to replicate some of your Event attributes, such as event_id and event_date, for example.
- Address:
- almost all fields: address is only required when you try to track an Event, but exists in the Account model as well.
- CreditCard:
- all fields: all of them are requested if you set the
payment_method
as "credit_card", so pay attention to that.
- all fields: all of them are requested if you set the
- Common requests:
- timestamp: some Models have setters and getters for this, as you can see in the general files, and you must provide us a UTC Unix timestamp.
Best Practices & Tips
In this part, we decided to share some nice practices we've discovered during development time and should help you with a cleaner integration.
- InspetorClass: we already told you about that but we think it's important for a cleaner integration. With this class, you don't need to pass your config every time and it creates a layer between our application and yours, where you can, for instance, create functions as model builders (we've already talked about that too) to keep all builders in one place. Here's a snippet of an
InspetorClass
with an example of builder.
import inspetor
class InspetorClass:
def __init__(self):
"""
Let's instantiate this awesome library!
"""
self.inspetor = InspetorClient(inspetor_config)
def get_client(self):
"""
return object of type InspetorClient
"""
return self.inspetor
def inspetor_auth_builder(self, auth_data) {
"""
param array auth_data
return object of type Inspetor.Model.Auth
"""
inspetor_auth = self.get_client.get_inspetor_auth()
inspetor_auth.account_email = auth_data.user_email
inspetor_auth.account_id = auth_data.account_id_login
inspetor_auth.timestamp = datetime.timestamp(datetime.now())
return inspetor_auth
...
Conclusion
WOW! It was lovely to work with you, my friend. We truly hope that our instructions were clear and effective. If you have any suggestions or find any bugs please feel free to contact us here.
Now you're invited to join our army against fraud 'cause STEALING IS BULLSHIT!
DPCL (dope cool)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.