@uappi/public-api

Composables Vue 3 + TypeScript para integração simplificada com a API pública da Uappi, facilitando o consumo, gerenciamento e reutilização de endpoints em aplicações modernas.

Instalação

Adicione ao seu projeto:

npm install @uappi/public-api

Escopos Disponíveis

O pacote expõe os seguintes escopos, cada um agrupando recursos relacionados:

• cart: Operações de carrinho, como adicionar/remover produtos, simular frete, pagamentos e condições.

  • listDetail Lista detalhes do carrinho
  • addProduct Adiciona um produto ao carrinho
  • deleteProduct Remove um produto do carrinho
  • upsertProduct Atualiza ou insere produto
  • shipmentQuote Lista opções de frete com base no carrinho
  • selectShipment Seleciona opção de frete
  • applyAddresses Aplica endereços entrega/faturamento ao carrinho
  • listPayments Lista formas de pagamento
  • buy: Finaliza a compra
  • paymentConditions: Lista condições de pagamento

• common: Utilitários como consulta de CEP, países e bandeiras de cartão.

  • listZipcode: Lista detalhes de endereço de CEP
  • listContries: Lista detalhes de países
  • countryDetail: Detalhes de um país
  • listCardFlags: Retorna dados utilitários sobre cada bandeira de cartão (regex de validação, etc)

• customer: Recursos para autenticação, cadastro, endereços, pedidos, newsletter, avaliações e histórico do cliente.

  • addNewsletter: Inscreve na newsletter da loja por email e name
  • deleteNewsletter: Remove inscrição na newsletter (apenas cliente logado)
  • createProductReview: Avalia um produto (apenas clientes logado)
  • listProductReview: Listagem paginada de todas avaliações do produto
  • listStoreReview: Listagem paginada de todas avaliações da loja
  • createInterest: Cria uma solicitação de interesse em um produto fora de estoque
  • changePasswordByAuthenticated: Alteração de senha com cliente autenticado
  • changePasswordByCode: Alteração de senha através de código enviado por e-mail
  • check: Verifica existencia de cliente com base no e-mail ou documento
  • listAddress: Listagem de endereços do cliente logado
  • createAddress: Cria novo endereço do cliente logado
  • deleteAddress: Remove um endereço do cliente logado
  • updateAddress: Atualiza endereço do cliente logado
  • updatePrimaryAddress: Define um endereço como principal
  • detail: Detalhes do cliente logado
  • passwordRecovery: Recuperação de senha
  • signinByDocument: Login por documento
  • signinByEmail: Login por e-mail
  • signup: Cadastro de novo cliente
  • update: Atualiza dados do cliente
  • loggout: Logout
  • detailOrderGroup: Detalhes de pedido
  • listOrderGroups: Lista pedidos
  • listOrderItemHistory: Exibe o histórico de atualizações do pedido
  • listCustomerHistory: Exibe o histórico de atualizações do cliente (senha, endereço, etc.)
  • listCustomerReview: Lista avaliações do cliente em produto
  • listWalletTransaction: Lista transações da carteira
  • claimGiftCard: Resgata gift card

• customization: Listagem de banners, vitrines e menus customizados.

  • listShowcase: Lista detalhes de vitrines
  • listBanners: Lista detalhes de banners
  • listMenu: Lista detalhes de menus
  • listTemplateSettings: Lista as configurações de settings e apps da loja com base na URI

• product: Consulta de marcas, variações, busca, comentários e informações de produtos.

  • listBrands: Listagem de marcas ativas
  • listVariation: Lista variações de um produto
  • getUrl: Consulta URL de produto (categorias, institucionais, detalhe de produto, etc.)
  • getSearch: Pesquisa produtos por termo
  • listShipmentQuoteProduct: Lista opções frete com base em um produto
  • deleteProductComment: Remove um comentário no produto
  • createProductComment: Adiciona um comentário no produto
  • listProductComments: Lista comentários de produto

