Ligue o GoCode Trade aos seus outros sistemas

Este é o caminho para ligar o GoCode Trade a outro sistema: o ERP ou o site da empresa, uma planilha ou uma ferramenta de automação. Siga os passos na ordem. Quem não programa pode ir direto ao passo 6.

1. O que dá para integrar
2. Criar a chave
3. Primeiro teste
4. Endereços da API
5. Webhooks (avisos automáticos)
6. Sem programar: Make, Zapier, n8n, Power Automate e Google Planilhas
7. Boas práticas e segurança
8. Ajuda

1O que dá para integrar

Há dois caminhos, que podem ser usados juntos:

• API: o outro sistema pergunta ao GoCode Trade (lê dados) ou manda dados para ele (grava), quando quiser.
• Webhooks: o GoCode Trade avisa o outro sistema na hora em que algo acontece, sem ele precisar perguntar.

Dados disponíveis na API

• Contratantes (as empresas que contratam a equipe), só os que a pessoa da chave vê.
• Contratos de cada contratante, com os profissionais alocados e os produtos conferidos nas visitas.
• Pontos de venda (lojas) com endereço e localização.
• Visitas: data, loja, profissional, check-in e check-out (hora e distância da loja), formulário (espaço, material, observações), produtos com preço, ruptura e validade, e a lista das fotos (só os dados: as imagens ficam no sistema).
• Conversa por contrato com o contratante: ler as mensagens e responder em nome da equipe.

Avisos disponíveis (webhooks)

• visita.realizada: Visita realizada (check-out feito)
• ruptura.registrada: Ruptura registrada no formulário da visita
• mensagem.contratante: Mensagem nova do contratante na conversa do contrato

2Criar a chave

1. Entre no GoCode Trade, menu Minha conta > API e webhooks (só o proprietário da conta vê).
2. Em Chaves da API, escreva para que é a chave (ex.: "Site", "Zapier", "ERP") e escolha:
   • Só leitura: o outro sistema só consulta. Use sempre que bastar.
   • Leitura e escrita: ele também cria e altera dados.
3. Clique em Criar e copie a chave na hora: ela começa com gct_ e aparece uma vez só. Se perder, revogue e crie outra.
4. Entregue a chave só para quem vai fazer a integração, por um canal seguro (nunca em grupo de mensagens ou e-mail aberto).

3Primeiro teste

No terminal (Prompt de Comando, PowerShell, Terminal do Mac ou Linux), troque gct_SUACHAVE pela chave e rode:

curl -H "Authorization: Bearer gct_SUACHAVE" "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/"

Se a chave estiver certa, a resposta mostra a empresa, a chave e os recursos disponíveis:

{
    "sistema": "GoCode Trade",
    "empresa": "suaempresa",
    "chave": {
        "nome": "Site",
        "escopo": "leitura"
    },
    "pessoa": {
        "nome": "Maria Souza",
        "email": "maria@suaempresa.com.br"
    },
    "recursos": [
        "contratantes",
        "contratos",
        "pdvs",
        "visitas"
    ]
}

Se vier {"erro": "Chave ausente ou inválida..."}, confira se copiou a chave inteira e se o cabeçalho está escrito como acima.

4Endereços da API

Endereço base: https://SUAEMPRESA.trade.gocodesystems.com.br/api?r= + o caminho. Exemplo: https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratantes.

