# 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` (operationId `contacts.xray`) ## Entrada | Campo | Tipo | Obrigatório | Nota | |---|---|---|---| | `contactId` | string (uuid) | sim | |
JSON Schema ```json { "$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 ```bash 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: ```bash 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. ```json { "$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).