Passar para o conteúdo principal
Todas as coleçõesIntegrações
Primeiros passos para integração via API
Primeiros passos para integração via API

Artigo com o descritivo técnico de como desenvolver a Integração via API

Yuri Takaes avatar
Escrito por Yuri Takaes
Atualizado há mais de 2 anos

Primeiros Passos

Esse artigo explica tecnicamente como são os primeiros passos para realizar uma integração com o Produttivo via API. Caso você não seja da área de tecnologia, sugerimos a leitura deste outro artigo.

O primeiro passo para iniciar o desenvolvimento da integração é solicitar seu acesso para o responsável pela conta do Produttivo. Em seguida, sugerimos que siga os passos abaixo descritos nesse artigo:

  1. Gerar a chave de acesso

  2. Como utilizar chave de acesso

  3. Realizar sua primeira requisição

  4. Como estruturar as requisições

  5. Consumir a API pelo Postman/Insomnia

Vamos lá?

Gerar a Chave de acesso da API

O acesso a API é realizado através de um usuário do tipo Administrador. Você pode utilizar um usuário existente na conta ou criar um novo, desde que seja do tipo administrador.

Realize o login no Produttivo com o usuário que será utilizado para a integração e acesse a tela de configurações:

Você irá precisar das seguintes informações: Authentication token, Device token. Essas são as informações que devem ser enviadas nas chamadas da API nos parâmetros X-Auth-Login, X-Auth-Token e X-Auth-Register que estão descritos em nossa documentação.

Realizar sua primeira Requisição

Após coletar as informações da Chave de Acesso, acesse a Referência da API clicando aqui para realizar suas primeiras requisições.

O primeiro passo é utilizar os dados Login, Authentication Token e Device Token para configurar sua autenticação. Para isso, clique no botão Authorize localizado no canto direito da tela:

Uma tela com três campos irá aparecer. Os campos devem ser preenchidos com as seguintes informações de Chave de Acesso:

  • AuthLogin: E-mail de Login

  • AuthRegister: Device Token

  • AuthToken: Authentication Token

Após o preenchimento de cada campo, é necessário clicar no botão “Authorize''.

OBS: Não dê refresh (F5) na página pois as informações de autenticação serão perdidas.

Agora faremos a primeira Request. Para isso, vá na aba Work (Atividades), clique em “List Works” depois clique em “Try it out” no canto direito e em “Execute” abaixo dos parâmetros.

Obtendo o código 200, as atividades da primeira página de sua conta irão aparecer em “Response Body”.

Como estruturar as requisições da API - Explicando URL, parâmetros da request (GET), Headers, Json Request (PUT, POST):

Referência da API

Está disponível para consulta a nossa documentação antiga da API. Ela está sendo migrada para sua nova versão que conta com exemplos de parâmetro e body de cada endpoint onde é possível testar as requisições por conta própria. Você pode acessá-la clicando aqui.

URL e Entidades

O Endpoint raiz para todas as chamadas é https://app.produttivo.com.br/, mudando apenas a entidade no final do url. Por exemplo, o endpoint para a entidade works (Atividades) é https://app.produttivo.com.br/works.

Se você deseja listar todas as atividades, basta realizar uma requisição do tipo GET no endpoint /works. Caso precise enviar algum parâmetro, você pode adicioná-los no url da seguinte forma: https://app.produttivo.com.br/works?page=2&q=Exemplo

Em todas as requests HTTP você precisará enviar os seguintes parâmetros no Header:

  • Content-type: application/json

  • Accept: application/json

  • X-Auth-Login: email@exemplo.com

  • X-Auth-Register: DeviceTokenExemplo

  • X-Auth-Token: AuthenticationTokenExemplo

Utilize a sua chave de acesso para preencher os valores de X-Auth-Login, X-Auth-Register e X-Auth-Token. Caso ainda não tenha uma chave de acesso, veja como gerar no tópico Gerar chave de acesso no início deste artigo.

Abaixo está um exemplo de uma requisição utilizando o 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"

