nuvemshop_api 0.1.1

Cliente Dart para a API REST Nuvemshop / Tiendanube (produtos, pedidos, loja, OAuth2). Documentação oficial: https://tiendanube.github.io/api-documentation/

nuvemshop_api

Cliente Dart para a API REST Nuvemshop / Tiendanube, organizado de forma semelhante ao pacote shopify_flutter: configuração global (NuvemshopConfig) e serviços com singleton (NuvemshopProducts.instance, etc.).

Documentação oficial da plataforma: Nuvemshop API.

Requisitos

• Dart ^3.9.0
• Cabeçalhos exigidos pela API: Authentication: bearer … (não use Authorization) e User-Agent — ver Authentication.

Instalação

dependencies:
  nuvemshop_api: ^0.1.1

Uso

1. OAuth (código de autorização → token)

import 'package:nuvemshop_api/nuvemshop_api.dart';

final grant = await NuvemshopOAuth.instance.exchangeAuthorizationCode(
  clientId: 'SEU_APP_ID',
  clientSecret: 'SEU_SECRET',
  code: 'CODIGO_DA_REDIRECT_URL',
  userAgent: 'MinhaApp ([e-mail])',
);

final token = grant.accessToken;
final storeId = grant.userId;

2. Chamadas à API da loja

NuvemshopConfig.setConfig(
  accessToken: token,
  storeId: storeId,
  userAgent: 'MinhaApp ([e-mail])',
  apiVersion: '2025-03',
);

final store = await NuvemshopStore.instance.get();
final produtos = await NuvemshopProducts.instance.list(perPage: 20);

Interceptores (monitoramento de requests/responses)

Todos os serviços REST da loja (NuvemshopStore, NuvemshopProducts, NuvemshopCarts, NuvemshopCustomRest, etc.) passam pelo mesmo Dio em NuvemshopHttpClient.instance. Você pode registrar interceptores do pacote dio para logar, medir tempo ou correlacionar chamadas:

import 'package:dio/dio.dart';
import 'package:nuvemshop_api/nuvemshop_api.dart';

NuvemshopHttpClient.instance.setUserInterceptors([
  InterceptorsWrapper(
    onRequest: (options, handler) {
      // options.uri, options.method, options.headers (evite logar token em produção)
      handler.next(options);
    },
    onResponse: (response, handler) {
      // response.statusCode, response.data
      handler.next(response);
    },
    onError: (error, handler) {
      // error.response, error.type
      handler.next(error);
    },
  ),
]);

• setUserInterceptors — substitui a lista inteira (útil para montar a cadeia uma vez no bootstrap).
• addUserInterceptor — acrescenta um interceptor.
• clearUserInterceptors — remove os interceptores do app.

Qualquer alteração invalida o Dio em cache; na próxima requisição ele é recriado com a lista atual. Os interceptores do app rodam antes do interceptor interno que converte HTTP ≥ 400 em DioException.

Escopo: isso não inclui NuvemshopOAuth.exchangeAuthorizationCode, que usa um Dio separado para POST /apps/authorize/token.

Em produção, evite logar corpo completo de respostas ou cabeçalho Authentication; prefira mascaramento e níveis de log condicionais.

3. Endpoints genéricos

Para recursos ainda não cobertos pelos serviços:

final data = await NuvemshopCustomRest.instance.get(
  'metafields/APP_NAMESPACE',
);

Serviços incluídos

Classe	Recurso da API
NuvemshopOAuth	POST /apps/authorize/token
NuvemshopStore	Store
NuvemshopProducts	Product
NuvemshopCategories	Category
NuvemshopCustomers	Customer
NuvemshopOrders	Order
NuvemshopDraftOrders	Draft Order
NuvemshopCustomRest	qualquer caminho relativo à base da loja

Publicação no pub.dev

Antes de publicar, ajuste no pubspec.yaml:

• homepage ou repository apontando para o repositório do pacote;
• remova ou comente publish_to: 'none' se existir.

Depois: dart pub publish --dry-run e dart pub publish.

Licença

MIT — ver LICENSE.