Como usar o SDK Go da Clickmax
O módulo clickmax.io/go chama a API da Clickmax a partir de código Go. Cada endpoint tem um método tipado, e toda chamada que falha devolve um *clickmax.Error com a categoria do erro.
Antes de começar, você precisa de:
- uma chave de API do workspace, criada por um proprietário ou administrador em Configurações > Conexões > API (detalhes em Autenticação na API da Clickmax);
- Go 1.24 ou mais recente. O módulo não tem dependências fora da biblioteca padrão.
A chave age em nome do workspace inteiro. Use o SDK somente no servidor e carregue a chave de uma variável de ambiente ou de um gerenciador de segredos. Nunca inclua a chave em código que roda no navegador ou em aplicativos.
Fazer a primeira chamada
Instale o módulo
Crie o cliente
O caminho de importação é clickmax.io/go e o pacote se chama clickmax:
clickmax.New não faz nenhuma requisição. Ele devolve erro quando a chave está vazia ou malformada ou quando uma opção é inválida.
Chame um endpoint
Os métodos ficam agrupados por recurso e seguem o caminho do endpoint: /tags/list vira c.Tags.List(ctx). Endpoints sem recurso são métodos do próprio cliente, como /whoami, que vira c.Whoami(ctx).
Todo método recebe um context.Context como primeiro argumento. Cancelar o contexto interrompe a requisição.
Endpoints de leitura com parâmetros de consulta recebem uma struct de parâmetros e os de escrita recebem o corpo da requisição como segundo argumento; clickmax.Ptr cria o ponteiro que um campo opcional exige.
Trate o erro
Use errors.As para ler o *clickmax.Error e decida o tratamento pelo campo Type:
Type e Code têm os mesmos valores dos campos type e code descritos em Erros na API da Clickmax. Ao pedir ajuda ao suporte, informe o RequestID. RetryAfter é o tempo indicado no cabeçalho Retry-After, ou zero quando o cabeçalho falta ou não pode ser lido.
Quando nenhuma resposta utilizável chega, o SDK usa tipos próprios: ErrorTypeNetwork, ErrorTypeTimeout, ErrorTypeAborted e ErrorTypeParse.
Consultar opções e todos os métodos
O README do repositório clickmax-go explica os campos opcionais e nulos, as opções WithTimeout, WithHeader e WithHTTPClient e como repetir uma chamada após um erro rate_limit. As opções valem para o cliente inteiro ou para uma única chamada. O SDK nunca repete requisições sozinho.
A documentação do pacote no pkg.go.dev lista todos os métodos, com os tipos de entrada e de resposta de cada um.
Atualizar o módulo
Cada versão do módulo corresponde à API v0 no momento em que foi publicada. Como a v0 ainda pode mudar, mantenha no go.mod a versão que você testou e teste a integração antes de atualizar.