Integração com Agendor via API

Revisão de ontem

  • URL
    • Rota (endpoints)
    • Parâmetros
  • Cabeçalhos (headers)
  • Corpo (body)

Requisição (request)

Resposta (response)

  • Cabeçalhos (headers)
    • Status code
  • Corpo (body)

API

API do Agendor

O que dá pra fazer?

Alguns exemplos do que é possível

1. Quando um lead preencher um formulário no site do cliente, criar uma empresa/pessoa com nome, email, telefone e a origem "Site". Depois, criar um negócio na 1a etapa para um vendedor aleatório como responsável

Como faz isso?

#comofaz

1. POST https://api.agendor.com.br/v1/organizations
{
  "nickname": "Acme (Nome da Empresa)",
  "userOwner": 39970
}

!

Lembre-se de definir o header:

Content-type

com o valor:

application/json

O status code da resposta indica onde o problema está

4xx

5xx

2xx

OK

Cliente enviou valores inválidos na requisição

Erro interno no servidor (provável bug na API)

3. POST https://api.agendor.com.br/v1/deals
{
  "title": "William - Interesse em Consultoria",
  "userOwner": 39970,
  "person": 14324758,
  "dealStageOrder": 1
}
{
  "name": "William (Nome da Pessoa)",
  "leadOrigin": 9,
  "userOwner": 39970,
  "organization": 8954650,
  "emails": ["lead@example.com"],
  "phones": [
    {
      "number": "(11) 98877-4455",
      "type": "mobile"
    }
  ]
}
2. POST https://api.agendor.com.br/v1/people

Como saber o id da origem?

Como não temos rotas /users ou /origins, é preciso descobrir os ids "inspecionando" o sistema

2. Quando um lead preencher um formulário no site do cliente, procurar se já existe uma pessoa com o email ou telefone informado. Depois, criar uma tarefa com a métrica ligação para o vendedor responsável ligar para esse lead

#comofaz

[
    {
        "personId": 14324757,
        "user": {
            "userId": 70,
            "name": "Tulio"
        },
        "leadOrigin": {
            "leadOriginId": 9,
            "name": "Site"
        },
        "organization": {
            "organizationId": 8954650,
            "nickname": "Acme (Nome da Empresa)"
        },
        "phones": [
            {
                "number": null,
                "type": "work"
            },
            {
                "number": "(11) 98877-4455",
                "type": "mobile"
            },
            {
                "number": null,
                "type": "fax"
            }
        ],
        "emails": [
            "lead@example.com"
        ],
        "social": {
            "facebook": null,
            "twitter": null,
            "skype": null,
            "msn": null,
            "linkedIn": null
        },
        "address": {},
        "userOwner": {
            "userId": 39970,
            "name": "T"
        },
        "name": "William (Nome da Pessoa)",
        "role": null,
        "createTime": "2017-07-06T10:07:36.000Z",
        "ranking": 0,
        "cpf": null,
        "description": null
    }
]
1. GET https://api.agendor.com.br/v1/people?q=lead@example.com
   GET https://api.agendor.com.br/v1/people?q=11988774455

OU

Exemplo de resposta:

{
  "text": "Ligar para o lead \n(tarefa criada via integração do site com o Agendor)",
  "assignedUsers": [39970],
  "person": 14324757,
  "dueDate": "2017-07-15T14:00:00.000Z",
  "metrics": [{
  	"metricId": 378532,
  	"value": 1
  }]
}
2. POST https://api.agendor.com.br/v1/tasks

Empresas

Ou seja..

Negócios

Pessoas

Tarefas

Buscar (GET)

Criar (POST)

Editar (PUT)

Excluir (PUT)

X

Mas..

Nem todos os campos estão disponíveis na API

!

Como assim?

Exemplo: É possível criar um negócio, mas não é possível definir um produto ou privacidade para ele

Comparativo

Empresas

  • Buscar apenas por nome fantasia (tem que ser o nome exato)
  • Inserir/Editar com os campos nome fantasia, usuário responsável, categoria, setor, telefones, email, endereço, cnpj, etc (ver documentação)
  • Excluir
  • Buscar por CNPJ, email, telefone, razão social, produto, categoria, etc
  • Inserir/Editar com os campos produto, privacidade e origem de cliente

Comparativo

Pessoas

  • Buscar por nome (pode ser só as iniciais), email, telefone
  • Inserir/Editar com os campos nome, usuário responsável, categoria, telefones, email, endereço, origem de cliente (campo leadOrigin não documentado), etc (ver documentação)
  • Excluir
  • Buscar por empresa, origem, categoria, produtos, etc
  • Inserir/Editar com os campos produto e privacidade, data de aniversário

Comparativo

  • Buscar por empresa, etapa, status
  • Inserir/Editar com os campos nome, usuário responsável, etapa, status, etc (ver documentação)
  • Excluir
  • Buscar por título, produtos, etc
  • Inserir/Editar com os campos produto, privacidade e motivo de perda

Negócios

Comparativo

  • Buscar por empresa, pessoa, negócio, data (criadas após)
  • Inserir/Editar com os campos texto, usuários responsáveis, empresa, negócio, métrica (campo metrics não documentado), etc (ver documentação)
  • Excluir
  • Buscar por usuário, pendente/finalizada, etc
  • A busca não retorna campos como métricas e usuários responsáveis
  • Inserir/Editar com os campos anexo

Tarefas

Em resumo

Principais problemas

  1. Não dá pra definir privacidade
  2. Não dá pra definir campos como motivo de perda, produtos, entre outros
  3. Não há rotas para buscar categorias, etapas, usuários, métricas, produtos, etc
  4. Não há como ser avisado que houve uma mudança no Agendor (ex: Empresa atualizada no Agendor > Atualizar no ERP)
  5. Não há como filtrar por data para verificar mudanças (ex: Empresa atualizada no Agendor > Atualizar no ERP)

Soluções

Já possui as rotas usuários, categorias, setores, métricas, produtos, etc

Já permite mais campos na inserção e atualização

Já tem privacidade

Evita re-trabalho

Permite integrar com centenas de apps

Ajuda a fazer Webhooks

(Negócio ganho > Enviar pro Slack)

Permite criar integrações "prontas" pros usuários

Frequent Asked Questions

1. Porque não usamos a V2?

A V2 é usada pelo sistema web. Se tornarmos ela pública e alguém fizer muitas requisições, o nosso sistema pode ficar lento.

Com a nova infra, ficou mais fácil resolver esse problema.

 

2. Porque não integramos com o Zapier/Pluga?

Iniciamos uma integração com eles para entender o que é possível ser feito e o esforço.

Não retomamos ainda por questões de prioridades.

3. Os programadores precisam usar o Postman?

Não, o Postman é apenas para facilitar o testes das rotas da API e entender como ela funciona.

Eles podem fazer isso diretamente pelo código ou usar outras ferramentas.

4. O Agendor integra com ERP?

Sim e não. É possível fazer uma integração, mas existem as limitações que comentamos. Por enquanto não há nenhuma feita no estilo da que fizemos com o RD. É bem provável que a integração com o Zapier/Pluga facilite integrar com algum ERP.

Dúvidas?

Obrigado!

Integração com Agendor via API

By Tulio Monte Azul

Made with Slides.com

Integração com Agendor via API

  • 107

More from Tulio Monte Azul