Agentes IA · Servidor MCP

Ambientes: Test e Live

O portal Developer tem dois ambientes, e cada app pertence a um deles. Não são duas vistas da mesma app: uma app de Test e a sua equivalente de Live são registos distintos, com client_id, segredos, webhooks e planos próprios. É por isso que promover uma integração implica repetir a configuração do lado de Live — nada é copiado automaticamente entre ambientes.

O que muda em cada ambiente

Comportamento	Test	Live
Gateway de pagamentos (Pay4All/AppyPay, E-Kwanza)	Simulado — devolve sempre um mock	Real — cobra dinheiro
Cobranças via API Developer (`create_test_charge`)	Permitido	Bloqueado (`403`)
Liquidar fatura (`simulate_invoice_payment`)	Permitido	Bloqueado (`403`)
Webhooks	Entregues a sério	Entregues a sério
Faturas criadas pelo MCP	Marcadas com `metadata.sandbox_mode = true`	Faturas normais

A linha que faz a diferença é a dos webhooks. Como são entregues a sério nos dois ambientes, podes validar o teu handler contra tráfego autêntico — mesmo payload, mesma assinatura, mesmo cabeçalho — sem que exista um único kwanza envolvido.

Numa cobrança de teste, a resposta traz sempre is_mock: true, entidade 00000 e referência 999 999 999. Se vires estes valores, tens a garantia de que o gateway real não foi contactado.

Como o MCP escolhe o ambiente

As ferramentas que aceitam um parâmetro environment assumem test quando ele é omitido. O valor por omissão do servidor vem da variável ACAPADEV_ENV, e o assistente é instruído a nunca criar nem alterar uma app live sem um pedido explícito teu.

Para saberes com o que estás a falar em qualquer momento:

"Qual é o contexto do meu ambiente Acapadev?"

O get_environment_context devolve o ambiente assumido, o URL da API e um sinalizador is_production, que distingue o SSO de produção do teu SSO local.

Domínios

Serviço	Domínio
Identidade (SSO)	`id.acapadev.com`
API	`api.acapadev.com`
Portal do Desenvolvedor	`developers.acapadev.com`
Documentação	`docs.acapadev.com`

Os domínios são os mesmos nos dois ambientes — Test e Live não têm URLs diferentes. O que separa um do outro são as credenciais: cada app pertence a um ambiente, e é o client_id (ou o app_id) que determina o comportamento do gateway.

Promover para Live

Quando o fluxo estiver validado em Test, a promoção é uma sequência deliberada e manual:

Cria (ou identifica) a app equivalente no ambiente Live.
Configura nela o billing_webhook_url de produção e subscreve invoice.paid.
Gera o webhook_secret da app Live e guarda-o no .env de produção. É diferente do de Test.
Obtém o client_secret da app Live para o fluxo M2M do teu servidor.
Sincroniza o catálogo de planos no ambiente Live.

Cuidado com a rotação de segredos. rotate_oauth_client_secret e rotate_webhook_secret invalidam de imediato o valor anterior. Numa app Live com tráfego, isso quebra a integração até o novo valor ser publicado. Confirma o campo webhook_secret_configured em get_payment_api_config antes de rodar seja o que for.

← Instalação Integrar pagamentos →