Workshop API

Parte 2

Revisão de terça

  • 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?

Vamos descobrir na prática!

1

Como faz isso?

Quando um lead preencher o formulário do nosso site, quero que isso crie uma empresa/pessoa com nome, email, telefone e a origem "Site". Também precisa gerar um novo negócio na 1a etapa para um vendedor aleatório

#comofaz

1. POST https://api.agendor.com.br/v3/organizations
{
  "name": "Acme (Nome da Empresa)",
  "ownerUser": 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)

{
  "name": "William 2 (Nome da Pessoa)",
  "leadOrigin": 9,
  "userOwner": 70,
  "category": 16,
  "organization": 14166719,
  "contact": {
  	"email": "lead@example.com",
  	"work": "(11) 98877-4455"
  }
}
2. POST https://api.agendor.com.br/v3/people

Como saber o id do usuário e da origem?

GET https://api.agendor.com.br/v3/users
GET https://api.agendor.com.br/v3/lead_origins

Dica: Dá pra duplicar abas no Postman clicando com o botão direito na aba > Duplicate Tab

Assim, a nova aba já terá os headers Authorization e Content-Type

3. POST https://api.agendor.com.br/v3/people/{ID}/deals
{
  "title": "Consultoria Enterprise",
  "userOwner": 70,
  "dealStage": 1
}

2

Quando um lead preencher o formulário do nosso site, quero que isso crie uma pessoa com nome, email, telefone e uma tarefa do tipo ligação para o vendedor responsável desse lead

Ah, tem lead que preenche o formulário mais de uma vez. Eles não podem ser duplicados no Agendor, ok?

Buscar pessoa por e-mail antes de inserir

{
    "data": [
        {
            "id": 14324757,
            "name": "William (Nome da Pessoa)",
            "organization": {
                "id": 8954650,
                "name": "Acme (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T10:07:36.000Z",
            "updatedAt": "2018-06-15T09:08:28.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": "(11) 3232-8080",
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": "+55 11 98888-7777",
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 70,
                "name": "Tulio"
            },
            "ownerUser": {
                "id": 39970,
                "name": "T"
            }
        },
        {
            "id": 14328403,
            "name": "William (Nome da Pessoa)",
            "organization": {
                "id": 8954650,
                "name": "Acme (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T14:38:28.000Z",
            "updatedAt": "2018-05-18T20:41:30.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 70,
                "name": "Tulio"
            },
            "ownerUser": {
                "id": 39970,
                "name": "T"
            }
        },
        {
            "id": 14329441,
            "name": "Rafael (Nome da Pessoa)",
            "organization": {
                "id": 8959072,
                "name": "R Sports (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:28:20.000Z",
            "updatedAt": "2018-06-11T19:42:47.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 39970,
                "name": "T"
            },
            "ownerUser": {
                "id": 70,
                "name": "Tulio"
            }
        },
        {
            "id": 14329470,
            "name": "Rafael (Nome da Pessoa)",
            "organization": {
                "id": 8959072,
                "name": "R Sports (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:31:16.000Z",
            "updatedAt": "2018-06-11T19:42:47.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 39970,
                "name": "T"
            },
            "ownerUser": {
                "id": 70,
                "name": "Tulio"
            }
        },
        {
            "id": 14329504,
            "name": "Rafael (Nome da Pessoa)",
            "organization": {
                "id": 8959072,
                "name": "R Sports (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:35:38.000Z",
            "updatedAt": "2018-06-11T19:42:47.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 39970,
                "name": "T"
            },
            "ownerUser": {
                "id": 70,
                "name": "Tulio"
            }
        },
        {
            "id": 14329507,
            "name": "Rafael (Nome da Pessoa)",
            "organization": {
                "id": 8959072,
                "name": "R Sports (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:36:02.000Z",
            "updatedAt": "2018-06-11T19:42:47.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 39970,
                "name": "T"
            },
            "ownerUser": {
                "id": 70,
                "name": "Tulio"
            }
        },
        {
            "id": 14329517,
            "name": "Rafael (Nome da Pessoa)",
            "organization": {
                "id": 8959072,
                "name": "R Sports (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:36:24.000Z",
            "updatedAt": "2018-06-11T19:42:47.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 39970,
                "name": "T"
            },
            "ownerUser": {
                "id": 70,
                "name": "Tulio"
            }
        },
        {
            "id": 14329520,
            "name": "Rafael (Nome da Pessoa)",
            "organization": {
                "id": 8959072,
                "name": "R Sports (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:36:44.000Z",
            "updatedAt": "2018-06-11T19:42:47.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 39970,
                "name": "T"
            },
            "ownerUser": {
                "id": 70,
                "name": "Tulio"
            }
        },
        {
            "id": 14329524,
            "name": "William (Nome da Pessoa)",
            "organization": {
                "id": 8954650,
                "name": "Acme (Nome da Empresa)"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2017-07-06T16:37:03.000Z",
            "updatedAt": "2018-05-18T20:41:30.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": "(11) 98877-4455",
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": null,
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": {
                "id": 9,
                "name": "Site"
            },
            "author": {
                "id": 70,
                "name": "Tulio"
            },
            "ownerUser": {
                "id": 39970,
                "name": "T"
            }
        },
        {
            "id": 19752017,
            "name": "William 2 (Nome da Pessoa)",
            "organization": {
                "id": 14166719,
                "name": "Teste API"
            },
            "cpf": null,
            "role": null,
            "ranking": 0,
            "description": null,
            "birthday": null,
            "avatar": null,
            "createdAt": "2018-06-17T12:49:14.000Z",
            "updatedAt": "2018-06-17T12:49:14.000Z",
            "products": [],
            "contact": {
                "email": "lead@example.com",
                "work": null,
                "mobile": null,
                "fax": null,
                "ramal": null,
                "radio": null,
                "whatsapp": null,
                "facebook": null,
                "twitter": null,
                "linkedIn": null,
                "skype": null,
                "instagram": null
            },
            "address": {
                "country": "Brasil",
                "district": null,
                "streetName": null,
                "streetNumber": null,
                "additionalInfo": null,
                "postalCode": null,
                "state": null,
                "city": null
            },
            "category": null,
            "leadOrigin": null,
            "author": {
                "id": 70,
                "name": "Tulio"
            },
            "ownerUser": null
        }
    ],
    "meta": {
        "totalCount": 13
    },
    "links": {
        "self": "https://api.agendor.com.br/v3/people?email=lead%40example.com",
        "next": "https://api.agendor.com.br/v3/people?email=lead%40example.com&page=2"
    }
}
1. GET https://api.agendor.com.br/v3/people?email=lead@example.com

