O que é a API do Produttivo?
A API do Produttivo permite integrar a plataforma a outros sistemas, automatizando o envio e o recebimento de informações de forma segura.
Importante:
O acesso à API está disponível apenas para clientes que possuem o plano Automação.
Caso você não seja da área de tecnologia e queira conhecer as possibilidades de integração do Produttivo, consulte o artigo Integrações do Produttivo com outros sistemas.
Neste artigo, você aprenderá como:
Gerar a chave de acesso da API;
Autenticar suas requisições;
Realizar sua primeira requisição;
Entender a estrutura das requisições;
Utilizar a API pelo Postman ou Insomnia.
Gerar a chave de acesso da API
Para utilizar a API do Produttivo, é necessário realizar a autenticação por meio de um usuário do tipo Administrador. Você pode utilizar um usuário já existente ou criar um novo, desde que ele possua esse perfil de acesso.
Para gerar a chave de acesso:
Faça login no Produttivo com o usuário que será utilizado na integração.
Acesse Configurações > Integrações.
Você precisará das seguintes informações:
Authentication Token
Device Token
Login (e-mail do usuário)
Esses dados serão utilizados nas chamadas da API por meio dos seguintes headers:
X-Auth-LoginX-Auth-TokenX-Auth-Register
Todas essas informações estão descritas na documentação da API.
Realizar sua primeira requisição
Após obter a chave de acesso, acesse a Referência da API para realizar suas primeiras requisições.
O primeiro passo é autenticar sua sessão utilizando as credenciais obtidas anteriormente.
Autenticar na documentação da API
Na documentação da API, clique no botão Authorize, localizado no canto superior direito da tela.
Será exibida uma janela com três campos para autenticação.
Preencha cada campo da seguinte forma:
Campo | Informação |
AuthLogin | E-mail de login |
AuthRegister | Device Token |
AuthToken | Authentication Token |
Após preencher todos os campos, clique em Authorize.
Importante:
Não atualize a página (F5) após realizar a autenticação. Caso isso aconteça, será necessário informar novamente as credenciais.
Executar a primeira requisição
Com a autenticação concluída:
Acesse a seção Works (Atividades).
Clique em List Works.
Selecione Try it out.
Clique em Execute.
Se a requisição for executada com sucesso, a API retornará o código 200.
Nesse caso, as atividades da primeira página da conta serão exibidas na seção Response Body.
Como estruturar as requisições da API
Depois de realizar sua primeira requisição, é importante entender como as chamadas da API são estruturadas. Nesta seção, você conhecerá a documentação da API, os principais endpoints, os headers obrigatórios, os parâmetros de listagem e como interpretar as respostas retornadas.
Referência da API
O Produttivo disponibiliza duas versões da documentação da API.
A documentação antiga continua disponível para consulta, enquanto a nova versão está sendo atualizada e conta com exemplos de parâmetros e body para cada endpoint, além de permitir testar as requisições diretamente pelo navegador.
Você pode acessá-las nos links abaixo:
URL e endpoints da API
Todas as requisições utilizam como base o seguinte endpoint:
https://app.produttivo.com.br/
O que muda entre as requisições é apenas a entidade (endpoint) acessada.
Por exemplo, para consultar as atividades do Produttivo, utilize:
GET https://app.produttivo.com.br/works
Caso seja necessário utilizar filtros, basta adicioná-los à URL.
Exemplo:
GET https://app.produttivo.com.br/works?page=2&q=Exemplo
Headers obrigatórios
Todas as requisições HTTP devem conter os seguintes headers:
Header | Valor |
Content-type | application/json |
Accept | application/json |
X-Auth-Login | E-mail do usuário |
X-Auth-Register | Device Token |
X-Auth-Token | Authentication Token |
Utilize as informações obtidas durante a geração da chave de acesso para preencher os campos X-Auth-Login, X-Auth-Register e X-Auth-Token.
Caso ainda não tenha gerado essas credenciais, consulte o tópico Gerar a chave de acesso da API no início deste artigo.
Exemplo de requisição utilizando cURL
Abaixo está um exemplo de requisição utilizando cURL.
curl -X GET "https://app.produttivo.com.br/works?page=2&q=Exemplo" -H "accept: application/json" -H "X-Auth-Login: email@exemplo.com" -H "X-Auth-Register: DeviceTokenExemplo" -H "X-Auth-Token: AuthenticationTokenExemplo"
Principais endpoints
Os endpoints abaixo estão entre os mais utilizados durante as integrações com a API do Produttivo.
Endpoint | Descrição |
| Atividades realizadas no Produttivo, vinculando formulário, responsável e execução. |
| Modelos de formulários cadastrados. |
| Preenchimentos dos formulários realizados nas atividades. |
| Clientes, locais e ativos cadastrados. |
| Cadastro de serviços. |
| Cadastro de peças. |
| Exportação de relatórios. |
| Membros da conta. |
| Fotos e arquivos anexados. |
Listagem: filtros e paginação
As requisições do tipo GET permitem utilizar parâmetros para refinar os resultados.
Os principais são:
Parâmetro | Descrição |
| Realiza pesquisas por texto. |
| Filtra registros atualizados após a data informada. |
| Define a página de resultados. |
| Define a ordenação ( |
Outros parâmetros podem ser consultados na Referência da API.
Como interpretar o Response Body
Quando uma requisição do tipo GET é executada com sucesso (código 200), o retorno da API é dividido em dois blocos principais:
Results
Meta
Results
O objeto results contém todos os dados retornados pela requisição.
Exemplo:
"results": [
{
"id": 2141832,
"work_number": 68,
"title": "Atividade teste 3",
"uuid": "549e5086-d58a-4191-9f1d-bf6a30e03823",
"work_type": "fill_form",
"form_id": 157555,
"start_time": null,
"end_time": null,
"status": "finished",
"account_id": 74109,
"project_id": null,
"repeat_periodicity": null,
"repeat_interval": null,
"repeat_weekdays": null,
"repeat_end_date": null,
"repeat_index": null,
"account_member_ids": [
128461
],
"details": "",
"resource_place_id": null,
"work_finish_option_id": null,
"source_field_value_id": null,
"fills_count": 0,
"fills_goal": null,
"created_at": "2022-04-13T10:40:35.000-03:00",
"updated_at": "2022-04-14T09:56:31.000-03:00",
"external_id": null,
"created_by_id": 96151,
"updated_by_id": 99735,
"updated_status_to_started_by_id": 99735,
"updated_status_to_finished_by_id": 99735,
"updated_status_to_reviewed_by_id": null,
"updated_status_to_reviewed_at": null,
"updated_status_to_canceled_by_id": null,
"updated_status_to_started_at": "2022-04-14T09:56:31.000-03:00",
"updated_status_to_finished_at": "2022-04-14T09:56:31.000-03:00",
"updated_status_to_canceled_at": null,
"device_updated_status_to_started_at": "2022-04-14T09:56:31.000-03:00",
"device_updated_status_to_finished_at": "2022-04-14T09:56:27.000-03:00",
"device_updated_status_to_canceled_at": null,
"requested_start_time": null
}
]
Meta
O objeto meta apresenta a quantidade de itens e informações sobre a paginação dos resultados.
Os principais campos são:
Campo | Descrição |
| Página atualmente exibida. |
| Quantidade total de registros encontrados. |
| Primeiro item exibido na página. |
| Último item exibido na página. |
| Número total de páginas disponíveis. |
Exemplo:
"meta": {
"current_page": 1,
"count": 105,
"from": 1,
"total_pages": 4,
"to": 30
}
}
Quando uma requisição retorna muitos registros, os resultados são divididos em páginas para melhorar o desempenho.
Caso o parâmetro page não seja informado, a API retornará, por padrão, os registros da primeira página.
Limite de requisições
O limite de utilização da API do Produttivo é de 600 requisições a cada 5 minutos.
Caso sua integração realize um número maior de chamadas nesse intervalo, será necessário aguardar a liberação de novas requisições antes de continuar a comunicação com a API.
Consumir a API pelo Postman ou Insomnia
O uso do Postman, Insomnia ou ferramentas semelhantes é opcional, mas recomendado para facilitar os testes e o desenvolvimento da integração com a API do Produttivo.
Na Referência da API, é possível exportar todas as requisições em um formato compatível com essas ferramentas, agilizando a configuração do ambiente de testes.
Importar a coleção da API
Para importar as requisições da documentação para o seu software (Postman, Insomnia ou outro compatível):
Acesse a Referência da API.
Localize o arquivo de exportação disponível no topo da página.
Salve o arquivo em seu computador.
Importe-o para o seu Workspace.
Configurar os headers das requisições
Após importar a coleção, configure os seguintes headers em todas as requisições:
Header | Valor |
Content-type | application/json |
Accept | application/json |
X-Auth-Login | E-mail de login (o mesmo utilizado no Swagger) |
X-Auth-Register | Device Token |
X-Auth-Token | Authentication Token |
Exemplo de configuração no Postman
Depois de importar a coleção da API, recomendamos criar um Environment para armazenar as credenciais utilizadas durante as requisições.
Crie variáveis para:
Login: e-mail utilizado no acesso;
Token: Authentication Token;
Register: Device Token;
URL (baseUrl):
https://app.produttivo.com.br
Essa configuração facilita a reutilização das credenciais em diferentes requisições.
Executar uma requisição no Postman
Após configurar o ambiente:
Abra a coleção importada.
Selecione uma requisição, como List Works.
Verifique se os headers estão preenchidos corretamente, utilizando as variáveis criadas anteriormente.
Os headers devem conter:
Header | Valor |
Content-type | application/json |
Accept | application/json |
X-Auth-Login | Variável de Login |
X-Auth-Register | Variável de Register |
X-Auth-Token | Variável de Token |
Exemplo Insomnia:
Exemplo Postman:
Caso algum parâmetro obrigatório não esteja presente, consulte a documentação da API e adicione-o manualmente.
Após concluir a configuração, clique em Send para executar a requisição.
Se tudo estiver configurado corretamente, a API retornará as informações de acordo com os filtros utilizados.
Precisa de ajuda?
Se tiver dúvidas durante a integração com a API do Produttivo, nossa equipe está à disposição para ajudar.
Basta clicar no botão laranja disponível no canto inferior da tela para falar com nosso time pelo chat 😉