OkMigo

SDK Python e contrato das telas

Comece pelo catálogo Python: ele é a forma recomendada de escrever um aplicativo inteiro. A referência JSON vem depois e mostra a fronteira que o SDK gera, o crivo aceita e os renderizadores Web e Flutter reconstruem.

Fonte canônica: o pacote público okmigo-cartao reúne o SDK, o catálogo executável, o crivo e o renderer Web do preview. Esta página documenta a autoria; o crivo continua sendo a decisão final sobre o JSON que sobrevive.

Três regras fecham o contrato. Campo desconhecido some; capacidade desconhecida no servidor recusa a tela inteira; cliente antigo ignora o que ainda não sabe desenhar. Ação nunca aponta URL: ela nomeia uma operação, exceto okmigoAutorizar, que é a saída controlada para o site do serviço.

Catálogo do SDK Python

Importe sempre de okmigo_cartao. Primitivas e composições ficam no mesmo lugar e compilam para o contrato fechado.

Os grupos abaixo cobrem a árvore do aplicativo e os componentes de tela. Enums aparecem ao lado do componente que configuram. Funções de validação — validar, expandir, relatorio e materializar_manifesto — são ferramentas do ciclo de desenvolvimento, não componentes visuais.

Aplicativo, telas e dados

Declara o aplicativo inteiro, suas rotas, o tema e as operações que alimentam cada tela.

AplicativoSuperficieTelaFonteConsultaDaFonteTemaNavegacao

Texto e estrutura responsiva

Organiza conteúdo sem declarar pixels, CSS ou comportamento específico de plataforma.

TextoPapelDoTextoPainelSecaoAreaColunaFaixaFatoFatosEspacoAlinhamentoLarguraDaAreaAlturaDaSecaoTomDaSecao

Resumo, estado e leitura rápida

Cria fichas, métricas, estados vazios, etiquetas e indicadores de andamento.

FichaMetricaGradeDeMetricasEstadoVazioComAlternativaEtiquetaStatusTomDaEtiquetaProgressoBarraDeValor

Formulários e campos

Coleta dados com tipos e formatos conhecidos pelos renderizadores Web e Flutter.

FormularioCampoTextoCampoNumeroCampoOcultoCampoDataCampoHoraCampoMesCampoMoedaCampoDocumentoCampoTelefoneCampoUrlCampoEtiquetasCampoComUnidadeCampoFormatadoFormatoDoCampo

Escolhas, busca e controles

Cobre seleção simples ou múltipla, autocomplete remoto, condições, quantidade e liga/desliga.

OpcaoEscolhaFormaDaEscolhaBuscaEscolhaMultiplaFormaDaEscolhaMultiplaEscolhaCondicionalRegraAoAlterarSeletorDeQuantidadeAlternancia

Ações e cartões interativos

Consulta ou grava somente por operações declaradas; menus e confirmações não abrem uma saída lateral.

AcaoAcoesTipoDeAcaoEnfaseDaAcaoCartaoClicavelMenuDeAcoesConfirmacaoAlternarAlvoDeVisibilidadeEnviarEAvancar

Navegação dentro da tela

Troca conteúdo que já veio no cartão, sem rede e sem executar código do serviço.

AbaAbasFiltroSegmentadoExpansivelDialogo

Listas, repetição e tabelas

Expande dados com limites fechados e apresenta conteúdo denso com degradação previsível.

RepetirCondicaoTabelaTabelaFlexivelLinhaDeTabelaCelulaDeTabelaPaginacao

Imagem, arquivos e utilidades

Mostra mídia acessível, recebe e entrega arquivos, copia valores e controla autorizações.

ImagemAlturaDaImagemGaleriaDeImagensArquivoFormatoDeArquivoDocumentoCopiarCronometroAutorizar

Agenda e linha do tempo

Representa datas, eventos, gestos de agenda e etapas de um processo.

CalendarioVistaDoCalendarioEventoTipoDeEventoAoTocarODiaAcaoDoEventoGestoDoEventoLinhaDoTempoEtapaDaLinhaDoTempoEstadoDaEtapa

Gráficos e financeiro

Declara significado dos dados; os clientes escolhem cor, escala e adaptação por plataforma.

GraficoFormaDoGraficoSeriePontoTomDoGraficoCartoesFinanceirosCartaoFinanceiroListaFinanceiraLancamentoFinanceiroDistribuicaoItemDeDistribuicaoTomFinanceiroSemanticaFinanceira

Metadados e migração

Tipa capacidades do produto e ajuda a migrar manifestos antigos sem tornar o adaptador a fonte final.

