API do powercash

api_doc.md

API do powercash

A url básica para acesso a API é api.power.cash/, todas os requests para a api devem começar com este domínio e subdomínio.

Organização para testes

A organização teste existe com o intuito de facilitar os testes na API. Os dados de acesso para ela são:

• URL: http://teste.power.cash
• Username: teste
• Senha: password

Autenticação

Todos os requests para a API devem vir assinados com um token de um usuário. O token consiste de uma senha que pode ser utilizada para acessar os recursos, por isso não compartilhe ele com ninguém.

Você consegue gerar o seu token na página de configurações de um usuário, no botão Generate a new one no canto superior direito da página.

Para autenticar um request, você simplesmente colocar um parâmetro token com o valor do token no seu request.

Por exemplo, se você acessar a URL http://api.power.cash/users?token=teste-SFMyNTY.g3QAAAACZAAEZGF0YW0AAAABMWQABnNpZ25lZG4GAAZg2itZAQ.ZUcMBnfcIEzJse5xcyzya0NLawHG0cAjeKhA71sHXxE conseguirá ver a lista de usuários (se por acaso retornar a mensagem {"errors":["You need to login first"]}, é porque o seu token está inválido).

Restful

A API é totalmente REST, e utiliza os métodos HTTP da seguinte forma (substitua resources pelo nome do resource):

GET resources/ - visualização da lista de resources POST resources/ - criação de um resource PUT resources/1 - alteração do resource com o id 1 GET resources/1 - visualização do resource com o id 1 DELETE resources/1 - remoção do resource com o id 1

A seguir está a documentação dos resources que vocês pode criar, alterar, consultar e apagar via API.

Resources

A seguir está a lista de resources disponíveis atualmente na API:

• activities
• channels
• companies
• company_contacts
• contacts
• opportunity
• opportunity_items
• organizations
• pipelines
• pipeline_products
• products
• teams
• team_memberships
• users

Para cada um deles é possível executar as actions que foram listadas anteriormente.

Detalhes dos resources

Seguem agora os detalhes de cada um dos resources

contacts

Os campos de um contact são:

• *name: string
• *email: string
• owner_user_id: int
• phone: string
• role: string
• address: string
• address_street: string
• address_street_number: string
• address_sublocality: string
• address_locality: string
• address_state: string
• address_country: string
• address_postal_code: string

Exemplo de criação:

$.ajax({
  url: "http://api.power.cash/contacts", 
  method: "POST",
  dataType: "json", 
  data: {
    token: "teste-SFMyNTY.g3QAAAACZAAEZGF0YW0AAAABMWQABnNpZ25lZG4GAAZg2itZAQ.ZUcMBnfcIEzJse5xcyzya0NLawHG0cAjeKhA71sHXxE",
    contact: {
      name: "João José Maria",
      phone: "+55 41 98017-1980",
      email: "[email protected]"
    }
  }
})

opportunities

Os campos de uma opportunity são:

• *pipeline_id: int
• *title: string
• description: string
• current_stage_id: string
• manual_total: boolean
• total: decimal
• channel_id: int
• company_id: int
• contact_id: int
• owner_user_id: int

Exemplo de criação:

$.ajax({
  url: "http://api.power.cash/opportunities", 
  method: "POST",
  dataType: "json", 
  data: {
    token: "teste-SFMyNTY.g3QAAAACZAAEZGF0YW0AAAABMWQABnNpZ25lZG4GAAZg2itZAQ.ZUcMBnfcIEzJse5xcyzya0NLawHG0cAjeKhA71sHXxE",
    opportunity: {
      title: "Vender feijão para o João",
      pipeline_id: 1
    }
  }
})

Além dos campos das opportunities, é possível enviar o contact da opportunity e a lista de opportunity_items nos requests de criação e atualização. Da seguinte forma:

$.ajax({
  url: "http://api.power.cash/opportunities", 
  method: "POST",
  dataType: "json", 
  data: {
    token: "teste-SFMyNTY.g3QAAAACZAAEZGF0YW0AAAABMWQABnNpZ25lZG4GAAZg2itZAQ.ZUcMBnfcIEzJse5xcyzya0NLawHG0cAjeKhA71sHXxE",
    opportunity: {
      title: "Vender feijão para o João",
      pipeline_id: 1,
      contact: {
        name: "João José Maria",
        phone: "+55 41 98017-1980",
        email: "[email protected]"
      },
      opportunity_items: [{
        product_id: 1,
        quantity: 5
      }]
    }
  }
})

Se a chave contact for informada, será verificado se já existe algum contato com aquele email, e a oportunidade será ligada a este contato, senão ele será criado.

No caso da chave opportunity_items, sempre serão criados os itens informados.

opportunity_items

Os campos de um opportunity_item são:

• *opportunity_id: int
• *product_id: int
• *quantity: int

Exemplo de criação:

$.ajax({
  url: "http://api.power.cash/opportunity_items", 
  method: "POST",
  dataType: "json", 
  data: {
    token: "teste-SFMyNTY.g3QAAAACZAAEZGF0YW0AAAABMWQABnNpZ25lZG4GAAZg2itZAQ.ZUcMBnfcIEzJse5xcyzya0NLawHG0cAjeKhA71sHXxE",
    opportunity_item: {
      opportunity_id: 1,
      product_id: 1,
      quantity: 10
    }
  }
})