@partiu-vantagens/partiu-sdk

Partiu SDK

Library made to integrate Partiu React/React-Native/JS front-end applications with the Partiu servers.

The SDK is divided in modules that are responsible for communicating with certain parts of the API. All the developed modules can be found below.

Glossary

• Initializing the SDK
• Modules
• Pagination

Installing

yarn add @partiu-vantagens/partiu-sdk
# or
npm install @partiu-vantagens/partiu-sdk

import Partiu from "@partiu-vantagens/partiu-sdk";

const partiu = new Partiu();
const partiu = new Partiu(true); // Initialize in beta mode (access beta api servers for testing)

const data = await partiu.promotions.list(); // Example for listing promotions

Modules:

• Auth
• Profile
• Categories
• Promotions
• Utilizations
• Contact
• Banners
• APIs

Auth

The Auth module is responsible for setting and removing the token from all the other requests. Each user has a unique token that's used by the API for verifying the client. For now, the token is fixed and is never refreshed, altough this functionality will probably be implemented soon.

Commands

Login

Adds a token to all request to server.

const token = "asdjhasdijuhg12312312asdasdsad";

partiu.auth.setToken(token);

Logout

Removes a token to all request to server.

partiu.auth.clearToken();

Profile

The Profile module is responsible for retrieving and updating user profile. Requires token.

Model

export interface Profile {
  id: number;
  full_name: string;
  email: string;
  telephone: string;
  image: string;
  city: string;
  cpf: string;
  active_agreement: object;
  allowed_push_notifications: boolean;
  allowed_promotional_emails: boolean;
}

Commands

Retrieve

const profile: Profile = await partiu.profile.retrieve();

Update

This endpoint uses the PATCH HTTP verb, so it's not necessary to pass the whole profile.

const updatedData = {
  full_name: "New Name",
  allowed_push_notifications: false,
};

await partiu.profile.update(updatedData);

Categories

The Categories module is responsible for listing Category models from the server.

Model

export interface Category {
  id: number;
  name: string;
  icon: string;
  image: string;
}

Commands

List

const data: Category[] = await partiu.categories.list();

List (Paginated)

For more details on pagination, see Pagination.

Promotions

The Promotions module is responsible for listing and retrieving Promotion models from the server.

OBS: When listing with promotions.list(), promotions from same company or stores are aggregated in the same object. After retrieving the promotion using the promotions.retrieve() all the promotions will be listed in the promotions attribute.

OBS 2: Link and Coupon fields are only given if the user is logged and have a valid subscription.

Model

declare enum PromotionModes {
  online = "online",
  local = "local",
}

declare enum PromotionTypes {
  discount = "discount",
  buy_and_gain = "buy_and_gain",
  treat = "treat",
}

export interface Promotion {
  id: number;
  mode: PromotionModes;
  type: PromotionTypes;
  original_price: number;
  discount: number;
  image: string;
  rules: string;
  link?: string;
  coupon?: string;
  featured: boolean;
  limited_codes: boolean;
}

export interface PromotionAggregator {
  id: number;
  image: string;
  show_name: string;
  subtitle: string;
  category: string;
  percentage: number;
  mode: PromotionModes;
  type: PromotionTypes;
  distance: string;
  favorite: boolean;
  featured: boolean;
  new: boolean;
}

export interface StorePromotions {
  id: number;
  image: string;
  show_name: string;
  subtitle: string;
  category: string;
  mode: PromotionModes;
  type: PromotionTypes;
  description: string;
  promotions: Promotion[];
  site: string;
  latitude: number;
  longitude: number;
}

export interface CompanyPromotions {
  id: number;
  image: string;
  show_name: string;
  subtitle: string;
  category: string;
  mode: PromotionModes;
  type: PromotionTypes;
  description: string;
  promotions: Promotion[];
  site: string;
}

Commands

List

const data: PromotionAggregator[] = await partiu.promotions.list();

AvailableFilters

export interface PromotionsFilters {
  category: string;
  mode: PromotionModes;
  name: string; // Company name
  type: PromotionTypes;
  featured: boolean;
  new: boolean;
  latitude: number; // Required for local discounts
  longitude: number; // Required for local discounts
}

Example:

const data = PromotionAggregator[] = await partiu.promotions.list({type: "buy_and_gain", new: true})

List (Paginated)

For more details on pagination, see Pagination.

Retrieve

const company_promotions: CompanyPromotions = await partiu.promotions.retrieve(
  "online_10"
);
const store_promotions: StorePromotions = await partiu.promotions.retrieve(
  "local_10"
);

Utilizations

The Utilizations module is responsible for:

