Pular para o conteúdo
OkMigo

← voltar para o guia de integração

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.

Ações no grupo

Declara o que o serviço pode fazer num grupo do okmigo — responder, sugerir publicação, enquete. Quem modera ativa e escolhe as capacidades; o okmigo confere e executa. O serviço nunca vê o grupo: recebe só uma referência opaca.

grupo

Aplicativo, telas e dados

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

AplicativoSuperficieTelaFonteConsultaDaFonteTemaNavegacaoDocumentoDeclaradoTelaResponsiva

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.

FormularioFormularioContextualCampoTextoCampoNumeroCampoOcultoCampoDataCampoHoraCampoMesCampoMoedaCampoDocumentoCampoTelefoneCampoUrlCampoEtiquetasCampoComUnidadeCampoFormatadoFormatoDoCampo

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

Navegação do aplicativo

Registra destinos internos, organiza muitas telas, busca em todo o app, adapta lista/detalhe e declara somente o estado de UI que pode ser restaurado.

RotaDestinoDaRotaParametroDaRotaTipoDeParametroDaRotaCabecalhoDaTelaNavegacaoAgrupadaGrupoDeNavegacaoIndicadorDeNavegacaoEstadoDoIndicadorMestreDetalheFluxoEtapaDoFluxoBuscaDoAplicativoTipoDeResultadoDaBuscaEstadoRestauravelPersistenciaDoEstadoHistoricoDeNavegacao

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.

ImagemAlturaDaImagemGaleriaDeImagensArquivoFormatoDeArquivoDocumentoCopiarConviteDoGrupoCronometroAutorizar

Leitura de dados

Mostra número com contexto: ranking com o critério à vista, tendência com rótulo, comparação lado a lado sem nota final, agenda por data e o estado de um dado que pode estar velho.

RankingItemDeRankingMinigraficoComparadorItemComparadoCriterioComparadoAgendaItemDaAgendaEstadoDoCompromissoCabecalhoDeDetalheEstadoDoDadoEstadoDaInformacao

Agenda e linha do tempo

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

CalendarioVistaDoCalendarioEventoTipoDeEventoNavegacaoDoCalendarioAoTocarODiaAcaoDoEventoGestoDoEventoLinhaDoTempoEtapaDaLinhaDoTempoEstadoDaEtapa

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

Agente de domínio (contrato 1)

Declara um agente que entende o domínio do produto, com competências, ferramentas de leitura da conversa, instruções curtas e orçamento. Valida as quatro respostas: respondido, precisa_esclarecer, acao_proposta e indisponivel.

AgenteDeDominioOrcamentoExemploAgenteInvalidovalidar_respostaRespostaDeAgenteInvalida

Papel do app (broker de roteamento)

Declara o que o app é dono, de quem recebe e para quem entrega pelo okmigo, o vocabulário e as falas de quem usa — o que o broker lê para mandar o pedido ao app DONO. O crivo avisa o que falta no cadastro e confere os dois lados das relações.

PapelRelacaoExemploDeRoteamentoPapelInvalidoavisos_do_cadastropares_que_nao_batem

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",
            ),
        ),
    )),
)
Rota tipada, cabeçalho e busca global
from okmigo_cartao import (
    Acao, BuscaDoAplicativo, CabecalhoDaTela, ConsultaDaFonte, Fonte,
    ParametroDaRota, Rota, TipoDeResultadoDaBusca,
)

cabecalho = CabecalhoDaTela(
    "Cliente",
    "Detalhe seguro, sem URL livre",
    acao_principal=Acao.navegar(
        "Abrir cliente", "cliente", parametros={"id": "cli-42"}
    ),
)

# Dentro de Aplicativo(...)
rotas = (Rota("cliente", "detalhe", (ParametroDaRota("id"),)),)
# Na superfície "detalhe": a fonte pede o parâmetro da rota pelo marcador.
fonte = Fonte(ConsultaDaFonte("detalhar_cliente", pedido={"cliente": "{rota.id}"}))
busca = BuscaDoAplicativo(
    "buscar_tudo",
    (TipoDeResultadoDaBusca("cliente", "Cliente", "cliente", "clientes"),),
    placeholder="Buscar cliente ou pedido",
)
Calendário responsivo com quatro vistas e período navegável
from okmigo_cartao import (
    Calendario, DestinoDaRota, Evento, NavegacaoDoCalendario,
    VistaDoCalendario,
)

agenda = Calendario(
    eventos=(Evento("{inicio}", "{titulo}", id="{id}"),),
    vista=VistaDoCalendario.MES,
    vistas=(
        VistaDoCalendario.DIA,
        VistaDoCalendario.SEMANA,
        VistaDoCalendario.MES,
        VistaDoCalendario.AGENDA,
    ),
    de="{periodo_de}",
    ate="{periodo_ate}",
    hora_inicial=8,
    hora_final=20,
    ao_navegar_periodo=NavegacaoDoCalendario(
        DestinoDaRota("agenda_periodo", {}),
        parametro="periodo",
    ),
)

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.

utilidade

okmigoConviteDoGrupo

Convidar para o grupo do okmigo que nasceu de uma coisa do serviço (a turma do GrupoIn).

rotuloref

Cuidados: O ref é o mesmo de okmigo_grupos_nascem. O okmigo gera o link ao toque, só para quem pode convidar; o serviço nunca vê o link nem o grupo.

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.

vistavistasdeatehoraInicialhoraFinaleventosaoTocarODiaacoesDoEventoaoNavegarPeriodo

Cuidados: Um toque abre formulário ou mostra bloco; não escreve sozinho. Evento sem id desenha, mas não aceita ação. `aoNavegarPeriodo` pede outro período por uma rota declarada (NavegacaoDoCalendario); cliente que não a conhece mostra só o período recebido.

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.

navegação

okmigoCabecalhoDaTela

Topo consistente de tela ou detalhe, com voltar, favorito, ação principal e menu.

titulosubtitulovariantevoltaracaoPrincipalfavoritardesfavoritarmenu

Cuidados: Navegação só usa rota registrada; favorito só usa escrita declarada. O renderer decide a adaptação.

estrutura adaptativa

okmigoMestreDetalhe

Lista e detalhe lado a lado quando cabe, ou uma etapa por vez no celular.

idlistadetalhevazioselecionado

Cuidados: Lista e detalhe passam integralmente pelo crivo e contam no teto de nós.

jornada

okmigoFluxo

Fluxo de 2 a 12 etapas com progresso, retomada e cancelamento explícito.

idetapasatualtokenDeRetomadapersistircancelar

Cuidados: O cliente apresenta a etapa; avançar e persistir continuam sendo operações declaradas.

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.