> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Escolhendo um endpoint de expansão
> Um guia de tarefa para endpoint da API de Expansão — qual endpoint chamar para descoberta, detalhe de empresa, o feed de sinais, comparação, mapas e valores de referência.
A API de Expansão é um pequeno conjunto de endpoints, cada um respondendo a uma pergunta diferente sobre como as empresas crescem em novos mercados. Este guia mapeia **o que você quer fazer** para **qual endpoint chamar**, para que você nunca precise adivinhar.
Novo nos conceitos (estágios, sinais, momentum, atualidade)? Comece com [O que são sinais de expansão?](/pt/knowledge-base/concepts/expansion-signals) — este guia parte do princípio de que você já os conhece e foca na seleção de endpoints.
## Escolha por tarefa
| Você quer… | Chame |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| **Encontrar empresas** que estão se expandindo para um mercado (por filtros ou uma consulta em linguagem natural) | [Expansion Search](/pt/api-reference/endpoint/expansions/market_lookup) |
| Ver **KPIs e fluxos em nível de mercado** (contagens por estágio, principais corredores) | [Expansion Overview](/pt/api-reference/endpoint/expansions/dashboard) |
| Obter o **status de uma empresa em um mercado** — estágio, presença, histórico e os sinais por trás dele | [Company Expansion Detail](/pt/api-reference/endpoint/expansions/company_lookup) |
| Obter o **feed enriquecido e com janela de tempo** dos eventos de sinal de uma empresa | [Company Signal Events](/pt/api-reference/endpoint/expansions/company_pulse_events) |
| **Comparar** a expansão de várias empresas lado a lado, a partir de uma empresa-alvo | [Compare Company Expansions](/pt/api-reference/endpoint/expansions/company_compare) |
| Obter **métricas de comparação prontas para exibição** (mercados, momentum, pontuação de expansão) para um conjunto de empresas que você já tem — por domínio, URL do LinkedIn ou id | [Batch Company Expansion Summaries](/pt/api-reference/endpoint/expansions/company_summaries) |
| Plotar **pontos ranqueados de empresa/mercado** em um mapa ou heatmap | [Expansion Rankings](/pt/api-reference/endpoint/expansions/company_markers) |
| Ler as **linhas brutas de sinal** por trás de um estágio — auditar as evidências ou construir sua própria pontuação | [Expansion Signal Search](/pt/api-reference/endpoint/expansions/signal_search) |
| Resolver **valores de filtro e enum** (estágios, tipos de sinal, atualidade…) | [Expansion Reference](/pt/api-reference/endpoint/expansions/types) |
## Os endpoints em resumo
O endpoint de descoberta. Filtre empresas por estágio de expansão, atualidade, mercado e o conjunto completo de dados firmográficos — ou passe uma `query` em linguagem natural. Lista paginada de empresas.
Agregados em nível de mercado: contagens por estágio, principais fluxos transfronteiriços, atividade de empresas monitoradas. Sem paginação — um snapshot de dashboard.
Uma empresa em um mercado: estágio atual, pontuação, presença, histórico de transições e os sinais de suporte. O snapshot por mercado.
O feed enriquecido e paginado dos eventos de sinal de uma empresa, entre tipos de sinal e uma janela de datas. O detalhamento de atividade.
Várias empresas lado a lado em uma única chamada, com séries semanais de sinais e seleção opcional de pares. Construído para grades de comparação.
Qualquer combinação de domain\_search\_id, domínio ou URL do LinkedIn, resolvida e retornada com os mesmos dados do Compare, além de um bloco de resumo calculado — sem empresa-alvo, sem seleção de pares.
Uma lista leve, ranqueada por pontuação, de pares empresa/mercado — campos mínimos, sem paginação — para renderização rápida de mapas e heatmaps.
Consulte as próprias linhas de sinal — tipo, subtipo, força, polaridade, evento datado, fonte e URL de evidência — entre empresas e mercados. Paginado, filtrável, sem agregação por empresa.
## "Detail" vs "Signal Events" — qual usar?
Este é o ponto de maior confusão, porque **ambos envolvem sinais**. A diferença é *snapshot vs. feed*:
| | Company Expansion Detail | Company Signal Events |
| -------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Escopo** | uma empresa × **um mercado** | uma empresa, em **todos os seus mercados estrangeiros** |
| **Mercados** | um **único mercado** via `country_code`, ou a empresa inteira de uma vez via `is_all_markets` | **todos os mercados estrangeiros** por padrão (mercado de origem excluído); restrinja a mercados específicos com `country_codes` (array) |
| **Retorna** | estágio, pontuação, presença, histórico **+ sinais de suporte** | **eventos de sinal enriquecidos** (URLs de evidência, listas de contratação, rótulos) |
| **Tempo** | posição atual | uma **janela de datas** que você escolhe (`window_days` — padrão 90 — ou `transitioned_dates`) |
| **Formato** | um objeto de snapshot estruturado | um feed de eventos paginado ("carregar mais") |
| **Use quando** | "Qual é o status desta empresa em **um** mercado, e por quê?" | "Mostre o fluxo completo em **todos** os mercados que impulsionam a expansão desta empresa" |
**A maioria das integrações só precisa de Company Expansion Detail** — ele já retorna os sinais por trás do estágio de uma empresa em um mercado. Recorra a **Company Signal Events** quando você quiser especificamente o fluxo de eventos rico, filtrável e com janela de tempo (por exemplo, construir uma UI de linha do tempo de atividade).
## "Compare" vs "Summaries" — qual usar?
Ambos retornam os mesmos dados de expansão por empresa, lado a lado. A diferença está nos *identificadores e no enquadramento*:
| | Compare Company Expansions | Batch Company Expansion Summaries |
| ----------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Entrada** | qualquer combinação de `domain_search_id`, `domain` ou `linkedin_url` | qualquer combinação de `domain_search_id`, `domain` ou `linkedin_url` |
| **Seleção de pares** | opcional, via `seed_target` | nenhuma — cada empresa é independente |
| **Agregação calculada** | nenhuma (calcule mercados/momentum/pontuação você mesmo) | bloco `summary` incluído por empresa (mercados ativos/novos, momentum, pontuação de expansão, mix de estágios) |
| **Use quando** | você já tem ids resolvidos e quer selecionar pares comparáveis para um alvo | você recebeu empresas por domínio ou URL do LinkedIn e quer métricas de comparação prontas para exibição em uma única chamada |
**Construindo uma grade de benchmarking de concorrentes em torno de uma empresa-alvo?** Use **Compare** com `seed_target` para selecionar pares automaticamente. **Já tem um conjunto de empresas** (uma watchlist, uma importação de CRM, uma lista de domínios) **e só quer os números?** Use **Batch Company Expansion Summaries** — isso evita que você reimplemente o cálculo de momentum/pontuação no lado do cliente.
## Um fluxo de trabalho típico
Chame **Expansion Search** com seus filtros (ou uma `query` em linguagem natural) para obter as empresas que estão se expandindo para o seu mercado-alvo. Defina `is_explain_match: true` para resumos de IA sobre "por que corresponde".
Pegue um `domain_search_id` dos resultados e chame **Company Expansion Detail** para a leitura completa em um mercado — estágio, presença, histórico e sinais.
Para o fluxo de eventos rico e com janela de tempo, chame **Company Signal Events** com os tipos de sinal e o intervalo de datas que interessam.
Use **Compare Company Expansions** para uma grade lado a lado a partir de uma empresa-alvo, **Batch Company Expansion Summaries** quando você já tiver um conjunto de empresas e quiser métricas prontas, ou **Expansion Rankings** para plotar pontos ranqueados em um mapa.
## Filtros compartilhados
Os endpoints de descoberta (**Expansion Search**, **Expansion Overview**, **Expansion Rankings**) aceitam o mesmo vocabulário de filtros — filtros de expansão (estágio, momentum, atualidade, escopo, tipos de sinal), o par de geografia direcionada (`froms` / `tos`) **e** o conjunto completo de dados firmográficos da empresa (setor, tecnologias, tamanho de funcionários, receita, listas salvas). Aprenda os filtros uma vez em [Visão geral de filtros](/pt/developer-guides/filters/overview); os valores válidos estão em [Expansion Reference](/pt/api-reference/endpoint/expansions/types) e no catálogo [Como funcionam os sinais de expansão](/pt/knowledge-base/concepts/how-expansion-signals-work).
Autenticação, suas primeiras chamadas, paginação e leitura de pontuações.
Um passo a passo completo de mercado até sinal.