• promotional: Ofertas, cupons, carteiras e pontos promocionais.

  • listPairOffers: Lista ofertas em pares de um produto (compre junto)
  • addCoupon: Adiciona cupom no carrinho
  • deleteCoupon: Remove cupom no carrinho
  • applyWallet: Aplica carteira saldo da carteira no carrinho
  • deleteWallet: Remove carteira saldo da carteira no carrinho
  • applyPoint: Aplica saldo de pontos no carrinho
  • deletePoint: Remove saldo de pontos no carrinho

Exemplos de Uso por Escopo

cart

import publicApi from '@uappi/public-api';

// Listar detalhes do carrinho
await publicApi.cart.listDetail(): CartResponse;

// Adiciona produto ao carrinho
await publicApi.cart.addProduct(
	payload: UpsertCartRequest
): CartResponse;

// Remover um ou varios produtos do carrinho
await publicApi.cart.deleteProduct(
	payload: DeleteCartRequest
): CartResponse;

// Adiciona ou atualiza a quantidade do produto no carrinho
await publicApi.cart.upsertProduct(
	payload: UpsertCartRequest
): CartResponse;

// Retorna opções de frete no contexto do carrinho
await publicApi.cart.shipmentQuote(
	payload: ShipmentQuoteCartRequest
): CartResponse;

// Seleciona uma opção de frete no contexto do carrinho.
await publicApi.cart.selectShipment(
	payload: SelectShipimentRequest
): CartResponse;

// Aplica endereço no contexto do carrinho.
await publicApi.cart.applyAddresses(
	payload: AddressesToCartRequest
): CartResponse;

// Lista as opções de pagamento no contexto do carrinho.
await publicApi.cart.listPayments(): PaymentResponse;

// Informa as condições do pagamento, para verificar condições do mix de pagamento
await publicApi.cart.paymentConditions(
	payload: PaymentConditionsRequest
): PaymentConditionsResponse;

common

import publicApi from '@uappi/public-api';

// Consultar CEP
await publicApi.common.listZipcode(zipcode: string): ZipcodeResponse;

// Retorna dados complementares de cada pais
await publicApi.common.listContries(): Array<CountryResponse>;

// Retorna os detalhes de um pais
await publicApi.common.countryDetail(code: CountryAlpha3): CountryResponse;

// Retorna dados utilitários sobre cada bandeira de cartão
await publicApi.common.listCardFlags(): CardFlags;

customer

import publicApi from '@uappi/public-api';

// Inscreve na newsletter da loja por email e name
await publicApi.customer.addNewsletter(): CustomerOrderResponse;

// Remove inscrição na newsletter (apenas clientes logado)
await publicApi.customer.deleteNewsletter(): CustomerOrderResponse;

// Avalia um produto (apenas clientes logado)
await publicApi.customer.createProductReview(
	productId: number,
	payload: ProductReviewRequest,
): ProductReviewResponse;

// Listagem paginada de todas avaliações do produto
await publicApi.customer.listProductReview(
	options?: Pick<
	ApiParams<ReviewFields, ReviewSortFields, ReviewConditionFields>,
		'condition' | 'order' | 'fields' | 'limit' | 'offset'
	>
): ProductReviewResponse;

// Listagem paginada de todas avaliações da loja
await publicApi.customer.listStoreReview(): ProductReviewResponse;

// 
await publicApi.customer.createInterest(
	payload: RequestInterest
): ResponseInterest;

// Alteração de senha com cliente autenticado
await publicApi.customer.changePasswordByAuthenticated(
	payload: ChangePasswordCustomerAuthenticated,
): boolean;

// Alteração de senha através de código enviado por e-mail
await publicApi.customer.changePasswordByCode(
	payload: ChangePasswordCustomerByCode
): boolean;

// Verifica existencia de cliente com base no e-mail ou documento
await publicApi.customer.check(
	payload: CheckCustomer
): boolean;

// Listagem de endereços do cliente logado
await publicApi.customer.listAddress(): CustomerAddressesResponse;

// Cria novo endereço do cliente logado
await publicApi.customer.createAddress(
	payload: UpsertCustomerAddressRequest
): CustomerAddressResponse;

// Remove um endereço do cliente logado
await publicApi.customer.deleteAddress(
	addressId: number
): CustomerAddressResponse;