• Todas as chamadas levam o cabeçalho Authorization: Bearer gct_....
• Para gravar (POST e PATCH), mande o corpo em JSON com Content-Type: application/json.
• Datas no formato AAAA-MM-DD; data e hora no formato ISO 8601 (2026-11-12T14:30:00-03:00). Valores em dinheiro vão em centavos (campos terminados em _cents).
• Listas vêm em páginas: &pagina=2 e &por_pagina=100 (até 100). A resposta traz total e paginas.
• Para buscar só o que mudou, use &desde=2026-11-01 ou &desde=2026-11-01T08:00.

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratantes" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "contratantes": [
        {
            "id": 7,
            "nome": "Café Bom Dia Alimentos",
            "cnpj": "12.345.678/0001-90",
            "email": "compras@cafebomdia.com.br",
            "telefone": "85999990000",
            "status": "ativo",
            "criado_em": "2026-03-02T10:00:00-03:00",
            "atualizado_em": null
        }
    ],
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "paginas": 1
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratantes/12" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "id": 7,
    "nome": "Café Bom Dia Alimentos",
    "cnpj": "12.345.678/0001-90",
    "email": "compras@cafebomdia.com.br",
    "telefone": "85999990000",
    "status": "ativo",
    "criado_em": "2026-03-02T10:00:00-03:00",
    "atualizado_em": null,
    "contratos": [
        {
            "id": 12,
            "numero": "Contrato 012",
            "status": "ativo"
        }
    ]
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratos" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "contratos": [
        {
            "id": 12,
            "numero": "Contrato 012",
            "contratante_id": 7,
            "contratante": "Café Bom Dia Alimentos",
            "servico": "promocao",
            "descricao": "Promoção nas redes de Fortaleza",
            "inicio": "2026-03-01",
            "fim": null,
            "status": "ativo",
            "produtos": [
                "Café Bom Dia 500 g"
            ],
            "profissionais": [
                {
                    "id": 18,
                    "nome": "Ana Souza"
                }
            ]
        }
    ],
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "paginas": 1
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratos/12" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "id": 12,
    "numero": "Contrato 012",
    "contratante_id": 7,
    "contratante": "Café Bom Dia Alimentos",
    "servico": "promocao",
    "descricao": "Promoção nas redes de Fortaleza",
    "inicio": "2026-03-01",
    "fim": null,
    "status": "ativo",
    "produtos": [
        "Café Bom Dia 500 g"
    ],
    "profissionais": [
        {
            "id": 18,
            "nome": "Ana Souza"
        }
    ]
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/pdvs" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "pdvs": [
        {
            "id": 33,
            "contratante_id": 7,
            "nome": "Supermercado Central - Aldeota",
            "rede": "Central",
            "codigo": "L-104",
            "cep": "60150-000",
            "logradouro": "Av. Santos Dumont",
            "numero": "1500",
            "bairro": "Aldeota",
            "cidade": "Fortaleza",
            "uf": "CE",
            "lat": -3.7372,
            "lng": -38.4972,
            "ativo": true
        }
    ],
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "paginas": 1
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/visitas" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "visitas": [
        {
            "id": 4821,
            "data": "2026-11-12",
            "hora_prevista": "08:00",
            "contrato_id": 12,
            "contratante_id": 7,
            "contratante": "Café Bom Dia Alimentos",
            "loja": {
                "id": 33,
                "nome": "Supermercado Central - Aldeota",
                "cidade": "Fortaleza",
                "uf": "CE"
            },
            "profissional": {
                "id": 18,
                "nome": "Ana Souza"
            },
            "checkin_em": "2026-11-12T08:04:00-03:00",
            "checkin_distancia_m": 35,
            "checkout_em": "2026-11-12T09:10:00-03:00",
            "checkout_distancia_m": 28,
            "espaco_frentes": 6,
            "material": "instalado",
            "observacoes": "Gôndola organizada.",
            "formulario_em": "2026-11-12T09:05:00-03:00",
            "produtos": [
                {
                    "produto": "Café Bom Dia 500 g",
                    "preco_cents": 1899,
                    "ruptura": false,
                    "validade": "2027-03-01"
                }
            ],
            "fotos": [
                {
                    "momento": "antes",
                    "tirada_em": "2026-11-12T08:06:00-03:00"
                }
            ],
            "atualizada_em": "2026-11-12T09:10:00-03:00"
        }
    ],
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "paginas": 1
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/visitas/12" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "id": 4821,
    "data": "2026-11-12",
    "hora_prevista": "08:00",
    "contrato_id": 12,
    "contratante_id": 7,
    "contratante": "Café Bom Dia Alimentos",
    "loja": {
        "id": 33,
        "nome": "Supermercado Central - Aldeota",
        "cidade": "Fortaleza",
        "uf": "CE"
    },
    "profissional": {
        "id": 18,
        "nome": "Ana Souza"
    },
    "checkin_em": "2026-11-12T08:04:00-03:00",
    "checkin_distancia_m": 35,
    "checkout_em": "2026-11-12T09:10:00-03:00",
    "checkout_distancia_m": 28,
    "espaco_frentes": 6,
    "material": "instalado",
    "observacoes": "Gôndola organizada.",
    "formulario_em": "2026-11-12T09:05:00-03:00",
    "produtos": [
        {
            "produto": "Café Bom Dia 500 g",
            "preco_cents": 1899,
            "ruptura": false,
            "validade": "2027-03-01"
        }
    ],
    "fotos": [
        {
            "momento": "antes",
            "tirada_em": "2026-11-12T08:06:00-03:00"
        }
    ],
    "atualizada_em": "2026-11-12T09:10:00-03:00"
}

