API e webhooks

Como começar

1. No CRM, abra Administração > API e webhooks e crie uma chave (só leitura ou leitura e escrita). Ela aparece uma vez só: guarde num lugar seguro. No nosso banco fica só uma impressão digital dela.
2. Mande a chave no cabeçalho Authorization: Bearer gcp_... em toda chamada.
3. O endereço é o da sua empresa: https://suaempresa.crm.gocodesystems.com.br/api?r= + o recurso.

A chave age como a pessoa que a criou: vê só o que ela vê e só faz o que ela pode. Para uma integração da empresa toda, crie a chave com um usuário que veja tudo.

Limites

• Chamadas: as do plano por mês (o plano Empresa inclui 100.000) e até 120 por minuto por chave. Passou, a resposta é 429; o mensal volta no dia 1º.
• Contatos: a lista e a contagem da base são livres. Abrir a ficha (telefones, e-mail e sócios) e mandar para o funil contam 1 contato do plano no mês. A mesma empresa no mesmo mês conta uma vez. Acabou, a resposta é 402: compre um pacote extra em Assinatura.
• Toda chamada fica no registro de uso da sua empresa (Administração > API e webhooks), guardado por 90 dias.

Endereços

Funil e negócios

Empresas e contatos (carteira)

Tarefas

Base de empresas do Brasil

Uso

Códigos das cidades: os do IBGE usados pela Receita (o CRM mostra o código ao escolher a cidade na busca). Ramo: parte do nome (ex.: padaria) ou o código do CNAE (ex.: 4721), separados por vírgula.

Exemplos

Contar e listar padarias abertas nos últimos 90 dias em Fortaleza

curl 'https://suaempresa.crm.gocodesystems.com.br/api?r=/busca/contar&municipios=1389&ramo=padaria&novas=90' \
  -H 'Authorization: Bearer gcp_...'

curl 'https://suaempresa.crm.gocodesystems.com.br/api?r=/busca&municipios=1389&ramo=padaria&novas=90&por_pagina=50' \
  -H 'Authorization: Bearer gcp_...'

Abrir a ficha de uma empresa (telefones, e-mail e sócios)

curl 'https://suaempresa.crm.gocodesystems.com.br/api?r=/empresas/12345678000195' \
  -H 'Authorization: Bearer gcp_...'

Mandar empresas da base para o funil

curl -X POST 'https://suaempresa.crm.gocodesystems.com.br/api?r=/busca/funil' \
  -H 'Authorization: Bearer gcp_...' -H 'Content-Type: application/json' \
  -d '{"cnpjs": ["12345678000195", "98765432000110"], "responsavel_email": "ana@suaempresa.com.br"}'

Criar um negócio vindo do formulário do seu site

curl -X POST 'https://suaempresa.crm.gocodesystems.com.br/api?r=/negocios' \
  -H 'Authorization: Bearer gcp_...' -H 'Content-Type: application/json' \
  -d '{"titulo": "Orçamento pelo site", "valor": 2500, "origem": "site", "cliente": {"nome": "Mercado Bom Preço", "email": "compras@bompreco.com.br", "telefone": "85999990000"}}'

Marcar um negócio como ganho

curl -X PATCH 'https://suaempresa.crm.gocodesystems.com.br/api?r=/negocios/42' \
  -H 'Authorization: Bearer gcp_...' -H 'Content-Type: application/json' \
  -d '{"status": "ganho"}'

Respostas e erros

Sucesso: 200 ou 201 (criado), com o JSON do recurso. Erro: o código HTTP e {"erro": "o motivo, em português"}.

• 401 chave ausente, inválida ou revogada · 402 acabaram os contatos do mês · 403 sem permissão, chave só de leitura ou plano sem API
• 404 não encontrado · 422 dado inválido (o motivo vem no erro) · 429 limite por minuto ou do mês · 503 base em atualização

Webhooks

Cadastre um endereço https e escolha os avisos. A cada evento mandamos um POST em JSON com evento, criado_em, empresa e dados. Se o seu endereço não responder 2xx, tentamos de novo em 1, 5 e 30 minutos, 2 e 10 horas; depois de 30 falhas seguidas o webhook é desligado e quem o criou é avisado no sino.

Cabeçalhos: X-GoCode-Evento, X-GoCode-Entrega (número da entrega, para não processar duas vezes) e X-GoCode-Assinatura = sha256= HMAC-SHA256 do corpo com o segredo do webhook.

// PHP: confira a assinatura antes de usar o aviso
$corpo = file_get_contents('php://input');
$esperado = 'sha256=' . hash_hmac('sha256', $corpo, 'SEU_SEGREDO');
if (!hash_equals($esperado, $_SERVER['HTTP_X_GOCODE_ASSINATURA'] ?? '')) {
  http_response_code(401);
  exit;
}
$aviso = json_decode($corpo, true);   // ['evento' => 'negocio.ganho', 'criado_em' => ..., 'empresa' => ..., 'dados' => [...]]

Dados pessoais

A base vem do cadastro aberto da Receita Federal. O CPF dos sócios vem sempre mascarado, e as empresas que pediram para sair não aparecem. Você é responsável pelo uso dos contatos (sem spam), conforme os termos de uso e a política de privacidade.