OperacaoParametrizadaConviteMarcaSolicitadaContatoAceitoCatalogoPublicoMarcaHorarioTelaResumidaPainelResumidoItemResumidoAplicativoDoContrato

Validação e artefatos

Expande dados fictícios, executa o crivo, explica perdas e materializa o manifesto para registro.

ConfigContratoDoSdkInvalidovalidarexpandirrelatoriocascamanifesto_conferematerializar_manifesto

Regra de autoria: uma tela nova usa somente objetos exportados por okmigo_cartao. Dicionário cru fica restrito ao adaptador temporário AplicativoDoContrato. Se uma intenção ainda não existir, ela entra primeiro no SDK, crivo, Web, Flutter, acessibilidade, fallbacks e testes.

Exemplos Python

Os exemplos usam a API pública atual e podem ser copiados para o módulo de autoria do seu produto.

Formulário com escrita conferida

from okmigo_cartao import Acao, CampoTexto, Formulario, Tela

PERFIL = Tela(
    "Perfil",
    (
        Formulario(
            "Dados básicos",
            campos=(
                CampoTexto(
                    "nome_perfil", "nome", "Nome", obrigatorio=True
                ),
            ),
            acoes=(Acao.escrever("Salvar", "salvar_perfil"),),
        ),
    ),
)

PERFIL.conferir(escrituras={"salvar_perfil"})

Cartão clicável, três pontos e confirmação

from okmigo_cartao import (
    Acao, CartaoClicavel, Confirmacao, MenuDeAcoes, Texto
)

ativo = CartaoClicavel(
    (Texto("SANB11", negrito=True), Texto("R$ 28,10")),
    Acao.consultar("Abrir SANB11", "detalhar_ativo"),
    menu=MenuDeAcoes((
        Acao.escrever(
            "Remover dos favoritos",
            "remover_favorito",
            icone="lixeira",
            confirmacao=Confirmacao(
                "Remover favorito?",
                "Você poderá adicioná-lo novamente depois.",
                "Remover",
            ),
        ),
    )),
)

Para ver navegação real entre superfícies, dados fictícios, claro, escuro, desktop e celular, siga o exemplo de aplicativo completo ou abra o catálogo que acompanha o pacote:

python -m okmigo_cartao preview exemplos/sdk_catalogo.py:APLICATIVO

Contrato JSON aceito pelo crivo

Use esta parte para entender a fronteira, criar um renderer ou investigar a saída de compilar(); para autoria nova, prefira os componentes Python acima.

topo

`AdaptiveCard`

A raiz de uma tela declarativa. Sem ela, o crivo recusa o cartão.

typeversionbodyokmigoTemaokmigoNavegacao

Cuidados: Use okmigoTema/okmigoNavegacao só quando a natureza da experiência pedir. Temas aceitos: financeiro-violeta, jornada-ativa, mercado-editorial e operacao-direta. O cliente escolhe a aparência; tema desconhecido é ignorado. O resto do topo também é ignorado.

geral

`TextBlock`

Texto, título, legenda e frase de apoio.

textsizeweightisSubtlewraphorizontalAlignmentfallback

Cuidados: Cor não passa. Se precisar de estado, use texto ou tom na caixa que carrega o texto.

geral

`Container`

Agrupa blocos, cria painéis, tiles, etapas e áreas tocáveis.

itemsstyleidisVisibleminHeightselectActionokmigoGradeokmigoSobrepostofallback

Cuidados: selectAction só alterna visibilidade. okmigoGrade aceita true, larga, compacta ou etiquetas.

geral

`ColumnSet`

Colunas simples dentro de uma mesma linha visual.

columnsColumn.itemsColumn.widthColumn.styleColumn.minHeightfallback

Cuidados: Use auto só para conteúdo de tamanho conhecido; texto imprevisível deve ser stretch.

geral

`Table`

Grade tabular quando as colunas precisam alinhar entre linhas.

columnsrowsTableRowTableCellfirstRowAsHeadershowGridLinesfallback

Cuidados: Teto de 16 colunas por 200 linhas. Cabeçalho sem dado derruba a tabela, então declare fallback.

geral

`FactSet`

Pares curtos de rótulo e valor.

facts.titlefacts.valuefallback

Cuidados: Fato sem título some; sem fatos, o bloco inteiro some.

geral

`Image`

Imagem servida pelo domínio do OkMigo.

urlheightaltTextfallback

Cuidados: URL de terceiro é recusada. Use /img/... ou URL absoluta nossa; sem imagem válida vira marcador.

formulário

`Input.Text`

Campo de texto que viaja no submit da própria caixa.

idcampolabelvalueplaceholderisMultilineisRequiredmaxLengthokmigoSomenteLeitura

