O cenário de campanha

Todo pedido de simulação, pela API ou pelo MCP, é um cenário de campanha: um documento JSON fechado, na versão 2 do contrato. O schema do pedido, em JSON Schema (draft 2020-12), é público em GET /v1/schemas/cenario-campanha e também aparece na referência.

O contrato é a autoridade. Um campo desconhecido, um valor fora do catálogo ou uma regra quebrada é recusado com um código estável e o campo culpado (Erros). Nada é inferido, arredondado ou completado para o pedido caber.

As duas famílias

familia	O que simula	Exige	Proíbe	kpis possíveis
adocao	A adoção de algo novo ao longo do tempo, a partir de um cenário-base: o pix, ou uma calibração do seu projeto	lancamento	mensagem, canais	adotantes
recepcao	Como uma mensagem chega às pessoas por canais de mídia e o que elas fazem com ela	mensagem e ao menos um canal	lancamento	alcance, ignora, absorve, repassa, rejeita

A recepção ainda não é calibrada

Nesta versão, a família recepcao usa as tabelas de referência do motor para qualquer mensagem, e todo resultado de recepção sai com calibracao: "nao_calibrado".

• O que ela compara: os canais, o calendário de cada canal, a intensidade e o público.
• O que ela não compara: o texto, o tom e o criativo. O stim_id identifica a mensagem nos seus resultados, mas não muda o comportamento simulado: duas mensagens com os mesmos canais, datas e público dão o mesmo resultado.

Mensagens com texto próprio chegam com o chat da plataforma.

Campos

Campo	Obrigatório	O que é
versao_contrato	sim	3. Um pedido na versão 2 continua aceito e é lido como 3, que só acrescentou a base da calibração. Outra versão é recusada.
release	sim	A release de dados, como v2.0.0. As releases e UFs oferecidas estão em list_releases (MCP). A v2.0.0 é a população mais nova, com cada domicílio no setor do seu endereço. A v1.2.0 e a v1.0.0 têm a população anterior; a v1.2.0 refaz a camada de trabalho do grafo. A validação foi medida na v2.0.0 e na v1.2.0.
familia	sim	adocao ou recepcao.
geografia.ufs	sim	As UFs simuladas, como ["MG"].
geografia.municipios	não	Códigos IBGE de 7 dígitos, dentro das UFs listadas. Restringem o público-alvo, não a simulação.
geografia.aps	não	Códigos de área de ponderação do Censo 2022 (10 dígitos), dentro dos municípios listados.
publico	não	O público-alvo, por eixos; um eixo vazio ou ausente é “todos”. Veja abaixo.
canais	recepção	Lista de {canal, dia_inicio, dia_fim, intensidade}. canal é digital, tv, radio ou exterior; intensidade vai de 0 (exclusivo) a 1. Os períodos de um mesmo canal não se sobrepõem e terminam dentro do horizonte.
mensagem	recepção	{stim_id, template_ver, politica}; stim_id tem 32 caracteres hexadecimais.
lancamento	adoção	{dia, cenario_base}, e dia cai dentro do horizonte. cenario_base é pix ou calibracao; com calibracao, lancamento.calibracao é o id de um job de calibração do mesmo projeto.
horizonte	sim	{data_inicio, dias}: a data do dia 1 (AAAA-MM-DD) e quantos dias simular.
replicas	sim	De 1 a 20 rodadas independentes, para medir a variação do resultado.
grupo_comparacao	sim	Um rótulo seu (minúsculas, dígitos, _ . -, até 64) que agrupa cenários a comparar.
kpis	sim	Os indicadores pedidos, do catálogo da família.
nome, descricao	não	Textos livres, até 80 e 500 caracteres. Não entram na identidade do cenário.

Geografia: UFs, municípios e áreas

A simulação roda sobre a população inteira das UFs em geografia.ufs. Os municípios (códigos IBGE de 7 dígitos) e as áreas de ponderação (10 dígitos) restringem a quem a mídia chega, e cada um precisa estar dentro das UFs e dos municípios listados.

O público-alvo

