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
- Não dá pra definir privacidade
- Não dá pra definir campos como motivo de perda, produtos, entre outros
- Não há rotas para buscar categorias, etapas, usuários, métricas, produtos, etc
- Não há como ser avisado que houve uma mudança no Agendor (ex: Empresa atualizada no Agendor > Atualizar no ERP)
- 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!