Documentação da API

O Shifton Tarefas permite automatizar o trabalho com a plataforma e conectá-la a serviços externos por meio de uma API aberta. Pela API estão disponíveis todas as entidades essenciais — tarefas, clientes, funcionários, listas de verificação, inventário, áreas de serviço, documentos do módulo Documentos financeiros e relatórios —, por isso o Shifton pode ser integrado aos seus sistemas de RH, de folha de pagamento e de análise de dados, assim como aos serviços internos da empresa.

A documentação está publicada em duas versões:

🚀 Nova documentação — versão atual do manual, com estrutura atualizada e os métodos mais recentes: 👉 https://api2.shifton.com/openapi/
📄 Documentação antiga — versão anterior (ainda mantida para as integrações existentes): 👉 https://api2.shifton.com/docs/

As duas versões podem ser abertas diretamente do aplicativo — na seção Developer, na aba Visão geral, pelos botões “Nova documentação” e “Documentação antiga”.

A documentação está disponível em dois idiomas. No canto superior direito da página da nova documentação há um seletor EN / RU — o idioma escolhido é memorizado.

Como obter uma chave de API

A chave de API é criada no próprio aplicativo:

Abra a seção Developer.
Vá para a aba Chaves de API (“Chaves de API”).
Clique em “Criar chave de API”.

O que preencher ao criar a chave

Abre-se o painel lateral Criar chave de API com os campos:

Título — nome da chave, campo obrigatório. Nomeie conforme a finalidade, para depois ficar claro o que desativar: “Exportação para o ERP”, “Relatórios para análise”.
Expira às — data após a qual a chave deixa de funcionar. Se o campo ficar vazio, a validade é ilimitada.
Acesso — o alcance dos direitos da chave:
Full access (act as me) — a chave funciona em seu nome e com os seus direitos.
Permissões restritas — um conjunto limitado de permissões, que você mesmo escolhe.

Clique em Adicionar para criar a chave, ou em Cancelar para fechar o painel.

📷 *Captura do painel de criação da chave — capturar no ambiente de produção*

A chave é criada para uma empresa específica e funciona apenas com os dados dela. A chave pode ser revogada a qualquer momento — a revogação vale imediatamente, e todas as requisições posteriores com essa chave retornarão o erro 401.

Importante: a chave criada é exibida apenas uma vez. Copie-a de imediato e guarde-a em um lugar seguro — não é possível obtê-la novamente. Se a chave for perdida, crie uma nova e revogue a antiga.

Autorização

Todas as requisições à API são assinadas com a chave no cabeçalho:

Authorization: Bearer {your_API_key}

Endereço base da API:

https://api2.shifton.com/work/1.0.0

Uma requisição sem chave válida retorna 401 e o corpo {"message":"Unauthenticated."}.

Primeira requisição

Por exemplo, para obter a lista de funcionários da empresa (coloque o ID da sua empresa em vez de {companyId}):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

O mesmo por meio do curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

O ID da empresa aparece na barra de endereços do aplicativo: app.shifton.com/c/8397/... — o número depois de /c/.

O que está disponível pela API

O manual abrange mais de 360 métodos. Principais seções para o serviço em campo:

Tarefas — /companies/{companyId}/tasks: criação, alteração, status, arquivos das tarefas.
Lista de afazeres (To Do) — /companies/{companyId}/todo.
Clientes — /companies/{companyId}/clients, além dos endereços e dos campos personalizados dos clientes.
Listas de verificação — /companies/{companyId}/checklists.
Áreas de serviço — /companies/{companyId}/tasks/service-areas.
Habilidades — /companies/{companyId}/skills.
Funcionários — /companies/{companyId}/employees: adição, edição, dispensa e restauração.
Inventário — itens, categorias, conjuntos e saldos nos depósitos.
Documentos financeiros — orçamentos, ordens de serviço, faturas, recibos, contadores de documentos e logotipo.
Relatórios — exportação de dados de trabalho e de presença.

Além disso, estão disponíveis escalas e turnos, férias e solicitações de folga, presença, faturamento e faturamento de SMS, notificações e módulos.

Webhooks

Se, em vez de fazer requisições regulares à API, você precisar receber os eventos no momento em que eles ocorrem, use os webhooks — aba Webhooks na seção Developer. O próprio Shifton envia uma requisição para o seu endereço quando o evento desejado acontece; a lista de eventos suportados é devolvida por um método separado.

