contacts.xray
Raio-X do contato. Tudo o que o Raio-X mostra numa chamada: cabeçalho (desde quando, de onde veio, tags, cliente, oportunidades abertas), temperatura e Score gravados, intenção (sinais de compra dos últimos 30 dias, pelo catálogo da temperatura), compras (quantidade, produtos distintos, ticket médio, LTV e valor em oportunidades abertas, em centavos), comunicação por canal (última interação, quem falou por último e consentimento: can_receive sem registro de opt-out, subscribed com opt-in, unsubscribed com opt-out; null = sem endereço no canal) e atividade dos últimos 14 dias. contact traz code (número sequencial), city e state do endereço. purchases.products = produtos distintos; purchases.externalByCurrency = vendas de plataformas integradas por moeda (aprovadas e renovações; ltvCents desconta reembolso e chargeback), vazio sem integração. summary traz o resumo da Atom guardado (text e generatedAt; available: false e text: null enquanto não há); quem gera e refaz é contacts.xray_summary.
- Endpoint:
POST https://app.atomiks.com.br/api/v1/contacts.xray(corpo JSON) - Quem pode chamar: membro da conta
- Escopo da chave:
contacts:read - Grava dados: não
- Pela chave de API: sim
- Ferramenta MCP:
contacts_xray - Ficha em JSON:
https://app.atomiks.com.br/api/v1/openapi.json(operationIdcontacts.xray)
Entrada
| Campo | Tipo | Obrigatório | Nota |
|---|---|---|---|
contactId | string (uuid) | sim |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"contactId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"contactId"
]
}Exemplo
curl -X POST https://app.atomiks.com.br/api/v1/contacts.xray \
-H "Authorization: Bearer $ATOMIKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactId":"00000000-0000-0000-0000-000000000000"}'CLI:
node cli/atomiks.mjs contacts.xray --json '{"contactId":"00000000-0000-0000-0000-000000000000"}'MCP: ferramenta contacts_xray com a mesma entrada.
Saída
Sucesso: {"data": ...} com o formato abaixo.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"contact": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"code": {
"type": [
"number",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"email": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"avatarUrl": {
"type": [
"string",
"null"
]
},
"since": {
"type": "string"
},
"isCustomer": {
"type": "boolean"
},
"openOpportunities": {
"type": "number"
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"color": {
"type": "string"
}
},
"required": [
"id",
"name",
"color"
],
"additionalProperties": false
}
},
"tagsTotal": {
"type": "number"
}
},
"required": [
"id",
"code",
"name",
"phone",
"email",
"city",
"state",
"avatarUrl",
"since",
"isCustomer",
"openOpportunities",
"tags",
"tagsTotal"
],
"additionalProperties": false
},
"origin": {
"type": "object",
"properties": {
"kind": {
"type": [
"string",
"null"
]
},
"detail": {
"type": [
"string",
"null"
]
},
"adId": {
"type": [
"string",
"null"
]
},
"adName": {
"type": [
"string",
"null"
]
},
"campaignName": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
}
},
"required": [
"kind",
"detail",
"adId",
"adName",
"campaignName",
"headline"
],
"additionalProperties": false
},
"temperature": {
"anyOf": [
{
"type": "object",
"properties": {
"value": {
"type": "number"
},
"band": {
"type": "string",
"enum": [
"cold",
"warm",
"hot"
]
},
"trend7d": {
"type": [
"number",
"null"
]
},
"computedAt": {
"type": [
"string",
"null"
]
}
},
"required": [
"value",
"band",
"trend7d",
"computedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"score": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"value": {
"type": [
"number",
"null"
]
},
"tier": {
"anyOf": [
{
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
{
"type": "null"
}
]
}
},
"required": [
"enabled",
"value",
"tier"
],
"additionalProperties": false
},
"summary": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"text": {
"type": [
"string",
"null"
]
},
"generatedAt": {
"type": [
"string",
"null"
]
},
"reason": {
"type": "string"
}
},
"required": [
"available",
"text",
"generatedAt",
"reason"
],
"additionalProperties": false
},
"intent": {
"type": "object",
"properties": {
"level": {
"type": "string",
"enum": [
"high",
"medium",
"low",
"none"
]
},
"windowDays": {
"type": "number"
},
"signals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"eventName": {
"type": "string"
},
"label": {
"type": "string"
},
"count": {
"type": "number"
},
"lastAt": {
"type": "string"
}
},
"required": [
"eventName",
"label",
"count",
"lastAt"
],
"additionalProperties": false
}
}
},
"required": [
"level",
"windowDays",
"signals"
],
"additionalProperties": false
},
"purchases": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"products": {
"type": "number"
},
"externalByCurrency": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"count": {
"type": "number"
},
"totalCents": {
"type": "number"
},
"avgCents": {
"type": "number"
},
"ltvCents": {
"type": "number"
}
},
"required": [
"currency",
"count",
"totalCents",
"avgCents",
"ltvCents"
],
"additionalProperties": false
}
},
"avgTicketCents": {
"type": "number"
},
"ltvCents": {
"type": "number"
},
"openCents": {
"type": "number"
},
"orders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"productName": {
"type": [
"string",
"null"
]
},
"valueCents": {
"type": "number"
},
"soldAt": {
"type": "string"
},
"source": {
"type": "string"
}
},
"required": [
"id",
"productName",
"valueCents",
"soldAt",
"source"
],
"additionalProperties": false
}
}
},
"required": [
"count",
"products",
"externalByCurrency",
"avgTicketCents",
"ltvCents",
"openCents",
"orders"
],
"additionalProperties": false
},
"communication": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"whatsapp",
"email",
"instagram",
"telegram",
"voice"
]
},
"lastInteractionAt": {
"type": [
"string",
"null"
]
},
"lastInboundAt": {
"type": [
"string",
"null"
]
},
"lastDirection": {
"anyOf": [
{
"type": "string",
"enum": [
"inbound",
"outbound"
]
},
{
"type": "null"
}
]
},
"consent": {
"anyOf": [
{
"type": "string",
"enum": [
"can_receive",
"subscribed",
"unsubscribed"
]
},
{
"type": "null"
}
]
}
},
"required": [
"channel",
"lastInteractionAt",
"lastInboundAt",
"lastDirection",
"consent"
],
"additionalProperties": false
}
},
"activity": {
"type": "object",
"properties": {
"windowDays": {
"type": "number"
},
"total": {
"type": "number"
},
"days": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": [
"date",
"count"
],
"additionalProperties": false
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"label": {
"type": "string"
},
"count": {
"type": "number"
},
"latestAt": {
"type": "string"
}
},
"required": [
"name",
"label",
"count",
"latestAt"
],
"additionalProperties": false
}
}
},
"required": [
"windowDays",
"total",
"days",
"items"
],
"additionalProperties": false
},
"updatedAt": {
"type": "string"
}
},
"required": [
"contact",
"origin",
"temperature",
"score",
"summary",
"intent",
"purchases",
"communication",
"activity",
"updatedAt"
],
"additionalProperties": false
}Erros
{"error": {"code", "message", "requestId"}}. Códigos: invalid_input (400), unauthorized (401), forbidden / account_pending / scope_missing (403), not_found (404), limit_reached (409), internal (500).