nuvemshop_api

pub package license

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 (suporte@exemplo.com)',
);

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

2. Chamadas à API da loja

NuvemshopConfig.setConfig(
  accessToken: token,
  storeId: storeId,
  userAgent: 'MinhaApp (suporte@exemplo.com)',
  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.

Libraries

nuvemshop_api
Cliente Dart para a API Nuvemshop / Tiendanube.