Exemplo de resposta:

{
  "text": "Ligar para o lead \n(tarefa criada via integração do site com o Agendor)",
  "due_date": "2020-01-19T12:00:00Z",
  "user": "70",
  "type": "LIGACAO"
}
2. POST
https://api.agendor.com.br/v3/people/14324757/tasks

Inserir tarefa para a pessoa que já existe

Crie empresas e pessoas via API e sem precisar buscar antes

Então sempre tem que buscar pela pessoa antes de inserir pra evitar duplicidade?

Seus problemas acabaram!

Conheça as rotas /upsert!

Eu agarantio!

POST https://api.agendor.com.br/v3/organization/upsert
POST https://api.agendor.com.br/v3/people/upsert

Busca se existe uma pessoa com o e-mail passado.
Se existir, atualiza ela. Se não existir, cria uma nova.

Busca se existe uma empresa com o cnpj ou nome passado.
Se existir, atualiza ela. Se não existir, cria uma nova.

Então, para inserir empresas e pessoas via API, sempre recomendar a rota /upsert para evitar duplicidade

Utilize a rota /people/upsert enviando o mesmo e-mail de uma pessoa que já existe mas passando outro nome

Vamos testar?

{
  "name": "Bob Esponja Calça Quadrada",
  "contact": {
    "email": "bob@siricascudo.com",
    "work": "(11) 98877-4455"
  }
}

Exemplo:

3

Quero que a empresa ou pessoa seja cadastrada no meu ERP, toda vez que um negócio for ganho

#comofaz

Assim como o sistema dos nossos clientes podem fazer requisições para a API do Agendor, os Webhooks são uma forma da API do Agendor fazer requisições ao sistema dos clientes.

Webhooks!

API do Agendor

Sistema do cliente

API do cliente

API do Agendor

Requisição

Requisição

O que aprendemos até agora:

Webhooks:

Postman
(para testes)

???
(Como testar?)

Como testar?

Copie essa URL

  1. Importem a biblioteca de exemplos do Postman usando o FAQ do Agendor: O Agendor pode ser integrado ao meu sistema atual?
  2. Crie um webhook para o evento de negócio ganho usando a rota do RequestBin para receber as requisições.
  3. Marque um negócio como ganho no Agendor e atualize o RequestBin para ver o que foi enviado pela API do Agendor

Hora de testar os Webhooks

E se a gente tivesse uma biblioteca no Postman já com todos os exemplos de uso da API?

Nós temos!

Empresas

Possibilidades da API

Negócios

Pessoas

Tarefas

Buscar (GET)

Criar (POST)

Editar (PUT)

Excluir (DELETE)

X

Produtos

Origens

Usuários

Categorias

Buscar (GET)

Criar (POST)

X

Buscar (GET)

Métricas

Funis

etc (ver docs)

O que mudou da V1 pra V3?

Principais problemas da V1

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

Tudo isso foi resolvido na V3

Frequent Asked Questions

1. Porque foi da V1 pra V3? Onde está a V2?

A V2 é usada pelo sistema web em alguns lugares (ex: atividades). A ideia era tornar a V2 pública mais vimos que tinha muitos pontos a melhorar na arquitetura dela e criamos uma V3 (mas que reutilizou muito código da V2).

 

2. Os programadores precisam usar o Postman?

Não, mas a vida deles será mais fácil se eles usarem. As nossas bibliotecas para Postman são praticamente uma documentação mais completa.

Eles até podem testar diretamente pelo código ou usar outras ferramentas, mas o Postman vai ajudá-los a ganhar tempo.

3. O Agendor integra com ERP?

Sim. Usando Webhooks e as rotas de criação (ex: /organizations/upsert).

4. Cliente: "Quero que todo negócio que não for ganho em 30 dias, seja perdido automaticamente. É possível? Como?" 

Sim, criando webhooks com os eventos de negócios criados e de negócios ganhos.

Dúvidas?

Acabou!

"Obrigado, de nada e parabéns pra vocês!"

Workshop API V3 pt. 2 (2020)

By Tulio Monte Azul

Made with Slides.com

Workshop API V3 pt. 2 (2020)

  • 321

More from Tulio Monte Azul