Step by Step Guide to Building a Pipefy API Integration in Ruby

Introduction

Hey there, fellow developer! Ready to supercharge your workflow with Pipefy's API? In this guide, we'll walk through building a Ruby integration that'll have you managing pipes and cards like a pro. Let's dive in!

Prerequisites

Before we get our hands dirty, make sure you've got:

• A Ruby environment set up (2.7+ recommended)
• A Pipefy account with API access
• Your favorite code editor

Got all that? Great! Let's move on.

Setting up the project

First things first, let's create a new Ruby project and grab the gems we need:

mkdir pipefy_integration
cd pipefy_integration
bundle init

Now, add these lines to your Gemfile:

gem 'httparty'
gem 'dotenv'

Run bundle install, and we're off to the races!

Authentication

Pipefy uses token-based authentication. Create a .env file in your project root and add your API token:

PIPEFY_API_TOKEN=your_api_token_here

Now, let's set up our HTTP headers:

require 'httparty'
require 'dotenv/load'

headers = {
  'Authorization' => "Bearer #{ENV['PIPEFY_API_TOKEN']}",
  'Content-Type' => 'application/json'
}

Making API requests

Time to make our first API call! Let's fetch some organization data:

response = HTTParty.get('https://api.pipefy.com/graphql', 
  headers: headers,
  body: { query: '{ me { id name } }' }.to_json
)

puts response.parsed_response

If all goes well, you should see your Pipefy user info. Cool, right?

CRUD operations

Now for the fun part - let's create, read, update, and delete pipes!

Creating a pipe

query = <<~GRAPHQL
  mutation {
    createPipe(input: {
      name: "My Awesome Pipe",
      organization_id: 12345
    }) {
      pipe { id name }
    }
  }
GRAPHQL

response = HTTParty.post('https://api.pipefy.com/graphql', 
  headers: headers,
  body: { query: query }.to_json
)

puts response.parsed_response

Reading pipe data

query = <<~GRAPHQL
  {
    pipe(id: 12345) {
      name
      phases { name }
    }
  }
GRAPHQL

response = HTTParty.post('https://api.pipefy.com/graphql', 
  headers: headers,
  body: { query: query }.to_json
)

puts response.parsed_response

Updating and deleting follow a similar pattern. Easy peasy!

Working with cards

Cards are the heart of Pipefy. Let's create one and move it around:

Creating a card

query = <<~GRAPHQL
  mutation {
    createCard(input: {
      pipe_id: 12345,
      title: "New task",
      fields_attributes: [
        { field_id: "title", field_value: "Do the thing" }
      ]
    }) {
      card { id title }
    }
  }
GRAPHQL

response = HTTParty.post('https://api.pipefy.com/graphql', 
  headers: headers,
  body: { query: query }.to_json
)

puts response.parsed_response

Moving cards between phases

query = <<~GRAPHQL
  mutation {
    moveCardToPhase(input: {
      card_id: 67890,
      destination_phase_id: 54321
    }) {
      card { id title phase { name } }
    }
  }
GRAPHQL

response = HTTParty.post('https://api.pipefy.com/graphql', 
  headers: headers,
  body: { query: query }.to_json
)

puts response.parsed_response

Error handling and best practices

Always wrap your API calls in begin/rescue blocks to handle errors gracefully:

begin
  response = HTTParty.post('https://api.pipefy.com/graphql', 
    headers: headers,
    body: { query: query }.to_json
  )
  
  if response.success?
    puts response.parsed_response
  else
    puts "Error: #{response.code} - #{response.message}"
  end
rescue => e
  puts "An error occurred: #{e.message}"
end

And don't forget about rate limits! Pipefy has a limit of 30 requests per minute, so space out your calls if you're doing bulk operations.

Conclusion

And there you have it! You're now equipped to build awesome Pipefy integrations with Ruby. Remember, this is just scratching the surface - there's so much more you can do with webhooks, batch operations, and more.

Keep exploring, keep coding, and most importantly, keep automating those workflows! Happy coding!