Começar
Primeira chamada
Dispare uma requisição real ao endpoint de busca de contatos e entenda a resposta.
Vamos usar o endpoint GET /contacts/message-search — o único endpoint público em Beta no momento. Ele busca contatos que mencionaram um termo específico em mensagens.
O que você precisa
- Uma API key criada com os escopos
contacts:reademessages:read - O
organization_id(UUID) da sua organização — visível na URL do CRM ou em Configurações → Geral
Requisição mínima
Substitua <SUA_API_KEY> e <ORG_ID> pelos seus valores.
curl -G "https://crm.oficinamartech.com/api/contacts/message-search" \
-H "Authorization: Bearer <SUA_API_KEY>" \
--data-urlencode "organization_id=<ORG_ID>" \
--data-urlencode "q=orçamento" \
--data-urlencode "limit=10"const url = new URL("https://crm.oficinamartech.com/api/contacts/message-search");
url.searchParams.set("organization_id", "<ORG_ID>");
url.searchParams.set("q", "orçamento");
url.searchParams.set("limit", "10");
const res = await fetch(url, {
headers: {
Authorization: `Bearer ${process.env.OFM_API_KEY}`,
},
});
const json = await res.json();
console.log(json.data);import os
import requests
res = requests.get(
"https://crm.oficinamartech.com/api/contacts/message-search",
params={
"organization_id": "<ORG_ID>",
"q": "orçamento",
"limit": 10,
},
headers={
"Authorization": f"Bearer {os.environ['OFM_API_KEY']}",
},
timeout=15,
)
res.raise_for_status()
print(res.json()["data"])$query = http_build_query([
"organization_id" => "<ORG_ID>",
"q" => "orçamento",
"limit" => 10,
]);
$ch = curl_init("https://crm.oficinamartech.com/api/contacts/message-search?$query");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer " . getenv("OFM_API_KEY"),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data["data"]);Resposta esperada
{
"data": [
{
"contact": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"organization_id": "<ORG_ID>",
"name": "Maria Silva",
"phone": "+5511999999999",
"email": "maria@example.com",
"avatar_url": null,
"source": "whatsapp"
},
"match_count": 3,
"conversations_count": 2,
"first_matched_at": "2026-05-15T14:23:00.000Z",
"last_matched_at": "2026-05-19T18:42:00.000Z",
"messages": []
}
],
"pagination": {
"limit": 10,
"offset": 0,
"count": 1,
"has_more": false,
"next_offset": null
},
"query": {
"organization_id": "<ORG_ID>",
"terms": ["orçamento"],
"match": "any",
"direction": "inbound",
"channel": null,
"from": null,
"to": null
}
}Entendendo o retorno
data[]— array de contatos que mencionaram o termomatch_count— número de mensagens do contato que contêm o termopagination— controles de paginação (veja guia)query— eco dos parâmetros normalizados (útil para debug)
A API normaliza acentos e capitalização. Buscar por "orcamento" retorna os mesmos resultados que "orçamento".
E se der erro?
- 401 Unauthorized — verifique se o header
Authorizationestá presente e a chave é válida - 403 Forbidden — chave válida mas sem o escopo necessário (
contacts:read+messages:read) - 400 Bad Request — algum parâmetro inválido. A resposta inclui
detailscom o problema
Veja Erros e retry para detalhes.