Desenvolver um aplicativo

Esta página é para quem programa o aplicativo. O aplicativo é uma página web comum, publicada pela sua empresa. Ela conversa com o MakePro por uma biblioteca JavaScript de arquivo único, o SDK de aplicativos.

Como o aplicativo conversa com o MakePro

• O aplicativo não guarda nem recebe login, senha ou chave de API.
• O MakePro abre a página dentro do quadro e entrega a ela o contexto: o lugar, a empresa, o quadro, os itens, a pessoa e o tema.
• O aplicativo pede os dados ao MakePro pelo SDK. O MakePro faz a chamada à API pública com o acesso da pessoa e devolve a resposta.
• As rotas, os parâmetros e as respostas são os mesmos da API pública. Use a referência no Swagger para montar as chamadas.

Começar

Carregue o SDK e conecte:

<script src="https://app.makepro.com.br/sdk/apps-v1.js"></script>
<script type="module">
  const contexto = await makepro.conectar();
  document.title = `Relatório de ${contexto.usuario.nome}`;
</script>

makepro.conectar() espera o MakePro responder e devolve o contexto. Aberta fora do MakePro, a página não recebe resposta e o pedido termina com TEMPO_ESGOTADO.

Exemplos prontos

Veja Exemplos com o SDK para ler colunas e itens, criar e alterar itens, alterar em lote, comentar, enviar arquivos e tratar erros, com um aplicativo completo no fim.

O contexto

{
  ponto: 'notes.guia_quadro',                // onde o aplicativo foi aberto
  escopo: { empresaId: 'comp_…', projetoId: null },
  conteiner: { tipo: 'quadro', id: '…' },    // o quadro
  alvos: { tipo: 'item', ids: ['…'] },       // item aberto ou itens marcados; vazio na guia do quadro
  usuario: { id: '…', nome: 'Ana' },         // sem e-mail
  tema: 'claro'                              // 'claro' ou 'escuro'
}

ponto	Onde a pessoa abriu	alvos.ids
notes.guia_quadro	Guia do quadro	vazio
notes.guia_item	Guia no painel do item	o item aberto
notes.acao_item	Menu do item	o item
notes.acao_multi	Barra de seleção	os itens marcados, até 500

No painel do item, a pessoa pode abrir outro item sem fechar o aplicativo. Ouça a troca:

makepro.aoMudarContexto((novo) => desenhar(novo));

makepro.contexto() devolve o contexto atual a qualquer momento.

Ler e alterar dados

makepro.fetch(caminho, { method, body }) chama uma rota da API pública. O caminho começa com /api/v1, e o corpo é um objeto JSON.

const { empresaId } = contexto.escopo;
const quadro = contexto.conteiner.id;
const base = `/api/v1/companies/${empresaId}/notes/boards/${quadro}`;

const itens = await makepro.fetch(`${base}/elements`);
if (itens.ok) desenharTabela(itens.corpo);

const criado = await makepro.fetch(`${base}/elements`, {
  method: 'POST',
  body: { name: 'Medição de novembro' },
});

A resposta tem sempre o formato { ok, status, corpo }. Um erro da API, como 403 ou 404, não dispara exceção: ele chega em status e corpo.

Métodos aceitos: GET, POST, PATCH, PUT e DELETE.

Avisar e fechar

await makepro.avisar('Medição salva');  // aviso no MakePro, com o nome do aplicativo
await makepro.fechar();                 // fecha a janela; só no menu do item e na seleção

Arquivos

As operações de arquivo exigem a permissão Baixar e enviar arquivos no cadastro. O arquivo passa pelo MakePro, e o aplicativo nunca recebe um link de download.

// Baixar os bytes de um anexo
const arquivo = await makepro.baixarArquivo({ element_id, column_id, asset_id });
// arquivo = { asset_id, filename, content_type, size, bytes }

// Salvar o anexo no computador da pessoa
await makepro.salvarArquivo({ element_id, column_id, asset_id });

// Enviar um arquivo para uma coluna de arquivo
const anexo = await makepro.enviarArquivo({
  element_id, column_id,
  filename: 'relatorio.pdf',
  content_type: 'application/pdf',
  bytes,                                // ArrayBuffer
});
// anexo = { asset_id, filename, extension, content_type, size }

Para anexos de subitem, informe também subelement_id. O item precisa estar no contexto do aplicativo.

Rotas de arquivo não passam pelo fetch

As rotas da API pública que devolvem link de download ou de envio são recusadas em makepro.fetch com ROTA_DE_ARQUIVO_PELA_PONTE. Use baixarArquivo, salvarArquivo e enviarArquivo.

Erros

Quando o MakePro recusa um pedido, a promessa é rejeitada com { codigo, mensagem }:

codigo	Quando acontece
TEMPO_ESGOTADO	O MakePro não respondeu a tempo, ou a página foi aberta fora do MakePro.
OPERACAO_DESCONHECIDA	A operação não existe nesse lugar, como fechar() na guia do quadro.
PARAMETRO_INVALIDO	Faltou um parâmetro ou ele tem o formato errado.
CAMINHO_INVALIDO	O caminho não começa com /api/v1 ou tem ...
FORA_DO_CONTEXTO	O item não está no contexto do aplicativo.
ROTA_DE_ARQUIVO_PELA_PONTE	A rota devolve link de arquivo; use as operações de arquivo.
SEM_PERMISSAO	O cadastro não tem a permissão de arquivos.
ARQUIVO_GRANDE	O arquivo passa de 100 MB.
RESPOSTA_GRANDE	A resposta da API é grande demais para o aplicativo.
LIMITE_DE_TAXA	Pedidos demais em pouco tempo.

Na API, as recusas mais comuns são:

status e código no corpo	Por quê
403 APP_ROTA_NAO_PUBLICA	A rota não faz parte da API pública.
403 PUBLIC_API_NOT_GRANTED	A API pública não está liberada para a empresa.
403 com outro código	A pessoa não tem acesso, ou o cadastro não tem a permissão de leitura ou de alteração.

Limites

Limite	Valor
Pedidos por minuto	60
Pedidos ao mesmo tempo	8
Corpo do fetch	5 MB
Arquivo	100 MB
Tempo de resposta	15 segundos; 6 minutos nas operações de arquivo
Itens marcados na seleção	500

Publicar e testar

• Publique a página num endereço https com nome de domínio público. O MakePro não abre http, IP, localhost nem rede interna.
• Para testar uma versão local, exponha a página num endereço https público, por exemplo com um túnel, e cadastre esse endereço num aplicativo de teste.
• Cadastre o aplicativo com só as permissões que ele usa e habilite-o num quadro de teste antes de liberar para a equipe.

Não peça senha dentro do aplicativo

O MakePro avisa a pessoa, acima de toda página de aplicativo, que ela não deve digitar a senha ali. Um aplicativo que pede a senha do MakePro quebra essa regra e deve ser desativado.