curl "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratos/12/mensagens" \
  -H "Authorization: Bearer gct_SUACHAVE"

{
    "mensagens": [
        {
            "id": 316,
            "contrato_id": 12,
            "autor": "equipe",
            "autor_nome": "Maria (Supervisão)",
            "texto": "Combinado, a reposição sai na sexta.",
            "tem_foto": false,
            "lida_em": null,
            "criada_em": "2026-11-12T10:02:00-03:00"
        }
    ]
}

curl -X POST "https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratos/12/mensagens" \
  -H "Authorization: Bearer gct_SUACHAVE" \
  -H "Content-Type: application/json" \
  -d '{"texto":"Combinado, a reposição sai na sexta."}'

{
    "id": 316,
    "contrato_id": 12,
    "autor": "equipe",
    "autor_nome": "Maria (Supervisão)",
    "texto": "Combinado, a reposição sai na sexta.",
    "tem_foto": false,
    "lida_em": null,
    "criada_em": "2026-11-12T10:02:00-03:00"
}

Respostas de erro

Os erros vêm sempre no formato {"erro": "explicação"}.

5Webhooks: o GoCode Trade avisa o seu sistema

1. Prepare no seu sistema um endereço https público que receba POST com JSON e responda com código 2xx (200, 201 ou 204) em até 5 segundos. Endereços de rede interna (192.168..., 10..., localhost) são recusados.
2. Entre no GoCode Trade, menu Minha conta > API e webhooks (só o proprietário da conta vê), em Webhooks, cole o endereço, marque os eventos e clique em Adicionar webhook.
3. Copie o segredo que aparece (uma vez só): ele serve para conferir que o aviso veio mesmo do GoCode Trade.
4. Clique em Testar: chega um evento teste. O resultado aparece em Últimas entregas.

O que chega

Cabeçalhos: Content-Type: application/json, X-GoCode-Evento (o evento), X-GoCode-Entrega (número da entrega, o mesmo nas novas tentativas: use para não processar duas vezes) e X-GoCode-Assinatura. Corpo:

{
    "evento": "visita.realizada",
    "criado_em": "2026-11-12T14:30:00-03:00",
    "empresa": "suaempresa",
    "dados": {
        "visita": {
            "id": 4821,
            "data": "2026-11-12",
            "hora_prevista": "08:00",
            "contrato_id": 12,
            "contratante_id": 7,
            "contratante": "Café Bom Dia Alimentos",
            "loja": {
                "id": 33,
                "nome": "Supermercado Central - Aldeota",
                "cidade": "Fortaleza",
                "uf": "CE"
            },
            "profissional": {
                "id": 18,
                "nome": "Ana Souza"
            },
            "checkin_em": "2026-11-12T08:04:00-03:00",
            "checkin_distancia_m": 35,
            "checkout_em": "2026-11-12T09:10:00-03:00",
            "checkout_distancia_m": 28,
            "espaco_frentes": 6,
            "material": "instalado",
            "observacoes": "Gôndola organizada.",
            "formulario_em": "2026-11-12T09:05:00-03:00",
            "produtos": [
                {
                    "produto": "Café Bom Dia 500 g",
                    "preco_cents": 1899,
                    "ruptura": false,
                    "validade": "2027-03-01"
                }
            ],
            "fotos": [
                {
                    "momento": "antes",
                    "tirada_em": "2026-11-12T08:06:00-03:00"
                }
            ],
            "atualizada_em": "2026-11-12T09:10:00-03:00"
        }
    }
}