// Atualiza endereço do cliente logado
await publicApi.customer.updateAddress(
	addressId: number,
	payload: UpsertCustomerAddressRequest,
): CustomerAddressResponse;

// 
await publicApi.customer.updatePrimaryAddress(
	addressId: number
): CustomerAddressResponse;

// 
await publicApi.customer.detail(
	options?: Pick<
		ApiParams<CustomerFields, CustomerSortFields, CustomerConditionFields>,
		'condition' | 'fields' | 'order'
	>
): CustomerResponse;

// 
await publicApi.customer.passwordRecovery(
	payload: PasswordRecoveryCustomer
): boolean;

// 
await publicApi.customer.signinByDocument(
	payload: SigninCustomerByDocument
): ResponseSigninCustomer;

// 
await publicApi.customer.signinByEmail(
	payload: SigninCustomerByEmail
): ResponseSigninCustomer;

// 
await publicApi.customer.signup(
	payload: SignupCustomer
): CustomerResponse;

// 
await publicApi.customer.update(
	payload: UpdateCustomer
): CustomerResponse;

// 
await publicApi.customer.loggout(): boolean;

// 
await publicApi.customer.detailOrderGroup(
	orderId: number,
	options?: Pick<ApiParams<CustomerOrderGroupFields>, 'fields'>,
): CustomerOrderResponse;

// 
await publicApi.customer.listOrderGroups(
	options?: Pick<
		ApiParams<
			CustomerOrderGroupFields,
			CustomerOrderGroupSortFields,
			CustomerOrderGroupConditionFields
		>,
		'condition' | 'fields' | 'limit' | 'offset' | 'order'
	>,
): CustomerOrdersResponse;

// 
await publicApi.customer.listOrderItemHistory(
	orderId: number,
	options?: Pick<
		ApiParams<
			'',
			CustomerOrderItemHistorySortFields,
			CustomerOrderItemHistoryConditionFields
		>,
		'condition' | 'fields' | 'limit' | 'offset' | 'order'
	>,
): CustomerOrderItemHistoriesResponse;

// 
await publicApi.customer.listCustomerHistory(
	options?: Pick<
		ApiParams<
			'', 
			CustomerHistorySortFields, 
			CustomerHistoryConditionFields
		>,
		'condition' | 'limit' | 'offset' | 'order'
	>,
): CustomerHistoryResponse;

// 
await publicApi.customer.listCustomerReview(
	options?: Pick<
		ApiParams<
			ReviewFields, 
			ReviewSortFields, 
			ReviewConditionFields
		>,
		'condition' | 'order' | 'fields' | 'limit' | 'offset'
	>,
): ProductReviewResponse;

// 
await publicApi.customer.listWalletTransaction(
	options?: Pick<
		ApiParams<
			'',
			WalletSortFields, 
			WalletConditionFields
		>,
		'condition' | 'order' | 'limit' | 'offset'
	>,
): WalletTransactionResponse;

// 
await publicApi.customer.claimGiftCard(
	payload: ClaimGiftCardRequest
): ClaimGiftCardResponse;

customization

import publicApi from '@uappi/public-api';

// Esse método possui sobrecarga de função, permitindo uma mesma função possuir duas assinaturas. 
// Retorna uma ou varias vitrines com base nos code passado como parametro
await publicApi.customization.listShowcase(codes: Array<string>): Array<Showcase>;
await publicApi.customization.listShowcase(code: string): Showcase;

// Esse método possui sobrecarga de função, permitindo uma mesma função possuir duas assinaturas. 
// Esse método possui Generic AdditionalParameters usado para definir a tipagem dos parametros personalizados e dinamicos cadastrados no grupo de banner.
// Retorna uma ou varios grupos de banner com base nos code passado como parametro
await publicApi.customization.listBanners<AdditionalParameters>(codes: Array<string>): Array<Banners<AdditionalParameters>>;
await publicApi.customization.listBanners<AdditionalParameters>(code: string): Banners<AdditionalParameters>;

