Módulos

O catálogo de módulos da plataforma e como a loja instala, liga, configura e remove cada um.

Um módulo é um recurso opcional da plataforma: um meio de pagamento, uma transportadora, uma integração com ERP, uma ferramenta de marketing. A plataforma tem um catálogo central de módulos; cada loja instala os que quer e liga ou desliga cada um. Módulos novos nascem desligados nas lojas existentes. Esta seção é a API que o painel usa na tela de módulos.

Como funciona

O ciclo de vida de um módulo na loja:

Não instalado→Instalado e ligado→Instalado e desligado→Removido

`install_status`	Significado
`not_installed`	Existe no catálogo, a loja não instalou.
`installed_enabled`	Instalado e ligado: as rotas e telas do módulo funcionam.
`installed_disabled`	Instalado mas desligado: configuração guardada, rotas respondem 403.

Escolher
Liste o catálogo e anote o id e o slug do módulo.
Conferir dependências
Pergunte se pode instalar.
Instalar e configurar
Instale e grave os ajustes.
Ligar ou desligar
Use a rota de configuração, ou o lote para vários módulos.

Conceitos-chave

Id e slug

O id é um UUID do catálogo central, igual para todas as lojas. O slug é o nome de texto estável (google-analytics). Os caminhos de instalação, configuração, remoção e dependências usam o id; os ajustes usam o slug. Enviar o slug onde se espera o id responde 400 invalid moduleId.

Módulos e o núcleo da plataforma

Algumas funcionalidades que eram módulos viraram parte do núcleo e estão sempre ligadas para todas as lojas. Elas não aparecem como "instalar" no catálogo, mas podem ter ajustes por loja.

Configuração e ajustes

A instalação guarda dois objetos: config (substituído por inteiro em cada gravação) e settings (gravados por merge, chave a chave). Para os ajustes do dia a dia, use a rota de ajustes.

Quem controla o quê

A operadora da plataforma pode esconder um módulo de uma loja, mesmo que ele exista no catálogo; a loja só vê e instala o que lhe foi liberado. Módulos privados pertencem a uma única loja.

Endpoints

Método	Caminho	Para que serve	Autenticação
GET	`/api/v1/admin/modules/catalog`	Catálogo com o estado de instalação	admin
GET	`/api/v1/admin/modules/available`	Módulos do catálogo da plataforma	admin
GET	`/api/v1/admin/modules`	Módulos instalados na loja	admin
POST	`/api/v1/admin/modules/{moduleId}/install`	Instalar um módulo	admin
PUT	`/api/v1/admin/modules/{moduleId}/config`	Ligar, desligar ou reconfigurar	admin
DELETE	`/api/v1/admin/modules/{moduleId}`	Remover um módulo da loja	admin
POST	`/api/v1/admin/modules/bulk-toggle`	Ligar ou desligar vários módulos	admin
GET	`/api/v1/admin/modules/{moduleId}/dependencies`	Pode instalar? Pode remover?	admin
GET	`/api/v1/admin/modules/{moduleId}/dependents`	Quais módulos dependem deste	admin
GET	`/api/v1/admin/modules/extension-points`	Pontos de extensão da plataforma	admin
GET	`/api/v1/admin/modules/{moduleSlug}/settings`	Ler os ajustes de um módulo	admin
PUT	`/api/v1/admin/modules/{moduleSlug}/settings`	Gravar os ajustes de um módulo	admin

Erros comuns

Enviar o slug no caminho de instalação: o caminho pede o id (400 invalid moduleId).
Achar que instalar liga o módulo para sempre: is_enabled pode ser desligado sem remover.
Mandar PUT .../config sem is_enabled esperando manter o estado: o módulo é desligado.
Remover um módulo de que outros dependem (400 cannot uninstall).
Confiar em toggled do lote para saber quantos módulos mudaram.
Gravar ajustes de um módulo não instalado (404).
Tratar a resposta de ajustes como pública: ela pode ter chaves de integração em texto.

Próximos passos

Catálogo de módulos

Veja o que existe.

Instalar, configurar e remover

Como autenticar as chamadas.