--- title: "Study Bus" method: POST path: "/api/v1/study/bus" tags: ["estudo"] --- # Study Bus `POST /api/v1/study/bus` ## Request - Base URL: `https://app.estudoseletricos.com` (the document declares no server; this is the origin it was published from) - URL: `https://app.estudoseletricos.com/api/v1/study/bus` - Auth: none declared ## Request body - StudyRequest - `rede` NetworkRequest, required: Os registros dos data_editors (o mesmo contrato da tool `montar_rede`). - `unifilar_interativo` boolean: marca cada símbolo com `data-elem` para o clique (G126). É OPT-IN: o SVG default continua byte a byte o do laudo - `protecoes` Protecao[]: as proteções posicionadas, só para o DESENHO — elas não entram no cálculo de curto-circuito. Sem elas o diagrama sai sem os símbolos de proteção, e quem acabou de pôr um disjuntor pelo desenho não o veria aparecer. Lista vazia = o SVG de sempre. - `kind` 'bus' | 'edge', required - `ref` union, required: id da barra ('bus') ou [from_id, to_id] ('edge') - string - string[] - `label` string - `model_id` string, nullable: id no devices_db; None = ajuste manual - `color` string - `ajustes` object, nullable: ajustes DESTA proteção (curve, in, ir, tms, isden, isd, tsd, iien, ii, tinst, tab) e a tolerância DIGITADA de quem o banco não declara banda: toli (± % nos pickups), tolt (± % no tempo das curvas L e S) e tolii (± % só na instantânea — vence o toli no Ii). A identidade (placement_key) é resolvida no servidor, onde ela é definida — o cliente não a calcula. Fusível e MCB são de BANDA: aqui não há ajuste a fazer e o que vier é ignorado pelo núcleo. A curva TÉRMICA tabelada (G325), para o modelo cujo banco não a declara: `pts` (pontos [múltiplo, t_s] da borda lenta), `pts_rapida` (a rápida, opcional), `pts_base` ('Ir' ou 'In', obrigatória) e `pts_fonte` (de onde vieram) - `datablock` 'curto' | 'arco' | 'adequacao' | 'protecao': O QUE cabe no bloco de dados de cada barra, decidido no SERVIDOR — não é filtro de tela. `curto` traz as quatro correntes; `arco` traz só a Ik3φ, porque a energia e o tempo entram pelo estudo e quatro correntes ao lado deles tornam o bloco ilegível; `adequacao` traz Ik3φ e ip, que são as duas que o duty compara; `protecao` traz a máxima e a MÍNIMA, que são os limites entre os quais o pickup vive - `unifilar_subrede` string, nullable: id de barra: desenha só a ÁREA dela (a barra e o que está a jusante). As áreas da rede vêm em `areas`; None = a folha da rede inteira - `barras` object[], required: as barras (id, label, Vn_kV) — até 500 por rede (G342) - `elementos` object[], required: transformadores, cabos, barramentos e reatores — até 1000 por rede (G342) - `fonte` object, nullable: a concessionária no ponto de conexão. Ausente (ou nula) só na rede alimentada por gerador — sem nenhum dos dois é recusa de forma - `motores` object[], nullable - `geradores` object[], nullable: geradores síncronos por barra (G334, IEC 60909-0 §6.6.1): bus_id, label, Sn_kVA, xd2_pu, cos_phi e os opcionais U_rG_kV, x0_pu, aterramento, Rn_ohm - `cenarios` object[], nullable: os cenários de OPERAÇÃO (G336): nome, `fontes` em serviço ('concessionaria' e as barras com gerador; ausente = todas) e `abertas` (os elementos abertos, [DE, PARA] ou 'DE→PARA'). Com eles o estudo de arco de cada barra é o do cenário de MAIS energia - `lang` string - `unifilar` boolean - `folha` Folha: Carimbo do unifilar (sheet_meta): o que a UI sabe do estudo. - `local` string - `equip` string - `resp` string - `crea` string: registro do responsável no CREA - `art` string: nº da ART do estudo - `rev` string: identificação da revisão (ex.: 'rev 3') - `rev_data` string: data da revisão, como o emissor a escreve - `wl_name` string - `protecoes` Protecao[], required - `kind` 'bus' | 'edge', required - `ref` union, required: id da barra ('bus') ou [from_id, to_id] ('edge') - string - string[] - `label` string - `model_id` string, nullable: id no devices_db; None = ajuste manual - `color` string - `ajustes` object, nullable: ajustes DESTA proteção (curve, in, ir, tms, isden, isd, tsd, iien, ii, tinst, tab) e a tolerância DIGITADA de quem o banco não declara banda: toli (± % nos pickups), tolt (± % no tempo das curvas L e S) e tolii (± % só na instantânea — vence o toli no Ii). A identidade (placement_key) é resolvida no servidor, onde ela é definida — o cliente não a calcula. Fusível e MCB são de BANDA: aqui não há ajuste a fazer e o que vier é ignorado pelo núcleo. A curva TÉRMICA tabelada (G325), para o modelo cujo banco não a declara: `pts` (pontos [múltiplo, t_s] da borda lenta), `pts_rapida` (a rápida, opcional), `pts_base` ('Ir' ou 'In', obrigatória) e `pts_fonte` (de onde vieram) - `barra_estudo` string, required - `ajustes` object: por placement_key (ver resposta): curve, in, ir, tms, isden, isd, tsd, iien, ii, tinst, tab, a tolerância digitada toli/tolt/tolii (± % nos pickups · no tempo das curvas L e S · só na instantânea) e a curva térmica tabelada pts/pts_rapida/pts_base/pts_fonte (G325) - `cb_open_ms` number: tempo de abertura do disjuntor (ms), somado ao tempo de atuação das proteções nos dois lados do compartimento. Com um RELÉ decidindo, 0 ms deixa de fora os ciclos do disjuntor que ele comanda — e o aviso sai em `avisos` - `t_sem_atuacao_ms` number, nullable: OPÇÃO, desligada por padrão (nulo): o tempo máximo de arco, em ms, adotado na barra cuja proteção EXISTE e não vê nenhuma das correntes de arco (G329). Com ela a barra ganha energia no tempo declarado — sem somar abertura — e a marca `t_max_adotado = sem_atuacao`; sem ela, sai sem número, como sempre. Maior que zero e no máximo 2000 ms (IEEE 1584:2018 §6.9.1), senão 422. A barra sem proteção declarada continua sem número, e o alerta `retaguarda_cega` permanece - `banda_padrao` 'norma', nullable: banda PADRÃO do disparador de curto-circuito onde o banco não declara banda e nenhuma tolerância foi digitada: 'norma' aplica ±20 % na instantânea do disjuntor termomagnético (IEC 60947-2), dito na folha como premissa do estudo; eletrônico e relé seguem na curva ajustada. Nulo = a curva nominal, como sempre foi - `base_ibf` 'pior_caso' | 'nominal', nullable: OPÇÃO, desligada por padrão (nulo = a corrente de curto MÁXIMA, como sempre): 'pior_caso' calcula cada barra também com a corrente MÍNIMA (IEC 60909-0 §7.1.2, ou a fonte mínima que a concessionária declara em `fonte.Icc_min_kA`) e fica com a que dá MAIS energia no cenário governante (NBR 17227 §4.2.1.3 e §5.1.12). O modo que governou sai em `ibf_base` de cada cenário; a corrente mínima que não pôde ser calculada é 422. 'nominal' (G328) calcula a energia com a corrente de TENSÃO NOMINAL — c = 1,0 no ponto de falta, sem K_T e os cabos em `t_cabo_C` (nulo = a temperatura de cada cabo): a base dos estudos feitos em tensão nominal, FORA do §7.1.2, dita no laudo; a máxima da norma segue dimensionando a barra - `t_cabo_C` number, nullable: a temperatura dos cabos (°C) na base `nominal` de Ibf (G328): nula = a temperatura declarada em cada cabo. Só vale com `base_ibf='nominal'` - `geometria` object: por id de barra - `geometria_padrao` GeometriaPadrao: A geometria padrão da PLANTA por classe de tensão — o 'study case' do arco (W6). Cada classe é uma declaração PARCIAL sobre o padrão do núcleo (o campo nulo continua sendo o dele), e a declaração POR BARRA prevalece sobre as duas. Duas classes porque o padrão do núcleo tem duas (até 1 kV · acima). - `bt` Geometria: A geometria de arco DAQUELA barra — uma declaração PARCIAL sobre o padrão por tensão do núcleo (BT: G=32 · D=610 · MT: G=152 · D=914). Nenhum campo é obrigatório e nenhum tem default AQUI: quem sabe o padrão é o núcleo, e repeti-lo no contrato seria a segunda definição dele. O que vier nulo continua sendo o padrão — é o que permite declarar só a distância de trabalho de cinquenta barras sem afirmar medição do resto. - `G` number, nullable - `D` number, nullable - `W` number, nullable - `H` number, nullable - `P` number, nullable - `cfg` string, nullable - `confirmado` boolean, nullable: a geometria foi CONFERIDA em campo, e não assumida do padrão por tensão. Não muda cálculo nenhum — muda o que o memorial afirma, e afirmar que se mediu o que se herdou é o começo de um laudo errado - `mt` Geometria: A geometria de arco DAQUELA barra — uma declaração PARCIAL sobre o padrão por tensão do núcleo (BT: G=32 · D=610 · MT: G=152 · D=914). Nenhum campo é obrigatório e nenhum tem default AQUI: quem sabe o padrão é o núcleo, e repeti-lo no contrato seria a segunda definição dele. O que vier nulo continua sendo o padrão — é o que permite declarar só a distância de trabalho de cinquenta barras sem afirmar medição do resto. - `G` number, nullable - `D` number, nullable - `W` number, nullable - `H` number, nullable - `P` number, nullable - `cfg` string, nullable - `confirmado` boolean, nullable: a geometria foi CONFERIDA em campo, e não assumida do padrão por tensão. Não muda cálculo nenhum — muda o que o memorial afirma, e afirmar que se mediu o que se herdou é o começo de um laudo errado - `figura` boolean: renderiza a folha TCC (PNG base64) - `svg` boolean: devolve também a folha em SVG (`tcc_svg`) — o mesmo desenho do PNG, com um id por curva: `tcc-curva-{n}` é o número do badge e o `tag` da folha de ajustes, e `tcc-faixa-reprovada-{par}-{k}` a faixa de seletividade do par - `I_max_kA` number, nullable - `T_max_ms` number - `erms_on` boolean: modo MANUTENÇÃO (ERMS · NEC 240.87): desenha a curva de manutenção ao lado da normal e compara as duas energias. Não altera o ajuste de operação — é um modo comutável, para trabalho energizado - `erms_ii_pu` number: instantâneo do modo manutenção, em múltiplos de In - `camadas_elemento` CamadasElemento: As camadas que o PRÓPRIO unifilar define para a folha: o dano do transformador que alimenta a barra, a partida dos motores dela e o dano k²S² do CABO que chega nela. As três juntas são o coordenograma de um motor — a curva de partida dele, o limite do cabo que o alimenta e a proteção que fica entre os dois — e é por isso que inserir um motor pelo diagrama cria também a barra dos terminais e o cabo: sem eles, duas dessas camadas não existem. Desligadas por omissão — a do transformador abre o eixo de tempo até ~1100 s, e ligá-la por padrão mudaria em silêncio a forma de toda folha existente. - `trafo` boolean - `motor` boolean - `cabo` boolean - `camadas_folha` CamadasFolha: As camadas de LEITURA da folha TCC — as mesmas da aba do coordenograma (`coord_show_*`). Nenhuma muda número: o tempo, a energia e o ponto de operação continuam calculados com elas desligadas (G128). A omissão é a folha que esta rota sempre desenhou. - `arco` boolean: verticais da corrente de arco (plena e reduzida) com os marcadores de operação. Desligada, a folha é de PROTEÇÃO pura — a que vai à concessionária - `ibf` boolean: vertical da falta franca da barra - `ikmin` boolean: corrente MÍNIMA (§7.1.2): pickup à direita dela não detecta a falta no fim do circuito - `ponto_ei` boolean: ★ no ponto de operação, com a energia e a categoria - `zonas_ei` boolean: fundo por categoria da NBR 17227 (1,2 · 12 · 40 cal/cm²), com a geometria da própria barra - `ith` boolean: corrente TÉRMICA equivalente Ith = Ik″·√(m+n) (Cláusula 14) no tempo de eliminação da própria folha. Sem duração não há grandeza térmica: a marca não sai, e `camadas_fora` diz por quê - `seletividade` boolean: as FAIXAS de corrente em que um par adjacente da cadeia reprova a seletividade (IEC 60255-151, margem de 15 %), atrás das curvas. O veredito é o de `seletividade`; par não verificado não tem faixa, e sem par reprovado a camada volta em `camadas_fora` com o motivo - `ferramentas` EstudoDoCaderno[]: os estudos da SUÍTE que o projeto carrega (`v2.tools`), no mesmo formato do caderno. O que cada ferramenta publica vira CAMADA da folha TCC — a ponte entre a ferramenta e o estudo. O que não pode ser desenhado volta em `camadas_fora`, com o motivo - `slug` string, required: o slug do catálogo (`GET /tools`) - `corpo` object, required: o corpo da rota `/tools//memorial` - `veredito` string: o que a tela mostrou - `resultado` string: a manchete do estudo ## Response `200` Successful Response - StudyResponse - `camadas` string[]: o que a folha TCC desenha além das curvas: as camadas das FERRAMENTAS da suíte, as do PRÓPRIO elemento e as de leitura pedidas (o Ith, com o tempo e o m; as zonas de energia) - `camadas_fora` CamadaFora[]: COBERTURA: os estudos da suíte que não viraram camada, com o motivo - `slug` string, required - `motivo` string, required - `camadas_premissas` string[]: o que a camada ASSUME porque a rede não declara (inrush, tempos de partida) — padrão da plataforma não pode passar por dado do equipamento - `folha_declara` string[]: o que a FOLHA somou e de onde veio cada banda (G307 · G308): a curva do relé com os ciclos do disjuntor que ele comanda (e se foram assumidos) e a banda do fabricante de cada disjuntor, com a fonte — o que o traço não diz sozinho - `estudos_realizados` string[]: o estudo de UMA barra resolve a cadeia de proteção e a energia incidente dela: são as duas análises, e o índice recebe as duas - `barra` object, required - `correntes` object, required - `criterios` CriterioOut[]: os CRITÉRIOS DO ESTUDO declarados (G318): regras, corrente de curto da energia, fontes máxima e mínima, c, K_T, cabos, banda, tempo máximo sem atuação, abertura do disjuntor e o teto de 2 s - `chave` string, required - `rotulo` string, required - `valor` string, required - `pior_caso` object, nullable: com `base_ibf='pior_caso'` (G333): os DOIS modos que o estudo comparou — max e min, cada um com a corrente (ibf_kA), o Ei governante e o lado que governou. O que valeu está em `ibf_base` dos cenários. Nulo sem a opção - `operacao` string, nullable: G336: o cenário de OPERAÇÃO que governa a barra (o de mais energia) — a folha, o desenho e os números são os dele. Nulo sem cenários - `operacoes` object, nullable: G336: a energia governante da barra em cada cenário em que ela está energizada (nulo = sem número nele) - `placement_keys` string[], required - `janela` object[], required - `cenarios` object, required - `governante` string, required - `Ei_gov` number, nullable - `t_gov_ms` number, nullable - `categoria` Categoria - `n` integer, required: 1 = abaixo do LAS · 2 = Tab. 11 · 3 = Tab. 12 · 5 = proibido - `label` string, required - `faixa` string, required - `arco` ArcoDaBarra: O DETALHE do arco numa barra da rede resolvida: o `arc/study` com as entradas que o estudo da barra usou — a tensão e a falta franca da barra, a geometria dela (própria ou o padrão por tensão) e o PAR de tempos do cenário GOVERNANTE (é com o par, e não com o máximo dos dois, que a energia reproduz a do estudo — G152). Fora do domínio do IEEE 1584 o estudo é nulo e `motivo` diz por quê. - `entrada` ArcRequest, required - `Voc` number, required: tensão de operação (kV) - `Ibf` number, required: corrente de falta franca trifásica (kA) - `G` number, required: gap entre condutores (mm) - `D` number, required: distância de trabalho (mm) - `T_p` number, required: tempo de eliminação na Iarc plena (ms) - `T_r` number, nullable: tempo na Iarc reduzida (ms); default = T_p - `W` number - `H` number - `P` number - `cfg` string - `lang` string - `estudo` ArcStudyCore: O ESTUDO de uma barra pelo IEEE 1584/NBR 17227, na ordem em que a tela decide: o número, a categoria e o EPI que ela impõe, o que a entrada tem de incoerente, se o Ei ainda é conservador na distância adotada e o que faria a categoria cair. É o que a aba do Streamlit monta em cinco chamadas ao núcleo — aqui vai numa só, para a tela não poder discordar de si mesma. - `Ei_cal` number, required - `LAS_mm` number, required - `Iarc_kA` number, required - `Imin_kA` number, required - `Ei_pleno_cal` number, required - `Ei_reduzido_cal` number, required - `governante` 'pleno' | 'reduzido', required - `categoria` Categoria, required - `n` integer, required: 1 = abaixo do LAS · 2 = Tab. 11 · 3 = Tab. 12 · 5 = proibido - `label` string, required - `faixa` string, required - `epi` string[]: EPI da Tabela 11/12 para a categoria (fonte única) - `D_rec_mm` number, required: distância recomendada da Tabela 3 - `avisos` string[]: faixas (validate_raw) - `coerencia` string[]: coerência cruzada (validate_coherence) - `conservador` ConservadorOut: Lado ALTO da NC-01 (`calc_core.d_conservative_check`): a distância de trabalho passou da recomendada além da tolerância, então o Ei calculado em D DEIXA de ser conservador. `None` dentro da tolerância — o lado baixo (o trabalhador perto demais) sai como aviso de coerência. - `D_rec` number, required - `Ei_conservative` number, required: Ei recalculado na distância normativa - `pct_over` number, required - `mitigacao` MitigacaoOut: `calc_core.mitigation_targets`: o tempo e a distância que levariam a categoria de EPI para a faixa imediatamente abaixo. Alvo NÃO atingível vem NULO — nunca 0, que a tela leria como 'basta zerar'. - `current_cat` integer, required - `target_cat` integer, required - `target_ei` number, required - `T_current` number, required - `D_current` number, required - `T_target` number, nullable - `T_at_D_rec` boolean - `D_target` number, nullable - `D_rec` number, required - `D_norm_met` boolean, required - `D_over_norm` boolean, required - `Ei_norm_ref` number, nullable - `Ei_current` number, required - `T_var` string, required - `plausibilidade` string[]: o que o RESULTADO tem de implausível (check_result_plausibility) - `anexo_iv` AnexoIvOut: A equivalência da categoria de EPI da NR-10, Anexo IV (Portaria MTE 737/2026, ref. NFPA 70E) — referência CRUZADA, não substitui a Tabela 11/12 da NBR 17227. Abaixo de 1,2 cal/cm² e a partir de 40 não há categoria (nulos); `acima_da_cat4` separa os dois casos. - `categoria` integer, nullable - `atpv_min_cal` number, nullable - `acima_da_cat4` boolean - `nr10_zonas` ZonasNr10Out: As zonas de aproximação da NR-10, Anexo II (Tabela 1), para a tensão: o raio da zona de RISCO e o da CONTROLADA. É proteção contra CHOQUE — não se confunde com a fronteira de arco (LAS). - `Rr_m` number, required - `Rc_m` number, required - `faixa` string, required - `motivo` string, nullable - `ciencia` CienciaOut: O GATE DE EMISSÃO (C29 · W8): o Termo e o CONJUNTO de alertas em vigor, com a impressão dele. A ciência vale para o conjunto em que foi dada — mudou o conjunto, muda o `hash`, e ela cai. Conjunto vazio ainda exige o Termo. - `termo` string, required - `alertas` AlertaCiencia[] - `codigo` string, required - `severidade` string, required - `texto` string, required - `hash` string, required - `n` integer - `impressao_modelo` string, nullable: a IMPRESSÃO DO MODELO (W8): sha256 (16 hex) da forma canônica do que define os números — rede, proteções, ajustes, geometria e tempo de abertura. É a que a capa do documento imprime; o carimbo e o idioma não a mudam, e é a MESMA no estudo da planta - `tabela_mestra` object[], required - `tags` object[], required - `tcc_png_b64` string, nullable - `tcc_svg` string, nullable: a MESMA folha em SVG (só com `svg=true`), com um id por curva - `erms` ErmsOut: Os DOIS cenários do modo manutenção (C39/G72). Existe como bloco próprio porque o que decide o procedimento é a diferença: se a energia de manutenção não muda a categoria, ligar o ERMS não dispensa nada. - `ii_pu` number, required - `Ei_normal` number, required - `Ei_erms` number, required - `t_normal_ms` number, required - `t_erms_ms` number, required - `cat_normal` integer, required - `cat_erms` integer, required - `seletividade` ParSeletividade[]: os pares ADJACENTES da cadeia e o veredito — o MESMO que a aba do coordenograma mostra e o memorial imprime - `up` string, required - `dn` string, required - `selective` boolean, nullable - `n_failures` integer, nullable - `n_points_tested` integer, nullable - `margin_required_pct` number, nullable - `motivo` string, nullable - `falhas` object[]: ponto a ponto: I_kA, t_up_ms, t_dn_ms, margin_pct e o tipo (issue) - `faixas` FaixaReprovada[]: as faixas de CORRENTE em que o par reprova — o que a camada `seletividade` da folha desenha; vazia no par seletivo ou não verificado - `I_de_kA` number, required - `I_ate_kA` number, required - `tipos` string[] - `I_min_barra_kA` number, nullable: a MENOR corrente de falta nesta barra que atravessa o par (arco reduzido do ramo ou curto mínimo referido ao ramo) — cada falha diz em `na_faixa` se está acima dela (G233) - `n_na_faixa` integer, nullable: quantos conflitos estão NA faixa de falta desta barra; os outros só existem com falta mais a jusante. Nulo no par não verificado - `sequencia` object: quem abre e em quantos ms: `ibf` na falta franca (a da coordenação) e `iarc` na corrente de arco (a da energia), com o intervalo até a seguinte - `resumo_ajustes` LinhaAjuste[]: a FOLHA DE AJUSTES da figura: cada curva com o número do badge (`tag`, nulo se não foi desenhada) e os ajustes NATIVOS — a mesma tabela do memorial e da prancha - `label` string, required - `tag` integer, nullable - `type` string, required - `In_A` number, nullable - `curve_name` string, nullable - `Ir_pu` number, nullable - `TMS` number, nullable - `Isd_pu` number, nullable - `tsd_ms` number, nullable - `Ii_pu` number, nullable - `t_inst_ms` number, nullable - `fora_escala` ForaEscala[]: as proteções da folha de ajustes SEM curva na janela do gráfico, com o pickup — calar a ausência seria mostrar menos curvas do que a tabela lista - `label` string, required - `pickup_A` number, nullable - `fora_escala_nota` string, nullable: o porquê e o remédio, no texto do núcleo - `I_max_kA` number, nullable: a corrente máxima do eixo da folha — a que foi usada - `unifilar_svg` string, required - `avisos` string[], required - `engine` string, required - `tier` string, required ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/estudoseletricos/apis/arc-flash-platform-api.md) · [All operations](https://skmtc.dev/estudoseletricos/apis/arc-flash-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/estudoseletricos/apis/arc-flash-platform-api/revisions/5877d717cb1b?raw)