Cuidados: id é estado do cliente; campo é o nome enviado ao serviço. Número aqui pode ser interpretado errado.

formulário

`Input.Number`

Campo numérico com teclado e validação de número.

idcampolabelvalueplaceholderisRequiredminmaxokmigoSomenteLeitura

Cuidados: Use para peso, preço, quantidade e qualquer valor que precise continuar número.

formulário

`Input.ChoiceSet`

Escolha única por lista, fichas tocáveis ou busca filtrada.

idcampolabelchoicesvaluestyleisRequiredokmigoEstritookmigoQuemOperaokmigoNotaokmigoIcone

Cuidados: filtered sozinho é livre; filtered + okmigoEstrito só aceita opção da lista. okmigoQuemOpera é preenchido pelo OkMigo.

ação

`ActionSet`

Conjunto de botões que alternam visibilidade ou enviam formulário.

actionsokmigoRodapefallback

Cuidados: Botões sem ação válida somem. Rodapé prende o CTA ao pé da tela enquanto a caixa dele estiver visível.

ação

`Action.ToggleVisibility`

Mostra e esconde blocos que já estão no cartão.

titletargetElementselementIdisVisible

Cuidados: Não toca rede, não grava e não navega. É a base de abas, etapas e voltar dentro do cartão.

ação

`Action.Submit`

Envia os campos da própria caixa para uma operação do serviço.

titledata.operacaostylemodeokmigoAposEnviar

Cuidados: A operação precisa estar no contrato de escrita. okmigoAposEnviar só aceita ToggleVisibility explícito.

ação

`Action.Execute`

Consulta uma operação de leitura com os campos da própria caixa e recebe outra ficha.

titledata.operacaostylemode

Cuidados: A operação precisa estar no contrato de leitura; a ficha retornada atravessa o mesmo crivo.

arquivo

`okmigoArquivo`

Entrada de arquivo, porque Adaptive Cards não tem Input.File.

idcampolabelaceitamaxBytesisRequired

Cuidados: aceita usa palavras: pdf, imagem, xml, planilha, texto. Palavra desconhecida some.

arquivo

`okmigoDocumento`

Arquivo do serviço para a pessoa ver ou baixar.

titulonometipotamanholer.operacaoler.pedido

Cuidados: A operação de ler precisa ser leitura declarada. PDF e imagem abrem na própria tela.

utilidade

`okmigoCopiar`

Botão para copiar um valor: Pix, código de barras, protocolo.

rotulovalor

Cuidados: Sem valor, some. Não chama serviço e não sai do app.

visualização

`okmigoGrafico`

Gráfico de barras ou linha para poucas séries.

formatituloseries.rotuloseries.corpontos.rotulopontos.valores

Cuidados: Cores são semânticas: positivo, negativo, neutro, atencao, principal, suave. Não existe pizza.

visualização

`okmigoCalendario`

Calendário declarativo com eventos e gestos locais.

vistadeeventosaoTocarODiaacoesDoEvento

Cuidados: Um toque abre formulário ou mostra bloco; não escreve sozinho. Evento sem id desenha, mas não aceita ação.

saída controlada

`okmigoAutorizar`

A única ida permitida para um endereço do serviço, normalmente OAuth ou autorização.

urlrotulomotivo

Cuidados: URL precisa ser https, sem credencial embutida, sem IP/porta e nunca domínio do OkMigo.

interação

`okmigoCronometro`

Contagem regressiva dentro do cartão.

rotulosegundos

Cuidados: Faixa de 1 a 3600 segundos. Não começa sozinho; a pessoa inicia.

visualização

`okmigoProgresso`

Barra de progresso do tipo feito de total.

feitoderotulotom

Cuidados: Recebe números, nunca porcentagem pronta. de inválido some; feito fora da faixa é prensado.

reservado: tema financeiro

`okmigoCartaoBancario`

Cartão financeiro com fatura, limite e lançamentos.

cartoestitulonumerofaturalimiteprogresso_feitoprogresso_delancamentos

Cuidados: Use só no tema financeiro-violeta. Está público para transparência, mas não é bloco genérico.

reservado: tema financeiro

`okmigoDistribuicao`

Distribuição financeira por categoria ou fatia.

tituloitens.rotuloitens.valoritens.textoitens.tom

Cuidados: Bloco específico do Financeiro. Itens sem rótulo ou valor somem.

reservado: tema financeiro

`okmigoListaFinanceira`

Lista de lançamentos financeiros com busca e filtros.

buscafiltrositens.iditens.grupoitens.tipoitens.tituloitens.valoritens.semantica

Cuidados: Bloco específico do Financeiro. semantica fora de positivo/negativo/neutro cai em neutro.