Códigos de erro

A API do Shifton usa os códigos de status HTTP padrão:

200 — requisição executada com sucesso.
201 — objeto criado com sucesso.
400 — parâmetros de requisição inválidos.
401 — erro de autorização: a chave não foi enviada, é inválida ou foi revogada.
403 — acesso negado.
404 — recurso não encontrado (na maioria das vezes, erro de digitação no endereço do método).
500 — erro do servidor.

Dicas de uso

Para novas integrações, use a nova documentação — a antiga foi mantida para as integrações que já funcionam.
Para testar as requisições são práticos o Postman ou o curl — eles permitem ver a resposta sem escrever uma linha de código.
Não guarde a chave em texto aberto no código e não a passe a terceiros: a chave dá acesso aos dados da empresa.
Respeite os limites de frequência de requisições (rate limits) — excedê-los pode levar a um bloqueio temporário do acesso à API.

Perguntas frequentes

Pergunta: Onde obter a chave de API? Resposta: No aplicativo: seção Developer → aba Chaves de API → botão “Criar chave de API”. A chave é emitida para a empresa atual.

Pergunta: Fechei a janela e não copiei a chave. Onde posso vê-la? Resposta: Em nenhum lugar — a chave é exibida apenas uma vez e não é fornecida novamente. Crie uma nova chave e revogue a antiga.

Pergunta: Como revogar a chave se ela cair em mãos erradas? Resposta: Exclua-a na aba Chaves de API. A revogação vale imediatamente: todas as requisições com essa chave passarão a retornar 401 de imediato.

Pergunta: Qual é a diferença entre “Full access” e “Restricted permissions”? Resposta: O Full access (act as me) dá à chave os mesmos direitos que você tem. As Permissões restritas permitem conceder à chave apenas o conjunto de permissões escolhido — o que é mais seguro para uma integração que precisa de acesso a apenas parte dos dados.

Pergunta: É possível limitar a validade da chave? Resposta: Sim, pelo campo Expira às na criação. Se ele não for preenchido, a chave será permanente.

Pergunta: Uma mesma chave funciona para várias empresas? Resposta: Não. A chave está vinculada à empresa na qual foi criada e funciona apenas com os dados dela. Para outra empresa, crie uma chave separada.

Pergunta: Qual é o endereço base da API? Resposta: https://api2.shifton.com/work/1.0.0. Depois vem o caminho do método, por exemplo /companies/{companyId}/tasks.

Pergunta: Onde obter o ID da empresa para as requisições? Resposta: Ele está na barra de endereços do aplicativo, logo depois de /c/ — por exemplo, em app.shifton.com/c/8397/tasks o identificador da empresa é 8397.

Pergunta: Qual versão da documentação usar? Resposta: Para novas integrações — a nova (api2.shifton.com/openapi). A antiga (api2.shifton.com/docs) é mantida para as integrações existentes.

Pergunta: Existe documentação em russo? Resposta: Sim. Na página da nova documentação, no canto superior direito, há o seletor EN / RU.

Pergunta: Com o que testar as requisições à API? Resposta: O mais prático são o Postman ou o curl — eles permitem enviar requisições e ver as respostas sem escrever código.

Pergunta: Por que recebo 401, mesmo tendo copiado a chave? Resposta: Verifique se a chave é enviada no cabeçalho Authorization com a palavra Bearer antes dela, se a chave não foi revogada e se a validade dela não expirou.

Pergunta: Por que recebo 404? Resposta: Na maioria das vezes o endereço está trocado: a parte base deve ser https://api2.shifton.com/work/1.0.0 e, no caminho do método, o {companyId} deve estar correto.

Pergunta: O que é possível automatizar pela API? Resposta: A criação e a alteração de tarefas, o trabalho com os clientes e os endereços deles, as listas de verificação, as áreas de serviço, as habilidades, os funcionários, o inventário, os documentos do módulo Documentos financeiros e a exportação de relatórios, assim como as escalas, os turnos e as férias.

Pergunta: É possível receber eventos do Shifton em vez de consultar a API? Resposta: Sim, para isso existem os webhooks — aba Webhooks na seção Developer.

Pergunta: A troca de senha afeta o funcionamento da integração? Resposta: Não. As integrações funcionam por chave de API, e não pela senha da conta.