Jobs

Um job é uma simulação enviada: um cenário, a release em que ele roda, o preço reservado e o registro de tudo o que aconteceu com ele. Cada job roda numa máquina dedicada, sem acesso à rede, e o que ele devolve são os achados e o veredito; o registro guarda o hash do que a máquina produziu.

O nome do job

Cada job pode ter um nome, o que as pessoas usam para achá-lo no app, no chat e nos agentes, no lugar do id. O nome é opcional.

• Ao enviar, o job recebe o nome do cenário (até 80 caracteres). Um pedido sem nome gera um job sem nome, e o app mostra um rótulo com o tipo, as UFs e a data do envio.
• No app, um membro renomeia o job em Renomear, na página dele, com até 120 caracteres. O nome novo aparece na lista do projeto, na barra lateral, no extrato de créditos e para os agentes.
• Pela API e pelo MCP, o nome vem em nome, em GET /v1/jobs/{id} e na lista de jobs, e em get_job e list_jobs.
• O nome não entra no pedido nem no registro: renomear não muda o resultado, o preço nem a idempotência.

Estados do job

estado	O que significa	Créditos
reservado	Aceito e com o preço reservado; espera uma vaga numa máquina.	reservados
ligando	A máquina está subindo.	reservados
rodando	A simulação está rodando.	reservados
concluido	Os achados estão prontos para ler.	cobrado o preço cotado
falhou	O job não terminou.	a reserva volta inteira
cancelado	Você cancelou antes de existir máquina.	a reserva volta inteira

O caminho normal é reservado → ligando → rodando → concluido. concluido, falhou e cancelado são finais: um job nunca sai deles.

Avisos de fim

• Pela API ou por um agente: o webhook do projeto avisa o seu sistema quando o job termina.
• Pelo app: quem enviou o job recebe um e-mail quando ele conclui ou falha, com o link da página do job. O aviso se desliga em Perfil, no app.
• A página de status do app (app.brasilsintetico.com/status) mostra se a API e a execução de jobs estão operando.

Fila: quantos jobs rodam ao mesmo tempo

Cada organização tem até 2 jobs em máquinas (ligando ou rodando) ao mesmo tempo, e a plataforma tem um teto geral. Um job acima do teto não é recusado: ele espera em reservado e começa por ordem de chegada quando uma vaga abre.

Quanto tempo demora

Um job leva de minutos a horas, conforme o tamanho: a população das UFs, os dias, as variantes e as réplicas. O tempo conta a partir de quando ele sai da fila (registro.iniciado_em), e nenhum job roda mais de 12 horas.

Idempotência

POST /v1/jobs exige o cabeçalho Idempotency-Key (1 a 200 caracteres), escolhido por você:

• a mesma chave com o mesmo pedido devolve o job que ela já criou, com status 200 em vez de 201, sem reservar de novo;
• a mesma chave com outro pedido é recusada com 409 idempotency_key_reused.

Assim, repetir uma chamada cuja resposta se perdeu é sempre seguro. Pelo MCP, submit_simulation usa por padrão o próprio cenário como chave.

Cancelar

POST /v1/jobs/{id}/cancel cancela um job que ainda não tem máquina (reservado) e devolve a reserva. Depois que a máquina existe, o cancelamento é recusado com 409 job_not_cancellable.

Apagar os dados de um job

POST /v1/jobs/{id}/erase (ou erase_job_data no MCP, ou Apagar dados na página do job, por um admin) apaga o pedido, as entradas e o resultado de um job que já terminou: concluido, falhou ou cancelado.

• Na hora, os achados deixam de ser servidos, e o job mostra apagamento_pedido_em.
• Em alguns minutos, os arquivos guardados são apagados e o registro ganha registro.apagado_em.
• O registro fica, com os hashes e os créditos, mas o job não pode mais ser refeito. Não dá para desfazer.
• Um pedido igual de outro job continua guardado enquanto esse outro job precisar dele.
• Um job em andamento é recusado com 409 job_not_erasable.

Falhas

A plataforma termina um job que:

• passa 15 minutos sem dar sinal de vida;
• roda além de 12 horas.

Essas falhas, e qualquer erro na máquina, encerram o job em falhou, e você não paga nada: a reserva volta inteira, como reembolso automático. O motivo fica em registro.termino.motivo.

O registro

O campo registro de cada job resume a execução:

• o hash do pedido e os manifests da release em cada UF;
• os créditos reservados, cobrados e estornados;
• quando o job saiu da fila (iniciado_em) e como terminou (termino);
• o hash e o tamanho do resultado.

Ele guarda só hashes e referências, nunca dados de pessoas. O pedido, as entradas e o resultado ficam guardados por 365 dias, até registro.retencao_ate, para que o job possa ser refeito byte a byte. No dia seguinte, a plataforma apaga os dados do job como num pedido seu: o job passa a mostrar apagamento_pedido_em e registro.apagado_em, e o registro fica.