LaTiendaCOOP backend

This README aims to document functionality of backend as well as required steps to get it up and running.

Table of Contents

• First Steps
  • Load location data
  • Load taxonomy data
• Company Endpoints
• Product Endpoints
• Core Endpoints
• History Endpoints
• Stats Endpoints
• Shop Integrations
  • WooCommerce
• Product Search
• Massive Data Load Endpoints
  • COOP and Managing User Data Load
  • Product Data Load
• GeoIP Setup
• Tags
• Development Utils
  • Fake product data generation

First Steps

• Clone repository: git clone git@bitbucket.org:enreda/back-latienda.git

• Use docker image for Postgis

docker run --name postgis -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -d -p 5432:5432 postgis/postgis

• Create file .env from example.env and populate fields correctly

From inside the project's folder:

• Make migrations:

python manage.py makemigrations core geo companies products history stats
python manage.py migrate

• Start server in development mode: python manage.py runserver

Load Location Data

To load initial location data use: python manage.py loadgisdata

Load Taxonomy Data

This data serves as initial Tags

To load initial set of tags: python manage.py addtaxonomy

Company Endpoints

CompanyViewSet

Queryset: validated Company instances only

Permissions:

• anon user: safe methods
• auth user: full access where user is company creator

MyCompanyViewSet

Queryset: Company instances where user is creator

Permissions:

• anon user: no access
• auth user: full access

AdminCompanyViewSet

Queryset: all Company instances, validated or not

Permissions: only accesible to authenticated users with role SITE_ADMIN

random_company_sample

Method view that returns a randome sample of companies

By default it returns 6 instances, but can be customized through parameter size

Product Endpoints

ProductViewSet

Endpoint url: /api/v1/products/

Queryset: active Product instances only

Permissions:

• anon user: safe methods
• auth user: full access where user is product creator

MyProductsViewSet

Endpoint url: /api/v1/my_products/

Queryset: Product instances where user is creator

Permissions:

• anon user: no access
• auth user: full access

AdminProductsViewSet

Endpoint url: /api/v1/admin_products/

Queryset: all Product instances, acgtive or not

Permissions: only accesible to authenticated users with role SITE_ADMIN

load_coop_products [POST]

Endpoint url: /api/v1/load_products/

Method view that reads a CSV file.

product_search [GET]

Endpoint url: /api/v1/search_products/

Allows searching of Products to all users

Parameters:

• q: used for search [MANDATORY]
• limit: max number of returned instances [OPTIONAL]
• offset: where to start counting results [OPTIONAL]
• shipping_cost: true/false
• discount: true/false
• category: string
• tags: string
• order: string (newest/oldest)
• price_min: int
• price_max: int

purchase_email [POST]

Endpoint url: /api/v1/purchase_email/

Sends email to company manager about the product that the user wants to purchase, and sends confirmation email to user.

Parameters:

• email: mandatory for anonymous users
• telephone
• company
• product
• comment

Core Endpoints

CustomUserViewSet

Endpoint url: /api/v1/users/

Queryset: all CustomUser instances

Permissions:

• anon user: only POST to register new user
• auth user: no access
• admin user: full access

ChangeUserPasswordView

Ednpoint url: /api/v1/user/change_password/<int:pk>/

Permissions: only accessible for your own user instance

UpdateUserView

Endpoint url: /api/v1/user/update/

Permissions: only accessible for your own user instance

create_company_user [POST]

Edndpoint: /api/v1/create_company_user/

Simultaneously create a company and its related user

NOT WORKING!!!

my_user [GET]

Endpoint url: /api/v1/my_user/

Returns instance of authenticated user

load_coop_managers [POST]

Ednpoint url: /api/v1/load_coops/

For each row it creates a Company instance, and a user instance linked to the company, with role COOP_MANAGER

activate_user

Endpoint: /activate/<uidb64>/<token>/

This endpoint is reached from the URL sent to the user after their registration

User Management

Creation:

• endpoint: /api/v1/users/
• method: GET
• payload:

{
  "email": "test@email.com",
  "full_name": "TEST NAME",
  "password": "VENTILADOR2ES1234499.89",
}

Change password:

• endpoint: api/v1/user/change_password/{user.pk}/
• method: POST
• payload:

{
  "old_password": "my_old_password",
  "password": "SUPERSECRETNEWPASSWORD",
  "password2": "SUPERSECRETNEWPASSWORD"
}

Update user profile:

• endpoint: api/v1/users/int:pk/
• method: PUT
• payload:

{
  "email": "new_user@email.com",
  "full_name": "Mr. TEST NAME",
}

