⚙️ Conceito Essencial - ApiParams

Alguns recursos da API Pública permitem um alto nível de customização através de parâmetros avançados.

Esses parâmetros são baseados em um conceito interno do backend chamado “obsearch”, que permite:

• Controlar quais dados serão retornados
• Aplicar ordenação
• Definir filtros complexos
• Melhorar performance, evitando dados desnecessários

No public-sdk, tudo isso é abstraído pela interface:

1export interface ApiParams<
2  FieldOptions = '',
3  OrderOptions = '',
4  ConditionOptions = '',
5> {
6  codes?: Array<string>;
7  limit?: number;
8  offset?: number;
9  fields?: Array<FieldOptions>;
10  order?: Array<ApiParamsOrder<OrderOptions>>;
11  condition?: ApiParamsConditionGroup<ConditionOptions>;
12  meta?: ApiParamsMeta;
13
14  // específicos
15  targetZipCode?: string;
16  targetCountryCode?: string;
17  items?: Array<{ productId: number; quantity: number }>;
18
19  variationMap?: Record<string, number>;
20
21  loginUrl?: string;
22  registerUrl?: string;
23}

🧠 Conceito principal

A ideia é simples: Você controla exatamente o que quer receber da API, ao invés de receber tudo.

Isso permite:

• Melhor performance
• Menor payload
• Respostas sob medida para o layout

fields - Controle de retorno

Define quais informações devem ser retornadas.

Exemplo:

1await Api.product.getUrl('/camiseta', {
2  fields: ['price', 'media', 'variation']
3});

order - Ordenação

Permite ordenar os resultados.

1await Api.product.getUrl('/camiseta', {
2  order: [
3    { field: 'price', order: 'ASC' }
4  ]
5});

condition Filtros avançados

Permite criar filtros complexos com AND / OR

1await Api.product.getUrl('/camiseta', {
2  condition: {
3    type: 'AND',
4    conditions: [
5      {
6        field: 'salePrice',
7        operator: 'between',
8        value: '50-100'
9      }
10    ]
11  }
12});

limite offset - Paginação

Controlam paginação dos resultados.

1await Api.product.getUrl('/camiseta', {
2  limit: 10,
3  offset: 20
4});

meta - Customizações avançadas

Permite enviar parâmetros adicionais que impactam o comportamento da API.

1await Api.product.getUrl('/camiseta', {
2  meta: {
3    dimensions: {
4      size: 'Centimeter',
5      weight: 'Kilogram'
6    }
7  }
8});

🧠 Tipagem avançada (TypeScript)

Cada recurso é tipado de forma especifica conforme a API Pública permite.

Por exemplo:

listVariation permite apenas os parametros: fields, condition e meta.

1await Api.product.listVariation(
2	variationData: VariationData,
3	options?: Pick<
4		ApiParams<ProductFields, ProductSortFields, ProductConditionFields>,
5		'condition' | 'fields' | 'meta'
6	>
7): Product;

Já o recurso getUrl permite os parametros: fields, condition, limit, offset, order e meta.

1await Api.product.getUrl<UrlType>(
2	path: string,
3	options?: Pick<
4		ApiParams<ProductFields, ProductOrderFields, ProductConditionFields>,
5		'condition' | 'fields' | 'limit' | 'offset' | 'meta' | 'order'
6	>
7): UrlType;

⚠️ Boas práticas

• Use fields sempre que possível → melhora performance
• Evite filtros muito complexos sem necessidade
• Combine limit + offset para paginação
• Prefira order no backend ao invés de ordenar no front

SDK Público - Api: Recursos