Eixo	Valores
idades	Pares [início, fim] nas bordas de 5 anos: o início é 0, 5, …, 80; o fim é 4, 9, …, 79, ou null para “e mais”. Ex.: [[20, 59]]. Faixas que seguem os grupos de 10 anos da grade principal (0–9, 10–19, …, 50–59 e 60 ou mais) saem nela; uma faixa que corta um grupo, como [25, 34], sai na grade etária.
sexos	masculino, feminino.
niveis_instrucao	fundamental_incompleto, fundamental_completo, medio_completo, superior_completo.
faixas_renda	Índices de 0 a 4 sobre a renda mensal em reais, com cortes fixos em 706, 1.412, 2.824 e 5.648 (≈ 0,5, 1, 2 e 4 salários mínimos de 2024). A faixa 0 inclui quem não tem renda.
racas	branca, preta, amarela, parda, indigena.

A grade etária

Um público em faixas de 5 anos é respondido numa segunda grade de publicação, mais grossa nos outros eixos: município × faixa de 5 anos (0–4, 5–9, …, 75–79 e 80 ou mais) × sexo. São os cortes que o Censo publica por município. Para caber nela, o pedido:

• é de recepção: a adoção não tem mídia nem alvo, e um cenário de adoção em faixas de 5 anos é recusado;
• não usa geografia.aps, porque a grade etária não tem área de ponderação;
• não usa faixas_renda, niveis_instrucao nem racas, nem com a lista completa, porque nenhuma delas cobre também quem tem o valor não determinado;
• mira só UFs em que a grade etária está aberta: hoje, todas menos o Piauí.

Cada faixa é julgada sozinha, e basta uma fora dos grupos de 10 anos para o público inteiro ir para a grade etária: [[20, 29], [30, 34]] sai nela, e [[20, 24], [25, 29]] também. Para ficar na grade principal, com renda, instrução, raça e área, junte as faixas vizinhas num grupo: [[20, 29]].

A grade etária abre UF a UF, depois que o teste de privacidade dela passa nos dados da UF. Na release v2.0.0, ela está aberta nas 27 UFs. Nas releases v1.0.0 e v1.2.0, desde 14 de outubro de 2026, está aberta em 26, todas menos o Piauí. Numa UF ainda fechada, a cotação recusa com age_grid_not_open, e a recusa diz quais UFs do pedido estão fechadas (Erros): ali, o público fica nos grupos de 10 anos. A ferramenta list_releases do MCP traz, em grade_etaria, as UFs abertas em cada release. O que muda no resultado está em Resultado.

O que a cotação confere na release

Além do contrato, a cotação confere o pedido contra a release escolhida, antes de reservar qualquer coisa:

• cada município e cada área de ponderação existe na malha da release (municipality_not_in_release, ap_not_in_release);
• o público cabe numa das duas grades de publicação (target_finer_than_grid);
• na grade etária, cada UF do pedido tem a grade aberta (age_grid_not_open).

Variantes

Um cenário de recepção com canais roda também variantes contrafactuais, para medir o efeito de cada canal:

• 1 canal: 2 variantes;
• N canais (N ≥ 2): 1 + 2N variantes.

Um cenário sem canais roda só a base. O número de variantes entra no preço.

Réplicas

replicas pede de 1 a 20 rodadas independentes do mesmo cenário, com sorteios diferentes. O resultado traz cada réplica separada, e os achados resumem a média, o mínimo e o máximo entre elas. Cada réplica entra no preço.

Exemplo de recepção

{
  "versao_contrato": 3,
  "release": "v2.0.0",
  "familia": "recepcao",
  "geografia": { "ufs": ["MG"], "municipios": ["3106200"] },
  "publico": { "idades": [[20, 59]], "faixas_renda": [1, 2, 3] },
  "canais": [
    { "canal": "digital", "dia_inicio": 1, "dia_fim": 14, "intensidade": 0.5 },
    { "canal": "radio", "dia_inicio": 7, "dia_fim": 21, "intensidade": 0.3 }
  ],
  "mensagem": {
    "stim_id": "af9cca9c97fcb5b610476bde8756e849",
    "template_ver": "tpl-ref",
    "politica": "pol-ref"
  },
  "horizonte": { "data_inicio": "2026-11-01", "dias": 30 },
  "replicas": 2,
  "grupo_comparacao": "campanha-bh",
  "kpis": ["alcance", "repassa"]
}

Este pedido custa R$ 14,499640: 5 variantes (2 canais) e 2 réplicas sobre a população inteira de MG. O público-alvo e a geografia dizem a quem a mídia chega. A simulação roda sobre toda a população das UFs, e a mensagem pode se espalhar para além do alvo pelo grafo social.