Authentication

Implemented using djangorestframework-simplejwt

New token pair endpoint: /api/v1/token/

Response:

{
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTYxMjI3MTcwNSwianRpIjoiZDU4YTgzYzFkYzFkNDI5MTljMGQ0NzcxNzljNzUxYTQiLCJ1c2VyX2lkIjo4fQ.yln80W5lONSyHwwqF4qBBHteqLuRfdLLWuaQANr_vxc",
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjEyMTg4OTA1LCJqdGkiOiIzNGIxMzM3NmU4MWI0OWY5YjU3ZmUxM2M5NThmZWZkYiIsInVzZXJfaWQiOjh9.aRDCUvKj7LCvixjPLC9ghy0h7rfRwR6Lo3A7HX4kSHE"
}

Refresh expired token endpoint: /api/v1/token/refresh/

Users

Endpoint url: /api/v1/users/

To get info on authenticated user: /api/v1/my_user/

Authenticated users cannot create new users

User are active by default

To create user:

{
    "email": "test_user23@mail.com",
    "full_name": "Mr Test User",
    "password": "wqertewqr32qrewqr",
    "provider": "TWITTER"
}

History Endpoints

Endpoint url: /api/v1/history/:

Historical records about product importation

Stats Endpoints

Endpoint url: /api/v1/stats/

logs about user interaction with products links

Location Endpoints

Location ednpoints:

• /api/v1/countries/
• /api/v1/regions/
• /api/v1/provinces/
• /api/v1/cities/

Tables filled with data from datasets/gadm36_ESP.gpkg with loadgisdata command.

Shop Integrations

We provide integrations with online shop platforms

It requires the json field Company.credentials to have the appropiate format and values

Endoint: /api/v1/companies/{PK}/import_products/

The software to handle different platform imports can be found in utils

WooCommerce

Credential format:

{
  "key": "qwerweqr",
  "secret": "asdfsa",
}

Method: utils.woocommerce.migrate_shop_products

Product Search

Endpoint: /api/v1/product_search/

Query parameters:

• q: text from the search input box

Response format:

{
  "filters": {
    "tags": {
      "singles": ["tag1", "tag2"],  // for tags that aren't nested
      "entry_1": ["subtag_1", "subtag_2"],  // for tree tags like entry_1/subtag_1
      "entry_2": ["subtag_1", "subtag_2"]   // one per penultimate tag in tree
    },
    "attributes": {
      "singles": ["tag1", "tag2"],  // for tags that aren't nested
      "entry_1": ["subtag_1", "subtag_2"],  // for tree tags like entry_1/subtag_1
      "entry_2": ["subtag_1", "subtag_2"]   // one per penultimate tag in tree
    },
  },
  "products" : [],    // list of serialized instances, in order of relevancy
}

Available query parameters:

• q: used for search [MANDATORY]
• limit: max number of returned instances [OPTIONAL]
• offset: where to start counting results [OPTIONAL]
• shipping_cost: true/false
• discount: true/false
• category: string
• tags: string
• order: string (newest/oldest)

Check out products.tests.ProductSearchTest for a practical case.

Massive Data Load Endpoints

COOP and Managing User Data Load

For massive load of data from COOPs and the managing user.

CSV headers: email,cif,nombre-coop,nombre-corto,url,es-tienda

Only admin users have access to endoint

Product Data Load

Endpoint: /api/v1/load_products/

Only functional for users with a related company instance

For massive load of product data.

CSV headers: sku,nombre-producto,descripcion,imagen,url,precio,gastos-envio,cond-envio,descuento,stock,tags,categoria,identificadores

Number fields must not include other symbols (like currency)

GeoIP Setup

Module: geoip2

• Download the GeoLite2 City and GeoLite2 Country binary datasets from maxmind.com
• Unzip files into datasets/ folder
• Set settings.GEOIP_PATH to datasets folder

Optional:

• install libmaxminddb C library for improved performance:

  sudo apt install libmaxminddb0 libmaxminddb-dev mmdb-bin

Tags

Both Company and Product models make use of tags.

Load shopping taxonomy

To create the initial set of tags, we can use the addtaxonomy management command. Reads the data from datasets/shop-taxonomy.es-ES.txt which is from google shopping

Top-level tags

In order to extract the top level tags for use as categories, we can use the extractparenttas management command. It saves the results to datasets/top_tags.txt

Development Utils

Fake product data generation

To create a dataset of fake companies and products:

python manage.py addtestdata

Creates 10 Companies, with 10 products each.

WARNING: the script deletes existing instances of both Company and Product