Os dados de cada evento

visita.realizada: Visita realizada (check-out feito)

{
    "visita": {
        "id": 4821,
        "data": "2026-11-12",
        "hora_prevista": "08:00",
        "contrato_id": 12,
        "contratante_id": 7,
        "contratante": "Café Bom Dia Alimentos",
        "loja": {
            "id": 33,
            "nome": "Supermercado Central - Aldeota",
            "cidade": "Fortaleza",
            "uf": "CE"
        },
        "profissional": {
            "id": 18,
            "nome": "Ana Souza"
        },
        "checkin_em": "2026-11-12T08:04:00-03:00",
        "checkin_distancia_m": 35,
        "checkout_em": "2026-11-12T09:10:00-03:00",
        "checkout_distancia_m": 28,
        "espaco_frentes": 6,
        "material": "instalado",
        "observacoes": "Gôndola organizada.",
        "formulario_em": "2026-11-12T09:05:00-03:00",
        "produtos": [
            {
                "produto": "Café Bom Dia 500 g",
                "preco_cents": 1899,
                "ruptura": false,
                "validade": "2027-03-01"
            }
        ],
        "fotos": [
            {
                "momento": "antes",
                "tirada_em": "2026-11-12T08:06:00-03:00"
            }
        ],
        "atualizada_em": "2026-11-12T09:10:00-03:00"
    }
}

ruptura.registrada: Ruptura registrada no formulário da visita

{
    "visita_id": 4821,
    "contrato_id": 12,
    "contratante": "Café Bom Dia Alimentos",
    "loja": "Supermercado Central - Aldeota",
    "data": "2026-11-12",
    "profissional": "Ana Souza",
    "produtos_em_ruptura": [
        "Café Bom Dia 500 g",
        "Café Bom Dia Extraforte 250 g"
    ]
}

mensagem.contratante: Mensagem nova do contratante na conversa do contrato

{
    "mensagem": {
        "id": 315,
        "contrato_id": 12,
        "autor": "contratante",
        "autor_nome": "Carlos (Café Bom Dia)",
        "texto": "Bom dia! A loja da Aldeota pediu reposição na sexta.",
        "tem_foto": false,
        "criada_em": "2026-11-12T09:41:00-03:00"
    }
}

Conferir a assinatura

X-GoCode-Assinatura vale sha256= seguido do HMAC-SHA256 do corpo exatamente como chegou, com o segredo. Calcule e compare; se não bater, ignore o aviso.

PHP

$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);   // $aviso['evento'], $aviso['dados']
http_response_code(204);

Node.js (Express)

const crypto = require('crypto');
app.post('/aviso', express.raw({ type: 'application/json' }), (req, res) => {
  const esperado = 'sha256=' + crypto.createHmac('sha256', process.env.SEGREDO).update(req.body).digest('hex');
  const recebido = req.get('X-GoCode-Assinatura') || '';
  if (esperado.length !== recebido.length || !crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido))) {
    return res.sendStatus(401);
  }
  const aviso = JSON.parse(req.body);   // aviso.evento, aviso.dados
  res.sendStatus(204);
});

Python (Flask)

import hmac, hashlib
@app.post('/aviso')
def aviso():
    corpo = request.get_data()
    esperado = 'sha256=' + hmac.new(SEGREDO.encode(), corpo, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperado, request.headers.get('X-GoCode-Assinatura', '')):
        return '', 401
    dados = request.get_json()   # dados['evento'], dados['dados']
    return '', 204

Se o seu endereço falhar

Sem resposta 2xx, tentamos de novo depois de 1, 5 e 30 minutos, 2 horas e 10 horas. Depois de 30 falhas seguidas o webhook é desligado e o proprietário recebe um aviso; para voltar, clique em Ligar. Os avisos podem chegar fora de ordem e, raramente, repetidos: use X-GoCode-Entrega para ignorar o que já processou.

