Para garantir uma integração performática, estável e escalável, é importante seguir algumas boas práticas que evitam sobrecarga no servidor, erros como "Too Many Requests" (HTTP 429) e garantem o melhor desempenho na troca de dados.

Abaixo listamos as principais orientações recomendadas para desenvolvedores que desejam consumir a API da melhor forma possível:

Armazene os dados localmente após a primeira carga

• Evite fazer múltiplas requisições repetidas à API para buscar dados que já foram obtidos anteriormente.
• A recomendação é armazenar as informações do PipeRun localmente, utilizando uma base de dados como MySQL, PostgreSQL, MongoDB, Parquet ou outra de sua preferência. Assim você pode consultar essas informações localmente, reduzindo o volume de requisições e melhorando a performance da sua aplicação.

Evite requisições com múltiplos with encadeados

A funcionalidade with permite trazer múltiplos dados relacionados na mesma requisição, mas utilizar vários withs encadeados (ex: deals?with=companies,persons,customForms) vai impactar negativamente no desempenho da API e aumentar o tempo de resposta a tal ponto que sua requisição poderá ser abruptamente encerrada por exceder o tempo limite de processamento.

Recomendação:

• Prefira fazer requisições separadas para cada recurso relacional (companies, persons etc).
• Evite o uso de with sempre que possível ou mantenha apenas o with essencial.
• Relacione os dados localmente, no seu banco de dados ou aplicação, utilizando os IDs que a API retorna.

Exemplo de abordagem recomendada pra buscar informações de Empresa, Pessoa e Oportunidades:

• /v1/deals?with=customForms&cursor=
• /v1/companies?cursor=
• /v1/persons?cursor=

Use paginação com cursor, evitando o uso de número da página

Evite utilizar o parâmetro page=1 para fazer paginação, principalmente quando você precisa fazer a busca de uma quantidade razoável de informações.

Para maior estabilidade e performance, utilize paginação por cursor:

• Inicie a requisição com cursor= (vazio)
• A cada resposta, o campo meta.cursor.next fornecerá uma hash que aponta para a próxima página.
• Continue utilizando o valor retornado do next nas próximas requisições até que ele seja null indicando que chegou ao fim das paginas.

Ajuste o valor de show= para maximizar os dados retornados

O parâmetro show define o número de registros retornados por requisição, sendo 15 itens por padrão e podendo ir de 1 a ao valor máximo permitido de 200 itens.

Quando estiver buscando uma quantidade razoável de dados utilize show=200 para otimizar a quantidade de dados obtidos em cada chamada, reduzindo o número total de requisições necessárias. Mas fique atento, as vezes as requisições podem ficar lentas ao retornar 200 itens, então cuide para que as requisições não fiquem lentas demais. Cada endpoint e cada Conta de usuário pode ter um valor ideal de paginação para otimizar a velocidade da entrega, isso normalmente tem a ver com a quantidade de informações a conta possui e como esses dados se relacionam.

Exemplo:

• /v1/companies?show=200&cursor=

Use filtros de data updated_at_start ou created_at_start para atualizações incrementais

Após a carga inicial de dados, utilize os filtros updated_at_start ou created_at_start para trazer apenas os registros que sofreram alterações a partir de uma data e hora específica. Isso reduz significativamente o volume de dados trafegados e evita processamentos desnecessários.

Exemplos práticos:

Carga inicial (full import):

• Primeira request: /v1/companies?show=200&cursor=
• Próximas requests: /v1/companies?show=200&cursor={hash_da_proxima_pagina}

Atualização incremental (após uma data):

• Primeira request: /v1/companies?show=200&updated_at_start=2025-01-29 00:00:01&cursor=
• Próximas requests: /v1/companies?show=200&updated_at_start=2025-01-29 00:00:01&cursor={hash_da_proxima_pagina}

Resumo

Seguindo essas boas práticas, você:

• Reduz o número total de chamadas à API;
• Evita sobrecarregar o sistema (sua aplicação e o PipeRun);
• Aumenta a performance e estabilidade do seu processo de integração;
• Garante melhor escalabilidade para o futuro;
• Evita o bloqueio da sua integração por uso abusivo ou fora dos termos de uso;

❗️

Atenção

O uso inadequado da integração via API, que possa comprometer a estabilidade da plataforma, poderá resultar no bloqueio da integração, inclusive sem aviso prévio. Por isso, é fundamental seguir atentamente as instruções descritas nesta documentação para evitar a interrupção repentina do serviço.