API REST

A API REST permite que o seu próprio software leia e altere o que está na sua conta do Measure Map Online: projetos e as suas medições, pastas, o catálogo de produtos e, no Enterprise, os membros da sua organização. Responde em JSON. A referência completa, com todos os campos e exemplos, é a documentação da API; esta página é a visão geral.

Para abrir a documentação a partir da aplicação, vá a codeDeveloper > apiAPI REST e prima menu_bookVisualizar documentação.

URL base#

Todos os pedidos vão para:

https://api.measuremaponline.com/api/v2

Autenticação#

Envie a sua chave de API, tal como está, no cabeçalho Authorization de cada pedido. Crie a chave na página Developer: consulte chaves de API.

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

Cada pedido é verificado em função do acesso da chave (por exemplo, Projetos Ler), da sua subscrição e, num pedido enviado a partir de uma página web, das restrições de sites da chave. Guarde no seu servidor as chaves que podem alterar dados: consulte manter a sua chave segura.

Produção e testes#

Há um único URL base para os dois. É a chave que decide: uma chave de testes lê e escreve projetos, pastas e produtos de testes, que as chaves de produção nunca veem. Os membros são os mesmos nos dois, mas para iniciar sessão como um membro é preciso uma chave de produção. Os projetos de convidados criados com uma chave de testes nunca são faturados, e os projetos de testes não podem ser incorporados no seu site. Os tokens indicam o ambiente a que pertencem.

O que a API abrange#

Algumas coisas a saber:

• Uma chave chega aos projetos da sua própria conta e, no Enterprise, aos dos membros da organização.
• Eliminar um projeto ou uma pasta através da API é definitivo: nada vai para a Reciclagem. Uma pasta leva consigo as pastas e os projetos que contém e que pertencem à sua conta ou aos seus membros.
• Nas medições de um projeto, uma forma lista os seus produtos em productIds, por ordem; productId é o primeiro deles.
• /projects/{pid}/mmp devolve o mesmo ficheiro .mmp que a aplicação exporta. O seu esquema está publicado em github.com/blueblinkone/mmp-validator. Os elementos novos só são acrescentados como opcionais, por isso um leitor escrito para um ficheiro mais antigo continua a funcionar.
• No Open Guest, um projeto criado através da API com o nível de acesso Open Guest conta para a sua utilização e orçamento do Open Guest, como um iniciado a partir da sua ligação de convidado.
• No Open Guest, a secção person_pin_circleLigação de convidado tem o guia API Open Guest, com código para o seu servidor e a sua página: o seu servidor obtém um token de POST /auth/token com a sua chave de produção e envia o visitante para um projeto novo só dele, com os seus dados já preenchidos.
• Criar um membro com POST /users/new ocupa um lugar, tal como um convite, e dá-lhe a função predefinida da sua organização.
• Um token de POST /auth/{uid}/login abre a conta desse membro, por isso requer uma chave que possa alterar membros, nunca a chave das suas incorporações. Não é dado para um Administrador nem para um Gestor, nem com uma chave de testes.
• Os produtos nunca são eliminados através da API, só arquivados, e o preço de custo de um produto nunca é devolvido.
• As parcelas cadastrais não fazem parte da API.

Respostas e erros#

Um pedido bem-sucedido responde com o estado 200 e JSON (a exportação .mmp responde com XML). Um pedido falhado responde com um estado de erro e um corpo como:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

Experimentar a API na página Developer#

codeDeveloper > terminalExperimentar a API envia pedidos reais com a sua chave e mostra exatamente o que é devolvido.

1. Escolha Produção ou Testes.
2. Escolha um Endpoint, como "Listar todos os projetos" ou "Obter medições".
3. Preencha os seus parâmetros. Um projeto ou um produto escolhe-se pelo nome entre os que a chave pode ler; quando é preciso uma pessoa, a sua própria conta é preenchida por si.
4. Prima play_arrowEnviar pedido. O estado e a resposta aparecem por baixo.

Só são oferecidos pedidos de leitura, por isso experimentar não altera nada, e estes pedidos não contam para a sua utilização. Se a sua chave não tiver o acesso de que um endpoint precisa, a página avisa-o de que vai responder 403.

Webhooks#

Um webhook avisa o seu servidor quando algo acontece, tal como os e-mails de notificação o avisam a si. Os webhooks fazem parte dos planos Enterprise e Open Guest.

Configurar um webhook#

Em codeDeveloper > webhookWebhooks:

1. Escreva o seu URL do endpoint: um endereço https:// na internet. Os endereços em redes privadas são recusados, e isto volta a ser verificado antes de cada entrega.
2. Marque os Eventos que quer (consulte eventos). Um endpoint novo começa com os eventos que o seu plano envia, e pelo menos um tem de estar marcado.
3. Prima saveSalvar. Na primeira vez, a página mostra o seu Segredo de assinatura por inteiro. Copie-o nesse momento: depois disso só são mostrados os últimos caracteres.
4. Prima sendEnviar evento de teste e escolha um evento.

Um teste envia uma amostra desse evento, com valores inventados e "test": true nos seus data, para o endpoint guardado, mesmo quando o evento não está marcado ou o endpoint está desativado. Para parar todas as entregas, prima delete_outlineRemover: o endpoint e o seu segredo são eliminados.

Por baixo das definições, a Referência de webhooks tem o que precisa para escrever o lado que recebe: os cabeçalhos e o corpo, código que verifica a assinatura em Node.js, Python e PHP, e dados de exemplo para cada evento.

O que o seu servidor recebe#

Cada evento é um POST para o seu endpoint, com um corpo JSON:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id é único para cada evento, created é o momento em que aconteceu, em milissegundos desde 1 de janeiro de 1970 (UTC), e o que data contém depende do evento. O pedido tem também estes cabeçalhos:

• Responda com um estado 2xx no prazo de 8 segundos, antes de qualquer trabalho demorado. Qualquer outro estado, um redirecionamento ou um tempo esgotado conta como falha.
• Cada evento é enviado uma vez e nunca é repetido. A secção mostra o Último envio e as Falhas consecutivas.
• Depois de 10 falhas seguidas, o endpoint é desativado e o proprietário recebe um e-mail. Corrija o seu servidor e prima saveSalvar para o voltar a ativar.
• De vez em quando, um evento chega duas vezes ou fora de ordem. Use id para ignorar as repetições e created para pôr os eventos por ordem.

Verificar a assinatura#

Qualquer pessoa que conheça o seu endereço pode enviar-lhe pedidos, por isso verifique cada entrega antes de confiar nela:

1. Divida o cabeçalho X-MMO-Signature na vírgula, em t e v1.
2. Calcule um HMAC-SHA256 de t, um ponto final e o corpo do pedido em bruto, com o seu segredo de assinatura como chave, escrito em hexadecimal.
3. Compare o resultado com v1 usando uma comparação em tempo constante.
4. Rejeite a entrega se t estiver a mais de 5 minutos da hora atual. t está em milissegundos.

Use o corpo exatamente como chegou: analisar o JSON e voltar a escrevê-lo altera-o, e a assinatura deixa de corresponder.

autorenewRodar segredo substitui o segredo de imediato e mostra o novo por inteiro, uma vez. Atualize o seu servidor assim que o rodar.

Eventos#