# Solomon Public API - **OpenAPI Version:** `3.1.0` - **API Version:** `0.1.0` Uma **fonte de dados** para a analytics da Solomon. Consulte os mesmos datasets que alimentam os dashboards da Solomon — marketing por anúncio, receita, pedidos, produtos, sessões, funis, attribution, cohorts, influenciadores — e construa o que quiser sobre isso. ## Modelo - `GET /v1/datasets` — descubra o catálogo: cada dataset, suas dimensões e métricas. - `POST /v1/query` — execute uma query: escolha um dataset, as dimensões para `group_by`, as `metrics`, o intervalo de datas e (onde houver suporte) o model de `attribution` e os `filters`. Não há endpoints de 'resumo' pré-agregados — você recebe linhas e faz o cálculo. ## Autenticação Duas formas, ambas `Authorization: Bearer `: - **API key** (`sk_*`) — servidor para servidor. Crie uma no dashboard da Solomon ("Chaves de API") com a permissão `data.read`. - **Sessão de login** (`tok_*`) — `POST /v1/auth/login` ou login com Google; atua com as próprias permissões Solomon do usuário. Escolha uma empresa por request com `X-Solomon-Company-Id`. ## Envelope de resposta Sucesso: `{ data, meta }`. Erros: RFC 7807 (`application/problem+json`). ## Web analytics Sessões, page views e funil de conversão do site vêm do **pixel da Solomon** e saem pelo `POST /v1/query`, como qualquer outro dataset — não há endpoint separado. | Dataset | O que traz | `group_by` | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `sessions_metrics` | sessões, usuários, sessões com bounce, page views e duração total das sessões | `source`, `campaign`, `content` | | `funnel_metrics` | funil em contagens únicas: page view → view content → add to cart → início de checkout → dados de cliente/entrega/pagamento → checkout concluído | `source`, `campaign`, `content`, `country`, `state`, `city`, `device_type`, `browser_name`, `os_name` | | `pages_sessions_metrics` | sessões, etapas do funil, compras e receita por landing page | `page_path` | | `products_sessions_metrics` | sessões e etapas do funil por produto | `product_id` | Sessões por origem e campanha em setembro: ```json { "dataset": "sessions_metrics", "date_start": "2026-09-01", "date_end": "2026-09-30", "group_by": ["source", "campaign"] } ``` Os nomes exatos das métricas de cada um estão em `GET /v1/datasets/{name}`. O que muda em relação aos outros datasets: - **Pessoas, sessões ou eventos** — `funnel_metrics` aceita `options.scope` para escolher o que cada etapa conta: `"user_id"` (pessoas), `"session_id"` (sessões) ou `"event_id"` (eventos). - **País, cidade e device só no funil** — `sessions_metrics` quebra apenas por `source`, `campaign` e `content`. Para geo, device, browser ou sistema operacional, use `funnel_metrics`. - **Métricas sempre completas** — `sessions_metrics`, `pages_sessions_metrics` e `products_sessions_metrics` devolvem todas as métricas, mesmo quando `metrics` pede só algumas. - **Filtros e atribuição** — só `sessions_metrics` aceita `filters`. Nenhum dos quatro aceita `attribution`: é tráfego do site, não pedido atribuído a campanha. - **Pixel × plataforma de anúncios** — `marketing_per_ad` também tem `page_views`, `view_content` e `add_to_cart`, mas lá os números são os que Meta/Google reportam. O que aconteceu no site é o que está nos datasets acima. ## Atribuição Os datasets de mídia aceitam um `attribution` — o model que decide qual campanha leva o crédito de cada pedido: | Model | Quem ganha o pedido | | -------------------------- | --------------------------------------------------------------- | | `paid_last_click` (padrão) | o último toque pago antes da compra | | `paid_first_click` | o primeiro toque pago da jornada | | `last_click` | o último toque, pago ou não | | `linear` | crédito dividido entre os toques | | `total_impact` | todos os toques distintos levam o pedido inteiro (soma > total) | ### Não existe janela de N dias A pergunta "qual é a janela de atribuição?" não tem resposta em dias porque a amarração não é temporal: **o touchpoint entra no pedido pelo `order_id` que o pixel gravou**, não por proximidade da data. As regras que valem são estas: 1. **Corte temporal** — só entra touchpoint com `timestamp <= data de criação do pedido`. Toque posterior à compra é descartado. 2. **Toque sintético** — quando não há histórico de pixel, a própria UTM do pedido vira um touchpoint (`from_orders`). É desempate, não interação real: no last-click ele perde para qualquer toque de pixel de mesma prioridade. 3. **Prioridade do sinal** — a ordenação é `paid_priority` antes do tempo: tem `ad_id` > é pago > é influenciador > não é direto > não é orgânico. Por isso `paid_first_click` não é literalmente "o primeiro toque", e sim o primeiro toque *da melhor classe de sinal presente naquele pedido*. 4. **Horizonte efetivo** — é a retenção do identificador do visitante no pixel, não um parâmetro do model. ### Quando não há campanha `sem_atribuicao` é tráfego sem origem identificável (o cliente digitou a URL, veio de app, perdeu a UTM no caminho); `Manual` são pedidos lançados à mão. Nos endpoints por pedido e por cliente esses casos voltam com os campos de clique em `null` — não há campanha para atribuir, e inventar uma seria pior que a omissão. ### A jornada inteira, não só o vencedor Os modelos elegem **um** toque por pedido; a jornada tem os outros. Para ver as campanhas que participaram sem levar o último clique, peça `order_attribution` com `options.include_touchpoints: true` — cada linha ganha `touchpoints`, a lista cronológica de todos os toques do pedido (`at`, `source`, `account_id`, `campaign_id`, `adgroup_id`, `ad_id`, `utm_campaign`, `utm_content`, `has_ad_id`, `from_orders`, e `campaign_name` quando `include_names` também está ligado). A lista é cortada nos 200 toques mais recentes por pedido; quando corta, `touchpoints_truncated` vem `true` — `touchpoints_count` continua sendo a contagem real. `GET /v1/customers/journey` responde a mesma pergunta **agregada** no nível do workspace (caminhos de conversão e papel de cada canal), sem chave de pedido. ### Nome da campanha, não só o id Os datasets de `/v1/query` agrupam por id. Há três formas de chegar ao nome: - `GET /v1/catalog/campaigns` — o cadastro (id, nome, status, `created_time`, conta, canal, UTMs) nos níveis `campaign`, `adgroup` e `ad`. Sincronize uma vez e faça o join. - `order_attribution` com `options.include_names: true` — os nomes já na linha do pedido. - `GET /v1/customers/acquisition?include_names=true` — idem na linha do cliente. **Data de início e de término de campanha não existem no dado** — não são coletadas de Meta/Google hoje. O campo mais próximo é `created_time`. ### Cobertura de `customer_id` Parte das plataformas (e todo pedido manual) não informa `customer_id`. Onde ele falta, a linha sai com `customer_id: null` e o pedido **não** aparece em `/v1/customers/acquisition`, que depende dessa chave. A visão por cliente cobre menos pedidos que a visão por pedido — compare as contagens antes de tratar a diferença como bug. ### Comparar com a plataforma de anúncios Estes números não batem com o Meta/Google Ads por desenho: as plataformas atribuem por view-through e janelas próprias, aqui a atribuição é por toque observado no site. A diferença é esperada; o que deve bater é a soma dos pedidos por campanha entre `order_attribution` e `attribution_metrics` no **mesmo model**. ## Rate limiting Token bucket por key: **60 requisições/minuto**, com **burst de 30**. O bucket recarrega continuamente (1 token/segundo), então 60 req/min sustentado passa; o que não passa é uma rajada acima de 30 de uma vez. Toda resposta traz `X-RateLimit-Limit` e `X-RateLimit-Remaining`. Ao estourar você recebe `429` com `Retry-After` em segundos — espere esse tempo antes de tentar de novo. Se precisar de mais vazão, fale com a gente em vez de paralelizar: o teto é por key, e abrir várias keys para contorná-lo satura o motor de query e degrada todo mundo. ## Saturação do motor de query Independente do seu limite, a API mantém um teto de chamadas simultâneas ao motor de query. Em pico você pode receber `503` com código `upstream_busy` e `Retry-After` — é recusa temporária e **retentável**, não erro da sua query. Trate com retry e backoff exponencial. Dica: consultas analíticas mudam devagar. Cacheie do seu lado e agende janelas amplas em vez de reconsultar o mesmo período em loop — a maior parte do tráfego que estoura o limite é polling repetido de dado que não mudou. ## Para IA / LLMs A referência completa em markdown está em `/llms.txt` — aponte seu assistente de IA para ela, ou use o botão **Copiar para IA** no canto inferior direito desta página. ## Versionamento Todos os endpoints sob `/v1`. Apenas mudanças aditivas dentro do `v1`; mudanças incompatíveis vão para `/v2`. ## Servers - **URL:** `https://read-api.solomon.com.br` - **Description:** produção ## Operations ### Fazer login com email e senha - **Method:** `POST` - **Path:** `/v1/auth/login` - **Tags:** Auth Autentica com as credenciais Solomon e retorna um token de sessão. Use-o como `Authorization: Bearer tok_live_xxx` nos requests de dados. #### Request Body ##### Content-Type: application/json - **`email` (required)** `string`, format: `email` - **`password` (required)** `string` **Example:** ```json { "email": "", "password": "" } ``` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`companies` (required)** `array` — Empresas que a conta pode acessar. Escolha uma com \`X-Solomon-Company-Id\`. **Items:** - **`id` (required)** `string` - **`name` (required)** `string` - **`expires_at` (required)** `string` - **`refresh_token` (required)** `string` - **`token` (required)** `string` — Token de acesso — envie como \`Authorization: Bearer\`. - **`token_type` (required)** `string`, possible values: `"Bearer"` - **`user` (required)** `object` - **`email` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string | null` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "token": "tok_live_...", "refresh_token": "", "token_type": "Bearer", "expires_at": "", "user": { "id": "", "email": null, "name": null }, "companies": [] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Trocar um refresh token por uma nova sessão - **Method:** `POST` - **Path:** `/v1/auth/refresh` - **Tags:** Auth #### Request Body ##### Content-Type: application/json - **`refresh_token` (required)** `string` **Example:** ```json { "refresh_token": "" } ``` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`companies` (required)** `array` — Empresas que a conta pode acessar. Escolha uma com \`X-Solomon-Company-Id\`. **Items:** - **`id` (required)** `string` - **`name` (required)** `string` - **`expires_at` (required)** `string` - **`refresh_token` (required)** `string` - **`token` (required)** `string` — Token de acesso — envie como \`Authorization: Bearer\`. - **`token_type` (required)** `string`, possible values: `"Bearer"` - **`user` (required)** `object` - **`email` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string | null` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "token": "tok_live_...", "refresh_token": "", "token_type": "Bearer", "expires_at": "", "user": { "id": "", "email": null, "name": null }, "companies": [] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Informações da sessão atual - **Method:** `GET` - **Path:** `/v1/auth/me` - **Tags:** Auth #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`companies` (required)** `array` **Items:** - **`id` (required)** `string` - **`name` (required)** `string` - **`kind` (required)** `string`, possible values: `"api_key", "user_session"` - **`user` (required)** `object` - **`email` (required)** `string | null` - **`id` (required)** `string` - **`workspace_id` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "kind": "api_key", "workspace_id": "", "user": { "id": "", "email": null }, "companies": [ { "id": "", "name": "" } ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Revogar a sessão de login atual - **Method:** `POST` - **Path:** `/v1/auth/logout` - **Tags:** Auth Revoga a sessão por trás do token `tok_*` apresentado — seus tokens de acesso e refresh (e o restante da sua família de rotação) param de funcionar imediatamente. Aplica-se apenas a sessões de login; API keys são gerenciadas no dashboard da Solomon. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`revoked` (required)** `boolean` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "revoked": true }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Iniciar login com Google - **Method:** `POST` - **Path:** `/v1/auth/google/start` - **Tags:** Auth Retorna uma URL de autorização do Google mais um `poll_token`. Abra a URL em um browser; após o consentimento o Google redireciona para o callback da API. Faça polling em `/v1/auth/google/poll` com `login_id` e `poll_token`. `intent`: `login` (padrão) para contas de clientes; `internal` para contas Workspace `@solomon.com.br` da equipe Solomon. #### Request Body ##### Content-Type: application/json - **`intent`** `string`, possible values: `"login", "internal"` **Example:** ```json { "intent": "login" } ``` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`authorization_url` (required)** `string`, format: `uri` - **`login_id` (required)** `string` - **`poll_token` (required)** `string` — Segredo para \`/v1/auth/google/poll\`. Mantenha-o no client — nunca o coloque no browser ou no redirect. Necessário para resgatar a sessão. - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "login_id": "", "authorization_url": "", "poll_token": "" }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Fazer polling de um login com Google - **Method:** `POST` - **Path:** `/v1/auth/google/poll` - **Tags:** Auth #### Request Body ##### Content-Type: application/json - **`login_id` (required)** `string` - **`poll_token` (required)** `string` — O \`poll\_token\` retornado por \`/v1/auth/google/start\`. **Example:** ```json { "login_id": "", "poll_token": "" } ``` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "status": "pending" }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Listar datasets disponíveis - **Method:** `GET` - **Path:** `/v1/datasets` - **Tags:** Data Retorna o catálogo de datasets consultáveis — dimensões que você pode usar em `group_by`, os `metrics` disponíveis, suporte a attribution/filtros. Use qualquer um em `POST /v1/query`. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`datasets` (required)** `array` **Items:** - **`description` (required)** `string` - **`dimensions` (required)** `array` **Items:** `string` - **`grouping_field` (required)** `string`, possible values: `"levels", "breakdowns", "breakdown", "none"` - **`ignores_metric_selection` (required)** `boolean` — True quando o dataset sempre devolve TODAS as métricas, mesmo que \`metrics\` peça um subconjunto — o motor de query a montante não sabe servir seleção parcial aqui. - **`metrics` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`pagination_only` (required)** `boolean` — True quando o dataset SÓ é servido paginado — sem \`limit\`/\`cursor\` o request é recusado com 422 em vez de devolver um resultado truncado. - **`requires_group_by` (required)** `boolean` — True quando \`group\_by\` é obrigatório — sem pelo menos uma dimensão o request é recusado com 422. Datasets sem dimensão nenhuma nunca aceitam \`group\_by\`. - **`storage` (required)** `string`, possible values: `"postgres", "clickhouse"` - **`supports_attribution` (required)** `boolean` - **`supports_filtering` (required)** `boolean` - **`supports_pagination` (required)** `boolean` — True quando \`POST /v1/query\` aceita \`limit\`/\`cursor\` para este dataset. - **`extra_options`** `array` **Items:** `string` - **`extra_options_help`** `object` — O que cada \`extra\_options\` aceita — tipo, valores válidos e default. - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "datasets": [ { "name": "", "description": "", "storage": "postgres", "grouping_field": "levels", "dimensions": [ "" ], "metrics": [ "" ], "supports_attribution": true, "supports_filtering": true, "supports_pagination": true, "pagination_only": true, "requires_group_by": true, "ignores_metric_selection": true, "extra_options": [ "" ], "extra_options_help": { "additionalProperty": "" } } ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Obter o schema de um dataset - **Method:** `GET` - **Path:** `/v1/datasets/{name}` - **Tags:** Data #### Parameters ##### `name` required - **In:** `path` `string` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`description` (required)** `string` - **`dimensions` (required)** `array` **Items:** `string` - **`grouping_field` (required)** `string`, possible values: `"levels", "breakdowns", "breakdown", "none"` - **`ignores_metric_selection` (required)** `boolean` — True quando o dataset sempre devolve TODAS as métricas, mesmo que \`metrics\` peça um subconjunto — o motor de query a montante não sabe servir seleção parcial aqui. - **`metrics` (required)** `array` **Items:** `string` - **`name` (required)** `string` - **`pagination_only` (required)** `boolean` — True quando o dataset SÓ é servido paginado — sem \`limit\`/\`cursor\` o request é recusado com 422 em vez de devolver um resultado truncado. - **`requires_group_by` (required)** `boolean` — True quando \`group\_by\` é obrigatório — sem pelo menos uma dimensão o request é recusado com 422. Datasets sem dimensão nenhuma nunca aceitam \`group\_by\`. - **`storage` (required)** `string`, possible values: `"postgres", "clickhouse"` - **`supports_attribution` (required)** `boolean` - **`supports_filtering` (required)** `boolean` - **`supports_pagination` (required)** `boolean` — True quando \`POST /v1/query\` aceita \`limit\`/\`cursor\` para este dataset. - **`extra_options`** `array` **Items:** `string` - **`extra_options_help`** `object` — O que cada \`extra\_options\` aceita — tipo, valores válidos e default. - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "name": "", "description": "", "storage": "postgres", "grouping_field": "levels", "dimensions": [ "" ], "metrics": [ "" ], "supports_attribution": true, "supports_filtering": true, "supports_pagination": true, "pagination_only": true, "requires_group_by": true, "ignores_metric_selection": true, "extra_options": [ "" ], "extra_options_help": { "additionalProperty": "" } }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 404 Dataset desconhecido. ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Executar uma query de dataset - **Method:** `POST` - **Path:** `/v1/query` - **Tags:** Data Executa uma query contra um dataset do Solomon e retorna as linhas brutas. Um endpoint, todos os datasets — construa dashboards, sincronize com um warehouse, gere relatórios. **Limites** — o range de datas é limitado a 366 dias por query; `group_by` aceita somente as `dimensions` listadas em `GET /v1/datasets` (violação → `422` com as dimensões válidas). Respostas grandes são entregues com `Transfer-Encoding: chunked`. **Paginação** — datasets com `supports_pagination: true` (hoje: marketing\_per\_ad, orders\_metrics, order\_attribution) aceitam `limit` (1–1000) e `cursor`. No modo paginado o `result` traz `{ rows: [...] }` — linhas planas ordenadas por `(date, order_id)` — e `meta.pagination` traz `next_cursor` e `has_more`; envie o `next_cursor` de volta no mesmo request para a próxima página. Sem `limit`/`cursor` o resultado vem completo no shape dos dashboards (compatível com o atual). **Exports longos** — agrupar por uma dimensão de identidade (`orders_metrics` por `order_id`) sem paginação é limitado a 7 dias de intervalo: o shape aninhado repete uma série diária por métrica para cada pedido, e em janelas longas o request não completa. Para períodos maiores mande `limit` — o caminho paginado devolve linhas planas, não tem limite de intervalo e é ordens de magnitude mais barato. **Datasets só-paginados** — `order_attribution` tem `pagination_only: true`: não existe shape agregado para ele, então sem `limit`/`cursor` o request é recusado com `422`. É recusa deliberada — devolver a primeira página calada faria você ler 500 pedidos como se fossem todos. #### Request Body ##### Content-Type: application/json - **`dataset` (required)** `string`, possible values: `"marketing_per_ad", "marketing_per_channel", "attribution_metrics", "general_attribution_metrics", "revenue", "orders_metrics", "order_attribution", "product_metrics", "clients_cohort", "influencer_metrics", "fixed_influencer_cost", "sessions_metrics", "funnel_metrics", "pages_sessions_metrics", "products_sessions_metrics", "payments_cost", "daily_product_cost", "daily_meta_tax_cost", "additional_cost", "additional_revenue"` — Nome do dataset. Veja \`GET /v1/datasets\`. - **`date_end` (required)** `string` — Fim do range (inclusive). O range completo é limitado a 366 dias. - **`date_start` (required)** `string` — Início do range (inclusive). O range completo é limitado a 366 dias. - **`attribution`** `string`, possible values: `"paid_last_click", "paid_first_click", "last_click", "linear", "total_impact"` — Model de attribution — aplica-se apenas a datasets onde \`supports\_attribution\` é true. O padrão é \`paid\_last\_click\` quando omitido. - **`cursor`** `string` — Cursor opaco devolvido em \`meta.pagination.next\_cursor\` — envie-o de volta (com os MESMOS dataset/datas/metrics) para buscar a próxima página. Implica o modo paginado. - **`filters`** `object` — Filtros de igualdade dimensão → valor. Apenas quando \`supports\_filtering\` é true. - **`group_by`** `array` — Dimensões para agrupar — subconjunto das \`dimensions\` do dataset. **Items:** `string` - **`limit`** `integer` — Ativa o modo paginado (datasets com \`supports\_pagination: true\`). Máximo de linhas por página (1–1000). No modo paginado o \`result\` traz \`rows\` planas (uma por pedido) e \`meta.pagination\` traz \`next\_cursor\`/\`has\_more\`. - **`metrics`** `array` — Metrics a retornar — subconjunto dos \`metrics\` do dataset. Omita para usar o conjunto padrão. **Items:** `string` - **`options`** `object` — Opções extras específicas do dataset, listadas em \`extra\_options\` no catálogo. Chave que não estiver na lista é recusada com 422 — um \`include\_touchpoint\` no singular vira erro explícito, não um 200 sem o campo que você pediu. **Example:** ```json { "dataset": "marketing_per_ad", "date_start": "2026-05-01", "date_end": "2026-05-19", "group_by": [ "campaign", "ad" ], "metrics": [ "spend", "revenue", "purchases" ], "attribution": "paid_last_click", "filters": { "source": "facebook" }, "options": {}, "limit": 500, "cursor": "" } ``` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`attribution` (required)** `string | null` - **`dataset` (required)** `string` - **`date_end` (required)** `string` - **`date_start` (required)** `string` - **`group_by` (required)** `array` **Items:** `string` - **`metrics` (required)** `array` — Metrics retornados. \`null\` quando \`metrics\` foi omitido do request — o conjunto padrão do dataset foi usado; inspecione \`result\` para ver as colunas presentes. **Items:** `string` - **`result`** `object` — Resultado bruto do dataset — a estrutura exata que os dashboards do Solomon consomem. No modo paginado (\`limit\`/\`cursor\`), em vez disso vem \`{ rows: \[...] }\` com uma linha plana por pedido e as métricas como colunas; a página seguinte é obtida re-enviando o request com \`cursor = meta.pagination.next\_cursor\`. - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "dataset": "", "date_start": "", "date_end": "", "group_by": [ "" ], "metrics": [ "" ], "attribution": null, "result": null }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Clientes adquiridos e a campanha de aquisição - **Method:** `GET` - **Path:** `/v1/customers/acquisition` - **Tags:** Customers Uma linha por cliente adquirido no período, com a campanha do **primeiro pedido** — a campanha de aquisição — em first-click e last-click lado a lado. Responde as duas pontas: sem filtro, *de qual campanha cada cliente veio*; com `campaign_id=`, *quais clientes aquela campanha trouxe*. `attribution` escolhe qual clique os filtros (`campaign_id`, `source`) e as colunas `acquisition_*` consideram — os dois modelos vêm na linha de qualquer forma. Use o mesmo model em `attribution_metrics` (`new_total_purchases`) para reconciliar os totais. Cada clique traz source, conta, campanha, adgroup, anúncio, as UTMs (`utm_campaign`, `utm_content`) e o timestamp. Com `include_names=true` vêm também os **nomes** de campanha/adgroup/anúncio/conta, para o relatório não mostrar só id. **"Adquirido" = primeiro pedido aprovado.** Pedido pendente ou cancelado não cria cliente, e clientes cuja plataforma não informa `customer_id` ficam de fora — a cobertura é menor que a de `orders_metrics`. Cliente sem campanha (venda manual, tráfego direto, UTM que não casa com anúncio) volta com os campos de clique em `null`. Paginado por `limit`/`cursor`: siga `meta.pagination.next_cursor` até `has_more: false`. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `attribution` - **In:** `query` `string`, possible values: `"paid_last_click", "paid_first_click"` — Model usado pelos filtros e pelas colunas \`acquisition\_\*\`. Padrão \`paid\_last\_click\`. ##### `campaign_id` - **In:** `query` `string` — Só clientes cuja campanha de aquisição (no model escolhido) é esta. ##### `source` - **In:** `query` `string` — Idem, para o canal. ##### `include_names` - **In:** `query` `[ "boolean", "null" ]` — Acrescenta os NOMES de campanha/adgroup/anúncio/conta (\`\*\_click\_campaign\_name\` etc. e \`acquisition\_campaign\_name\`) junto dos ids. Custa um scan do cadastro de anúncios por request — para sincronizar o cadastro uma vez e fazer o join do seu lado, use \`GET /v1/catalog/campaigns\`. ##### `include_lifetime` - **In:** `query` `[ "boolean", "null" ]` — Acrescenta \`orders\_count\`, \`lifetime\_revenue\` e \`last\_order\_at\` do cliente. Custa um agregado a mais sobre os pedidos — fica de fora por padrão. ##### `limit` - **In:** `query` `integer` ##### `cursor` - **In:** `query` `string` — Cursor opaco devolvido em \`meta.pagination.next\_cursor\`. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`customers` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "customers": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Caminhos de conversão (jornada do cliente) - **Method:** `GET` - **Path:** `/v1/customers/journey` - **Tags:** Customers Jornada do cliente no nível do workspace — os caminhos de pontos de contato que levam à conversão e o papel de cada canal ao longo deles. Linhas brutas; agregue como preferir. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`paths` (required)** `array` **Items:** - **`sources` (required)** `array` **Items:** - **`time_range` (required)** `object` - **`end` (required)** `string` - **`start` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "time_range": { "start": "", "end": "" }, "paths": [ {} ], "sources": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Breakdown de Meta Ads por dado demográfico / placement - **Method:** `GET` - **Path:** `/v1/meta/breakdown` - **Tags:** Meta Cruza investimento e resultados do Meta Ads por uma única dimensão de breakdown. Direto da Meta Insights API — não passa pelo motor de query de datasets. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `breakdown` required - **In:** `query` `string`, possible values: `"age", "gender", "country", "region", "placement", "publisher_platform", "device_platform", "impression_device"` ##### `ad_account_id` - **In:** `query` `string` ##### `campaign_id` - **In:** `query` `string` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`breakdown` (required)** `string` - **`rows` (required)** `array` **Items:** - **`totals` (required)** `object` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "breakdown": "", "rows": [ {} ], "totals": {} }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Log de alterações do Meta Ads - **Method:** `GET` - **Path:** `/v1/meta/activity` - **Tags:** Meta Feed de auditoria de edições (orçamento, status, criativo) em objetos de ad da Meta no período. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `ad_account_id` - **In:** `query` `string` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`count` (required)** `integer` - **`events` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "events": [ {} ], "count": 1 }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Comentários em um ad da Meta - **Method:** `GET` - **Path:** `/v1/meta/comments` - **Tags:** Meta Comentários públicos no post que dá origem ao ad — para pipelines de moderação / sentimento. #### Parameters ##### `ad_id` required - **In:** `query` `string` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`comments` (required)** `array` **Items:** - **`count` (required)** `integer` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "comments": [ {} ], "count": 1 }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Insights orgânicos do Instagram - **Method:** `GET` - **Path:** `/v1/instagram/insights` - **Tags:** Instagram Alcance, impressões, visualizações de perfil, etc. da Instagram Graph API. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `ig_user_id` required - **In:** `query` `string` ##### `metrics` - **In:** `query` `string` — Nomes de métricas separados por vírgula. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`insights` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "insights": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Consulta de perfil business público do Instagram - **Method:** `GET` - **Path:** `/v1/instagram/business-discovery` - **Tags:** Instagram Consulta um perfil business/creator público do IG por username, via a própria conta business do IG do workspace (`ig_user_id`). #### Parameters ##### `username` required - **In:** `query` `string` ##### `ig_user_id` required - **In:** `query` `string` — O id da sua conta business do IG. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`biography` (required)** `string | null` - **`followers_count` (required)** `number | null` - **`follows_count` (required)** `number | null` - **`media_count` (required)** `number | null` - **`name` (required)** `string | null` - **`profile_picture_url` (required)** `string | null` - **`username` (required)** `string` - **`website` (required)** `string | null` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "username": "", "name": null, "biography": null, "followers_count": null, "follows_count": null, "media_count": null, "profile_picture_url": null, "website": null }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Assets criativos do Google Ads - **Method:** `GET` - **Path:** `/v1/google/assets` - **Tags:** Google Ads Títulos, descrições e imagens da biblioteca de assets do Google Ads, em todas as contas do Google Ads conectadas ao workspace. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `campaign_type` - **In:** `query` `string`, possible values: `"pmax", "search", "all"` — \`pmax\`, \`search\` ou \`all\` (padrão). ##### `min_impressions` - **In:** `query` `[ "integer", "null" ]` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`assets` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "assets": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Snapshot do estoque atual - **Method:** `GET` - **Path:** `/v1/catalog/stock` - **Tags:** Catalog Níveis de estoque e dias de cobertura projetados por produto / SKU. #### Parameters ##### `product_ids` - **In:** `query` `string` — Ids de produtos separados por vírgula. ##### `only_out_of_stock` - **In:** `query` `[ "boolean", "null" ]` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`items` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "items": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Uso e receita de cupons - **Method:** `GET` - **Path:** `/v1/catalog/coupons` - **Tags:** Catalog Resgates, receita, valor de desconto e participação de novos clientes por cupom. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `codes` - **In:** `query` `string` — Códigos de cupom separados por vírgula. ##### `sort_by` - **In:** `query` `string`, possible values: `"uses", "revenue", "discount_amount"` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`coupons` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "coupons": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Cadastro de campanhas, adgroups e anúncios - **Method:** `GET` - **Path:** `/v1/catalog/campaigns` - **Tags:** Catalog O cadastro que resolve **id → nome** para os datasets. As queries de `/v1/query` agrupam por `campaign_id`/`adgroup_id`/`ad_id`; puxe este cadastro uma vez e faça o join por id para apresentar nomes no relatório. `level` escolhe o grão: `campaign` (padrão), `adgroup` ou `ad`. Cada linha traz `id`, `name`, `status`, `created_time`, a conta (`account_id`/`account_name`), o canal (`source`) e as UTMs mapeadas; no nível `ad` vem também `image_url` e os ids/nomes dos níveis acima. **Data de início e de término de campanha não existem no dado** — não são coletadas de Meta/Google hoje. O campo mais próximo é `created_time`. Paginado por `limit`/`cursor`: siga `meta.pagination.next_cursor` até `has_more: false`. #### Parameters ##### `level` - **In:** `query` `string`, possible values: `"campaign", "adgroup", "ad"` — Grão do cadastro. Padrão \`campaign\`. ##### `source` - **In:** `query` `string` — Filtra por canal, ex.: \`facebook\`, \`google\`, \`tiktok\`, \`pinterest\`. ##### `status` - **In:** `query` `string` — Filtra por status do objeto no nível pedido (comparação case-insensitive). ##### `ids` - **In:** `query` `string` — Ids do nível pedido, separados por vírgula. ##### `q` - **In:** `query` `string` — Busca por nome (substring, case-insensitive). ##### `limit` - **In:** `query` `integer` ##### `cursor` - **In:** `query` `string` — Cursor opaco devolvido em \`meta.pagination.next\_cursor\`. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`items` (required)** `array` **Items:** - **`level` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "level": "", "items": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Comprados juntos com frequência - **Method:** `GET` - **Path:** `/v1/catalog/basket-analysis` - **Tags:** Catalog Pares de produtos que coocorrem em pedidos, com contagem de coocorrência, lift e confiança. #### Parameters ##### `start` required - **In:** `query` `string` ##### `end` required - **In:** `query` `string` ##### `min_co_occurrence` - **In:** `query` `integer` ##### `limit` - **In:** `query` `integer` #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`pairs` (required)** `array` **Items:** - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "pairs": [ {} ] }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### Impostos & taxas do período - **Method:** `GET` - **Path:** `/v1/finance/taxes` - **Tags:** Finance Imposto geral configurável da empresa (regra/alíquota com múltiplos períodos de vigência), imposto de mídia da Meta, e taxas de gateway/checkout — agregados no período. O imposto geral é calculado (não é métrica do `/v1/query`): mesma lógica do painel Solomon. #### Parameters ##### `date_start` required - **In:** `query` `string` ##### `date_end` required - **In:** `query` `string` ##### `attribution` - **In:** `query` `string`, possible values: `"paid_last_click", "paid_first_click", "last_click", "linear", "total_impact"` — Model de attribution usado nos agregados de custo. Padrão \`paid\_last\_click\`. #### Responses ##### Status: 200 Sucesso. ###### Content-Type: application/json - **`data` (required)** `object` - **`approved_revenue` (required)** `number` — Receita aprovada do período (base dos percentuais). - **`attribution` (required)** `string` - **`checkout_fee` (required)** `number` — Custo da plataforma de checkout no período. - **`date_end` (required)** `string` - **`date_start` (required)** `string` - **`gateway_fee` (required)** `number` — Custo de gateway de pagamento no período. - **`imposto` (required)** `number` — Imposto geral configurável da empresa, calculado pela regra/alíquota vigente em cada dia do período. 0 quando não configurado. - **`meta_tax_cost` (required)** `number` — Imposto sobre publicidade da Meta no período. - **`tax_rule` (required)** `object | null` — Regra/alíquota (e períodos de vigência) aplicada. \`null\` se imposto não configurado. - **`aliquote_rate`** `number` - **`calculation_rule`** `string` - **`periods`** `array` **Items:** - **`aliquote_rate`** `number` - **`calculation_rule`** `string` - **`end_date`** `string` - **`start_date`** `string` - **`taxes_and_fees_revenue_pct` (required)** `number` — taxes\_and\_fees\_total como % da receita aprovada. - **`taxes_and_fees_total` (required)** `number` — Soma de imposto + meta\_tax + gateway + checkout. - **`meta` (required)** `object` - **`request_id` (required)** `string` - **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "data": { "date_start": "", "date_end": "", "attribution": "", "approved_revenue": 1, "imposto": 1, "meta_tax_cost": 1, "gateway_fee": 1, "checkout_fee": 1, "taxes_and_fees_total": 1, "taxes_and_fees_revenue_pct": 1, "tax_rule": { "calculation_rule": "", "aliquote_rate": 1, "periods": [ { "calculation_rule": "", "aliquote_rate": 1, "start_date": "", "end_date": "" } ] } }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": null } } ``` ##### Status: 401 Token ausente ou inválido. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 403 O token não tem o scope necessário, ou a empresa não é permitida. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 422 Falha na validação do request. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 429 Rate limit excedido. Veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 500 Erro interno do servidor. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 502 Falha no serviço Solomon upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 503 Motor de query saturado (\`upstream\_busy\`). Temporário e retentável — veja \`Retry-After\`. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ##### Status: 504 Timeout no upstream. ###### Content-Type: application/problem+json - **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` - **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ## Schemas ### Company - **Type:**`object` * **`id` (required)** `string` * **`name` (required)** `string` **Example:** ```json { "id": "", "name": "" } ``` ### Session - **Type:**`object` * **`companies` (required)** `array` — Empresas que a conta pode acessar. Escolha uma com \`X-Solomon-Company-Id\`. **Items:** - **`id` (required)** `string` - **`name` (required)** `string` * **`expires_at` (required)** `string` * **`refresh_token` (required)** `string` * **`token` (required)** `string` — Token de acesso — envie como \`Authorization: Bearer\`. * **`token_type` (required)** `string`, possible values: `"Bearer"` * **`user` (required)** `object` - **`email` (required)** `string | null` - **`id` (required)** `string` - **`name` (required)** `string | null` **Example:** ```json { "token": "tok_live_...", "refresh_token": "", "token_type": "Bearer", "expires_at": "", "user": { "id": "", "email": null, "name": null }, "companies": [ { "id": "", "name": "" } ] } ``` ### Pagination - **Type:**`object` * **`has_more` (required)** `boolean` * **`limit` (required)** `integer` * **`next_cursor` (required)** `string | null` **Example:** ```json { "next_cursor": null, "has_more": true, "limit": 1 } ``` ### ResponseMeta - **Type:**`object` * **`request_id` (required)** `string` * **`pagination`** `object` - **`has_more` (required)** `boolean` - **`limit` (required)** `integer` - **`next_cursor` (required)** `string | null` **Example:** ```json { "request_id": "550e8400-e29b-41d4-a716-446655440000", "pagination": { "next_cursor": null, "has_more": true, "limit": 1 } } ``` ### ProblemDetail - **Type:**`object` Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` **Example:** ```json { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" } ``` ### ErrorEnvelope - **Type:**`object` * **`error` (required)** `object` — Detalhe de problema RFC 7807. Campos extras podem estar presentes conforme o código de erro. - **`code` (required)** `string` - **`detail` (required)** `string` - **`instance` (required)** `string` - **`status` (required)** `integer` - **`title` (required)** `string` * **`meta` (required)** `object` - **`request_id` (required)** `string` **Example:** ```json { "error": { "code": "rate_limited", "title": "", "status": 1, "detail": "", "instance": "" }, "meta": { "request_id": "" } } ``` ### LoginRequest - **Type:**`object` * **`email` (required)** `string`, format: `email` * **`password` (required)** `string` **Example:** ```json { "email": "", "password": "" } ``` ### RefreshRequest - **Type:**`object` * **`refresh_token` (required)** `string` **Example:** ```json { "refresh_token": "" } ``` ### GoogleStartRequest - **Type:**`object` * **`intent`** `string`, possible values: `"login", "internal"` **Example:** ```json { "intent": "login" } ``` ### GooglePollRequest - **Type:**`object` * **`login_id` (required)** `string` * **`poll_token` (required)** `string` — O \`poll\_token\` retornado por \`/v1/auth/google/start\`. **Example:** ```json { "login_id": "", "poll_token": "" } ``` ### Dataset - **Type:**`object` * **`description` (required)** `string` * **`dimensions` (required)** `array` **Items:** `string` * **`grouping_field` (required)** `string`, possible values: `"levels", "breakdowns", "breakdown", "none"` * **`ignores_metric_selection` (required)** `boolean` — True quando o dataset sempre devolve TODAS as métricas, mesmo que \`metrics\` peça um subconjunto — o motor de query a montante não sabe servir seleção parcial aqui. * **`metrics` (required)** `array` **Items:** `string` * **`name` (required)** `string` * **`pagination_only` (required)** `boolean` — True quando o dataset SÓ é servido paginado — sem \`limit\`/\`cursor\` o request é recusado com 422 em vez de devolver um resultado truncado. * **`requires_group_by` (required)** `boolean` — True quando \`group\_by\` é obrigatório — sem pelo menos uma dimensão o request é recusado com 422. Datasets sem dimensão nenhuma nunca aceitam \`group\_by\`. * **`storage` (required)** `string`, possible values: `"postgres", "clickhouse"` * **`supports_attribution` (required)** `boolean` * **`supports_filtering` (required)** `boolean` * **`supports_pagination` (required)** `boolean` — True quando \`POST /v1/query\` aceita \`limit\`/\`cursor\` para este dataset. * **`extra_options`** `array` **Items:** `string` * **`extra_options_help`** `object` — O que cada \`extra\_options\` aceita — tipo, valores válidos e default. **Example:** ```json { "name": "", "description": "", "storage": "postgres", "grouping_field": "levels", "dimensions": [ "" ], "metrics": [ "" ], "supports_attribution": true, "supports_filtering": true, "supports_pagination": true, "pagination_only": true, "requires_group_by": true, "ignores_metric_selection": true, "extra_options": [ "" ], "extra_options_help": { "additionalProperty": "" } } ``` ### QueryResult - **Type:**`object` * **`attribution` (required)** `string | null` * **`dataset` (required)** `string` * **`date_end` (required)** `string` * **`date_start` (required)** `string` * **`group_by` (required)** `array` **Items:** `string` * **`metrics` (required)** `array` — Metrics retornados. \`null\` quando \`metrics\` foi omitido do request — o conjunto padrão do dataset foi usado; inspecione \`result\` para ver as colunas presentes. **Items:** `string` * **`result`** `object` — Resultado bruto do dataset — a estrutura exata que os dashboards do Solomon consomem. No modo paginado (\`limit\`/\`cursor\`), em vez disso vem \`{ rows: \[...] }\` com uma linha plana por pedido e as métricas como colunas; a página seguinte é obtida re-enviando o request com \`cursor = meta.pagination.next\_cursor\`. **Example:** ```json { "dataset": "", "date_start": "", "date_end": "", "group_by": [ "" ], "metrics": [ "" ], "attribution": null, "result": null } ``` ### QueryRequest - **Type:**`object` * **`dataset` (required)** `string`, possible values: `"marketing_per_ad", "marketing_per_channel", "attribution_metrics", "general_attribution_metrics", "revenue", "orders_metrics", "order_attribution", "product_metrics", "clients_cohort", "influencer_metrics", "fixed_influencer_cost", "sessions_metrics", "funnel_metrics", "pages_sessions_metrics", "products_sessions_metrics", "payments_cost", "daily_product_cost", "daily_meta_tax_cost", "additional_cost", "additional_revenue"` — Nome do dataset. Veja \`GET /v1/datasets\`. * **`date_end` (required)** `string` — Fim do range (inclusive). O range completo é limitado a 366 dias. * **`date_start` (required)** `string` — Início do range (inclusive). O range completo é limitado a 366 dias. * **`attribution`** `string`, possible values: `"paid_last_click", "paid_first_click", "last_click", "linear", "total_impact"` — Model de attribution — aplica-se apenas a datasets onde \`supports\_attribution\` é true. O padrão é \`paid\_last\_click\` quando omitido. * **`cursor`** `string` — Cursor opaco devolvido em \`meta.pagination.next\_cursor\` — envie-o de volta (com os MESMOS dataset/datas/metrics) para buscar a próxima página. Implica o modo paginado. * **`filters`** `object` — Filtros de igualdade dimensão → valor. Apenas quando \`supports\_filtering\` é true. * **`group_by`** `array` — Dimensões para agrupar — subconjunto das \`dimensions\` do dataset. **Items:** `string` * **`limit`** `integer` — Ativa o modo paginado (datasets com \`supports\_pagination: true\`). Máximo de linhas por página (1–1000). No modo paginado o \`result\` traz \`rows\` planas (uma por pedido) e \`meta.pagination\` traz \`next\_cursor\`/\`has\_more\`. * **`metrics`** `array` — Metrics a retornar — subconjunto dos \`metrics\` do dataset. Omita para usar o conjunto padrão. **Items:** `string` * **`options`** `object` — Opções extras específicas do dataset, listadas em \`extra\_options\` no catálogo. Chave que não estiver na lista é recusada com 422 — um \`include\_touchpoint\` no singular vira erro explícito, não um 200 sem o campo que você pediu. **Example:** ```json { "dataset": "marketing_per_ad", "date_start": "2026-05-01", "date_end": "2026-05-19", "group_by": [ "campaign", "ad" ], "metrics": [ "spend", "revenue", "purchases" ], "attribution": "paid_last_click", "filters": { "source": "facebook" }, "options": {}, "limit": 500, "cursor": "" } ``` ### TaxesResult - **Type:**`object` * **`approved_revenue` (required)** `number` — Receita aprovada do período (base dos percentuais). * **`attribution` (required)** `string` * **`checkout_fee` (required)** `number` — Custo da plataforma de checkout no período. * **`date_end` (required)** `string` * **`date_start` (required)** `string` * **`gateway_fee` (required)** `number` — Custo de gateway de pagamento no período. * **`imposto` (required)** `number` — Imposto geral configurável da empresa, calculado pela regra/alíquota vigente em cada dia do período. 0 quando não configurado. * **`meta_tax_cost` (required)** `number` — Imposto sobre publicidade da Meta no período. * **`tax_rule` (required)** `object | null` — Regra/alíquota (e períodos de vigência) aplicada. \`null\` se imposto não configurado. - **`aliquote_rate`** `number` - **`calculation_rule`** `string` - **`periods`** `array` **Items:** - **`aliquote_rate`** `number` - **`calculation_rule`** `string` - **`end_date`** `string` - **`start_date`** `string` * **`taxes_and_fees_revenue_pct` (required)** `number` — taxes\_and\_fees\_total como % da receita aprovada. * **`taxes_and_fees_total` (required)** `number` — Soma de imposto + meta\_tax + gateway + checkout. **Example:** ```json { "date_start": "", "date_end": "", "attribution": "", "approved_revenue": 1, "imposto": 1, "meta_tax_cost": 1, "gateway_fee": 1, "checkout_fee": 1, "taxes_and_fees_total": 1, "taxes_and_fees_revenue_pct": 1, "tax_rule": { "calculation_rule": "", "aliquote_rate": 1, "periods": [ { "calculation_rule": "", "aliquote_rate": 1, "start_date": "", "end_date": "" } ] } } ```