Todas as coleções
Integraçõ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 uma semana

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?