As principais entidades e endpoints são:

  • /works: Atividade realizada no Produttivo, vinculando o formulário, quando e quem deve realizar

  • /forms: Modelo de formulário configurado na conta do Produttivo

  • /form_fills: Preenchimento do formulário para uma atividade

  • /resource_places: Cliente, local ou ativo cadastrado

  • /services: Cadastro de Serviços

  • /parts: Cadastro de Peças

  • /export_requests: Exportação de relatórios

  • /account_members: Membros da conta

  • /attachments: Fotos e arquivos

Listagem: filtros e paginação

Os principais parâmetros usados em uma request GET de lista são:

  • q: Realizar pesquisas por texto

  • updated_after: Filtrar por itens que foram atualizados após a data definida

  • page: Filtrar pelo número da página de resultados

  • order_type: Tipo de ordenação ('desc' ou não preencher para 'asc')

Outros parâmetros podem ser encontrados na Referência da API.

GET: Explicando response body (Results e Meta)

Ao realizar uma requisição do tipo GET de lista e obter código 200, o conteúdo do response body estará separado entre dois itens:

  • Results: Todo o conteúdo resposta da request

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: Mostra a quantidade de itens e informações da paginação. São eles:

    • current_page: Informa o número da página que está sendo exibida (Ex: 2)

    • count: Número total de itens (Ex: 100)

    • from: Número do primeiro item exibido na página (31)

    • total_pages: Número total de páginas (Ex: 4)

    • to: Número do último item exibido na página (Ex: 60)

Exemplo:

"meta": {
    "current_page": 1,
    "count": 105,
    "from": 1,
    "total_pages": 4,
    "to": 30
  }
}

Caso a resposta da sua request possua muitos itens, ela será separada por páginas para maior desempenho. Sendo assim, é possível utilizar o parâmetro page citado acima para escolher e trazer as informações da página de sua escolha. Se o parâmetro page não for informado na request, por padrão serão apresentados todos os itens da primeira página.

Limite de requisições: O limite de requisições do Produttivo é de 600 a cada 5 minutos.

Consumir a API pelo Postman/Insomnia

Esse é um passo opcional, mas que sugerimos para facilitar a sua análise e testes para desenvolver a integração com o Produttivo. Em nossa Referência da API você pode facilmente exportar as requisições em um padrão compatível com ferramentas como Postman e Insomnia. Veja como fazer isso e configurar essas ferramentas nos tópicos abaixo.

Importação e configuração das Requests:

Para importar as Requests vistas no Swagger em seu software (Postman, Insomnia e etc), basta salvar o seguinte arquivo que se encontra no topo da página e utilizá-lo para importar tudo em seu Workspace:

Após realizar a importação será necessário configurar o “Header” de todas as Requests da seguinte forma:

  • Content-type: application/json

  • Accept: application/json

  • X-Auth-Login: email@exemplo.com (E-mail de Login - o mesmo usado no Swagger)

  • X-Auth-Register: DeviceTokenExemplo (Mesmo Register usado no Swagger)

  • X-Auth-Token: AuthenticationTokenExemplo (Mesmo Token usado no Swagger)

Exemplo de requisições pelo Postman

Abra seu software de utilização da API (Postman, Insomnia, etc.) e crie um novo Workspace do Produttivo. Após isso, vá em Environment e crie variáveis para Login, Token, Register e Url (Nomes das variáveis são de sua escolha pessoal).

Login: E-mail

Token: Authentication token

Register: Device Token

URL (baseUrl): https://app.produttivo.com.br

Navegue até a documentação da api importada pro software, selecione a sua primeira request (exemplo: List Works). No Header será necessário colocar as seguintes informações com seus respectivos valores:

  • Content-type: application/json

  • Accept: application/json

  • X-Auth-Login: X-Auth-Login (variável de login criada anteriormente)

  • X-Auth-Register: X-Auth-Register (variável de Register criada anteriormente)

  • X-Auth-Token: X-Auth-Token (variável de token criada anteriormente)
    ​

Exemplo Insomnia:

Exemplo Postman:

Ainda dentro da documentação da api em (List works), após a configuração dos headers, verifique se os parâmetros estão corretos conferindo na documentação da API. Caso esteja faltando algum campo necessário, você pode adicionar manualmente:

Após tudo configurado. clique em Send para consultar as informações desejadas com os filtros informados:

Respondeu à sua pergunta?