O que é o coturno via marte
O coturno via marte é uma forma de processamento de turnos de trabalho que utiliza a plataforma Marte como middleware entre os sistemas de ponto eletrônico e o cadastro funcional das empresas. Na prática, os dados de entrada, saída e intervalos são enviados para a API do Marte, que normaliza as informações antes de repassar ao sistema de folha ou ao departamento de RH. A maioria das empresas que adota esse fluxo faz isso para evitar inconsistências causadas por diferentes modelos de relógio de ponto.
Como configurar o coturno via marte no dia a dia
O primeiro passo é ter acesso à documentação técnica da API do Marte para integração de turnos. A URL base costuma ser https://api.marte.com.br/v1/turnos, mas isso varia conforme o contrato da empresa com a provedora. Você precisará de um token de autenticação do tipo Bearer, gerado no painel administrativo do Marte, e esse token tem validade de 24 horas, então o sistema precisa renovar automaticamente. Dentro do seu sistema de ponto, mapeie os campos obrigatórios: matrícula do funcionário, data do registro, tipo de movimento (entrada, saída, intervalo), e o turno associado. O formato de envio é JSON, e a API exige que a data venha no padrão ISO 8601. Se enviar errado, o retorno é um erro 422 sem muita explicação, então vale validar localmente antes de enviar.
Um detalhe importante que muitos esquecem: a API do Marte retorna um ID de confirmação para cada registro aceito. Guarde esse ID. Eu perdi cerca de três dias rastreando um funcionário que tinha registros duplicados porque não estava salvando esses IDs no banco de dados local. Depois passei a fazer um SELECT comparando o hash dos registros enviados com os recebidos, e aí conseguir isolair o problema em cinco minutos.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Pegadinhas que ninguém conta
A maioria dos manuais não menciona que o Marte possui um limite de requisições de 100 calls por segundo por tenant. Se sua empresa tem mais de mil colaboradores marcando ponto simultaneamente no início e no final do expediente, você vai estourar esse limite facilmente. A solução é implementar um buffer em fila com retry exponencial. Um delays de 500ms entre batches já resolve na maioria dos casos. Outro ponto: a api trata turnos parciais de forma diferente dependendo do tipo de contrato do cliente. Turnos de meia noite, por exemplo, podem ser retornados com a datacalendar errada se o sistema de origem não considerar o fuso horário correto. Use sempre tzutc() ou equivalente, e nunca confie no fuso do servidor de aplicação.
Quando o coturno via marte não funciona bem
Se sua operação depende de integração em tempo real para calcular horas extras automaticamente, esse modelo não é ideal. O Marte processa os turnos de forma batch, com latência que varia entre 30 segundos e 5 minutos dependendo da fila. Para cálculos de folha no mesmo dia, o resultado pode sair atrasado. Nesse caso, vale considerar uma integração direta com o sistema de folha ou usar um conector que faça polling ao invés de push. Também há limitações nos campos customizados. Se sua empresa precisa enviar dados específicos como região de trabalho, equipamento utilizado ou motivo da alteração de turno, o campo meta da API suporta apenas até 4KB por registro. Projetos maiores precisam dividir os dados em múltiplas chamadas ou migrar para uma solução mais robusta.
Download e instalação do conector
O conector oficial do coturno via marte pode ser baixado diretamente do painel de integrações da plataforma Marte, na seção de desenvolvedores. O pacote inclui bibliotecas para Python 3.9+, Node.js 18+, e um SDK em Java para ambientes corporativos mais tradicionais. A instalação via pip é simples: pip install marte-turnos-sdk. Para Node, npm install @marte/turnos. O repositório oficial fica em https://github.com/marte-dev/turnos-sdk, e lá também estão os exemplos de código e o arquivo de schema OpenAPI. Antes de colocar em produção, execute o teste de sandbox com pelo menos dez registros variados. O ambiente de homologação do Marte é quase idêntico ao produção, mas alguns edge cases de turnos de virada de mês só aparecem lá. Eu recomendo rodar o teste numa sexta-feira à tarde, porque se algo quebrar, você tem o fim de semana para resolver antes do processamento de folha na segunda.
Manutenção e monitoramento
Configure alertas para falhas de autenticação e rate limit. Um webhook de notificação para a URL /hooks/falha-envio resolve boa parte do monitoramento. A logging de cada chamada deve incluir o status code retornado, o tempo de resposta e o payload exato enviado. Isso economiza horas de debugging quando um lote inteiro falha sem motivo aparente. O ciclo de atualização do SDK geralmente acontece a cada dois meses, com correções de bugs e ajustes de schema. Mantenha o pacote atualizado, porque versões desatualizadas frequentemente encontram problemas de compatibilidade com as mudanças de endpoint que a plataforma faz sem aviso prévio na documentação.
