Guia de integração do monday.com para programação da produção com SkyPlanner APS

O monday.com disponibiliza uma GraphQL API em POST https://api.monday.com/v2. São lançadas versões trimestralmente, e o cabeçalho API-Version permite fixar a versão a utilizar. As descontinuações são anunciadas com pelo menos seis meses de antecedência. (Gestão de versões da API)

Uma integração para programação da produção utiliza os seguintes objetos:

• Boards e groups, frequentemente usados para organizar etapas ou semanas.
• Items e subitems. Um item representa normalmente uma encomenda ou tarefa, e os subitems contêm as operações.
• Column values: Status, Date, Timeline, Numbers, People, Dependency, Time Tracking, Connect Boards e Mirror.
• Webhooks para eventos de alteração.

As leituras usam items_page dentro de um quadro ou grupo. Por predefinição, cada página contém 25 itens. A documentação indica que “the maximum is 500.” (este é o número máximo de itens por página). Para continuar a leitura, utilize next_items_page. Tenha em conta que “each cursor will expire 60 minutes after the first request.” (cada cursor expira após esse intervalo, contado a partir do primeiro pedido). Filtre com query_params para ler apenas as encomendas em aberto. (items_page)

As escritas usam create_item, create_subitem, change_column_value e change_multiple_column_values. Esta última operação atualiza várias colunas de um item numa única chamada, tal como é necessário para devolver a programação ao monday.com.

Para grandes volumes de dados, a versão 2026-07 da API e as posteriores disponibilizam ingest_items e backfill_items. Carrega-se um CSV para um URL pré-assinado e consulta-se periodicamente o estado do processamento. (Importação em massa)

Crie uma subscrição com create_webhook(board_id, url, event, config). Uma integração para programação da produção precisa dos seguintes eventos:

• create_item e create_subitem para novas encomendas e operações.
• change_column_value ou change_specific_column_value para alterações à data de entrega, à quantidade ou à prioridade.
• change_status_column_value para alterações de estado feitas pelos utilizadores.
• item_archived, item_deleted e item_moved_to_specific_group para encomendas canceladas ou concluídas.

O URL de receção tem de responder a um token de verificação quando o webhook é criado. Em caso de falha na entrega, aplica-se a regra “retry once a minute for 30 minutes,” (repetir a tentativa uma vez por minuto durante esse período); depois, as tentativas terminam. Por isso, a integração também faz uma leitura periódica para reconciliação com items_page e um filtro para os itens atualizados recentemente. (Webhooks)

No sentido inverso, o SkyPlanner envia webhooks quando o estado ou a programação mudam. O serviço de integração recebe-os e regista as novas datas no monday.com. Assim, a atualização dos dados no monday.com é desencadeada por eventos.

1. Carga inicial de dados mestre. Leia os produtos, os materiais e as encomendas em aberto com items_page. Crie os centros de trabalho, os turnos e as restrições no SkyPlanner, ou importe-os do Excel. Decida desde o início se as operações serão subitems ou ficarão num quadro ligado.

2. Sincronização de encomendas. Os webhooks do quadro de produção enviam os itens novos e alterados para o SkyPlanner como encomendas. Se acompanhar as encomendas de compra num quadro, o SkyPlanner considera o material encomendado disponível na data de entrega e atualiza o stock quando a encomenda de compra é marcada como Entregue.

3. Escrita da programação no monday.com. Para cada encomenda que o motor tenha programado ou reprogramado, a integração chama change_multiple_column_values. Preenche a coluna Timeline com o início e o fim previstos e regista o centro de trabalho na respetiva coluna. Uma chamada por item mantém baixo o número de pedidos.

4. Progresso no chão de fábrica. Os operadores registam o trabalho com Mobile Confirmations, Production Timer ou Quick Log Mode. Os registos de tempo mantêm a programação atualizada, e a etiqueta Status correspondente é devolvida ao quadro. Assim, a equipa comercial acompanha o progresso sem ter de perguntar.

5. Responsabilidade pelos dados e regras de resolução de conflitos. Documente estas regras antes da entrada em produção:

A principal fonte de conflitos são as edições manuais da coluna Timeline. Estabeleça que só o SkyPlanner escreve nessa coluna, ou trate uma edição manual como um pedido e deixe o SkyPlanner reprogramar. O Autopilot reprograma automaticamente quando há alterações na produção.

• Cada conta organiza as encomendas de forma diferente. Um quadro por cliente, operações como itens ou subitems, máquinas em colunas People ou Status. Faça o mapeamento pelos IDs das colunas de cada conta, nunca pelo título da coluna.
• Limites dos planos. Os planos Free, Basic e Standard permitem 1.000 chamadas à API por dia, o Pro 10.000 e o Enterprise 25.000. Use webhooks para as alterações e atualize os dados no monday.com em lote com change_multiple_column_values. (limites de chamadas)
• As ligações entre quadros têm limites. O Basic permite uma ligação a um quadro e o Standard cinco, o que limita os quadros de operações ou produtos que podem ser ligados. (limites de Connect Boards)
• Fixe a versão da API. As versões mudam trimestralmente. Antes da versão 2026-04, os quadros multinível estavam excluídos da consulta predefinida de quadros.
• Expiração do cursor. Um cursor de items_page é válido durante 60 minutos. Os processos de reconciliação longos têm de poder reiniciar sem inconsistências.
• Limites dos webhooks. O URL pode ter, no máximo, 255 caracteres e as novas tentativas terminam ao fim de 30 minutos. O recetor tem de ser idempotente.
• Unidades e durações. As colunas Numbers não têm unidade. Antes da primeira importação, defina se as durações são expressas em minutos ou em horas.