6Sem programar

Nas ferramentas abaixo, use o endereço e a chave do passo 2. Os nomes dos menus podem mudar um pouco conforme a versão da ferramenta.

Make

• Receber avisos: crie um cenário com o módulo Webhooks > Custom webhook, copie o endereço que o Make gerar e cadastre no passo 5. Clique em Testar no GoCode Trade para o Make reconhecer os campos.
• Consultar ou gravar: use o módulo HTTP > Make a request, método GET ou POST, URL https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratantes, cabeçalho Authorization com o valor Bearer gct_SUACHAVE e, para gravar, corpo do tipo JSON.

Zapier

• Receber avisos: gatilho Webhooks by Zapier > Catch Hook; cadastre no passo 5 o endereço que o Zapier mostrar e clique em Testar.
• Consultar ou gravar: ação Webhooks by Zapier > Custom Request, com a URL, o método e o cabeçalho Authorization: Bearer gct_SUACHAVE. O Webhooks by Zapier faz parte dos planos pagos do Zapier.

n8n

• Receber avisos: nó Webhook com método POST; use a URL de produção dele no passo 5.
• Consultar ou gravar: nó HTTP Request, com autenticação por cabeçalho (Header Auth): nome Authorization, valor Bearer gct_SUACHAVE.

Power Automate

• Receber avisos: gatilho When a HTTP request is received (Quando uma solicitação HTTP é recebida); salve o fluxo, copie a URL gerada e cadastre no passo 5.
• Consultar ou gravar: ação HTTP, com o método, a URL e o cabeçalho Authorization. Esses dois conectores são do tipo premium no Power Automate.

Google Planilhas (Apps Script)

Na planilha, abra Extensões > Apps Script, cole o código abaixo, troque a chave e rode a função importar (na primeira vez o Google pede autorização). Para repetir sozinho, crie um acionador de tempo em Acionadores.

function importar() {
  var resp = UrlFetchApp.fetch('https://SUAEMPRESA.trade.gocodesystems.com.br/api?r=/contratantes&por_pagina=100', {
    headers: { Authorization: 'Bearer gct_SUACHAVE' },
    muteHttpExceptions: true
  });
  var dados = JSON.parse(resp.getContentText());
  var lista = dados[Object.keys(dados)[0]];   // a lista vem na primeira chave da resposta
  var aba = SpreadsheetApp.getActiveSheet();
  aba.clear();
  if (!lista || !lista.length) return;
  var colunas = Object.keys(lista[0]);
  aba.appendRow(colunas);
  lista.forEach(function (item) {
    aba.appendRow(colunas.map(function (c) { var v = item[c]; return typeof v === 'object' && v !== null ? JSON.stringify(v) : v; }));
  });
}

Para receber avisos numa planilha, publique o script como App da Web com uma função doPost(e) e cadastre a URL no passo 5. O Apps Script não mostra os cabeçalhos do pedido, então ali não dá para conferir a assinatura: use esse caminho só para dados que não sejam sensíveis.

7Boas práticas e segurança

• Guarde a chave só no servidor ou na ferramenta de automação. Nunca coloque a chave no código de um site (JavaScript no navegador) nem dentro de um aplicativo de celular: qualquer pessoa conseguiria copiá-la.
• Use uma chave por integração e dê nomes claros. Prefira Só leitura quando bastar.
• Ao trocar de fornecedor ou se a chave vazar, revogue e crie outra.
• Sempre confira a assinatura dos webhooks antes de usar os dados.
• LGPD: os dados pessoais que saem pela integração continuam sob a responsabilidade da sua empresa. Leve só o necessário e trate-os com o mesmo cuidado do sistema.
• Tudo o que a chave faz fica registrado como feito pela pessoa que a criou.

8Ajuda

Precisa de ajuda com a integração? Fale com o suporte do GoCode Trade pelo e-mail suporte@gocodesystems.com.br, contando o que está tentando fazer, o endereço usado e a resposta recebida (nunca mande a chave).