Sobre a api de Integração com o getCRM
A integração com o getCRM utiliza o padrão de api Restful com JSON e UTF-8.
Você dever gerar o token (campo UserKeyId) no cadastro da empresa no getCRM e identificar o usuário de integração, conforme a imagem abaixo:
Esse token será utilizado em todos os endpoints conforme o exemplo abaixo:
Endpoint
https://api.getcrm.com.br/v1/064b46c45dba4d21b9073aa1d566233b/CriarConta
Utilizamos a versão Open Source do SoapUI (https://www.soapui.org/) para realizar os testes com nossa api.
Exemplo:
Versões
Versão 1.0.1
Publicada em 16/11/2018 às 22h.
- Incluído novo campo Origem em Contas.
Versão 1.0.0
Publicada em 01/08/2018 às 22h.
- Incluídos endpoints para incluir e alterar Contas, Consultar todas as Contas, Consultar Contas por código de Conta, Consultar Contas pelo campo Código Externo.
Criar Conta
Inclusão de uma Conta (pessoa física ou jurídica).
Se o campo CPF ou CNPJ for informado, será utilizado como chave. Caso contrário, será utilizado o campo email.
Se a Conta já existir (validada por CPF ou CNPJ ou email), a conta não será alterada e um erro será retornado.
Para alterar uma conta, utilize o endpoint AlterarConta.
Endpoint
https://api.getcrm.com.br/v1/{token}/CriarConta
Método
POST
Parâmetros
| Coluna | Descrição |
Tipo
|
Tamanho Máximo
|
| Parâmetros Obrigatórios | |||
| Email da Conta. | String |
100
|
|
| nome | Nome da Conta. | String |
200
|
| fantasia | Nome de Fantasia. | String |
100
|
| tipoconta | 0 - Ativo / 1 - Inativo / 2 - Prospect. | Inteiro |
1
|
| usuario | Email do usuário no getCRM determinado para essa Conta. | String |
100
|
| Parâmetros Opcionais | |||
| telefonecomercial | Número de telefone de contato. | String |
20
|
| telefonecelular | Número de telefone celular de contato. | String | 20 |
| nomecontato | Nome do contato. | String | 100 |
| cnpjcpf | CNPJ ou CPF (não formatado: sem barras ou pontos). | String | 14 |
| endereco | 1 ocorrência por registro. Endereço é um parâmetro opcional porém, se algum parâmetro for informado, é necessário preencher todos os parâmetros dentro de endereço. |
|
|
| logradouro | Logradouro (ex. Rua Manoel Justino; Av. São Leopoldo). | String | 100 |
| numero | Número do logradouro (ex. 123; s/n). | String | 10 |
| complemento | Complemento do número (ex. Apto 15; Quadra 7 Lote 2, ou enviar branco). | String | 20 |
| bairro | Nome do Bairro (não abreviar). | String | 100 |
| cidade | Nome da Cidade (não abreviar). | String | 100 |
| cep | CEP (não formato: sem barra). | String | 8 |
| uf | Sigla do estado (utilizar EX para países diferentes de Brasil). | String | 2 |
| pais | Nome do país em português (não abreviar). | String | 100 |
| codigoexterno | Campo livre normalmente utilizado para informar o código da conta no sistema de gestão. | String | 200 |
| origem | Origem da Conta | String |
200
|
| campo1 | Campo livre para utilizar como controle. | String | 2000 |
| campo2 | Campo livre para utilizar como controle. | String | 2000 |
| campo3 | Campo livre para utilizar como controle. | String | 2000 |
Retorno
| Coluna | Descrição | Tipo |
| resultado | Retorna o valor OK ou Erro. | String |
| codigo | Código da Conta. Pode retornar brancos quando ocorrer erro ou retornar o código da Conta na tentativa de incluir uma conta já existente. | String |
| erro | Detalhes do erro. Retorna um valor em branco quando OK. | String |
Exemplo JSON
{
"email": "jonassantos@getcrm.com.br",
"nome": "Jonas Santos",
"fantasia": "",
"tipoconta": 0,
"usuario": "edna@hjj2a.com.br",
"telefonecomercial": "0115555555",
"telefocelular": "01195555555",
"nomecontato": "Jonas",
"cnpjcpf": "09134508717",
"endereco": {
"logradouro": "Rua São Paulo",
"numero": "525",
"complemento": "Apto 154 A",
"bairro": "Centro",
"cidade": "São Paulo",
"cep": "04580780",
"uf": "SP",
"pais": "Brasil"
},
"codigoexterno": "ex1233",
"origem", "Indicação",
"campo1": "1",
"campo2": "2",
"campo3": "3"
}
Exemplo de Retorno JSON
{
"resultado": "OK",
"codigo": "453",
"erro": ""
}
Alterar Conta
Alteração de uma Conta (pessoa física ou jurídica).
Endpoint
https://api.getcrm.com.br/v1/{token}/AlterarConta/{codigoconta}
| Coluna | Descrição | Tipo |
| {codigoconta} | Código da Conta (número sequencial criado pelo getCRM). | Inteiro |
Método
POST
Parâmetros
| Coluna | Descrição |
Tipo
|
Tamanho Máximo
|
| Parâmetros Opcionais | |||
| Email da Conta. | String |
100
|
|
| nome | Nome da Conta. | String |
200
|
| fantasia | Nome de Fantasia. | String |
200
|
| tipoconta | 0 - Ativo / 1 - Inativo / 2 - Prospect. | Inteiro |
1
|
| usuario | Email do usuário no getCRM determinado para essa Conta. | String |
100
|
| telefonecomercial | Número de telefone de contato da Conta. | String |
20
|
| telefonecelular | Número de telefone celular do contato. | String | 20 |
| nomecontato | Nome do contato. | String | 100 |
| cnpjcpf | CNPJ ou CPF (não formatado: sem barras ou pontos). | String | 14 |
| endereco | 1 ocorrência por registro. Endereço é um parâmetro opcional porém, se algum parâmetro for informado, é necessário preencher todos os parâmetros dentro de endereço. |
|
|
| logradouro | Logradouro (ex. Rua Manoel Justino; Av. São Leopoldo). | String | 100 |
| numero | Número do logradouro (ex. 123; s/n). | String | 10 |
| complemento | Complemento do número (ex. Apto 15; Quadra 7 Lote 2, ou enviar branco). | String | 20 |
| bairro | Nome do Bairro (não abreviar). | String | 100 |
| cidade | Nome da Cidade (não abreviar). | String | 100 |
| cep | CEP (não formato: sem barra). | String | 8 |
| uf | Sigla do estado (utilizar EX para países diferentes de Brasil). | String | 2 |
| pais | Nome do país em português (não abreviar). | String | 100 |
| codigoexterno | Campo livre normalmente utilizado para informar o código da conta no sistema de gestão. | String | 200 |
| origem | Origem da Conta. | String |
200
|
| campo1 | Campo livre para utilizar como controle. | String | 2000 |
| campo2 | Campo livre para utilizar como controle. | String | 2000 |
| campo3 | Campo livre para utilizar como controle. | String | 2000 |
Retorno
| Coluna | Descrição | Tipo |
| resultado | Retorna o valor OK ou Erro. | String |
| erro | Detalhes do erro. Retorna um valor em branco quando OK. | String |
Exemplo JSON
{
"email": "jonassantos@getcrm.com.br",
"nome": "Jonas Santos",
"fantasia": "",
"tipoconta": 0,
"usuario": "edna@hjj2a.com.br",
"telefonecomercial": "0115555555",
"telefocelular": "01195555555",
"nomecontato": "Jonas",
"cnpjcpf": "09134508717",
"endereco": {
"logradouro": "Rua São Paulo",
"numero": "525",
"complemento": "Apto 154 A",
"bairro": "Centro",
"cidade": "São Paulo",
"cep": "04580780",
"uf": "SP",
"pais": "Brasil"
},
"codigoexterno": "ex1233",
"origem", "",
"campo1": "1",
"campo2": "2",
"campo3": "3"
}
Exemplo de Retorno JSON
{
"resultado": "OK",
"erro": ""
}
Consultar Contas
Consultar uma ou todas as contas.
Endpoint
https://api.getcrm.com.br/v1/{token}/ConsultarContas/{codigoconta}
| Coluna | Descrição | Tipo |
| {codigoconta} | Código da Conta (número sequencial criado pelo getCRM). Opcional, se não informado, retorna todas as Contas da Empresa. | Inteiro |
Método
GET
Retorno
| Coluna | Descrição |
Tipo
|
Tamanho Máximo
|
| retorno | Retorna o valor OK ou Erro. | String |
|
| erro | Detalhes do erro. Retorna um valor em branco quando OK. | String |
|
| contas | 1 ou mais ocorrências de Contas. |
|
|
| Email da Conta. | String |
100
|
|
| nome | Nome da Conta. | String |
200
|
| fantasia | Nome de Fantasia. | String |
100
|
| tipoconta | 0 - Ativo / 1 - Inativo / 2 - Prospect. | Inteiro |
1
|
| usuario | Email do usuário no getCRM determinado para essa Conta. | String |
100
|
| telefonecomercial | Número de telefone de contato da Conta. | String |
20
|
| telefonecelular | Número de telefone celular do contato. | String | 20 |
| nomecontato | Nome do contato. | String | 100 |
| cnpjcpf | CNPJ ou CPF (não formatado: sem barras ou pontos). | String | 14 |
| endereco | 1 ocorrência por registro. |
|
|
| logradouro | Logradouro (ex. Rua Manoel Justino; Av. São Leopoldo). | String | 100 |
| numero | Número do logradouro (ex. 123; s/n). | String | 10 |
| complemento | Complemento do número (ex. Apto 15; Quadra 7 Lote 2, ou enviar branco). | String | 20 |
| bairro | Nome do Bairro (não abreviar). | String | 100 |
| cidade | Nome da Cidade (não abreviar). | String | 100 |
| cep | CEP (não formato: sem barra). | String | 8 |
| uf | Sigla do estado (utilizar EX para países diferentes de Brasil). | String | 2 |
| pais | Nome do país em português (não abreviar). | String | 100 |
| codigoexterno | Campo livre normalmente utilizado para informar o código da conta no sistema de gestão. | String | 200 |
| origem | Origem da Conta. | String |
200
|
| campo1 | Campo livre para utilizar como controle. | String | 2000 |
| campo2 | Campo livre para utilizar como controle. | String | 2000 |
| campo3 | Campo livre para utilizar como controle. | String | 2000 |
Exemplo de Retorno JSON (OK)
{
"resultado": "OK",
"erro": "",
"contas":
[
{
"conta": 3,
"email": "joaomarques41@uol.com.br",
"nome": "JOÃO MARQUES",
"fantasia": "",
"tipoconta": 0,
"usuario": "administrador",
"telefonecomercial": "11-5555-5555",
"telefonecelular": "11-9999-9999",
"nomecontato": "João Marcos",
"cnpjcpf": "123.518.447-18",
"endereco": {
"logradouro": "Rua São José",
"numero": "44",
"complemento": "",
"bairro": "Centro",
"cidade": "São Caetano do Sul",
"cep": "09570120",
"uf": "SP",
"pais": "Brasil"
},
"codigoexterno": "",
"origem", "",
"campo1": "",
"campo2": "",
"campo3": ""
},
{
"conta": 4,
"email": "contato@ebx2.com.br",
"nome": "EB EMPREENDIMENTOS",
"fantasia": "",
"tipoconta": 0,
"usuario": "eb@getcrm.com.br",
"telefonecomercial": "11-5555-5556",
"telefonecelular": "11-9999-9998",
"nomecontato": "Maria",
"cnpjcpf": "39.682.357/0001-32",
"endereco": {
"logradouro": "",
"numero": "",
"complemento": "",
"bairro": "",
"cidade": "",
"cep": "",
"uf": "",
"pais": ""
},
"codigoexterno": "",
"origem", "",
"campo1": "",
"campo2": "",
"campo3": ""
},
{
"conta": 5,
"email": "joao@gh2.com.br",
"nome": "J & J CAIXA",
"fantasia": "",
"tipoconta": 0,
"usuario": "administrador",
"telefonecomercial": "11-5555-5557",
"telefonecelular": "11-9999-9997",
"nomecontato": "Marcelo",
"cnpjcpf": "11.488.787/0001-07",
"endereco": {
"logradouro": "",
"numero": "",
"complemento": "",
"bairro": "",
"cidade": "",
"cep": "",
"uf": "",
"pais": ""
},
"codigoexterno": "14A",
"origem", "",
"campo1": "",
"campo2": "",
"campo3": ""
}
]
}
Exemplo de Retorno JSON (Erro)
{
"resultado": "Erro",
"erro": "Token inválido !"
}
Consultar Conta pelo Código Externo
Consultar uma conta pelo campo Código Externo.
Endpoint
https://api.getcrm.com.br/v1/{token}/ConsultarContaCodigoExterno/{codigoexterno}
| Coluna | Descrição | Tipo |
| {codigoexterno} | Código Externo. | String |
Método
GET
Retorno
| Coluna | Descrição |
Tipo
|
Tamanho Máximo
|
| retorno | Retorna o valor OK ou Erro. | String |
|
| erro | Detalhes do erro. Retorna um valor em branco quando OK. | String |
|
| contas | 1 ou mais ocorrências de Contas. |
|
|
| Email da Conta. | String |
100
|
|
| nome | Nome da Conta. | String |
200
|
| fantasia | Nome de Fantasia. | String |
100
|
| tipoconta | 0 - Ativo / 1 - Inativo / 2 - Prospect. | Inteiro |
1
|
| usuario | Email do usuário no getCRM determinado para essa Conta. | String |
100
|
| telefonecomercial | Número de telefone de contato da Conta. | String |
20
|
| telefonecelular | Número de telefone celular do contato. | String | 20 |
| nomecontato | Nome do contato. | String | 100 |
| cnpjcpf | CNPJ ou CPF (não formatado: sem barras ou pontos). | String | 14 |
| endereco | 1 ocorrência por registro. |
|
|
| logradouro | Logradouro (ex. Rua Manoel Justino; Av. São Leopoldo). | String | 100 |
| numero | Número do logradouro (ex. 123; s/n). | String | 10 |
| complemento | Complemento do número (ex. Apto 15; Quadra 7 Lote 2, ou enviar branco). | String | 20 |
| bairro | Nome do Bairro (não abreviar). | String | 100 |
| cidade | Nome da Cidade (não abreviar). | String | 100 |
| cep | CEP (não formato: sem barra). | String | 8 |
| uf | Sigla do estado (utilizar EX para países diferentes de Brasil). | String | 2 |
| pais | Nome do país em português (não abreviar). | String | 100 |
| codigoexterno | Campo livre normalmente utilizado para informar o código da conta no sistema de gestão. | String | 200 |
| origem | Origem da Conta. | String |
200
|
| campo1 | Campo livre para utilizar como controle. | String | 2000 |
| campo2 | Campo livre para utilizar como controle. | String | 2000 |
| campo3 | Campo livre para utilizar como controle. | String | 2000 |
Exemplo de Retorno JSON (OK)
{
"resultado": "OK",
"erro": "",
"contas":
[
{
"conta": 3,
"email": "joaomarques41@uol.com.br",
"nome": "JOÃO MARQUES",
"fantasia": "",
"tipoconta": 0,
"usuario": "administrador",
"telefonecomercial": "11-5555-5555",
"telefonecelular": "11-9999-9999",
"nomecontato": "João Marcos",
"cnpjcpf": "123.518.447-18",
"endereco": {
"logradouro": "Rua São José",
"numero": "44",
"complemento": "",
"bairro": "Centro",
"cidade": "São Caetano do Sul",
"cep": "09570120",
"uf": "SP",
"pais": "Brasil"
},
"codigoexterno": "",
"origem", "",
"campo1": "",
"campo2": "",
"campo3": ""
},
{
"conta": 4,
"email": "contato@ebx2.com.br",
"nome": "EB EMPREENDIMENTOS",
"fantasia": "",
"tipoconta": 0,
"usuario": "eb@getcrm.com.br",
"telefonecomercial": "11-5555-5556",
"telefonecelular": "11-9999-9998",
"nomecontato": "Maria",
"cnpjcpf": "39.682.357/0001-32",
"endereco": {
"logradouro": "",
"numero": "",
"complemento": "",
"bairro": "",
"cidade": "",
"cep": "",
"uf": "",
"pais": ""
},
"codigoexterno": "",
"origem", "",
"campo1": "",
"campo2": "",
"campo3": ""
},
{
"conta": 5,
"email": "joao@gh2.com.br",
"nome": "J & J CAIXA",
"fantasia": "",
"tipoconta": 0,
"usuario": "administrador",
"telefonecomercial": "11-5555-5557",
"telefonecelular": "11-9999-9997",
"nomecontato": "Marcelo",
"cnpjcpf": "11.488.787/0001-07",
"endereco": {
"logradouro": "",
"numero": "",
"complemento": "",
"bairro": "",
"cidade": "",
"cep": "",
"uf": "",
"pais": ""
},
"codigoexterno": "14A",
"origem", "",
"campo1": "",
"campo2": "",
"campo3": ""
}
]
}
Exemplo de Retorno JSON (Erro)
{
"resultado": "Erro",
"erro": "Nenhum registro localizado !"
}
Mais informações ?
Entre em contato com nossa equipe de suporte via email: suporte@getcrm.com.br.