Essa é a documentação para a API REST da Linkseller CRM de Vendas https://www.linkseller.com.br/
Veja abaixo as instruções gerais sobre como usar a nossa API.
Para poder acessar qualquer rota em nossa API, é preciso passar no header (cabeçalho) o “access-token” com o token que é encontrado em sua conta no menu https://lscrm.com.br/api/
Exemplo:
curl --header "access-token: 00000000-1111-2222-3333-444444444444" 'https://api.lscrm.com.br/v1/opportunities'
Para retornar dados, é preciso fazer um GET na API. O GET pode ser feito de 2 maneiras:
GET “list”, ao chamar a rota, será retornado uma listagem com vários itens.
Exemplo: https://api.lscrm.com.br/v1/opportunities
Existem vários parâmetros que podem ser passado via query string, para maniputar os dados a serem retornados (veja abaixo).
GET “data”, ao passar o /ID, será retornado apenas o item desejado.
Aviso: Se for colocado uma barra após a rota(ex: /v1/opportunities/), será considerado como um GET data(e dará um erro por não ter passado o ID).
GET list – JSON
Ao fazer um GET list (para qualquer rota) o JSON retornado terá o seguinte padrão:
Response 200 (application/json)
{
"status_code": "200",
"returned": "get_list",
"get_list": {
"pagination": {
"total": "100",
"page": "1",
"limit": "10"
},
"itens": [
{
"id": "xx",
"campo1": "xxxxx",
"campo2": "xxxxx",
"user_id" : "1"
"users": {
"id": "1",
"name": "Nome do usuário"
}
}
],
"extra": {
"extra_value": []
}
}
}
Ao fazer um GET list de uma rota, existem diversos parametros, que podem ser usados para manipular o que será retornado, por exemplo, pode ser filtrado por um campo, ordenado ou limitar a quantidade de registros a retornar.
Obs: Em todas as referências a campo(s), ele deve ser passado da mesma forma que é retornado no “item”, ou seja em minusculo, e com o underline como separador(ex: user_id).
Parâmetros disponíveis:
Campos desejados – “fields”
Objetivo: Usado para limitar o que será retornado, passando os campo(s) desejado(s) que devem ser exibidos.
Padrão: Retorna todos os campos existentes.
Exemplo: https://api.lscrm.com.br/v1/opportunities?fields=title,user_id,client_id
Filtrar dados da rota – “filters”
Objetivo: Filtrar os resultados, por campo(s) desejado(s), passando o campo, um operador, e o valor desejado.
Padrão: Não é feito nenhum filtro.
Modo de uso: filters[CAMPO][OPERADOR]
Exemplo: https://api.lscrm.com.br/v1/opportunities?filters[user_id][equal]=1
Filtrar dados relacionados – “related_filters”
Objetivo: Permite filtrar dados de rotas relacionadas, já que em muitas rotas, será retornado dados de outras rotas (ex: users: { “name”: “xxx”})
Padrão: Não é feito nenhum filtro.
Modo de uso: related_filters[ROTA][CAMPO][OPERADOR]
Exemplo: https://api.lscrm.com.br/v1/opportunities?related_filters[users][name][equal]=Nome
Ordenar dados – “order”
Objetivo: Ordenar os itens por um campo desejado, passando o nome do campo e asc (ascendente) ou desc (descendente)
Padrão: Ordena ascendente(asc) pela chave primaria (normalmente o campo “id”).
Exemplo: https://api.lscrm.com.br/v1/opportunities?order[title]=asc
Quantidade de registros – “limit”
Objetivo: Limita a quantidade de registros a serem retornados, baseado no numero passado.
Padrão: o limite padrão é 10.
Paginação – “page”
Objetivo: Permite paginar os resultados, usado para “navegar” entre os registros existentes
Padrão: a página 1.
Para adicionar um registro em qualquer rota, basta fazer um POST para ela, com os campos listados na documentação de cada rota (que são os campos listados no GET).
Alguns pontos a serem considerados:
Todo POST deve ser passado no formato “x-www-form-urlencoded”
Os campos “added_in” e “updated_in” não precisam ser passados, pois serão adicionados automaticamente.
Se não for passado nenhum campo, será retornado: Response 400
{
"status_code": "400",
"returned": "error",
"error": {
"status": "400 - Bad Request",
"detail": "Não foi passado nenhum campo.",
"extra": "Nota: o POST deve ser feito em 'x-www-form-urlencoded'"
}
}
Caso haja algum campo obrigatório e ele não tenha sido passado será retornado: Response 400
{
"status_code": "400",
"returned": "error",
"error": {
"status": "400 - Bad Request",
"detail": "Não foi passado todos os campos obrigatórios (veja no item \"extra\" o que falta).",
"extra": {
"NOME_DO_CAMPO": "Título do campo"
}
}
}
Caso a rota não permita o cadastro de dados, será retornado: Response 405
{
"status_code": "405",
"returned": "error",
"error": {
"status": "405 - Method Not Allowed",
"detail": "Essa rota não aceita esse método.",
"extra": "Métodos aceito(s): XXXXX, XXXXXX"
}
}
Se o cadastro foi feito com sucesso será retornado: Response 201
{
"status_code": "201",
"returned": "post_data",
"post_data": {
... (os mesmo dados que um GET data )
}
}
Para editar um registro em qualquer rota, basta fazer um PUT para ela, passando o ID do registro e com os campos listados na documentação de cada rota (que são os campos listados no GET).
Alguns pontos a serem considerados:
Os dados do PUT devem ser enviados no formato “x-www-form-urlencoded”
O ID deve ser passado na URL após a rota: Exemplo: https://api.lscrm.com.br/v1/opportunities/152
Os campos “added_in” e “updated_in” não precisam ser passados, pois serão adicionados automaticamente.
Se não for passado nenhum campo, será retornado: Response 400
{
"status_code": "400",
"returned": "error",
"error": {
"status": "400 - Bad Request",
"detail": "Não foi passado nenhum campo.",
"extra": "Nota: o POST deve ser feito em 'x-www-form-urlencoded'"
}
}
Caso haja algum campo obrigatório e ele não tenha sido passado será retornado: Response 400
{
"status_code": "400",
"returned": "error",
"error": {
"status": "400 - Bad Request",
"detail": "Não foi passado todos os campos obrigatórios (veja no item \"extra\" o que falta).",
"extra": {
"NOME_DO_CAMPO": "Título do campo"
}
}
}
Caso a rota não permita esse método, será retornado: Response 405
{
"status_code": "405",
"returned": "error",
"error": {
"status": "405 - Method Not Allowed",
"detail": "Essa rota não aceita esse método.",
"extra": "Métodos aceito(s): XXXXX, XXXXXX"
}
}
Se o cadastro foi feito com sucesso será retornado: Response 201
{
"status_code": "200",
"returned": "put_data",
"put_data": {
... (os mesmo dados que um GET data )
}
}
O cadastro de Webhooks, é feito pelo painel do sistema, no menu Gerenciar > Integrações > Webhooks https://lscrm.com.br/webhooks/
Ao usar o recurso de Webhooks, por padrão será enviado os mesmos dados, exibidos na documentação de cada rota (Oportunidades, Organizações, Pessoas, etc).
Nessa documentação, basta clicar no item “Dados de uma …. (GET Data)” da rota desejada (abaixo), para analisar os dados que serão enviados.
Nota: Só existe a diferança que será enviado apenas o conteudo dentro de “get_data”.”item”.
Ou seja, não será enviado os campos “status_code” e “returned”.
Rota para os dados de oportunidades
(inteiro) id: ID da Oportunidade
(texto) entity_type: Oportunidade para – “organizations” ou “persons”
(inteiro) organization_id: ID da Organização
(inteiro) person_id: ID da Pessoa
(texto) title: Título da Oportunidade
(inteiro) user_id: ID do responsável
(inteiro) stage_id: ID da Etapa
(data) close_in: Data de fechamento
(decimal) value: Receita
(data hora) stage_last_change: (Não é exibido no sistema)
(texto) history: Notas
(data hora) added_in: Adicionado em
(data hora) updated_in: Atualizado em
(objeto) users: Dados do usuário
(objeto) stages: Dados da etapa
(objeto) organizations: Dados da Organização
(objeto) persons: Dados da Pessoa
(objeto) organizations_first_person: Dados da Pessoa da Organização
(objeto) additional_values: Dados dos campos adicionais
Retornar a listagem das oportunidades cadastradas.
Veja em “GET “list” – Parâmetros” como pode ser ordenado/filtrado os dados.
Nota: uma oportunidade pode ser para uma organização (client_id) ou para uma pessoa (contact_id), ou seja apenas 1 deles terá valor(o outro terá “0”).
Para adicionar uma oportunidade, basta fazer um POST, com os campos listados no GET (acima).
Campos obrigatórios: “organization_id ou person_id”, “title” e “stage_id”.
“added_in” e “updated_in” não é preciso passar, pois serão setados pela API
“close_in” se não for informado, será colocado 7 dias no futuro.
Responsável: se o “user_id” não for informado, será colocado o usuário que está acessando a API.
campos adicionais devem ser passados no formato “additional_values[ENTIDADE][CAMPO]=VALOR” , sendo que a ENTIDADE pode ser “opportunities”, “organizations”, “persons”
Para editar uma oportunidade, basta fazer um PUT, dos campos desejados.
Obs: A data de atualização será preenchida automaticamente
Rota para os dados de Organizações.
Retornar a listagem das organizações cadastradas.
Veja em “GET “list” – Parâmetros” como pode ser ordenado/filtrado os dados.
Nota: se a organização tiver pessoas, será retornado os dados delas.
Para adicionar uma Organização, basta fazer um POST, com os campos listados no GET (acima).
Campos obrigatórios: “name”.
“added_in” e “updated_in” não é preciso passar, pois serão setados pela API
Responsável: se o “user_id” não for informado, será colocado o usuário que está acessando a API.
Campos adicionais devem ser passados no formato “additional_values[CAMPO]=VALOR”
Caso queira é possivel já adicionar uma Pessoa e vincula-la com a Organização, para fazer isso basta enviar “first_person[CAMPO]=VALOR”
Rota para os dados de Pessoas.
Retornar a listagem das pessoas cadastradas.
Veja em “GET “list” – Parâmetros” como pode ser ordenado/filtrado os dados.
Para adicionar uma Pessoa, basta fazer um POST, com os campos listados no GET (acima).
Campos obrigatórios: “name”.
“added_in” e “updated_in” não é preciso passar, pois serão setados pela API
Responsável: se o “user_id” não for informado, será colocado o usuário que está acessando a API.
Campos adicionais devem ser passados no formato “additional_values[CAMPO]=VALOR”
Rota para os dados do Pré-vendas Leads.
(inteiro) id: ID da Oportunidade
(texto) situation: Situação
(inteiro) user_id: ID do responsável
(texto) company_name: Empresa
(texto) company_address: Endereço
(texto) phone: Telefone
(texto) person_name: Pessoa
(texto) company_document: CPF/CNPJ
(texto) history: Motivo
(texto) task_id: ID da Tarefa
(texto) opt_id: ID da Oportunidade
(data hora) scheduled_time: Reagendado para
(data hora) added_in: Adicionado em
(data hora) updated_in: Atualizado em
(objeto) users: Dados do usuário
(objeto) additional_values: Dados dos campos adicionais
Retornar a listagem dos leads do pré-vendas cadastradas.
Veja em “GET “list” – Parâmetros” como pode ser ordenado/filtrado os dados.
Nota: “task_id” ou “opt_id” será preenchido quando houver interesse no lead.
Para adicionar um lead no pré-vendas, basta fazer um POST, com os campos listados no GET.
Campos obrigatórios: nenhum campo é obrigatório!
“situation” se não for informado, será colocado “new” (Novo).
“added_in” e “updated_in” não é preciso passar, pois serão setados pela API
“task_id”, “opt_id” e “scheduled_time” não serão cadastrados no POST
“user_id” se não informado, será colocado 0 (sem responsável)
campos adicionais devem ser passados no formato “additional_values[CAMPO]=VALOR”
Rota para os usuários cadastrados
Rota para os dados de Etapas de Vendas
(inteiro) id: ID da Etapa
(inteiro) pipe_id: ID do Funil
(inteiro) order: Ordem
(texto) name: Nome da etapa
(texto) name_short: Nome abreviado da etapa
(texto) background: Cor de fundo da Etapa
(texto) type: Tipo de etapa
(texto) active: Etapa ativa ?
(data hora) added_in: Adicionado em
(data hora) updated_in: Atualizado em
(objeto) pipes: Dados do Funil
Retornar a listagem das etapas cadastradas.
Veja em “GET “list” – Parâmetros” como pode ser ordenado/filtrado os dados.
Rota para os campos adicionais da entidades
(inteiro) id: ID do Campo
(texto) name: Nome do campo
(texto) key: Chave do campo
(texto) type: Tipo do campo
(texto) options: Opções (se for o caso)
(texto) entity: Entidade (Pode ser para Oportunidades, Organizações ou Pessoas)
(data hora) added_in: Adicionado em
(data hora) updated_in: Atualizado em
Retornar a listagem dos campos adicionais cadastrados.
Veja em “GET “list” – Parâmetros” como pode ser ordenado/filtrado os dados.