API Marketek: Introdução para Desenvolvedores

A API da Marketek permite que desenvolvedores integrem a plataforma com sistemas externos, automatizem operações em escala e construam aplicações personalizadas. Este guia apresenta os conceitos fundamentais para começar a utilizar a API de forma eficiente.

Autenticação

A API da Marketek suporta dois métodos de autenticação:

• Chave de API (API Key) — ideal para integrações server-to-server. Gere sua chave em Configurações > Integrações > API. Envie a chave no header Authorization: Bearer SUA_CHAVE.
• OAuth 2.0 — recomendado para aplicações que acessam dados de múltiplas contas. Utilize o fluxo de autorização padrão (Authorization Code Grant) para obter tokens de acesso.

URL Base e Formato de Requisições

Todas as requisições devem ser feitas para:

https://rest.marketek.com.br/v1/

O formato padrão de envio e resposta é JSON. Inclua o header Content-Type: application/json em requisições POST e PUT.

Limites de Requisição (Rate Limits)

Quando o limite é excedido, a API retorna o código 429 Too Many Requests. Implemente lógica de retry com backoff exponencial.

Endpoints Disponíveis

Os principais grupos de endpoints são:

• /contacts — criar, listar, atualizar e excluir contatos.
• /opportunities — gerenciar oportunidades no pipeline.
• /conversations — enviar mensagens e consultar histórico.
• /campaigns — disparar campanhas de e-mail e SMS.
• /workflows — adicionar contatos a workflows existentes.
• /calendars — criar e gerenciar agendamentos.
• /forms — listar formulários e submissões.

Exemplos de Código

Exemplo com cURL

Buscar um contato pelo e-mail:

curl -X GET "https://rest.marketek.com.br/v1/contacts?email=joao@exemplo.com" 
  -H "Authorization: Bearer SUA_CHAVE" 
  -H "Content-Type: application/json"

Exemplo com Python

Criar um novo contato:

import requests

url = "https://rest.marketek.com.br/v1/contacts"
headers = {
    "Authorization": "Bearer SUA_CHAVE",
    "Content-Type": "application/json"
}
payload = {
    "firstName": "João",
    "lastName": "Silva",
    "email": "joao@exemplo.com",
    "phone": "+5511999998888"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Tratamento de Erros

A API retorna códigos HTTP padrão:

• 200 — sucesso.
• 201 — recurso criado com sucesso.
• 400 — requisição inválida (verifique o corpo da mensagem de erro).
• 401 — não autorizado (chave de API inválida ou expirada).
• 404 — recurso não encontrado.
• 429 — limite de requisições excedido.
• 500 — erro interno do servidor.

Webhooks para Eventos em Tempo Real

Além de consultar a API, você pode receber notificações automáticas quando eventos ocorrem na Marketek. Configure webhooks em Configurações > Integrações > Webhooks. Eventos suportados incluem:

• Contato criado ou atualizado
• Oportunidade movida de estágio
• Formulário submetido
• Pagamento recebido
• Agendamento criado ou cancelado