For AI agents: the complete documentation index is available at https://docs.clickmax.io/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/reference/api/sdk-go.md.
  • Português
  • 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.
    Mantenha a chave no servidor

    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

    go get clickmax.io/go

    Crie o cliente

    O caminho de importação é clickmax.io/go e o pacote se chama clickmax:

    import "clickmax.io/go"
    
    c, err := clickmax.New(os.Getenv("CLICKMAX_API_KEY"))
    if err != nil {
    	log.Fatal(err)
    }

    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.

    ctx := context.Background()
    
    tags, err := c.Tags.List(ctx)
    if err != nil {
    	log.Fatal(err)
    }
    for _, tag := range tags.Data {
    	fmt.Println(tag.Name)
    }

    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.

    created, err := c.Tags.Create(ctx, clickmax.TagsCreateInput{Name: "VIP", Color: clickmax.Ptr("ff8800")})
    if err != nil {
    	log.Fatal(err)
    }
    fmt.Println(created.ID)

    Trate o erro

    Use errors.As para ler o *clickmax.Error e decida o tratamento pelo campo Type:

    tags, err := c.Tags.List(ctx)
    if err != nil {
    	var cerr *clickmax.Error
    	if errors.As(err, &cerr) {
    		switch cerr.Type {
    		case clickmax.ErrorTypeAuthentication:
    			log.Printf("chave recusada: code=%s request_id=%s", cerr.Code, cerr.RequestID)
    		case clickmax.ErrorTypeRateLimit:
    			log.Printf("limite de requisições atingido, tente de novo em %s", cerr.RetryAfter)
    		default:
    			log.Printf("tags.list falhou: type=%s code=%s request_id=%s", cerr.Type, cerr.Code, cerr.RequestID)
    		}
    	}
    	return
    }
    for _, tag := range tags.Data {
    	fmt.Println(tag.Name)
    }

    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.