> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Places

> Busca externa que alimenta a criação de Points com nome e coordenadas.

Um **Place** é o resultado de uma busca externa de locais. Ele é usado para descoberta/geocodificação e alimenta a criação de [Points](/domain/operations/points) no catálogo global.

## Operações

### Autocomplete

| Campo          | Descrição                                       |
| -------------- | ----------------------------------------------- |
| `query`        | Termo digitado pelo usuário                     |
| `sessionToken` | Token opcional para agrupar uma sessão de busca |

Retorna sugestões para o termo digitado:

| Campo da sugestão | Descrição                                            |
| ----------------- | ---------------------------------------------------- |
| `placeId`         | Identificador do Google usado para resolver detalhes |
| `text`            | Texto completo da sugestão                           |
| `name`            | Nome principal                                       |
| `description`     | Texto secundário/endereço                            |

### Detalhes do local

| Campo          | Descrição                                           |
| -------------- | --------------------------------------------------- |
| `placeId`      | Identificador do local escolhido                    |
| `sessionToken` | Mesmo token usado no autocomplete, quando informado |

Resolve um `placeId` no formato pronto para semear um Point:

| Campo         | Origem                                                                            |
| ------------- | --------------------------------------------------------------------------------- |
| `placeId`     | eco do identificador                                                              |
| `name`        | `displayName` → `shortFormattedAddress` → `formattedAddress` (primeiro não-vazio) |
| `description` | `formattedAddress` quando presente e diferente de `name`; senão `null`            |
| `lat` / `lng` | coordenadas do local (obrigatórias no provedor)                                   |

## Fluxo de cadastro de Point

```mermaid theme={null}
sequenceDiagram
    participant Op as Operador BackOffice
    participant O as DEVMOB
    participant G as Provedor de lugares
    participant PT as Point

    Op->>O: Busca sugestões
    O->>G: Consulta autocomplete
    G-->>Op: sugestões (placeId, name, description)
    Op->>O: Escolhe placeId
    O->>G: Consulta detalhes
    G-->>Op: { name, description, lat, lng }
    Op->>PT: Cria Point
```

<Tip>
  O `sessionToken` agrupa autocomplete e detalhe final em uma única sessão de cobrança do provider — informe o mesmo token durante todo o fluxo de seleção de um local.
</Tip>

## Capacidade

Place é uma capacidade de BackOffice, usada na gestão do catálogo global de Points:

| Ação                        | Acesso                    |
| --------------------------- | ------------------------- |
| Autocomplete de locais      | BackOffice — `read:point` |
| Detalhes do local escolhido | BackOffice — `read:point` |

<Note>
  A busca usa região `br` e idioma `pt-BR`. O Point resultante é salvo quando o operador cria o ponto.
</Note>