1. Storing the history of the user's promotion usage.
2. Generating a code that will be use in the PDV for validating the user usage.
3. Storing the value of the discount that was given, together with the feedback of the whole experience.

Once the user has chosen a promotion to use, the system must call the utilizations.create(promotionId) action to keep history of the usage. In case of local promotions, this is essencial since it will return a code that will be input in the PDV system for validation that the user is subscribed to Partiu.

Once the user used (accessed the site if online or had the code validated if local), it can give two aditional information: How much it payed and the feedback (good or bad experience). It must be passed using the utilizations.update(code, {user_given_value: 23.00, feedback: true /* True if good false if bad */ }) action.

Model

export interface Utilization {
  code: string;
  created_at: Date;
  expires_at: Date;
  company: string;
  used: boolean;
  feedback: boolean;
  user_given_total: number;
  pdv_given_total: number;
  display_name: string;
}

export interface CategoryReport {
  name: string;
  usage: number;
  economized: number;
}

Commands

Create

Creates a utilization from a promotion.

const utilization: Utilization = await partiu.utilizations.create("3881");

Update

Adds more information about the utilization, such as: total paid and feedback.

const utilization = await partiu.utilizations.update("UFP12A", {
  user_given_total: 30.4,
  feedback: true,
});

List

Lists all user utilizations.

const utilizations: Utilization[] = await partiu.utilizations.paginated.list();

List (Paginated)

For more details on pagination, see Pagination.

Report

Lists user usage grouped by category. Receives two parameters for filtering: month and year.

const report: CategoryReport[] = await partiu.utilizations.report(4, 2022);

Contact

The Contact module is responsible for creating support tickets.

Model

export interface ContactForm {
  name: string;
  email: string;
  subject: string;
  telephone: string;
  message: string;
  landing: string; // This is about where the contact came from (landing, app, iframe, etc...)
}

Commands

Create

const response: ContactForm = await partiu.contact.create(
  "Test",
  "[e-mail]",
  "test subject",
  "21995150897",
  "Help, everything is on fire!!!",
  "smartfit landing"
);

Banners

The Banners module is responsible for listing Banner models from the server.

Model

export interface Banner {
  name: string;
  image: string;
}

Commands

List

Lists all banners.

const banners: Banner[] = await partiu.banner.list();

APIs

Partiu uses some third party APIs to fetch extra information when needed.

CEP API (ViaCEP)

Returns an address from CEP.

const address = await partiu.api.getAddressFromCEP("99999-999");

export interface Address {
  cep: string;
  logradouro: string;
  complemento: string;
  bairro: string;
  localidade: string;
  uf: string;
  ibge: string;
  gia: string;
  ddd: string;
  siafi: string;
}

CNPJ API (ReceitaWS)

Returns company data from CNPJ.

const companyData: CompanyData = await partiu.api.getCompanyDataFromCNPJ(
  "99.999.999/9999-99"
);

declare enum CompanyTypes {
  MATRIZ = "MATRIZ",
  FILIAL = "FILIAL",
}

export interface CompanyActivity {
  code: string;
  text: string;
}

export interface CompanyOwner {
  nome: string;
  qual: string;
  pais_origem: string;
  nome_rep_legal: string;
  qual_rep_legal: string;
}

export interface CompanyData {
  ultima_atualizacao: string;
  cnpj: string;
  cep: string;
  nome: string;
  tipo: CompanyTypes;
  porte: string;
  fantasia: string;
  abertura: string;
  atividade_principal: CompanyActivity;
  atividades_secundarias: CompanyActivity[];
  natureza_juridica: string;
  logradouro: string;
  numero: string;
  complemento: string;
  bairro: string;
  municipio: string;
  uf: string;
  email: string;
  telefone: string;
  efr: string;
  situacao: string;
  data_situacao: string;
  motivo_situacao: string;
  situacao_especial: string;
  data_situacao_especial: string;
  capital_social: string;
  qsa: CompanyOwner[];
}

Pagination

Some modules provides a pagination object to easily deal with paginated endponts. They can be used as described below (using the promotions module as an example):

const data: PromotionAggregator[] = await partiu.promotions.paginated.list({
  mode: "online",
  type: "discount",
});
const moreData: PromotionAggregator[] =
  await partiu.promotions.paginated.next();

partiu.promotions.reset(); // Resets pagination to default

As seen by the code above, the paginated.next() command will call the next page of models, with the the filters already applied.

To reset the pagination, you can call paginated.list() command again or the paginated.reset() command.

This implementation of pagination is focused on infinite scrolling, so the page data is not provided. However, a paginated.previous() command is provided if needed.