Ir para o conteúdo

Frontend Web - Integração com API

Cliente HTTP base

Arquivo central:

  • src/services/api.ts

Responsabilidade:

  • configurar baseURL
  • headers padrão
  • interceptores de autenticação/erro

Camada de serviços por submódulo

A integração de domínio deve acontecer em:

  • src/modules/<dominio>/<submodulo>/services/*.service.ts

Exemplos:

  • src/modules/payments/checkout/services/checkout.service.ts
  • src/modules/cycles/list/services/list.service.ts
  • src/modules/profile/profile/services/profile.service.ts

Fluxo recomendado

  1. page.tsx delega para hook.
  2. hook chama service.
  3. service usa api.
  4. view.tsx não chama API direta.

Regras obrigatórias

  1. Service não importa hooks nem view.
  2. Service não conhece componente React.
  3. view.tsx não importa services do submódulo.
  4. Transformações de payload devem ficar em mappers.ts quando fizer sentido.

Erros e autenticação

  • Erros HTTP são tratados por interceptores globais e pela camada de hook.
  • Regras de autorização por rota ficam no ProtectedRoute, não no componente visual.

Observação de evolução

src/services/api.ts continua como client base compartilhado. A especialização de domínio está nos serviços locais por submódulo para evitar acoplamento monolítico em um único arquivo de API.

Atualização importante (marketplace de cursos)

O catálogo de cursos passou a usar endpoint agregado:

  • GET /marketplace/catalog

Com isso, o frontend deve priorizar:

  • src/modules/marketplace/hooks/useMarketplaceCatalog.ts
  • src/modules/marketplace/services/marketplace.service.ts

Detalhes completos em:

Atualização importante (onboarding cliente + PBI)

Integrações obrigatórias no fluxo de cliente:

  • PUT /client/profile/method-onboarding para concluir onboarding obrigatório.
  • PUT /client/profile/pbi para auto-definição/edição de PBI quando elegível.
  • GET /client/profile para ler:
  • method_onboarding_version
  • knows_billings_method
  • knows_own_pbi
  • wants_professional_guidance
  • pbi_defined_by

Recomendação:

  • usar ['client-health-gate', userId] para cache de bloqueio/liberação de rota;
  • invalidar ['client-profile'] e ['client-statistics'] após salvar PBI.