// Esse método possui sobrecarga de função, permitindo uma mesma função possuir duas assinaturas. 
// Retorna uma ou varias vitrines com base nos code passado como parametro
await publicApi.customization.listMenu(codes: Array<string>) Array<Menu>;
await publicApi.customization.listMenu(code: string) Menu;

product

import publicApi from '@uappi/public-api';

// Listar marcas
await publicApi.product.listBrands(
	options?: Pick<
		ApiParams<BrandFields, BrandOrders, BrandConditions>,
		'condition' | 'fields' | 'offset' | 'limit' | 'order'
	>
): Brand;

// Buscar variações de um produto
await publicApi.product.listVariation(
	variationData: VariationData,
	options?: Pick<
		ApiParams<ProductFields, ProductSortFields, ProductConditionFields>,
		'condition' | 'fields' | 'meta'
	>
): Product;

// Nesse método é necessário definir o Generic UrlType conforme a request da página que espera ser retornado, exemplo: para buscar uma página de catalogo é informamos UrlListing. Todos os tipos podem ser conferidos na documentação oficial.
// Request com dados da página (categoria, detalhe de produto, institucional, marca, etc)
await publicApi.product.getUrl<UrlType>(
	path: string,
	options?: Pick<
		ApiParams<ProductFields, ProductOrderFields, ProductConditionFields>,
		'condition' | 'fields' | 'limit' | 'offset' | 'meta' | 'order'
	>
): UrlType;

// Retorna uma lista de produtos com base no termo de pesquisa. Pode ser usado para criar uma sugestão no header do site e também para criar uma listagem paginada de busca de produto
await publicApi.product.getSearch(
	term: string,
	options?: Pick<
		ApiParams<ProductFields, ProductSortFields, ProductConditionFields>,
		'condition' | 'fields' | 'limit' | 'meta' | 'offset' | 'order'
	>
): Search;

// Usado para cotar frete no contexto do produto informado na requisição. Não considera produtos persistidos no carrinho.
await publicApi.product.listShipmentQuoteProduct(
	payload: Pick<ApiParams, 'targetCountryCode' | 'targetZipCode' | 'items'>,
): ShipmentQuoteProductResponse;

// Permite o cliente deletar seu comentário/pergunta realizada no produto.
await publicApi.product.deleteProductComment(
	commentId: number
): boolean;

// Permite o cliente criar um comentário/pergunta no produto.
await publicApi.product.createProductComment(
	productId: number,
  	payload: CreateProductComment,
): ProductComment;

// Retorna uma listagem paginada de todos os comentários do produto 
await publicApi.product.listProductComments(
	options?: Pick<
		ApiParams<
			ProductCommentFields,
			ProductCommentSortFields,
			ProductCommentConditionFields
		>,
		'condition' | 'order' | 'limit' | 'offset' | 'fields'
	>
): ProductCommentsResponse;

promotional

import publicApi from '@uappi/public-api';

// Retorna a listagem de opções de compre junto no contexto do produto.
await publicApi.promotional.listPairOffers(
	productId: number,
	options?: Pick<ApiParams<ProductFields>, 'fields' | 'variationMap'>
): PairOfferResponse;

// Adiciona cupom no contexto do carrinho.
await publicApi.promotional.addCoupon(
	payload: AddCouponRequest
): CartResponse;

// Remove cupom no contexto do carrinho.
await publicApi.promotional.deleteCoupon(): CartResponse;

// Aplica saldo em carteira como forma de desconto no contexto carrinho.
await publicApi.promotional.applyWallet(): CartResponse;

// Remove saldo em carteira aplicado no contexto do carrinho.
await publicApi.promotional.deleteWallet(): CartResponse;

// Aplica saldo de pontos como forma de desconto no contexto do carrinho.
await publicApi.promotional.applyPoint(): CartResponse;

// Remove saldo de pontos aplicado no contexto do carrinho.
await publicApi.promotional.deletePoint(): CartResponse;

Tipos

Todos os métodos retornam dados tipados para melhor experiência com TypeScript.

Contribuição

Contribuições são bem-vindas! Abra uma issue ou envie um pull request.

Licença

ISC