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
- Importem a biblioteca de exemplos do Postman usando o FAQ do Agendor: O Agendor pode ser integrado ao meu sistema atual?
- Crie um webhook para o evento de negócio ganho usando a rota do RequestBin para receber as requisições.
- 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
- Não dava pra definir privacidade
- Não dava pra definir campos como motivo de perda, produtos, entre outros
- Não havia rotas para buscar categorias, etapas, usuários, métricas, produtos, etc
- Não havia como ser avisado que houve uma mudança no Agendor (ex: Empresa atualizada no Agendor > Atualizar no ERP)
- 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!"
