# Ambiente (/docs/comecar/ambiente)

> A variável AMBIENTE é a única configuração do SDK. Ela decide para qual endereço cada serviço aponta.

O termo_core lê **uma única variável**: `AMBIENTE`. Os endereços de cada serviço ficam numa tabela dentro do próprio pacote (`packages/rust/base/servicos.rs`, copiada para o TypeScript), nunca em `.env`.

| `AMBIENTE` | Para onde cada serviço aponta |
| --- | --- |
| `LOCALHOST` | o servidor local (`http://localhost:51xx1`) ou o sandbox, escolhido por serviço |
| `SANDBOX` | `https://sandbox-api-<serviço>.termotubos.com.br` |
| `PRODUCTION` | `https://api-<serviço>.termotubos.com.br` |

Sem `AMBIENTE`, ou com um valor inválido, o processo para com a mensagem `defina a variável AMBIENTE com LOCALHOST, SANDBOX ou PRODUCTION`. **Nunca cai em PRODUCTION por engano.**

<Callout title="Projetos que consomem o termo_core">
Rodam sempre com `AMBIENTE=SANDBOX` em desenvolvimento, com o segredo do próprio app gerado no TermoAuth.
</Callout>

## No backend [#no-backend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```bash
AMBIENTE=SANDBOX node servidor.js
```

O valor é lido uma vez de `process.env.AMBIENTE` (Node, Bun e Deno com compatibilidade) e fica fixo no processo.

</Tab>
<Tab value="Rust">

```bash
AMBIENTE=SANDBOX cargo run
```

O valor é lido uma vez, na primeira chamada. Variável ausente ou inválida encerra o processo com `panic!` e a mensagem acima.

</Tab>
</Tabs>

## No navegador [#no-navegador]

Não existe `process.env` no navegador. Fixe o ambiente **uma vez**, antes da primeira chamada:

```ts title="main.ts"
import { definir_ambiente_atual_pelo_codigo } from "termo_core";

definir_ambiente_atual_pelo_codigo(import.meta.env.VITE_AMBIENTE); // "SANDBOX"
```

Depois de fixado, tentar trocar para outro ambiente lança `termo_core: o ambiente já está fixado em SANDBOX`.

## Apontar um serviço para outro endereço [#apontar-um-serviço-para-outro-endereço]

Só para testes ou ferramentas: troca o endereço de um serviço neste processo (ou nesta aba), por cima da tabela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { servicos, substituir_endereco_do_servico_neste_processo } from "termo_core";

substituir_endereco_do_servico_neste_processo(servicos.TERMO_AUTH, "http://localhost:9999");
```

</Tab>
<Tab value="Rust">

```rust
termo_core::substituir_endereco_do_servico_neste_processo(&termo_core::servicos::TERMO_AUTH, "http://localhost:9999");
```

</Tab>
</Tabs>

A referência completa de `ambiente_atual`, `definir_ambiente_atual_pelo_codigo`, `endereco_do_servico_no_ambiente_atual` e afins está em [Funções da base](/docs/comecar/funcoes_da_base#ambiente).


# Arquitetura (/docs/comecar/arquitetura)

> Como o termo_core é gerado dos contratos OpenAPI e como esta documentação acompanha o código.

```text
TermoCore/
├── openapi/              cópia versionada dos contratos (<serviço>.json e webhook_eventos.json)
├── gerador/              binário Rust que baixa os contratos do SANDBOX e gera os dois pacotes
├── packages/
│   ├── rust/             crate termo_core (crates.io)
│   └── typescript/       pacote termo_core (npm)
└── docs/                 esta documentação (Fumadocs)
```

## Do contrato à função [#do-contrato-à-função]

<Steps>
<Step>

### Sincronizar [#sincronizar]

`cargo run -p gerador -- sincronizar` baixa o `openapi.json` de cada serviço e o catálogo de eventos (`GET /esquemas.json` do TermoWebhook), sempre do **SANDBOX**, para `openapi/`. O TermoCore nunca acessa o banco de outro serviço.

</Step>
<Step>

### Gerar [#gerar]

`cargo run -p gerador -- gerar` lê os contratos uma vez (`leitura_do_openapi.rs`) e escreve `rotas` e `tipos` de cada serviço em Rust e em TypeScript, com os mesmos nomes.

</Step>
<Step>

### Publicar [#publicar]

O workflow `publicar-termo-core.yml` publica no crates.io e no npm quando o código de cada pacote muda, subindo só o último número da versão.

</Step>
<Step>

### Documentar [#documentar]

`bun scripts/gerar_paginas_dos_sdks.ts` (roda sozinho antes do `dev` e do `build` desta documentação) lê o código já gerado em `packages/` e os contratos em `openapi/` e escreve uma página por entidade em `content/docs/servicos/` e o catálogo de eventos. A documentação nunca fica atrás do pacote.

</Step>
</Steps>

## O que é gerado e o que é feito à mão [#o-que-é-gerado-e-o-que-é-feito-à-mão]

| Parte | Origem |
| --- | --- |
| `<serviço>/rotas` e `<serviço>/tipos` (Rust e TypeScript) | gerado do `openapi.json` |
| `webhook/eventos` (contratos) | gerado do `webhook_eventos.json` |
| `base/` (ambiente, credencial, erro, requisição, token do aplicativo) | feito à mão |
| `webhook/` publicar, receber, fila, assinatura (só Rust) | feito à mão |
| `docs/content/docs/servicos/` e `eventos/catalogo/` | gerado pelo script da documentação |
| demais páginas desta documentação | feitas à mão |


# Convenções (/docs/comecar/convencoes)

> Como os nomes das funções são formados, a ordem dos argumentos e o que cada função devolve.

## Nome das funções [#nome-das-funções]

Cada rota da API vira uma função cujo nome é a **ação primeiro e o recurso no final**, em snake_case, igual nas duas linguagens.

| `operationId` no OpenAPI | Tag | Função |
| --- | --- | --- |
| `usuarioBuscarPeloId` | `usuario` | `buscar_pelo_id_usuario` |
| `chaveDeAssinaturaBuscarPaginador` | `chave_de_assinatura` | `buscar_paginador_chave_de_assinatura` |
| `arquivoCriar` | `arquivo` | `criar_arquivo` |

Os verbos se repetem em todos os serviços: `buscar_paginador_*` (lista com paginação), `buscar_auto_complete_*` (lista curta para seleção), `buscar_pelo_filtro_*` (tudo que casa com o filtro), `buscar_pelo_id_*`, `criar_*`, `atualizar_pelo_id_*` e `deletar_pelo_id_*`.

A **entidade** de cada página desta documentação é a tag da rota no OpenAPI.

## Ordem dos argumentos [#ordem-dos-argumentos]

1. `credencial_de_acesso`: só nas rotas que exigem login.
2. Parâmetros do caminho (`id`, `cnpj`...), na ordem em que aparecem na URL.
3. `parametros`: consulta e cabeçalho, num objeto (`ParametrosDe<Função>`).
4. O corpo: `corpo_da_requisicao` (JSON) ou `formulario` (upload `multipart`).
5. Só no TypeScript: `opcoes_da_chamada` (`sinal_de_cancelamento`, `tempo_limite_em_milissegundos`, padrão 30 s).

## Tipos e retorno [#tipos-e-retorno]

- Tipos em PascalCase, com o **mesmo nome** nos dois pacotes. Nas `interface` do TypeScript os campos têm o nome exato do JSON.
- Datas, UUIDs e decimais chegam como `string` no TypeScript; no Rust, como `chrono::DateTime<Utc>`, `uuid::Uuid` e afins.
- Rota sem corpo na resposta devolve `Promise<void>` / `Result<(), _>`.
- Rota que devolve arquivo devolve `Promise<Uint8Array>` / `Result<Vec<u8>, _>`.
- Upload `multipart` recebe um `FormData` no TypeScript e um `reqwest::multipart::Form` (reexportado em `termo_core::base::multipart`) no Rust.

## Nomes descritivos [#nomes-descritivos]

Todo o código usa nomes completos, mesmo longos: `guardar_evento_para_publicar_na_mesma_transacao`, `servico_nao_encontrou_o_registro`. Isso vale também para quem usa o SDK e facilita a leitura por pessoas e por IA.


# Credencial e token do aplicativo (/docs/comecar/credencial)

> Como o SDK se autentica. Token do usuário logado para o painel, token do aplicativo para a conversa entre back-ends.

Toda função de rota que exige login recebe uma `CredencialDeAcesso` como **primeiro argumento**. Ela vira o cabeçalho `Authorization: Bearer <token>`. Rotas públicas não pedem credencial.

Existem dois jeitos de criar uma credencial:

| Quem chama | Como criar | Onde usar |
| --- | --- | --- |
| Uma pessoa logada | `CredencialDeAcesso.token_do_usuario_logado(token)` | rotas de painel, em nome do usuário |
| O próprio app (back-end) | `token_do_aplicativo()` | APIs de sistema: gateway do TermoAI, arquivos do TermoBucket, publicação no TermoWebhook |

## Token do usuário logado [#token-do-usuário-logado]

O JWT que o TermoAuth entregou para o usuário, com ou sem o prefixo `Bearer `.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { CredencialDeAcesso } from "termo_core";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(request.headers.authorization);
```

</Tab>
<Tab value="Rust">

```rust
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);
```

</Tab>
</Tabs>

A credencial não vaza em log: no TypeScript, `JSON.stringify` mostra `CredencialDeAcesso(***)`.

## Token do aplicativo (conversa entre back-ends) [#token-do-aplicativo-conversa-entre-back-ends]

Só no back-end. O app troca o **segredo do app**, gerado no TermoAuth, por um JWT curto em `POST {TermoAuth}/token_de_app`. O token fica em cache no processo e só é pedido de novo quando falta menos de **60 s** para `expira_em`. Não existe tarefa em background.

<Steps>
<Step>

### Entregue o segredo ao SDK [#entregue-o-segredo-ao-sdk]

Os apps guardam o segredo cifrado no próprio banco (tela `/painel/configuracoes/provedores`, só master) e o entregam ao subir e a cada gravação. A variável `SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH` fica só como alternativa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { definir_segredo_do_app } from "termo_core";

definir_segredo_do_app(segredo_guardado_no_banco);
```

</Tab>
<Tab value="Rust">

```rust
termo_core::definir_segredo_do_app(Some(segredo_guardado_no_banco));
```

</Tab>
</Tabs>

</Step>
<Step>

### Peça a credencial [#peça-a-credencial]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { token_do_aplicativo } from "termo_core";

const credencial_de_acesso = await token_do_aplicativo();
```

</Tab>
<Tab value="Rust">

```rust
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_aplicativo().await?;
```

</Tab>
</Tabs>

</Step>
</Steps>

<Callout type="error" title="Nunca no navegador">
O segredo do app não pode ir para o frontend. Use `token_do_aplicativo()` só em código de servidor.
</Callout>

Sem segredo, `token_do_aplicativo()` devolve `ErroAoChamarServico` do tipo `falha_ao_montar_requisicao` (no Rust, `FalhaAoMontarRequisicao`) pedindo para cadastrá-lo. A fila de eventos do TermoWebhook espera até o segredo ser cadastrado.

## Id do aplicativo [#id-do-aplicativo]

`identificador_do_aplicativo()` devolve o id do próprio app no TermoAuth (o `app` do token de aplicativo). É o mesmo id do app em todos os serviços, inclusive o destino das entregas do TermoWebhook.

Referência completa em [Funções da base](/docs/comecar/funcoes_da_base#credencial-e-token-do-aplicativo).


# Erros (/docs/comecar/erros)

> Toda função de rota falha com ErroAoChamarServico, com o status HTTP e o campo erro da resposta.

Toda falha das funções geradas chega como **`ErroAoChamarServico`**, com o mesmo formato nas duas linguagens.

| Tipo (TypeScript) | Variante (Rust) | Quando acontece |
| --- | --- | --- |
| `falha_ao_montar_requisicao` | `FalhaAoMontarRequisicao` | faltou algo antes de enviar (ex.: segredo do app) |
| `falha_de_conexao_com_o_servico` | `FalhaDeConexaoComOServico` | rede, DNS, tempo limite |
| `servico_respondeu_com_erro` | `ServicoRespondeuComErro` | o serviço respondeu 4xx ou 5xx |
| `resposta_do_servico_em_formato_inesperado` | `RespostaDoServicoEmFormatoInesperado` | a resposta não bate com o contrato |

Campos: `nome_do_servico`, `detalhe`, `status_http`, `mensagem_de_erro` (o campo `erro` do corpo, quando o serviço responde `{ "erro": "..." }`) e `corpo_da_resposta`.

## Métodos [#métodos]

| Método | Devolve |
| --- | --- |
| `status_http_da_resposta()` | o status HTTP, só quando o serviço respondeu com erro |
| `servico_nao_encontrou_o_registro()` | `true` para 404 |
| `vale_tentar_de_novo()` | `true` para falha de conexão, 408, 429 e 5xx |

## Exemplo [#exemplo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { ErroAoChamarServico } from "termo_core";
import { buscar_pelo_id_usuario } from "termo_core/auth";

try {
  const usuario = await buscar_pelo_id_usuario(credencial_de_acesso, id);
} catch (erro) {
  if (erro instanceof ErroAoChamarServico && erro.servico_nao_encontrou_o_registro()) {
    // 404: o usuário não existe
  } else if (erro instanceof ErroAoChamarServico && erro.vale_tentar_de_novo()) {
    // rede ou 5xx: tente mais tarde
  } else {
    throw erro;
  }
}
```

O cancelamento por `sinal_de_cancelamento` chega como o `AbortError` do próprio `fetch`, não como `ErroAoChamarServico`.

</Tab>
<Tab value="Rust">

```rust
use termo_core::ErroAoChamarServico;

match termo_core::auth::buscar_pelo_id_usuario(&credencial_de_acesso, &id).await {
    Ok(usuario) => { /* ... */ }
    Err(erro) if erro.servico_nao_encontrou_o_registro() => { /* 404 */ }
    Err(erro) if erro.vale_tentar_de_novo() => { /* rede ou 5xx */ }
    Err(ErroAoChamarServico::ServicoRespondeuComErro { status_http, mensagem_de_erro, .. }) => {
        eprintln!("{status_http}: {mensagem_de_erro:?}");
    }
    Err(erro) => return Err(erro.into()),
}
```

</Tab>
</Tabs>


# Funções da base (/docs/comecar/funcoes_da_base)

> Referência das funções feitas à mão que todo serviço usa. Ambiente, credencial, token do aplicativo, endereços e erros.

A `base` é a parte do SDK escrita à mão (o resto é gerado dos contratos). Tudo daqui é exportado pela raiz: `import { ... } from "termo_core"` no TypeScript e `termo_core::...` no Rust.

## Ambiente [#ambiente]

### `ambiente_atual` [#ambiente_atual]

Ambiente fixado pelo código ou lido uma única vez da variável `AMBIENTE`. Sem ambiente, lança erro (TypeScript) ou encerra o processo (Rust) com uma mensagem clara.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function ambiente_atual(): Ambiente // "LOCALHOST" | "SANDBOX" | "PRODUCTION"
```

</Tab>
<Tab value="Rust">

```rust
pub fn ambiente_atual() -> Ambiente // Ambiente::Localhost | Sandbox | Production
```

</Tab>
</Tabs>

### `definir_ambiente_atual_pelo_codigo` [#definir_ambiente_atual_pelo_codigo]

Fixa o ambiente sem ler a variável. No navegador é o único jeito. Só vale antes da primeira consulta ao ambiente.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function definir_ambiente_atual_pelo_codigo(ambiente: Ambiente | string): void
```

Lança erro para um nome inválido ou se o ambiente já estiver fixado em outro valor.

</Tab>
<Tab value="Rust">

```rust
pub fn definir_ambiente_atual_pelo_codigo(ambiente: Ambiente) -> Result<(), Ambiente>
```

Devolve `Err(ambiente_ja_fixado)` quando o ambiente já tinha sido fixado.

</Tab>
</Tabs>

### `interpretar_nome_do_ambiente` [#interpretar_nome_do_ambiente]

Converte um texto (sem diferenciar maiúsculas) no ambiente, ou nada quando não existe.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function interpretar_nome_do_ambiente(nome_do_ambiente: string): Ambiente | undefined
const TODOS_OS_AMBIENTES: readonly Ambiente[]
const NOME_DA_VARIAVEL_DO_AMBIENTE = "AMBIENTE"
```

</Tab>
<Tab value="Rust">

```rust
impl Ambiente {
    pub const TODOS_OS_AMBIENTES: [Ambiente; 3];
    pub fn interpretar_nome_do_ambiente(nome_do_ambiente: &str) -> Option<Ambiente>;
    pub fn nome_do_ambiente(&self) -> &'static str;
}
pub const NOME_DA_VARIAVEL_DO_AMBIENTE: &str = "AMBIENTE";
```

</Tab>
</Tabs>

## Endereços dos serviços [#endereços-dos-serviços]

### `endereco_do_servico_no_ambiente_atual` [#endereco_do_servico_no_ambiente_atual]

Endereço da API do serviço no ambiente em que o código está rodando (ou o endereço substituído neste processo).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { endereco_do_servico_no_ambiente_atual, servicos } from "termo_core";

function endereco_do_servico_no_ambiente_atual(servico: ServicoTermotubos): string

endereco_do_servico_no_ambiente_atual(servicos.TERMO_AUTH); // "https://sandbox-api-auth.termotubos.com.br"
```

</Tab>
<Tab value="Rust">

```rust
pub fn endereco_do_servico_no_ambiente_atual(servico: &ServicoTermotubos) -> String

termo_core::endereco_do_servico_no_ambiente_atual(&termo_core::servicos::TERMO_AUTH);
```

</Tab>
</Tabs>

### `endereco_no_ambiente` [#endereco_no_ambiente]

Endereço do serviço num ambiente qualquer, sem olhar o ambiente atual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function endereco_no_ambiente(servico: ServicoTermotubos, ambiente: Ambiente): string
```

</Tab>
<Tab value="Rust">

```rust
impl ServicoTermotubos {
    pub fn endereco_no_ambiente(&self, ambiente: Ambiente) -> &'static str;
}
```

</Tab>
</Tabs>

### `substituir_endereco_do_servico_neste_processo` [#substituir_endereco_do_servico_neste_processo]

Troca o endereço de um serviço só neste processo, por cima da tabela por ambiente (ex.: um servidor de teste). O normal é não precisar chamar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function substituir_endereco_do_servico_neste_processo(servico: ServicoTermotubos, novo_endereco: string): void
```

</Tab>
<Tab value="Rust">

```rust
pub fn substituir_endereco_do_servico_neste_processo(servico: &ServicoTermotubos, novo_endereco: impl Into<String>)
```

</Tab>
</Tabs>

### `servicos` e `ServicoTermotubos` [#servicos-e-servicotermotubos]

A tabela de endereços. Uma constante por serviço (`TERMO_AUTH`, `TERMO_BUCKET`...) e `TODOS_OS_SERVICOS`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
interface ServicoTermotubos {
  readonly nome_do_servico: string;          // "TermoAuth"
  readonly nome_do_modulo: string;           // "auth"
  readonly endereco_no_localhost: string | null; // null = usa o sandbox
  readonly endereco_no_sandbox: string;
  readonly endereco_em_production: string;
}
```

</Tab>
<Tab value="Rust">

```rust
pub struct ServicoTermotubos {
    pub nome_do_servico: &'static str,
    pub nome_do_modulo: &'static str,
    pub endereco_no_localhost: EnderecoNoLocalhost, // ServidorLocal(&str) | MesmoEnderecoDoSandbox
    pub endereco_no_sandbox: &'static str,
    pub endereco_em_production: &'static str,
}
```

</Tab>
</Tabs>

## Credencial e token do aplicativo [#credencial-e-token-do-aplicativo]

### `CredencialDeAcesso.token_do_usuario_logado` [#credencialdeacessotoken_do_usuario_logado]

Credencial a partir do JWT do usuário, com ou sem `Bearer `.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
class CredencialDeAcesso {
  static token_do_usuario_logado(token_do_usuario: string): CredencialDeAcesso;
  token_bearer(): string;
}
```

</Tab>
<Tab value="Rust">

```rust
impl CredencialDeAcesso {
    pub fn token_do_usuario_logado(token_do_usuario: impl Into<String>) -> CredencialDeAcesso;
    pub fn token_bearer(&self) -> &str;
}
```

</Tab>
</Tabs>

### `token_do_aplicativo` [#token_do_aplicativo]

JWT curto do próprio app, trocado no TermoAuth pelo segredo do app. Em cache, renovado quando falta menos de 60 s para expirar. Só back-end.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function token_do_aplicativo(): Promise<CredencialDeAcesso>
```

</Tab>
<Tab value="Rust">

```rust
impl CredencialDeAcesso {
    pub async fn token_do_aplicativo() -> Result<CredencialDeAcesso, ErroAoChamarServico>;
}
```

</Tab>
</Tabs>

### `definir_segredo_do_app` [#definir_segredo_do_app]

Define o segredo do app neste processo (ex.: lido do banco). Tem prioridade sobre a variável `SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH`; vazio volta a usar a variável. Trocar o segredo descarta o token em cache.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function definir_segredo_do_app(segredo: string | null | undefined): void
```

</Tab>
<Tab value="Rust">

```rust
pub fn definir_segredo_do_app(segredo: Option<String>)
```

</Tab>
</Tabs>

### `segredo_do_app_configurado` [#segredo_do_app_configurado]

`true` quando há segredo definido pelo código ou pela variável de ambiente.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function segredo_do_app_configurado(): boolean
const VARIAVEL_DO_SEGREDO_DO_APP = "SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH"
```

</Tab>
<Tab value="Rust">

```rust
pub fn segredo_do_app_configurado() -> bool
```

</Tab>
</Tabs>

### `identificador_do_aplicativo` [#identificador_do_aplicativo]

Id do próprio app no TermoAuth (o `app` devolvido por `POST /token_de_app`), o mesmo id do app em todos os serviços.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function identificador_do_aplicativo(): Promise<string>
```

</Tab>
<Tab value="Rust">

```rust
pub async fn identificador_do_aplicativo() -> Result<String, ErroAoChamarServico>
```

</Tab>
</Tabs>

## Erros [#erros]

### `ErroAoChamarServico` [#erroaochamarservico]

O erro de todas as funções de rota. Detalhes e exemplos em [Erros](/docs/comecar/erros).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
class ErroAoChamarServico extends Error {
  readonly tipo: TipoDoErroAoChamarServico;
  readonly nome_do_servico: string;
  readonly detalhe: string | undefined;
  readonly status_http: number | undefined;
  readonly mensagem_de_erro: string | undefined;
  readonly corpo_da_resposta: string | undefined;

  status_http_da_resposta(): number | undefined;
  servico_nao_encontrou_o_registro(): boolean;
  vale_tentar_de_novo(): boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
pub enum ErroAoChamarServico {
    FalhaAoMontarRequisicao { nome_do_servico: &'static str, detalhe: String },
    FalhaDeConexaoComOServico { nome_do_servico: &'static str, detalhe: String },
    ServicoRespondeuComErro { nome_do_servico: &'static str, status_http: u16, mensagem_de_erro: Option<String>, corpo_da_resposta: String },
    RespostaDoServicoEmFormatoInesperado { nome_do_servico: &'static str, detalhe: String },
}

impl ErroAoChamarServico {
    pub fn status_http_da_resposta(&self) -> Option<u16>;
    pub fn servico_nao_encontrou_o_registro(&self) -> bool;
    pub fn vale_tentar_de_novo(&self) -> bool;
}
```

</Tab>
</Tabs>

## Requisição [#requisição]

Usadas pelo código gerado. Você só precisa delas para chamar uma rota que ainda não está no contrato.

### `chamar_servico` / `RequisicaoAoServico` [#chamar_servico--requisicaoaoservico]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function chamar_servico<Resposta>(requisicao: RequisicaoAoServico, opcoes_da_chamada?: OpcoesDaChamada): Promise<Resposta>

interface RequisicaoAoServico {
  servico: ServicoTermotubos;
  metodo_http: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  caminho_da_rota: string;
  credencial_de_acesso?: CredencialDeAcesso;
  parametros_de_consulta?: object;
  cabecalhos?: object;
  corpo_json?: unknown;
  formulario?: FormData;
  formato_da_resposta: "json" | "sem_conteudo" | "bytes";
}

interface OpcoesDaChamada {
  sinal_de_cancelamento?: AbortSignal;
  tempo_limite_em_milissegundos?: number; // padrão 30_000
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::base::{Method, RequisicaoAoServico};

let resposta: serde_json::Value = RequisicaoAoServico::nova_requisicao(&termo_core::servicos::TERMO_AUTH, Method::GET, "/rota")
    .com_credencial_de_acesso(&credencial_de_acesso)
    .com_parametros_de_consulta(&parametros)
    .com_cabecalho_opcional("x-cabecalho", Some("valor"))
    .com_corpo_json(&corpo)               // ou .com_corpo_multipart(formulario)
    .enviar_e_ler_resposta_json()         // ou enviar_e_ignorar_corpo_da_resposta / enviar_e_ler_resposta_em_bytes
    .await?;
```

</Tab>
</Tabs>

### `codificar_parametro_de_caminho` [#codificar_parametro_de_caminho]

Codifica um valor para entrar com segurança num segmento do caminho (`/usuario/{id}`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function codificar_parametro_de_caminho(valor: string | number | boolean): string
```

</Tab>
<Tab value="Rust">

```rust
pub fn codificar_parametro_de_caminho(valor: impl Display) -> String
```

</Tab>
</Tabs>


# Início rápido (/docs/comecar)

> Instale o termo_core, defina o ambiente e faça sua primeira chamada a um serviço da Termotubos em menos de 5 minutos.

O **termo_core** é o SDK da Termotubos: todos os clientes dos nossos serviços num pacote só, em **TypeScript** (npm, para frontend e backend) e em **Rust** (crates.io). Cada aplicativo é um módulo (`auth`, `bucket`, `portal`...) e **cada rota da API vira uma função**, com o mesmo nome nas duas linguagens.

Ao terminar esta página você terá chamado o TermoAuth e lido um usuário, com 3 passos.

<Callout title="Sem documentação de API">
Aqui você não monta requisição HTTP, URL nem cabeçalho. O SDK resolve o endereço pelo ambiente, manda a credencial e devolve o tipo certo. Se a rota existe na API, existe uma função para ela.
</Callout>

<Steps>
<Step>

### Instale o pacote [#instale-o-pacote]

Fixe sempre a **versão exata**: cada mudança de contrato publica uma versão nova subindo só o último número, inclusive quando quebra código.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```bash
npm install termo_core --save-exact
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
[dependencies]
termo_core = "=0.1.5"
```

</Tab>
</Tabs>

</Step>
<Step>

### Defina o ambiente [#defina-o-ambiente]

A **única** configuração é a variável `AMBIENTE`: `LOCALHOST`, `SANDBOX` ou `PRODUCTION`. Sem ela o processo para com uma mensagem clara, nunca cai em produção por engano.

```bash title=".env"
AMBIENTE=SANDBOX
```

No navegador não existe `process.env`: chame `definir_ambiente_atual_pelo_codigo(import.meta.env.VITE_AMBIENTE)` uma vez ao subir o app. Detalhes em [Ambiente](/docs/comecar/ambiente).

</Step>
<Step>

### Chame uma função [#chame-uma-função]

Toda rota que exige login recebe uma `CredencialDeAcesso` como primeiro argumento.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_usuario, buscar_paginador_usuario } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);

const usuario = await buscar_pelo_id_usuario(credencial_de_acesso, id);
const pagina = await buscar_paginador_usuario(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let usuario = termo_core::auth::buscar_pelo_id_usuario(&credencial_de_acesso, &id).await?;
let pagina = termo_core::auth::buscar_paginador_usuario(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorUsuario { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

</Step>
</Steps>

## Próximos passos [#próximos-passos]

<Cards>
  <Card icon={<LayoutGrid />} title="Todas as funções" href="/docs/servicos" description="Por aplicativo e por entidade, com assinatura, exemplo e tipos." />
  <Card icon={<KeyRound />} title="Credencial e token do aplicativo" href="/docs/comecar/credencial" description="Token do usuário logado e conversa entre back-ends." />
  <Card icon={<TriangleAlert />} title="Tratamento de erros" href="/docs/comecar/erros" description="ErroAoChamarServico, 404 e quando vale tentar de novo." />
  <Card icon={<Webhook />} title="Eventos do TermoWebhook" href="/docs/eventos" description="Publicar, guardar na fila e receber eventos." />
</Cards>


# Instalação (/docs/comecar/instalacao)

> Como adicionar o termo_core em projetos TypeScript e Rust, fixar a versão e escolher só os serviços que você usa.

## TypeScript [#typescript]

TypeScript puro, só `fetch`, `interface` e `type`, **sem nenhuma dependência em runtime**. Funciona no navegador, em Node 20+, Bun e Deno.

```bash
npm install termo_core --save-exact
```

```json title="package.json"
{
  "dependencies": {
    "termo_core": "0.1.5"
  }
}
```

Cada serviço tem o próprio caminho de importação, bom para o bundle do frontend:

```ts
import { buscar_pelo_id_usuario } from "termo_core/auth";
import { criar_arquivo } from "termo_core/bucket";

// ou tudo pela raiz, com um namespace por serviço
import { auth, bucket } from "termo_core";
await auth.buscar_pelo_id_usuario(credencial_de_acesso, id);
```

## Rust [#rust]

```toml title="Cargo.toml"
[dependencies]
termo_core = "=0.1.5"                                                  # todos os serviços
termo_core = { version = "=0.1.5", features = ["webhook_postgres"] }   # + fila de saída de eventos
```

Cada serviço é uma **feature**, todas ligadas por padrão (`todos_os_servicos`). Para compilar menos:

```toml
termo_core = { version = "=0.1.5", default-features = false, features = ["auth", "bucket"] }
```

| Feature | O que liga |
| --- | --- |
| `todos_os_servicos` (padrão) | todos os módulos de serviço |
| `ai`, `auth`, `bucket`, `intranet`, `leads`, `mcp`, `portal`, `quality`, `sell`, `status`, `studio`, `support`, `tracing`, `webhook`, `wms` | o módulo do serviço com o mesmo nome |
| `webhook_publicar` | `publicar_evento_no_hub_agora` e `ConfiguracaoDoHub` |
| `webhook_receber` | conferência da assinatura Ed25519 das entregas do hub |
| `webhook_postgres` | fila de saída no Postgres do app (inclui `webhook_publicar`) |

## Por que fixar a versão exata [#por-que-fixar-a-versão-exata]

<Callout type="warn" title="Sempre com =">
Nunca use `"0.1"`, `"^0.1.5"` nem `"~0.1.5"`. Os contratos vêm do SANDBOX e o workflow publica **toda** mudança subindo só o último número, inclusive quando a mudança quebra código (campo ou rota removida, nome trocado).
</Callout>

Sem a versão exata, um `cargo update` ou um `npm install` sem lockfile pode trazer, sem ninguém perceber, um contrato que ainda só existe no sandbox. Para atualizar, troque a versão de propósito e confira se o projeto compila.

As versões do crate e do pacote npm **não andam juntas**: cada uma sobe quando o código dela muda.

<Callout>Os exemplos usam `0.1.5`. A versão publicada mais recente de cada pacote aparece no topo da página de cada [serviço](/docs/servicos), no bloco de importação.</Callout>


# TermoAuth (/docs/eventos/catalogo/termo_auth)

> Eventos publicados pelo TermoAuth: colaborador.atualizado, colaborador.criado.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Contratos gerados dos esquemas cadastrados no TermoWebhook (`GET /esquemas.json`). No Rust, cada evento implementa o trait `Evento` (`APLICATIVO`, `TIPO`, `VERSAO`); no TypeScript, existe o tipo dos dados e uma constante com a identificação.

| Evento | Versão | Situação | Tipo |
| --- | --- | --- | --- |
| `colaborador.atualizado` | 2 | ativa | [`ColaboradorAtualizadoV2`](#colaboradoratualizadov2) |
| `colaborador.atualizado` | 1 | descontinuada | [`ColaboradorAtualizadoV1`](#colaboradoratualizadov1) |
| `colaborador.criado` | 2 | ativa | [`ColaboradorCriadoV2`](#colaboradorcriadov2) |
| `colaborador.criado` | 1 | descontinuada | [`ColaboradorCriadoV1`](#colaboradorcriadov1) |

## `colaborador.atualizado` v2 [#colaboradoratualizadov2]

<Evento tipo="colaborador.atualizado" versao={2} aplicativo="TermoAuth" situacao="ativa" />

Toda vez que os dados de um colaborador mudam no TermoAuth

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { webhook } from "termo_core";

type Dados = webhook.eventos.termo_auth.ColaboradorAtualizadoV2;
const identificacao = webhook.eventos.termo_auth.ColaboradorAtualizadoV2; // { aplicativo, tipo, versao }

export type ColaboradorAtualizadoV2CamposAlteradosItem = "nome" | "email" | "imagem" | "perfil" | "e_master" | "setor" | "cargo" | "funcao";

export type ColaboradorAtualizadoV2Perfil = "colaborador" | "cliente";

export interface ColaboradorAtualizadoV2 {
  atualizado_em: string;
  campos_alterados: Array<ColaboradorAtualizadoV2CamposAlteradosItem>;
  cargo: string | null;
  criado_em: string;
  e_master: boolean;
  email: string;
  email_verificado: boolean;
  funcao: string | null;
  id: string;
  imagem: string | null;
  nome: string;
  perfil: ColaboradorAtualizadoV2Perfil;
  setor: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::eventos::termo_auth::ColaboradorAtualizadoV2;

pub enum ColaboradorAtualizadoV2CamposAlteradosItem {
    #[serde(rename = "nome")]
    Nome,
    #[serde(rename = "email")]
    Email,
    #[serde(rename = "imagem")]
    Imagem,
    #[serde(rename = "perfil")]
    Perfil,
    #[serde(rename = "e_master")]
    EMaster,
    #[serde(rename = "setor")]
    Setor,
    #[serde(rename = "cargo")]
    Cargo,
    #[serde(rename = "funcao")]
    Funcao,
}

pub enum ColaboradorAtualizadoV2Perfil {
    #[serde(rename = "colaborador")]
    Colaborador,
    #[serde(rename = "cliente")]
    Cliente,
}

pub struct ColaboradorAtualizadoV2 {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub campos_alterados: Vec<ColaboradorAtualizadoV2CamposAlteradosItem>,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub e_master: bool,
    pub email: String,
    pub email_verificado: bool,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub nome: String,
    pub perfil: ColaboradorAtualizadoV2Perfil,
    pub setor: Option<String>,
}
```

</Tab>
</Tabs>

## `colaborador.atualizado` v1 [#colaboradoratualizadov1]

<Evento tipo="colaborador.atualizado" versao={1} aplicativo="TermoAuth" situacao="descontinuada" />

Toda vez que os dados de um colaborador mudam no TermoAuth

<Callout type="warn" title="Versão descontinuada">Continue recebendo enquanto houver publicadores, mas use a versão mais nova em código novo.</Callout>

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { webhook } from "termo_core";

type Dados = webhook.eventos.termo_auth.ColaboradorAtualizadoV1;
const identificacao = webhook.eventos.termo_auth.ColaboradorAtualizadoV1; // { aplicativo, tipo, versao }

export type ColaboradorAtualizadoV1CamposAlteradosItem = "nome" | "email" | "imagem" | "perfil" | "e_master";

export type ColaboradorAtualizadoV1Perfil = "colaborador" | "cliente";

export interface ColaboradorAtualizadoV1 {
  atualizado_em: string;
  campos_alterados: Array<ColaboradorAtualizadoV1CamposAlteradosItem>;
  criado_em: string;
  e_master: boolean;
  email: string;
  email_verificado: boolean;
  id: string;
  imagem: string | null;
  nome: string;
  perfil: ColaboradorAtualizadoV1Perfil;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::eventos::termo_auth::ColaboradorAtualizadoV1;

pub enum ColaboradorAtualizadoV1CamposAlteradosItem {
    #[serde(rename = "nome")]
    Nome,
    #[serde(rename = "email")]
    Email,
    #[serde(rename = "imagem")]
    Imagem,
    #[serde(rename = "perfil")]
    Perfil,
    #[serde(rename = "e_master")]
    EMaster,
}

pub enum ColaboradorAtualizadoV1Perfil {
    #[serde(rename = "colaborador")]
    Colaborador,
    #[serde(rename = "cliente")]
    Cliente,
}

pub struct ColaboradorAtualizadoV1 {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub campos_alterados: Vec<ColaboradorAtualizadoV1CamposAlteradosItem>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub e_master: bool,
    pub email: String,
    pub email_verificado: bool,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub nome: String,
    pub perfil: ColaboradorAtualizadoV1Perfil,
}
```

</Tab>
</Tabs>

## `colaborador.criado` v2 [#colaboradorcriadov2]

<Evento tipo="colaborador.criado" versao={2} aplicativo="TermoAuth" situacao="ativa" />

Toda vez que um colaborador entra no termo auth

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { webhook } from "termo_core";

type Dados = webhook.eventos.termo_auth.ColaboradorCriadoV2;
const identificacao = webhook.eventos.termo_auth.ColaboradorCriadoV2; // { aplicativo, tipo, versao }

export type ColaboradorCriadoV2Perfil = "colaborador";

export interface ColaboradorCriadoV2 {
  cargo: string | null;
  criado_em: string;
  e_master: boolean;
  email: string;
  email_verificado: boolean;
  funcao: string | null;
  id: string;
  imagem: string | null;
  nome: string;
  perfil: ColaboradorCriadoV2Perfil;
  setor: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV2;

pub enum ColaboradorCriadoV2Perfil {
    #[serde(rename = "colaborador")]
    Colaborador,
}

pub struct ColaboradorCriadoV2 {
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub e_master: bool,
    pub email: String,
    pub email_verificado: bool,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub nome: String,
    pub perfil: ColaboradorCriadoV2Perfil,
    pub setor: Option<String>,
}
```

</Tab>
</Tabs>

## `colaborador.criado` v1 [#colaboradorcriadov1]

<Evento tipo="colaborador.criado" versao={1} aplicativo="TermoAuth" situacao="descontinuada" />

Toda vez que um colaborador entra no termo auth

<Callout type="warn" title="Versão descontinuada">Continue recebendo enquanto houver publicadores, mas use a versão mais nova em código novo.</Callout>

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import { webhook } from "termo_core";

type Dados = webhook.eventos.termo_auth.ColaboradorCriadoV1;
const identificacao = webhook.eventos.termo_auth.ColaboradorCriadoV1; // { aplicativo, tipo, versao }

export type ColaboradorCriadoV1Perfil = "colaborador";

export interface ColaboradorCriadoV1 {
  criado_em: string;
  e_master: boolean;
  email: string;
  email_verificado: boolean;
  id: string;
  imagem: string | null;
  nome: string;
  perfil: ColaboradorCriadoV1Perfil;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV1;

pub enum ColaboradorCriadoV1Perfil {
    #[serde(rename = "colaborador")]
    Colaborador,
}

pub struct ColaboradorCriadoV1 {
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub e_master: bool,
    pub email: String,
    pub email_verificado: bool,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub nome: String,
    pub perfil: ColaboradorCriadoV1Perfil,
}
```

</Tab>
</Tabs>


# Fila no Postgres (/docs/eventos/fila_postgres)

> Guardar o evento na mesma transação que grava a mudança e enviar em background, com novas tentativas. Feature webhook_postgres.

```toml title="Cargo.toml"
termo_core = { version = "=0.1.5", features = ["webhook_postgres"] }
```

O padrão *outbox*: o evento é gravado numa tabela do **banco do próprio app** dentro da mesma transação da mudança, e uma tarefa em background publica no hub.

## `iniciar_envio_automatico_dos_eventos_guardados` [#iniciar_envio_automatico_dos_eventos_guardados]

Chame **uma vez ao subir o app**. Cria a tabela se não existir e inicia a tarefa que envia os eventos guardados.

```rust
pub async fn iniciar_envio_automatico_dos_eventos_guardados(
    pool: &PgPool,
    hub: Option<ConfiguracaoDoHub>,
) -> Result<JoinHandle<()>, sqlx::Error>
```

```rust title="main.rs"
termo_core::definir_segredo_do_app(segredo_lido_do_banco);
termo_core::webhook::iniciar_envio_automatico_dos_eventos_guardados(
    &pool,
    termo_core::webhook::ConfiguracaoDoHub::carregar_do_ambiente_atual(),
)
.await?;
```

- Aviso imediato por `LISTEN/NOTIFY` no canal `termo_eventos_<schema>`; se não der para ouvir, varre a tabela a cada 5 s.
- Envia em lotes de 50, em ordem de criação, com `FOR UPDATE SKIP LOCKED` (várias instâncias do app não enviam o mesmo evento).
- Falha que vale tentar de novo espera 5 s, 30 s, 2 min, 5 min e depois 10 min entre tentativas.
- Recusa definitiva do hub (400, 413, 422) descarta o evento com log.
- Evento sem entrega há mais de 1 h (`RETENCAO_EM_SEGUNDOS`) é descartado com log.
- Sem segredo do app, os eventos esperam na tabela até ele ser cadastrado.
- Com `hub` igual a `None`, os eventos só são impressos no terminal.

## `guardar_evento_para_publicar_na_mesma_transacao` [#guardar_evento_para_publicar_na_mesma_transacao]

Guarda o evento dentro da transação que já grava a mudança. Devolve o id do envelope.

```rust
pub async fn guardar_evento_para_publicar_na_mesma_transacao<'c, E, T>(
    executor: E,
    entidade_id: impl Into<String>,
    dados: T,
) -> Result<Uuid, sqlx::Error>
where
    E: PgExecutor<'c>,
    T: Evento,
```

```rust title="Exemplo"
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV2;

let mut transacao = pool.begin().await?;
sqlx::query("INSERT INTO colaborador ...").execute(&mut *transacao).await?;
termo_core::webhook::guardar_evento_para_publicar_na_mesma_transacao(
    &mut *transacao,
    colaborador.id.to_string(),
    ColaboradorCriadoV2 { /* ... */ },
)
.await?;
transacao.commit().await?;
```

## `guardar_envelope_para_publicar_na_mesma_transacao` [#guardar_envelope_para_publicar_na_mesma_transacao]

O mesmo, quando você já montou o `Envelope` (ex.: para escolher o `id` ou o `ocorrido_em`).

```rust
pub async fn guardar_envelope_para_publicar_na_mesma_transacao<'c, E, T>(
    executor: E,
    envelope: &Envelope<T>,
) -> Result<Uuid, sqlx::Error>
where
    E: PgExecutor<'c>,
    T: Evento,
```

## `criar_tabela_da_fila_de_saida_se_nao_existir` [#criar_tabela_da_fila_de_saida_se_nao_existir]

Já chamada por `iniciar_envio_automatico_dos_eventos_guardados`. Use só se quiser criar a tabela antes (ex.: em migração).

```rust
pub async fn criar_tabela_da_fila_de_saida_se_nao_existir(pool: &PgPool) -> Result<(), sqlx::Error>

pub const TABELA_DA_FILA: &str = "termo_eventos_pendente";
pub const RETENCAO_EM_SEGUNDOS: f64 = 3600.0;
```

```sql title="termo_eventos_pendente"
CREATE TABLE IF NOT EXISTS termo_eventos_pendente (
    id uuid PRIMARY KEY,
    tipo text NOT NULL,
    versao integer NOT NULL,
    entidade_id text NOT NULL,
    envelope jsonb NOT NULL,
    tentativas integer NOT NULL DEFAULT 0,
    proxima_tentativa_em timestamptz NOT NULL DEFAULT now(),
    reservado_ate timestamptz,
    ultimo_erro text,
    criado_em timestamptz NOT NULL DEFAULT now()
);
```


# Eventos do TermoWebhook (/docs/eventos)

> Como os apps da Termotubos publicam e recebem eventos pelo hub, com contratos tipados gerados dos esquemas cadastrados.

O **TermoWebhook** é o hub de eventos da Termotubos. Um app publica (`colaborador.criado`), o hub guarda e entrega a todos os apps assinantes, assinando cada entrega com Ed25519.

| Recurso | TypeScript | Rust |
| --- | --- | --- |
| Contratos tipados dos eventos | sim (tipos e `{ aplicativo, tipo, versao }`) | sim (structs com o trait `Evento`) |
| Publicar na hora | não | `publicar_evento_no_hub_agora` (feature `webhook_publicar`) |
| Fila de saída no Postgres do app | não | `guardar_evento_para_publicar_na_mesma_transacao` (feature `webhook_postgres`) |
| Receber entregas conferidas | não | `receber_evento_conferido_do_hub` (feature `webhook_receber`) |
| Rotas da API do hub (painel) | sim | sim. Veja [TermoWebhook](/docs/servicos/webhook) |

## O fluxo [#o-fluxo]

<Steps>
<Step>

### Guardar na mesma transação [#guardar-na-mesma-transação]

No model, dentro da transação que já grava a mudança, o app guarda o evento numa tabela local (`termo_eventos_pendente`). Se a transação falhar, o evento some junto: nunca existe evento de algo que não aconteceu.

</Step>
<Step>

### Enviar em background [#enviar-em-background]

Uma tarefa iniciada ao subir o app lê a tabela (aviso imediato por `LISTEN/NOTIFY`, com varredura a cada 5 s) e publica no hub com `Authorization: Bearer <token do aplicativo>`, com novas tentativas.

</Step>
<Step>

### Receber conferido [#receber-conferido]

O hub entrega no endereço cadastrado do app assinante. O app confere a assinatura com a chave pública do hub e lê o evento tipado.

</Step>
</Steps>

## Credencial [#credencial]

Para publicar e para receber, basta o **segredo do app** gerado no TermoAuth (veja [Credencial](/docs/comecar/credencial)). O hub reconhece quem publica pelo token de aplicativo, e o destino assinado em cada entrega é o id do app no TermoAuth (`identificador_do_aplicativo()`). Sem segredo, os eventos esperam na fila e as entregas recebidas respondem `503`, então o hub reenvia.

## Exemplo completo [#exemplo-completo]

```rust
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV2;

// Ao subir, uma vez (feature webhook_postgres):
termo_core::webhook::iniciar_envio_automatico_dos_eventos_guardados(
    &pool,
    termo_core::webhook::ConfiguracaoDoHub::carregar_do_ambiente_atual(),
)
.await?;

// No model, dentro da transação que já grava a mudança:
termo_core::webhook::guardar_evento_para_publicar_na_mesma_transacao(&mut *transacao, id.to_string(), ColaboradorCriadoV2 { /* ... */ }).await?;

// Na rota que recebe as entregas (feature webhook_receber):
let evento = termo_core::webhook::receber_evento_conferido_do_hub::<ColaboradorCriadoV2>(&cabecalhos, &corpo).await?;
```

<Cards>
  <Card icon={<Send />} title="Publicar" href="/docs/eventos/publicar" description="Publicar um envelope no hub agora." />
  <Card icon={<Database />} title="Fila no Postgres" href="/docs/eventos/fila_postgres" description="Guardar na transação e enviar em background." />
  <Card icon={<Inbox />} title="Receber" href="/docs/eventos/receber" description="Conferir a assinatura e ler o evento." />
  <Card icon={<BookOpen />} title="Catálogo de eventos" href="/docs/eventos/catalogo/termo_auth" description="Todos os contratos, por aplicativo." />
</Cards>


# Publicar (/docs/eventos/publicar)

> Publicar um evento no TermoWebhook na hora, com o token do aplicativo. Feature webhook_publicar.

```toml title="Cargo.toml"
termo_core = { version = "=0.1.5", features = ["webhook_publicar"] }
```

<Callout>Em código de app, prefira a [fila no Postgres](/docs/eventos/fila_postgres): ela garante que o evento só sai se a transação gravou e tenta de novo sozinha. Publicar na hora serve para ferramentas e scripts.</Callout>

## `publicar_evento_no_hub_agora` [#publicar_evento_no_hub_agora]

Envia o envelope para `POST {hub}/eventos` com `Authorization: Bearer <token do aplicativo>`. Tempo limite de 10 s, sem seguir redirecionamentos.

```rust
pub async fn publicar_evento_no_hub_agora<T: Evento>(
    configuracao: &ConfiguracaoDoHub,
    envelope: &Envelope<T>,
) -> Result<Publicado, FalhaDePublicacao>
```

```rust title="Exemplo"
use termo_core::webhook::{publicar_evento_no_hub_agora, ConfiguracaoDoHub, Envelope};
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV2;

let hub = ConfiguracaoDoHub::carregar_do_ambiente_atual().expect("sempre devolve o hub do ambiente");
let envelope = Envelope::novo(colaborador.id.to_string(), ColaboradorCriadoV2 { /* ... */ });

match publicar_evento_no_hub_agora(&hub, &envelope).await {
    Ok(publicado) if publicado.repetido => println!("o hub já tinha este evento"),
    Ok(_) => {}
    Err(falha) if falha.vale_tentar_de_novo() => { /* tente mais tarde */ }
    Err(falha) => eprintln!("recusado: {falha}"),
}
```

## `ConfiguracaoDoHub` [#configuracaodohub]

```rust
pub struct ConfiguracaoDoHub {
    pub url: String,
}

impl ConfiguracaoDoHub {
    pub fn nova(url: impl Into<String>) -> Self;
    /// Sempre devolve o hub do ambiente atual. Sem segredo do app, avisa que os eventos esperam na fila.
    pub fn carregar_do_ambiente_atual() -> Option<Self>;
    pub fn endereco_de_publicacao(&self) -> String; // "{url}/eventos"
}

pub const CAMINHO_DE_PUBLICACAO: &str = "/eventos";
```

## `Envelope` e o trait `Evento` [#envelope-e-o-trait-evento]

```rust
pub trait Evento: Serialize + DeserializeOwned {
    const APLICATIVO: &'static str;
    const TIPO: &'static str;
    const VERSAO: i32;
}

pub struct Envelope<T> {
    pub id: Uuid,               // UUID v7, gerado por Envelope::novo
    pub tipo: String,           // T::TIPO
    pub versao: i32,            // T::VERSAO
    pub entidade_id: String,
    pub ocorrido_em: DateTime<Utc>,
    pub dados: T,
}

impl<T: Evento> Envelope<T> {
    pub fn novo(entidade_id: impl Into<String>, dados: T) -> Self;
}
```

## `Publicado` e `FalhaDePublicacao` [#publicado-e-falhadepublicacao]

```rust
pub struct Publicado {
    pub repetido: bool,          // o hub já tinha um evento com este id
    pub aviso: Option<String>,
}

pub enum FalhaDePublicacao {
    Rede(String),
    SemTokenDoAplicativo(String),
    Recusado { status: u16, motivo: Option<String>, mensagem: String },
    Serializacao(String),
}

impl FalhaDePublicacao {
    /// false para Serializacao e para recusas 400, 413 e 422; true para o resto.
    pub fn vale_tentar_de_novo(&self) -> bool;
}
```

### `endereco_do_termo_webhook_no_ambiente_atual` [#endereco_do_termo_webhook_no_ambiente_atual]

```rust
pub fn endereco_do_termo_webhook_no_ambiente_atual() -> String
```

Endereço do hub no ambiente atual (features `webhook_publicar` ou `webhook_receber`).


# Receber (/docs/eventos/receber)

> Conferir a assinatura Ed25519 de uma entrega do hub e ler o evento tipado. Feature webhook_receber.

```toml title="Cargo.toml"
termo_core = { version = "=0.1.5", features = ["webhook_receber"] }
```

Cada entrega do hub chega com os cabeçalhos `X-TermoWebhook-Data`, `X-TermoWebhook-Chave` e `X-TermoWebhook-Assinatura`. A assinatura cobre a data, o destino (o id do app no TermoAuth) e o corpo, e é conferida com a chave pública do hub (`GET /.well-known/jwks.json`, em cache, buscada de novo no máximo a cada 30 s quando aparece uma chave nova).

## `receber_evento_conferido_do_hub` [#receber_evento_conferido_do_hub]

O caminho mais curto quando a rota recebe um tipo só.

```rust
pub async fn receber_evento_conferido_do_hub<T: Evento>(
    cabecalhos: &HeaderMap,
    corpo: &[u8],
) -> Result<EventoRecebido<T>, ErroDeRecebimento>
```

```rust title="Exemplo com axum"
use axum::{body::Bytes, http::{HeaderMap, StatusCode}};
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV2;

async fn receber_colaborador_criado(cabecalhos: HeaderMap, corpo: Bytes) -> StatusCode {
    match termo_core::webhook::receber_evento_conferido_do_hub::<ColaboradorCriadoV2>(&cabecalhos, &corpo).await {
        Ok(evento) => {
            // evento.dados é ColaboradorCriadoV2
            StatusCode::OK
        }
        Err(erro) => erro.status(),
    }
}
```

## `conferir_entrega_recebida_do_hub` [#conferir_entrega_recebida_do_hub]

Quando a mesma rota recebe vários tipos: confere a assinatura e devolve a `Entrega`, para você escolher o tipo.

```rust
pub async fn conferir_entrega_recebida_do_hub<'a>(
    cabecalhos: &HeaderMap,
    corpo: &'a [u8],
) -> Result<Entrega<'a>, ErroDeRecebimento>
```

```rust title="Exemplo"
use termo_core::webhook::eventos::termo_auth::{ColaboradorAtualizadoV2, ColaboradorCriadoV2};

let entrega = termo_core::webhook::conferir_entrega_recebida_do_hub(&cabecalhos, &corpo).await?;
if entrega.e::<ColaboradorCriadoV2>() {
    let evento = entrega.ler::<ColaboradorCriadoV2>()?;
} else if entrega.e::<ColaboradorAtualizadoV2>() {
    let evento = entrega.ler::<ColaboradorAtualizadoV2>()?;
}
```

## `conferir_entrega_recebida_do_hub_com_configuracao` [#conferir_entrega_recebida_do_hub_com_configuracao]

O mesmo, com o endereço do hub e o id do app informados (ex.: testes).

```rust
pub async fn conferir_entrega_recebida_do_hub_com_configuracao<'a>(
    configuracao: &ConfiguracaoDeRecebimento,
    cabecalhos: &HeaderMap,
    corpo: &'a [u8],
) -> Result<Entrega<'a>, ErroDeRecebimento>

pub struct ConfiguracaoDeRecebimento {
    pub url: String,
    pub aplicativo_id: String,
}

impl ConfiguracaoDeRecebimento {
    pub fn nova(url: impl Into<String>, aplicativo_id: impl Into<String>) -> Self;
    /// Hub do ambiente atual e id do app pelo token de aplicativo.
    pub async fn carregar_do_ambiente_atual() -> Result<Self, ErroDeRecebimento>;
    pub fn endereco_das_chaves(&self) -> String; // "{url}/.well-known/jwks.json"
}
```

## `Entrega` e `EventoRecebido` [#entrega-e-eventorecebido]

```rust
pub struct Entrega<'a> {
    pub id: Uuid,
    pub tipo: String,
    pub versao: i32,
    // corpo: &'a [u8]
}

impl<'a> Entrega<'a> {
    pub fn e<T: Evento>(&self) -> bool;                                      // tipo e versão batem
    pub fn ler<T: Evento>(&self) -> Result<EventoRecebido<T>, ErroDeRecebimento>;
    pub fn corpo(&self) -> &'a [u8];
}

pub struct EventoRecebido<T> {
    pub id: Uuid,
    pub tipo: String,
    pub versao: i32,
    pub entidade_id: String,
    pub ocorrido_em: DateTime<Utc>,
    pub recebido_em: DateTime<Utc>,
    pub publicador: String,
    pub dados: T,
}
```

## `ErroDeRecebimento` [#erroderecebimento]

`status()` já devolve o código HTTP certo para responder ao hub.

| Variante | `status()` | Quando |
| --- | --- | --- |
| `SemIdentificacaoDoAplicativo(String)` | 503 | sem segredo do app: o hub reenvia depois |
| `SemAssinatura` | 401 | faltam os cabeçalhos de assinatura |
| `ForaDaJanela` | 401 | `X-TermoWebhook-Data` fora da tolerância de 5 minutos |
| `ChaveDesconhecida(String)` | 401 | a chave não está entre as chaves públicas do hub |
| `ChavesIndisponiveis(String)` | 503 | não deu para buscar as chaves do hub |
| `AssinaturaInvalida` | 401 | a assinatura não confere para este app |
| `CorpoInvalido(String)` | 400 | o corpo não é o envelope esperado |
| `TipoDiferente { tipo, versao }` | 200 | entrega de outro tipo: responda 200 para o hub não reenviar |


# Sobre esta documentação (/docs/recursos/documentacao)

> Como rodar, editar e publicar esta documentação, feita com Fumadocs e publicada no Cloudflare Pages.

O código fica em `docs/` no repositório [TermoCore](https://github.com/OrgTermotubos/TermoCore): Next.js com Fumadocs, exportado como site estático.

## Rodar na máquina [#rodar-na-máquina]

```bash
cd docs
bun install
bun run dev        # http://localhost:51050
```

`dev` e `build` rodam antes `bun scripts/gerar_paginas_dos_sdks.ts`, que regenera as páginas de **Serviços** e o **Catálogo de eventos** a partir de `packages/` e `openapi/`.

## O que editar [#o-que-editar]

| Pasta | Origem |
| --- | --- |
| `content/docs/comecar/`, `eventos/*.mdx`, `recursos/` | escritas à mão: edite à vontade |
| `content/docs/servicos/`, `content/docs/eventos/catalogo/` | geradas: **não edite**, mude o contrato ou o script |

Quando um serviço muda o contrato: `cargo run -p gerador` na raiz atualiza os pacotes, e o próximo build da documentação já mostra as funções novas.

## Publicação [#publicação]

O Cloudflare Pages faz o build a cada push na `main`:

| Campo | Valor |
| --- | --- |
| Framework preset | `None` |
| Build command | `bun install --frozen-lockfile && bun run build` |
| Build output directory | `out` |
| Root directory | `docs` |
| Variável de ambiente | `BUN_VERSION` = `1.4.2` |


# Glossário (/docs/recursos/glossario)

> Os termos usados no termo_core e nesta documentação.

| Termo | Significado |
| --- | --- |
| **termo_core** | o SDK da Termotubos, com o mesmo nome no crates.io (Rust) e no npm (TypeScript) |
| **Serviço / aplicativo** | um sistema da Termotubos com API própria (TermoAuth, TermoBucket...). Vira um módulo do SDK |
| **Módulo** | `termo_core::auth` no Rust, `termo_core/auth` no TypeScript |
| **Entidade** | o recurso de uma rota (`usuario`, `arquivo`), vindo da tag no OpenAPI. Cada entidade é uma página aqui |
| **Função de rota** | função gerada para uma rota da API, ex.: `buscar_pelo_id_usuario` |
| **`AMBIENTE`** | a única variável lida pelo SDK: `LOCALHOST`, `SANDBOX` ou `PRODUCTION` |
| **Credencial de acesso** | `CredencialDeAcesso`, o token enviado em `Authorization: Bearer` |
| **Token do usuário logado** | o JWT que o TermoAuth deu para a pessoa |
| **Segredo do app** | segredo gerado no TermoAuth para o app, guardado cifrado no banco do app e entregue com `definir_segredo_do_app` |
| **Token do aplicativo** | JWT curto do próprio app, trocado pelo segredo em `POST /token_de_app`. Para as APIs de sistema |
| **Id do aplicativo** | o `app` do token de aplicativo, o mesmo id em todos os serviços (`identificador_do_aplicativo()`) |
| **Contrato** | o `openapi.json` de um serviço ou o catálogo de esquemas de evento, copiado em `openapi/` |
| **Gerador** | o binário `gerador` que transforma os contratos em código Rust e TypeScript |
| **TermoWebhook / hub** | o serviço central de eventos |
| **Evento** | algo que aconteceu num app (`colaborador.criado`), com tipo e versão |
| **Envelope** | o evento publicado: `id`, `tipo`, `versao`, `entidade_id`, `ocorrido_em`, `dados` |
| **Entrega** | o envio de um evento do hub para um app assinante, assinado com Ed25519 |
| **Fila de saída** | a tabela `termo_eventos_pendente` no banco do app que publica |
| **Versão descontinuada** | versão de esquema de evento que ainda circula, mas não deve ser usada em código novo |


# Usar com IA (/docs/recursos)

> Esta documentação foi feita para ser lida por pessoas e por agentes de IA. Veja como entregar o SDK inteiro ao seu assistente.

Toda página segue o padrão do Fumadocs e também existe em Markdown puro, então dá para colar no Claude, no ChatGPT ou no Cursor sem perder nada.

| Recurso | Endereço | Para quê |
| --- | --- | --- |
| Índice | [`/llms.txt`](/llms.txt) | lista de todas as páginas com descrição, para o agente escolher o que ler |
| Documentação inteira | [`/llms-full.txt`](/llms-full.txt) | todas as funções e tipos num arquivo só |
| Uma página em Markdown | `/llms.mdx/docs/<caminho>/content.md` | ex.: [`/llms.mdx/docs/servicos/auth/usuario/content.md`](/llms.mdx/docs/servicos/auth/usuario/content.md) |
| Botão **Copiar para IA** | topo de cada página | copia a página em Markdown |
| Menu **Abrir** | topo de cada página | abre a página no Claude, ChatGPT, Cursor ou GitHub |

## Instrução sugerida para o seu agente [#instrução-sugerida-para-o-seu-agente]

```md title="CLAUDE.md"
Este projeto usa o SDK termo_core da Termotubos (TypeScript e Rust).
Antes de chamar qualquer serviço da Termotubos, leia https://<endereço desta documentação>/llms.txt
e use as funções do termo_core; nunca monte requisições HTTP à mão.
Fixe a versão exata do termo_core (com = no Cargo.toml, sem ^ no package.json).
```

## Como as páginas são organizadas [#como-as-páginas-são-organizadas]

- **Serviços** → um aplicativo por pasta → uma página por entidade (a tag da rota no OpenAPI).
- Em cada entidade: tabela de resumo, depois cada função com a rota, assinatura TypeScript e Rust, exemplo, argumentos e retorno, e no fim os tipos usados.
- O nome da função é o mesmo nas duas linguagens, então buscar pelo nome (`Ctrl K`) acha a função nas duas.


# Auth (/docs/servicos/ai/auth)

> 1 função do TermoAI para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Busca o acesso de quem está logado |

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Busca o acesso de quem está logado

Livre para qualquer usuário autenticado com acesso ativo, mesmo sem nenhuma permissão liberada. Devolve o acesso de quem chamou (id, e-mail, nome e se é master do TermoAuth), o nome do perfil de acesso (`perfil_acesso`, `null` sem perfil) e as permissões por área (`gateway`, `conversas`, `colaboradores` e `configuracoes`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões e, no primeiro pedido, ganha o acesso e o colaborador automaticamente. `nome` vem do TermoAuth e, se estiver vazio, repete o e-mail. É a chamada que o painel faz antes de mostrar qualquer tela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/ai";

export interface AcessoAtual {
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::AcessoAtual;

pub struct AcessoAtual {
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/ai";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/ai";

export interface Permissoes {
  colaboradores?: Acoes;
  configuracoes?: Acoes;
  conversas?: Acoes;
  gateway?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Permissoes;

pub struct Permissoes {
    pub colaboradores: Option<Acoes>,
    pub configuracoes: Option<Acoes>,
    pub conversas: Option<Acoes>,
    pub gateway: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Chave IA (/docs/servicos/ai/chave_ia)

> 8 funções do TermoAI para chave ia.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_chave_ia`](#buscar_paginador_chave_ia) | `GET /chave_ia` | Lista as chaves de IA paginadas |
| [`criar_chave_ia`](#criar_chave_ia) | `POST /chave_ia` | Cadastra uma chave de API de uma IA |
| [`buscar_auto_complete_chave_ia`](#buscar_auto_complete_chave_ia) | `GET /chave_ia/autocomplete` | Lista básica de chaves de IA para seleção |
| [`buscar_pelo_filtro_chave_ia`](#buscar_pelo_filtro_chave_ia) | `GET /chave_ia/filtro` | Busca chaves de IA por filtro |
| [`buscar_pelo_id_chave_ia`](#buscar_pelo_id_chave_ia) | `GET /chave_ia/{id}` | Busca uma chave de IA pelo id |
| [`atualizar_pelo_id_chave_ia`](#atualizar_pelo_id_chave_ia) | `PATCH /chave_ia/{id}` | Atualiza uma chave de IA pelo id |
| [`deletar_pelo_id_chave_ia`](#deletar_pelo_id_chave_ia) | `DELETE /chave_ia/{id}` | Exclui uma chave de IA pelo id |
| [`buscar_creditos_chave_ia`](#buscar_creditos_chave_ia) | `GET /chave_ia/{id}/creditos` | Consulta o saldo da chave na própria IA |

## `buscar_paginador_chave_ia` [#buscar_paginador_chave_ia]

<Rota metodo="GET" caminho="/chave_ia" credencial />

Lista as chaves de IA paginadas

Exige qualquer permissão da área `gateway` (qualquer ação liberada na área já libera a leitura). Lista as chaves não excluídas por prioridade e depois pela ordem de cadastro. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de chaves não excluídas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorChaveIa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaChaveIa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_chave_ia(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorChaveIa,
) -> Result<tipos::PaginaChaveIa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_chave_ia(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorChaveIa { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaChaveIa>` · Rust: `Result<tipos::PaginaChaveIa, ErroAoChamarServico>` · veja [`PaginaChaveIa`](#tipo-paginachaveia).

## `criar_chave_ia` [#criar_chave_ia]

<Rota metodo="POST" caminho="/chave_ia" credencial />

Cadastra uma chave de API de uma IA

Exige a permissão `criar` da área `gateway`. Cadastra a chave de uma IA do catálogo, que o gateway passa a usar. `provedor` é obrigatório (`gemini`, `groq`, `openrouter`, `mistral`, `cerebras`, `cloudflare`, `huggingface`, `nvidia`, `cohere`, `zai`, `ollama`, `deepseek` ou `openai`); `apelido` é obrigatório (até 80 caracteres); `chave` é obrigatória (até 500 caracteres, sem espaços) e única. `conta_id` vai até 64 caracteres e é obrigatório para `cloudflare`. `limites` (opcional, cada um de 1 a 100.000.000 requisições ou de 1 a 1.000.000.000.000 tokens por minuto, hora, dia e mês) faz o gateway pular a chave quando estoura. `fuso_da_cota` (`UTC`, `America/Los_Angeles` ou `America/Sao_Paulo`) define quando o dia e o mês viram; o padrão é o da IA. `prioridade` vai de 1 a 999 (padrão 100): o gateway tenta primeiro a menor. `gratuita` (padrão `false`) marca a chave como free: o custo de cada uso (tokens de entrada e de saída × preço do modelo em `preco_modelo`) conta como gasto numa chave paga e como economia numa gratuita. `deepseek` e `openai` só têm chave paga: `gratuita = true` nelas responde `400`. A resposta nunca traz a chave, só `chave_mascarada`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ChaveIaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ChaveIa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_chave_ia(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ChaveIaCriar,
) -> Result<tipos::ChaveIa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::criar_chave_ia(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ChaveIaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ChaveIaCriar", typeDescriptionLink: "#tipo-chaveiacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ChaveIa>` · Rust: `Result<tipos::ChaveIa, ErroAoChamarServico>` · veja [`ChaveIa`](#tipo-chaveia).

## `buscar_auto_complete_chave_ia` [#buscar_auto_complete_chave_ia]

<Rota metodo="GET" caminho="/chave_ia/autocomplete" credencial />

Lista básica de chaves de IA para seleção

Exige qualquer permissão da área `gateway` (qualquer ação liberada na área já libera a leitura). Devolve só id, apelido e IA, em ordem alfabética do apelido, sem as excluídas. `busca` procura o trecho no apelido (sem diferenciar maiúsculas) ou no id da IA. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteChaveIa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaChaveIaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_chave_ia(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteChaveIa,
) -> Result<tipos::PaginaChaveIaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_auto_complete_chave_ia(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarAutoCompleteChaveIa { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaChaveIaAutoComplete>` · Rust: `Result<tipos::PaginaChaveIaAutoComplete, ErroAoChamarServico>` · veja [`PaginaChaveIaAutoComplete`](#tipo-paginachaveiaautocomplete).

## `buscar_pelo_filtro_chave_ia` [#buscar_pelo_filtro_chave_ia]

<Rota metodo="GET" caminho="/chave_ia/filtro" credencial />

Busca chaves de IA por filtro

Exige qualquer permissão da área `gateway` (qualquer ação liberada na área já libera a leitura). Devolve todas as chaves não excluídas que casam com o filtro, sem paginação, por prioridade e depois pela ordem de cadastro. `provedor` precisa ser igual ao id da IA (por exemplo `gemini`); `apelido` procura o trecho no apelido, sem diferenciar maiúsculas; `ativo` filtra pela situação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroChaveIa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ChaveIa>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_chave_ia(credencial_de_acesso, { provedor: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroChaveIa,
) -> Result<Vec<tipos::ChaveIa>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_chave_ia(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroChaveIa { provedor: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.provedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.apelido": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ChaveIa>>` · Rust: `Result<Vec<tipos::ChaveIa>, ErroAoChamarServico>`

## `buscar_pelo_id_chave_ia` [#buscar_pelo_id_chave_ia]

<Rota metodo="GET" caminho="/chave_ia/{id}" credencial />

Busca uma chave de IA pelo id

Exige qualquer permissão da área `gateway` (qualquer ação liberada na área já libera a leitura). Devolve a chave com a chave de API mascarada (só os últimos caracteres), os limites, o consumo na janela atual de minuto, hora, dia e mês, `libera_em` (quando volta a ter cota, se algum limite estourou), os bloqueios ainda vigentes por categoria (pausas depois de falha, com a data em que acabam), o total de usos e o último erro. Chave excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ChaveIa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_chave_ia(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ChaveIa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_chave_ia(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ChaveIa>` · Rust: `Result<tipos::ChaveIa, ErroAoChamarServico>` · veja [`ChaveIa`](#tipo-chaveia).

## `atualizar_pelo_id_chave_ia` [#atualizar_pelo_id_chave_ia]

<Rota metodo="PATCH" caminho="/chave_ia/{id}" credencial />

Atualiza uma chave de IA pelo id

Exige a permissão `editar` da área `gateway`. Atualização parcial: só os campos enviados mudam, nas mesmas regras do cadastro; a IA (`provedor`) não muda. `chave` vazia mantém a atual; uma chave nova limpa os bloqueios e o último erro. `conta_id` vazio apaga o valor. `limites`, quando enviado, troca os oito limites de uma vez (o que faltar fica sem limite). `ativo: false` tira a chave do gateway; reativar limpa os bloqueios. Trocar `gratuita` só vale para os usos seguintes: o histórico guarda o tipo e o custo da hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ChaveIaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ChaveIa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_chave_ia(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ChaveIaAtualizar,
) -> Result<tipos::ChaveIa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::atualizar_pelo_id_chave_ia(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ChaveIaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ChaveIaAtualizar", typeDescriptionLink: "#tipo-chaveiaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ChaveIa>` · Rust: `Result<tipos::ChaveIa, ErroAoChamarServico>` · veja [`ChaveIa`](#tipo-chaveia).

## `deletar_pelo_id_chave_ia` [#deletar_pelo_id_chave_ia]

<Rota metodo="DELETE" caminho="/chave_ia/{id}" credencial />

Exclui uma chave de IA pelo id

Exige a permissão `deletar` da área `gateway`. Exclusão lógica: a chave sai das leituras e o gateway deixa de usá-la. Excluir de novo responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_chave_ia(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::ai::deletar_pelo_id_chave_ia(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `buscar_creditos_chave_ia` [#buscar_creditos_chave_ia]

<Rota metodo="GET" caminho="/chave_ia/{id}/creditos" credencial />

Consulta o saldo da chave na própria IA

Exige qualquer permissão da área `gateway` (qualquer ação liberada na área já libera a leitura). Pergunta à IA dona da chave quanto ainda resta: `restantes`, `limite` (quando a IA informa) e `unidade` (`dolares` ou `requisicoes_hoje`). Responde `null` quando a IA não informa saldo. Em `groq` e `cerebras` a consulta gasta 1 requisição do modelo que o gateway usa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_creditos_chave_ia(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Creditos | null>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_creditos_chave_ia } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_creditos_chave_ia(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_creditos_chave_ia(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<Option<tipos::Creditos>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_creditos_chave_ia(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Creditos | null>` · Rust: `Result<Option<tipos::Creditos>, ErroAoChamarServico>` · veja [`Creditos`](#tipo-creditos).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ChaveIa [#tipo-chaveia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIa } from "termo_core/ai";

export interface ChaveIa {
  apelido: string;
  ativo: boolean;
  atualizado_em: string;
  bloqueios: Record<string, string>;
  chave_mascarada: string;
  consumo: Consumo;
  conta_id?: string | null;
  criado_em: string;
  fuso_da_cota: string;
  gratuita: boolean;
  id: string;
  libera_em?: string | null;
  limites: Limites;
  prioridade: number;
  provedor: string;
  ultimo_erro?: string | null;
  ultimo_erro_em?: string | null;
  ultimo_uso_em?: string | null;
  usos_total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIa;

pub struct ChaveIa {
    pub apelido: String,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueios: std::collections::BTreeMap<String, chrono::DateTime<chrono::Utc>>,
    pub chave_mascarada: String,
    pub consumo: Consumo,
    pub conta_id: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub fuso_da_cota: String,
    pub gratuita: bool,
    pub id: uuid::Uuid,
    pub libera_em: Option<chrono::DateTime<chrono::Utc>>,
    pub limites: Limites,
    pub prioridade: i32,
    pub provedor: String,
    pub ultimo_erro: Option<String>,
    pub ultimo_erro_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultimo_uso_em: Option<chrono::DateTime<chrono::Utc>>,
    pub usos_total: i64,
}
```

</Tab>
</Tabs>

### ChaveIaAtualizar [#tipo-chaveiaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIaAtualizar } from "termo_core/ai";

export interface ChaveIaAtualizar {
  apelido?: string | null;
  ativo?: boolean | null;
  chave?: string | null;
  conta_id?: string | null;
  fuso_da_cota?: string | null;
  gratuita?: boolean | null;
  limites?: Limites | null;
  prioridade?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIaAtualizar;

pub struct ChaveIaAtualizar {
    pub apelido: Option<String>,
    pub ativo: Option<bool>,
    pub chave: Option<String>,
    pub conta_id: Option<String>,
    pub fuso_da_cota: Option<String>,
    pub gratuita: Option<bool>,
    pub limites: Option<Limites>,
    pub prioridade: Option<i32>,
}
```

</Tab>
</Tabs>

### ChaveIaCriar [#tipo-chaveiacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIaCriar } from "termo_core/ai";

export interface ChaveIaCriar {
  apelido: string;
  chave: string;
  conta_id?: string | null;
  fuso_da_cota?: string | null;
  gratuita?: boolean;
  limites?: Limites;
  prioridade?: number | null;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIaCriar;

pub struct ChaveIaCriar {
    pub apelido: String,
    pub chave: String,
    pub conta_id: Option<String>,
    pub fuso_da_cota: Option<String>,
    pub gratuita: Option<bool>,
    pub limites: Option<Limites>,
    pub prioridade: Option<i32>,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### Consumo [#tipo-consumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Consumo } from "termo_core/ai";

export interface Consumo {
  requisicoes_dia: number;
  requisicoes_hora: number;
  requisicoes_mes: number;
  requisicoes_minuto: number;
  tokens_dia: number;
  tokens_hora: number;
  tokens_mes: number;
  tokens_minuto: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Consumo;

pub struct Consumo {
    pub requisicoes_dia: i64,
    pub requisicoes_hora: i64,
    pub requisicoes_mes: i64,
    pub requisicoes_minuto: i64,
    pub tokens_dia: i64,
    pub tokens_hora: i64,
    pub tokens_mes: i64,
    pub tokens_minuto: i64,
}
```

</Tab>
</Tabs>

### Creditos [#tipo-creditos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Creditos } from "termo_core/ai";

export interface Creditos {
  limite?: number | null;
  restantes: number;
  unidade: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Creditos;

pub struct Creditos {
    pub limite: Option<f64>,
    pub restantes: f64,
    pub unidade: String,
}
```

</Tab>
</Tabs>

### Limites [#tipo-limites]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Limites } from "termo_core/ai";

export interface Limites {
  requisicoes_dia?: number | null;
  requisicoes_hora?: number | null;
  requisicoes_mes?: number | null;
  requisicoes_minuto?: number | null;
  tokens_dia?: number | null;
  tokens_hora?: number | null;
  tokens_mes?: number | null;
  tokens_minuto?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Limites;

pub struct Limites {
    pub requisicoes_dia: Option<i32>,
    pub requisicoes_hora: Option<i32>,
    pub requisicoes_mes: Option<i32>,
    pub requisicoes_minuto: Option<i32>,
    pub tokens_dia: Option<i64>,
    pub tokens_hora: Option<i64>,
    pub tokens_mes: Option<i64>,
    pub tokens_minuto: Option<i64>,
}
```

</Tab>
</Tabs>

### PaginaChaveIa [#tipo-paginachaveia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaChaveIa } from "termo_core/ai";

export interface PaginaChaveIa {
  itens: Array<PaginaChaveIaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaChaveIa;

pub struct PaginaChaveIa {
    pub itens: Vec<PaginaChaveIaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaChaveIaAutoComplete [#tipo-paginachaveiaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaChaveIaAutoComplete } from "termo_core/ai";

export interface PaginaChaveIaAutoComplete {
  itens: Array<PaginaChaveIaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaChaveIaAutoComplete;

pub struct PaginaChaveIaAutoComplete {
    pub itens: Vec<PaginaChaveIaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaChaveIaAutoCompleteItensItem [#tipo-paginachaveiaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaChaveIaAutoCompleteItensItem } from "termo_core/ai";

export interface PaginaChaveIaAutoCompleteItensItem {
  apelido: string;
  id: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaChaveIaAutoCompleteItensItem;

pub struct PaginaChaveIaAutoCompleteItensItem {
    pub apelido: String,
    pub id: uuid::Uuid,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### PaginaChaveIaItensItem [#tipo-paginachaveiaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaChaveIaItensItem } from "termo_core/ai";

export interface PaginaChaveIaItensItem {
  apelido: string;
  ativo: boolean;
  atualizado_em: string;
  bloqueios: Record<string, string>;
  chave_mascarada: string;
  consumo: Consumo;
  conta_id?: string | null;
  criado_em: string;
  fuso_da_cota: string;
  gratuita: boolean;
  id: string;
  libera_em?: string | null;
  limites: Limites;
  prioridade: number;
  provedor: string;
  ultimo_erro?: string | null;
  ultimo_erro_em?: string | null;
  ultimo_uso_em?: string | null;
  usos_total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaChaveIaItensItem;

pub struct PaginaChaveIaItensItem {
    pub apelido: String,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueios: std::collections::BTreeMap<String, chrono::DateTime<chrono::Utc>>,
    pub chave_mascarada: String,
    pub consumo: Consumo,
    pub conta_id: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub fuso_da_cota: String,
    pub gratuita: bool,
    pub id: uuid::Uuid,
    pub libera_em: Option<chrono::DateTime<chrono::Utc>>,
    pub limites: Limites,
    pub prioridade: i32,
    pub provedor: String,
    pub ultimo_erro: Option<String>,
    pub ultimo_erro_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultimo_uso_em: Option<chrono::DateTime<chrono::Utc>>,
    pub usos_total: i64,
}
```

</Tab>
</Tabs>


# Chave IA uso (/docs/servicos/ai/chave_ia_uso)

> 2 funções do TermoAI para chave ia uso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_chave_ia_uso`](#buscar_paginador_chave_ia_uso) | `GET /chave_ia_uso` | Lista os usos das chaves de IA paginados |
| [`buscar_pelo_filtro_chave_ia_uso`](#buscar_pelo_filtro_chave_ia_uso) | `GET /chave_ia_uso/filtro` | Painel de tokens e custo das chaves de IA |

## `buscar_paginador_chave_ia_uso` [#buscar_paginador_chave_ia_uso]

<Rota metodo="GET" caminho="/chave_ia_uso" credencial />

Lista os usos das chaves de IA paginados

Exige qualquer permissão da área `gateway`. Lista cada uso do gateway, do mais recente para o mais antigo, com a chave, a categoria, o modelo, os tokens, os tokens de entrada e de saída, se a chave era gratuita, os preços por 1M de entrada e de saída e o custo do uso gravados na hora. Aceita os mesmos filtros do painel (`inicio`, `fim`, `chave_ia_id`, `gratuita`). `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 20.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_chave_ia_uso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorChaveIaUso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaChaveIaUso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_chave_ia_uso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_chave_ia_uso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_chave_ia_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorChaveIaUso,
) -> Result<tipos::PaginaChaveIaUso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_chave_ia_uso(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorChaveIaUso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.chave_ia_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.gratuita": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaChaveIaUso>` · Rust: `Result<tipos::PaginaChaveIaUso, ErroAoChamarServico>` · veja [`PaginaChaveIaUso`](#tipo-paginachaveiauso).

## `buscar_pelo_filtro_chave_ia_uso` [#buscar_pelo_filtro_chave_ia_uso]

<Rota metodo="GET" caminho="/chave_ia_uso/filtro" credencial />

Painel de tokens e custo das chaves de IA

Exige qualquer permissão da área `gateway`. Soma os usos do gateway no período (`inicio` e `fim` em `AAAA-MM-DD`, dias no fuso `America/Sao_Paulo`; padrão os últimos 30 dias até hoje). Devolve os totais (requisições, tokens em chaves gratuitas e pagas, R$ economizado nas gratuitas e R$ gasto nas pagas), a série por dia (todo dia do período, mesmo sem uso) e o resumo por chave e modelo, do mais usado para o menos. O custo de cada uso é o gravado na hora (tokens de entrada e de saída × preço do modelo em `preco_modelo`), então mudar o preço não reescreve o histórico. No resumo por chave e modelo, `custo_entrada_por_milhao` e `custo_saida_por_milhao` são o preço atual (nulos quando o modelo não tem preço) e `requisicoes_sem_preco` conta os usos gravados sem preço. `chave_ia_id` e `gratuita` filtram.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_chave_ia_uso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroChaveIaUso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ChaveIaUsoPainel>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_chave_ia_uso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_chave_ia_uso(credencial_de_acesso, { inicio: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_chave_ia_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroChaveIaUso,
) -> Result<tipos::ChaveIaUsoPainel, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_chave_ia_uso(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroChaveIaUso { inicio: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.chave_ia_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.gratuita": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ChaveIaUsoPainel>` · Rust: `Result<tipos::ChaveIaUsoPainel, ErroAoChamarServico>` · veja [`ChaveIaUsoPainel`](#tipo-chaveiausopainel).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ChaveIaUsoPainel [#tipo-chaveiausopainel]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIaUsoPainel } from "termo_core/ai";

export interface ChaveIaUsoPainel {
  fim: string;
  inicio: string;
  por_dia: Array<ChaveIaUsoPorDia>;
  por_modelo: Array<ChaveIaUsoPorModelo>;
  totais: ChaveIaUsoTotais;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIaUsoPainel;

pub struct ChaveIaUsoPainel {
    pub fim: chrono::NaiveDate,
    pub inicio: chrono::NaiveDate,
    pub por_dia: Vec<ChaveIaUsoPorDia>,
    pub por_modelo: Vec<ChaveIaUsoPorModelo>,
    pub totais: ChaveIaUsoTotais,
}
```

</Tab>
</Tabs>

### ChaveIaUsoPorDia [#tipo-chaveiausopordia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIaUsoPorDia } from "termo_core/ai";

export interface ChaveIaUsoPorDia {
  dia: string;
  tokens_gratuitos: number;
  tokens_pagos: number;
  valor_economizado: number;
  valor_gasto: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIaUsoPorDia;

pub struct ChaveIaUsoPorDia {
    pub dia: chrono::NaiveDate,
    pub tokens_gratuitos: i64,
    pub tokens_pagos: i64,
    pub valor_economizado: f64,
    pub valor_gasto: f64,
}
```

</Tab>
</Tabs>

### ChaveIaUsoPorModelo [#tipo-chaveiausopormodelo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIaUsoPorModelo } from "termo_core/ai";

export interface ChaveIaUsoPorModelo {
  apelido: string;
  chave_ia_id: string;
  custo: number;
  custo_entrada_por_milhao?: number | null;
  custo_saida_por_milhao?: number | null;
  gratuita: boolean;
  modelo: string;
  preco_modelo_id?: string | null;
  provedor: string;
  requisicoes: number;
  requisicoes_sem_preco: number;
  tokens: number;
  tokens_entrada: number;
  tokens_saida: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIaUsoPorModelo;

pub struct ChaveIaUsoPorModelo {
    pub apelido: String,
    pub chave_ia_id: uuid::Uuid,
    pub custo: f64,
    pub custo_entrada_por_milhao: Option<f64>,
    pub custo_saida_por_milhao: Option<f64>,
    pub gratuita: bool,
    pub modelo: String,
    pub preco_modelo_id: Option<uuid::Uuid>,
    pub provedor: String,
    pub requisicoes: i64,
    pub requisicoes_sem_preco: i64,
    pub tokens: i64,
    pub tokens_entrada: i64,
    pub tokens_saida: i64,
}
```

</Tab>
</Tabs>

### ChaveIaUsoTotais [#tipo-chaveiausototais]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChaveIaUsoTotais } from "termo_core/ai";

export interface ChaveIaUsoTotais {
  requisicoes: number;
  tokens_gratuitos: number;
  tokens_pagos: number;
  valor_economizado: number;
  valor_gasto: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChaveIaUsoTotais;

pub struct ChaveIaUsoTotais {
    pub requisicoes: i64,
    pub tokens_gratuitos: i64,
    pub tokens_pagos: i64,
    pub valor_economizado: f64,
    pub valor_gasto: f64,
}
```

</Tab>
</Tabs>

### PaginaChaveIaUso [#tipo-paginachaveiauso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaChaveIaUso } from "termo_core/ai";

export interface PaginaChaveIaUso {
  itens: Array<PaginaChaveIaUsoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaChaveIaUso;

pub struct PaginaChaveIaUso {
    pub itens: Vec<PaginaChaveIaUsoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaChaveIaUsoItensItem [#tipo-paginachaveiausoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaChaveIaUsoItensItem } from "termo_core/ai";

export interface PaginaChaveIaUsoItensItem {
  apelido: string;
  categoria: string;
  chave_ia_id: string;
  criado_em: string;
  custo: number;
  custo_entrada_por_milhao: number;
  custo_saida_por_milhao: number;
  gratuita: boolean;
  id: string;
  modelo: string;
  provedor: string;
  tokens: number;
  tokens_entrada: number;
  tokens_saida: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaChaveIaUsoItensItem;

pub struct PaginaChaveIaUsoItensItem {
    pub apelido: String,
    pub categoria: String,
    pub chave_ia_id: uuid::Uuid,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub custo: f64,
    pub custo_entrada_por_milhao: f64,
    pub custo_saida_por_milhao: f64,
    pub gratuita: bool,
    pub id: uuid::Uuid,
    pub modelo: String,
    pub provedor: String,
    pub tokens: i32,
    pub tokens_entrada: i32,
    pub tokens_saida: i32,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/ai/colaborador)

> 5 funções do TermoAI para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista os colaboradores com paginação |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista os colaboradores com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena por nome. Quando quem chama é master do TermoAuth, antes de listar o TermoAI busca no TermoAuth os colaboradores `@termotubos.com.br` que ainda não existem aqui e os cadastra sem perfil de acesso (sem nenhuma permissão). `nome` e `cargo` procuram por trecho, sem diferenciar maiúsculas, e `ativo` filtra pela situação. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com o filtro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e e-mail, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail; `nome`, `email` e `cargo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação; `perfil_acesso_id` filtra pelo perfil de acesso. Sem filtro, devolve todos. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização com o TermoAuth) e só o perfil de acesso muda.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve o colaborador com o e-mail e o `master` do acesso dele. Colaborador excluído responde `404`. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização com o TermoAuth) e só o perfil de acesso muda.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoAI: `perfil_acesso_id` aponta para um perfil de `GET /perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/ai";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/ai";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/ai";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/ai";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/ai";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/ai";

export interface PaginaColaboradorItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>


# Config system gateway (/docs/servicos/ai/config_system_gateway)

> 7 funções do TermoAI para config system gateway.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_config_system_gateway`](#buscar_paginador_config_system_gateway) | `GET /config_system_gateway` | Lista as regras do gateway paginadas |
| [`criar_config_system_gateway`](#criar_config_system_gateway) | `POST /config_system_gateway` | Cadastra as regras do gateway de uma categoria |
| [`buscar_auto_complete_config_system_gateway`](#buscar_auto_complete_config_system_gateway) | `GET /config_system_gateway/autocomplete` | Lista básica das regras do gateway para seleção |
| [`buscar_pelo_filtro_config_system_gateway`](#buscar_pelo_filtro_config_system_gateway) | `GET /config_system_gateway/filtro` | Busca as regras do gateway por categoria |
| [`buscar_pelo_id_config_system_gateway`](#buscar_pelo_id_config_system_gateway) | `GET /config_system_gateway/{id}` | Busca as regras do gateway pelo id |
| [`atualizar_pelo_id_config_system_gateway`](#atualizar_pelo_id_config_system_gateway) | `PATCH /config_system_gateway/{id}` | Atualiza as regras do gateway pelo id |
| [`deletar_pelo_id_config_system_gateway`](#deletar_pelo_id_config_system_gateway) | `DELETE /config_system_gateway/{id}` | Exclui as regras do gateway pelo id |

## `buscar_paginador_config_system_gateway` [#buscar_paginador_config_system_gateway]

<Rota metodo="GET" caminho="/config_system_gateway" credencial />

Lista as regras do gateway paginadas

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Lista as configurações não excluídas na ordem de cadastro. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de configurações não excluídas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorConfigSystemGateway = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfigSystemGateway>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_config_system_gateway(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorConfigSystemGateway,
) -> Result<tipos::PaginaConfigSystemGateway, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_config_system_gateway(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorConfigSystemGateway { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfigSystemGateway>` · Rust: `Result<tipos::PaginaConfigSystemGateway, ErroAoChamarServico>` · veja [`PaginaConfigSystemGateway`](#tipo-paginaconfigsystemgateway).

## `criar_config_system_gateway` [#criar_config_system_gateway]

<Rota metodo="POST" caminho="/config_system_gateway" credencial />

Cadastra as regras do gateway de uma categoria

Exige a permissão `criar` da área `configuracoes`. Define como `POST /gateway` atende uma categoria: `tempo_limite_segundos` por tentativa (5 a 600), `prazo_total_segundos` do pedido (5 a 1800, maior ou igual ao tempo por tentativa), `maximo_tentativas` (1 a 50) e quanto tempo uma chave fica pausada depois de uma falha comum (`espera_falha_segundos`, 0 a 86400), de estourar o limite por minuto (`espera_limite_segundos`, 1 a 86400), de esgotar a cota diária (`espera_cota_diaria_segundos`, 1 a 86400) e de ter a chave recusada (`espera_chave_invalida_segundos`, 1 a 86400). `categoria` é obrigatória (`texto_para_texto`, `imagem_para_texto`, `texto_para_imagem`, `audio_para_texto`, `texto_para_audio`, `video_para_texto` ou `texto_para_video`) e só pode ter uma configuração; campo não enviado assume o padrão da categoria. Sem configuração, o gateway usa os padrões.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfigSystemGatewayCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfigSystemGateway>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_config_system_gateway(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfigSystemGatewayCriar,
) -> Result<tipos::ConfigSystemGateway, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::criar_config_system_gateway(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfigSystemGatewayCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfigSystemGatewayCriar", typeDescriptionLink: "#tipo-configsystemgatewaycriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfigSystemGateway>` · Rust: `Result<tipos::ConfigSystemGateway, ErroAoChamarServico>` · veja [`ConfigSystemGateway`](#tipo-configsystemgateway).

## `buscar_auto_complete_config_system_gateway` [#buscar_auto_complete_config_system_gateway]

<Rota metodo="GET" caminho="/config_system_gateway/autocomplete" credencial />

Lista básica das regras do gateway para seleção

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve só id e categoria, em ordem alfabética da categoria, sem as excluídas. `busca` procura o trecho no nome da categoria. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConfigSystemGateway = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfigSystemGatewayAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_config_system_gateway(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConfigSystemGateway,
) -> Result<tipos::PaginaConfigSystemGatewayAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_auto_complete_config_system_gateway(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarAutoCompleteConfigSystemGateway { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfigSystemGatewayAutoComplete>` · Rust: `Result<tipos::PaginaConfigSystemGatewayAutoComplete, ErroAoChamarServico>` · veja [`PaginaConfigSystemGatewayAutoComplete`](#tipo-paginaconfigsystemgatewayautocomplete).

## `buscar_pelo_filtro_config_system_gateway` [#buscar_pelo_filtro_config_system_gateway]

<Rota metodo="GET" caminho="/config_system_gateway/filtro" credencial />

Busca as regras do gateway por categoria

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve as configurações não excluídas, sem paginação, na ordem de cadastro. `categoria` precisa ser igual ao nome da categoria (por exemplo `texto_para_texto`); sem filtro, devolve todas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroConfigSystemGateway = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ConfigSystemGateway>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_config_system_gateway(credencial_de_acesso, { categoria: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroConfigSystemGateway,
) -> Result<Vec<tipos::ConfigSystemGateway>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_config_system_gateway(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroConfigSystemGateway { categoria: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ConfigSystemGateway>>` · Rust: `Result<Vec<tipos::ConfigSystemGateway>, ErroAoChamarServico>`

## `buscar_pelo_id_config_system_gateway` [#buscar_pelo_id_config_system_gateway]

<Rota metodo="GET" caminho="/config_system_gateway/{id}" credencial />

Busca as regras do gateway pelo id

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve a configuração do gateway de uma categoria, com os tempos em segundos. Configuração excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfigSystemGateway>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_config_system_gateway(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ConfigSystemGateway, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_config_system_gateway(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfigSystemGateway>` · Rust: `Result<tipos::ConfigSystemGateway, ErroAoChamarServico>` · veja [`ConfigSystemGateway`](#tipo-configsystemgateway).

## `atualizar_pelo_id_config_system_gateway` [#atualizar_pelo_id_config_system_gateway]

<Rota metodo="PATCH" caminho="/config_system_gateway/{id}" credencial />

Atualiza as regras do gateway pelo id

Exige a permissão `editar` da área `configuracoes`. Atualização parcial: só os tempos enviados mudam, nas mesmas faixas do cadastro, e o prazo total continua maior ou igual ao tempo por tentativa. A categoria não muda.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ConfigSystemGatewayAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfigSystemGateway>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_config_system_gateway(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ConfigSystemGatewayAtualizar,
) -> Result<tipos::ConfigSystemGateway, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::atualizar_pelo_id_config_system_gateway(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ConfigSystemGatewayAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfigSystemGatewayAtualizar", typeDescriptionLink: "#tipo-configsystemgatewayatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfigSystemGateway>` · Rust: `Result<tipos::ConfigSystemGateway, ErroAoChamarServico>` · veja [`ConfigSystemGateway`](#tipo-configsystemgateway).

## `deletar_pelo_id_config_system_gateway` [#deletar_pelo_id_config_system_gateway]

<Rota metodo="DELETE" caminho="/config_system_gateway/{id}" credencial />

Exclui as regras do gateway pelo id

Exige a permissão `deletar` da área `configuracoes`. Exclusão lógica: a categoria volta a usar as regras padrão do gateway e pode ganhar uma configuração nova. Excluir de novo responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_config_system_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_config_system_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_config_system_gateway(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_config_system_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::ai::deletar_pelo_id_config_system_gateway(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ConfigSystemGateway [#tipo-configsystemgateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemGateway } from "termo_core/ai";

export interface ConfigSystemGateway {
  atualizado_em: string;
  categoria: string;
  criado_em: string;
  espera_chave_invalida_segundos: number;
  espera_cota_diaria_segundos: number;
  espera_falha_segundos: number;
  espera_limite_segundos: number;
  id: string;
  maximo_tentativas: number;
  prazo_total_segundos: number;
  tempo_limite_segundos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConfigSystemGateway;

pub struct ConfigSystemGateway {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub espera_chave_invalida_segundos: i32,
    pub espera_cota_diaria_segundos: i32,
    pub espera_falha_segundos: i32,
    pub espera_limite_segundos: i32,
    pub id: uuid::Uuid,
    pub maximo_tentativas: i32,
    pub prazo_total_segundos: i32,
    pub tempo_limite_segundos: i32,
}
```

</Tab>
</Tabs>

### ConfigSystemGatewayAtualizar [#tipo-configsystemgatewayatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemGatewayAtualizar } from "termo_core/ai";

export type ConfigSystemGatewayAtualizar = ValoresDoGateway;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConfigSystemGatewayAtualizar;

pub type ConfigSystemGatewayAtualizar = ValoresDoGateway;
```

</Tab>
</Tabs>

### ConfigSystemGatewayCriar [#tipo-configsystemgatewaycriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemGatewayCriar } from "termo_core/ai";

export type ConfigSystemGatewayCriar = ValoresDoGateway & ConfigSystemGatewayCriarParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConfigSystemGatewayCriar;

pub type ConfigSystemGatewayCriar = serde_json::Value;
```

</Tab>
</Tabs>

### ConfigSystemGatewayCriarParte2 [#tipo-configsystemgatewaycriarparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemGatewayCriarParte2 } from "termo_core/ai";

export interface ConfigSystemGatewayCriarParte2 {
  categoria: string;
}
```

</Tab>
<Tab value="Rust">

`termo_core::ai::ConfigSystemGatewayCriarParte2`

</Tab>
</Tabs>

### PaginaConfigSystemGateway [#tipo-paginaconfigsystemgateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemGateway } from "termo_core/ai";

export interface PaginaConfigSystemGateway {
  itens: Array<PaginaConfigSystemGatewayItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConfigSystemGateway;

pub struct PaginaConfigSystemGateway {
    pub itens: Vec<PaginaConfigSystemGatewayItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemGatewayAutoComplete [#tipo-paginaconfigsystemgatewayautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemGatewayAutoComplete } from "termo_core/ai";

export interface PaginaConfigSystemGatewayAutoComplete {
  itens: Array<PaginaConfigSystemGatewayAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConfigSystemGatewayAutoComplete;

pub struct PaginaConfigSystemGatewayAutoComplete {
    pub itens: Vec<PaginaConfigSystemGatewayAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemGatewayAutoCompleteItensItem [#tipo-paginaconfigsystemgatewayautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemGatewayAutoCompleteItensItem } from "termo_core/ai";

export interface PaginaConfigSystemGatewayAutoCompleteItensItem {
  categoria: string;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConfigSystemGatewayAutoCompleteItensItem;

pub struct PaginaConfigSystemGatewayAutoCompleteItensItem {
    pub categoria: String,
    pub id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemGatewayItensItem [#tipo-paginaconfigsystemgatewayitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemGatewayItensItem } from "termo_core/ai";

export interface PaginaConfigSystemGatewayItensItem {
  atualizado_em: string;
  categoria: string;
  criado_em: string;
  espera_chave_invalida_segundos: number;
  espera_cota_diaria_segundos: number;
  espera_falha_segundos: number;
  espera_limite_segundos: number;
  id: string;
  maximo_tentativas: number;
  prazo_total_segundos: number;
  tempo_limite_segundos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConfigSystemGatewayItensItem;

pub struct PaginaConfigSystemGatewayItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub espera_chave_invalida_segundos: i32,
    pub espera_cota_diaria_segundos: i32,
    pub espera_falha_segundos: i32,
    pub espera_limite_segundos: i32,
    pub id: uuid::Uuid,
    pub maximo_tentativas: i32,
    pub prazo_total_segundos: i32,
    pub tempo_limite_segundos: i32,
}
```

</Tab>
</Tabs>

### ValoresDoGateway [#tipo-valoresdogateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValoresDoGateway } from "termo_core/ai";

export interface ValoresDoGateway {
  espera_chave_invalida_segundos?: number | null;
  espera_cota_diaria_segundos?: number | null;
  espera_falha_segundos?: number | null;
  espera_limite_segundos?: number | null;
  maximo_tentativas?: number | null;
  prazo_total_segundos?: number | null;
  tempo_limite_segundos?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ValoresDoGateway;

pub struct ValoresDoGateway {
    pub espera_chave_invalida_segundos: Option<i32>,
    pub espera_cota_diaria_segundos: Option<i32>,
    pub espera_falha_segundos: Option<i32>,
    pub espera_limite_segundos: Option<i32>,
    pub maximo_tentativas: Option<i32>,
    pub prazo_total_segundos: Option<i32>,
    pub tempo_limite_segundos: Option<i32>,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/ai/configuracao)

> 2 funções do TermoAI para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao` | Busca a configuração do app (segredo do TermoAuth) |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao` | Grava o segredo do app gerado no TermoAuth |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Busca a configuração do app (segredo do TermoAuth)

Só para master do TermoAuth. Devolve se o segredo do app gerado no TermoAuth (`segredo_do_app_gerado_no_termo_auth`) está cadastrado e os 4 últimos caracteres mascarados, nunca o valor. O segredo fica cifrado no banco com AES-256-GCM (chave derivada de `GLOBAL_SECRET_CRIPTOGRAFIA`); sem essa variável no servidor, `criptografia_configurada` vem `false` e o segredo aparece como não configurado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao" credencial />

Grava o segredo do app gerado no TermoAuth

Só para master do TermoAuth. Campo ausente não muda, string troca o segredo (até 2.000 caracteres, sem quebra de linha) e `null` limpa. O valor é cifrado antes de ir ao banco e entregue na hora ao `termo_core`, sem deploy.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/ai";

export interface Configuracao {
  atualizado_em: string;
  atualizado_por?: string | null;
  criptografia_configurada: boolean;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Configuracao;

pub struct Configuracao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub atualizado_por: Option<String>,
    pub criptografia_configurada: bool,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/ai";

export interface ConfiguracaoAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/ai";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Conversa (/docs/servicos/ai/conversa)

> 7 funções do TermoAI para conversa.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_conversa`](#buscar_paginador_conversa) | `GET /conversa` | Lista as conversas paginadas |
| [`criar_conversa`](#criar_conversa) | `POST /conversa` | Abre uma conversa vazia |
| [`buscar_auto_complete_conversa`](#buscar_auto_complete_conversa) | `GET /conversa/autocomplete` | Lista básica de conversas para seleção |
| [`buscar_pelo_filtro_conversa`](#buscar_pelo_filtro_conversa) | `GET /conversa/filtro` | Busca conversas por filtro |
| [`buscar_pelo_id_conversa`](#buscar_pelo_id_conversa) | `GET /conversa/{id}` | Busca uma conversa pelo id, com as mensagens |
| [`atualizar_pelo_id_conversa`](#atualizar_pelo_id_conversa) | `PATCH /conversa/{id}` | Atualiza o título, a IA ou a instrução de uma conversa |
| [`deletar_pelo_id_conversa`](#deletar_pelo_id_conversa) | `DELETE /conversa/{id}` | Exclui uma conversa pelo id |

## `buscar_paginador_conversa` [#buscar_paginador_conversa]

<Rota metodo="GET" caminho="/conversa" credencial />

Lista as conversas paginadas

Exige qualquer permissão da área `conversas` (qualquer ação liberada na área já libera a leitura). Lista o resumo (sem as mensagens, com a quantidade delas) das conversas não excluídas, da atualizada mais recentemente para a mais antiga. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 20, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de conversas não excluídas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorConversa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConversaResumo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_conversa(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorConversa,
) -> Result<tipos::PaginaConversaResumo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_conversa(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorConversa { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConversaResumo>` · Rust: `Result<tipos::PaginaConversaResumo, ErroAoChamarServico>` · veja [`PaginaConversaResumo`](#tipo-paginaconversaresumo).

## `criar_conversa` [#criar_conversa]

<Rota metodo="POST" caminho="/conversa" credencial />

Abre uma conversa vazia

Exige a permissão `criar` da área `conversas`. Abre uma conversa de quem chama, com origem `painel` e sem mensagens; as mensagens entram pelo `POST /gateway` com o `conversa_id`. `categoria` é obrigatória (`texto_para_texto`, `imagem_para_texto`, `texto_para_imagem`, `audio_para_texto`, `texto_para_audio`, `video_para_texto` ou `texto_para_video`). `provedor` fixa uma IA que atenda a categoria (por exemplo `gemini`); vazio ou ausente deixa o gateway escolher. `instrucao` vai até 4000 caracteres e `titulo` até 120 (vazio vira "Nova conversa").

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConversaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Conversa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_conversa(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConversaCriar,
) -> Result<tipos::Conversa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::criar_conversa(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConversaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConversaCriar", typeDescriptionLink: "#tipo-conversacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Conversa>` · Rust: `Result<tipos::Conversa, ErroAoChamarServico>` · veja [`Conversa`](#tipo-conversa).

## `buscar_auto_complete_conversa` [#buscar_auto_complete_conversa]

<Rota metodo="GET" caminho="/conversa/autocomplete" credencial />

Lista básica de conversas para seleção

Exige qualquer permissão da área `conversas` (qualquer ação liberada na área já libera a leitura). Devolve só id e título, em ordem alfabética do título, sem as excluídas. `busca` procura o trecho no título, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConversa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConversaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_conversa(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConversa,
) -> Result<tipos::PaginaConversaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_auto_complete_conversa(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarAutoCompleteConversa { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConversaAutoComplete>` · Rust: `Result<tipos::PaginaConversaAutoComplete, ErroAoChamarServico>` · veja [`PaginaConversaAutoComplete`](#tipo-paginaconversaautocomplete).

## `buscar_pelo_filtro_conversa` [#buscar_pelo_filtro_conversa]

<Rota metodo="GET" caminho="/conversa/filtro" credencial />

Busca conversas por filtro

Exige qualquer permissão da área `conversas` (qualquer ação liberada na área já libera a leitura). Devolve o resumo (sem as mensagens, com a quantidade delas) de no máximo 200 conversas não excluídas, da atualizada mais recentemente para a mais antiga, sem paginação. `busca` procura o trecho no título ou no e-mail de quem abriu, sem diferenciar maiúsculas. `categoria`, `provedor` (id da IA) e `origem` (`painel` ou `api`) precisam ser iguais.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroConversa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ConversaResumo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_conversa(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroConversa,
) -> Result<Vec<tipos::ConversaResumo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_conversa(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroConversa { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.provedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.origem": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ConversaResumo>>` · Rust: `Result<Vec<tipos::ConversaResumo>, ErroAoChamarServico>`

## `buscar_pelo_id_conversa` [#buscar_pelo_id_conversa]

<Rota metodo="GET" caminho="/conversa/{id}" credencial />

Busca uma conversa pelo id, com as mensagens

Exige qualquer permissão da área `conversas` (qualquer ação liberada na área já libera a leitura); as conversas não são filtradas por pessoa. Devolve a conversa inteira: título, categoria, IA fixada, instrução, origem (`painel` ou `api`), e-mail de quem abriu e as mensagens em ordem (`papel` `usuario` ou `assistente`, texto, arquivo guardado no TermoBucket com `arquivo_id` e `url` de download assinada por 15 minutos (sem o TermoBucket, em base64 quando tem até 5 MB), IA, modelo, apelido da chave, erro, duração e tentativas que falharam). Conversa excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Conversa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_conversa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Conversa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_conversa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Conversa>` · Rust: `Result<tipos::Conversa, ErroAoChamarServico>` · veja [`Conversa`](#tipo-conversa).

## `atualizar_pelo_id_conversa` [#atualizar_pelo_id_conversa]

<Rota metodo="PATCH" caminho="/conversa/{id}" credencial />

Atualiza o título, a IA ou a instrução de uma conversa

Exige a permissão `editar` da área `conversas`. Atualização parcial: só os campos enviados mudam; categoria e mensagens não mudam por aqui. `titulo` vai até 120 caracteres (vazio vira "Nova conversa"). `provedor` precisa atender a categoria da conversa; texto vazio volta à escolha automática do gateway. `instrucao` vai até 4000 caracteres; texto vazio apaga a instrução.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ConversaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Conversa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_conversa(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ConversaAtualizar,
) -> Result<tipos::Conversa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::atualizar_pelo_id_conversa(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ConversaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConversaAtualizar", typeDescriptionLink: "#tipo-conversaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Conversa>` · Rust: `Result<tipos::Conversa, ErroAoChamarServico>` · veja [`Conversa`](#tipo-conversa).

## `deletar_pelo_id_conversa` [#deletar_pelo_id_conversa]

<Rota metodo="DELETE" caminho="/conversa/{id}" credencial />

Exclui uma conversa pelo id

Exige a permissão `deletar` da área `conversas`. Exclusão lógica: a conversa sai das leituras e não recebe mais mensagens pelo gateway. Excluir de novo responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_conversa } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_conversa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::ai::deletar_pelo_id_conversa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ArquivoDaMensagem [#tipo-arquivodamensagem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivoDaMensagem } from "termo_core/ai";

export interface ArquivoDaMensagem {
  arquivo_id?: string | null;
  base64?: string | null;
  nome?: string | null;
  tamanho?: number | null;
  tipo_mime: string;
  url?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ArquivoDaMensagem;

pub struct ArquivoDaMensagem {
    pub arquivo_id: Option<uuid::Uuid>,
    pub base64: Option<String>,
    pub nome: Option<String>,
    pub tamanho: Option<i64>,
    pub tipo_mime: String,
    pub url: Option<String>,
}
```

</Tab>
</Tabs>

### ChamadaDaMensagem [#tipo-chamadadamensagem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChamadaDaMensagem } from "termo_core/ai";

export interface ChamadaDaMensagem {
  argumentos?: unknown;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChamadaDaMensagem;

pub struct ChamadaDaMensagem {
    pub argumentos: Option<serde_json::Value>,
    pub id: String,
    pub nome: String,
}
```

</Tab>
</Tabs>

### Conversa [#tipo-conversa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Conversa } from "termo_core/ai";

export interface Conversa {
  aplicativo?: string | null;
  atualizado_em: string;
  categoria: string;
  criado_em: string;
  email?: string | null;
  id: string;
  instrucao?: string | null;
  mensagens: Array<MensagemDaConversa>;
  origem: string;
  provedor?: string | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Conversa;

pub struct Conversa {
    pub aplicativo: Option<String>,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: Option<String>,
    pub id: uuid::Uuid,
    pub instrucao: Option<String>,
    pub mensagens: Vec<MensagemDaConversa>,
    pub origem: String,
    pub provedor: Option<String>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### ConversaAtualizar [#tipo-conversaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConversaAtualizar } from "termo_core/ai";

export interface ConversaAtualizar {
  instrucao?: string | null;
  provedor?: string | null;
  titulo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConversaAtualizar;

pub struct ConversaAtualizar {
    pub instrucao: Option<String>,
    pub provedor: Option<String>,
    pub titulo: Option<String>,
}
```

</Tab>
</Tabs>

### ConversaCriar [#tipo-conversacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConversaCriar } from "termo_core/ai";

export interface ConversaCriar {
  categoria: string;
  instrucao?: string | null;
  provedor?: string | null;
  titulo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConversaCriar;

pub struct ConversaCriar {
    pub categoria: String,
    pub instrucao: Option<String>,
    pub provedor: Option<String>,
    pub titulo: Option<String>,
}
```

</Tab>
</Tabs>

### ConversaResumo [#tipo-conversaresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConversaResumo } from "termo_core/ai";

export interface ConversaResumo {
  aplicativo?: string | null;
  atualizado_em: string;
  categoria: string;
  criado_em: string;
  email?: string | null;
  id: string;
  origem: string;
  provedor?: string | null;
  quantidade_mensagens: number;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ConversaResumo;

pub struct ConversaResumo {
    pub aplicativo: Option<String>,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: Option<String>,
    pub id: uuid::Uuid,
    pub origem: String,
    pub provedor: Option<String>,
    pub quantidade_mensagens: i32,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### MensagemDaConversa [#tipo-mensagemdaconversa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { MensagemDaConversa } from "termo_core/ai";

export interface MensagemDaConversa {
  arquivo?: ArquivoDaMensagem | null;
  chamadas_de_ferramenta?: Array<ChamadaDaMensagem>;
  chave?: string | null;
  criado_em: string;
  duracao_ms?: number | null;
  erro?: string | null;
  modelo?: string | null;
  papel: string;
  provedor?: string | null;
  tentativas?: Array<TentativaDaMensagem>;
  texto?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::MensagemDaConversa;

pub struct MensagemDaConversa {
    pub arquivo: Option<ArquivoDaMensagem>,
    pub chamadas_de_ferramenta: Option<Vec<ChamadaDaMensagem>>,
    pub chave: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub duracao_ms: Option<i64>,
    pub erro: Option<String>,
    pub modelo: Option<String>,
    pub papel: String,
    pub provedor: Option<String>,
    pub tentativas: Option<Vec<TentativaDaMensagem>>,
    pub texto: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaConversaAutoComplete [#tipo-paginaconversaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaAutoComplete } from "termo_core/ai";

export interface PaginaConversaAutoComplete {
  itens: Array<PaginaConversaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConversaAutoComplete;

pub struct PaginaConversaAutoComplete {
    pub itens: Vec<PaginaConversaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConversaAutoCompleteItensItem [#tipo-paginaconversaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaAutoCompleteItensItem } from "termo_core/ai";

export interface PaginaConversaAutoCompleteItensItem {
  id: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConversaAutoCompleteItensItem;

pub struct PaginaConversaAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### PaginaConversaResumo [#tipo-paginaconversaresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaResumo } from "termo_core/ai";

export interface PaginaConversaResumo {
  itens: Array<PaginaConversaResumoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConversaResumo;

pub struct PaginaConversaResumo {
    pub itens: Vec<PaginaConversaResumoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConversaResumoItensItem [#tipo-paginaconversaresumoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaResumoItensItem } from "termo_core/ai";

export interface PaginaConversaResumoItensItem {
  aplicativo?: string | null;
  atualizado_em: string;
  categoria: string;
  criado_em: string;
  email?: string | null;
  id: string;
  origem: string;
  provedor?: string | null;
  quantidade_mensagens: number;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaConversaResumoItensItem;

pub struct PaginaConversaResumoItensItem {
    pub aplicativo: Option<String>,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: Option<String>,
    pub id: uuid::Uuid,
    pub origem: String,
    pub provedor: Option<String>,
    pub quantidade_mensagens: i32,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### TentativaDaMensagem [#tipo-tentativadamensagem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TentativaDaMensagem } from "termo_core/ai";

export interface TentativaDaMensagem {
  chave: string;
  duracao_ms: number;
  erro: string;
  modelo: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::TentativaDaMensagem;

pub struct TentativaDaMensagem {
    pub chave: String,
    pub duracao_ms: i64,
    pub erro: String,
    pub modelo: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>


# Gateway (/docs/servicos/ai/gateway)

> 3 funções do TermoAI para gateway.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`chave_ia_buscar_catalogo`](#chave_ia_buscar_catalogo) | `GET /gateway` | Catálogo do gateway de IA |
| [`chave_ia_executar_gateway`](#chave_ia_executar_gateway) | `POST /gateway` | Executa um pedido no gateway de IA |
| [`chave_ia_buscar_modelos`](#chave_ia_buscar_modelos) | `GET /gateway/modelos` | Lista os modelos que o gateway pode usar agora |

## `chave_ia_buscar_catalogo` [#chave_ia_buscar_catalogo]

<Rota metodo="GET" caminho="/gateway" credencial />

Catálogo do gateway de IA

Exige qualquer permissão da área `gateway` (qualquer ação liberada na área já libera a leitura). Lista o que `POST /gateway` atende: cada categoria (`texto_para_texto`, `imagem_para_texto`, `texto_para_imagem`, `audio_para_texto`, `texto_para_audio`, `video_para_texto`, `texto_para_video`) com a descrição, o tipo de `entrada` e de `saida` (`texto`, `imagem`, `audio` ou `video`), quantas chaves estão livres agora e as IAs que a atendem com o modelo de cada uma; e cada IA com o nome, se exige conta, o fuso padrão da cota e as categorias que atende.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function chave_ia_buscar_catalogo(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.CatalogoDoGateway>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { chave_ia_buscar_catalogo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await chave_ia_buscar_catalogo(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn chave_ia_buscar_catalogo(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::CatalogoDoGateway, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::chave_ia_buscar_catalogo(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.CatalogoDoGateway>` · Rust: `Result<tipos::CatalogoDoGateway, ErroAoChamarServico>` · veja [`CatalogoDoGateway`](#tipo-catalogodogateway).

## `chave_ia_executar_gateway` [#chave_ia_executar_gateway]

<Rota metodo="POST" caminho="/gateway" credencial />

Executa um pedido no gateway de IA

Com token de usuário, exige a permissão `criar` da área `gateway`; com token de aplicativo (outro back-end, via `termo_core::CredencialDeAcesso::token_do_aplicativo()`), qualquer app válido do TermoAuth entra e a conversa nova grava o slug do app em `aplicativo`. Atende o pedido com as chaves de IA cadastradas, trocando de chave e de IA quando uma falha, até as regras da categoria (`/config_system_gateway`) mandarem parar. `categoria` é obrigatória. Nas categorias de entrada em texto, `texto` é obrigatório; nas de entrada em imagem, áudio ou vídeo, `arquivo` é obrigatório: `{ base64, tipo_mime }` (até 20 MB, aceita data URL) ou `{ url }` (baixada pelo TermoAI), e `texto` é a pergunta sobre o arquivo (sem ele vale uma pergunta padrão). `provedor` fixa uma IA que atenda a categoria (só ela, sem trocar de IA). `provedor_preferido` (um `provedor` de `GET /gateway/modelos`) tenta primeiro as chaves dessa IA e só troca para as outras, na ordem de sempre, quando ela falha ou não tem chave livre; sem ele, a escolha é a de sempre; com `provedor` junto, vale o `provedor`. `instrucao` é a instrução de sistema, `idioma` ajuda transcrição e fala, `voz` escolhe a voz da fala. `historico` (no máximo as 40 últimas mensagens com texto, `papel` `usuario` ou `assistente`) dá contexto; sem ele, com `conversa_id` (de uma conversa da mesma categoria), o contexto vem da própria conversa. A pergunta e a resposta são gravadas na conversa informada ou numa conversa nova de origem `api`, cujo id volta em `conversa_id`; os arquivos da pergunta e da resposta ficam no TermoBucket (privados, do app `termo-ai`). A resposta traz `texto` ou `arquivo` (base64 com o tipo), a IA, o modelo, o apelido da chave que atendeu, os tokens (quando a IA informa), as tentativas que falharam e a duração. Ferramentas (opcional, só em `texto_para_texto`): `ferramentas` lista até 128 funções (`nome` com até 64 letras, números, `_` ou `-`; `descricao`; `parametros` em JSON Schema) que a IA pode pedir para chamar; só entram as IAs que aceitam ferramentas (Gemini, Groq, Mistral, Cerebras, NVIDIA, Cohere, Z.ai e Ollama). Quando a IA quer uma ferramenta, a resposta traz `chamadas_de_ferramenta` (`id`, `nome`, `argumentos` em objeto e `assinatura`, que deve voltar igual) e, às vezes, `texto`. Quem chamou executa as ferramentas e pede de novo com o `historico` estendido: a mensagem `assistente` com as `chamadas_de_ferramenta` (e `texto`, vazio se não houver) e uma mensagem `ferramenta` por resultado, com `chamada_id` e o resultado em `texto`; quando o histórico termina num resultado, `texto` do pedido é opcional. Mensagens de ferramenta no histórico exigem `ferramentas` no pedido. A conversa gravada guarda as chamadas na mensagem do assistente, mas não os resultados.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function chave_ia_executar_gateway(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PedidoGateway,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.RespostaDoGateway>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { chave_ia_executar_gateway } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await chave_ia_executar_gateway(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn chave_ia_executar_gateway(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PedidoGateway,
) -> Result<tipos::RespostaDoGateway, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::chave_ia_executar_gateway(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PedidoGateway", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PedidoGateway", typeDescriptionLink: "#tipo-pedidogateway" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.RespostaDoGateway>` · Rust: `Result<tipos::RespostaDoGateway, ErroAoChamarServico>` · veja [`RespostaDoGateway`](#tipo-respostadogateway).

## `chave_ia_buscar_modelos` [#chave_ia_buscar_modelos]

<Rota metodo="GET" caminho="/gateway/modelos" credencial />

Lista os modelos que o gateway pode usar agora

Com token de usuário, exige qualquer permissão da área `gateway`; com token de aplicativo (outro back-end, via `termo_core::CredencialDeAcesso::token_do_aplicativo()`), qualquer app válido do TermoAuth entra. Serve para o app mostrar e deixar escolher a IA que vai em `provedor_preferido` do `POST /gateway`. `categoria` é opcional (padrão `texto_para_texto`). Só entram as IAs da categoria com ao menos uma chave ativa cadastrada, na ordem do catálogo. Cada item traz o id da IA (`provedor`, o valor de `provedor_preferido`), o nome da empresa (`empresa`), o `modelo` que o gateway usa nela, a `url_da_logo` (SVG servido pelo frontend do TermoAI; `logo_monocromatica` indica a logo de uma cor só, que deve ser pintada com a cor do texto), `gratuito` (todas as chaves ativas da IA são gratuitas; com uma paga já vira `false`), `aceita_ferramentas` e quantas chaves ativas a IA tem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function chave_ia_buscar_modelos(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeChaveIaBuscarModelos = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ModeloDoGateway>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { chave_ia_buscar_modelos } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await chave_ia_buscar_modelos(credencial_de_acesso, { categoria: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn chave_ia_buscar_modelos(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeChaveIaBuscarModelos,
) -> Result<Vec<tipos::ModeloDoGateway>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::chave_ia_buscar_modelos(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeChaveIaBuscarModelos { categoria: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ModeloDoGateway>>` · Rust: `Result<Vec<tipos::ModeloDoGateway>, ErroAoChamarServico>`

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Arquivo [#tipo-arquivo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Arquivo } from "termo_core/ai";

export interface Arquivo {
  base64: string;
  tipo_mime: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Arquivo;

pub struct Arquivo {
    pub base64: String,
    pub tipo_mime: String,
}
```

</Tab>
</Tabs>

### ArquivoDoPedido [#tipo-arquivodopedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivoDoPedido } from "termo_core/ai";

export interface ArquivoDoPedido {
  base64?: string | null;
  nome?: string | null;
  tipo_mime?: string | null;
  url?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ArquivoDoPedido;

pub struct ArquivoDoPedido {
    pub base64: Option<String>,
    pub nome: Option<String>,
    pub tipo_mime: Option<String>,
    pub url: Option<String>,
}
```

</Tab>
</Tabs>

### CatalogoDoGateway [#tipo-catalogodogateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CatalogoDoGateway } from "termo_core/ai";

export interface CatalogoDoGateway {
  categorias: Array<CategoriaDoCatalogo>;
  provedores: Array<ProvedorDoCatalogo>;
  rota: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::CatalogoDoGateway;

pub struct CatalogoDoGateway {
    pub categorias: Vec<CategoriaDoCatalogo>,
    pub provedores: Vec<ProvedorDoCatalogo>,
    pub rota: String,
}
```

</Tab>
</Tabs>

### CategoriaDoCatalogo [#tipo-categoriadocatalogo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CategoriaDoCatalogo } from "termo_core/ai";

export interface CategoriaDoCatalogo {
  categoria: string;
  chaves_disponiveis: number;
  descricao: string;
  entrada: string;
  provedores: Array<ProvedorDaCategoria>;
  saida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::CategoriaDoCatalogo;

pub struct CategoriaDoCatalogo {
    pub categoria: String,
    pub chaves_disponiveis: i64,
    pub descricao: String,
    pub entrada: String,
    pub provedores: Vec<ProvedorDaCategoria>,
    pub saida: String,
}
```

</Tab>
</Tabs>

### ChamadaDeFerramenta [#tipo-chamadadeferramenta]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ChamadaDeFerramenta } from "termo_core/ai";

export interface ChamadaDeFerramenta {
  argumentos?: unknown;
  assinatura?: string | null;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ChamadaDeFerramenta;

pub struct ChamadaDeFerramenta {
    pub argumentos: Option<serde_json::Value>,
    pub assinatura: Option<String>,
    pub id: String,
    pub nome: String,
}
```

</Tab>
</Tabs>

### Ferramenta [#tipo-ferramenta]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Ferramenta } from "termo_core/ai";

export interface Ferramenta {
  descricao?: string | null;
  nome: string;
  parametros?: unknown;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Ferramenta;

pub struct Ferramenta {
    pub descricao: Option<String>,
    pub nome: String,
    pub parametros: Option<serde_json::Value>,
}
```

</Tab>
</Tabs>

### MensagemDoHistorico [#tipo-mensagemdohistorico]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { MensagemDoHistorico } from "termo_core/ai";

export interface MensagemDoHistorico {
  chamada_id?: string | null;
  chamadas_de_ferramenta?: Array<ChamadaDeFerramenta>;
  papel: Papel;
  texto: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::MensagemDoHistorico;

pub struct MensagemDoHistorico {
    pub chamada_id: Option<String>,
    pub chamadas_de_ferramenta: Option<Vec<ChamadaDeFerramenta>>,
    pub papel: Papel,
    pub texto: String,
}
```

</Tab>
</Tabs>

### ModeloDoGateway [#tipo-modelodogateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ModeloDoGateway } from "termo_core/ai";

export interface ModeloDoGateway {
  aceita_ferramentas: boolean;
  chaves_ativas: number;
  empresa: string;
  gratuito: boolean;
  logo_monocromatica: boolean;
  modelo: string;
  provedor: string;
  url_da_logo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ModeloDoGateway;

pub struct ModeloDoGateway {
    pub aceita_ferramentas: bool,
    pub chaves_ativas: i64,
    pub empresa: String,
    pub gratuito: bool,
    pub logo_monocromatica: bool,
    pub modelo: String,
    pub provedor: String,
    pub url_da_logo: String,
}
```

</Tab>
</Tabs>

### Papel [#tipo-papel]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Papel } from "termo_core/ai";

export type Papel = "usuario" | "assistente" | "ferramenta";
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Papel;

pub enum Papel {
    #[serde(rename = "usuario")]
    Usuario,
    #[serde(rename = "assistente")]
    Assistente,
    #[serde(rename = "ferramenta")]
    Ferramenta,
}
```

</Tab>
</Tabs>

### PedidoGateway [#tipo-pedidogateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoGateway } from "termo_core/ai";

export interface PedidoGateway {
  arquivo?: ArquivoDoPedido | null;
  categoria: string;
  conversa_id?: string | null;
  ferramentas?: Array<Ferramenta> | null;
  historico?: Array<MensagemDoHistorico> | null;
  idioma?: string | null;
  instrucao?: string | null;
  provedor?: string | null;
  provedor_preferido?: string | null;
  texto?: string | null;
  voz?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PedidoGateway;

pub struct PedidoGateway {
    pub arquivo: Option<ArquivoDoPedido>,
    pub categoria: String,
    pub conversa_id: Option<uuid::Uuid>,
    pub ferramentas: Option<Vec<Ferramenta>>,
    pub historico: Option<Vec<MensagemDoHistorico>>,
    pub idioma: Option<String>,
    pub instrucao: Option<String>,
    pub provedor: Option<String>,
    pub provedor_preferido: Option<String>,
    pub texto: Option<String>,
    pub voz: Option<String>,
}
```

</Tab>
</Tabs>

### ProvedorDaCategoria [#tipo-provedordacategoria]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProvedorDaCategoria } from "termo_core/ai";

export interface ProvedorDaCategoria {
  modelo?: string | null;
  nome: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ProvedorDaCategoria;

pub struct ProvedorDaCategoria {
    pub modelo: Option<String>,
    pub nome: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### ProvedorDoCatalogo [#tipo-provedordocatalogo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProvedorDoCatalogo } from "termo_core/ai";

export interface ProvedorDoCatalogo {
  categorias: Array<string>;
  exige_conta: boolean;
  fuso_da_cota: string;
  nome: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::ProvedorDoCatalogo;

pub struct ProvedorDoCatalogo {
    pub categorias: Vec<String>,
    pub exige_conta: bool,
    pub fuso_da_cota: String,
    pub nome: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### RespostaDoGateway [#tipo-respostadogateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RespostaDoGateway } from "termo_core/ai";

export interface RespostaDoGateway {
  arquivo?: Arquivo | null;
  categoria: string;
  chamadas_de_ferramenta?: Array<ChamadaDeFerramenta> | null;
  chave: string;
  conversa_id?: string | null;
  duracao_ms: number;
  modelo: string;
  provedor: string;
  tentativas: Array<TentativaDaMensagem>;
  texto?: string | null;
  tokens?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::RespostaDoGateway;

pub struct RespostaDoGateway {
    pub arquivo: Option<Arquivo>,
    pub categoria: String,
    pub chamadas_de_ferramenta: Option<Vec<ChamadaDeFerramenta>>,
    pub chave: String,
    pub conversa_id: Option<uuid::Uuid>,
    pub duracao_ms: i64,
    pub modelo: String,
    pub provedor: String,
    pub tentativas: Vec<TentativaDaMensagem>,
    pub texto: Option<String>,
    pub tokens: Option<i64>,
}
```

</Tab>
</Tabs>

### TentativaDaMensagem [#tipo-tentativadamensagem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TentativaDaMensagem } from "termo_core/ai";

export interface TentativaDaMensagem {
  chave: string;
  duracao_ms: number;
  erro: string;
  modelo: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::TentativaDaMensagem;

pub struct TentativaDaMensagem {
    pub chave: String,
    pub duracao_ms: i64,
    pub erro: String,
    pub modelo: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>


# TermoAI (/docs/servicos/ai)

> Gateway de IA da Termotubos. POST /gateway atende pedidos de texto, imagem, áudio e vídeo com as chaves de IA cadastradas, trocando de chave e de IA quando uma falha, e grava cada pedido numa convers…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Gateway de IA da Termotubos. `POST /gateway` atende pedidos de texto, imagem, áudio e vídeo com as chaves de IA cadastradas, trocando de chave e de IA quando uma falha, e grava cada pedido numa conversa; o resto da API administra as chaves, as regras do gateway, as conversas, os colaboradores e os perfis de acesso. Tudo, menos `GET /`, `GET /test` e `GET /openapi.json`, usa o token do usuário logado no TermoAuth; `POST /gateway` e `GET /gateway/modelos` também aceitam o token de aplicativo de outro back-end.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::ai` (feature `ai`) |
| Importação TypeScript | `termo_core/ai` ou `import { ai } from "termo_core"` |
| Funções | 51 |
| Entidades | 11 |
| Versão do contrato | `0.1.18` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | o mesmo do sandbox (`https://sandbox-api-ai.termotubos.com.br`) |
| `SANDBOX` | `https://sandbox-api-ai.termotubos.com.br` |
| `PRODUCTION` | `https://api-ai.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Chave IA" href="/docs/servicos/ai/chave_ia" description="8 funções" />
  <Card title="Chave IA uso" href="/docs/servicos/ai/chave_ia_uso" description="2 funções" />
  <Card title="Conversa" href="/docs/servicos/ai/conversa" description="7 funções" />
  <Card title="Gateway" href="/docs/servicos/ai/gateway" description="3 funções" />
  <Card title="Preço modelo" href="/docs/servicos/ai/preco_modelo" description="7 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/ai/auth" description="1 função" />
  <Card title="Colaborador" href="/docs/servicos/ai/colaborador" description="5 funções" />
  <Card title="Config system gateway" href="/docs/servicos/ai/config_system_gateway" description="7 funções" />
  <Card title="Configuração" href="/docs/servicos/ai/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/ai/perfil_acesso" description="7 funções" />
  <Card title="Teste" href="/docs/servicos/ai/test" description="2 funções" />
</Cards>


# Perfil acesso (/docs/servicos/ai/perfil_acesso)

> 7 funções do TermoAI para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso com paginação |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcesso>` · Rust: `Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>` · veja [`PaginaPerfilAcesso`](#tipo-paginaperfilacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoAI dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`gateway`, `conversas`, `colaboradores`, `configuracoes`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoComplete`](#tipo-paginaperfilacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::ai::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/ai";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcesso [#tipo-paginaperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcesso } from "termo_core/ai";

export interface PaginaPerfilAcesso {
  itens: Array<PaginaPerfilAcessoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPerfilAcesso;

pub struct PaginaPerfilAcesso {
    pub itens: Vec<PaginaPerfilAcessoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoComplete [#tipo-paginaperfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoComplete } from "termo_core/ai";

export interface PaginaPerfilAcessoAutoComplete {
  itens: Array<PaginaPerfilAcessoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPerfilAcessoAutoComplete;

pub struct PaginaPerfilAcessoAutoComplete {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteItensItem [#tipo-paginaperfilacessoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteItensItem } from "termo_core/ai";

export interface PaginaPerfilAcessoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPerfilAcessoAutoCompleteItensItem;

pub struct PaginaPerfilAcessoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoItensItem [#tipo-paginaperfilacessoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoItensItem } from "termo_core/ai";

export interface PaginaPerfilAcessoItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPerfilAcessoItensItem;

pub struct PaginaPerfilAcessoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/ai";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/ai";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/ai";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/ai";

export interface Permissoes {
  colaboradores?: Acoes;
  configuracoes?: Acoes;
  conversas?: Acoes;
  gateway?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::Permissoes;

pub struct Permissoes {
    pub colaboradores: Option<Acoes>,
    pub configuracoes: Option<Acoes>,
    pub conversas: Option<Acoes>,
    pub gateway: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Preço modelo (/docs/servicos/ai/preco_modelo)

> 7 funções do TermoAI para preço modelo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_preco_modelo`](#buscar_paginador_preco_modelo) | `GET /preco_modelo` | Lista os preços de modelos paginados |
| [`criar_preco_modelo`](#criar_preco_modelo) | `POST /preco_modelo` | Cadastra o preço de um modelo de uma IA |
| [`buscar_auto_complete_preco_modelo`](#buscar_auto_complete_preco_modelo) | `GET /preco_modelo/autocomplete` | Lista básica de preços de modelos para seleção |
| [`buscar_pelo_filtro_preco_modelo`](#buscar_pelo_filtro_preco_modelo) | `GET /preco_modelo/filtro` | Busca preços de modelos por filtro |
| [`buscar_pelo_id_preco_modelo`](#buscar_pelo_id_preco_modelo) | `GET /preco_modelo/{id}` | Busca o preço de um modelo pelo id |
| [`atualizar_pelo_id_preco_modelo`](#atualizar_pelo_id_preco_modelo) | `PATCH /preco_modelo/{id}` | Atualiza o preço de um modelo |
| [`deletar_pelo_id_preco_modelo`](#deletar_pelo_id_preco_modelo) | `DELETE /preco_modelo/{id}` | Exclui o preço de um modelo |

## `buscar_paginador_preco_modelo` [#buscar_paginador_preco_modelo]

<Rota metodo="GET" caminho="/preco_modelo" credencial />

Lista os preços de modelos paginados

Exige qualquer permissão da área `gateway`. Ordena por IA e modelo. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 20.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPrecoModelo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPrecoModelo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_preco_modelo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPrecoModelo,
) -> Result<tipos::PaginaPrecoModelo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_paginador_preco_modelo(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPaginadorPrecoModelo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPrecoModelo>` · Rust: `Result<tipos::PaginaPrecoModelo, ErroAoChamarServico>` · veja [`PaginaPrecoModelo`](#tipo-paginaprecomodelo).

## `criar_preco_modelo` [#criar_preco_modelo]

<Rota metodo="POST" caminho="/preco_modelo" credencial />

Cadastra o preço de um modelo de uma IA

Exige a permissão `criar` da área `gateway`. O preço vale para todas as chaves da IA (`provedor`, do catálogo) que usarem o `modelo` (até 200 caracteres, sem diferenciar maiúsculas). `custo_entrada_por_milhao` e `custo_saida_por_milhao` são os R$ de 1M de tokens de entrada e de saída (0 a 1.000.000). Cada uso do gateway grava o preço da hora: numa chave paga vira gasto, numa gratuita vira economia. Usos anteriores ao cadastro continuam sem custo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PrecoModeloCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PrecoModelo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_preco_modelo(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PrecoModeloCriar,
) -> Result<tipos::PrecoModelo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::criar_preco_modelo(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PrecoModeloCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PrecoModeloCriar", typeDescriptionLink: "#tipo-precomodelocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PrecoModelo>` · Rust: `Result<tipos::PrecoModelo, ErroAoChamarServico>` · veja [`PrecoModelo`](#tipo-precomodelo).

## `buscar_auto_complete_preco_modelo` [#buscar_auto_complete_preco_modelo]

<Rota metodo="GET" caminho="/preco_modelo/autocomplete" credencial />

Lista básica de preços de modelos para seleção

Exige qualquer permissão da área `gateway`. Devolve id, IA e modelo em ordem alfabética do modelo. `busca` procura o trecho no modelo ou na IA. `pagina` começa em 1 e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePrecoModelo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPrecoModeloAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_preco_modelo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePrecoModelo,
) -> Result<tipos::PaginaPrecoModeloAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_auto_complete_preco_modelo(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarAutoCompletePrecoModelo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPrecoModeloAutoComplete>` · Rust: `Result<tipos::PaginaPrecoModeloAutoComplete, ErroAoChamarServico>` · veja [`PaginaPrecoModeloAutoComplete`](#tipo-paginaprecomodeloautocomplete).

## `buscar_pelo_filtro_preco_modelo` [#buscar_pelo_filtro_preco_modelo]

<Rota metodo="GET" caminho="/preco_modelo/filtro" credencial />

Busca preços de modelos por filtro

Exige qualquer permissão da área `gateway`. Devolve até 500 preços, por IA e modelo. `provedor` precisa ser igual ao id da IA; `modelo` procura o trecho, sem diferenciar maiúsculas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPrecoModelo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PrecoModelo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_preco_modelo(credencial_de_acesso, { provedor: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPrecoModelo,
) -> Result<Vec<tipos::PrecoModelo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_filtro_preco_modelo(
    &credencial_de_acesso,
    &termo_core::ai::ParametrosDeBuscarPeloFiltroPrecoModelo { provedor: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.provedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.modelo": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PrecoModelo>>` · Rust: `Result<Vec<tipos::PrecoModelo>, ErroAoChamarServico>`

## `buscar_pelo_id_preco_modelo` [#buscar_pelo_id_preco_modelo]

<Rota metodo="GET" caminho="/preco_modelo/{id}" credencial />

Busca o preço de um modelo pelo id

Exige qualquer permissão da área `gateway`. `chaves` é quantas chaves não excluídas da IA usam este preço.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PrecoModelo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_preco_modelo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PrecoModelo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::buscar_pelo_id_preco_modelo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PrecoModelo>` · Rust: `Result<tipos::PrecoModelo, ErroAoChamarServico>` · veja [`PrecoModelo`](#tipo-precomodelo).

## `atualizar_pelo_id_preco_modelo` [#atualizar_pelo_id_preco_modelo]

<Rota metodo="PATCH" caminho="/preco_modelo/{id}" credencial />

Atualiza o preço de um modelo

Exige a permissão `editar` da área `gateway`. Atualização parcial; a IA não muda. O preço novo vale de uma vez para todas as chaves da IA nos usos seguintes; o histórico guarda o preço da hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PrecoModeloAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PrecoModelo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_preco_modelo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PrecoModeloAtualizar,
) -> Result<tipos::PrecoModelo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::ai::atualizar_pelo_id_preco_modelo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PrecoModeloAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PrecoModeloAtualizar", typeDescriptionLink: "#tipo-precomodeloatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PrecoModelo>` · Rust: `Result<tipos::PrecoModelo, ErroAoChamarServico>` · veja [`PrecoModelo`](#tipo-precomodelo).

## `deletar_pelo_id_preco_modelo` [#deletar_pelo_id_preco_modelo]

<Rota metodo="DELETE" caminho="/preco_modelo/{id}" credencial />

Exclui o preço de um modelo

Exige a permissão `deletar` da área `gateway`. Exclusão lógica: os usos seguintes do modelo ficam sem custo; o histórico não muda.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_preco_modelo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_preco_modelo } from "termo_core/ai";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_preco_modelo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_preco_modelo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::ai::deletar_pelo_id_preco_modelo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaPrecoModelo [#tipo-paginaprecomodelo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPrecoModelo } from "termo_core/ai";

export interface PaginaPrecoModelo {
  itens: Array<PaginaPrecoModeloItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPrecoModelo;

pub struct PaginaPrecoModelo {
    pub itens: Vec<PaginaPrecoModeloItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPrecoModeloAutoComplete [#tipo-paginaprecomodeloautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPrecoModeloAutoComplete } from "termo_core/ai";

export interface PaginaPrecoModeloAutoComplete {
  itens: Array<PaginaPrecoModeloAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPrecoModeloAutoComplete;

pub struct PaginaPrecoModeloAutoComplete {
    pub itens: Vec<PaginaPrecoModeloAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPrecoModeloAutoCompleteItensItem [#tipo-paginaprecomodeloautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPrecoModeloAutoCompleteItensItem } from "termo_core/ai";

export interface PaginaPrecoModeloAutoCompleteItensItem {
  id: string;
  modelo: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPrecoModeloAutoCompleteItensItem;

pub struct PaginaPrecoModeloAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub modelo: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### PaginaPrecoModeloItensItem [#tipo-paginaprecomodeloitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPrecoModeloItensItem } from "termo_core/ai";

export interface PaginaPrecoModeloItensItem {
  atualizado_em: string;
  chaves: number;
  criado_em: string;
  custo_entrada_por_milhao: number;
  custo_saida_por_milhao: number;
  id: string;
  modelo: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PaginaPrecoModeloItensItem;

pub struct PaginaPrecoModeloItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chaves: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub custo_entrada_por_milhao: f64,
    pub custo_saida_por_milhao: f64,
    pub id: uuid::Uuid,
    pub modelo: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### PrecoModelo [#tipo-precomodelo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PrecoModelo } from "termo_core/ai";

export interface PrecoModelo {
  atualizado_em: string;
  chaves: number;
  criado_em: string;
  custo_entrada_por_milhao: number;
  custo_saida_por_milhao: number;
  id: string;
  modelo: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PrecoModelo;

pub struct PrecoModelo {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chaves: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub custo_entrada_por_milhao: f64,
    pub custo_saida_por_milhao: f64,
    pub id: uuid::Uuid,
    pub modelo: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>

### PrecoModeloAtualizar [#tipo-precomodeloatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PrecoModeloAtualizar } from "termo_core/ai";

export interface PrecoModeloAtualizar {
  custo_entrada_por_milhao?: number | null;
  custo_saida_por_milhao?: number | null;
  modelo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PrecoModeloAtualizar;

pub struct PrecoModeloAtualizar {
    pub custo_entrada_por_milhao: Option<f64>,
    pub custo_saida_por_milhao: Option<f64>,
    pub modelo: Option<String>,
}
```

</Tab>
</Tabs>

### PrecoModeloCriar [#tipo-precomodelocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PrecoModeloCriar } from "termo_core/ai";

export interface PrecoModeloCriar {
  custo_entrada_por_milhao: number;
  custo_saida_por_milhao: number;
  modelo: string;
  provedor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::PrecoModeloCriar;

pub struct PrecoModeloCriar {
    pub custo_entrada_por_milhao: f64,
    pub custo_saida_por_milhao: f64,
    pub modelo: String,
    pub provedor: String,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/ai/test)

> 2 funções do TermoAI para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as ai from "termo_core/ai";
// ou: import { ai } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["ai"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true` e a versão do backend que está publicada, no formato semver.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/ai";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::ai::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` sempre que o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/ai";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::ai::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/ai";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/ai";

export interface VersaoDoBackend {
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::ai::VersaoDoBackend;

pub struct VersaoDoBackend {
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>


# App (/docs/servicos/auth/app)

> 6 funções do TermoAuth para app.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_app`](#buscar_paginador_app) | `GET /app` | Lista apps com paginação |
| [`criar_app`](#criar_app) | `POST /app` | Cadastra um app |
| [`buscar_auto_complete_app`](#buscar_auto_complete_app) | `GET /app/autocomplete` | Lista básica de apps para seleção |
| [`buscar_pelo_filtro_app`](#buscar_pelo_filtro_app) | `GET /app/filtro` | Busca apps por filtro |
| [`buscar_pelo_id_app`](#buscar_pelo_id_app) | `GET /app/{id}` | Busca um app pelo id |
| [`atualizar_pelo_id_app`](#atualizar_pelo_id_app) | `PATCH /app/{id}` | Atualiza um app pelo id |

## `buscar_paginador_app` [#buscar_paginador_app]

<Rota metodo="GET" caminho="/app" credencial />

Lista apps com paginação

Na ordem de exibição. Sem `todos`, devolve só os apps que o perfil de quem chama pode abrir e que aparecem na lista do ambiente atual, como o `/apps`. Com `todos=true`, que exige o token de um master, devolve todos os cadastrados, como o `/master/apps`. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 50 e máximo 500. `busca` procura no nome, no id e no setor. Os links rápidos (`endereco_repositorio`, `endereco_diagrama_banco`, `endereco_documentacao`, `endereco_openapi`) só vêm preenchidos para master.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_app(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorApp = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaApp>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_app } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_app(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_app(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorApp,
) -> Result<tipos::PaginaApp, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_paginador_app(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorApp { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.acesso": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.todos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaApp>` · Rust: `Result<tipos::PaginaApp, ErroAoChamarServico>` · veja [`PaginaApp`](#tipo-paginaapp).

## `criar_app` [#criar_app]

<Rota metodo="POST" caminho="/app" credencial />

Cadastra um app

Só master. `id` é o slug usado em `?app=<id>`: letras minúsculas, números e hífens, até 40 caracteres, e não pode ser `settings`. `perfis` lista quem pode abrir o app (`colaborador`, `cliente`, pelo menos um); `acesso` é `autenticado`, `em_hospedagem`, `em_desenvolvimento` ou `link_externo`. `cor` no formato `#rrggbb`; endereços começam com `http://` ou `https://`; `caminho_inicial` começa com `/`. `endereco_repositorio`, `endereco_diagrama_banco`, `endereco_documentacao` e `endereco_openapi` são os links rápidos da TI, opcionais. Cadastrar o id de um app excluído o traz de volta. Vale na hora, sem reiniciar nada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_app(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AppCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.App>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_app } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_app(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_app(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AppCriar,
) -> Result<tipos::App, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::criar_app(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AppCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AppCriar", typeDescriptionLink: "#tipo-appcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.App>` · Rust: `Result<tipos::App, ErroAoChamarServico>` · veja [`App`](#tipo-app).

## `buscar_auto_complete_app` [#buscar_auto_complete_app]

<Rota metodo="GET" caminho="/app/autocomplete" credencial />

Lista básica de apps para seleção

Só master. Devolve só id, nome e setor, em ordem alfabética, para escolher um app. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10. `busca` procura no nome e no id.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_app(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteApp = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAppAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_app } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_app(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_app(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteApp,
) -> Result<tipos::PaginaAppAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_auto_complete_app(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarAutoCompleteApp { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAppAutoComplete>` · Rust: `Result<tipos::PaginaAppAutoComplete, ErroAoChamarServico>` · veja [`PaginaAppAutoComplete`](#tipo-paginaappautocomplete).

## `buscar_pelo_filtro_app` [#buscar_pelo_filtro_app]

<Rota metodo="GET" caminho="/app/filtro" credencial />

Busca apps por filtro

Só master. Devolve todos os apps que casam com o filtro, sem paginação, na ordem de exibição. `busca` procura no nome, no id e na descrição; `setor` compara sem diferenciar maiúsculas; `acesso` é `autenticado`, `em_hospedagem`, `em_desenvolvimento` ou `link_externo`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_app(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroApp = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.App>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_app } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_app(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_app(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroApp,
) -> Result<Vec<tipos::App>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_filtro_app(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPeloFiltroApp { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.acesso": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.App>>` · Rust: `Result<Vec<tipos::App>, ErroAoChamarServico>`

## `buscar_pelo_id_app` [#buscar_pelo_id_app]

<Rota metodo="GET" caminho="/app/{id}" credencial />

Busca um app pelo id

Sem token, só encontra os apps que têm porta de entrada no ambiente atual (`acesso` `autenticado` e endereço configurado). Com `todos=true`, que exige o token de um master, encontra qualquer app cadastrado. Os links rápidos (`endereco_repositorio`, `endereco_diagrama_banco`, `endereco_documentacao`, `endereco_openapi`) só vêm preenchidos com `todos=true`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_app(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  parametros: ParametrosDeBuscarPeloIdApp = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.App>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_app } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_app(credencial_de_acesso, id, { todos: true });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_app(
    credencial_de_acesso: &CredencialDeAcesso,
    id: &str,
    parametros: &ParametrosDeBuscarPeloIdApp,
) -> Result<tipos::App, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_id_app(
    &credencial_de_acesso,
    &id,
    &termo_core::auth::ParametrosDeBuscarPeloIdApp { todos: Some(true) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "parametros.todos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.App>` · Rust: `Result<tipos::App, ErroAoChamarServico>` · veja [`App`](#tipo-app).

## `atualizar_pelo_id_app` [#atualizar_pelo_id_app]

<Rota metodo="PATCH" caminho="/app/{id}" credencial />

Atualiza um app pelo id

Só master. Atualização parcial: só os campos enviados mudam, e o `id` não muda. As regras de cada campo são as mesmas do cadastro. O app `settings` não pode ser alterado. Vale na hora, sem reiniciar nada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_app(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AppAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.App>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_app } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_app(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_app(
    credencial_de_acesso: &CredencialDeAcesso,
    id: &str,
    corpo_da_requisicao: &tipos::AppAtualizar,
) -> Result<tipos::App, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::atualizar_pelo_id_app(
    &credencial_de_acesso,
    &id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "corpo_da_requisicao": { type: "tipos.AppAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AppAtualizar", typeDescriptionLink: "#tipo-appatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.App>` · Rust: `Result<tipos::App, ErroAoChamarServico>` · veja [`App`](#tipo-app).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### App [#tipo-app]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { App } from "termo_core/auth";

export interface App {
  acesso: string;
  atualizado_em: string;
  caminho_inicial: string;
  cor: string;
  criado_em: string;
  descricao: string;
  disponivel: boolean;
  e_app_conta: boolean;
  endereco: string;
  endereco_desenvolvimento: string;
  endereco_diagrama_banco: string;
  endereco_documentacao: string;
  endereco_entrada: string;
  endereco_openapi: string;
  endereco_producao: string;
  endereco_repositorio: string;
  endereco_sandbox: string;
  id: string;
  nome: string;
  ordem: number;
  perfis: Array<string>;
  setor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::App;

pub struct App {
    pub acesso: String,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub caminho_inicial: String,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub disponivel: bool,
    pub e_app_conta: bool,
    pub endereco: String,
    pub endereco_desenvolvimento: String,
    pub endereco_diagrama_banco: String,
    pub endereco_documentacao: String,
    pub endereco_entrada: String,
    pub endereco_openapi: String,
    pub endereco_producao: String,
    pub endereco_repositorio: String,
    pub endereco_sandbox: String,
    pub id: String,
    pub nome: String,
    pub ordem: i32,
    pub perfis: Vec<String>,
    pub setor: String,
}
```

</Tab>
</Tabs>

### AppAtualizar [#tipo-appatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AppAtualizar } from "termo_core/auth";

export interface AppAtualizar {
  acesso?: string | null;
  caminho_inicial?: string | null;
  cor?: string | null;
  descricao?: string | null;
  endereco_desenvolvimento?: string | null;
  endereco_diagrama_banco?: string | null;
  endereco_documentacao?: string | null;
  endereco_openapi?: string | null;
  endereco_producao?: string | null;
  endereco_repositorio?: string | null;
  endereco_sandbox?: string | null;
  nome?: string | null;
  ordem?: number | null;
  perfis?: Array<string> | null;
  setor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::AppAtualizar;

pub struct AppAtualizar {
    pub acesso: Option<String>,
    pub caminho_inicial: Option<String>,
    pub cor: Option<String>,
    pub descricao: Option<String>,
    pub endereco_desenvolvimento: Option<String>,
    pub endereco_diagrama_banco: Option<String>,
    pub endereco_documentacao: Option<String>,
    pub endereco_openapi: Option<String>,
    pub endereco_producao: Option<String>,
    pub endereco_repositorio: Option<String>,
    pub endereco_sandbox: Option<String>,
    pub nome: Option<String>,
    pub ordem: Option<i32>,
    pub perfis: Option<Vec<String>>,
    pub setor: Option<String>,
}
```

</Tab>
</Tabs>

### AppCriar [#tipo-appcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AppCriar } from "termo_core/auth";

export interface AppCriar {
  acesso: string;
  caminho_inicial?: string | null;
  cor?: string | null;
  descricao?: string | null;
  endereco_desenvolvimento?: string | null;
  endereco_diagrama_banco?: string | null;
  endereco_documentacao?: string | null;
  endereco_openapi?: string | null;
  endereco_producao?: string | null;
  endereco_repositorio?: string | null;
  endereco_sandbox?: string | null;
  id: string;
  nome: string;
  ordem?: number | null;
  perfis: Array<string>;
  setor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::AppCriar;

pub struct AppCriar {
    pub acesso: String,
    pub caminho_inicial: Option<String>,
    pub cor: Option<String>,
    pub descricao: Option<String>,
    pub endereco_desenvolvimento: Option<String>,
    pub endereco_diagrama_banco: Option<String>,
    pub endereco_documentacao: Option<String>,
    pub endereco_openapi: Option<String>,
    pub endereco_producao: Option<String>,
    pub endereco_repositorio: Option<String>,
    pub endereco_sandbox: Option<String>,
    pub id: String,
    pub nome: String,
    pub ordem: Option<i32>,
    pub perfis: Vec<String>,
    pub setor: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaApp [#tipo-paginaapp]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaApp } from "termo_core/auth";

export interface PaginaApp {
  itens: Array<PaginaAppItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaApp;

pub struct PaginaApp {
    pub itens: Vec<PaginaAppItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAppAutoComplete [#tipo-paginaappautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAppAutoComplete } from "termo_core/auth";

export interface PaginaAppAutoComplete {
  itens: Array<PaginaAppAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaAppAutoComplete;

pub struct PaginaAppAutoComplete {
    pub itens: Vec<PaginaAppAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAppAutoCompleteItensItem [#tipo-paginaappautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAppAutoCompleteItensItem } from "termo_core/auth";

export interface PaginaAppAutoCompleteItensItem {
  id: string;
  nome: string;
  setor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaAppAutoCompleteItensItem;

pub struct PaginaAppAutoCompleteItensItem {
    pub id: String,
    pub nome: String,
    pub setor: String,
}
```

</Tab>
</Tabs>

### PaginaAppItensItem [#tipo-paginaappitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAppItensItem } from "termo_core/auth";

export interface PaginaAppItensItem {
  acesso: string;
  atualizado_em: string;
  caminho_inicial: string;
  cor: string;
  criado_em: string;
  descricao: string;
  disponivel: boolean;
  e_app_conta: boolean;
  endereco: string;
  endereco_desenvolvimento: string;
  endereco_diagrama_banco: string;
  endereco_documentacao: string;
  endereco_entrada: string;
  endereco_openapi: string;
  endereco_producao: string;
  endereco_repositorio: string;
  endereco_sandbox: string;
  id: string;
  nome: string;
  ordem: number;
  perfis: Array<string>;
  setor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaAppItensItem;

pub struct PaginaAppItensItem {
    pub acesso: String,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub caminho_inicial: String,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub disponivel: bool,
    pub e_app_conta: bool,
    pub endereco: String,
    pub endereco_desenvolvimento: String,
    pub endereco_diagrama_banco: String,
    pub endereco_documentacao: String,
    pub endereco_entrada: String,
    pub endereco_openapi: String,
    pub endereco_producao: String,
    pub endereco_repositorio: String,
    pub endereco_sandbox: String,
    pub id: String,
    pub nome: String,
    pub ordem: i32,
    pub perfis: Vec<String>,
    pub setor: String,
}
```

</Tab>
</Tabs>


# Cargo (/docs/servicos/auth/cargo)

> 6 funções do TermoAuth para cargo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_cargo`](#buscar_paginador_cargo) | `GET /cargo` | Lista cargos com paginação |
| [`criar_cargo`](#criar_cargo) | `POST /cargo` | Cadastra um cargo |
| [`buscar_auto_complete_cargo`](#buscar_auto_complete_cargo) | `GET /cargo/autocomplete` | Lista básica de cargos para seleção |
| [`buscar_pelo_filtro_cargo`](#buscar_pelo_filtro_cargo) | `GET /cargo/filtro` | Busca cargos por filtro |
| [`buscar_pelo_id_cargo`](#buscar_pelo_id_cargo) | `GET /cargo/{id}` | Busca um cargo pelo id |
| [`atualizar_pelo_id_cargo`](#atualizar_pelo_id_cargo) | `PATCH /cargo/{id}` | Renomeia um cargo |

## `buscar_paginador_cargo` [#buscar_paginador_cargo]

<Rota metodo="GET" caminho="/cargo" credencial />

Lista cargos com paginação

Só master. Em ordem alfabética. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 500. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_cargo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCargo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCargo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_cargo } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_cargo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_cargo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCargo,
) -> Result<tipos::PaginaCargo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_paginador_cargo(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorCargo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCargo>` · Rust: `Result<tipos::PaginaCargo, ErroAoChamarServico>` · veja [`PaginaCargo`](#tipo-paginacargo).

## `criar_cargo` [#criar_cargo]

<Rota metodo="POST" caminho="/cargo" credencial />

Cadastra um cargo

Só master. `nome` é obrigatório, de 1 a 120 caracteres, e não pode repetir outro cargo (sem diferenciar maiúsculas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_cargo(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.CargoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cargo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_cargo } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_cargo(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_cargo(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::CargoCriar,
) -> Result<tipos::Cargo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::criar_cargo(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.CargoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::CargoCriar", typeDescriptionLink: "#tipo-cargocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cargo>` · Rust: `Result<tipos::Cargo, ErroAoChamarServico>` · veja [`Cargo`](#tipo-cargo).

## `buscar_auto_complete_cargo` [#buscar_auto_complete_cargo]

<Rota metodo="GET" caminho="/cargo/autocomplete" credencial />

Lista básica de cargos para seleção

Só master. Devolve só id e nome, em ordem alfabética. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 100. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_cargo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteCargo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCargoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_cargo } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_cargo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_cargo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteCargo,
) -> Result<tipos::PaginaCargoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_auto_complete_cargo(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarAutoCompleteCargo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCargoAutoComplete>` · Rust: `Result<tipos::PaginaCargoAutoComplete, ErroAoChamarServico>` · veja [`PaginaCargoAutoComplete`](#tipo-paginacargoautocomplete).

## `buscar_pelo_filtro_cargo` [#buscar_pelo_filtro_cargo]

<Rota metodo="GET" caminho="/cargo/filtro" credencial />

Busca cargos por filtro

Só master. Devolve todos os cargos que casam com o filtro, sem paginação, em ordem alfabética. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_cargo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroCargo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Cargo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_cargo } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_cargo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_cargo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroCargo,
) -> Result<Vec<tipos::Cargo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_filtro_cargo(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPeloFiltroCargo { busca: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Cargo>>` · Rust: `Result<Vec<tipos::Cargo>, ErroAoChamarServico>`

## `buscar_pelo_id_cargo` [#buscar_pelo_id_cargo]

<Rota metodo="GET" caminho="/cargo/{id}" credencial />

Busca um cargo pelo id

Só master. `quantidade_de_colaboradores` conta os usuários ligados ao cargo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_cargo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cargo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_cargo } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_cargo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_cargo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Cargo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_id_cargo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cargo>` · Rust: `Result<tipos::Cargo, ErroAoChamarServico>` · veja [`Cargo`](#tipo-cargo).

## `atualizar_pelo_id_cargo` [#atualizar_pelo_id_cargo]

<Rota metodo="PATCH" caminho="/cargo/{id}" credencial />

Renomeia um cargo

Só master. Renomear avisa os apps de novo sobre cada colaborador do cargo, porque eles recebem o nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_cargo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.CargoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cargo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_cargo } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_cargo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_cargo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::CargoAtualizar,
) -> Result<tipos::Cargo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::atualizar_pelo_id_cargo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.CargoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::CargoAtualizar", typeDescriptionLink: "#tipo-cargoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cargo>` · Rust: `Result<tipos::Cargo, ErroAoChamarServico>` · veja [`Cargo`](#tipo-cargo).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Cargo [#tipo-cargo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cargo } from "termo_core/auth";

export interface Cargo {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  quantidade_de_colaboradores: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::Cargo;

pub struct Cargo {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_colaboradores: i64,
}
```

</Tab>
</Tabs>

### CargoAtualizar [#tipo-cargoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CargoAtualizar } from "termo_core/auth";

export interface CargoAtualizar {
  nome?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::CargoAtualizar;

pub struct CargoAtualizar {
    pub nome: Option<String>,
}
```

</Tab>
</Tabs>

### CargoCriar [#tipo-cargocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CargoCriar } from "termo_core/auth";

export interface CargoCriar {
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::CargoCriar;

pub struct CargoCriar {
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaCargo [#tipo-paginacargo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCargo } from "termo_core/auth";

export interface PaginaCargo {
  itens: Array<PaginaCargoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaCargo;

pub struct PaginaCargo {
    pub itens: Vec<PaginaCargoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaCargoAutoComplete [#tipo-paginacargoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCargoAutoComplete } from "termo_core/auth";

export interface PaginaCargoAutoComplete {
  itens: Array<PaginaCargoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaCargoAutoComplete;

pub struct PaginaCargoAutoComplete {
    pub itens: Vec<PaginaCargoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaCargoAutoCompleteItensItem [#tipo-paginacargoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCargoAutoCompleteItensItem } from "termo_core/auth";

export interface PaginaCargoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaCargoAutoCompleteItensItem;

pub struct PaginaCargoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaCargoItensItem [#tipo-paginacargoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCargoItensItem } from "termo_core/auth";

export interface PaginaCargoItensItem {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  quantidade_de_colaboradores: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaCargoItensItem;

pub struct PaginaCargoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_colaboradores: i64,
}
```

</Tab>
</Tabs>


# Função (/docs/servicos/auth/funcao)

> 6 funções do TermoAuth para função.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_funcao`](#buscar_paginador_funcao) | `GET /funcao` | Lista funções com paginação |
| [`criar_funcao`](#criar_funcao) | `POST /funcao` | Cadastra uma função |
| [`buscar_auto_complete_funcao`](#buscar_auto_complete_funcao) | `GET /funcao/autocomplete` | Lista básica de funções para seleção |
| [`buscar_pelo_filtro_funcao`](#buscar_pelo_filtro_funcao) | `GET /funcao/filtro` | Busca funções por filtro |
| [`buscar_pelo_id_funcao`](#buscar_pelo_id_funcao) | `GET /funcao/{id}` | Busca uma função pelo id |
| [`atualizar_pelo_id_funcao`](#atualizar_pelo_id_funcao) | `PATCH /funcao/{id}` | Renomeia uma função |

## `buscar_paginador_funcao` [#buscar_paginador_funcao]

<Rota metodo="GET" caminho="/funcao" credencial />

Lista funções com paginação

Só master. Em ordem alfabética. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 500. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_funcao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorFuncao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFuncao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_funcao } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_funcao(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_funcao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorFuncao,
) -> Result<tipos::PaginaFuncao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_paginador_funcao(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorFuncao { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFuncao>` · Rust: `Result<tipos::PaginaFuncao, ErroAoChamarServico>` · veja [`PaginaFuncao`](#tipo-paginafuncao).

## `criar_funcao` [#criar_funcao]

<Rota metodo="POST" caminho="/funcao" credencial />

Cadastra uma função

Só master. `nome` é obrigatório, de 1 a 120 caracteres, e não pode repetir outra função (sem diferenciar maiúsculas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_funcao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.FuncaoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Funcao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_funcao } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_funcao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_funcao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::FuncaoCriar,
) -> Result<tipos::Funcao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::criar_funcao(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.FuncaoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::FuncaoCriar", typeDescriptionLink: "#tipo-funcaocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Funcao>` · Rust: `Result<tipos::Funcao, ErroAoChamarServico>` · veja [`Funcao`](#tipo-funcao).

## `buscar_auto_complete_funcao` [#buscar_auto_complete_funcao]

<Rota metodo="GET" caminho="/funcao/autocomplete" credencial />

Lista básica de funções para seleção

Só master. Devolve só id e nome, em ordem alfabética. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 100. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_funcao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteFuncao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFuncaoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_funcao } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_funcao(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_funcao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteFuncao,
) -> Result<tipos::PaginaFuncaoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_auto_complete_funcao(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarAutoCompleteFuncao { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFuncaoAutoComplete>` · Rust: `Result<tipos::PaginaFuncaoAutoComplete, ErroAoChamarServico>` · veja [`PaginaFuncaoAutoComplete`](#tipo-paginafuncaoautocomplete).

## `buscar_pelo_filtro_funcao` [#buscar_pelo_filtro_funcao]

<Rota metodo="GET" caminho="/funcao/filtro" credencial />

Busca funções por filtro

Só master. Devolve todas as funções que casam com o filtro, sem paginação, em ordem alfabética. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_funcao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroFuncao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Funcao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_funcao } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_funcao(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_funcao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroFuncao,
) -> Result<Vec<tipos::Funcao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_filtro_funcao(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPeloFiltroFuncao { busca: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Funcao>>` · Rust: `Result<Vec<tipos::Funcao>, ErroAoChamarServico>`

## `buscar_pelo_id_funcao` [#buscar_pelo_id_funcao]

<Rota metodo="GET" caminho="/funcao/{id}" credencial />

Busca uma função pelo id

Só master. `quantidade_de_colaboradores` conta os usuários ligados à função.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_funcao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Funcao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_funcao } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_funcao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_funcao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Funcao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_id_funcao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Funcao>` · Rust: `Result<tipos::Funcao, ErroAoChamarServico>` · veja [`Funcao`](#tipo-funcao).

## `atualizar_pelo_id_funcao` [#atualizar_pelo_id_funcao]

<Rota metodo="PATCH" caminho="/funcao/{id}" credencial />

Renomeia uma função

Só master. Renomear avisa os apps de novo sobre cada colaborador da função, porque eles recebem o nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_funcao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.FuncaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Funcao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_funcao } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_funcao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_funcao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::FuncaoAtualizar,
) -> Result<tipos::Funcao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::atualizar_pelo_id_funcao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.FuncaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::FuncaoAtualizar", typeDescriptionLink: "#tipo-funcaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Funcao>` · Rust: `Result<tipos::Funcao, ErroAoChamarServico>` · veja [`Funcao`](#tipo-funcao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Funcao [#tipo-funcao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Funcao } from "termo_core/auth";

export interface Funcao {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  quantidade_de_colaboradores: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::Funcao;

pub struct Funcao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_colaboradores: i64,
}
```

</Tab>
</Tabs>

### FuncaoAtualizar [#tipo-funcaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FuncaoAtualizar } from "termo_core/auth";

export interface FuncaoAtualizar {
  nome?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::FuncaoAtualizar;

pub struct FuncaoAtualizar {
    pub nome: Option<String>,
}
```

</Tab>
</Tabs>

### FuncaoCriar [#tipo-funcaocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FuncaoCriar } from "termo_core/auth";

export interface FuncaoCriar {
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::FuncaoCriar;

pub struct FuncaoCriar {
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaFuncao [#tipo-paginafuncao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncao } from "termo_core/auth";

export interface PaginaFuncao {
  itens: Array<PaginaFuncaoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaFuncao;

pub struct PaginaFuncao {
    pub itens: Vec<PaginaFuncaoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaFuncaoAutoComplete [#tipo-paginafuncaoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncaoAutoComplete } from "termo_core/auth";

export interface PaginaFuncaoAutoComplete {
  itens: Array<PaginaFuncaoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaFuncaoAutoComplete;

pub struct PaginaFuncaoAutoComplete {
    pub itens: Vec<PaginaFuncaoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaFuncaoAutoCompleteItensItem [#tipo-paginafuncaoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncaoAutoCompleteItensItem } from "termo_core/auth";

export interface PaginaFuncaoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaFuncaoAutoCompleteItensItem;

pub struct PaginaFuncaoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaFuncaoItensItem [#tipo-paginafuncaoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncaoItensItem } from "termo_core/auth";

export interface PaginaFuncaoItensItem {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  quantidade_de_colaboradores: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaFuncaoItensItem;

pub struct PaginaFuncaoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_colaboradores: i64,
}
```

</Tab>
</Tabs>


# TermoAuth (/docs/servicos/auth)

> Consulta de usuários, apps, setores, cargos e funções do serviço central de login da Termotubos. Toda chamada usa o token do usuário logado, e as permissões são as dele: quem não é master só enxerga…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Consulta de usuários, apps, setores, cargos e funções do serviço central de login da Termotubos. Toda chamada usa o token do usuário logado, e as permissões são as dele: quem não é master só enxerga o próprio usuário.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::auth` (feature `auth`) |
| Importação TypeScript | `termo_core/auth` ou `import { auth } from "termo_core"` |
| Funções | 29 |
| Entidades | 6 |
| Versão do contrato | `0.1.23` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51001` |
| `SANDBOX` | `https://sandbox-api-auth.termotubos.com.br` |
| `PRODUCTION` | `https://api-auth.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="App" href="/docs/servicos/auth/app" description="6 funções" />
  <Card title="Cargo" href="/docs/servicos/auth/cargo" description="6 funções" />
  <Card title="Função" href="/docs/servicos/auth/funcao" description="6 funções" />
  <Card title="Setor" href="/docs/servicos/auth/setor" description="6 funções" />
  <Card title="Token de app" href="/docs/servicos/auth/token_de_app" description="1 função" />
  <Card title="Usuário" href="/docs/servicos/auth/usuario" description="4 funções" />
</Cards>


# Setor (/docs/servicos/auth/setor)

> 6 funções do TermoAuth para setor.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_setor`](#buscar_paginador_setor) | `GET /setor` | Lista setores com paginação |
| [`criar_setor`](#criar_setor) | `POST /setor` | Cadastra um setor |
| [`buscar_auto_complete_setor`](#buscar_auto_complete_setor) | `GET /setor/autocomplete` | Lista básica de setores para seleção |
| [`buscar_pelo_filtro_setor`](#buscar_pelo_filtro_setor) | `GET /setor/filtro` | Busca setores por filtro |
| [`buscar_pelo_id_setor`](#buscar_pelo_id_setor) | `GET /setor/{id}` | Busca um setor pelo id |
| [`atualizar_pelo_id_setor`](#atualizar_pelo_id_setor) | `PATCH /setor/{id}` | Renomeia um setor |

## `buscar_paginador_setor` [#buscar_paginador_setor]

<Rota metodo="GET" caminho="/setor" credencial />

Lista setores com paginação

Só master. Em ordem alfabética. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 500. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_setor(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorSetor = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSetor>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_setor } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_setor(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_setor(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorSetor,
) -> Result<tipos::PaginaSetor, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_paginador_setor(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorSetor { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSetor>` · Rust: `Result<tipos::PaginaSetor, ErroAoChamarServico>` · veja [`PaginaSetor`](#tipo-paginasetor).

## `criar_setor` [#criar_setor]

<Rota metodo="POST" caminho="/setor" credencial />

Cadastra um setor

Só master. `nome` é obrigatório, de 1 a 120 caracteres, e não pode repetir outro setor (sem diferenciar maiúsculas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_setor(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.SetorCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Setor>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_setor } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_setor(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_setor(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::SetorCriar,
) -> Result<tipos::Setor, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::criar_setor(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.SetorCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SetorCriar", typeDescriptionLink: "#tipo-setorcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Setor>` · Rust: `Result<tipos::Setor, ErroAoChamarServico>` · veja [`Setor`](#tipo-setor).

## `buscar_auto_complete_setor` [#buscar_auto_complete_setor]

<Rota metodo="GET" caminho="/setor/autocomplete" credencial />

Lista básica de setores para seleção

Só master. Devolve só id e nome, em ordem alfabética. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 100. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_setor(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteSetor = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSetorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_setor } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_setor(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_setor(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteSetor,
) -> Result<tipos::PaginaSetorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_auto_complete_setor(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarAutoCompleteSetor { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSetorAutoComplete>` · Rust: `Result<tipos::PaginaSetorAutoComplete, ErroAoChamarServico>` · veja [`PaginaSetorAutoComplete`](#tipo-paginasetorautocomplete).

## `buscar_pelo_filtro_setor` [#buscar_pelo_filtro_setor]

<Rota metodo="GET" caminho="/setor/filtro" credencial />

Busca setores por filtro

Só master. Devolve todos os setores que casam com o filtro, sem paginação, em ordem alfabética. `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_setor(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroSetor = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Setor>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_setor } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_setor(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_setor(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroSetor,
) -> Result<Vec<tipos::Setor>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_filtro_setor(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPeloFiltroSetor { busca: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Setor>>` · Rust: `Result<Vec<tipos::Setor>, ErroAoChamarServico>`

## `buscar_pelo_id_setor` [#buscar_pelo_id_setor]

<Rota metodo="GET" caminho="/setor/{id}" credencial />

Busca um setor pelo id

Só master. `quantidade_de_colaboradores` conta os usuários ligados ao setor.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_setor(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Setor>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_setor } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_setor(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_setor(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Setor, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_id_setor(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Setor>` · Rust: `Result<tipos::Setor, ErroAoChamarServico>` · veja [`Setor`](#tipo-setor).

## `atualizar_pelo_id_setor` [#atualizar_pelo_id_setor]

<Rota metodo="PATCH" caminho="/setor/{id}" credencial />

Renomeia um setor

Só master. Renomear avisa os apps de novo sobre cada colaborador do setor, porque eles recebem o nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_setor(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.SetorAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Setor>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_setor } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_setor(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_setor(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::SetorAtualizar,
) -> Result<tipos::Setor, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::atualizar_pelo_id_setor(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.SetorAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SetorAtualizar", typeDescriptionLink: "#tipo-setoratualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Setor>` · Rust: `Result<tipos::Setor, ErroAoChamarServico>` · veja [`Setor`](#tipo-setor).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaSetor [#tipo-paginasetor]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSetor } from "termo_core/auth";

export interface PaginaSetor {
  itens: Array<PaginaSetorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaSetor;

pub struct PaginaSetor {
    pub itens: Vec<PaginaSetorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSetorAutoComplete [#tipo-paginasetorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSetorAutoComplete } from "termo_core/auth";

export interface PaginaSetorAutoComplete {
  itens: Array<PaginaSetorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaSetorAutoComplete;

pub struct PaginaSetorAutoComplete {
    pub itens: Vec<PaginaSetorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSetorAutoCompleteItensItem [#tipo-paginasetorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSetorAutoCompleteItensItem } from "termo_core/auth";

export interface PaginaSetorAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaSetorAutoCompleteItensItem;

pub struct PaginaSetorAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaSetorItensItem [#tipo-paginasetoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSetorItensItem } from "termo_core/auth";

export interface PaginaSetorItensItem {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  quantidade_de_colaboradores: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaSetorItensItem;

pub struct PaginaSetorItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_colaboradores: i64,
}
```

</Tab>
</Tabs>

### Setor [#tipo-setor]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Setor } from "termo_core/auth";

export interface Setor {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  quantidade_de_colaboradores: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::Setor;

pub struct Setor {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_colaboradores: i64,
}
```

</Tab>
</Tabs>

### SetorAtualizar [#tipo-setoratualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SetorAtualizar } from "termo_core/auth";

export interface SetorAtualizar {
  nome?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::SetorAtualizar;

pub struct SetorAtualizar {
    pub nome: Option<String>,
}
```

</Tab>
</Tabs>

### SetorCriar [#tipo-setorcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SetorCriar } from "termo_core/auth";

export interface SetorCriar {
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::SetorCriar;

pub struct SetorCriar {
    pub nome: String,
}
```

</Tab>
</Tabs>


# Token de app (/docs/servicos/auth/token_de_app)

> 1 função do TermoAuth para token de app.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`criar_token_de_app`](#criar_token_de_app) | `POST /token_de_app` | Troca o segredo do app por um token de aplicativo |

## `criar_token_de_app` [#criar_token_de_app]

<Rota metodo="POST" caminho="/token_de_app" />

Troca o segredo do app por um token de aplicativo

Pública, sem token de usuário. O backend de um app manda o segredo gerado em `/master/apps` (cadastrado pelo master na tela de provedores do app e entregue ao `termo_core`) e recebe um JWT EdDSA de 15 minutos, assinado com a mesma chave do token de usuário (valide pelo `/.well-known/jwks.json`). Claims: `iss`, `aud`, `sub` (id do app), `iat`, `exp`, `tipo` = `aplicativo`, `name` (nome do app) e `isMaster` (falso quando o app aceita o perfil `cliente`). Vale só nas APIs de sistema dos outros apps, nunca no painel. Peça outro quando faltar menos de 60 s para `expira_em`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_token_de_app(
  corpo_da_requisicao: tipos.TokenDeAppCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TokenDeAppEmitido>
```

```ts title="Exemplo"
import { criar_token_de_app } from "termo_core/auth";

const resposta = await criar_token_de_app(corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_token_de_app(
    corpo_da_requisicao: &tipos::TokenDeAppCriar,
) -> Result<tipos::TokenDeAppEmitido, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::auth::criar_token_de_app(&corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "corpo_da_requisicao": { type: "tipos.TokenDeAppCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TokenDeAppCriar", typeDescriptionLink: "#tipo-tokendeappcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TokenDeAppEmitido>` · Rust: `Result<tipos::TokenDeAppEmitido, ErroAoChamarServico>` · veja [`TokenDeAppEmitido`](#tipo-tokendeappemitido).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### TokenDeAppCriar [#tipo-tokendeappcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TokenDeAppCriar } from "termo_core/auth";

export interface TokenDeAppCriar {
  segredo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::TokenDeAppCriar;

pub struct TokenDeAppCriar {
    pub segredo: String,
}
```

</Tab>
</Tabs>

### TokenDeAppEmitido [#tipo-tokendeappemitido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TokenDeAppEmitido } from "termo_core/auth";

export interface TokenDeAppEmitido {
  app: string;
  expira_em: number;
  token: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::TokenDeAppEmitido;

pub struct TokenDeAppEmitido {
    pub app: String,
    pub expira_em: i64,
    pub token: String,
}
```

</Tab>
</Tabs>


# Usuário (/docs/servicos/auth/usuario)

> 4 funções do TermoAuth para usuário.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as auth from "termo_core/auth";
// ou: import { auth } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["auth"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_usuario`](#buscar_paginador_usuario) | `GET /usuario` | Lista usuários com paginação |
| [`buscar_auto_complete_usuario`](#buscar_auto_complete_usuario) | `GET /usuario/autocomplete` | Lista básica de usuários para seleção |
| [`buscar_pelo_filtro_usuario`](#buscar_pelo_filtro_usuario) | `GET /usuario/filtro` | Busca usuários por filtro |
| [`buscar_pelo_id_usuario`](#buscar_pelo_id_usuario) | `GET /usuario/{id}` | Busca um usuário pelo id |

## `buscar_paginador_usuario` [#buscar_paginador_usuario]

<Rota metodo="GET" caminho="/usuario" credencial />

Lista usuários com paginação

Só master. Os mais recentes vêm primeiro. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10 e máximo 500. `busca` procura no nome e no e-mail; `perfil` é `colaborador` ou `cliente`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_usuario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorUsuario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaUsuario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_usuario } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_usuario(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_usuario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorUsuario,
) -> Result<tipos::PaginaUsuario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_paginador_usuario(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPaginadorUsuario { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaUsuario>` · Rust: `Result<tipos::PaginaUsuario, ErroAoChamarServico>` · veja [`PaginaUsuario`](#tipo-paginausuario).

## `buscar_auto_complete_usuario` [#buscar_auto_complete_usuario]

<Rota metodo="GET" caminho="/usuario/autocomplete" credencial />

Lista básica de usuários para seleção

Só master. Devolve só id, nome e e-mail, em ordem alfabética, para escolher um usuário. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10. `busca` procura no nome e no e-mail; `perfil` é `colaborador` ou `cliente`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_usuario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteUsuario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaUsuarioAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_usuario } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_usuario(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_usuario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteUsuario,
) -> Result<tipos::PaginaUsuarioAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_auto_complete_usuario(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarAutoCompleteUsuario { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaUsuarioAutoComplete>` · Rust: `Result<tipos::PaginaUsuarioAutoComplete, ErroAoChamarServico>` · veja [`PaginaUsuarioAutoComplete`](#tipo-paginausuarioautocomplete).

## `buscar_pelo_filtro_usuario` [#buscar_pelo_filtro_usuario]

<Rota metodo="GET" caminho="/usuario/filtro" credencial />

Busca usuários por filtro

Só master. Devolve todos os usuários que casam com o filtro, sem paginação, em ordem alfabética. `busca` procura no nome e no e-mail; `perfil` é `colaborador` ou `cliente`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_usuario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroUsuario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Usuario>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_usuario } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_usuario(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_usuario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroUsuario,
) -> Result<Vec<tipos::Usuario>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_filtro_usuario(
    &credencial_de_acesso,
    &termo_core::auth::ParametrosDeBuscarPeloFiltroUsuario { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Usuario>>` · Rust: `Result<Vec<tipos::Usuario>, ErroAoChamarServico>`

## `buscar_pelo_id_usuario` [#buscar_pelo_id_usuario]

<Rota metodo="GET" caminho="/usuario/{id}" credencial />

Busca um usuário pelo id

Quem não é master só consegue buscar o próprio usuário, cujo id é o `sub` do token.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_usuario(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Usuario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_usuario } from "termo_core/auth";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_usuario(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_usuario(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Usuario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::auth::buscar_pelo_id_usuario(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Usuario>` · Rust: `Result<tipos::Usuario, ErroAoChamarServico>` · veja [`Usuario`](#tipo-usuario).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaUsuario [#tipo-paginausuario]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsuario } from "termo_core/auth";

export interface PaginaUsuario {
  itens: Array<PaginaUsuarioItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaUsuario;

pub struct PaginaUsuario {
    pub itens: Vec<PaginaUsuarioItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaUsuarioAutoComplete [#tipo-paginausuarioautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsuarioAutoComplete } from "termo_core/auth";

export interface PaginaUsuarioAutoComplete {
  itens: Array<PaginaUsuarioAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaUsuarioAutoComplete;

pub struct PaginaUsuarioAutoComplete {
    pub itens: Vec<PaginaUsuarioAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaUsuarioAutoCompleteItensItem [#tipo-paginausuarioautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsuarioAutoCompleteItensItem } from "termo_core/auth";

export interface PaginaUsuarioAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaUsuarioAutoCompleteItensItem;

pub struct PaginaUsuarioAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaUsuarioItensItem [#tipo-paginausuarioitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsuarioItensItem } from "termo_core/auth";

export interface PaginaUsuarioItensItem {
  atualizado_em: string;
  bloqueado_ate?: string | null;
  cargo?: string | null;
  cargo_id?: string | null;
  criado_em: string;
  dois_fatores_ativo: boolean;
  e_master: boolean;
  email: string;
  email_verificado: boolean;
  funcao?: string | null;
  funcao_id?: string | null;
  id: string;
  imagem?: string | null;
  master_pelo_ambiente: boolean;
  nome: string;
  perfil: string;
  setor?: string | null;
  setor_id?: string | null;
  tem_senha: boolean;
  ultimo_login_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::PaginaUsuarioItensItem;

pub struct PaginaUsuarioItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub cargo: Option<String>,
    pub cargo_id: Option<uuid::Uuid>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub dois_fatores_ativo: bool,
    pub e_master: bool,
    pub email: String,
    pub email_verificado: bool,
    pub funcao: Option<String>,
    pub funcao_id: Option<uuid::Uuid>,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub master_pelo_ambiente: bool,
    pub nome: String,
    pub perfil: String,
    pub setor: Option<String>,
    pub setor_id: Option<uuid::Uuid>,
    pub tem_senha: bool,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>

### Usuario [#tipo-usuario]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Usuario } from "termo_core/auth";

export interface Usuario {
  atualizado_em: string;
  bloqueado_ate?: string | null;
  cargo?: string | null;
  cargo_id?: string | null;
  criado_em: string;
  dois_fatores_ativo: boolean;
  e_master: boolean;
  email: string;
  email_verificado: boolean;
  funcao?: string | null;
  funcao_id?: string | null;
  id: string;
  imagem?: string | null;
  master_pelo_ambiente: boolean;
  nome: string;
  perfil: string;
  setor?: string | null;
  setor_id?: string | null;
  tem_senha: boolean;
  ultimo_login_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::auth::Usuario;

pub struct Usuario {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub cargo: Option<String>,
    pub cargo_id: Option<uuid::Uuid>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub dois_fatores_ativo: bool,
    pub e_master: bool,
    pub email: String,
    pub email_verificado: bool,
    pub funcao: Option<String>,
    pub funcao_id: Option<uuid::Uuid>,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub master_pelo_ambiente: bool,
    pub nome: String,
    pub perfil: String,
    pub setor: Option<String>,
    pub setor_id: Option<uuid::Uuid>,
    pub tem_senha: bool,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>


# Aplicativo (/docs/servicos/bucket/aplicativo)

> 7 funções do TermoBucket para aplicativo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_aplicativo`](#buscar_paginador_aplicativo) | `GET /aplicativo` | Lista os aplicativos com paginação |
| [`buscar_auto_complete_aplicativo`](#buscar_auto_complete_aplicativo) | `GET /aplicativo/autocomplete` | Lista básica de aplicativos para seleção |
| [`buscar_pelo_filtro_aplicativo`](#buscar_pelo_filtro_aplicativo) | `GET /aplicativo/filtro` | Busca aplicativos por filtro |
| [`buscar_pelo_id_aplicativo`](#buscar_pelo_id_aplicativo) | `GET /aplicativo/{id}` | Busca um aplicativo pelo id |
| [`atualizar_pelo_id_aplicativo`](#atualizar_pelo_id_aplicativo) | `PATCH /aplicativo/{id}` | Atualiza um aplicativo pelo id |
| [`deletar_pelo_id_aplicativo`](#deletar_pelo_id_aplicativo) | `DELETE /aplicativo/{id}` | Exclui um aplicativo pelo id |
| [`deletar_arquivos_aplicativo`](#deletar_arquivos_aplicativo) | `DELETE /aplicativo/{id}/arquivos` | Apaga todos os arquivos de um aplicativo |

## `buscar_paginador_aplicativo` [#buscar_paginador_aplicativo]

<Rota metodo="GET" caminho="/aplicativo" credencial />

Lista os aplicativos com paginação

Exige qualquer permissão da área `aplicativos`. Ordena pelo nome e traz o consumo atual de cada aplicativo (quantidade e bytes dos arquivos públicos e privados). `pagina` começa em 1 (padrão 1; valores menores viram 1). `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta todos os aplicativos não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_aplicativo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAplicativo,
) -> Result<tipos::PaginaAplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_paginador_aplicativo(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPaginadorAplicativo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativo>` · Rust: `Result<tipos::PaginaAplicativo, ErroAoChamarServico>` · veja [`PaginaAplicativo`](#tipo-paginaaplicativo).

## `buscar_auto_complete_aplicativo` [#buscar_auto_complete_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/autocomplete" credencial />

Lista básica de aplicativos para seleção

Exige qualquer permissão da área `aplicativos`. Devolve só id, slug e nome, em ordem alfabética de nome. `busca` procura por trecho do nome ou do slug, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os aplicativos que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_aplicativo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAplicativo,
) -> Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_auto_complete_aplicativo(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarAutoCompleteAplicativo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativoAutoComplete>` · Rust: `Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>` · veja [`PaginaAplicativoAutoComplete`](#tipo-paginaaplicativoautocomplete).

## `buscar_pelo_filtro_aplicativo` [#buscar_pelo_filtro_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/filtro" credencial />

Busca aplicativos por filtro

Exige qualquer permissão da área `aplicativos`. Devolve todos os aplicativos não excluídos que casam com o filtro, sem paginação, em ordem alfabética de nome, cada um com o consumo atual. `nome` e `slug` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Aplicativo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_aplicativo(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAplicativo,
) -> Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_filtro_aplicativo(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPeloFiltroAplicativo { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.slug": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Aplicativo>>` · Rust: `Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>`

## `buscar_pelo_id_aplicativo` [#buscar_pelo_id_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/{id}" credencial />

Busca um aplicativo pelo id

Exige qualquer permissão da área `aplicativos`. O aplicativo é cada sistema da Termotubos que guarda arquivos no TermoBucket: `slug` é o identificador do app no TermoAuth e o prefixo dos arquivos dele, `tamanho_maximo` é o limite em bytes por arquivo e `tipos_permitidos` são os tipos MIME aceitos (`image/*` aceita qualquer imagem). Traz o consumo atual: quantidade e bytes dos arquivos públicos e privados não excluídos. Aplicativo excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_id_aplicativo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## `atualizar_pelo_id_aplicativo` [#atualizar_pelo_id_aplicativo]

<Rota metodo="PATCH" caminho="/aplicativo/{id}" credencial />

Atualiza um aplicativo pelo id

Exige a permissão `editar` da área `aplicativos`. Atualização parcial: só os campos enviados mudam e campo desconhecido é recusado. `nome` não pode ficar vazio (até 120 caracteres). `tamanho_maximo` é o limite em bytes por arquivo, maior que zero e de no máximo 99.614.720 (95 MiB, limite de envio pelo Cloudflare Workers). `tipos_permitidos` substitui a lista inteira: de 1 a 50 tipos MIME no formato `tipo/subtipo`, aceitando `tipo/*` (ex.: `image/*`); os valores são gravados em minúsculas, sem repetição. `ativo = false` faz a API de arquivos recusar o aplicativo com `403`. O `slug` não muda. Vale em até 5 minutos para a API de arquivos (cache do aplicativo).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AplicativoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_aplicativo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AplicativoAtualizar,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::atualizar_pelo_id_aplicativo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AplicativoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AplicativoAtualizar", typeDescriptionLink: "#tipo-aplicativoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## `deletar_pelo_id_aplicativo` [#deletar_pelo_id_aplicativo]

<Rota metodo="DELETE" caminho="/aplicativo/{id}" credencial />

Exclui um aplicativo pelo id

Exige a permissão `deletar` da área `aplicativos`. A exclusão é lógica e só é aceita quando o aplicativo não tem arquivos: com arquivos responde `409`, e é preciso apagá-los antes (`DELETE /aplicativo/{id}/arquivos`). Se o aplicativo voltar a chamar a API de arquivos, ele é cadastrado de novo com os limites padrão.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::bucket::deletar_pelo_id_aplicativo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `deletar_arquivos_aplicativo` [#deletar_arquivos_aplicativo]

<Rota metodo="DELETE" caminho="/aplicativo/{id}/arquivos" credencial />

Apaga todos os arquivos de um aplicativo

Só para master do TermoAuth (além da permissão `deletar` da área `aplicativos`). Apaga no R2 todos os objetos do prefixo do aplicativo nos buckets público e privado e marca os registros dos arquivos como excluídos. Se o R2 falhar, nada é marcado como excluído e a chamada pode ser repetida. Devolve quantos objetos saíram do R2 e quantos registros foram marcados.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_arquivos_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ArquivosApagados>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_arquivos_aplicativo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await deletar_arquivos_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_arquivos_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ArquivosApagados, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::deletar_arquivos_aplicativo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ArquivosApagados>` · Rust: `Result<tipos::ArquivosApagados, ErroAoChamarServico>` · veja [`ArquivosApagados`](#tipo-arquivosapagados).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Aplicativo [#tipo-aplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Aplicativo } from "termo_core/bucket";

export interface Aplicativo {
  arquivos_privados: number;
  arquivos_publicos: number;
  ativo: boolean;
  atualizado_em: string;
  bytes_privados: number;
  bytes_publicos: number;
  criado_em: string;
  id: string;
  nome: string;
  slug: string;
  tamanho_maximo: number;
  tipos_permitidos: Array<string>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Aplicativo;

pub struct Aplicativo {
    pub arquivos_privados: i64,
    pub arquivos_publicos: i64,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bytes_privados: i64,
    pub bytes_publicos: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub slug: String,
    pub tamanho_maximo: i64,
    pub tipos_permitidos: Vec<String>,
}
```

</Tab>
</Tabs>

### AplicativoAtualizar [#tipo-aplicativoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AplicativoAtualizar } from "termo_core/bucket";

export interface AplicativoAtualizar {
  ativo?: boolean | null;
  nome?: string | null;
  tamanho_maximo?: number | null;
  tipos_permitidos?: Array<string> | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::AplicativoAtualizar;

pub struct AplicativoAtualizar {
    pub ativo: Option<bool>,
    pub nome: Option<String>,
    pub tamanho_maximo: Option<i64>,
    pub tipos_permitidos: Option<Vec<String>>,
}
```

</Tab>
</Tabs>

### ArquivosApagados [#tipo-arquivosapagados]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivosApagados } from "termo_core/bucket";

export interface ArquivosApagados {
  objetos_apagados: number;
  registros_apagados: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ArquivosApagados;

pub struct ArquivosApagados {
    pub objetos_apagados: i64,
    pub registros_apagados: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativo [#tipo-paginaaplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativo } from "termo_core/bucket";

export interface PaginaAplicativo {
  itens: Array<PaginaAplicativoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAplicativo;

pub struct PaginaAplicativo {
    pub itens: Vec<PaginaAplicativoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoComplete [#tipo-paginaaplicativoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoComplete } from "termo_core/bucket";

export interface PaginaAplicativoAutoComplete {
  itens: Array<PaginaAplicativoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAplicativoAutoComplete;

pub struct PaginaAplicativoAutoComplete {
    pub itens: Vec<PaginaAplicativoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoCompleteItensItem [#tipo-paginaaplicativoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoCompleteItensItem } from "termo_core/bucket";

export interface PaginaAplicativoAutoCompleteItensItem {
  id: string;
  nome: string;
  slug: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAplicativoAutoCompleteItensItem;

pub struct PaginaAplicativoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
    pub slug: String,
}
```

</Tab>
</Tabs>

### PaginaAplicativoItensItem [#tipo-paginaaplicativoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoItensItem } from "termo_core/bucket";

export interface PaginaAplicativoItensItem {
  arquivos_privados: number;
  arquivos_publicos: number;
  ativo: boolean;
  atualizado_em: string;
  bytes_privados: number;
  bytes_publicos: number;
  criado_em: string;
  id: string;
  nome: string;
  slug: string;
  tamanho_maximo: number;
  tipos_permitidos: Array<string>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAplicativoItensItem;

pub struct PaginaAplicativoItensItem {
    pub arquivos_privados: i64,
    pub arquivos_publicos: i64,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bytes_privados: i64,
    pub bytes_publicos: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub slug: String,
    pub tamanho_maximo: i64,
    pub tipos_permitidos: Vec<String>,
}
```

</Tab>
</Tabs>


# Arquivo (/docs/servicos/bucket/arquivo)

> 13 funções do TermoBucket para arquivo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_arquivo`](#buscar_paginador_arquivo) | `GET /arquivo` | Lista os arquivos de todos os aplicativos com paginação |
| [`buscar_resumo_arquivo`](#buscar_resumo_arquivo) | `GET /arquivo/resumo` | Resumo do armazenamento para o dashboard |
| [`buscar_pelo_id_arquivo`](#buscar_pelo_id_arquivo) | `GET /arquivo/{id}` | Busca um arquivo pelo id e devolve a URL de download |
| [`baixar_conteudo_arquivo`](#baixar_conteudo_arquivo) | `GET /arquivo/{id}/conteudo` | Baixa o conteúdo do arquivo |
| [`enviar_conteudo_arquivo`](#enviar_conteudo_arquivo) | `PUT /arquivo/{id}/conteudo` | Envia o conteúdo do arquivo |
| [`privado_buscar_paginador_arquivo`](#privado_buscar_paginador_arquivo) | `GET /private/{app}` | Lista os arquivos privados do aplicativo com paginação |
| [`privado_criar_arquivo`](#privado_criar_arquivo) | `POST /private/{app}` | Registra um arquivo privado e devolve a URL de envio |
| [`privado_buscar_pelo_id_arquivo`](#privado_buscar_pelo_id_arquivo) | `GET /private/{app}/{id}` | Busca um arquivo privado do aplicativo e devolve a URL de download |
| [`privado_deletar_pelo_id_arquivo`](#privado_deletar_pelo_id_arquivo) | `DELETE /private/{app}/{id}` | Apaga um arquivo privado do aplicativo |
| [`publico_buscar_paginador_arquivo`](#publico_buscar_paginador_arquivo) | `GET /public/{app}` | Lista os arquivos públicos do aplicativo com paginação |
| [`publico_criar_arquivo`](#publico_criar_arquivo) | `POST /public/{app}` | Registra um arquivo público e devolve a URL de envio |
| [`publico_buscar_pelo_id_arquivo`](#publico_buscar_pelo_id_arquivo) | `GET /public/{app}/{id}` | Busca um arquivo público do aplicativo e devolve a URL de download |
| [`publico_deletar_pelo_id_arquivo`](#publico_deletar_pelo_id_arquivo) | `DELETE /public/{app}/{id}` | Apaga um arquivo público do aplicativo |

## `buscar_paginador_arquivo` [#buscar_paginador_arquivo]

<Rota metodo="GET" caminho="/arquivo" credencial />

Lista os arquivos de todos os aplicativos com paginação

Exige qualquer permissão da área `aplicativos`. Lista os arquivos não excluídos de uma visibilidade, de todos os aplicativos, do mais novo para o mais antigo. `visibilidade` é obrigatória (`publico` ou `privado`); `aplicativo_id` filtra por um aplicativo; `nome` procura por trecho do nome original, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os arquivos que casam com o filtro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorArquivo,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaArquivo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_arquivo(credencial_de_acesso, { visibilidade });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorArquivo,
) -> Result<tipos::PaginaArquivo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_paginador_arquivo(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPaginadorArquivo { visibilidade, ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.visibilidade": { type: "string", required: true, description: "Rust: String" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaArquivo>` · Rust: `Result<tipos::PaginaArquivo, ErroAoChamarServico>` · veja [`PaginaArquivo`](#tipo-paginaarquivo).

## `buscar_resumo_arquivo` [#buscar_resumo_arquivo]

<Rota metodo="GET" caminho="/arquivo/resumo" credencial />

Resumo do armazenamento para o dashboard

Exige qualquer permissão da área `aplicativos`. Devolve os totais atuais de arquivos e bytes (geral, públicos e privados), os envios por dia dos últimos 90 dias, o armazenamento no fim de cada um dos últimos 12 meses (com o que foi enviado no mês) e os 8 aplicativos que mais ocupam espaço. Os envios contam também os arquivos já excluídos, e a data de exclusão refaz o histórico de armazenamento. Dias e meses no horário de Brasília.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_resumo_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Resumo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_resumo_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_resumo_arquivo(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_resumo_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Resumo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_resumo_arquivo(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Resumo>` · Rust: `Result<tipos::Resumo, ErroAoChamarServico>` · veja [`Resumo`](#tipo-resumo).

## `buscar_pelo_id_arquivo` [#buscar_pelo_id_arquivo]

<Rota metodo="GET" caminho="/arquivo/{id}" credencial />

Busca um arquivo pelo id e devolve a URL de download

Exige qualquer permissão da área `aplicativos`. Busca um arquivo de qualquer aplicativo e devolve o registro e uma URL de download assinada, válida por 15 minutos (`GET /arquivo/{id}/conteudo`, sem token); arquivo público traz também `url_publica`, o endereço permanente. Arquivo excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ArquivoComDownload>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_arquivo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ArquivoComDownload, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_id_arquivo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ArquivoComDownload>` · Rust: `Result<tipos::ArquivoComDownload, ErroAoChamarServico>` · veja [`ArquivoComDownload`](#tipo-arquivocomdownload).

## `baixar_conteudo_arquivo` [#baixar_conteudo_arquivo]

<Rota metodo="GET" caminho="/arquivo/{id}/conteudo" />

Baixa o conteúdo do arquivo

Pública, sem token: o acesso vem do link. Arquivo privado só abre com `expira` e `assinatura` da `url_download` (15 minutos); arquivo público abre também sem eles, pela `url_publica`. Devolve o conteúdo com o `Content-Type` gravado; imagem, vídeo, áudio e PDF abrem no navegador e os demais tipos são baixados como anexo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function baixar_conteudo_arquivo(
  id: string,
  parametros: ParametrosDeBaixarConteudoArquivo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Uint8Array>
```

```ts title="Exemplo"
import { baixar_conteudo_arquivo } from "termo_core/bucket";

const resposta = await baixar_conteudo_arquivo(id, { expira: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn baixar_conteudo_arquivo(
    id: uuid::Uuid,
    parametros: &ParametrosDeBaixarConteudoArquivo,
) -> Result<Vec<u8>, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::bucket::baixar_conteudo_arquivo(
    id,
    &termo_core::bucket::ParametrosDeBaixarConteudoArquivo { expira: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "parametros.expira": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.assinatura": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Uint8Array>` · Rust: `Result<Vec<u8>, ErroAoChamarServico>` · os bytes do arquivo.

## `enviar_conteudo_arquivo` [#enviar_conteudo_arquivo]

<Rota metodo="PUT" caminho="/arquivo/{id}/conteudo" />

Envia o conteúdo do arquivo

Pública, sem token: o acesso vem do link. É a `url_envio` devolvida ao criar o arquivo (`expira` e `assinatura` obrigatórios, 15 minutos). O corpo é o conteúdo cru, com o `Content-Type` e o `Content-Length` informados ao criar; o TermoBucket grava no R2 pelo binding do Worker. Enviar de novo pelo mesmo link substitui o conteúdo. O tamanho fica limitado também pelo corpo máximo de requisição do plano do Cloudflare Workers (100 MB no Free e no Pro).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function enviar_conteudo_arquivo(
  id: string,
  parametros: ParametrosDeEnviarConteudoArquivo,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { enviar_conteudo_arquivo } from "termo_core/bucket";

await enviar_conteudo_arquivo(id, { expira, assinatura });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn enviar_conteudo_arquivo(
    id: uuid::Uuid,
    parametros: &ParametrosDeEnviarConteudoArquivo,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::bucket::enviar_conteudo_arquivo(
    id,
    &termo_core::bucket::ParametrosDeEnviarConteudoArquivo { expira, assinatura },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "parametros.expira": { type: "number", required: true, description: "Rust: i64" },
    "parametros.assinatura": { type: "string", required: true, description: "Rust: String" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `privado_buscar_paginador_arquivo` [#privado_buscar_paginador_arquivo]

<Rota metodo="GET" caminho="/private/{app}" credencial />

Lista os arquivos privados do aplicativo com paginação

API de arquivos dos apps, com o token de aplicativo do TermoAuth. Lista só os arquivos privados não excluídos do aplicativo do token, do mais novo para o mais antigo. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function privado_buscar_paginador_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  parametros: ParametrosDePrivadoBuscarPaginadorArquivo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaArquivo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { privado_buscar_paginador_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await privado_buscar_paginador_arquivo(credencial_de_acesso, app, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn privado_buscar_paginador_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    parametros: &ParametrosDePrivadoBuscarPaginadorArquivo,
) -> Result<tipos::PaginaArquivo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::privado_buscar_paginador_arquivo(
    &credencial_de_acesso,
    &app,
    &termo_core::bucket::ParametrosDePrivadoBuscarPaginadorArquivo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaArquivo>` · Rust: `Result<tipos::PaginaArquivo, ErroAoChamarServico>` · veja [`PaginaArquivo`](#tipo-paginaarquivo).

## `privado_criar_arquivo` [#privado_criar_arquivo]

<Rota metodo="POST" caminho="/private/{app}" credencial />

Registra um arquivo privado e devolve a URL de envio

API de arquivos dos apps, com o token de aplicativo do TermoAuth (o painel não usa). Registra o arquivo privado do aplicativo do token e devolve uma URL de envio assinada, válida por 15 minutos (`PUT /arquivo/{id}/conteudo`, sem token), para o app enviar o conteúdo com `PUT` e os `cabecalhos` indicados. `nome_original` é obrigatório (até 255 caracteres); `tipo` é o tipo MIME exato (`tipo/subtipo`, gravado em minúsculas) e precisa estar entre os tipos permitidos do aplicativo; `tamanho` é o tamanho em bytes, maior que zero e até o `tamanho_maximo` do aplicativo. O envio só é aceito com o `Content-Type` e o `Content-Length` informados aqui, e o TermoBucket grava no R2 pelo binding do Worker. No primeiro pedido, o aplicativo é cadastrado sozinho com os limites padrão (50 MiB, `image/*` e `application/pdf`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function privado_criar_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  corpo_da_requisicao: tipos.ArquivoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ArquivoCriado>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { privado_criar_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await privado_criar_arquivo(credencial_de_acesso, app, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn privado_criar_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    corpo_da_requisicao: &tipos::ArquivoCriar,
) -> Result<tipos::ArquivoCriado, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::privado_criar_arquivo(
    &credencial_de_acesso,
    &app,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "corpo_da_requisicao": { type: "tipos.ArquivoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ArquivoCriar", typeDescriptionLink: "#tipo-arquivocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ArquivoCriado>` · Rust: `Result<tipos::ArquivoCriado, ErroAoChamarServico>` · veja [`ArquivoCriado`](#tipo-arquivocriado).

## `privado_buscar_pelo_id_arquivo` [#privado_buscar_pelo_id_arquivo]

<Rota metodo="GET" caminho="/private/{app}/{id}" credencial />

Busca um arquivo privado do aplicativo e devolve a URL de download

API de arquivos dos apps, com o token de aplicativo do TermoAuth. Devolve o registro do arquivo e uma URL de download assinada, válida por 15 minutos. Só encontra arquivo privado do próprio aplicativo do token: arquivo de outro app ou de outra visibilidade responde `404`. Arquivo privado só é lido pela URL assinada (`url_publica` é sempre `null`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function privado_buscar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ArquivoComDownload>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { privado_buscar_pelo_id_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await privado_buscar_pelo_id_arquivo(credencial_de_acesso, app, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn privado_buscar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    id: uuid::Uuid,
) -> Result<tipos::ArquivoComDownload, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::privado_buscar_pelo_id_arquivo(
    &credencial_de_acesso,
    &app,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ArquivoComDownload>` · Rust: `Result<tipos::ArquivoComDownload, ErroAoChamarServico>` · veja [`ArquivoComDownload`](#tipo-arquivocomdownload).

## `privado_deletar_pelo_id_arquivo` [#privado_deletar_pelo_id_arquivo]

<Rota metodo="DELETE" caminho="/private/{app}/{id}" credencial />

Apaga um arquivo privado do aplicativo

API de arquivos dos apps, com o token de aplicativo do TermoAuth. Apaga o objeto no R2 e marca o registro como excluído. Só alcança arquivo privado do próprio aplicativo do token. Se o R2 falhar, o registro continua e a chamada pode ser repetida.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function privado_deletar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { privado_deletar_pelo_id_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await privado_deletar_pelo_id_arquivo(credencial_de_acesso, app, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn privado_deletar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::bucket::privado_deletar_pelo_id_arquivo(&credencial_de_acesso, &app, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `publico_buscar_paginador_arquivo` [#publico_buscar_paginador_arquivo]

<Rota metodo="GET" caminho="/public/{app}" credencial />

Lista os arquivos públicos do aplicativo com paginação

API de arquivos dos apps, com o token de aplicativo do TermoAuth. Lista só os arquivos públicos não excluídos do aplicativo do token, do mais novo para o mais antigo. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function publico_buscar_paginador_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  parametros: ParametrosDePublicoBuscarPaginadorArquivo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaArquivo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { publico_buscar_paginador_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await publico_buscar_paginador_arquivo(credencial_de_acesso, app, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn publico_buscar_paginador_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    parametros: &ParametrosDePublicoBuscarPaginadorArquivo,
) -> Result<tipos::PaginaArquivo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::publico_buscar_paginador_arquivo(
    &credencial_de_acesso,
    &app,
    &termo_core::bucket::ParametrosDePublicoBuscarPaginadorArquivo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaArquivo>` · Rust: `Result<tipos::PaginaArquivo, ErroAoChamarServico>` · veja [`PaginaArquivo`](#tipo-paginaarquivo).

## `publico_criar_arquivo` [#publico_criar_arquivo]

<Rota metodo="POST" caminho="/public/{app}" credencial />

Registra um arquivo público e devolve a URL de envio

API de arquivos dos apps, com o token de aplicativo do TermoAuth (o painel não usa). Registra o arquivo público do aplicativo do token e devolve uma URL de envio assinada, válida por 15 minutos (`PUT /arquivo/{id}/conteudo`, sem token), para o app enviar o conteúdo com `PUT` e os `cabecalhos` indicados. `nome_original` é obrigatório (até 255 caracteres); `tipo` é o tipo MIME exato (`tipo/subtipo`, gravado em minúsculas) e precisa estar entre os tipos permitidos do aplicativo; `tamanho` é o tamanho em bytes, maior que zero e até o `tamanho_maximo` do aplicativo. O envio só é aceito com o `Content-Type` e o `Content-Length` informados aqui, e o TermoBucket grava no R2 pelo binding do Worker. No primeiro pedido, o aplicativo é cadastrado sozinho com os limites padrão (50 MiB, `image/*` e `application/pdf`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function publico_criar_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  corpo_da_requisicao: tipos.ArquivoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ArquivoCriado>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { publico_criar_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await publico_criar_arquivo(credencial_de_acesso, app, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn publico_criar_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    corpo_da_requisicao: &tipos::ArquivoCriar,
) -> Result<tipos::ArquivoCriado, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::publico_criar_arquivo(
    &credencial_de_acesso,
    &app,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "corpo_da_requisicao": { type: "tipos.ArquivoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ArquivoCriar", typeDescriptionLink: "#tipo-arquivocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ArquivoCriado>` · Rust: `Result<tipos::ArquivoCriado, ErroAoChamarServico>` · veja [`ArquivoCriado`](#tipo-arquivocriado).

## `publico_buscar_pelo_id_arquivo` [#publico_buscar_pelo_id_arquivo]

<Rota metodo="GET" caminho="/public/{app}/{id}" credencial />

Busca um arquivo público do aplicativo e devolve a URL de download

API de arquivos dos apps, com o token de aplicativo do TermoAuth. Devolve o registro do arquivo e uma URL de download assinada, válida por 15 minutos. Só encontra arquivo público do próprio aplicativo do token: arquivo de outro app ou de outra visibilidade responde `404`. Como o arquivo é público, a resposta também traz `url_publica`, o endereço permanente que abre sem assinatura (pelo domínio público do bucket, quando `R2_URL_PUBLICA` está configurado, ou por `GET /arquivo/{id}/conteudo`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function publico_buscar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ArquivoComDownload>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { publico_buscar_pelo_id_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await publico_buscar_pelo_id_arquivo(credencial_de_acesso, app, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn publico_buscar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    id: uuid::Uuid,
) -> Result<tipos::ArquivoComDownload, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::publico_buscar_pelo_id_arquivo(
    &credencial_de_acesso,
    &app,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ArquivoComDownload>` · Rust: `Result<tipos::ArquivoComDownload, ErroAoChamarServico>` · veja [`ArquivoComDownload`](#tipo-arquivocomdownload).

## `publico_deletar_pelo_id_arquivo` [#publico_deletar_pelo_id_arquivo]

<Rota metodo="DELETE" caminho="/public/{app}/{id}" credencial />

Apaga um arquivo público do aplicativo

API de arquivos dos apps, com o token de aplicativo do TermoAuth. Apaga o objeto no R2 e marca o registro como excluído. Só alcança arquivo público do próprio aplicativo do token. Se o R2 falhar, o registro continua e a chamada pode ser repetida.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function publico_deletar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  app: string,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { publico_deletar_pelo_id_arquivo } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await publico_deletar_pelo_id_arquivo(credencial_de_acesso, app, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn publico_deletar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    app: &str,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::bucket::publico_deletar_pelo_id_arquivo(&credencial_de_acesso, &app, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "app": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ArmazenamentoDoMes [#tipo-armazenamentodomes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArmazenamentoDoMes } from "termo_core/bucket";

export interface ArmazenamentoDoMes {
  arquivos: number;
  arquivos_enviados: number;
  bytes: number;
  bytes_enviados: number;
  mes: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ArmazenamentoDoMes;

pub struct ArmazenamentoDoMes {
    pub arquivos: i64,
    pub arquivos_enviados: i64,
    pub bytes: i64,
    pub bytes_enviados: i64,
    pub mes: chrono::NaiveDate,
}
```

</Tab>
</Tabs>

### Arquivo [#tipo-arquivo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Arquivo } from "termo_core/bucket";

export interface Arquivo {
  app: string;
  atualizado_em: string;
  bucket: string;
  chave: string;
  criado_em: string;
  id: string;
  nome_original: string;
  tamanho: number;
  tipo: string;
  visibilidade: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Arquivo;

pub struct Arquivo {
    pub app: String,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bucket: String,
    pub chave: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome_original: String,
    pub tamanho: i64,
    pub tipo: String,
    pub visibilidade: String,
}
```

</Tab>
</Tabs>

### ArquivoComDownload [#tipo-arquivocomdownload]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivoComDownload } from "termo_core/bucket";

export interface ArquivoComDownload {
  arquivo: Arquivo;
  expira_em: string;
  url_download: string;
  url_publica?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ArquivoComDownload;

pub struct ArquivoComDownload {
    pub arquivo: Arquivo,
    pub expira_em: chrono::DateTime<chrono::Utc>,
    pub url_download: String,
    pub url_publica: Option<String>,
}
```

</Tab>
</Tabs>

### ArquivoCriado [#tipo-arquivocriado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivoCriado } from "termo_core/bucket";

export interface ArquivoCriado {
  arquivo: Arquivo;
  cabecalhos: Record<string, string>;
  expira_em: string;
  metodo: string;
  url_envio: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ArquivoCriado;

pub struct ArquivoCriado {
    pub arquivo: Arquivo,
    pub cabecalhos: std::collections::BTreeMap<String, String>,
    pub expira_em: chrono::DateTime<chrono::Utc>,
    pub metodo: String,
    pub url_envio: String,
}
```

</Tab>
</Tabs>

### ArquivoCriar [#tipo-arquivocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivoCriar } from "termo_core/bucket";

export interface ArquivoCriar {
  nome_original: string;
  tamanho: number;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ArquivoCriar;

pub struct ArquivoCriar {
    pub nome_original: String,
    pub tamanho: i64,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### ConsumoDoAplicativo [#tipo-consumodoaplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConsumoDoAplicativo } from "termo_core/bucket";

export interface ConsumoDoAplicativo {
  arquivos: number;
  bytes: number;
  id: string;
  nome: string;
  slug: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ConsumoDoAplicativo;

pub struct ConsumoDoAplicativo {
    pub arquivos: i64,
    pub bytes: i64,
    pub id: uuid::Uuid,
    pub nome: String,
    pub slug: String,
}
```

</Tab>
</Tabs>

### EnviosDoDia [#tipo-enviosdodia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EnviosDoDia } from "termo_core/bucket";

export interface EnviosDoDia {
  arquivos: number;
  bytes: number;
  dia: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::EnviosDoDia;

pub struct EnviosDoDia {
    pub arquivos: i64,
    pub bytes: i64,
    pub dia: chrono::NaiveDate,
}
```

</Tab>
</Tabs>

### PaginaArquivo [#tipo-paginaarquivo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaArquivo } from "termo_core/bucket";

export interface PaginaArquivo {
  itens: Array<PaginaArquivoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaArquivo;

pub struct PaginaArquivo {
    pub itens: Vec<PaginaArquivoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaArquivoItensItem [#tipo-paginaarquivoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaArquivoItensItem } from "termo_core/bucket";

export interface PaginaArquivoItensItem {
  app: string;
  atualizado_em: string;
  bucket: string;
  chave: string;
  criado_em: string;
  id: string;
  nome_original: string;
  tamanho: number;
  tipo: string;
  visibilidade: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaArquivoItensItem;

pub struct PaginaArquivoItensItem {
    pub app: String,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bucket: String,
    pub chave: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome_original: String,
    pub tamanho: i64,
    pub tipo: String,
    pub visibilidade: String,
}
```

</Tab>
</Tabs>

### Resumo [#tipo-resumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Resumo } from "termo_core/bucket";

export interface Resumo {
  armazenamento_por_mes: Array<ArmazenamentoDoMes>;
  arquivos: number;
  arquivos_privados: number;
  arquivos_publicos: number;
  bytes: number;
  bytes_privados: number;
  bytes_publicos: number;
  consumo_por_aplicativo: Array<ConsumoDoAplicativo>;
  envios_por_dia: Array<EnviosDoDia>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Resumo;

pub struct Resumo {
    pub armazenamento_por_mes: Vec<ArmazenamentoDoMes>,
    pub arquivos: i64,
    pub arquivos_privados: i64,
    pub arquivos_publicos: i64,
    pub bytes: i64,
    pub bytes_privados: i64,
    pub bytes_publicos: i64,
    pub consumo_por_aplicativo: Vec<ConsumoDoAplicativo>,
    pub envios_por_dia: Vec<EnviosDoDia>,
}
```

</Tab>
</Tabs>


# Auth (/docs/servicos/bucket/auth)

> 8 funções do TermoBucket para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_auth`](#buscar_paginador_auth) | `GET /auth` | Lista acessos com paginação |
| [`criar_auth`](#criar_auth) | `POST /auth` | Cria um acesso |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Busca o acesso de quem está logado |
| [`buscar_auto_complete_auth`](#buscar_auto_complete_auth) | `GET /auth/autocomplete` | Lista básica de acessos para seleção |
| [`buscar_pelo_filtro_auth`](#buscar_pelo_filtro_auth) | `GET /auth/filtro` | Busca acessos por filtro |
| [`buscar_pelo_id_auth`](#buscar_pelo_id_auth) | `GET /auth/{id}` | Busca um acesso pelo id |
| [`atualizar_pelo_id_auth`](#atualizar_pelo_id_auth) | `PATCH /auth/{id}` | Atualiza um acesso pelo id |
| [`deletar_pelo_id_auth`](#deletar_pelo_id_auth) | `DELETE /auth/{id}` | Exclui um acesso pelo id |

## `buscar_paginador_auth` [#buscar_paginador_auth]

<Rota metodo="GET" caminho="/auth" credencial />

Lista acessos com paginação

Exige qualquer permissão da área `colaboradores`. Ordena por perfil e depois por e-mail. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10, sem máximo. Acessos excluídos não aparecem nem entram no `total`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_auth(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAuth,
) -> Result<tipos::PaginaAuth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_paginador_auth(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPaginadorAuth { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuth>` · Rust: `Result<tipos::PaginaAuth, ErroAoChamarServico>` · veja [`PaginaAuth`](#tipo-paginaauth).

## `criar_auth` [#criar_auth]

<Rota metodo="POST" caminho="/auth" credencial />

Cria um acesso

Exige a permissão `criar` da área `colaboradores`. Cadastra quem pode entrar no TermoBucket: o e-mail é gravado em minúsculas, sem espaços nas pontas, com até 160 caracteres. O único perfil aceito é `colaborador`. O acesso nasce ativo e sem perfil de acesso. Para a pessoa conseguir entrar, o e-mail precisa ser `@termotubos.com.br` e existir no TermoAuth. O colaborador não se cadastra aqui: vem só do TermoAuth, pela sincronização.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_auth(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AuthCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_auth(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AuthCriar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::criar_auth(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AuthCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthCriar", typeDescriptionLink: "#tipo-authcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Busca o acesso de quem está logado

Livre para qualquer usuário autenticado com cadastro ativo, mesmo sem nenhuma permissão liberada. Devolve o cadastro de quem chamou, o nome do perfil de acesso do colaborador em `perfil_acesso` (`null` quando ainda não tem) e as permissões que o perfil dá por área (`aplicativos`, `colaboradores` e `configuracoes`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões e, no primeiro acesso, ganha o cadastro automaticamente. `nome` vem do TermoAuth e, se estiver vazio, repete o e-mail. É a chamada que o painel faz antes de mostrar qualquer tela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## `buscar_auto_complete_auth` [#buscar_auto_complete_auth]

<Rota metodo="GET" caminho="/auth/autocomplete" credencial />

Lista básica de acessos para seleção

Exige qualquer permissão da área `colaboradores`. Devolve só id, e-mail e perfil, em ordem alfabética de e-mail, para escolher um acesso. `busca` procura por trecho do e-mail, sem diferenciar maiúsculas; `perfil` compara o valor exato. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10, sem máximo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_auth(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAuth,
) -> Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_auto_complete_auth(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarAutoCompleteAuth { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthAutoComplete>` · Rust: `Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>` · veja [`PaginaAuthAutoComplete`](#tipo-paginaauthautocomplete).

## `buscar_pelo_filtro_auth` [#buscar_pelo_filtro_auth]

<Rota metodo="GET" caminho="/auth/filtro" credencial />

Busca acessos por filtro

Exige qualquer permissão da área `colaboradores`. Devolve todos os acessos que casam com o filtro, sem paginação, em ordem alfabética de e-mail. `email` procura por trecho, sem diferenciar maiúsculas; `perfil` compara o valor exato; `ativo` filtra pela situação. Sem filtro, devolve todos. Acessos excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Auth>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_auth(credencial_de_acesso, { email: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAuth,
) -> Result<Vec<tipos::Auth>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_filtro_auth(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPeloFiltroAuth { email: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Auth>>` · Rust: `Result<Vec<tipos::Auth>, ErroAoChamarServico>`

## `buscar_pelo_id_auth` [#buscar_pelo_id_auth]

<Rota metodo="GET" caminho="/auth/{id}" credencial />

Busca um acesso pelo id

Exige qualquer permissão da área `colaboradores`. Acesso excluído responde `404`. `vinculado` diz se há um colaborador ligado ao acesso, e `nome` é o nome desse colaborador.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `atualizar_pelo_id_auth` [#atualizar_pelo_id_auth]

<Rota metodo="PATCH" caminho="/auth/{id}" credencial />

Atualiza um acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Só os campos enviados mudam: `email` (gravado em minúsculas, até 160 caracteres) e `ativo` (acesso inativo é barrado em todas as rotas). O acesso de um master do TermoAuth não pode ser alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AuthAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_auth(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AuthAtualizar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::atualizar_pelo_id_auth(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AuthAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthAtualizar", typeDescriptionLink: "#tipo-authatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `deletar_pelo_id_auth` [#deletar_pelo_id_auth]

<Rota metodo="DELETE" caminho="/auth/{id}" credencial />

Exclui um acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica: o acesso some das consultas e a pessoa deixa de entrar, mas o registro fica guardado e não há como restaurar. Acesso com colaborador vinculado não pode ser excluído: o colaborador pertence ao TermoAuth e só sai de lá. O acesso de um master do TermoAuth não pode ser excluído.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_auth } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::bucket::deletar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/bucket";

export interface AcessoAtual {
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::AcessoAtual;

pub struct AcessoAtual {
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/bucket";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Auth [#tipo-auth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Auth } from "termo_core/bucket";

export interface Auth {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Auth;

pub struct Auth {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### AuthAtualizar [#tipo-authatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthAtualizar } from "termo_core/bucket";

export interface AuthAtualizar {
  ativo?: boolean | null;
  email?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::AuthAtualizar;

pub struct AuthAtualizar {
    pub ativo: Option<bool>,
    pub email: Option<String>,
}
```

</Tab>
</Tabs>

### AuthCriar [#tipo-authcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthCriar } from "termo_core/bucket";

export interface AuthCriar {
  email: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::AuthCriar;

pub struct AuthCriar {
    pub email: String,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuth [#tipo-paginaauth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuth } from "termo_core/bucket";

export interface PaginaAuth {
  itens: Array<PaginaAuthItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAuth;

pub struct PaginaAuth {
    pub itens: Vec<PaginaAuthItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoComplete [#tipo-paginaauthautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoComplete } from "termo_core/bucket";

export interface PaginaAuthAutoComplete {
  itens: Array<PaginaAuthAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAuthAutoComplete;

pub struct PaginaAuthAutoComplete {
    pub itens: Vec<PaginaAuthAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteItensItem [#tipo-paginaauthautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteItensItem } from "termo_core/bucket";

export interface PaginaAuthAutoCompleteItensItem {
  email: string;
  id: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAuthAutoCompleteItensItem;

pub struct PaginaAuthAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthItensItem [#tipo-paginaauthitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthItensItem } from "termo_core/bucket";

export interface PaginaAuthItensItem {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaAuthItensItem;

pub struct PaginaAuthItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/bucket";

export interface Permissoes {
  aplicativos?: Acoes;
  colaboradores?: Acoes;
  configuracoes?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub configuracoes: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/bucket/colaborador)

> 5 funções do TermoBucket para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista colaboradores com paginação |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista colaboradores com paginação

Só leitura: o colaborador é cadastrado, alterado e excluído no TermoAuth e chega aqui pela sincronização com o TermoAuth; aqui só se escolhe o perfil de acesso dele (`PATCH /colaborador/{id}/perfil_acesso`). Exige qualquer permissão da área `colaboradores`. Ordena por nome. `nome` e `cargo` filtram por trecho, sem diferenciar maiúsculas, e `ativo` pela situação. `pagina` começa em 1 (padrão 1; valores menores viram 1). `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. Colaboradores excluídos não aparecem nem entram no `total`, que conta os registros que casam com os filtros. Quando quem chama é master do TermoAuth, a lista antes traz do TermoAuth os colaboradores `@termotubos.com.br` que ainda não existem aqui, criando acesso e colaborador com o perfil de acesso `Acesso inicial` (só `ler` em todas as áreas, recriado se tiver sido excluído); quem já existe não é alterado e ninguém é excluído. Se o TermoAuth falhar, a lista sai mesmo assim, só sem a sincronização.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores`. Devolve só id, nome e e-mail, em ordem alfabética de nome, para escolher um colaborador. `busca` procura por trecho do nome ou do e-mail, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10, sem máximo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores`. Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail; `nome`, `email` e `cargo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação; `perfil_acesso_id` filtra pelo perfil de acesso. Sem filtro, devolve todos. Colaboradores excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores`. Colaborador excluído responde `404`. Traz junto o e-mail do acesso, se ele é master do TermoAuth e o perfil de acesso (`perfil_acesso_id` e o nome em `perfil_acesso`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoBucket: `perfil_acesso_id` aponta para um perfil de `GET /perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/bucket";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/bucket";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/bucket";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/bucket";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/bucket";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/bucket";

export interface PaginaColaboradorItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>


# TermoBucket (/docs/servicos/bucket)

> Microserviço de arquivos da Termotubos, sobre o Cloudflare R2. Os apps enviam, listam, baixam e apagam os próprios arquivos na API de arquivos (/public/{app} e /private/{app}) com o token de aplicati…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Microserviço de arquivos da Termotubos, sobre o Cloudflare R2. Os apps enviam, listam, baixam e apagam os próprios arquivos na API de arquivos (`/public/{app}` e `/private/{app}`) com o token de aplicativo do TermoAuth; o conteúdo vai e volta por links assinados de 15 minutos (`/arquivo/{id}/conteudo`), e o Worker grava e lê no R2 pelo binding; o resto da API é o painel (aplicativos e o consumo de cada um, arquivos de todos os apps, dashboard, registro das requisições, perfis de acesso e colaboradores, que vêm só do TermoAuth) e usa o token do usuário logado no TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::bucket` (feature `bucket`) |
| Importação TypeScript | `termo_core/bucket` ou `import { bucket } from "termo_core"` |
| Funções | 43 |
| Entidades | 7 |
| Versão do contrato | `0.3.1` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51121` |
| `SANDBOX` | `https://sandbox-api-bucket.termotubos.com.br` |
| `PRODUCTION` | `https://api-bucket.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Aplicativo" href="/docs/servicos/bucket/aplicativo" description="7 funções" />
  <Card title="Arquivo" href="/docs/servicos/bucket/arquivo" description="13 funções" />
  <Card title="Log" href="/docs/servicos/bucket/log" description="1 função" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/bucket/auth" description="8 funções" />
  <Card title="Colaborador" href="/docs/servicos/bucket/colaborador" description="5 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/bucket/perfil_acesso" description="7 funções" />
  <Card title="Teste" href="/docs/servicos/bucket/test" description="2 funções" />
</Cards>


# Log (/docs/servicos/bucket/log)

> 1 função do TermoBucket para log.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_log`](#buscar_paginador_log) | `GET /log` | Lista o registro das requisições recebidas |

## `buscar_paginador_log` [#buscar_paginador_log]

<Rota metodo="GET" caminho="/log" credencial />

Lista o registro das requisições recebidas

Exige qualquer permissão da área `configuracoes`. Lista as requisições que o backend recebeu, da mais nova para a mais antiga, com método, caminho, consulta, status, duração, IP, cabeçalhos e os corpos da requisição e da resposta. O cabeçalho `Authorization` e as URLs assinadas saem mascarados. `pagina` começa em 1 (padrão 1; valores menores viram 1) e `tamanho` tem padrão 20, entre 1 e 100.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_log(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorLog = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaLog>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_log } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_log(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_log(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorLog,
) -> Result<tipos::PaginaLog, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_paginador_log(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPaginadorLog { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaLog>` · Rust: `Result<tipos::PaginaLog, ErroAoChamarServico>` · veja [`PaginaLog`](#tipo-paginalog).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaLog [#tipo-paginalog]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaLog } from "termo_core/bucket";

export interface PaginaLog {
  itens: Array<PaginaLogItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaLog;

pub struct PaginaLog {
    pub itens: Vec<PaginaLogItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaLogItensItem [#tipo-paginalogitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaLogItensItem } from "termo_core/bucket";

export interface PaginaLogItensItem {
  cabecalhos: unknown;
  caminho: string;
  consulta?: string | null;
  corpo_requisicao?: string | null;
  corpo_resposta?: string | null;
  criado_em: string;
  duracao_ms: number;
  id: string;
  ip?: string | null;
  metodo: string;
  status: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaLogItensItem;

pub struct PaginaLogItensItem {
    pub cabecalhos: serde_json::Value,
    pub caminho: String,
    pub consulta: Option<String>,
    pub corpo_requisicao: Option<String>,
    pub corpo_resposta: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub duracao_ms: i32,
    pub id: uuid::Uuid,
    pub ip: Option<String>,
    pub metodo: String,
    pub status: i32,
}
```

</Tab>
</Tabs>


# Perfil acesso (/docs/servicos/bucket/perfil_acesso)

> 7 funções do TermoBucket para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso com paginação |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome. `pagina` começa em 1 (padrão 1; valores menores viram 1). `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcesso>` · Rust: `Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>` · veja [`PaginaPerfilAcesso`](#tipo-paginaperfilacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoBucket dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`aplicativos`, `colaboradores` e `configuracoes`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoComplete`](#tipo-paginaperfilacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::bucket::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::bucket::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/bucket";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::bucket::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/bucket";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcesso [#tipo-paginaperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcesso } from "termo_core/bucket";

export interface PaginaPerfilAcesso {
  itens: Array<PaginaPerfilAcessoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaPerfilAcesso;

pub struct PaginaPerfilAcesso {
    pub itens: Vec<PaginaPerfilAcessoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoComplete [#tipo-paginaperfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoComplete } from "termo_core/bucket";

export interface PaginaPerfilAcessoAutoComplete {
  itens: Array<PaginaPerfilAcessoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaPerfilAcessoAutoComplete;

pub struct PaginaPerfilAcessoAutoComplete {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteItensItem [#tipo-paginaperfilacessoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteItensItem } from "termo_core/bucket";

export interface PaginaPerfilAcessoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaPerfilAcessoAutoCompleteItensItem;

pub struct PaginaPerfilAcessoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoItensItem [#tipo-paginaperfilacessoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoItensItem } from "termo_core/bucket";

export interface PaginaPerfilAcessoItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PaginaPerfilAcessoItensItem;

pub struct PaginaPerfilAcessoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/bucket";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/bucket";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/bucket";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/bucket";

export interface Permissoes {
  aplicativos?: Acoes;
  colaboradores?: Acoes;
  configuracoes?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub configuracoes: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/bucket/test)

> 2 funções do TermoBucket para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as bucket from "termo_core/bucket";
// ou: import { bucket } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["bucket"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true`, e a versão do backend publicada (`versao` e `versao_backend`, iguais), no formato semver.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/bucket";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::bucket::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` e a versão do backend no ar (semver) sempre que o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/bucket";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::bucket::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/bucket";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/bucket";

export interface VersaoDoBackend {
  sucesso: boolean;
  versao: string;
  versao_backend: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::bucket::VersaoDoBackend;

pub struct VersaoDoBackend {
    pub sucesso: bool,
    pub versao: String,
    pub versao_backend: String,
}
```

</Tab>
</Tabs>


# Serviços (/docs/servicos)

> Todas as 644 funções do termo_core, por aplicativo e por entidade, em TypeScript e em Rust.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Cada aplicativo da Termotubos é um módulo do `termo_core` e cada rota da API dele é uma função, com o **mesmo nome em TypeScript e em Rust**. Escolha o aplicativo e depois a entidade.

<Cards>
  <Card icon={<Sparkles />} title="TermoAI" href="/docs/servicos/ai" description="51 funções · 11 entidades. Gateway de IA da Termotubos. POST /gateway atende pedidos de texto, imagem, áudio e vídeo com as chaves de IA…" />
  <Card icon={<KeyRound />} title="TermoAuth" href="/docs/servicos/auth" description="29 funções · 6 entidades. Consulta de usuários, apps, setores, cargos e funções do serviço central de login da Termotubos. Toda chamada…" />
  <Card icon={<HardDrive />} title="TermoBucket" href="/docs/servicos/bucket" description="43 funções · 7 entidades. Microserviço de arquivos da Termotubos, sobre o Cloudflare R2. Os apps enviam, listam, baixam e apagam os pró…" />
  <Card icon={<Building />} title="TermoIntranetAPI" href="/docs/servicos/intranet" description="43 funções · 9 entidades. Consulta, só leitura, de clientes, faturas e funcionários vindos do banco da intranet da Termotubos, mais a a…" />
  <Card icon={<Target />} title="TermoLeads" href="/docs/servicos/leads" description="29 funções · 9 entidades. Consulta da base CNPJ da Receita Federal. GET /api/cnpj/{cnpj} é pública; a listagem de empresas, os colabora…" />
  <Card icon={<Store />} title="TermoPortal" href="/docs/servicos/portal" description="158 funções · 31 entidades. API do Portal B2B da Termotubos: catálogo (produtos), unidades clientes, pessoas e perfis, cotações, pedidos,…" />
  <Card icon={<MessageCircle />} title="TermoSell" href="/docs/servicos/sell" description="73 funções · 14 entidades. Atendimento comercial da Termotubos pelo WhatsApp: cadastro de clientes, robôs de atendimento com IA (fluxo e…" />
  <Card icon={<LifeBuoy />} title="TermoSupport" href="/docs/servicos/support" description="90 funções · 17 entidades. Suporte e gestão de projetos da Termotubos. A API é o painel: cadastro dos aplicativos atendidos e dos docume…" />
  <Card icon={<Radar />} title="TermoTracing" href="/docs/servicos/tracing" description="59 funções · 11 entidades. Rastreamento de navegação e erros dos sites e sistemas da Termotubos. O script instalado em cada site envia l…" />
  <Card icon={<Webhook />} title="TermoWebhook" href="/docs/servicos/webhook" description="69 funções · 16 entidades. Hub central de eventos da Termotubos. Os apps publicam em POST /eventos com o token de aplicativo do TermoAut…" />
</Cards>

## Ainda sem funções [#ainda-sem-funções]

Estes módulos já existem no pacote, mas o serviço ainda não publicou o `openapi.json`.

<Cards>
  <Card icon={<Plug />} title="TermoMCP" href="/docs/servicos/mcp" description="Ainda sem openapi.json publicado." />
  <Card icon={<BadgeCheck />} title="TermoQuality" href="/docs/servicos/quality" description="Ainda sem openapi.json publicado." />
  <Card icon={<Activity />} title="TermoStatus" href="/docs/servicos/status" description="Ainda sem openapi.json publicado." />
  <Card icon={<Palette />} title="TermoStudio" href="/docs/servicos/studio" description="Ainda sem openapi.json publicado." />
  <Card icon={<Warehouse />} title="TermoWMS" href="/docs/servicos/wms" description="Ainda sem openapi.json publicado." />
</Cards>


# Auth (/docs/servicos/intranet/auth)

> 9 funções do TermoIntranetAPI para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_auth`](#buscar_paginador_auth) | `GET /auth` | Lista os acessos com paginação por cursor |
| [`criar_auth`](#criar_auth) | `POST /auth` | Cadastra um acesso |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Acesso de quem está logado |
| [`buscar_auto_complete_auth`](#buscar_auto_complete_auth) | `GET /auth/autocomplete` | Lista básica de acessos para seleção |
| [`buscar_pelo_filtro_auth`](#buscar_pelo_filtro_auth) | `GET /auth/filtro` | Busca acessos por filtro |
| [`buscar_total_auth`](#buscar_total_auth) | `GET /auth/total` | Total de registros do paginador |
| [`buscar_pelo_id_auth`](#buscar_pelo_id_auth) | `GET /auth/{id}` | Busca um acesso pelo id |
| [`atualizar_pelo_id_auth`](#atualizar_pelo_id_auth) | `PATCH /auth/{id}` | Atualiza um acesso |
| [`deletar_pelo_id_auth`](#deletar_pelo_id_auth) | `DELETE /auth/{id}` | Exclui um acesso |

## `buscar_paginador_auth` [#buscar_paginador_auth]

<Rota metodo="GET" caminho="/auth" credencial />

Lista os acessos com paginação por cursor

Exige qualquer permissão da área `colaboradores`. Ordena por perfil, depois por e-mail e por id, sempre 50 itens por página. Sem `cursor` vem a primeira página de acessos; para a seguinte, envie em `cursor` o `proximo_cursor` recebido (nulo na última página). O total de registros não vem aqui: está em `GET /auth/total`, para a lista não esperar o `count(*)`. Cursor de id inexistente devolve página vazia. Acessos excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthString>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_auth(credencial_de_acesso, { cursor: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAuth,
) -> Result<tipos::PaginaAuthString, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_paginador_auth(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPaginadorAuth { cursor: Some(Default::default()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthString>` · Rust: `Result<tipos::PaginaAuthString, ErroAoChamarServico>` · veja [`PaginaAuthString`](#tipo-paginaauthstring).

## `criar_auth` [#criar_auth]

<Rota metodo="POST" caminho="/auth" credencial />

Cadastra um acesso

Exige a permissão `criar` da área `colaboradores`. Cadastra quem pode entrar no TermoIntranetAPI: o e-mail é obrigatório, gravado em minúsculas e sem espaços nas pontas, com até 160 caracteres. O único perfil aceito é `colaborador`. O acesso nasce ativo e sem nenhuma permissão: as áreas vêm do perfil de acesso do colaborador (`PATCH /colaborador/{id}/perfil_acesso`). Para a pessoa conseguir entrar, o e-mail precisa ser `@termotubos.com.br` e existir no TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_auth(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AuthCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_auth(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AuthCriar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::criar_auth(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AuthCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthCriar", typeDescriptionLink: "#tipo-authcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Acesso de quem está logado

Livre para qualquer usuário autenticado com cadastro ativo, mesmo sem nenhuma permissão liberada. Devolve o cadastro de quem chamou (o `nome` vem do token e, vazio, vira o e-mail), o nome do perfil de acesso do colaborador em `perfil_acesso` (nulo sem perfil) e as permissões por área que o perfil libera (`clientes`, `faturas`, `funcionarios` e `colaboradores`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões, com ou sem perfil, e, no primeiro acesso, ganha o cadastro automaticamente.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## `buscar_auto_complete_auth` [#buscar_auto_complete_auth]

<Rota metodo="GET" caminho="/auth/autocomplete" credencial />

Lista básica de acessos para seleção

Exige qualquer permissão da área `colaboradores`. Devolve só id, e-mail e perfil, em ordem alfabética de e-mail, para escolher um acesso. `busca` procura por trecho do e-mail, sem diferenciar maiúsculas; `perfil` compara o valor exato. Paginação por cursor: `tamanho` tem padrão 10 e máximo 100, e para a página seguinte envie em `cursor` o `proximo_cursor` recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthAutoCompleteString>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_auth(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAuth,
) -> Result<tipos::PaginaAuthAutoCompleteString, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_auto_complete_auth(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarAutoCompleteAuth { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthAutoCompleteString>` · Rust: `Result<tipos::PaginaAuthAutoCompleteString, ErroAoChamarServico>` · veja [`PaginaAuthAutoCompleteString`](#tipo-paginaauthautocompletestring).

## `buscar_pelo_filtro_auth` [#buscar_pelo_filtro_auth]

<Rota metodo="GET" caminho="/auth/filtro" credencial />

Busca acessos por filtro

Exige qualquer permissão da área `colaboradores`. Devolve todos os acessos que casam com o filtro, sem paginação, em ordem alfabética de e-mail. `email` procura por trecho, sem diferenciar maiúsculas; `perfil` compara o valor exato; `ativo` filtra pela situação. Sem filtro, devolve todos. Acessos excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Auth>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_auth(credencial_de_acesso, { email: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAuth,
) -> Result<Vec<tipos::Auth>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_filtro_auth(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPeloFiltroAuth { email: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Auth>>` · Rust: `Result<Vec<tipos::Auth>, ErroAoChamarServico>`

## `buscar_total_auth` [#buscar_total_auth]

<Rota metodo="GET" caminho="/auth/total" credencial />

Total de registros do paginador

Exige qualquer permissão da área `colaboradores`. Devolve só o `count(*)` com os mesmos filtros de `GET /auth`, para o frontend montar o paginador sem atrasar a lista: a tela pede a primeira página e o total em paralelo. Conta os mesmos acessos que a listagem devolve; excluídos não contam.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_total_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Total>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_total_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_total_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_total_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Total, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_total_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Total>` · Rust: `Result<tipos::Total, ErroAoChamarServico>` · veja [`Total`](#tipo-total).

## `buscar_pelo_id_auth` [#buscar_pelo_id_auth]

<Rota metodo="GET" caminho="/auth/{id}" credencial />

Busca um acesso pelo id

Exige qualquer permissão da área `colaboradores`. Acesso excluído responde `404`. `vinculado` diz se há um colaborador ligado ao acesso, e `nome` é o nome desse colaborador.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `atualizar_pelo_id_auth` [#atualizar_pelo_id_auth]

<Rota metodo="PATCH" caminho="/auth/{id}" credencial />

Atualiza um acesso

Exige a permissão `editar` da área `colaboradores`. Só os campos enviados mudam: `email` (gravado em minúsculas, até 160 caracteres) e `ativo` (acesso inativo é barrado em todas as rotas). O acesso de um master do TermoAuth não pode ser alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AuthAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_auth(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AuthAtualizar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::atualizar_pelo_id_auth(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AuthAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthAtualizar", typeDescriptionLink: "#tipo-authatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `deletar_pelo_id_auth` [#deletar_pelo_id_auth]

<Rota metodo="DELETE" caminho="/auth/{id}" credencial />

Exclui um acesso

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica: o acesso some das consultas e a pessoa deixa de entrar, mas o registro fica guardado e não há como restaurar. Acesso com colaborador vinculado não pode ser excluído. O acesso de um master do TermoAuth não pode ser excluído.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_auth } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::intranet::deletar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/intranet";

export interface AcessoAtual {
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::AcessoAtual;

pub struct AcessoAtual {
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/intranet";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Auth [#tipo-auth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Auth } from "termo_core/intranet";

export interface Auth {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Auth;

pub struct Auth {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### AuthAtualizar [#tipo-authatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthAtualizar } from "termo_core/intranet";

export interface AuthAtualizar {
  ativo?: boolean | null;
  email?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::AuthAtualizar;

pub struct AuthAtualizar {
    pub ativo: Option<bool>,
    pub email: Option<String>,
}
```

</Tab>
</Tabs>

### AuthCriar [#tipo-authcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthCriar } from "termo_core/intranet";

export interface AuthCriar {
  email: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::AuthCriar;

pub struct AuthCriar {
    pub email: String,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteString [#tipo-paginaauthautocompletestring]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteString } from "termo_core/intranet";

export interface PaginaAuthAutoCompleteString {
  itens: Array<PaginaAuthAutoCompleteStringItensItem>;
  proximo_cursor?: string;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaAuthAutoCompleteString;

pub struct PaginaAuthAutoCompleteString {
    pub itens: Vec<PaginaAuthAutoCompleteStringItensItem>,
    pub proximo_cursor: Option<String>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteStringItensItem [#tipo-paginaauthautocompletestringitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteStringItensItem } from "termo_core/intranet";

export interface PaginaAuthAutoCompleteStringItensItem {
  email: string;
  id: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaAuthAutoCompleteStringItensItem;

pub struct PaginaAuthAutoCompleteStringItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthString [#tipo-paginaauthstring]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthString } from "termo_core/intranet";

export interface PaginaAuthString {
  itens: Array<PaginaAuthStringItensItem>;
  proximo_cursor?: string;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaAuthString;

pub struct PaginaAuthString {
    pub itens: Vec<PaginaAuthStringItensItem>,
    pub proximo_cursor: Option<String>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthStringItensItem [#tipo-paginaauthstringitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthStringItensItem } from "termo_core/intranet";

export interface PaginaAuthStringItensItem {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaAuthStringItensItem;

pub struct PaginaAuthStringItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/intranet";

export interface Permissoes {
  clientes?: Acoes;
  colaboradores?: Acoes;
  faturas?: Acoes;
  funcionarios?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Permissoes;

pub struct Permissoes {
    pub clientes: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub faturas: Option<Acoes>,
    pub funcionarios: Option<Acoes>,
}
```

</Tab>
</Tabs>

### Total [#tipo-total]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Total } from "termo_core/intranet";

export interface Total {
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Total;

pub struct Total {
    pub total: i64,
}
```

</Tab>
</Tabs>


# Cliente (/docs/servicos/intranet/cliente)

> 5 funções do TermoIntranetAPI para cliente.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_cliente`](#buscar_paginador_cliente) | `GET /cliente` | Lista clientes com paginação por cursor |
| [`buscar_auto_complete_cliente`](#buscar_auto_complete_cliente) | `GET /cliente/autocomplete` | Lista básica para seleção |
| [`buscar_pelo_filtro_cliente`](#buscar_pelo_filtro_cliente) | `GET /cliente/filtro` | Busca por filtro |
| [`buscar_total_cliente`](#buscar_total_cliente) | `GET /cliente/total` | Total de registros do paginador |
| [`buscar_pelo_id_cliente`](#buscar_pelo_id_cliente) | `GET /cliente/{id}` | Busca pelo id |

## `buscar_paginador_cliente` [#buscar_paginador_cliente]

<Rota metodo="GET" caminho="/cliente" credencial />

Lista clientes com paginação por cursor

Exige qualquer permissão da área `clientes`. Ordena do id mais novo para o mais antigo (os clientes da intranet não têm índice por nome), sempre 50 itens por página. Só clientes ativos do cadastro da intranet, só leitura. Sem `cursor` vem a primeira página; para a seguinte, envie em `cursor` o `proximo_cursor` recebido (nulo na última página). O total de registros não vem aqui: está em `GET /cliente/total`, para a lista não esperar o `count(*)`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaClienteResumoI64>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_cliente } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_cliente(credencial_de_acesso, { cursor: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCliente,
) -> Result<tipos::PaginaClienteResumoI64, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_paginador_cliente(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPaginadorCliente { cursor: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaClienteResumoI64>` · Rust: `Result<tipos::PaginaClienteResumoI64, ErroAoChamarServico>` · veja [`PaginaClienteResumoI64`](#tipo-paginaclienteresumoi64).

## `buscar_auto_complete_cliente` [#buscar_auto_complete_cliente]

<Rota metodo="GET" caminho="/cliente/autocomplete" credencial />

Lista básica para seleção

Exige qualquer permissão da área `clientes`. Devolve só id, nome e CPF/CNPJ, do id mais novo para o mais antigo, para escolher um cliente ativo. `busca` procura por trecho do nome, do nome fantasia ou dos dígitos do CPF/CNPJ. Paginação por cursor: `tamanho` tem padrão 10 e máximo 100, e para a página seguinte envie em `cursor` o `proximo_cursor` recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaClienteAutoCompleteI64>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_cliente } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_cliente(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteCliente,
) -> Result<tipos::PaginaClienteAutoCompleteI64, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_auto_complete_cliente(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarAutoCompleteCliente { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaClienteAutoCompleteI64>` · Rust: `Result<tipos::PaginaClienteAutoCompleteI64, ErroAoChamarServico>` · veja [`PaginaClienteAutoCompleteI64`](#tipo-paginaclienteautocompletei64).

## `buscar_pelo_filtro_cliente` [#buscar_pelo_filtro_cliente]

<Rota metodo="GET" caminho="/cliente/filtro" credencial />

Busca por filtro

Exige qualquer permissão da área `clientes`. Aceita `nome`, `cpf_cnpj`, `email`, `cidade`, `uf` e `vendedor`; informe ao menos um. Devolve no máximo 100 registros.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ClienteResumo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_cliente } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_cliente(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroCliente,
) -> Result<Vec<tipos::ClienteResumo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_filtro_cliente(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPeloFiltroCliente { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cpf_cnpj": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ClienteResumo>>` · Rust: `Result<Vec<tipos::ClienteResumo>, ErroAoChamarServico>`

## `buscar_total_cliente` [#buscar_total_cliente]

<Rota metodo="GET" caminho="/cliente/total" credencial />

Total de registros do paginador

Exige qualquer permissão da área `clientes`. Devolve só o `count(*)` com os mesmos filtros de `GET /cliente`, para o frontend montar o paginador sem atrasar a lista: a tela pede a primeira página e o total em paralelo. Conta os mesmos clientes ativos do cadastro da intranet que a listagem devolve.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_total_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Total>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_total_cliente } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_total_cliente(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_total_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Total, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_total_cliente(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Total>` · Rust: `Result<tipos::Total, ErroAoChamarServico>` · veja [`Total`](#tipo-total).

## `buscar_pelo_id_cliente` [#buscar_pelo_id_cliente]

<Rota metodo="GET" caminho="/cliente/{id}" credencial />

Busca pelo id

Exige qualquer permissão da área `clientes`. Devolve o cliente ativo completo, com tipos, pessoas de contato e atividades.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_cliente } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_cliente(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::Cliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_cliente(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cliente>` · Rust: `Result<tipos::Cliente, ErroAoChamarServico>` · veja [`Cliente`](#tipo-cliente).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Atividade [#tipo-atividade]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Atividade } from "termo_core/intranet";

export interface Atividade {
  cnae?: string | null;
  nome?: string | null;
  principal: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Atividade;

pub struct Atividade {
    pub cnae: Option<String>,
    pub nome: Option<String>,
    pub principal: bool,
}
```

</Tab>
</Tabs>

### Cliente [#tipo-cliente]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cliente } from "termo_core/intranet";

export interface Cliente {
  atividades: Array<Atividade>;
  atualizado_no_tiny_em?: string | null;
  bairro?: string | null;
  celular?: string | null;
  cep?: string | null;
  cidade?: string | null;
  codigo?: string | null;
  complemento?: string | null;
  cpf_cnpj?: string | null;
  criado_no_tiny_em?: string | null;
  email?: string | null;
  email_nota_fiscal?: string | null;
  id: number;
  id_tiny?: number | null;
  inscricao_estadual?: string | null;
  limite_credito?: number | null;
  logradouro?: string | null;
  nome?: string | null;
  nome_fantasia?: string | null;
  numero?: string | null;
  observacao?: string | null;
  pessoas_contato: Array<PessoaContato>;
  site?: string | null;
  situacao?: string | null;
  telefone?: string | null;
  tipo_pessoa?: string | null;
  tipos: Array<string>;
  uf?: string | null;
  ultima_compra_em?: string | null;
  ultima_compra_numero?: number | null;
  ultima_compra_valor?: number | null;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Cliente;

pub struct Cliente {
    pub atividades: Vec<Atividade>,
    pub atualizado_no_tiny_em: Option<chrono::DateTime<chrono::Utc>>,
    pub bairro: Option<String>,
    pub celular: Option<String>,
    pub cep: Option<String>,
    pub cidade: Option<String>,
    pub codigo: Option<String>,
    pub complemento: Option<String>,
    pub cpf_cnpj: Option<String>,
    pub criado_no_tiny_em: Option<chrono::DateTime<chrono::Utc>>,
    pub email: Option<String>,
    pub email_nota_fiscal: Option<String>,
    pub id: i64,
    pub id_tiny: Option<i64>,
    pub inscricao_estadual: Option<String>,
    pub limite_credito: Option<f64>,
    pub logradouro: Option<String>,
    pub nome: Option<String>,
    pub nome_fantasia: Option<String>,
    pub numero: Option<String>,
    pub observacao: Option<String>,
    pub pessoas_contato: Vec<PessoaContato>,
    pub site: Option<String>,
    pub situacao: Option<String>,
    pub telefone: Option<String>,
    pub tipo_pessoa: Option<String>,
    pub tipos: Vec<String>,
    pub uf: Option<String>,
    pub ultima_compra_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultima_compra_numero: Option<i64>,
    pub ultima_compra_valor: Option<f64>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### ClienteResumo [#tipo-clienteresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteResumo } from "termo_core/intranet";

export interface ClienteResumo {
  celular?: string | null;
  cidade?: string | null;
  codigo?: string | null;
  cpf_cnpj?: string | null;
  email?: string | null;
  id: number;
  id_tiny?: number | null;
  nome?: string | null;
  nome_fantasia?: string | null;
  situacao?: string | null;
  telefone?: string | null;
  tipo_pessoa?: string | null;
  uf?: string | null;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::ClienteResumo;

pub struct ClienteResumo {
    pub celular: Option<String>,
    pub cidade: Option<String>,
    pub codigo: Option<String>,
    pub cpf_cnpj: Option<String>,
    pub email: Option<String>,
    pub id: i64,
    pub id_tiny: Option<i64>,
    pub nome: Option<String>,
    pub nome_fantasia: Option<String>,
    pub situacao: Option<String>,
    pub telefone: Option<String>,
    pub tipo_pessoa: Option<String>,
    pub uf: Option<String>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaClienteAutoCompleteI64 [#tipo-paginaclienteautocompletei64]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteAutoCompleteI64 } from "termo_core/intranet";

export interface PaginaClienteAutoCompleteI64 {
  itens: Array<PaginaClienteAutoCompleteI64ItensItem>;
  proximo_cursor?: number;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaClienteAutoCompleteI64;

pub struct PaginaClienteAutoCompleteI64 {
    pub itens: Vec<PaginaClienteAutoCompleteI64ItensItem>,
    pub proximo_cursor: Option<i64>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaClienteAutoCompleteI64ItensItem [#tipo-paginaclienteautocompletei64itensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteAutoCompleteI64ItensItem } from "termo_core/intranet";

export interface PaginaClienteAutoCompleteI64ItensItem {
  cpf_cnpj?: string | null;
  id: number;
  nome?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaClienteAutoCompleteI64ItensItem;

pub struct PaginaClienteAutoCompleteI64ItensItem {
    pub cpf_cnpj: Option<String>,
    pub id: i64,
    pub nome: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaClienteResumoI64 [#tipo-paginaclienteresumoi64]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteResumoI64 } from "termo_core/intranet";

export interface PaginaClienteResumoI64 {
  itens: Array<PaginaClienteResumoI64ItensItem>;
  proximo_cursor?: number;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaClienteResumoI64;

pub struct PaginaClienteResumoI64 {
    pub itens: Vec<PaginaClienteResumoI64ItensItem>,
    pub proximo_cursor: Option<i64>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaClienteResumoI64ItensItem [#tipo-paginaclienteresumoi64itensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteResumoI64ItensItem } from "termo_core/intranet";

export interface PaginaClienteResumoI64ItensItem {
  celular?: string | null;
  cidade?: string | null;
  codigo?: string | null;
  cpf_cnpj?: string | null;
  email?: string | null;
  id: number;
  id_tiny?: number | null;
  nome?: string | null;
  nome_fantasia?: string | null;
  situacao?: string | null;
  telefone?: string | null;
  tipo_pessoa?: string | null;
  uf?: string | null;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaClienteResumoI64ItensItem;

pub struct PaginaClienteResumoI64ItensItem {
    pub celular: Option<String>,
    pub cidade: Option<String>,
    pub codigo: Option<String>,
    pub cpf_cnpj: Option<String>,
    pub email: Option<String>,
    pub id: i64,
    pub id_tiny: Option<i64>,
    pub nome: Option<String>,
    pub nome_fantasia: Option<String>,
    pub situacao: Option<String>,
    pub telefone: Option<String>,
    pub tipo_pessoa: Option<String>,
    pub uf: Option<String>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### PessoaContato [#tipo-pessoacontato]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PessoaContato } from "termo_core/intranet";

export interface PessoaContato {
  departamento?: string | null;
  email?: string | null;
  id: number;
  marketing: boolean;
  nome?: string | null;
  ramal?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PessoaContato;

pub struct PessoaContato {
    pub departamento: Option<String>,
    pub email: Option<String>,
    pub id: i64,
    pub marketing: bool,
    pub nome: Option<String>,
    pub ramal: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### Total [#tipo-total]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Total } from "termo_core/intranet";

export interface Total {
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Total;

pub struct Total {
    pub total: i64,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/intranet/colaborador)

> 6 funções do TermoIntranetAPI para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista os colaboradores com paginação por cursor |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_total_colaborador`](#buscar_total_colaborador) | `GET /colaborador/total` | Total de registros do paginador |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista os colaboradores com paginação por cursor

Exige qualquer permissão da área `colaboradores`. Ordena por nome e id, sempre 50 itens por página. `nome`, `setor` e `cargo` procuram por trecho, sem diferenciar maiúsculas, e `ativo` filtra pela situação (é o filtro da tela). Sem `cursor` vem a primeira página de colaboradores; para a seguinte, envie em `cursor` o `proximo_cursor` recebido (nulo na última página). O total de registros não vem aqui: está em `GET /colaborador/total`, para a lista não esperar o `count(*)`. Cursor de id inexistente devolve página vazia. Quando quem chama é master do TermoAuth, antes de listar o backend cadastra os colaboradores do TermoAuth que ainda não existem aqui, com o perfil de acesso "Acesso inicial" (só leitura). Colaboradores excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorString>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { cursor: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaboradorString, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPaginadorColaborador { cursor: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorString>` · Rust: `Result<tipos::PaginaColaboradorString, ErroAoChamarServico>` · veja [`PaginaColaboradorString`](#tipo-paginacolaboradorstring).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores`. Devolve só id, nome e e-mail, em ordem alfabética de nome, para escolher um colaborador. `busca` procura por trecho do nome ou do e-mail, sem diferenciar maiúsculas. Paginação por cursor: `tamanho` tem padrão 10 e máximo 100, e para a página seguinte envie em `cursor` o `proximo_cursor` recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoCompleteString>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoCompleteString, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoCompleteString>` · Rust: `Result<tipos::PaginaColaboradorAutoCompleteString, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoCompleteString`](#tipo-paginacolaboradorautocompletestring).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores`. Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail; `nome`, `email`, `setor` e `cargo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação; `perfil_acesso_id` filtra pelo perfil de acesso. Sem filtro, devolve todos. Colaboradores excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_total_colaborador` [#buscar_total_colaborador]

<Rota metodo="GET" caminho="/colaborador/total" credencial />

Total de registros do paginador

Exige qualquer permissão da área `colaboradores`. Devolve só o `count(*)` com os mesmos filtros de `GET /colaborador` (`nome`, `setor`, `cargo` e `ativo`), para o frontend montar o paginador sem atrasar a lista: a tela pede a primeira página e o total em paralelo. Conta os mesmos colaboradores que a listagem devolve; excluídos não contam.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_total_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarTotalColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Total>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_total_colaborador } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_total_colaborador(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_total_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarTotalColaborador,
) -> Result<tipos::Total, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_total_colaborador(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarTotalColaborador { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Total>` · Rust: `Result<tipos::Total, ErroAoChamarServico>` · veja [`Total`](#tipo-total).

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores`. O colaborador é do TermoAuth, que é o único que cria, altera e exclui; aqui só se define o perfil de acesso dele. Colaborador excluído responde `404`. Traz junto o e-mail do acesso, se ele é master do TermoAuth, o setor, o cargo e a função vindos do TermoAuth e o perfil de acesso (`perfil_acesso_id` e o nome em `perfil_acesso`, nulos quando a pessoa ainda não tem perfil).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoIntranetAPI: `perfil_acesso_id` aponta para um perfil de `GET /perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/intranet";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/intranet";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteString [#tipo-paginacolaboradorautocompletestring]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteString } from "termo_core/intranet";

export interface PaginaColaboradorAutoCompleteString {
  itens: Array<PaginaColaboradorAutoCompleteStringItensItem>;
  proximo_cursor?: string;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaColaboradorAutoCompleteString;

pub struct PaginaColaboradorAutoCompleteString {
    pub itens: Vec<PaginaColaboradorAutoCompleteStringItensItem>,
    pub proximo_cursor: Option<String>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteStringItensItem [#tipo-paginacolaboradorautocompletestringitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteStringItensItem } from "termo_core/intranet";

export interface PaginaColaboradorAutoCompleteStringItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaColaboradorAutoCompleteStringItensItem;

pub struct PaginaColaboradorAutoCompleteStringItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorString [#tipo-paginacolaboradorstring]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorString } from "termo_core/intranet";

export interface PaginaColaboradorString {
  itens: Array<PaginaColaboradorStringItensItem>;
  proximo_cursor?: string;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaColaboradorString;

pub struct PaginaColaboradorString {
    pub itens: Vec<PaginaColaboradorStringItensItem>,
    pub proximo_cursor: Option<String>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorStringItensItem [#tipo-paginacolaboradorstringitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorStringItensItem } from "termo_core/intranet";

export interface PaginaColaboradorStringItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaColaboradorStringItensItem;

pub struct PaginaColaboradorStringItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### Total [#tipo-total]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Total } from "termo_core/intranet";

export interface Total {
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Total;

pub struct Total {
    pub total: i64,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/intranet/configuracao)

> 2 funções do TermoIntranetAPI para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao` | Configuração do app |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao` | Atualiza o segredo do app |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Configuração do app

Só um master do TermoAuth. Devolve a situação do segredo do app gerado no TermoAuth (`/master/apps`), guardado cifrado no banco: `configurado` e o final mascarado em `final_visivel`, nunca o valor. `criptografia_configurada` diz se o servidor tem a `GLOBAL_SECRET_CRIPTOGRAFIA`; sem ela o segredo aparece como não configurado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao" credencial />

Atualiza o segredo do app

Só um master do TermoAuth. `segredo_do_app_gerado_no_termo_auth` ausente não muda nada, uma string troca o valor (até 2.000 caracteres, sem quebra de linha) e `null` limpa. O valor é cifrado com AES-256-GCM e entregue ao `termo_core` na hora, sem deploy.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/intranet";

export interface Configuracao {
  atualizado_em: string;
  atualizado_por?: string | null;
  criptografia_configurada: boolean;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Configuracao;

pub struct Configuracao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub atualizado_por: Option<String>,
    pub criptografia_configurada: bool,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/intranet";

export interface ConfiguracaoAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/intranet";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Fatura (/docs/servicos/intranet/fatura)

> 5 funções do TermoIntranetAPI para fatura.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_fatura`](#buscar_paginador_fatura) | `GET /fatura` | Lista faturas com paginação por cursor |
| [`buscar_auto_complete_fatura`](#buscar_auto_complete_fatura) | `GET /fatura/autocomplete` | Lista básica para seleção |
| [`buscar_pelo_filtro_fatura`](#buscar_pelo_filtro_fatura) | `GET /fatura/filtro` | Busca por filtro |
| [`buscar_total_fatura`](#buscar_total_fatura) | `GET /fatura/total` | Total de registros do paginador |
| [`buscar_pelo_id_fatura`](#buscar_pelo_id_fatura) | `GET /fatura/{id}` | Busca pelo id |

## `buscar_paginador_fatura` [#buscar_paginador_fatura]

<Rota metodo="GET" caminho="/fatura" credencial />

Lista faturas com paginação por cursor

Exige qualquer permissão da área `faturas`. Ordena da data de emissão mais recente para a mais antiga e, no empate, pelo id decrescente, sempre 50 itens por página. Só leitura, a partir do banco da intranet. Sem `cursor` vem a primeira página; para a seguinte, envie em `cursor` o `proximo_cursor` recebido (nulo na última página). O total de registros não vem aqui: está em `GET /fatura/total`, para a lista não esperar o `count(*)`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorFatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFaturaResumoI64>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_fatura } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_fatura(credencial_de_acesso, { cursor: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorFatura,
) -> Result<tipos::PaginaFaturaResumoI64, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_paginador_fatura(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPaginadorFatura { cursor: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFaturaResumoI64>` · Rust: `Result<tipos::PaginaFaturaResumoI64, ErroAoChamarServico>` · veja [`PaginaFaturaResumoI64`](#tipo-paginafaturaresumoi64).

## `buscar_auto_complete_fatura` [#buscar_auto_complete_fatura]

<Rota metodo="GET" caminho="/fatura/autocomplete" credencial />

Lista básica para seleção

Exige qualquer permissão da área `faturas`. Devolve só id, número, série e nome do cliente, da emissão mais recente para a mais antiga, para escolher uma fatura. `busca` procura por trecho do nome do cliente ou, quando é um número, pelo número exato da fatura. Paginação por cursor: `tamanho` tem padrão 10 e máximo 100, e para a página seguinte envie em `cursor` o `proximo_cursor` recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteFatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFaturaAutoCompleteI64>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_fatura } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_fatura(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteFatura,
) -> Result<tipos::PaginaFaturaAutoCompleteI64, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_auto_complete_fatura(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarAutoCompleteFatura { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFaturaAutoCompleteI64>` · Rust: `Result<tipos::PaginaFaturaAutoCompleteI64, ErroAoChamarServico>` · veja [`PaginaFaturaAutoCompleteI64`](#tipo-paginafaturaautocompletei64).

## `buscar_pelo_filtro_fatura` [#buscar_pelo_filtro_fatura]

<Rota metodo="GET" caminho="/fatura/filtro" credencial />

Busca por filtro

Exige qualquer permissão da área `faturas`. Aceita `numero`, `cliente`, `cpf_cnpj`, `vendedor`, `numero_pedido`, `situacao`, `emitida_de` e `emitida_ate` (datas em AAAA-MM-DD); informe ao menos um. Devolve no máximo 100 registros.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroFatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.FaturaResumo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_fatura } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_fatura(credencial_de_acesso, { numero: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroFatura,
) -> Result<Vec<tipos::FaturaResumo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_filtro_fatura(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPeloFiltroFatura { numero: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.numero": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cliente": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cpf_cnpj": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.numero_pedido": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.emitida_de": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.emitida_ate": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.FaturaResumo>>` · Rust: `Result<Vec<tipos::FaturaResumo>, ErroAoChamarServico>`

## `buscar_total_fatura` [#buscar_total_fatura]

<Rota metodo="GET" caminho="/fatura/total" credencial />

Total de registros do paginador

Exige qualquer permissão da área `faturas`. Devolve só o `count(*)` com os mesmos filtros de `GET /fatura`, para o frontend montar o paginador sem atrasar a lista: a tela pede a primeira página e o total em paralelo. Conta as mesmas faturas do banco da intranet que a listagem devolve.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_total_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Total>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_total_fatura } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_total_fatura(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_total_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Total, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_total_fatura(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Total>` · Rust: `Result<tipos::Total, ErroAoChamarServico>` · veja [`Total`](#tipo-total).

## `buscar_pelo_id_fatura` [#buscar_pelo_id_fatura]

<Rota metodo="GET" caminho="/fatura/{id}" credencial />

Busca pelo id

Exige qualquer permissão da área `faturas`. Devolve a fatura completa, com itens e parcelas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Fatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_fatura } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_fatura(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::Fatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_fatura(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Fatura>` · Rust: `Result<tipos::Fatura, ErroAoChamarServico>` · veja [`Fatura`](#tipo-fatura).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Fatura [#tipo-fatura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Fatura } from "termo_core/intranet";

export interface Fatura {
  base_icms?: number | null;
  base_icms_st?: number | null;
  chave_acesso?: string | null;
  cliente_bairro?: string | null;
  cliente_cep?: string | null;
  cliente_cidade?: string | null;
  cliente_codigo?: string | null;
  cliente_complemento?: string | null;
  cliente_cpf_cnpj?: string | null;
  cliente_email?: string | null;
  cliente_inscricao_estadual?: string | null;
  cliente_logradouro?: string | null;
  cliente_nome?: string | null;
  cliente_numero?: string | null;
  cliente_telefone?: string | null;
  cliente_tipo_pessoa?: string | null;
  cliente_uf?: string | null;
  codigo_rastreamento?: string | null;
  condicao_pagamento?: string | null;
  descricao_situacao?: string | null;
  emitida_em?: string | null;
  entrega_bairro?: string | null;
  entrega_cep?: string | null;
  entrega_cidade?: string | null;
  entrega_complemento?: string | null;
  entrega_cpf_cnpj?: string | null;
  entrega_logradouro?: string | null;
  entrega_nome?: string | null;
  entrega_numero?: string | null;
  entrega_uf?: string | null;
  especie_volumes?: string | null;
  forma_pagamento?: string | null;
  frete_por_conta?: string | null;
  id: number;
  id_tiny: number;
  itens: Array<FaturaItem>;
  natureza_operacao?: string | null;
  numero?: number | null;
  numero_ecommerce?: string | null;
  numero_pedido?: number | null;
  observacoes?: string | null;
  parcelas: Array<FaturaParcela>;
  peso_bruto?: number | null;
  peso_liquido?: number | null;
  quantidade_volumes?: number | null;
  saida_em?: string | null;
  serie?: number | null;
  situacao?: number | null;
  transportadora_cidade?: string | null;
  transportadora_cpf_cnpj?: string | null;
  transportadora_nome?: string | null;
  transportadora_uf?: string | null;
  url_rastreamento?: string | null;
  valor_desconto?: number | null;
  valor_faturado?: number | null;
  valor_frete?: number | null;
  valor_icms?: number | null;
  valor_icms_st?: number | null;
  valor_ipi?: number | null;
  valor_outros?: number | null;
  valor_produtos?: number | null;
  valor_seguro?: number | null;
  valor_total?: number | null;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Fatura;

pub struct Fatura {
    pub base_icms: Option<f64>,
    pub base_icms_st: Option<f64>,
    pub chave_acesso: Option<String>,
    pub cliente_bairro: Option<String>,
    pub cliente_cep: Option<String>,
    pub cliente_cidade: Option<String>,
    pub cliente_codigo: Option<String>,
    pub cliente_complemento: Option<String>,
    pub cliente_cpf_cnpj: Option<String>,
    pub cliente_email: Option<String>,
    pub cliente_inscricao_estadual: Option<String>,
    pub cliente_logradouro: Option<String>,
    pub cliente_nome: Option<String>,
    pub cliente_numero: Option<String>,
    pub cliente_telefone: Option<String>,
    pub cliente_tipo_pessoa: Option<String>,
    pub cliente_uf: Option<String>,
    pub codigo_rastreamento: Option<String>,
    pub condicao_pagamento: Option<String>,
    pub descricao_situacao: Option<String>,
    pub emitida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub entrega_bairro: Option<String>,
    pub entrega_cep: Option<String>,
    pub entrega_cidade: Option<String>,
    pub entrega_complemento: Option<String>,
    pub entrega_cpf_cnpj: Option<String>,
    pub entrega_logradouro: Option<String>,
    pub entrega_nome: Option<String>,
    pub entrega_numero: Option<String>,
    pub entrega_uf: Option<String>,
    pub especie_volumes: Option<String>,
    pub forma_pagamento: Option<String>,
    pub frete_por_conta: Option<String>,
    pub id: i64,
    pub id_tiny: i64,
    pub itens: Vec<FaturaItem>,
    pub natureza_operacao: Option<String>,
    pub numero: Option<i64>,
    pub numero_ecommerce: Option<String>,
    pub numero_pedido: Option<i64>,
    pub observacoes: Option<String>,
    pub parcelas: Vec<FaturaParcela>,
    pub peso_bruto: Option<f64>,
    pub peso_liquido: Option<f64>,
    pub quantidade_volumes: Option<i64>,
    pub saida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub serie: Option<i64>,
    pub situacao: Option<i32>,
    pub transportadora_cidade: Option<String>,
    pub transportadora_cpf_cnpj: Option<String>,
    pub transportadora_nome: Option<String>,
    pub transportadora_uf: Option<String>,
    pub url_rastreamento: Option<String>,
    pub valor_desconto: Option<f64>,
    pub valor_faturado: Option<f64>,
    pub valor_frete: Option<f64>,
    pub valor_icms: Option<f64>,
    pub valor_icms_st: Option<f64>,
    pub valor_ipi: Option<f64>,
    pub valor_outros: Option<f64>,
    pub valor_produtos: Option<f64>,
    pub valor_seguro: Option<f64>,
    pub valor_total: Option<f64>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### FaturaItem [#tipo-faturaitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FaturaItem } from "termo_core/intranet";

export interface FaturaItem {
  cfop?: string | null;
  codigo?: string | null;
  descricao?: string | null;
  id: number;
  ncm?: string | null;
  quantidade?: number | null;
  unidade?: string | null;
  valor_total?: number | null;
  valor_unitario?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::FaturaItem;

pub struct FaturaItem {
    pub cfop: Option<String>,
    pub codigo: Option<String>,
    pub descricao: Option<String>,
    pub id: i64,
    pub ncm: Option<String>,
    pub quantidade: Option<f64>,
    pub unidade: Option<String>,
    pub valor_total: Option<f64>,
    pub valor_unitario: Option<f64>,
}
```

</Tab>
</Tabs>

### FaturaParcela [#tipo-faturaparcela]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FaturaParcela } from "termo_core/intranet";

export interface FaturaParcela {
  dias?: number | null;
  forma_pagamento?: string | null;
  id: number;
  meio_pagamento?: string | null;
  observacao?: string | null;
  valor?: number | null;
  vencimento?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::FaturaParcela;

pub struct FaturaParcela {
    pub dias: Option<i64>,
    pub forma_pagamento: Option<String>,
    pub id: i64,
    pub meio_pagamento: Option<String>,
    pub observacao: Option<String>,
    pub valor: Option<f64>,
    pub vencimento: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>

### FaturaResumo [#tipo-faturaresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FaturaResumo } from "termo_core/intranet";

export interface FaturaResumo {
  cliente_cidade?: string | null;
  cliente_cpf_cnpj?: string | null;
  cliente_nome?: string | null;
  cliente_uf?: string | null;
  descricao_situacao?: string | null;
  emitida_em?: string | null;
  id: number;
  id_tiny: number;
  natureza_operacao?: string | null;
  numero?: number | null;
  numero_pedido?: number | null;
  serie?: number | null;
  situacao?: number | null;
  valor_total?: number | null;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::FaturaResumo;

pub struct FaturaResumo {
    pub cliente_cidade: Option<String>,
    pub cliente_cpf_cnpj: Option<String>,
    pub cliente_nome: Option<String>,
    pub cliente_uf: Option<String>,
    pub descricao_situacao: Option<String>,
    pub emitida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub id: i64,
    pub id_tiny: i64,
    pub natureza_operacao: Option<String>,
    pub numero: Option<i64>,
    pub numero_pedido: Option<i64>,
    pub serie: Option<i64>,
    pub situacao: Option<i32>,
    pub valor_total: Option<f64>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaFaturaAutoCompleteI64 [#tipo-paginafaturaautocompletei64]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaAutoCompleteI64 } from "termo_core/intranet";

export interface PaginaFaturaAutoCompleteI64 {
  itens: Array<PaginaFaturaAutoCompleteI64ItensItem>;
  proximo_cursor?: number;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFaturaAutoCompleteI64;

pub struct PaginaFaturaAutoCompleteI64 {
    pub itens: Vec<PaginaFaturaAutoCompleteI64ItensItem>,
    pub proximo_cursor: Option<i64>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaFaturaAutoCompleteI64ItensItem [#tipo-paginafaturaautocompletei64itensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaAutoCompleteI64ItensItem } from "termo_core/intranet";

export interface PaginaFaturaAutoCompleteI64ItensItem {
  cliente_nome?: string | null;
  id: number;
  numero?: number | null;
  serie?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFaturaAutoCompleteI64ItensItem;

pub struct PaginaFaturaAutoCompleteI64ItensItem {
    pub cliente_nome: Option<String>,
    pub id: i64,
    pub numero: Option<i64>,
    pub serie: Option<i64>,
}
```

</Tab>
</Tabs>

### PaginaFaturaResumoI64 [#tipo-paginafaturaresumoi64]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaResumoI64 } from "termo_core/intranet";

export interface PaginaFaturaResumoI64 {
  itens: Array<PaginaFaturaResumoI64ItensItem>;
  proximo_cursor?: number;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFaturaResumoI64;

pub struct PaginaFaturaResumoI64 {
    pub itens: Vec<PaginaFaturaResumoI64ItensItem>,
    pub proximo_cursor: Option<i64>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaFaturaResumoI64ItensItem [#tipo-paginafaturaresumoi64itensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaResumoI64ItensItem } from "termo_core/intranet";

export interface PaginaFaturaResumoI64ItensItem {
  cliente_cidade?: string | null;
  cliente_cpf_cnpj?: string | null;
  cliente_nome?: string | null;
  cliente_uf?: string | null;
  descricao_situacao?: string | null;
  emitida_em?: string | null;
  id: number;
  id_tiny: number;
  natureza_operacao?: string | null;
  numero?: number | null;
  numero_pedido?: number | null;
  serie?: number | null;
  situacao?: number | null;
  valor_total?: number | null;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFaturaResumoI64ItensItem;

pub struct PaginaFaturaResumoI64ItensItem {
    pub cliente_cidade: Option<String>,
    pub cliente_cpf_cnpj: Option<String>,
    pub cliente_nome: Option<String>,
    pub cliente_uf: Option<String>,
    pub descricao_situacao: Option<String>,
    pub emitida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub id: i64,
    pub id_tiny: i64,
    pub natureza_operacao: Option<String>,
    pub numero: Option<i64>,
    pub numero_pedido: Option<i64>,
    pub serie: Option<i64>,
    pub situacao: Option<i32>,
    pub valor_total: Option<f64>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### Total [#tipo-total]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Total } from "termo_core/intranet";

export interface Total {
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Total;

pub struct Total {
    pub total: i64,
}
```

</Tab>
</Tabs>


# Funcionário (/docs/servicos/intranet/funcionario)

> 5 funções do TermoIntranetAPI para funcionário.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_funcionario`](#buscar_paginador_funcionario) | `GET /funcionario` | Lista funcionários com paginação por cursor |
| [`buscar_auto_complete_funcionario`](#buscar_auto_complete_funcionario) | `GET /funcionario/autocomplete` | Lista básica para seleção |
| [`buscar_pelo_filtro_funcionario`](#buscar_pelo_filtro_funcionario) | `GET /funcionario/filtro` | Busca por filtro |
| [`buscar_total_funcionario`](#buscar_total_funcionario) | `GET /funcionario/total` | Total de registros do paginador |
| [`buscar_pelo_id_funcionario`](#buscar_pelo_id_funcionario) | `GET /funcionario/{id}` | Busca pelo id |

## `buscar_paginador_funcionario` [#buscar_paginador_funcionario]

<Rota metodo="GET" caminho="/funcionario" credencial />

Lista funcionários com paginação por cursor

Exige qualquer permissão da área `funcionarios`. Ordena por nome e id, sempre 50 itens por página. Só funcionários ativos do tipo colaborador no cadastro da intranet, só leitura. Sem `cursor` vem a primeira página; para a seguinte, envie em `cursor` o `proximo_cursor` recebido (nulo na última página). O total de registros não vem aqui: está em `GET /funcionario/total`, para a lista não esperar o `count(*)`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_funcionario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorFuncionario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFuncionarioResumoI64>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_funcionario } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_funcionario(credencial_de_acesso, { cursor: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_funcionario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorFuncionario,
) -> Result<tipos::PaginaFuncionarioResumoI64, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_paginador_funcionario(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPaginadorFuncionario { cursor: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFuncionarioResumoI64>` · Rust: `Result<tipos::PaginaFuncionarioResumoI64, ErroAoChamarServico>` · veja [`PaginaFuncionarioResumoI64`](#tipo-paginafuncionarioresumoi64).

## `buscar_auto_complete_funcionario` [#buscar_auto_complete_funcionario]

<Rota metodo="GET" caminho="/funcionario/autocomplete" credencial />

Lista básica para seleção

Exige qualquer permissão da área `funcionarios`. Devolve só id, nome e departamento, em ordem alfabética de nome, para escolher um funcionário ativo. `busca` procura por trecho do nome ou da matrícula. Paginação por cursor: `tamanho` tem padrão 10 e máximo 100, e para a página seguinte envie em `cursor` o `proximo_cursor` recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_funcionario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteFuncionario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFuncionarioAutoCompleteI64>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_funcionario } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_funcionario(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_funcionario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteFuncionario,
) -> Result<tipos::PaginaFuncionarioAutoCompleteI64, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_auto_complete_funcionario(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarAutoCompleteFuncionario { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFuncionarioAutoCompleteI64>` · Rust: `Result<tipos::PaginaFuncionarioAutoCompleteI64, ErroAoChamarServico>` · veja [`PaginaFuncionarioAutoCompleteI64`](#tipo-paginafuncionarioautocompletei64).

## `buscar_pelo_filtro_funcionario` [#buscar_pelo_filtro_funcionario]

<Rota metodo="GET" caminho="/funcionario/filtro" credencial />

Busca por filtro

Exige qualquer permissão da área `funcionarios`. Aceita `nome`, `cpf`, `matricula`, `departamento`, `cargo`, `unidade` e `tipo_contrato`; informe ao menos um. Devolve no máximo 100 registros.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_funcionario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroFuncionario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.FuncionarioResumo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_funcionario } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_funcionario(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_funcionario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroFuncionario,
) -> Result<Vec<tipos::FuncionarioResumo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_filtro_funcionario(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPeloFiltroFuncionario { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cpf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.matricula": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.departamento": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_contrato": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.FuncionarioResumo>>` · Rust: `Result<Vec<tipos::FuncionarioResumo>, ErroAoChamarServico>`

## `buscar_total_funcionario` [#buscar_total_funcionario]

<Rota metodo="GET" caminho="/funcionario/total" credencial />

Total de registros do paginador

Exige qualquer permissão da área `funcionarios`. Devolve só o `count(*)` com os mesmos filtros de `GET /funcionario`, para o frontend montar o paginador sem atrasar a lista: a tela pede a primeira página e o total em paralelo. Conta os mesmos funcionários ativos do tipo colaborador que a listagem devolve.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_total_funcionario(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Total>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_total_funcionario } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_total_funcionario(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_total_funcionario(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Total, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_total_funcionario(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Total>` · Rust: `Result<tipos::Total, ErroAoChamarServico>` · veja [`Total`](#tipo-total).

## `buscar_pelo_id_funcionario` [#buscar_pelo_id_funcionario]

<Rota metodo="GET" caminho="/funcionario/{id}" credencial />

Busca pelo id

Exige qualquer permissão da área `funcionarios`. Devolve o funcionário ativo completo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_funcionario(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Funcionario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_funcionario } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_funcionario(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_funcionario(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::Funcionario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_funcionario(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Funcionario>` · Rust: `Result<tipos::Funcionario, ErroAoChamarServico>` · veja [`Funcionario`](#tipo-funcionario).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Email [#tipo-email]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Email } from "termo_core/intranet";

export interface Email {
  corporativo: boolean;
  endereco: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Email;

pub struct Email {
    pub corporativo: bool,
    pub endereco: String,
}
```

</Tab>
</Tabs>

### Funcionario [#tipo-funcionario]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Funcionario } from "termo_core/intranet";

export interface Funcionario {
  admitido_em?: string | null;
  cargo?: string | null;
  chefe_imediato?: string | null;
  codigo_barras?: string | null;
  cpf?: string | null;
  ctps_serie?: string | null;
  departamento?: string | null;
  em_ferias: boolean;
  emails: Array<Email>;
  empresa_cnpj?: string | null;
  empresa_nome?: string | null;
  estado_civil?: string | null;
  ferias_ate?: string | null;
  ferias_de?: string | null;
  genero?: string | null;
  gestor: boolean;
  id: number;
  jornada?: string | null;
  matricula?: string | null;
  nascido_em?: string | null;
  nome: string;
  observacao?: string | null;
  pis?: string | null;
  ramal?: string | null;
  rg?: string | null;
  telefones: Array<Telefone>;
  tipo_contrato?: string | null;
  ultimo_acesso?: string | null;
  unidade?: string | null;
  usuario: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Funcionario;

pub struct Funcionario {
    pub admitido_em: Option<chrono::NaiveDate>,
    pub cargo: Option<String>,
    pub chefe_imediato: Option<String>,
    pub codigo_barras: Option<String>,
    pub cpf: Option<String>,
    pub ctps_serie: Option<String>,
    pub departamento: Option<String>,
    pub em_ferias: bool,
    pub emails: Vec<Email>,
    pub empresa_cnpj: Option<String>,
    pub empresa_nome: Option<String>,
    pub estado_civil: Option<String>,
    pub ferias_ate: Option<chrono::NaiveDate>,
    pub ferias_de: Option<chrono::NaiveDate>,
    pub genero: Option<String>,
    pub gestor: bool,
    pub id: i64,
    pub jornada: Option<String>,
    pub matricula: Option<String>,
    pub nascido_em: Option<chrono::NaiveDate>,
    pub nome: String,
    pub observacao: Option<String>,
    pub pis: Option<String>,
    pub ramal: Option<String>,
    pub rg: Option<String>,
    pub telefones: Vec<Telefone>,
    pub tipo_contrato: Option<String>,
    pub ultimo_acesso: Option<chrono::DateTime<chrono::Utc>>,
    pub unidade: Option<String>,
    pub usuario: String,
}
```

</Tab>
</Tabs>

### FuncionarioResumo [#tipo-funcionarioresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FuncionarioResumo } from "termo_core/intranet";

export interface FuncionarioResumo {
  admitido_em?: string | null;
  cargo?: string | null;
  departamento?: string | null;
  id: number;
  matricula?: string | null;
  nome: string;
  ramal?: string | null;
  tipo_contrato?: string | null;
  unidade?: string | null;
  usuario: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::FuncionarioResumo;

pub struct FuncionarioResumo {
    pub admitido_em: Option<chrono::NaiveDate>,
    pub cargo: Option<String>,
    pub departamento: Option<String>,
    pub id: i64,
    pub matricula: Option<String>,
    pub nome: String,
    pub ramal: Option<String>,
    pub tipo_contrato: Option<String>,
    pub unidade: Option<String>,
    pub usuario: String,
}
```

</Tab>
</Tabs>

### PaginaFuncionarioAutoCompleteI64 [#tipo-paginafuncionarioautocompletei64]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncionarioAutoCompleteI64 } from "termo_core/intranet";

export interface PaginaFuncionarioAutoCompleteI64 {
  itens: Array<PaginaFuncionarioAutoCompleteI64ItensItem>;
  proximo_cursor?: number;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFuncionarioAutoCompleteI64;

pub struct PaginaFuncionarioAutoCompleteI64 {
    pub itens: Vec<PaginaFuncionarioAutoCompleteI64ItensItem>,
    pub proximo_cursor: Option<i64>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaFuncionarioAutoCompleteI64ItensItem [#tipo-paginafuncionarioautocompletei64itensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncionarioAutoCompleteI64ItensItem } from "termo_core/intranet";

export interface PaginaFuncionarioAutoCompleteI64ItensItem {
  departamento?: string | null;
  id: number;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFuncionarioAutoCompleteI64ItensItem;

pub struct PaginaFuncionarioAutoCompleteI64ItensItem {
    pub departamento: Option<String>,
    pub id: i64,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaFuncionarioResumoI64 [#tipo-paginafuncionarioresumoi64]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncionarioResumoI64 } from "termo_core/intranet";

export interface PaginaFuncionarioResumoI64 {
  itens: Array<PaginaFuncionarioResumoI64ItensItem>;
  proximo_cursor?: number;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFuncionarioResumoI64;

pub struct PaginaFuncionarioResumoI64 {
    pub itens: Vec<PaginaFuncionarioResumoI64ItensItem>,
    pub proximo_cursor: Option<i64>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaFuncionarioResumoI64ItensItem [#tipo-paginafuncionarioresumoi64itensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFuncionarioResumoI64ItensItem } from "termo_core/intranet";

export interface PaginaFuncionarioResumoI64ItensItem {
  admitido_em?: string | null;
  cargo?: string | null;
  departamento?: string | null;
  id: number;
  matricula?: string | null;
  nome: string;
  ramal?: string | null;
  tipo_contrato?: string | null;
  unidade?: string | null;
  usuario: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaFuncionarioResumoI64ItensItem;

pub struct PaginaFuncionarioResumoI64ItensItem {
    pub admitido_em: Option<chrono::NaiveDate>,
    pub cargo: Option<String>,
    pub departamento: Option<String>,
    pub id: i64,
    pub matricula: Option<String>,
    pub nome: String,
    pub ramal: Option<String>,
    pub tipo_contrato: Option<String>,
    pub unidade: Option<String>,
    pub usuario: String,
}
```

</Tab>
</Tabs>

### Telefone [#tipo-telefone]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Telefone } from "termo_core/intranet";

export interface Telefone {
  ddd?: string | null;
  nome?: string | null;
  numero: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Telefone;

pub struct Telefone {
    pub ddd: Option<String>,
    pub nome: Option<String>,
    pub numero: String,
}
```

</Tab>
</Tabs>

### Total [#tipo-total]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Total } from "termo_core/intranet";

export interface Total {
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Total;

pub struct Total {
    pub total: i64,
}
```

</Tab>
</Tabs>


# TermoIntranetAPI (/docs/servicos/intranet)

> Consulta, só leitura, de clientes, faturas e funcionários vindos do banco da intranet da Termotubos, mais a administração de quem pode entrar (acessos, perfis de acesso com as permissões por área e c…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Consulta, só leitura, de clientes, faturas e funcionários vindos do banco da intranet da Termotubos, mais a administração de quem pode entrar (acessos, perfis de acesso com as permissões por área e colaboradores sincronizados do TermoAuth). O login é do TermoAuth: toda chamada autenticada usa o token do usuário logado. As listagens paginam por cursor, com 50 itens por página.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::intranet` (feature `intranet`) |
| Importação TypeScript | `termo_core/intranet` ou `import { intranet } from "termo_core"` |
| Funções | 43 |
| Entidades | 9 |
| Versão do contrato | `0.1.12` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51091` |
| `SANDBOX` | `https://sandbox-api-intranet.termotubos.com.br` |
| `PRODUCTION` | `https://api-intranet.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Cliente" href="/docs/servicos/intranet/cliente" description="5 funções" />
  <Card title="Fatura" href="/docs/servicos/intranet/fatura" description="5 funções" />
  <Card title="Funcionário" href="/docs/servicos/intranet/funcionario" description="5 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/intranet/auth" description="9 funções" />
  <Card title="Colaborador" href="/docs/servicos/intranet/colaborador" description="6 funções" />
  <Card title="Configuração" href="/docs/servicos/intranet/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/intranet/perfil_acesso" description="8 funções" />
  <Card title="Teste" href="/docs/servicos/intranet/test" description="2 funções" />
  <Card title="Webhooks" href="/docs/servicos/intranet/webhooks" description="1 função" />
</Cards>


# Perfil acesso (/docs/servicos/intranet/perfil_acesso)

> 8 funções do TermoIntranetAPI para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso com paginação por cursor |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_total_perfil_acesso`](#buscar_total_perfil_acesso) | `GET /perfil_acesso/total` | Total de registros do paginador |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso com paginação por cursor

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome e pelo id, sempre 50 itens por página. Sem `cursor` vem a primeira página; para a seguinte, envie em `cursor` o `proximo_cursor` recebido (nulo na última página). O total de registros não vem aqui: está em `GET /perfil_acesso/total`, para a lista não esperar o `count(*)`. Cursor de id inexistente devolve página vazia. Perfis excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoString>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { cursor: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoString, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPaginadorPerfilAcesso { cursor: Some(Default::default()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoString>` · Rust: `Result<tipos::PaginaPerfilAcessoString, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoString`](#tipo-paginaperfilacessostring).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoIntranetAPI dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`clientes`, `faturas`, `funcionarios`, `colaboradores`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. Paginação por cursor: `tamanho` tem padrão 10 e máximo 100, e para a página seguinte envie em `cursor` o `proximo_cursor` recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoCompleteString>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoCompleteString, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoCompleteString>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoCompleteString, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoCompleteString`](#tipo-paginaperfilacessoautocompletestring).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::intranet::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_total_perfil_acesso` [#buscar_total_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/total" credencial />

Total de registros do paginador

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o `count(*)` com os mesmos filtros de `GET /perfil_acesso`, para o frontend montar o paginador sem atrasar a lista: a tela pede a primeira página e o total em paralelo. Perfis excluídos não contam.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_total_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Total>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_total_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_total_perfil_acesso(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_total_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Total, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_total_perfil_acesso(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Total>` · Rust: `Result<tipos::Total, ErroAoChamarServico>` · veja [`Total`](#tipo-total).

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::intranet::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/intranet";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::intranet::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/intranet";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteString [#tipo-paginaperfilacessoautocompletestring]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteString } from "termo_core/intranet";

export interface PaginaPerfilAcessoAutoCompleteString {
  itens: Array<PaginaPerfilAcessoAutoCompleteStringItensItem>;
  proximo_cursor?: string;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaPerfilAcessoAutoCompleteString;

pub struct PaginaPerfilAcessoAutoCompleteString {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteStringItensItem>,
    pub proximo_cursor: Option<String>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteStringItensItem [#tipo-paginaperfilacessoautocompletestringitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteStringItensItem } from "termo_core/intranet";

export interface PaginaPerfilAcessoAutoCompleteStringItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaPerfilAcessoAutoCompleteStringItensItem;

pub struct PaginaPerfilAcessoAutoCompleteStringItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoString [#tipo-paginaperfilacessostring]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoString } from "termo_core/intranet";

export interface PaginaPerfilAcessoString {
  itens: Array<PaginaPerfilAcessoStringItensItem>;
  proximo_cursor?: string;
  tamanho: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaPerfilAcessoString;

pub struct PaginaPerfilAcessoString {
    pub itens: Vec<PaginaPerfilAcessoStringItensItem>,
    pub proximo_cursor: Option<String>,
    pub tamanho: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoStringItensItem [#tipo-paginaperfilacessostringitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoStringItensItem } from "termo_core/intranet";

export interface PaginaPerfilAcessoStringItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PaginaPerfilAcessoStringItensItem;

pub struct PaginaPerfilAcessoStringItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/intranet";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/intranet";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/intranet";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/intranet";

export interface Permissoes {
  clientes?: Acoes;
  colaboradores?: Acoes;
  faturas?: Acoes;
  funcionarios?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Permissoes;

pub struct Permissoes {
    pub clientes: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub faturas: Option<Acoes>,
    pub funcionarios: Option<Acoes>,
}
```

</Tab>
</Tabs>

### Total [#tipo-total]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Total } from "termo_core/intranet";

export interface Total {
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::Total;

pub struct Total {
    pub total: i64,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/intranet/test)

> 2 funções do TermoIntranetAPI para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true` e a versão do backend que está publicada, no formato semver.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/intranet";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::intranet::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` e a versão do backend no ar sempre que o servidor está de pé; não consulta os bancos nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/intranet";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::intranet::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/intranet";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/intranet";

export interface VersaoDoBackend {
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::VersaoDoBackend;

pub struct VersaoDoBackend {
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>


# Webhooks (/docs/servicos/intranet/webhooks)

> 1 função do TermoIntranetAPI para webhooks.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as intranet from "termo_core/intranet";
// ou: import { intranet } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["intranet"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`receber_evento_termo_webhook_webhooks`](#receber_evento_termo_webhook_webhooks) | `POST /webhooks/termowebhook` | Recebe os eventos entregues pelo TermoWebhook |

## `receber_evento_termo_webhook_webhooks` [#receber_evento_termo_webhook_webhooks]

<Rota metodo="POST" caminho="/webhooks/termowebhook" />

Recebe os eventos entregues pelo TermoWebhook

Pública, sem token do usuário: quem chama é o TermoWebhook, o hub de eventos da Termotubos, e a entrega é conferida pela assinatura Ed25519 do hub (chave pública do hub, data dentro da tolerância e id deste aplicativo como destino). Hoje são aplicados `colaborador.criado` e `colaborador.atualizado`, nas versões 1 e 2, que cadastram e atualizam o colaborador e o acesso a partir do TermoAuth; evento repetido ou mais antigo que o último aplicado é descartado sem erro, e tipo desconhecido responde `200` sem fazer nada. A resposta não tem corpo; qualquer status fora de `2xx` faz o hub reenviar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_termo_webhook_webhooks(
  parametros: ParametrosDeReceberEventoTermoWebhookWebhooks,
  corpo_da_requisicao: tipos.EntregaDoEvento,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { receber_evento_termo_webhook_webhooks } from "termo_core/intranet";

await receber_evento_termo_webhook_webhooks({ "X-TermoWebhook-Data": 1, "X-TermoWebhook-Chave": "...", "X-TermoWebhook-Assinatura": "..." }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_termo_webhook_webhooks(
    parametros: &ParametrosDeReceberEventoTermoWebhookWebhooks,
    corpo_da_requisicao: &tipos::EntregaDoEvento,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::intranet::receber_evento_termo_webhook_webhooks(
    &termo_core::intranet::ParametrosDeReceberEventoTermoWebhookWebhooks { x_termo_webhook_data, x_termo_webhook_chave, x_termo_webhook_assinatura, ..Default::default() },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.X-TermoWebhook-Data": { type: "number", required: true, description: "Horário Unix em segundos usado na assinatura\n\nEnviado no cabeçalho X-TermoWebhook-Data. · Rust: i64" },
    "parametros.X-TermoWebhook-Chave": { type: "string", required: true, description: "Identificador da chave do hub que assinou a entrega\n\nEnviado no cabeçalho X-TermoWebhook-Chave. · Rust: String" },
    "parametros.X-TermoWebhook-Destino": { type: "string | null", required: false, description: "Id do aplicativo de destino no hub\n\nEnviado no cabeçalho X-TermoWebhook-Destino. · Rust: Option<String>" },
    "parametros.X-TermoWebhook-Assinatura": { type: "string", required: true, description: "ed25519=<base64url> da assinatura de <data>.<destino>.<corpo> com a chave do hub\n\nEnviado no cabeçalho X-TermoWebhook-Assinatura. · Rust: String" },
    "corpo_da_requisicao": { type: "tipos.EntregaDoEvento", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EntregaDoEvento", typeDescriptionLink: "#tipo-entregadoevento" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EntregaDoEvento [#tipo-entregadoevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaDoEvento } from "termo_core/intranet";

export interface EntregaDoEvento {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  publicador: string;
  recebido_em: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::intranet::EntregaDoEvento;

pub struct EntregaDoEvento {
    pub dados: serde_json::Map<String, serde_json::Value>,
    pub entidade_id: String,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub publicador: String,
    pub recebido_em: chrono::DateTime<chrono::Utc>,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>


# Auth (/docs/servicos/leads/auth)

> 1 função do TermoLeads para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`eu_auth`](#eu_auth) | `GET /api/auth/eu` | Devolve o usuário logado e as permissões dele |

## `eu_auth` [#eu_auth]

<Rota metodo="GET" caminho="/api/auth/eu" credencial />

Devolve o usuário logado e as permissões dele

Exige login: token válido do TermoAuth, e-mail `@termotubos.com.br` e acesso cadastrado e ativo no TermoLeads (o master do TermoAuth ganha o acesso e o colaborador no primeiro pedido; os demais chegam pela sincronização que um master dispara ao listar os colaboradores). Não exige nenhuma área. Devolve `id` (o id no TermoAuth), `nome`, `email`, `master`, o nome do `perfil_acesso` e as `permissoes` de cada área, que o frontend usa para montar o menu.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function eu_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { eu_auth } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await eu_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn eu_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::eu_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/leads";

export interface AcessoAtual {
  /**
   * E-mail do usuário, sempre `@termotubos.com.br`
   */
  email: string;
  /**
   * Id do usuário no TermoAuth (o `sub` do token)
   */
  id: string;
  /**
   * `true` quando o token traz `isMaster`: tem todas as permissões e libera a importação da base
   */
  master: boolean;
  /**
   * Nome do usuário (o e-mail quando o token não traz nome)
   */
  nome: string;
  /**
   * Nome do perfil de acesso da pessoa; `null` quando não tem perfil
   */
  perfil_acesso?: string | null;
  /**
   * Ações liberadas em cada área (todas para o master)
   */
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::AcessoAtual;

pub struct AcessoAtual {
    /// E-mail do usuário, sempre `@termotubos.com.br`
    pub email: String,
    /// Id do usuário no TermoAuth (o `sub` do token)
    pub id: String,
    /// `true` quando o token traz `isMaster`: tem todas as permissões e libera a importação da base
    pub master: bool,
    /// Nome do usuário (o e-mail quando o token não traz nome)
    pub nome: String,
    /// Nome do perfil de acesso da pessoa; `null` quando não tem perfil
    pub perfil_acesso: Option<String>,
    /// Ações liberadas em cada área (todas para o master)
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/leads";

export interface Acoes {
  /**
   * Libera o cadastro na área
   */
  criar?: boolean;
  /**
   * Libera a exclusão na área
   */
  deletar?: boolean;
  /**
   * Libera a alteração na área
   */
  editar?: boolean;
  /**
   * Libera a leitura da área (qualquer outra ação liberada já libera a leitura)
   */
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Acoes;

pub struct Acoes {
    /// Libera o cadastro na área
    pub criar: Option<bool>,
    /// Libera a exclusão na área
    pub deletar: Option<bool>,
    /// Libera a alteração na área
    pub editar: Option<bool>,
    /// Libera a leitura da área (qualquer outra ação liberada já libera a leitura)
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/leads";

export interface Permissoes {
  /**
   * Ações liberadas na área `colaboradores`: colaboradores e perfis de acesso
   */
  colaboradores?: Acoes;
  /**
   * Ações liberadas na área `empresas`: Consultar CNPJ e Localizar Empresas
   */
  empresas?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Permissoes;

pub struct Permissoes {
    /// Ações liberadas na área `colaboradores`: colaboradores e perfis de acesso
    pub colaboradores: Option<Acoes>,
    /// Ações liberadas na área `empresas`: Consultar CNPJ e Localizar Empresas
    pub empresas: Option<Acoes>,
}
```

</Tab>
</Tabs>


# CNPJ (/docs/servicos/leads/cnpj)

> 2 funções do TermoLeads para cnpj.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_cnpj`](#buscar_pelo_id_cnpj) | `GET /api/cnpj/{cnpj}` | Consulta um estabelecimento pelo CNPJ |
| [`buscar_paginador_cnpj`](#buscar_paginador_cnpj) | `GET /api/empresas` | Lista estabelecimentos da base CNPJ com filtros e paginação |

## `buscar_pelo_id_cnpj` [#buscar_pelo_id_cnpj]

<Rota metodo="GET" caminho="/api/cnpj/{cnpj}" />

Consulta um estabelecimento pelo CNPJ

Rota pública, sem login. Devolve o cadastro completo de um estabelecimento da base CNPJ da Receita Federal: dados do estabelecimento (situação cadastral, CNAE principal e secundários, endereço, telefones, e-mail), da empresa (razão social, natureza jurídica, porte, capital social), do Simples Nacional e do MEI, e o quadro societário em `socios`. O CNPJ pode ir com ou sem máscara (`04.252.011/0001-10` ou `04252011000110`); só os dígitos contam e precisam ser 14. `socios` é uma lista de objetos em ordem alfabética do nome, com as chaves `cnpj_basico`, `identificador_socio`, `identificador_socio_descricao`, `nome_socio_razao_social`, `cnpj_cpf_socio`, `qualificacao_socio`, `qualificacao_socio_descricao`, `data_entrada_sociedade`, `pais`, `pais_descricao`, `representante_legal`, `nome_representante`, `qualificacao_representante`, `qualificacao_representante_descricao` e `faixa_etaria`, todas em texto. Datas e códigos vêm em texto, como a Receita publica. A situação cadastral `02` é a ativa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_cnpj(
  cnpj: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cnpj>
```

```ts title="Exemplo"
import { buscar_pelo_id_cnpj } from "termo_core/leads";

const resposta = await buscar_pelo_id_cnpj(cnpj);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_cnpj(cnpj: &str) -> Result<tipos::Cnpj, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::leads::buscar_pelo_id_cnpj(&cnpj).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "cnpj": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cnpj>` · Rust: `Result<tipos::Cnpj, ErroAoChamarServico>` · veja [`Cnpj`](#tipo-cnpj).

## `buscar_paginador_cnpj` [#buscar_paginador_cnpj]

<Rota metodo="GET" caminho="/api/empresas" credencial />

Lista estabelecimentos da base CNPJ com filtros e paginação

Exige qualquer permissão da área `empresas` (o master do TermoAuth tem todas). Lista os estabelecimentos da base CNPJ da Receita Federal em ordem de CNPJ, com um resumo de cada um (razão social, nome fantasia, capital social, situação, UF, município, endereço, telefones e e-mail); o cadastro completo sai em `GET /api/cnpj/{cnpj}`. Todos os filtros são opcionais e se somam; valor vazio é ignorado. `tamanho` tem padrão 12 e máximo 50 (valores fora do intervalo são ajustados para 1 a 50); `pagina` começa em 1 e é ajustada para o intervalo válido. `total` é a contagem dos registros que casam com o filtro, limitada a 2.000.000: quando passa desse teto, ou quando a contagem demora mais de 6 segundos, `total` vem 2.000.000 e `estimado` vem `true`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_cnpj(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCnpj = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDeEmpresas>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_cnpj } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_cnpj(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_cnpj(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCnpj,
) -> Result<tipos::PaginaDeEmpresas, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_paginador_cnpj(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarPaginadorCnpj { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Número da página, a partir de 1 (padrão 1) · Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Itens por página, de 1 a 50 (padrão 12) · Rust: Option<i64>" },
    "parametros.situacao": { type: "string", required: false, description: "ativa (situação cadastral 02) ou inativa (qualquer outra); outro valor é ignorado · Rust: Option<String>" },
    "parametros.uf": { type: "string", required: false, description: "Sigla da UF, sem diferenciar maiúsculas (ex.: SP) · Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Nome exato do município como a Receita publica, sem diferenciar maiúsculas e aceitando com ou sem acento (ex.: São Paulo) · Rust: Option<String>" },
    "parametros.cnae": { type: "string", required: false, description: "Um ou mais códigos do CNAE fiscal principal separados por vírgula, com ou sem pontuação (ex.: 6201-5/00,4781400) · Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDeEmpresas>` · Rust: `Result<tipos::PaginaDeEmpresas, ErroAoChamarServico>` · veja [`PaginaDeEmpresas`](#tipo-paginadeempresas).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Cnpj [#tipo-cnpj]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cnpj } from "termo_core/leads";

export interface Cnpj {
  /**
   * Bairro
   */
  bairro?: string | null;
  /**
   * CEP, 8 dígitos sem máscara
   */
  cep?: string | null;
  /**
   * Código do CNAE fiscal principal, 7 dígitos
   */
  cnae_fiscal_principal?: string | null;
  /**
   * Descrição do CNAE fiscal principal
   */
  cnae_fiscal_principal_descricao?: string | null;
  /**
   * Códigos dos CNAEs secundários separados por vírgula, como a Receita publica
   */
  cnae_fiscal_secundaria?: string | null;
  /**
   * CNPJ do estabelecimento, 14 dígitos sem máscara
   */
  cnpj: string;
  /**
   * Oito primeiros dígitos do CNPJ, que identificam a empresa
   */
  cnpj_basico: string;
  /**
   * Dois dígitos verificadores do CNPJ
   */
  cnpj_dv?: string | null;
  /**
   * Quatro dígitos da ordem do estabelecimento (0001 é a matriz na maioria dos casos)
   */
  cnpj_ordem?: string | null;
  /**
   * Complemento do endereço
   */
  complemento?: string | null;
  /**
   * E-mail cadastrado na Receita
   */
  correio_eletronico?: string | null;
  /**
   * Data de início da atividade, no formato AAAAMMDD
   */
  data_inicio_atividade?: string | null;
  /**
   * Data da situação cadastral, no formato AAAAMMDD
   */
  data_situacao_cadastral?: string | null;
  /**
   * Data da situação especial, no formato AAAAMMDD
   */
  data_situacao_especial?: string | null;
  /**
   * DDD do telefone 1
   */
  ddd_1?: string | null;
  /**
   * DDD do telefone 2
   */
  ddd_2?: string | null;
  /**
   * DDD do fax
   */
  ddd_fax?: string | null;
  /**
   * Capital social em reais, em texto com vírgula decimal (ex.: `5000,00`)
   */
  empresa_capital_social?: string | null;
  /**
   * Ente federativo responsável, preenchido só para natureza jurídica de órgão público
   */
  empresa_ente_federativo_responsavel?: string | null;
  /**
   * Código da natureza jurídica
   */
  empresa_natureza_juridica?: string | null;
  /**
   * Natureza jurídica por extenso
   */
  empresa_natureza_juridica_descricao?: string | null;
  /**
   * Código do porte: 00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais
   */
  empresa_porte_empresa?: string | null;
  /**
   * Porte por extenso: `Não informado`, `Microempresa`, `Empresa de Pequeno Porte` ou `Demais`
   */
  empresa_porte_empresa_descricao?: string | null;
  /**
   * Código da qualificação do responsável pela empresa
   */
  empresa_qualificacao_responsavel?: string | null;
  /**
   * Qualificação do responsável por extenso
   */
  empresa_qualificacao_responsavel_descricao?: string | null;
  /**
   * Razão social da empresa
   */
  empresa_razao_social?: string | null;
  /**
   * Fax, sem o DDD
   */
  fax?: string | null;
  /**
   * Código da Receita: 1 matriz, 2 filial
   */
  identificador_matriz_filial?: string | null;
  /**
   * `Matriz` ou `Filial`
   */
  identificador_matriz_filial_descricao?: string | null;
  /**
   * Nome do logradouro
   */
  logradouro?: string | null;
  /**
   * Código do motivo da situação cadastral
   */
  motivo_situacao_cadastral?: string | null;
  /**
   * Motivo da situação cadastral por extenso
   */
  motivo_situacao_cadastral_descricao?: string | null;
  /**
   * Código do município na tabela da Receita
   */
  municipio?: string | null;
  /**
   * Nome do município em maiúsculas
   */
  municipio_descricao?: string | null;
  /**
   * Cidade no exterior, quando o estabelecimento fica fora do Brasil
   */
  nome_cidade_exterior?: string | null;
  /**
   * Nome fantasia do estabelecimento
   */
  nome_fantasia?: string | null;
  /**
   * Número do endereço
   */
  numero?: string | null;
  /**
   * Código do país, quando o estabelecimento fica no exterior
   */
  pais?: string | null;
  /**
   * Nome do país
   */
  pais_descricao?: string | null;
  /**
   * Data da exclusão do MEI, no formato AAAAMMDD
   */
  simples_data_exclusao_mei?: string | null;
  /**
   * Data da exclusão do Simples Nacional, no formato AAAAMMDD
   */
  simples_data_exclusao_simples?: string | null;
  /**
   * Data da opção pelo MEI, no formato AAAAMMDD
   */
  simples_data_opcao_mei?: string | null;
  /**
   * Data da opção pelo Simples Nacional, no formato AAAAMMDD
   */
  simples_data_opcao_simples?: string | null;
  /**
   * Opção pelo MEI: `S` ou `N`
   */
  simples_opcao_pelo_mei?: string | null;
  /**
   * Opção pelo MEI por extenso: `Sim` ou `Não`
   */
  simples_opcao_pelo_mei_descricao?: string | null;
  /**
   * Opção pelo Simples Nacional: `S` ou `N`
   */
  simples_opcao_pelo_simples?: string | null;
  /**
   * Opção pelo Simples Nacional por extenso: `Sim` ou `Não`
   */
  simples_opcao_pelo_simples_descricao?: string | null;
  /**
   * Código da situação cadastral: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada
   */
  situacao_cadastral?: string | null;
  /**
   * Situação cadastral por extenso: `Nula`, `Ativa`, `Suspensa`, `Inapta` ou `Baixada`
   */
  situacao_cadastral_descricao?: string | null;
  /**
   * Situação especial do estabelecimento, quando houver
   */
  situacao_especial?: string | null;
  /**
   * Quadro societário em ordem alfabética do nome; cada sócio é um objeto com textos nas chaves `cnpj_basico`, `identificador_socio` (1 pessoa jurídica, 2 pessoa física, 3 estrangeiro), `identificador_socio_descricao`, `nome_socio_razao_social`, `cnpj_cpf_socio` (CPF parcialmente mascarado pela Receita), `qualificacao_socio`, `qualificacao_socio_descricao`, `data_entrada_sociedade` (AAAAMMDD), `pais`, `pais_descricao`, `representante_legal`, `nome_representante`, `qualificacao_representante`, `qualificacao_representante_descricao` e `faixa_etaria`. Lista vazia quando não há sócios
   */
  socios: Array<Record<string, unknown>>;
  /**
   * Telefone 1, sem o DDD
   */
  telefone_1?: string | null;
  /**
   * Telefone 2, sem o DDD
   */
  telefone_2?: string | null;
  /**
   * `true` quando os dados da empresa (razão social, natureza, porte, capital) foram encontrados na base
   */
  tem_empresa: boolean;
  /**
   * `true` quando a empresa tem registro do Simples Nacional ou do MEI na base
   */
  tem_simples: boolean;
  /**
   * Tipo do logradouro (ex.: RUA, AVENIDA)
   */
  tipo_logradouro?: string | null;
  /**
   * Sigla da UF
   */
  uf?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Cnpj;

pub struct Cnpj {
    /// Bairro
    pub bairro: Option<String>,
    /// CEP, 8 dígitos sem máscara
    pub cep: Option<String>,
    /// Código do CNAE fiscal principal, 7 dígitos
    pub cnae_fiscal_principal: Option<String>,
    /// Descrição do CNAE fiscal principal
    pub cnae_fiscal_principal_descricao: Option<String>,
    /// Códigos dos CNAEs secundários separados por vírgula, como a Receita publica
    pub cnae_fiscal_secundaria: Option<String>,
    /// CNPJ do estabelecimento, 14 dígitos sem máscara
    pub cnpj: String,
    /// Oito primeiros dígitos do CNPJ, que identificam a empresa
    pub cnpj_basico: String,
    /// Dois dígitos verificadores do CNPJ
    pub cnpj_dv: Option<String>,
    /// Quatro dígitos da ordem do estabelecimento (0001 é a matriz na maioria dos casos)
    pub cnpj_ordem: Option<String>,
    /// Complemento do endereço
    pub complemento: Option<String>,
    /// E-mail cadastrado na Receita
    pub correio_eletronico: Option<String>,
    /// Data de início da atividade, no formato AAAAMMDD
    pub data_inicio_atividade: Option<String>,
    /// Data da situação cadastral, no formato AAAAMMDD
    pub data_situacao_cadastral: Option<String>,
    /// Data da situação especial, no formato AAAAMMDD
    pub data_situacao_especial: Option<String>,
    /// DDD do telefone 1
    pub ddd_1: Option<String>,
    /// DDD do telefone 2
    pub ddd_2: Option<String>,
    /// DDD do fax
    pub ddd_fax: Option<String>,
    /// Capital social em reais, em texto com vírgula decimal (ex.: `5000,00`)
    pub empresa_capital_social: Option<String>,
    /// Ente federativo responsável, preenchido só para natureza jurídica de órgão público
    pub empresa_ente_federativo_responsavel: Option<String>,
    /// Código da natureza jurídica
    pub empresa_natureza_juridica: Option<String>,
    /// Natureza jurídica por extenso
    pub empresa_natureza_juridica_descricao: Option<String>,
    /// Código do porte: 00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais
    pub empresa_porte_empresa: Option<String>,
    /// Porte por extenso: `Não informado`, `Microempresa`, `Empresa de Pequeno Porte` ou `Demais`
    pub empresa_porte_empresa_descricao: Option<String>,
    /// Código da qualificação do responsável pela empresa
    pub empresa_qualificacao_responsavel: Option<String>,
    /// Qualificação do responsável por extenso
    pub empresa_qualificacao_responsavel_descricao: Option<String>,
    /// Razão social da empresa
    pub empresa_razao_social: Option<String>,
    /// Fax, sem o DDD
    pub fax: Option<String>,
    /// Código da Receita: 1 matriz, 2 filial
    pub identificador_matriz_filial: Option<String>,
    /// `Matriz` ou `Filial`
    pub identificador_matriz_filial_descricao: Option<String>,
    /// Nome do logradouro
    pub logradouro: Option<String>,
    /// Código do motivo da situação cadastral
    pub motivo_situacao_cadastral: Option<String>,
    /// Motivo da situação cadastral por extenso
    pub motivo_situacao_cadastral_descricao: Option<String>,
    /// Código do município na tabela da Receita
    pub municipio: Option<String>,
    /// Nome do município em maiúsculas
    pub municipio_descricao: Option<String>,
    /// Cidade no exterior, quando o estabelecimento fica fora do Brasil
    pub nome_cidade_exterior: Option<String>,
    /// Nome fantasia do estabelecimento
    pub nome_fantasia: Option<String>,
    /// Número do endereço
    pub numero: Option<String>,
    /// Código do país, quando o estabelecimento fica no exterior
    pub pais: Option<String>,
    /// Nome do país
    pub pais_descricao: Option<String>,
    /// Data da exclusão do MEI, no formato AAAAMMDD
    pub simples_data_exclusao_mei: Option<String>,
    /// Data da exclusão do Simples Nacional, no formato AAAAMMDD
    pub simples_data_exclusao_simples: Option<String>,
    /// Data da opção pelo MEI, no formato AAAAMMDD
    pub simples_data_opcao_mei: Option<String>,
    /// Data da opção pelo Simples Nacional, no formato AAAAMMDD
    pub simples_data_opcao_simples: Option<String>,
    /// Opção pelo MEI: `S` ou `N`
    pub simples_opcao_pelo_mei: Option<String>,
    /// Opção pelo MEI por extenso: `Sim` ou `Não`
    pub simples_opcao_pelo_mei_descricao: Option<String>,
    /// Opção pelo Simples Nacional: `S` ou `N`
    pub simples_opcao_pelo_simples: Option<String>,
    /// Opção pelo Simples Nacional por extenso: `Sim` ou `Não`
    pub simples_opcao_pelo_simples_descricao: Option<String>,
    /// Código da situação cadastral: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada
    pub situacao_cadastral: Option<String>,
    /// Situação cadastral por extenso: `Nula`, `Ativa`, `Suspensa`, `Inapta` ou `Baixada`
    pub situacao_cadastral_descricao: Option<String>,
    /// Situação especial do estabelecimento, quando houver
    pub situacao_especial: Option<String>,
    /// Quadro societário em ordem alfabética do nome; cada sócio é um objeto com textos nas chaves `cnpj_basico`, `identificador_socio` (1 pessoa jurídica, 2 pessoa física, 3 estrangeiro), `identificador_socio_descricao`, `nome_socio_razao_social`, `cnpj_cpf_socio` (CPF parcialmente mascarado pela Receita), `qualificacao_socio`, `qualificacao_socio_descricao`, `data_entrada_sociedade` (AAAAMMDD), `pais`, `pais_descricao`, `representante_legal`, `nome_representante`, `qualificacao_representante`, `qualificacao_representante_descricao` e `faixa_etaria`. Lista vazia quando não há sócios
    pub socios: Vec<serde_json::Map<String, serde_json::Value>>,
    /// Telefone 1, sem o DDD
    pub telefone_1: Option<String>,
    /// Telefone 2, sem o DDD
    pub telefone_2: Option<String>,
    /// `true` quando os dados da empresa (razão social, natureza, porte, capital) foram encontrados na base
    pub tem_empresa: bool,
    /// `true` quando a empresa tem registro do Simples Nacional ou do MEI na base
    pub tem_simples: bool,
    /// Tipo do logradouro (ex.: RUA, AVENIDA)
    pub tipo_logradouro: Option<String>,
    /// Sigla da UF
    pub uf: Option<String>,
}
```

</Tab>
</Tabs>

### CnpjResumo [#tipo-cnpjresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CnpjResumo } from "termo_core/leads";

export interface CnpjResumo {
  /**
   * CNPJ do estabelecimento, 14 dígitos sem máscara
   */
  cnpj: string;
  /**
   * E-mail cadastrado na Receita
   */
  correio_eletronico?: string | null;
  /**
   * DDD do telefone 1
   */
  ddd_1?: string | null;
  /**
   * DDD do telefone 2
   */
  ddd_2?: string | null;
  /**
   * Capital social em reais, em texto com vírgula decimal (ex.: `5000,00`)
   */
  empresa_capital_social?: string | null;
  /**
   * Razão social da empresa
   */
  empresa_razao_social?: string | null;
  /**
   * Nome do logradouro
   */
  logradouro?: string | null;
  /**
   * Nome do município em maiúsculas
   */
  municipio_descricao?: string | null;
  /**
   * Nome fantasia do estabelecimento
   */
  nome_fantasia?: string | null;
  /**
   * Número do endereço
   */
  numero?: string | null;
  /**
   * Situação cadastral por extenso: `Nula`, `Ativa`, `Suspensa`, `Inapta` ou `Baixada`
   */
  situacao_cadastral_descricao?: string | null;
  /**
   * Telefone 1, sem o DDD
   */
  telefone_1?: string | null;
  /**
   * Telefone 2, sem o DDD
   */
  telefone_2?: string | null;
  /**
   * Tipo do logradouro (ex.: RUA, AVENIDA)
   */
  tipo_logradouro?: string | null;
  /**
   * Sigla da UF
   */
  uf?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::CnpjResumo;

pub struct CnpjResumo {
    /// CNPJ do estabelecimento, 14 dígitos sem máscara
    pub cnpj: String,
    /// E-mail cadastrado na Receita
    pub correio_eletronico: Option<String>,
    /// DDD do telefone 1
    pub ddd_1: Option<String>,
    /// DDD do telefone 2
    pub ddd_2: Option<String>,
    /// Capital social em reais, em texto com vírgula decimal (ex.: `5000,00`)
    pub empresa_capital_social: Option<String>,
    /// Razão social da empresa
    pub empresa_razao_social: Option<String>,
    /// Nome do logradouro
    pub logradouro: Option<String>,
    /// Nome do município em maiúsculas
    pub municipio_descricao: Option<String>,
    /// Nome fantasia do estabelecimento
    pub nome_fantasia: Option<String>,
    /// Número do endereço
    pub numero: Option<String>,
    /// Situação cadastral por extenso: `Nula`, `Ativa`, `Suspensa`, `Inapta` ou `Baixada`
    pub situacao_cadastral_descricao: Option<String>,
    /// Telefone 1, sem o DDD
    pub telefone_1: Option<String>,
    /// Telefone 2, sem o DDD
    pub telefone_2: Option<String>,
    /// Tipo do logradouro (ex.: RUA, AVENIDA)
    pub tipo_logradouro: Option<String>,
    /// Sigla da UF
    pub uf: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaDeEmpresas [#tipo-paginadeempresas]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDeEmpresas } from "termo_core/leads";

export interface PaginaDeEmpresas {
  /**
   * `true` quando `total` é o teto de 2.000.000 (a contagem passou do teto ou demorou mais de 6 segundos), e não a contagem exata
   */
  estimado: boolean;
  /**
   * Estabelecimentos da página, em ordem de CNPJ
   */
  itens: Array<CnpjResumo>;
  /**
   * Página devolvida, já ajustada ao intervalo válido
   */
  pagina: number;
  /**
   * Itens por página usados, já ajustados ao intervalo de 1 a 50
   */
  tamanho: number;
  /**
   * Quantidade de estabelecimentos que casam com o filtro, limitada a 2.000.000
   */
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PaginaDeEmpresas;

pub struct PaginaDeEmpresas {
    /// `true` quando `total` é o teto de 2.000.000 (a contagem passou do teto ou demorou mais de 6 segundos), e não a contagem exata
    pub estimado: bool,
    /// Estabelecimentos da página, em ordem de CNPJ
    pub itens: Vec<CnpjResumo>,
    /// Página devolvida, já ajustada ao intervalo válido
    pub pagina: i64,
    /// Itens por página usados, já ajustados ao intervalo de 1 a 50
    pub tamanho: i64,
    /// Quantidade de estabelecimentos que casam com o filtro, limitada a 2.000.000
    pub total: i64,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/leads/colaborador)

> 5 funções do TermoLeads para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /api/colaborador` | Lista os colaboradores com paginação |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /api/colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /api/colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /api/colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /api/colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/api/colaborador" credencial />

Lista os colaboradores com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena por nome. Quando quem chama é master do TermoAuth, antes de listar o TermoLeads busca no TermoAuth os colaboradores `@termotubos.com.br` que ainda não existem aqui e os cadastra com o perfil de acesso "Acesso inicial" (só leitura em todas as áreas). `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta os registros que casam com o filtro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDeColaboradores>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaDeColaboradores, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Número da página, a partir de 1 (padrão 1) · Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Aceito, mas ignorado: a página tem sempre 50 itens · Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Trecho do nome, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Trecho do setor, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Trecho do cargo, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "true só os ativos, false só os inativos · Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDeColaboradores>` · Rust: `Result<tipos::PaginaDeColaboradores, ErroAoChamarServico>` · veja [`PaginaDeColaboradores`](#tipo-paginadecolaboradores).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/api/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e e-mail, em ordem alfabética de nome. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDeColaboradoresAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaDeColaboradoresAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Trecho do nome ou do e-mail, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Número da página, a partir de 1 (padrão 1) · Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Itens por página (padrão 10) · Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDeColaboradoresAutoComplete>` · Rust: `Result<tipos::PaginaDeColaboradoresAutoComplete, ErroAoChamarServico>` · veja [`PaginaDeColaboradoresAutoComplete`](#tipo-paginadecolaboradoresautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/api/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. Todos os filtros são opcionais e se somam; sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Trecho do nome ou do e-mail, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Trecho do nome, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Trecho do e-mail, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Trecho do setor, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Trecho do cargo, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "true só os ativos, false só os inativos · Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Só os colaboradores deste perfil de acesso · Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/api/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve o colaborador com o e-mail e o `master` do acesso dele e o perfil de acesso. Colaborador excluído responde `404`. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização) e só o perfil de acesso é alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/api/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoLeads: `perfil_acesso_id` aponta para um perfil de `GET /api/perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/leads";

export interface Colaborador {
  /**
   * `false` quando o colaborador está inativo
   */
  ativo: boolean;
  /**
   * Data e hora da última alteração (ISO 8601, UTC)
   */
  atualizado_em: string;
  /**
   * Id do acesso (`auth`) do colaborador
   */
  auth_id: string;
  /**
   * Cargo do colaborador
   */
  cargo?: string | null;
  /**
   * Data e hora do cadastro (ISO 8601, UTC)
   */
  criado_em: string;
  /**
   * E-mail do acesso, sempre `@termotubos.com.br`
   */
  email: string;
  /**
   * Função do colaborador
   */
  funcao?: string | null;
  /**
   * Id do colaborador no TermoLeads
   */
  id: string;
  /**
   * `true` quando a pessoa é master do TermoAuth (tem tudo liberado e não aceita perfil de acesso)
   */
  master: boolean;
  /**
   * Nome do colaborador, vindo do TermoAuth
   */
  nome: string;
  /**
   * Nome do perfil de acesso da pessoa; `null` quando não tem perfil
   */
  perfil_acesso?: string | null;
  /**
   * Id do perfil de acesso da pessoa; `null` quando ainda não tem perfil (não enxerga nenhuma área)
   */
  perfil_acesso_id?: string | null;
  /**
   * Setor do colaborador
   */
  setor?: string | null;
  /**
   * Telefone do colaborador
   */
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Colaborador;

pub struct Colaborador {
    /// `false` quando o colaborador está inativo
    pub ativo: bool,
    /// Data e hora da última alteração (ISO 8601, UTC)
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    /// Id do acesso (`auth`) do colaborador
    pub auth_id: uuid::Uuid,
    /// Cargo do colaborador
    pub cargo: Option<String>,
    /// Data e hora do cadastro (ISO 8601, UTC)
    pub criado_em: chrono::DateTime<chrono::Utc>,
    /// E-mail do acesso, sempre `@termotubos.com.br`
    pub email: String,
    /// Função do colaborador
    pub funcao: Option<String>,
    /// Id do colaborador no TermoLeads
    pub id: uuid::Uuid,
    /// `true` quando a pessoa é master do TermoAuth (tem tudo liberado e não aceita perfil de acesso)
    pub master: bool,
    /// Nome do colaborador, vindo do TermoAuth
    pub nome: String,
    /// Nome do perfil de acesso da pessoa; `null` quando não tem perfil
    pub perfil_acesso: Option<String>,
    /// Id do perfil de acesso da pessoa; `null` quando ainda não tem perfil (não enxerga nenhuma área)
    pub perfil_acesso_id: Option<uuid::Uuid>,
    /// Setor do colaborador
    pub setor: Option<String>,
    /// Telefone do colaborador
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorAutoComplete [#tipo-colaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorAutoComplete } from "termo_core/leads";

export interface ColaboradorAutoComplete {
  /**
   * E-mail do colaborador
   */
  email: string;
  /**
   * Id do colaborador
   */
  id: string;
  /**
   * Nome do colaborador
   */
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ColaboradorAutoComplete;

pub struct ColaboradorAutoComplete {
    /// E-mail do colaborador
    pub email: String,
    /// Id do colaborador
    pub id: uuid::Uuid,
    /// Nome do colaborador
    pub nome: String,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/leads";

export interface ColaboradorVincularPerfilAcesso {
  /**
   * Id do perfil de acesso que a pessoa passa a usar; `null` tira o perfil
   */
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    /// Id do perfil de acesso que a pessoa passa a usar; `null` tira o perfil
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaDeColaboradores [#tipo-paginadecolaboradores]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDeColaboradores } from "termo_core/leads";

export interface PaginaDeColaboradores {
  /**
   * Colaboradores da página, em ordem alfabética de nome
   */
  itens: Array<Colaborador>;
  /**
   * Página devolvida, a partir de 1
   */
  pagina: number;
  /**
   * Itens por página (sempre 50)
   */
  tamanho: number;
  /**
   * Quantidade de colaboradores que casam com o filtro
   */
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PaginaDeColaboradores;

pub struct PaginaDeColaboradores {
    /// Colaboradores da página, em ordem alfabética de nome
    pub itens: Vec<Colaborador>,
    /// Página devolvida, a partir de 1
    pub pagina: i64,
    /// Itens por página (sempre 50)
    pub tamanho: i64,
    /// Quantidade de colaboradores que casam com o filtro
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaDeColaboradoresAutoComplete [#tipo-paginadecolaboradoresautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDeColaboradoresAutoComplete } from "termo_core/leads";

export interface PaginaDeColaboradoresAutoComplete {
  /**
   * Colaboradores da página, em ordem alfabética de nome
   */
  itens: Array<ColaboradorAutoComplete>;
  /**
   * Página devolvida, a partir de 1
   */
  pagina: number;
  /**
   * Itens por página usados
   */
  tamanho: number;
  /**
   * Quantidade de colaboradores que casam com a busca
   */
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PaginaDeColaboradoresAutoComplete;

pub struct PaginaDeColaboradoresAutoComplete {
    /// Colaboradores da página, em ordem alfabética de nome
    pub itens: Vec<ColaboradorAutoComplete>,
    /// Página devolvida, a partir de 1
    pub pagina: i64,
    /// Itens por página usados
    pub tamanho: i64,
    /// Quantidade de colaboradores que casam com a busca
    pub total: i64,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/leads/configuracao)

> 2 funções do TermoLeads para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /api/configuracao` | Mostra a situação do segredo do app |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /api/configuracao` | Grava ou apaga o segredo do app |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/api/configuracao" credencial />

Mostra a situação do segredo do app

Exige o usuário master (token do TermoAuth com `isMaster`). Devolve se o segredo do app `termo-leads` gerado no TermoAuth está cadastrado e o final mascarado dele, nunca o valor. O segredo fica cifrado no banco (AES-256-GCM, chave derivada da `GLOBAL_SECRET_CRIPTOGRAFIA` do servidor); sem essa variável, ou se ela mudou, o segredo aparece como não configurado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/api/configuracao" credencial />

Grava ou apaga o segredo do app

Exige o usuário master (token do TermoAuth com `isMaster`). `segredo_do_app_gerado_no_termo_auth` ausente não mexe, texto troca e `null` apaga. O valor é cifrado antes de ir para o banco e entregue na hora ao `termo_core`, que o usa para pedir o token de aplicativo ao TermoAuth: vale sem deploy. Responde 503 quando o servidor está sem a `GLOBAL_SECRET_CRIPTOGRAFIA`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/leads";

export interface Configuracao {
  /**
   * Data e hora da última alteração (ISO 8601, UTC)
   */
  atualizado_em: string;
  /**
   * E-mail de quem gravou por último; `null` antes da primeira gravação
   */
  atualizado_por?: string | null;
  /**
   * `false` quando o servidor está sem a `GLOBAL_SECRET_CRIPTOGRAFIA`: nada abre e nada pode ser gravado
   */
  criptografia_disponivel: boolean;
  /**
   * Situação do segredo do app `termo-leads` gerado no TermoAuth; o valor nunca é devolvido
   */
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Configuracao;

pub struct Configuracao {
    /// Data e hora da última alteração (ISO 8601, UTC)
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    /// E-mail de quem gravou por último; `null` antes da primeira gravação
    pub atualizado_por: Option<String>,
    /// `false` quando o servidor está sem a `GLOBAL_SECRET_CRIPTOGRAFIA`: nada abre e nada pode ser gravado
    pub criptografia_disponivel: bool,
    /// Situação do segredo do app `termo-leads` gerado no TermoAuth; o valor nunca é devolvido
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/leads";

export interface ConfiguracaoAtualizar {
  /**
   * Segredo do app gerado no TermoAuth: ausente não mexe, texto troca (até 2.000 caracteres, sem quebra de linha) e `null` apaga
   */
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    /// Segredo do app gerado no TermoAuth: ausente não mexe, texto troca (até 2.000 caracteres, sem quebra de linha) e `null` apaga
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/leads";

export interface ValorProtegido {
  /**
   * `true` quando há um valor gravado que abre com a `GLOBAL_SECRET_CRIPTOGRAFIA` atual
   */
  configurado: boolean;
  /**
   * Os 4 últimos caracteres do valor, mascarados (`••••abcd`); `null` quando não há valor
   */
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ValorProtegido;

pub struct ValorProtegido {
    /// `true` quando há um valor gravado que abre com a `GLOBAL_SECRET_CRIPTOGRAFIA` atual
    pub configurado: bool,
    /// Os 4 últimos caracteres do valor, mascarados (`••••abcd`); `null` quando não há valor
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Importar (/docs/servicos/leads/importar)

> 8 funções do TermoLeads para importar.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`cancelar_importar`](#cancelar_importar) | `POST /api/importar/cancelar` | Cancela a importação em andamento |
| [`iniciar_importar`](#iniciar_importar) | `POST /api/importar/iniciar` | Inicia a importação da base CNPJ da Receita Federal |
| [`relatorios_importar`](#relatorios_importar) | `GET /api/importar/relatorios` | Lista o histórico das importações |
| [`sincronizar_importar`](#sincronizar_importar) | `POST /api/importar/sincronizar` | Envia a base CNPJ local para sandbox ou production |
| [`sincronizar_cancelar_importar`](#sincronizar_cancelar_importar) | `POST /api/importar/sincronizar/cancelar` | Cancela a sincronização em andamento |
| [`sincronizar_pontos_importar`](#sincronizar_pontos_importar) | `GET /api/importar/sincronizar/pontos` | Lista os pontos de retomada salvos |
| [`sincronizar_status_importar`](#sincronizar_status_importar) | `GET /api/importar/sincronizar/status` | Mostra o progresso da sincronização |
| [`status_importar`](#status_importar) | `GET /api/importar/status` | Mostra o progresso da importação |

## `cancelar_importar` [#cancelar_importar]

<Rota metodo="POST" caminho="/api/importar/cancelar" credencial />

Cancela a importação em andamento

Exige o usuário master (token do TermoAuth com `isMaster`) e só roda no localhost (`APP_ENV=development`); em sandbox e production responde 403. Pede o cancelamento da importação em andamento; ela para no próximo ponto seguro e a base em uso não é alterada. Não tem corpo. Sem importação em andamento, ou com o cancelamento já pedido, não faz nada. Devolve o progresso atual, com `cancelando` em `true` quando o pedido foi aceito.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function cancelar_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ImportProgress>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { cancelar_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await cancelar_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn cancelar_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::ImportProgress, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::cancelar_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ImportProgress>` · Rust: `Result<tipos::ImportProgress, ErroAoChamarServico>` · veja [`ImportProgress`](#tipo-importprogress).

## `iniciar_importar` [#iniciar_importar]

<Rota metodo="POST" caminho="/api/importar/iniciar" credencial />

Inicia a importação da base CNPJ da Receita Federal

Exige o usuário master (token do TermoAuth com `isMaster`) e só roda no localhost (`APP_ENV=development`); em sandbox e production responde 403. Dispara em segundo plano a importação completa da base CNPJ: baixa o mês mais recente publicado pela Receita, monta a base nova e só no fim troca a base em uso, que continua respondendo durante todo o processo. Operação pesada, que leva horas. Não tem corpo. Se já houver uma importação em andamento, não começa outra e devolve o progresso dela. A resposta é o progresso no momento do pedido; o andamento se acompanha em `GET /api/importar/status`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function iniciar_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ImportProgress>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { iniciar_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await iniciar_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn iniciar_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::ImportProgress, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::iniciar_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ImportProgress>` · Rust: `Result<tipos::ImportProgress, ErroAoChamarServico>` · veja [`ImportProgress`](#tipo-importprogress).

## `relatorios_importar` [#relatorios_importar]

<Rota metodo="GET" caminho="/api/importar/relatorios" credencial />

Lista o histórico das importações

Exige o usuário master (token do TermoAuth com `isMaster`) e só roda no localhost (`APP_ENV=development`); em sandbox e production responde 403. Devolve as últimas 50 importações registradas, da mais recente para a mais antiga, sem paginação: mês importado, `status` (`executando`, `concluido`, `concluido_com_falhas`, `erro` ou `cancelado`), início e fim (data e hora em RFC 3339), arquivos processados, total de linhas e o erro, se houve. Se o banco falhar, devolve a lista vazia.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function relatorios_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ImportResumo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { relatorios_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await relatorios_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn relatorios_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<Vec<tipos::ImportResumo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::relatorios_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ImportResumo>>` · Rust: `Result<Vec<tipos::ImportResumo>, ErroAoChamarServico>`

## `sincronizar_importar` [#sincronizar_importar]

<Rota metodo="POST" caminho="/api/importar/sincronizar" credencial />

Envia a base CNPJ local para sandbox ou production

Exige o usuário master e só roda no localhost (`APP_ENV=development`). Lê a tabela `cnpj` local em lotes (padrão 1.000 linhas, `SINCRONIZAR_LOTE`) e manda cada um, um por vez, para `POST /api/micro_servico/cnpj/lote` do ambiente escolhido, com a chave `GLOBAL_SECRET_API_MICRO_SERVICE` do `.env` local. Falha de rede ou 5xx tenta de novo até 6 vezes. Com `retomarDe` (14 dígitos), continua depois daquele CNPJ. Cada lote confirmado grava o último CNPJ no banco local (`GET /api/importar/sincronizar/pontos`), que é apagado quando a sincronização termina com sucesso. Não começa durante uma importação; se já houver uma sincronização em andamento, devolve o progresso dela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function sincronizar_importar(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.SincronizarCnpjInput,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SincronizacaoProgress>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { sincronizar_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await sincronizar_importar(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn sincronizar_importar(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::SincronizarCnpjInput,
) -> Result<tipos::SincronizacaoProgress, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::sincronizar_importar(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.SincronizarCnpjInput", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SincronizarCnpjInput", typeDescriptionLink: "#tipo-sincronizarcnpjinput" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SincronizacaoProgress>` · Rust: `Result<tipos::SincronizacaoProgress, ErroAoChamarServico>` · veja [`SincronizacaoProgress`](#tipo-sincronizacaoprogress).

## `sincronizar_cancelar_importar` [#sincronizar_cancelar_importar]

<Rota metodo="POST" caminho="/api/importar/sincronizar/cancelar" credencial />

Cancela a sincronização em andamento

Exige o usuário master e só roda no localhost. Para depois do lote que está sendo enviado; `ultimoCnpj` fica como ponto de retomada. Não tem corpo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function sincronizar_cancelar_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SincronizacaoProgress>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { sincronizar_cancelar_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await sincronizar_cancelar_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn sincronizar_cancelar_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::SincronizacaoProgress, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::sincronizar_cancelar_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SincronizacaoProgress>` · Rust: `Result<tipos::SincronizacaoProgress, ErroAoChamarServico>` · veja [`SincronizacaoProgress`](#tipo-sincronizacaoprogress).

## `sincronizar_pontos_importar` [#sincronizar_pontos_importar]

<Rota metodo="GET" caminho="/api/importar/sincronizar/pontos" credencial />

Lista os pontos de retomada salvos

Exige o usuário master e só roda no localhost. Devolve, por ambiente, o último CNPJ confirmado pelo destino, gravado no banco local a cada lote. Sobrevive a um reinício do backend local; some quando a sincronização daquele ambiente termina com sucesso.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function sincronizar_pontos_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PontoSincronizacao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { sincronizar_pontos_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await sincronizar_pontos_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn sincronizar_pontos_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<Vec<tipos::PontoSincronizacao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::sincronizar_pontos_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PontoSincronizacao>>` · Rust: `Result<Vec<tipos::PontoSincronizacao>, ErroAoChamarServico>`

## `sincronizar_status_importar` [#sincronizar_status_importar]

<Rota metodo="GET" caminho="/api/importar/sincronizar/status" credencial />

Mostra o progresso da sincronização

Exige o usuário master e só roda no localhost. Devolve o destino, as linhas enviadas e gravadas, os lotes, o último CNPJ confirmado, o erro e as últimas 200 linhas do log.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function sincronizar_status_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SincronizacaoProgress>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { sincronizar_status_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await sincronizar_status_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn sincronizar_status_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::SincronizacaoProgress, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::sincronizar_status_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SincronizacaoProgress>` · Rust: `Result<tipos::SincronizacaoProgress, ErroAoChamarServico>` · veja [`SincronizacaoProgress`](#tipo-sincronizacaoprogress).

## `status_importar` [#status_importar]

<Rota metodo="GET" caminho="/api/importar/status" credencial />

Mostra o progresso da importação

Exige o usuário master (token do TermoAuth com `isMaster`) e só roda no localhost (`APP_ENV=development`); em sandbox e production responde 403. Devolve o progresso da importação da execução atual do servidor: `etapa` (vazia antes da primeira importação, depois `preparando`, `baixando`, `importando`, `montagem`, `indices` ou `concluido`), `running`, `finalizado`, `cancelando`, o mês importado em `mes` (`AAAA-MM`), o download dos arquivos, os arquivos processados com linhas lidas e descartadas, a montagem por faixas, as falhas, o erro final e as últimas 200 linhas do log. Sem importação desde que o servidor subiu, os campos vêm vazios ou zerados.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function status_importar(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ImportProgress>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { status_importar } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await status_importar(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn status_importar(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::ImportProgress, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::status_importar(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ImportProgress>` · Rust: `Result<tipos::ImportProgress, ErroAoChamarServico>` · veja [`ImportProgress`](#tipo-importprogress).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ArquivoStatus [#tipo-arquivostatus]

Estado de um arquivo individual no lote.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ArquivoStatus } from "termo_core/leads";

export interface ArquivoStatus {
  /**
   * Bytes baixados
   */
  bytes: number;
  /**
   * `pendente`, `baixando`, `concluido` ou `falha`
   */
  estado: string;
  /**
   * Nome do arquivo
   */
  nome: string;
  /**
   * Tamanho do arquivo em bytes, quando conhecido
   */
  total?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ArquivoStatus;

pub struct ArquivoStatus {
    /// Bytes baixados
    pub bytes: i64,
    /// `pendente`, `baixando`, `concluido` ou `falha`
    pub estado: String,
    /// Nome do arquivo
    pub nome: String,
    /// Tamanho do arquivo em bytes, quando conhecido
    pub total: Option<i64>,
}
```

</Tab>
</Tabs>

### DownloadProgress [#tipo-downloadprogress]

Progresso do download, serializado para o frontend dentro do progresso da
importação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DownloadProgress } from "termo_core/leads";

export interface DownloadProgress {
  /**
   * Situação do download de cada arquivo
   */
  arquivos: Array<ArquivoStatus>;
  /**
   * Quantidade de arquivos já baixados
   */
  arquivosConcluidos: number;
  /**
   * Total de bytes baixados
   */
  bytesBaixados: number;
  /**
   * Total de bytes a baixar, quando conhecido
   */
  bytesTotal?: number | null;
  /**
   * Mensagens dos arquivos cujo download falhou
   */
  falhas: Array<string>;
  /**
   * Quantidade de arquivos a baixar
   */
  totalArquivos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::DownloadProgress;

pub struct DownloadProgress {
    /// Situação do download de cada arquivo
    pub arquivos: Vec<ArquivoStatus>,
    /// Quantidade de arquivos já baixados
    #[serde(rename = "arquivosConcluidos")]
    pub arquivos_concluidos: i64,
    /// Total de bytes baixados
    #[serde(rename = "bytesBaixados")]
    pub bytes_baixados: i64,
    /// Total de bytes a baixar, quando conhecido
    #[serde(rename = "bytesTotal")]
    pub bytes_total: Option<i64>,
    /// Mensagens dos arquivos cujo download falhou
    pub falhas: Vec<String>,
    /// Quantidade de arquivos a baixar
    #[serde(rename = "totalArquivos")]
    pub total_arquivos: i64,
}
```

</Tab>
</Tabs>

### ImportArquivo [#tipo-importarquivo]

Estado de um arquivo individual no lote de importação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ImportArquivo } from "termo_core/leads";

export interface ImportArquivo {
  /**
   * Bytes já lidos
   */
  bytesLidos: number;
  /**
   * Tamanho do arquivo descompactado, em bytes
   */
  bytesTotal: number;
  /**
   * Registros malformados descartados
   */
  descartadas: number;
  /**
   * Erro do arquivo, quando falhou
   */
  erro?: string | null;
  /**
   * `pendente`, `importando`, `concluido` ou `falha`
   */
  estado: string;
  /**
   * Linhas lidas
   */
  linhas: number;
  /**
   * Nome do arquivo
   */
  nome: string;
  /**
   * Destino dos dados do arquivo
   */
  tabela: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ImportArquivo;

pub struct ImportArquivo {
    /// Bytes já lidos
    #[serde(rename = "bytesLidos")]
    pub bytes_lidos: i64,
    /// Tamanho do arquivo descompactado, em bytes
    #[serde(rename = "bytesTotal")]
    pub bytes_total: i64,
    /// Registros malformados descartados
    pub descartadas: i64,
    /// Erro do arquivo, quando falhou
    pub erro: Option<String>,
    /// `pendente`, `importando`, `concluido` ou `falha`
    pub estado: String,
    /// Linhas lidas
    pub linhas: i64,
    /// Nome do arquivo
    pub nome: String,
    /// Destino dos dados do arquivo
    pub tabela: String,
}
```

</Tab>
</Tabs>

### ImportProgress [#tipo-importprogress]

Estado global da importação, serializado para o frontend.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ImportProgress } from "termo_core/leads";

export interface ImportProgress {
  /**
   * Situação de cada arquivo processado
   */
  arquivos: Array<ImportArquivo>;
  /**
   * Quantidade de arquivos já processados
   */
  arquivosConcluidos: number;
  /**
   * `true` depois que o cancelamento foi pedido
   */
  cancelando: boolean;
  /**
   * Progresso do download dos arquivos da Receita
   */
  download: DownloadProgress;
  /**
   * Erro que interrompeu a importação, quando houve
   */
  erro?: string | null;
  /**
   * Etapa atual: vazia antes da primeira importação, depois `preparando`, `baixando`, `importando`, `montagem`, `indices` ou `concluido`
   */
  etapa: string;
  /**
   * Faixa em montagem
   */
  faixaAtual: number;
  /**
   * Quantidade de faixas da montagem da base
   */
  faixasTotal: number;
  /**
   * Mensagens dos arquivos que falharam
   */
  falhas: Array<string>;
  /**
   * `true` quando a última importação terminou, com sucesso, erro ou cancelamento
   */
  finalizado: boolean;
  /**
   * Total de registros malformados descartados
   */
  linhasDescartadasTotal: number;
  /**
   * Total de linhas lidas
   */
  linhasTotal: number;
  /**
   * Últimas 200 linhas do log da importação
   */
  log: Array<string>;
  /**
   * Mês da base importada, no formato AAAA-MM, conhecido depois do download
   */
  mes?: string | null;
  /**
   * Quantidade de estabelecimentos já montados
   */
  montagemFeitas: number;
  /**
   * Quantidade de estabelecimentos a montar
   */
  montagemTotal: number;
  /**
   * `true` enquanto a importação está em andamento
   */
  running: boolean;
  /**
   * Quantidade de arquivos a processar
   */
  totalArquivos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ImportProgress;

pub struct ImportProgress {
    /// Situação de cada arquivo processado
    pub arquivos: Vec<ImportArquivo>,
    /// Quantidade de arquivos já processados
    #[serde(rename = "arquivosConcluidos")]
    pub arquivos_concluidos: i64,
    /// `true` depois que o cancelamento foi pedido
    pub cancelando: bool,
    /// Progresso do download dos arquivos da Receita
    pub download: DownloadProgress,
    /// Erro que interrompeu a importação, quando houve
    pub erro: Option<String>,
    /// Etapa atual: vazia antes da primeira importação, depois `preparando`, `baixando`, `importando`, `montagem`, `indices` ou `concluido`
    pub etapa: String,
    /// Faixa em montagem
    #[serde(rename = "faixaAtual")]
    pub faixa_atual: i64,
    /// Quantidade de faixas da montagem da base
    #[serde(rename = "faixasTotal")]
    pub faixas_total: i64,
    /// Mensagens dos arquivos que falharam
    pub falhas: Vec<String>,
    /// `true` quando a última importação terminou, com sucesso, erro ou cancelamento
    pub finalizado: bool,
    /// Total de registros malformados descartados
    #[serde(rename = "linhasDescartadasTotal")]
    pub linhas_descartadas_total: i64,
    /// Total de linhas lidas
    #[serde(rename = "linhasTotal")]
    pub linhas_total: i64,
    /// Últimas 200 linhas do log da importação
    pub log: Vec<String>,
    /// Mês da base importada, no formato AAAA-MM, conhecido depois do download
    pub mes: Option<String>,
    /// Quantidade de estabelecimentos já montados
    #[serde(rename = "montagemFeitas")]
    pub montagem_feitas: i64,
    /// Quantidade de estabelecimentos a montar
    #[serde(rename = "montagemTotal")]
    pub montagem_total: i64,
    /// `true` enquanto a importação está em andamento
    pub running: bool,
    /// Quantidade de arquivos a processar
    #[serde(rename = "totalArquivos")]
    pub total_arquivos: i64,
}
```

</Tab>
</Tabs>

### ImportResumo [#tipo-importresumo]

Resumo de uma execução de importação para o relatório no frontend.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ImportResumo } from "termo_core/leads";

export interface ImportResumo {
  /**
   * Quantidade de arquivos processados sem falha
   */
  arquivosOk: number;
  /**
   * Erro da execução, quando houve
   */
  erro?: string | null;
  /**
   * Fim da execução, data e hora em RFC 3339; nulo enquanto executa
   */
  finalizadoEm?: string | null;
  /**
   * Id da execução (UUID)
   */
  id: string;
  /**
   * Início da execução, data e hora em RFC 3339
   */
  iniciadoEm?: string | null;
  /**
   * Total de linhas lidas
   */
  linhasTotal: number;
  /**
   * Mês da base importada, no formato AAAA-MM
   */
  mes?: string | null;
  /**
   * `executando`, `concluido`, `concluido_com_falhas`, `erro` ou `cancelado`
   */
  status: string;
  /**
   * Quantidade de arquivos da importação
   */
  totalArquivos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::ImportResumo;

pub struct ImportResumo {
    /// Quantidade de arquivos processados sem falha
    #[serde(rename = "arquivosOk")]
    pub arquivos_ok: i32,
    /// Erro da execução, quando houve
    pub erro: Option<String>,
    /// Fim da execução, data e hora em RFC 3339; nulo enquanto executa
    #[serde(rename = "finalizadoEm")]
    pub finalizado_em: Option<String>,
    /// Id da execução (UUID)
    pub id: String,
    /// Início da execução, data e hora em RFC 3339
    #[serde(rename = "iniciadoEm")]
    pub iniciado_em: Option<String>,
    /// Total de linhas lidas
    #[serde(rename = "linhasTotal")]
    pub linhas_total: i64,
    /// Mês da base importada, no formato AAAA-MM
    pub mes: Option<String>,
    /// `executando`, `concluido`, `concluido_com_falhas`, `erro` ou `cancelado`
    pub status: String,
    /// Quantidade de arquivos da importação
    #[serde(rename = "totalArquivos")]
    pub total_arquivos: i32,
}
```

</Tab>
</Tabs>

### PontoSincronizacao [#tipo-pontosincronizacao]

Ponto de retomada salvo de um ambiente.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PontoSincronizacao } from "termo_core/leads";

export interface PontoSincronizacao {
  /**
   * Destino: `sandbox` ou `production`
   */
  ambiente: string;
  /**
   * Quando o ponto foi gravado, data e hora em RFC 3339
   */
  atualizadoEm: string;
  /**
   * Último CNPJ confirmado pelo destino, salvo no banco local
   */
  ultimoCnpj: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PontoSincronizacao;

pub struct PontoSincronizacao {
    /// Destino: `sandbox` ou `production`
    pub ambiente: String,
    /// Quando o ponto foi gravado, data e hora em RFC 3339
    #[serde(rename = "atualizadoEm")]
    pub atualizado_em: String,
    /// Último CNPJ confirmado pelo destino, salvo no banco local
    #[serde(rename = "ultimoCnpj")]
    pub ultimo_cnpj: String,
}
```

</Tab>
</Tabs>

### SincronizacaoProgress [#tipo-sincronizacaoprogress]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SincronizacaoProgress } from "termo_core/leads";

export interface SincronizacaoProgress {
  /**
   * Destino: `sandbox` ou `production`
   */
  ambiente: string;
  /**
   * `true` depois que o cancelamento foi pedido
   */
  cancelando: boolean;
  /**
   * URL base do backend de destino
   */
  destino: string;
  /**
   * Linhas enviadas e confirmadas pelo destino nesta execução
   */
  enviados: number;
  /**
   * Erro que interrompeu a sincronização, quando houve
   */
  erro?: string | null;
  /**
   * `true` quando a última sincronização terminou, com sucesso, erro ou cancelamento
   */
  finalizado: boolean;
  /**
   * Linhas que o destino inseriu ou alterou
   */
  gravados: number;
  /**
   * Linhas da tabela local até o CNPJ de retomada, enviadas numa execução anterior; zero quando começa do início
   */
  jaSincronizados: number;
  /**
   * Últimas 200 linhas do log da sincronização
   */
  log: Array<string>;
  /**
   * Lotes enviados
   */
  lotes: number;
  /**
   * `true` enquanto a sincronização está em andamento
   */
  running: boolean;
  /**
   * Total aproximado de linhas da tabela `cnpj` local
   */
  totalEstimado: number;
  /**
   * Último CNPJ confirmado pelo destino, ponto de retomada
   */
  ultimoCnpj?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::SincronizacaoProgress;

pub struct SincronizacaoProgress {
    /// Destino: `sandbox` ou `production`
    pub ambiente: String,
    /// `true` depois que o cancelamento foi pedido
    pub cancelando: bool,
    /// URL base do backend de destino
    pub destino: String,
    /// Linhas enviadas e confirmadas pelo destino nesta execução
    pub enviados: i64,
    /// Erro que interrompeu a sincronização, quando houve
    pub erro: Option<String>,
    /// `true` quando a última sincronização terminou, com sucesso, erro ou cancelamento
    pub finalizado: bool,
    /// Linhas que o destino inseriu ou alterou
    pub gravados: i64,
    /// Linhas da tabela local até o CNPJ de retomada, enviadas numa execução anterior; zero quando começa do início
    #[serde(rename = "jaSincronizados")]
    pub ja_sincronizados: i64,
    /// Últimas 200 linhas do log da sincronização
    pub log: Vec<String>,
    /// Lotes enviados
    pub lotes: i64,
    /// `true` enquanto a sincronização está em andamento
    pub running: bool,
    /// Total aproximado de linhas da tabela `cnpj` local
    #[serde(rename = "totalEstimado")]
    pub total_estimado: i64,
    /// Último CNPJ confirmado pelo destino, ponto de retomada
    #[serde(rename = "ultimoCnpj")]
    pub ultimo_cnpj: Option<String>,
}
```

</Tab>
</Tabs>

### SincronizarCnpjInput [#tipo-sincronizarcnpjinput]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SincronizarCnpjInput } from "termo_core/leads";

export interface SincronizarCnpjInput {
  /**
   * Destino da sincronização: `sandbox` ou `production`
   */
  ambiente: string;
  /**
   * Continua depois deste CNPJ (retomada de uma sincronização interrompida); vazio começa do início
   */
  retomarDe?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::SincronizarCnpjInput;

pub struct SincronizarCnpjInput {
    /// Destino da sincronização: `sandbox` ou `production`
    pub ambiente: String,
    /// Continua depois deste CNPJ (retomada de uma sincronização interrompida); vazio começa do início
    #[serde(rename = "retomarDe")]
    pub retomar_de: Option<String>,
}
```

</Tab>
</Tabs>


# TermoLeads (/docs/servicos/leads)

> Consulta da base CNPJ da Receita Federal. GET /api/cnpj/{cnpj} é pública; a listagem de empresas, os colaboradores e os perfis de acesso exigem o token do usuário logado no TermoAuth e a permissão da…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Consulta da base CNPJ da Receita Federal. `GET /api/cnpj/{cnpj}` é pública; a listagem de empresas, os colaboradores e os perfis de acesso exigem o token do usuário logado no TermoAuth e a permissão da área no perfil de acesso dele; a importação da base (download e carga do mês mais recente publicado pela Receita) é só do usuário master.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::leads` (feature `leads`) |
| Importação TypeScript | `termo_core/leads` ou `import { leads } from "termo_core"` |
| Funções | 29 |
| Entidades | 9 |
| Versão do contrato | `0.5.17` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51031` |
| `SANDBOX` | `https://sandbox-api-leads.termotubos.com.br` |
| `PRODUCTION` | `https://api-leads.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="CNPJ" href="/docs/servicos/leads/cnpj" description="2 funções" />
  <Card title="Importar" href="/docs/servicos/leads/importar" description="8 funções" />
  <Card title="Micro serviço" href="/docs/servicos/leads/micro_servico" description="1 função" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/leads/auth" description="1 função" />
  <Card title="Colaborador" href="/docs/servicos/leads/colaborador" description="5 funções" />
  <Card title="Configuração" href="/docs/servicos/leads/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/leads/perfil_acesso" description="7 funções" />
  <Card title="Saúde" href="/docs/servicos/leads/saude" description="1 função" />
  <Card title="Teste" href="/docs/servicos/leads/test" description="2 funções" />
</Cards>


# Micro serviço (/docs/servicos/leads/micro_servico)

> 1 função do TermoLeads para micro serviço.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`cnpj_salvar_lote`](#cnpj_salvar_lote) | `POST /api/micro_servico/cnpj/lote` | Recebe um lote da base CNPJ montada no localhost |

## `cnpj_salvar_lote` [#cnpj_salvar_lote]

<Rota metodo="POST" caminho="/api/micro_servico/cnpj/lote" />

Recebe um lote da base CNPJ montada no localhost

Sem JWT: exige o header `x-secret-api-micro-service` igual a `GLOBAL_SECRET_API_MICRO_SERVICE` do servidor (sem a variável, a rota fica fechada). Usada pela sincronização do localhost, que monta a base da Receita e manda as linhas prontas em lotes. Faz upsert por `cnpj`: insere o CNPJ novo e atualiza o que já existe, regravando só as linhas que mudaram. No máximo 5.000 registros por lote.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function cnpj_salvar_lote(
  corpo_da_requisicao: tipos.SalvarLoteCnpjInput,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SalvarLoteCnpjOutput>
```

```ts title="Exemplo"
import { cnpj_salvar_lote } from "termo_core/leads";

const resposta = await cnpj_salvar_lote(corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn cnpj_salvar_lote(
    corpo_da_requisicao: &tipos::SalvarLoteCnpjInput,
) -> Result<tipos::SalvarLoteCnpjOutput, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::leads::cnpj_salvar_lote(&corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "corpo_da_requisicao": { type: "tipos.SalvarLoteCnpjInput", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SalvarLoteCnpjInput", typeDescriptionLink: "#tipo-salvarlotecnpjinput" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SalvarLoteCnpjOutput>` · Rust: `Result<tipos::SalvarLoteCnpjOutput, ErroAoChamarServico>` · veja [`SalvarLoteCnpjOutput`](#tipo-salvarlotecnpjoutput).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Cnpj [#tipo-cnpj]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cnpj } from "termo_core/leads";

export interface Cnpj {
  /**
   * Bairro
   */
  bairro?: string | null;
  /**
   * CEP, 8 dígitos sem máscara
   */
  cep?: string | null;
  /**
   * Código do CNAE fiscal principal, 7 dígitos
   */
  cnae_fiscal_principal?: string | null;
  /**
   * Descrição do CNAE fiscal principal
   */
  cnae_fiscal_principal_descricao?: string | null;
  /**
   * Códigos dos CNAEs secundários separados por vírgula, como a Receita publica
   */
  cnae_fiscal_secundaria?: string | null;
  /**
   * CNPJ do estabelecimento, 14 dígitos sem máscara
   */
  cnpj: string;
  /**
   * Oito primeiros dígitos do CNPJ, que identificam a empresa
   */
  cnpj_basico: string;
  /**
   * Dois dígitos verificadores do CNPJ
   */
  cnpj_dv?: string | null;
  /**
   * Quatro dígitos da ordem do estabelecimento (0001 é a matriz na maioria dos casos)
   */
  cnpj_ordem?: string | null;
  /**
   * Complemento do endereço
   */
  complemento?: string | null;
  /**
   * E-mail cadastrado na Receita
   */
  correio_eletronico?: string | null;
  /**
   * Data de início da atividade, no formato AAAAMMDD
   */
  data_inicio_atividade?: string | null;
  /**
   * Data da situação cadastral, no formato AAAAMMDD
   */
  data_situacao_cadastral?: string | null;
  /**
   * Data da situação especial, no formato AAAAMMDD
   */
  data_situacao_especial?: string | null;
  /**
   * DDD do telefone 1
   */
  ddd_1?: string | null;
  /**
   * DDD do telefone 2
   */
  ddd_2?: string | null;
  /**
   * DDD do fax
   */
  ddd_fax?: string | null;
  /**
   * Capital social em reais, em texto com vírgula decimal (ex.: `5000,00`)
   */
  empresa_capital_social?: string | null;
  /**
   * Ente federativo responsável, preenchido só para natureza jurídica de órgão público
   */
  empresa_ente_federativo_responsavel?: string | null;
  /**
   * Código da natureza jurídica
   */
  empresa_natureza_juridica?: string | null;
  /**
   * Natureza jurídica por extenso
   */
  empresa_natureza_juridica_descricao?: string | null;
  /**
   * Código do porte: 00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais
   */
  empresa_porte_empresa?: string | null;
  /**
   * Porte por extenso: `Não informado`, `Microempresa`, `Empresa de Pequeno Porte` ou `Demais`
   */
  empresa_porte_empresa_descricao?: string | null;
  /**
   * Código da qualificação do responsável pela empresa
   */
  empresa_qualificacao_responsavel?: string | null;
  /**
   * Qualificação do responsável por extenso
   */
  empresa_qualificacao_responsavel_descricao?: string | null;
  /**
   * Razão social da empresa
   */
  empresa_razao_social?: string | null;
  /**
   * Fax, sem o DDD
   */
  fax?: string | null;
  /**
   * Código da Receita: 1 matriz, 2 filial
   */
  identificador_matriz_filial?: string | null;
  /**
   * `Matriz` ou `Filial`
   */
  identificador_matriz_filial_descricao?: string | null;
  /**
   * Nome do logradouro
   */
  logradouro?: string | null;
  /**
   * Código do motivo da situação cadastral
   */
  motivo_situacao_cadastral?: string | null;
  /**
   * Motivo da situação cadastral por extenso
   */
  motivo_situacao_cadastral_descricao?: string | null;
  /**
   * Código do município na tabela da Receita
   */
  municipio?: string | null;
  /**
   * Nome do município em maiúsculas
   */
  municipio_descricao?: string | null;
  /**
   * Cidade no exterior, quando o estabelecimento fica fora do Brasil
   */
  nome_cidade_exterior?: string | null;
  /**
   * Nome fantasia do estabelecimento
   */
  nome_fantasia?: string | null;
  /**
   * Número do endereço
   */
  numero?: string | null;
  /**
   * Código do país, quando o estabelecimento fica no exterior
   */
  pais?: string | null;
  /**
   * Nome do país
   */
  pais_descricao?: string | null;
  /**
   * Data da exclusão do MEI, no formato AAAAMMDD
   */
  simples_data_exclusao_mei?: string | null;
  /**
   * Data da exclusão do Simples Nacional, no formato AAAAMMDD
   */
  simples_data_exclusao_simples?: string | null;
  /**
   * Data da opção pelo MEI, no formato AAAAMMDD
   */
  simples_data_opcao_mei?: string | null;
  /**
   * Data da opção pelo Simples Nacional, no formato AAAAMMDD
   */
  simples_data_opcao_simples?: string | null;
  /**
   * Opção pelo MEI: `S` ou `N`
   */
  simples_opcao_pelo_mei?: string | null;
  /**
   * Opção pelo MEI por extenso: `Sim` ou `Não`
   */
  simples_opcao_pelo_mei_descricao?: string | null;
  /**
   * Opção pelo Simples Nacional: `S` ou `N`
   */
  simples_opcao_pelo_simples?: string | null;
  /**
   * Opção pelo Simples Nacional por extenso: `Sim` ou `Não`
   */
  simples_opcao_pelo_simples_descricao?: string | null;
  /**
   * Código da situação cadastral: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada
   */
  situacao_cadastral?: string | null;
  /**
   * Situação cadastral por extenso: `Nula`, `Ativa`, `Suspensa`, `Inapta` ou `Baixada`
   */
  situacao_cadastral_descricao?: string | null;
  /**
   * Situação especial do estabelecimento, quando houver
   */
  situacao_especial?: string | null;
  /**
   * Quadro societário em ordem alfabética do nome; cada sócio é um objeto com textos nas chaves `cnpj_basico`, `identificador_socio` (1 pessoa jurídica, 2 pessoa física, 3 estrangeiro), `identificador_socio_descricao`, `nome_socio_razao_social`, `cnpj_cpf_socio` (CPF parcialmente mascarado pela Receita), `qualificacao_socio`, `qualificacao_socio_descricao`, `data_entrada_sociedade` (AAAAMMDD), `pais`, `pais_descricao`, `representante_legal`, `nome_representante`, `qualificacao_representante`, `qualificacao_representante_descricao` e `faixa_etaria`. Lista vazia quando não há sócios
   */
  socios: Array<Record<string, unknown>>;
  /**
   * Telefone 1, sem o DDD
   */
  telefone_1?: string | null;
  /**
   * Telefone 2, sem o DDD
   */
  telefone_2?: string | null;
  /**
   * `true` quando os dados da empresa (razão social, natureza, porte, capital) foram encontrados na base
   */
  tem_empresa: boolean;
  /**
   * `true` quando a empresa tem registro do Simples Nacional ou do MEI na base
   */
  tem_simples: boolean;
  /**
   * Tipo do logradouro (ex.: RUA, AVENIDA)
   */
  tipo_logradouro?: string | null;
  /**
   * Sigla da UF
   */
  uf?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Cnpj;

pub struct Cnpj {
    /// Bairro
    pub bairro: Option<String>,
    /// CEP, 8 dígitos sem máscara
    pub cep: Option<String>,
    /// Código do CNAE fiscal principal, 7 dígitos
    pub cnae_fiscal_principal: Option<String>,
    /// Descrição do CNAE fiscal principal
    pub cnae_fiscal_principal_descricao: Option<String>,
    /// Códigos dos CNAEs secundários separados por vírgula, como a Receita publica
    pub cnae_fiscal_secundaria: Option<String>,
    /// CNPJ do estabelecimento, 14 dígitos sem máscara
    pub cnpj: String,
    /// Oito primeiros dígitos do CNPJ, que identificam a empresa
    pub cnpj_basico: String,
    /// Dois dígitos verificadores do CNPJ
    pub cnpj_dv: Option<String>,
    /// Quatro dígitos da ordem do estabelecimento (0001 é a matriz na maioria dos casos)
    pub cnpj_ordem: Option<String>,
    /// Complemento do endereço
    pub complemento: Option<String>,
    /// E-mail cadastrado na Receita
    pub correio_eletronico: Option<String>,
    /// Data de início da atividade, no formato AAAAMMDD
    pub data_inicio_atividade: Option<String>,
    /// Data da situação cadastral, no formato AAAAMMDD
    pub data_situacao_cadastral: Option<String>,
    /// Data da situação especial, no formato AAAAMMDD
    pub data_situacao_especial: Option<String>,
    /// DDD do telefone 1
    pub ddd_1: Option<String>,
    /// DDD do telefone 2
    pub ddd_2: Option<String>,
    /// DDD do fax
    pub ddd_fax: Option<String>,
    /// Capital social em reais, em texto com vírgula decimal (ex.: `5000,00`)
    pub empresa_capital_social: Option<String>,
    /// Ente federativo responsável, preenchido só para natureza jurídica de órgão público
    pub empresa_ente_federativo_responsavel: Option<String>,
    /// Código da natureza jurídica
    pub empresa_natureza_juridica: Option<String>,
    /// Natureza jurídica por extenso
    pub empresa_natureza_juridica_descricao: Option<String>,
    /// Código do porte: 00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais
    pub empresa_porte_empresa: Option<String>,
    /// Porte por extenso: `Não informado`, `Microempresa`, `Empresa de Pequeno Porte` ou `Demais`
    pub empresa_porte_empresa_descricao: Option<String>,
    /// Código da qualificação do responsável pela empresa
    pub empresa_qualificacao_responsavel: Option<String>,
    /// Qualificação do responsável por extenso
    pub empresa_qualificacao_responsavel_descricao: Option<String>,
    /// Razão social da empresa
    pub empresa_razao_social: Option<String>,
    /// Fax, sem o DDD
    pub fax: Option<String>,
    /// Código da Receita: 1 matriz, 2 filial
    pub identificador_matriz_filial: Option<String>,
    /// `Matriz` ou `Filial`
    pub identificador_matriz_filial_descricao: Option<String>,
    /// Nome do logradouro
    pub logradouro: Option<String>,
    /// Código do motivo da situação cadastral
    pub motivo_situacao_cadastral: Option<String>,
    /// Motivo da situação cadastral por extenso
    pub motivo_situacao_cadastral_descricao: Option<String>,
    /// Código do município na tabela da Receita
    pub municipio: Option<String>,
    /// Nome do município em maiúsculas
    pub municipio_descricao: Option<String>,
    /// Cidade no exterior, quando o estabelecimento fica fora do Brasil
    pub nome_cidade_exterior: Option<String>,
    /// Nome fantasia do estabelecimento
    pub nome_fantasia: Option<String>,
    /// Número do endereço
    pub numero: Option<String>,
    /// Código do país, quando o estabelecimento fica no exterior
    pub pais: Option<String>,
    /// Nome do país
    pub pais_descricao: Option<String>,
    /// Data da exclusão do MEI, no formato AAAAMMDD
    pub simples_data_exclusao_mei: Option<String>,
    /// Data da exclusão do Simples Nacional, no formato AAAAMMDD
    pub simples_data_exclusao_simples: Option<String>,
    /// Data da opção pelo MEI, no formato AAAAMMDD
    pub simples_data_opcao_mei: Option<String>,
    /// Data da opção pelo Simples Nacional, no formato AAAAMMDD
    pub simples_data_opcao_simples: Option<String>,
    /// Opção pelo MEI: `S` ou `N`
    pub simples_opcao_pelo_mei: Option<String>,
    /// Opção pelo MEI por extenso: `Sim` ou `Não`
    pub simples_opcao_pelo_mei_descricao: Option<String>,
    /// Opção pelo Simples Nacional: `S` ou `N`
    pub simples_opcao_pelo_simples: Option<String>,
    /// Opção pelo Simples Nacional por extenso: `Sim` ou `Não`
    pub simples_opcao_pelo_simples_descricao: Option<String>,
    /// Código da situação cadastral: 01 nula, 02 ativa, 03 suspensa, 04 inapta, 08 baixada
    pub situacao_cadastral: Option<String>,
    /// Situação cadastral por extenso: `Nula`, `Ativa`, `Suspensa`, `Inapta` ou `Baixada`
    pub situacao_cadastral_descricao: Option<String>,
    /// Situação especial do estabelecimento, quando houver
    pub situacao_especial: Option<String>,
    /// Quadro societário em ordem alfabética do nome; cada sócio é um objeto com textos nas chaves `cnpj_basico`, `identificador_socio` (1 pessoa jurídica, 2 pessoa física, 3 estrangeiro), `identificador_socio_descricao`, `nome_socio_razao_social`, `cnpj_cpf_socio` (CPF parcialmente mascarado pela Receita), `qualificacao_socio`, `qualificacao_socio_descricao`, `data_entrada_sociedade` (AAAAMMDD), `pais`, `pais_descricao`, `representante_legal`, `nome_representante`, `qualificacao_representante`, `qualificacao_representante_descricao` e `faixa_etaria`. Lista vazia quando não há sócios
    pub socios: Vec<serde_json::Map<String, serde_json::Value>>,
    /// Telefone 1, sem o DDD
    pub telefone_1: Option<String>,
    /// Telefone 2, sem o DDD
    pub telefone_2: Option<String>,
    /// `true` quando os dados da empresa (razão social, natureza, porte, capital) foram encontrados na base
    pub tem_empresa: bool,
    /// `true` quando a empresa tem registro do Simples Nacional ou do MEI na base
    pub tem_simples: bool,
    /// Tipo do logradouro (ex.: RUA, AVENIDA)
    pub tipo_logradouro: Option<String>,
    /// Sigla da UF
    pub uf: Option<String>,
}
```

</Tab>
</Tabs>

### SalvarLoteCnpjInput [#tipo-salvarlotecnpjinput]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SalvarLoteCnpjInput } from "termo_core/leads";

export interface SalvarLoteCnpjInput {
  /**
   * Linhas completas da tabela `cnpj` (os mesmos campos de `Cnpj`), no máximo 5.000 por lote
   */
  registros: Array<Record<string, unknown>>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::SalvarLoteCnpjInput;

pub struct SalvarLoteCnpjInput {
    /// Linhas completas da tabela `cnpj` (os mesmos campos de `Cnpj`), no máximo 5.000 por lote
    pub registros: Vec<serde_json::Map<String, serde_json::Value>>,
}
```

</Tab>
</Tabs>

### SalvarLoteCnpjOutput [#tipo-salvarlotecnpjoutput]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SalvarLoteCnpjOutput } from "termo_core/leads";

export interface SalvarLoteCnpjOutput {
  /**
   * Quantidade de registros inseridos ou alterados (os iguais ao que já estava no banco não contam)
   */
  gravados: number;
  /**
   * Quantidade de registros recebidos no lote
   */
  recebidos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::SalvarLoteCnpjOutput;

pub struct SalvarLoteCnpjOutput {
    /// Quantidade de registros inseridos ou alterados (os iguais ao que já estava no banco não contam)
    pub gravados: i64,
    /// Quantidade de registros recebidos no lote
    pub recebidos: i64,
}
```

</Tab>
</Tabs>


# Perfil acesso (/docs/servicos/leads/perfil_acesso)

> 7 funções do TermoLeads para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /api/perfil_acesso` | Lista os perfis de acesso com paginação |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /api/perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /api/perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /api/perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /api/perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /api/perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /api/perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/api/perfil_acesso" credencial />

Lista os perfis de acesso com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDePerfisDeAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaDePerfisDeAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Número da página, a partir de 1 (padrão 1) · Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Aceito, mas ignorado: a página tem sempre 50 itens · Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDePerfisDeAcesso>` · Rust: `Result<tipos::PaginaDePerfisDeAcesso, ErroAoChamarServico>` · veja [`PaginaDePerfisDeAcesso`](#tipo-paginadeperfisdeacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/api/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoLeads dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /api/colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`empresas`, `colaboradores`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/api/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDePerfisDeAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaDePerfisDeAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Trecho do nome, sem diferenciar maiúsculas · Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Número da página, a partir de 1 (padrão 1) · Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Itens por página (padrão 10) · Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDePerfisDeAcessoAutoComplete>` · Rust: `Result<tipos::PaginaDePerfisDeAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaDePerfisDeAcessoAutoComplete`](#tipo-paginadeperfisdeacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/api/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::leads::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Trecho do nome, sem diferenciar maiúsculas · Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/api/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/api/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::leads::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/api/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/leads";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::leads::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/leads";

export interface Acoes {
  /**
   * Libera o cadastro na área
   */
  criar?: boolean;
  /**
   * Libera a exclusão na área
   */
  deletar?: boolean;
  /**
   * Libera a alteração na área
   */
  editar?: boolean;
  /**
   * Libera a leitura da área (qualquer outra ação liberada já libera a leitura)
   */
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Acoes;

pub struct Acoes {
    /// Libera o cadastro na área
    pub criar: Option<bool>,
    /// Libera a exclusão na área
    pub deletar: Option<bool>,
    /// Libera a alteração na área
    pub editar: Option<bool>,
    /// Libera a leitura da área (qualquer outra ação liberada já libera a leitura)
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaDePerfisDeAcesso [#tipo-paginadeperfisdeacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDePerfisDeAcesso } from "termo_core/leads";

export interface PaginaDePerfisDeAcesso {
  /**
   * Perfis da página, em ordem alfabética de nome
   */
  itens: Array<PerfilAcesso>;
  /**
   * Página devolvida, a partir de 1
   */
  pagina: number;
  /**
   * Itens por página (sempre 50)
   */
  tamanho: number;
  /**
   * Quantidade de perfis não excluídos
   */
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PaginaDePerfisDeAcesso;

pub struct PaginaDePerfisDeAcesso {
    /// Perfis da página, em ordem alfabética de nome
    pub itens: Vec<PerfilAcesso>,
    /// Página devolvida, a partir de 1
    pub pagina: i64,
    /// Itens por página (sempre 50)
    pub tamanho: i64,
    /// Quantidade de perfis não excluídos
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaDePerfisDeAcessoAutoComplete [#tipo-paginadeperfisdeacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDePerfisDeAcessoAutoComplete } from "termo_core/leads";

export interface PaginaDePerfisDeAcessoAutoComplete {
  /**
   * Perfis da página, em ordem alfabética de nome
   */
  itens: Array<PerfilAcessoAutoComplete>;
  /**
   * Página devolvida, a partir de 1
   */
  pagina: number;
  /**
   * Itens por página usados
   */
  tamanho: number;
  /**
   * Quantidade de perfis que casam com a busca
   */
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PaginaDePerfisDeAcessoAutoComplete;

pub struct PaginaDePerfisDeAcessoAutoComplete {
    /// Perfis da página, em ordem alfabética de nome
    pub itens: Vec<PerfilAcessoAutoComplete>,
    /// Página devolvida, a partir de 1
    pub pagina: i64,
    /// Itens por página usados
    pub tamanho: i64,
    /// Quantidade de perfis que casam com a busca
    pub total: i64,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/leads";

export interface PerfilAcesso {
  /**
   * Data e hora da última alteração (ISO 8601, UTC)
   */
  atualizado_em: string;
  /**
   * Quantidade de colaboradores que usam o perfil
   */
  colaboradores: number;
  /**
   * Data e hora do cadastro (ISO 8601, UTC)
   */
  criado_em: string;
  /**
   * Descrição do perfil
   */
  descricao?: string | null;
  /**
   * Id do perfil de acesso
   */
  id: string;
  /**
   * Nome do perfil, único sem diferenciar maiúsculas
   */
  nome: string;
  /**
   * Ações liberadas em cada área do TermoLeads
   */
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PerfilAcesso;

pub struct PerfilAcesso {
    /// Data e hora da última alteração (ISO 8601, UTC)
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    /// Quantidade de colaboradores que usam o perfil
    pub colaboradores: i64,
    /// Data e hora do cadastro (ISO 8601, UTC)
    pub criado_em: chrono::DateTime<chrono::Utc>,
    /// Descrição do perfil
    pub descricao: Option<String>,
    /// Id do perfil de acesso
    pub id: uuid::Uuid,
    /// Nome do perfil, único sem diferenciar maiúsculas
    pub nome: String,
    /// Ações liberadas em cada área do TermoLeads
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/leads";

export interface PerfilAcessoAtualizar {
  /**
   * Nova descrição; vazia apaga o valor
   */
  descricao?: string | null;
  /**
   * Novo nome do perfil, até 80 caracteres
   */
  nome?: string | null;
  /**
   * Novo conjunto de permissões; substitui o anterior inteiro
   */
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    /// Nova descrição; vazia apaga o valor
    pub descricao: Option<String>,
    /// Novo nome do perfil, até 80 caracteres
    pub nome: Option<String>,
    /// Novo conjunto de permissões; substitui o anterior inteiro
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoAutoComplete [#tipo-perfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAutoComplete } from "termo_core/leads";

export interface PerfilAcessoAutoComplete {
  /**
   * Id do perfil de acesso
   */
  id: string;
  /**
   * Nome do perfil
   */
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PerfilAcessoAutoComplete;

pub struct PerfilAcessoAutoComplete {
    /// Id do perfil de acesso
    pub id: uuid::Uuid,
    /// Nome do perfil
    pub nome: String,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/leads";

export interface PerfilAcessoCriar {
  /**
   * Descrição do perfil, até 200 caracteres
   */
  descricao?: string | null;
  /**
   * Nome do perfil, até 80 caracteres
   */
  nome: string;
  /**
   * Ações liberadas em cada área; o que não vier fica `false`
   */
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    /// Descrição do perfil, até 200 caracteres
    pub descricao: Option<String>,
    /// Nome do perfil, até 80 caracteres
    pub nome: String,
    /// Ações liberadas em cada área; o que não vier fica `false`
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/leads";

export interface Permissoes {
  /**
   * Ações liberadas na área `colaboradores`: colaboradores e perfis de acesso
   */
  colaboradores?: Acoes;
  /**
   * Ações liberadas na área `empresas`: Consultar CNPJ e Localizar Empresas
   */
  empresas?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::Permissoes;

pub struct Permissoes {
    /// Ações liberadas na área `colaboradores`: colaboradores e perfis de acesso
    pub colaboradores: Option<Acoes>,
    /// Ações liberadas na área `empresas`: Consultar CNPJ e Localizar Empresas
    pub empresas: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Saúde (/docs/servicos/leads/saude)

> 1 função do TermoLeads para saúde.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`verificar_saude`](#verificar_saude) | `GET /healthz` | Confere se a API está no ar |

## `verificar_saude` [#verificar_saude]

<Rota metodo="GET" caminho="/healthz" />

Confere se a API está no ar

Rota pública, sem login. Responde `status: ok` e a versão do backend no ar (semver) quando o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude } from "termo_core/leads";

const resposta = await verificar_saude();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::leads::verificar_saude().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/leads";

export interface SaudeDoBackend {
  /**
   * Sempre `ok` quando o servidor está no ar
   */
  status: string;
  /**
   * Versão do backend no ar (semver do Cargo.toml)
   */
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::SaudeDoBackend;

pub struct SaudeDoBackend {
    /// Sempre `ok` quando o servidor está no ar
    pub status: String,
    /// Versão do backend no ar (semver do Cargo.toml)
    pub versao: String,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/leads/test)

> 2 funções do TermoLeads para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as leads from "termo_core/leads";
// ou: import { leads } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["leads"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true` e a versão do backend publicada, no formato semver. Qualquer rota que não existe responde `404` com `{ sucesso: false, mensagem: "Rota não encontrada" }`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/leads";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::leads::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` e a versão do backend no ar (semver) sempre que o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeTestDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/leads";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test(

) -> Result<tipos::SaudeTestDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::leads::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeTestDoBackend>` · Rust: `Result<tipos::SaudeTestDoBackend, ErroAoChamarServico>` · veja [`SaudeTestDoBackend`](#tipo-saudetestdobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeTestDoBackend [#tipo-saudetestdobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeTestDoBackend } from "termo_core/leads";

export interface SaudeTestDoBackend {
  /**
   * Sempre `Backend no ar`
   */
  mensagem: string;
  /**
   * Sempre `true` quando o servidor está no ar
   */
  sucesso: boolean;
  /**
   * Versão do backend no ar (semver)
   */
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::SaudeTestDoBackend;

pub struct SaudeTestDoBackend {
    /// Sempre `Backend no ar`
    pub mensagem: String,
    /// Sempre `true` quando o servidor está no ar
    pub sucesso: bool,
    /// Versão do backend no ar (semver)
    pub versao: String,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/leads";

export interface VersaoDoBackend {
  /**
   * Sempre `true` quando o servidor está no ar
   */
  sucesso: boolean;
  /**
   * Versão do backend no ar (semver)
   */
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::leads::VersaoDoBackend;

pub struct VersaoDoBackend {
    /// Sempre `true` quando o servidor está no ar
    pub sucesso: bool,
    /// Versão do backend no ar (semver)
    pub versao: String,
}
```

</Tab>
</Tabs>


# TermoMCP (/docs/servicos/mcp)

> Cliente do TermoMCP no termo_core.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as mcp from "termo_core/mcp";
// ou: import { mcp } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["mcp"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::mcp` (feature `mcp`) |
| Importação TypeScript | `termo_core/mcp` ou `import { mcp } from "termo_core"` |
| Funções | 0 |
| Entidades | 0 |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51061` |
| `SANDBOX` | `https://sandbox-api-mcp.termotubos.com.br` |
| `PRODUCTION` | `https://api-mcp.termotubos.com.br` |

<Callout type="info" title="Ainda sem funções">O TermoMCP ainda não publicou o `openapi.json` no sandbox, então o módulo existe mas não tem funções. Elas aparecem aqui sozinhas assim que o contrato for publicado e o gerador rodar.</Callout>


# Arquivo (/docs/servicos/portal/arquivo)

> 3 funções do TermoPortal para arquivo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`criar_arquivo`](#criar_arquivo) | `POST /arquivo` | Envia um arquivo (imagem ou PDF de boletim) |
| [`buscar_pelo_id_arquivo`](#buscar_pelo_id_arquivo) | `GET /arquivo/{caminho}` | Lê um arquivo enviado |
| [`deletar_pelo_id_arquivo`](#deletar_pelo_id_arquivo) | `DELETE /arquivo/{caminho}` | Apaga um arquivo enviado |

## `criar_arquivo` [#criar_arquivo]

<Rota metodo="POST" caminho="/arquivo" credencial />

Envia um arquivo (imagem ou PDF de boletim)

Exige uma sessão válida; as pastas (`produtos` e `boletins`) exigem a permissão `criar` ou `editar` no módulo `Configuracoes`. Formulário `multipart/form-data` com os campos `pasta` e `arquivo`. Imagem de produto (`produtos`, até 5 MB, PNG, JPG, WEBP ou GIF) vai para o TermoBucket (bucket público, app `portal-b2b`, pelo token do próprio app) e a `url` devolvida é o endereço público permanente dela, que vai nas `imagens` do produto (até 15). PDF de boletim (`boletins`, até 20 MB) fica no disco da API e a `url` é relativa (`/arquivo/boletins/<uuid>.pdf`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  formulario: FormData,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Arquivo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_arquivo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_arquivo(credencial_de_acesso, formulario);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    formulario: multipart::Form,
) -> Result<tipos::Arquivo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_arquivo(&credencial_de_acesso, formulario).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "formulario": { type: "FormData", required: true, description: "Corpo multipart/form-data (upload). · Rust: multipart::Form" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Arquivo>` · Rust: `Result<tipos::Arquivo, ErroAoChamarServico>` · veja [`Arquivo`](#tipo-arquivo).

## `buscar_pelo_id_arquivo` [#buscar_pelo_id_arquivo]

<Rota metodo="GET" caminho="/arquivo/{caminho}" credencial />

Lê um arquivo enviado

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve o conteúdo do arquivo com o `Content-Type` dele (imagem ou PDF). `caminho` é o que vem depois de `/arquivo/` na `url` devolvida pelo envio (ex.: `produtos/<uuid>.png`). Campos: `baixar` com o valor `1` força o download (Content-Disposition attachment); `nome` é o nome sugerido para o download (só letras, números, ponto, hífen e `_`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  caminho: string,
  parametros: ParametrosDeBuscarPeloIdArquivo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Uint8Array>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_arquivo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_arquivo(credencial_de_acesso, caminho, { baixar: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    caminho: &str,
    parametros: &ParametrosDeBuscarPeloIdArquivo,
) -> Result<Vec<u8>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_arquivo(
    &credencial_de_acesso,
    &caminho,
    &termo_core::portal::ParametrosDeBuscarPeloIdArquivo { baixar: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "caminho": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "parametros.baixar": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Uint8Array>` · Rust: `Result<Vec<u8>, ErroAoChamarServico>` · os bytes do arquivo.

## `deletar_pelo_id_arquivo` [#deletar_pelo_id_arquivo]

<Rota metodo="DELETE" caminho="/arquivo/{caminho}" credencial />

Apaga um arquivo enviado

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Apaga o arquivo do disco de verdade (não há exclusão lógica para arquivos). `caminho` é o que vem depois de `/arquivo/` na `url`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_arquivo(
  credencial_de_acesso: CredencialDeAcesso,
  caminho: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_arquivo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_arquivo(credencial_de_acesso, caminho);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_arquivo(
    credencial_de_acesso: &CredencialDeAcesso,
    caminho: &str,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_arquivo(&credencial_de_acesso, &caminho).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "caminho": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Arquivo [#tipo-arquivo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Arquivo } from "termo_core/portal";

export interface Arquivo {
  url: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Arquivo;

pub struct Arquivo {
    pub url: String,
}
```

</Tab>
</Tabs>


# Boletim técnico (/docs/servicos/portal/boletim_tecnico)

> 8 funções do TermoPortal para boletim técnico.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_boletim_tecnico`](#buscar_paginador_boletim_tecnico) | `GET /boletim_tecnico` | Lista as categorias com a situação do boletim |
| [`criar_boletim_tecnico`](#criar_boletim_tecnico) | `POST /boletim_tecnico` | Cria o boletim técnico de uma categoria |
| [`buscar_auto_complete_boletim_tecnico`](#buscar_auto_complete_boletim_tecnico) | `GET /boletim_tecnico/autocomplete` | Lista básica dos boletins para seleção |
| [`buscar_pelo_filtro_boletim_tecnico`](#buscar_pelo_filtro_boletim_tecnico) | `GET /boletim_tecnico/filtro` | Busca boletins por categoria |
| [`buscar_informacoes_paginador_boletim_tecnico`](#buscar_informacoes_paginador_boletim_tecnico) | `GET /boletim_tecnico/paginador` | Totais da lista de categorias do boletim |
| [`buscar_pelo_id_boletim_tecnico`](#buscar_pelo_id_boletim_tecnico) | `GET /boletim_tecnico/{id}` | Busca um boletim técnico pelo id |
| [`atualizar_pelo_id_boletim_tecnico`](#atualizar_pelo_id_boletim_tecnico) | `PATCH /boletim_tecnico/{id}` | Atualiza a descrição da categoria |
| [`deletar_pelo_id_boletim_tecnico`](#deletar_pelo_id_boletim_tecnico) | `DELETE /boletim_tecnico/{id}` | Exclui o boletim técnico e as medidas dele |

## `buscar_paginador_boletim_tecnico` [#buscar_paginador_boletim_tecnico]

<Rota metodo="GET" caminho="/boletim_tecnico" credencial />

Lista as categorias com a situação do boletim

Exige sessão. Uma linha por categoria do SKU (`sku_categoria` da tabela auxiliar, mais as que já têm boletim), tenha ela boletim ou não: `boletim_tecnico_id` e `atualizado_em` vêm nulos quando ainda não tem. `total_medidas` junta as medidas dos produtos da categoria e as já descritas; `situacao` é `vazio` (sem descrição e sem medida descrita), `completo` (com descrição e todas as medidas descritas) ou `incompleto`. `busca` procura no código e na descrição; `situacao` filtra. Ordem pelo código, 50 por página, por cursor: `cursor` é o `sku_categoria` da última linha recebida. As categorias saem de um cache em memória, descartado a cada gravação em boletim, medida, tabela auxiliar ou produto (e recarregado do banco no máximo a cada 10 minutos).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorBoletimTecnico = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.BoletimTecnicoCategoria>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_boletim_tecnico(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorBoletimTecnico,
) -> Result<Vec<tipos::BoletimTecnicoCategoria>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_boletim_tecnico(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorBoletimTecnico { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.BoletimTecnicoCategoria>>` · Rust: `Result<Vec<tipos::BoletimTecnicoCategoria>, ErroAoChamarServico>`

## `criar_boletim_tecnico` [#criar_boletim_tecnico]

<Rota metodo="POST" caminho="/boletim_tecnico" credencial />

Cria o boletim técnico de uma categoria

Exige o módulo `Configuracoes` (criar). O boletim é o pai: um por categoria do SKU. `sku_categoria` obrigatório (os 3 primeiros caracteres do SKU, ex.: `T2Z`; gravado em maiúsculas); `descricao` opcional (texto livre, até 10.000 caracteres, padrão vazio). Uma categoria só tem um boletim.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.BoletimTecnicoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnico>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_boletim_tecnico(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::BoletimTecnicoCriar,
) -> Result<tipos::BoletimTecnico, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_boletim_tecnico(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.BoletimTecnicoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::BoletimTecnicoCriar", typeDescriptionLink: "#tipo-boletimtecnicocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnico>` · Rust: `Result<tipos::BoletimTecnico, ErroAoChamarServico>` · veja [`BoletimTecnico`](#tipo-boletimtecnico).

## `buscar_auto_complete_boletim_tecnico` [#buscar_auto_complete_boletim_tecnico]

<Rota metodo="GET" caminho="/boletim_tecnico/autocomplete" credencial />

Lista básica dos boletins para seleção

Exige sessão. Só id e a categoria (`label`), em ordem alfabética. `busca` procura na categoria. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteBoletimTecnico = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaBoletimTecnicoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_boletim_tecnico(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteBoletimTecnico,
) -> Result<tipos::PaginaBoletimTecnicoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_boletim_tecnico(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteBoletimTecnico { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaBoletimTecnicoAutoComplete>` · Rust: `Result<tipos::PaginaBoletimTecnicoAutoComplete, ErroAoChamarServico>` · veja [`PaginaBoletimTecnicoAutoComplete`](#tipo-paginaboletimtecnicoautocomplete).

## `buscar_pelo_filtro_boletim_tecnico` [#buscar_pelo_filtro_boletim_tecnico]

<Rota metodo="GET" caminho="/boletim_tecnico/filtro" credencial />

Busca boletins por categoria

Exige sessão. Até 50 por página (`pagina`, a partir de 1, padrão 1). `sku_categoria` é exato (sem diferença de maiúsculas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroBoletimTecnico = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.BoletimTecnico>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_boletim_tecnico(credencial_de_acesso, { sku_categoria: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroBoletimTecnico,
) -> Result<Vec<tipos::BoletimTecnico>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_boletim_tecnico(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroBoletimTecnico { sku_categoria: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku_categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.BoletimTecnico>>` · Rust: `Result<Vec<tipos::BoletimTecnico>, ErroAoChamarServico>`

## `buscar_informacoes_paginador_boletim_tecnico` [#buscar_informacoes_paginador_boletim_tecnico]

<Rota metodo="GET" caminho="/boletim_tecnico/paginador" credencial />

Totais da lista de categorias do boletim

Exige sessão. Recebe os mesmos filtros de `GET /boletim_tecnico` (`cursor` é ignorado). `total` respeita todos os filtros; `total_categorias`, `completas`, `incompletas` e `vazias` respeitam só a `busca` (para os contadores das abas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_informacoes_paginador_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarInformacoesPaginadorBoletimTecnico = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnicoPaginador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_informacoes_paginador_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_informacoes_paginador_boletim_tecnico(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_informacoes_paginador_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarInformacoesPaginadorBoletimTecnico,
) -> Result<tipos::BoletimTecnicoPaginador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_informacoes_paginador_boletim_tecnico(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarInformacoesPaginadorBoletimTecnico { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnicoPaginador>` · Rust: `Result<tipos::BoletimTecnicoPaginador, ErroAoChamarServico>` · veja [`BoletimTecnicoPaginador`](#tipo-boletimtecnicopaginador).

## `buscar_pelo_id_boletim_tecnico` [#buscar_pelo_id_boletim_tecnico]

<Rota metodo="GET" caminho="/boletim_tecnico/{id}" credencial />

Busca um boletim técnico pelo id

Exige sessão. Boletim excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnico>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_boletim_tecnico(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::BoletimTecnico, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_boletim_tecnico(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnico>` · Rust: `Result<tipos::BoletimTecnico, ErroAoChamarServico>` · veja [`BoletimTecnico`](#tipo-boletimtecnico).

## `atualizar_pelo_id_boletim_tecnico` [#atualizar_pelo_id_boletim_tecnico]

<Rota metodo="PATCH" caminho="/boletim_tecnico/{id}" credencial />

Atualiza a descrição da categoria

Exige o módulo `Configuracoes` (editar). Muda só a `descricao` (até 10.000 caracteres, pode ficar vazia); campo ausente mantém o valor atual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.BoletimTecnicoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnico>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_boletim_tecnico(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::BoletimTecnicoAtualizar,
) -> Result<tipos::BoletimTecnico, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_boletim_tecnico(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.BoletimTecnicoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::BoletimTecnicoAtualizar", typeDescriptionLink: "#tipo-boletimtecnicoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnico>` · Rust: `Result<tipos::BoletimTecnico, ErroAoChamarServico>` · veja [`BoletimTecnico`](#tipo-boletimtecnico).

## `deletar_pelo_id_boletim_tecnico` [#deletar_pelo_id_boletim_tecnico]

<Rota metodo="DELETE" caminho="/boletim_tecnico/{id}" credencial />

Exclui o boletim técnico e as medidas dele

Exige o módulo `Configuracoes` (excluir). Exclusão lógica do boletim e de todas as descrições de medida dele, na mesma transação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_boletim_tecnico(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_boletim_tecnico } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_boletim_tecnico(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_boletim_tecnico(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_boletim_tecnico(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### BoletimTecnico [#tipo-boletimtecnico]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnico } from "termo_core/portal";

export interface BoletimTecnico {
  atualizado_em: string;
  criado_em: string;
  descricao: string;
  id: string;
  resumo: string;
  sku_categoria: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnico;

pub struct BoletimTecnico {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub id: uuid::Uuid,
    pub resumo: String,
    pub sku_categoria: String,
}
```

</Tab>
</Tabs>

### BoletimTecnicoAtualizar [#tipo-boletimtecnicoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoAtualizar } from "termo_core/portal";

export interface BoletimTecnicoAtualizar {
  descricao?: string | null;
  resumo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoAtualizar;

pub struct BoletimTecnicoAtualizar {
    pub descricao: Option<String>,
    pub resumo: Option<String>,
}
```

</Tab>
</Tabs>

### BoletimTecnicoCategoria [#tipo-boletimtecnicocategoria]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoCategoria } from "termo_core/portal";

export interface BoletimTecnicoCategoria {
  atualizado_em?: string | null;
  boletim_tecnico_id?: string | null;
  descricao: string;
  medidas_descritas: number;
  resumo: string;
  situacao: string;
  sku_categoria: string;
  total_medidas: number;
  total_produtos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoCategoria;

pub struct BoletimTecnicoCategoria {
    pub atualizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub boletim_tecnico_id: Option<uuid::Uuid>,
    pub descricao: String,
    pub medidas_descritas: i64,
    pub resumo: String,
    pub situacao: String,
    pub sku_categoria: String,
    pub total_medidas: i64,
    pub total_produtos: i64,
}
```

</Tab>
</Tabs>

### BoletimTecnicoCriar [#tipo-boletimtecnicocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoCriar } from "termo_core/portal";

export interface BoletimTecnicoCriar {
  descricao?: string | null;
  resumo?: string | null;
  sku_categoria: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoCriar;

pub struct BoletimTecnicoCriar {
    pub descricao: Option<String>,
    pub resumo: Option<String>,
    pub sku_categoria: String,
}
```

</Tab>
</Tabs>

### BoletimTecnicoPaginador [#tipo-boletimtecnicopaginador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoPaginador } from "termo_core/portal";

export interface BoletimTecnicoPaginador {
  completas: number;
  incompletas: number;
  paginas: number;
  tamanho: number;
  total: number;
  total_categorias: number;
  vazias: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoPaginador;

pub struct BoletimTecnicoPaginador {
    pub completas: i64,
    pub incompletas: i64,
    pub paginas: i64,
    pub tamanho: i64,
    pub total: i64,
    pub total_categorias: i64,
    pub vazias: i64,
}
```

</Tab>
</Tabs>

### PaginaBoletimTecnicoAutoComplete [#tipo-paginaboletimtecnicoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaBoletimTecnicoAutoComplete } from "termo_core/portal";

export interface PaginaBoletimTecnicoAutoComplete {
  itens: Array<PaginaBoletimTecnicoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaBoletimTecnicoAutoComplete;

pub struct PaginaBoletimTecnicoAutoComplete {
    pub itens: Vec<PaginaBoletimTecnicoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaBoletimTecnicoAutoCompleteItensItem [#tipo-paginaboletimtecnicoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaBoletimTecnicoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaBoletimTecnicoAutoCompleteItensItem {
  id: string;
  label: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaBoletimTecnicoAutoCompleteItensItem;

pub struct PaginaBoletimTecnicoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub label: String,
}
```

</Tab>
</Tabs>


# Boletim técnico medida (/docs/servicos/portal/boletim_tecnico_medida)

> 8 funções do TermoPortal para boletim técnico medida.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_boletim_tecnico_medida`](#buscar_paginador_boletim_tecnico_medida) | `GET /boletim_tecnico_medida` | Lista as medidas de uma categoria com a descrição |
| [`criar_boletim_tecnico_medida`](#criar_boletim_tecnico_medida) | `POST /boletim_tecnico_medida` | Descreve uma medida do boletim técnico |
| [`buscar_auto_complete_boletim_tecnico_medida`](#buscar_auto_complete_boletim_tecnico_medida) | `GET /boletim_tecnico_medida/autocomplete` | Lista básica das medidas descritas para seleção |
| [`buscar_pelo_filtro_boletim_tecnico_medida`](#buscar_pelo_filtro_boletim_tecnico_medida) | `GET /boletim_tecnico_medida/filtro` | Busca medidas descritas por boletim ou medida |
| [`buscar_informacoes_paginador_boletim_tecnico_medida`](#buscar_informacoes_paginador_boletim_tecnico_medida) | `GET /boletim_tecnico_medida/paginador` | Totais das medidas de uma categoria |
| [`buscar_pelo_id_boletim_tecnico_medida`](#buscar_pelo_id_boletim_tecnico_medida) | `GET /boletim_tecnico_medida/{id}` | Busca a descrição de uma medida pelo id |
| [`atualizar_pelo_id_boletim_tecnico_medida`](#atualizar_pelo_id_boletim_tecnico_medida) | `PATCH /boletim_tecnico_medida/{id}` | Atualiza a descrição de uma medida |
| [`deletar_pelo_id_boletim_tecnico_medida`](#deletar_pelo_id_boletim_tecnico_medida) | `DELETE /boletim_tecnico_medida/{id}` | Exclui a descrição de uma medida |

## `buscar_paginador_boletim_tecnico_medida` [#buscar_paginador_boletim_tecnico_medida]

<Rota metodo="GET" caminho="/boletim_tecnico_medida" credencial />

Lista as medidas de uma categoria com a descrição

Exige sessão. `sku_categoria` obrigatório. Uma linha por medida da categoria (as dos produtos e as já descritas): `boletim_tecnico_medida_id`, `descricao` e `atualizado_em` vêm nulos quando a medida ainda não foi descrita; `total_produtos` e `exemplo_produto` (o primeiro nome em ordem alfabética) vêm dos produtos. `busca` procura na medida, na descrição e no nome do produto; `situacao` é `descrita` ou `pendente`. Ordem pela medida, 50 por página, por cursor: `cursor` é o `sku_medida` da última linha recebida. As medidas de cada categoria saem de um cache em memória, descartado a cada gravação em boletim, medida, tabela auxiliar ou produto (e recarregado do banco no máximo a cada 10 minutos).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorBoletimTecnicoMedida = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.BoletimTecnicoMedidaLinha>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_boletim_tecnico_medida(credencial_de_acesso, { sku_categoria: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorBoletimTecnicoMedida,
) -> Result<Vec<tipos::BoletimTecnicoMedidaLinha>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_boletim_tecnico_medida(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorBoletimTecnicoMedida { sku_categoria: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku_categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.BoletimTecnicoMedidaLinha>>` · Rust: `Result<Vec<tipos::BoletimTecnicoMedidaLinha>, ErroAoChamarServico>`

## `criar_boletim_tecnico_medida` [#criar_boletim_tecnico_medida]

<Rota metodo="POST" caminho="/boletim_tecnico_medida" credencial />

Descreve uma medida do boletim técnico

Exige o módulo `Configuracoes` (criar). A medida é filha do boletim da categoria. `boletim_tecnico_id` (uuid do boletim), `sku_medida` (os 4 caracteres do SKU depois da categoria, ex.: `0064`; gravado em maiúsculas) e `descricao` (texto, até 10.000 caracteres; cada linha é um item) obrigatórios. Uma medida só tem uma descrição por boletim.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.BoletimTecnicoMedidaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnicoMedida>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_boletim_tecnico_medida(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::BoletimTecnicoMedidaCriar,
) -> Result<tipos::BoletimTecnicoMedida, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_boletim_tecnico_medida(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.BoletimTecnicoMedidaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::BoletimTecnicoMedidaCriar", typeDescriptionLink: "#tipo-boletimtecnicomedidacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnicoMedida>` · Rust: `Result<tipos::BoletimTecnicoMedida, ErroAoChamarServico>` · veja [`BoletimTecnicoMedida`](#tipo-boletimtecnicomedida).

## `buscar_auto_complete_boletim_tecnico_medida` [#buscar_auto_complete_boletim_tecnico_medida]

<Rota metodo="GET" caminho="/boletim_tecnico_medida/autocomplete" credencial />

Lista básica das medidas descritas para seleção

Exige sessão. Só id e a medida (`label`), em ordem alfabética. `boletim_tecnico_id` restringe a um boletim; `busca` procura na medida. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteBoletimTecnicoMedida = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaBoletimTecnicoMedidaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_boletim_tecnico_medida(credencial_de_acesso, { boletim_tecnico_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteBoletimTecnicoMedida,
) -> Result<tipos::PaginaBoletimTecnicoMedidaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_boletim_tecnico_medida(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteBoletimTecnicoMedida { boletim_tecnico_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.boletim_tecnico_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaBoletimTecnicoMedidaAutoComplete>` · Rust: `Result<tipos::PaginaBoletimTecnicoMedidaAutoComplete, ErroAoChamarServico>` · veja [`PaginaBoletimTecnicoMedidaAutoComplete`](#tipo-paginaboletimtecnicomedidaautocomplete).

## `buscar_pelo_filtro_boletim_tecnico_medida` [#buscar_pelo_filtro_boletim_tecnico_medida]

<Rota metodo="GET" caminho="/boletim_tecnico_medida/filtro" credencial />

Busca medidas descritas por boletim ou medida

Exige sessão. Até 50 por página (`pagina`, a partir de 1, padrão 1). `boletim_tecnico_id` e `sku_medida` são exatos e opcionais.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroBoletimTecnicoMedida = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.BoletimTecnicoMedida>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_boletim_tecnico_medida(credencial_de_acesso, { boletim_tecnico_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroBoletimTecnicoMedida,
) -> Result<Vec<tipos::BoletimTecnicoMedida>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_boletim_tecnico_medida(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroBoletimTecnicoMedida { boletim_tecnico_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.boletim_tecnico_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.sku_medida": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.BoletimTecnicoMedida>>` · Rust: `Result<Vec<tipos::BoletimTecnicoMedida>, ErroAoChamarServico>`

## `buscar_informacoes_paginador_boletim_tecnico_medida` [#buscar_informacoes_paginador_boletim_tecnico_medida]

<Rota metodo="GET" caminho="/boletim_tecnico_medida/paginador" credencial />

Totais das medidas de uma categoria

Exige sessão. Mesmos filtros de `GET /boletim_tecnico_medida` (`cursor` é ignorado). `total` respeita todos os filtros; `total_medidas`, `descritas` e `pendentes` respeitam só a categoria e a `busca`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_informacoes_paginador_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarInformacoesPaginadorBoletimTecnicoMedida = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnicoMedidaPaginador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_informacoes_paginador_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_informacoes_paginador_boletim_tecnico_medida(credencial_de_acesso, { sku_categoria: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_informacoes_paginador_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarInformacoesPaginadorBoletimTecnicoMedida,
) -> Result<tipos::BoletimTecnicoMedidaPaginador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_informacoes_paginador_boletim_tecnico_medida(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarInformacoesPaginadorBoletimTecnicoMedida { sku_categoria: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku_categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnicoMedidaPaginador>` · Rust: `Result<tipos::BoletimTecnicoMedidaPaginador, ErroAoChamarServico>` · veja [`BoletimTecnicoMedidaPaginador`](#tipo-boletimtecnicomedidapaginador).

## `buscar_pelo_id_boletim_tecnico_medida` [#buscar_pelo_id_boletim_tecnico_medida]

<Rota metodo="GET" caminho="/boletim_tecnico_medida/{id}" credencial />

Busca a descrição de uma medida pelo id

Exige sessão. Medida excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnicoMedida>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_boletim_tecnico_medida(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::BoletimTecnicoMedida, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_boletim_tecnico_medida(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnicoMedida>` · Rust: `Result<tipos::BoletimTecnicoMedida, ErroAoChamarServico>` · veja [`BoletimTecnicoMedida`](#tipo-boletimtecnicomedida).

## `atualizar_pelo_id_boletim_tecnico_medida` [#atualizar_pelo_id_boletim_tecnico_medida]

<Rota metodo="PATCH" caminho="/boletim_tecnico_medida/{id}" credencial />

Atualiza a descrição de uma medida

Exige o módulo `Configuracoes` (editar). Muda só a `descricao` (não pode ficar vazia, até 10.000 caracteres); campo ausente mantém o valor atual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.BoletimTecnicoMedidaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BoletimTecnicoMedida>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_boletim_tecnico_medida(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::BoletimTecnicoMedidaAtualizar,
) -> Result<tipos::BoletimTecnicoMedida, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_boletim_tecnico_medida(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.BoletimTecnicoMedidaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::BoletimTecnicoMedidaAtualizar", typeDescriptionLink: "#tipo-boletimtecnicomedidaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BoletimTecnicoMedida>` · Rust: `Result<tipos::BoletimTecnicoMedida, ErroAoChamarServico>` · veja [`BoletimTecnicoMedida`](#tipo-boletimtecnicomedida).

## `deletar_pelo_id_boletim_tecnico_medida` [#deletar_pelo_id_boletim_tecnico_medida]

<Rota metodo="DELETE" caminho="/boletim_tecnico_medida/{id}" credencial />

Exclui a descrição de uma medida

Exige o módulo `Configuracoes` (excluir). Exclusão lógica: a medida volta a aparecer como pendente na lista enquanto houver produto com ela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_boletim_tecnico_medida(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_boletim_tecnico_medida } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_boletim_tecnico_medida(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_boletim_tecnico_medida(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_boletim_tecnico_medida(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### BoletimTecnicoMedida [#tipo-boletimtecnicomedida]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoMedida } from "termo_core/portal";

export interface BoletimTecnicoMedida {
  atualizado_em: string;
  boletim_tecnico_id: string;
  criado_em: string;
  descricao: string;
  id: string;
  sku_medida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoMedida;

pub struct BoletimTecnicoMedida {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub boletim_tecnico_id: uuid::Uuid,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub id: uuid::Uuid,
    pub sku_medida: String,
}
```

</Tab>
</Tabs>

### BoletimTecnicoMedidaAtualizar [#tipo-boletimtecnicomedidaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoMedidaAtualizar } from "termo_core/portal";

export interface BoletimTecnicoMedidaAtualizar {
  descricao?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoMedidaAtualizar;

pub struct BoletimTecnicoMedidaAtualizar {
    pub descricao: Option<String>,
}
```

</Tab>
</Tabs>

### BoletimTecnicoMedidaCriar [#tipo-boletimtecnicomedidacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoMedidaCriar } from "termo_core/portal";

export interface BoletimTecnicoMedidaCriar {
  boletim_tecnico_id: string;
  descricao: string;
  sku_medida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoMedidaCriar;

pub struct BoletimTecnicoMedidaCriar {
    pub boletim_tecnico_id: uuid::Uuid,
    pub descricao: String,
    pub sku_medida: String,
}
```

</Tab>
</Tabs>

### BoletimTecnicoMedidaLinha [#tipo-boletimtecnicomedidalinha]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoMedidaLinha } from "termo_core/portal";

export interface BoletimTecnicoMedidaLinha {
  atualizado_em?: string | null;
  boletim_tecnico_medida_id?: string | null;
  descricao?: string | null;
  exemplo_produto?: string | null;
  sku_medida: string;
  total_produtos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoMedidaLinha;

pub struct BoletimTecnicoMedidaLinha {
    pub atualizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub boletim_tecnico_medida_id: Option<uuid::Uuid>,
    pub descricao: Option<String>,
    pub exemplo_produto: Option<String>,
    pub sku_medida: String,
    pub total_produtos: i64,
}
```

</Tab>
</Tabs>

### BoletimTecnicoMedidaPaginador [#tipo-boletimtecnicomedidapaginador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BoletimTecnicoMedidaPaginador } from "termo_core/portal";

export interface BoletimTecnicoMedidaPaginador {
  descritas: number;
  paginas: number;
  pendentes: number;
  tamanho: number;
  total: number;
  total_medidas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BoletimTecnicoMedidaPaginador;

pub struct BoletimTecnicoMedidaPaginador {
    pub descritas: i64,
    pub paginas: i64,
    pub pendentes: i64,
    pub tamanho: i64,
    pub total: i64,
    pub total_medidas: i64,
}
```

</Tab>
</Tabs>

### PaginaBoletimTecnicoMedidaAutoComplete [#tipo-paginaboletimtecnicomedidaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaBoletimTecnicoMedidaAutoComplete } from "termo_core/portal";

export interface PaginaBoletimTecnicoMedidaAutoComplete {
  itens: Array<PaginaBoletimTecnicoMedidaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaBoletimTecnicoMedidaAutoComplete;

pub struct PaginaBoletimTecnicoMedidaAutoComplete {
    pub itens: Vec<PaginaBoletimTecnicoMedidaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaBoletimTecnicoMedidaAutoCompleteItensItem [#tipo-paginaboletimtecnicomedidaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaBoletimTecnicoMedidaAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaBoletimTecnicoMedidaAutoCompleteItensItem {
  id: string;
  label: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaBoletimTecnicoMedidaAutoCompleteItensItem;

pub struct PaginaBoletimTecnicoMedidaAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub label: String,
}
```

</Tab>
</Tabs>


# Catálogo atributo (/docs/servicos/portal/catalogo_atributo)

> 7 funções do TermoPortal para catálogo atributo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_catalogo_atributo`](#buscar_paginador_catalogo_atributo) | `GET /catalogo_atributo` | Lista os atributos do catálogo paginados |
| [`criar_catalogo_atributo`](#criar_catalogo_atributo) | `POST /catalogo_atributo` | Cadastra um atributo do catálogo |
| [`buscar_auto_complete_catalogo_atributo`](#buscar_auto_complete_catalogo_atributo) | `GET /catalogo_atributo/autocomplete` | Lista básica de atributos do catálogo para seleção |
| [`buscar_pelo_filtro_catalogo_atributo`](#buscar_pelo_filtro_catalogo_atributo) | `GET /catalogo_atributo/filtro` | Busca atributos do catálogo por filtro |
| [`buscar_pelo_id_catalogo_atributo`](#buscar_pelo_id_catalogo_atributo) | `GET /catalogo_atributo/{id}` | Busca um atributo do catálogo pelo id |
| [`atualizar_pelo_id_catalogo_atributo`](#atualizar_pelo_id_catalogo_atributo) | `PATCH /catalogo_atributo/{id}` | Atualiza um atributo do catálogo |
| [`deletar_pelo_id_catalogo_atributo`](#deletar_pelo_id_catalogo_atributo) | `DELETE /catalogo_atributo/{id}` | Exclui um atributo do catálogo |

## `buscar_paginador_catalogo_atributo` [#buscar_paginador_catalogo_atributo]

<Rota metodo="GET" caminho="/catalogo_atributo" credencial />

Lista os atributos do catálogo paginados

Exige só uma sessão válida (qualquer pessoa logada no portal). Ordem: tipo, `ordem`, valor; `tipo` opcional filtra. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCatalogoAtributo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCatalogoAtributo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_catalogo_atributo(credencial_de_acesso, { tipo: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCatalogoAtributo,
) -> Result<tipos::PaginaCatalogoAtributo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_catalogo_atributo(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorCatalogoAtributo { tipo: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCatalogoAtributo>` · Rust: `Result<tipos::PaginaCatalogoAtributo, ErroAoChamarServico>` · veja [`PaginaCatalogoAtributo`](#tipo-paginacatalogoatributo).

## `criar_catalogo_atributo` [#criar_catalogo_atributo]

<Rota metodo="POST" caminho="/catalogo_atributo" credencial />

Cadastra um atributo do catálogo

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Valor de atributo usado nas variações de produto (ex.: tipo `cor` valor `Azul`). `tipo` tem só letras minúsculas sem acento e `_` (até 40); `valor` é obrigatório, até 120 caracteres e único dentro do tipo; `cor_hexadecimal` (`#RRGGBB`) só vale para o tipo `cor`; `ordem` não negativa; `ativo` tem padrão `true`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.CatalogoAtributoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.CatalogoAtributo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_catalogo_atributo(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::CatalogoAtributoCriar,
) -> Result<tipos::CatalogoAtributo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_catalogo_atributo(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.CatalogoAtributoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::CatalogoAtributoCriar", typeDescriptionLink: "#tipo-catalogoatributocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.CatalogoAtributo>` · Rust: `Result<tipos::CatalogoAtributo, ErroAoChamarServico>` · veja [`CatalogoAtributo`](#tipo-catalogoatributo).

## `buscar_auto_complete_catalogo_atributo` [#buscar_auto_complete_catalogo_atributo]

<Rota metodo="GET" caminho="/catalogo_atributo/autocomplete" credencial />

Lista básica de atributos do catálogo para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve só id e valor, em ordem alfabética. `busca` procura no valor; `tipo` e `ativo` filtram. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteCatalogoAtributo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCatalogoAtributoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_catalogo_atributo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteCatalogoAtributo,
) -> Result<tipos::PaginaCatalogoAtributoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_catalogo_atributo(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteCatalogoAtributo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCatalogoAtributoAutoComplete>` · Rust: `Result<tipos::PaginaCatalogoAtributoAutoComplete, ErroAoChamarServico>` · veja [`PaginaCatalogoAtributoAutoComplete`](#tipo-paginacatalogoatributoautocomplete).

## `buscar_pelo_filtro_catalogo_atributo` [#buscar_pelo_filtro_catalogo_atributo]

<Rota metodo="GET" caminho="/catalogo_atributo/filtro" credencial />

Busca atributos do catálogo por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve os atributos não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), ordenados por tipo, `ordem` e valor. `tipo` é exato; `valor` procura o trecho; `ativo` filtra pela situação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroCatalogoAtributo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.CatalogoAtributo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_catalogo_atributo(credencial_de_acesso, { tipo: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroCatalogoAtributo,
) -> Result<Vec<tipos::CatalogoAtributo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_catalogo_atributo(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroCatalogoAtributo { tipo: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.valor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.CatalogoAtributo>>` · Rust: `Result<Vec<tipos::CatalogoAtributo>, ErroAoChamarServico>`

## `buscar_pelo_id_catalogo_atributo` [#buscar_pelo_id_catalogo_atributo]

<Rota metodo="GET" caminho="/catalogo_atributo/{id}" credencial />

Busca um atributo do catálogo pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Atributo excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.CatalogoAtributo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_catalogo_atributo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::CatalogoAtributo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_catalogo_atributo(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.CatalogoAtributo>` · Rust: `Result<tipos::CatalogoAtributo, ErroAoChamarServico>` · veja [`CatalogoAtributo`](#tipo-catalogoatributo).

## `atualizar_pelo_id_catalogo_atributo` [#atualizar_pelo_id_catalogo_atributo]

<Rota metodo="PATCH" caminho="/catalogo_atributo/{id}" credencial />

Atualiza um atributo do catálogo

Exige a permissão `editar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Muda `valor`, `cor_hexadecimal` (envie `null` para apagar), `ordem` e `ativo`; o tipo não muda. Atualização parcial: campo ausente mantém o valor atual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.CatalogoAtributoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.CatalogoAtributo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_catalogo_atributo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::CatalogoAtributoAtualizar,
) -> Result<tipos::CatalogoAtributo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_catalogo_atributo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.CatalogoAtributoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::CatalogoAtributoAtualizar", typeDescriptionLink: "#tipo-catalogoatributoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.CatalogoAtributo>` · Rust: `Result<tipos::CatalogoAtributo, ErroAoChamarServico>` · veja [`CatalogoAtributo`](#tipo-catalogoatributo).

## `deletar_pelo_id_catalogo_atributo` [#deletar_pelo_id_catalogo_atributo]

<Rota metodo="DELETE" caminho="/catalogo_atributo/{id}" credencial />

Exclui um atributo do catálogo

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_catalogo_atributo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_catalogo_atributo } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_catalogo_atributo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_catalogo_atributo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_catalogo_atributo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### CatalogoAtributo [#tipo-catalogoatributo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CatalogoAtributo } from "termo_core/portal";

export interface CatalogoAtributo {
  ativo: boolean;
  atualizado_em: string;
  cor_hexadecimal?: string | null;
  criado_em: string;
  id: string;
  ordem: number;
  tipo: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CatalogoAtributo;

pub struct CatalogoAtributo {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cor_hexadecimal: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub ordem: i32,
    pub tipo: String,
    pub valor: String,
}
```

</Tab>
</Tabs>

### CatalogoAtributoAtualizar [#tipo-catalogoatributoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CatalogoAtributoAtualizar } from "termo_core/portal";

export interface CatalogoAtributoAtualizar {
  ativo?: boolean | null;
  cor_hexadecimal?: string | null;
  ordem?: number | null;
  valor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CatalogoAtributoAtualizar;

pub struct CatalogoAtributoAtualizar {
    pub ativo: Option<bool>,
    pub cor_hexadecimal: Option<String>,
    pub ordem: Option<i32>,
    pub valor: Option<String>,
}
```

</Tab>
</Tabs>

### CatalogoAtributoCriar [#tipo-catalogoatributocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CatalogoAtributoCriar } from "termo_core/portal";

export interface CatalogoAtributoCriar {
  ativo?: boolean | null;
  cor_hexadecimal?: string | null;
  ordem?: number | null;
  tipo: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CatalogoAtributoCriar;

pub struct CatalogoAtributoCriar {
    pub ativo: Option<bool>,
    pub cor_hexadecimal: Option<String>,
    pub ordem: Option<i32>,
    pub tipo: String,
    pub valor: String,
}
```

</Tab>
</Tabs>

### PaginaCatalogoAtributo [#tipo-paginacatalogoatributo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCatalogoAtributo } from "termo_core/portal";

export interface PaginaCatalogoAtributo {
  itens: Array<PaginaCatalogoAtributoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCatalogoAtributo;

pub struct PaginaCatalogoAtributo {
    pub itens: Vec<PaginaCatalogoAtributoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaCatalogoAtributoAutoComplete [#tipo-paginacatalogoatributoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCatalogoAtributoAutoComplete } from "termo_core/portal";

export interface PaginaCatalogoAtributoAutoComplete {
  itens: Array<PaginaCatalogoAtributoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCatalogoAtributoAutoComplete;

pub struct PaginaCatalogoAtributoAutoComplete {
    pub itens: Vec<PaginaCatalogoAtributoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaCatalogoAtributoAutoCompleteItensItem [#tipo-paginacatalogoatributoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCatalogoAtributoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaCatalogoAtributoAutoCompleteItensItem {
  id: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCatalogoAtributoAutoCompleteItensItem;

pub struct PaginaCatalogoAtributoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub valor: String,
}
```

</Tab>
</Tabs>

### PaginaCatalogoAtributoItensItem [#tipo-paginacatalogoatributoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCatalogoAtributoItensItem } from "termo_core/portal";

export interface PaginaCatalogoAtributoItensItem {
  ativo: boolean;
  atualizado_em: string;
  cor_hexadecimal?: string | null;
  criado_em: string;
  id: string;
  ordem: number;
  tipo: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCatalogoAtributoItensItem;

pub struct PaginaCatalogoAtributoItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cor_hexadecimal: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub ordem: i32,
    pub tipo: String,
    pub valor: String,
}
```

</Tab>
</Tabs>


# Cliente (/docs/servicos/portal/cliente)

> 9 funções do TermoPortal para cliente.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_cliente`](#buscar_paginador_cliente) | `GET /cliente` | Uma página de clientes, por cursor |
| [`criar_cliente`](#criar_cliente) | `POST /cliente` | Cadastra o cliente |
| [`buscar_auto_complete_cliente`](#buscar_auto_complete_cliente) | `GET /cliente/autocomplete` | Lista básica de clientes para seleção |
| [`buscar_pelo_filtro_cliente`](#buscar_pelo_filtro_cliente) | `GET /cliente/filtro` | Busca clientes por filtro |
| [`buscar_informacoes_paginador_cliente`](#buscar_informacoes_paginador_cliente) | `GET /cliente/paginador` | Total, páginas e contagens dos clientes |
| [`sincronizar_cliente`](#sincronizar_cliente) | `POST /cliente/sincronizar` | Sincroniza um lote de clientes do Tiny |
| [`buscar_pelo_id_cliente`](#buscar_pelo_id_cliente) | `GET /cliente/{id}` | Busca o cliente pelo id |
| [`atualizar_pelo_id_cliente`](#atualizar_pelo_id_cliente) | `PATCH /cliente/{id}` | Atualiza o cliente |
| [`deletar_pelo_id_cliente`](#deletar_pelo_id_cliente) | `DELETE /cliente/{id}` | Exclui o cliente |

## `buscar_paginador_cliente` [#buscar_paginador_cliente]

<Rota metodo="GET" caminho="/cliente" credencial />

Uma página de clientes, por cursor

A tabela `cliente` tem os clientes do Tiny (cópia do TermoIntranetAPI mantida pela sincronização do backend) e, na mesma linha, o login de quem entra no portal pela área `/app` (`email` e `identificador_termoauth`; cada unidade tem um cliente só, `unidade.cliente_id`). Exige a permissão `ver` no módulo `Configuracoes`; quem não é colaborador interno vê só os clientes das próprias unidades. Ordem alfabética do nome (sem acento; empate pelo id). Devolve só o array dos 50 clientes da página; a seguinte manda em `cursor` o `id` do último cliente recebido. Filtros: `busca` (CPF/CNPJ ou palavras do nome e do nome fantasia, sem acento), `acesso` (`com` = tem login, `sem` = só cadastro do Tiny, `solicitacoes` = pediu acesso; sem ele, todos), `uf`, `cidade`, `vendedor` (nome no Tiny) e `unidade_id`. Total, páginas e contagens vêm de `GET /cliente/paginador`, com os mesmos filtros.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Cliente>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_cliente(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCliente,
) -> Result<Vec<tipos::Cliente>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_cliente(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorCliente { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.acesso": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_pessoa": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Cliente>>` · Rust: `Result<Vec<tipos::Cliente>, ErroAoChamarServico>`

## `criar_cliente` [#criar_cliente]

<Rota metodo="POST" caminho="/cliente" credencial />

Cadastra o cliente

Cliente é o usuário de fora da Termotubos: entra pela área `/app` e cada unidade tem um cliente só (`unidade.cliente_id`). Exige a permissão administrativa `usuarios.gerenciar`; quem não é colaborador interno só cria cliente nas próprias unidades (informe ao menos uma em `unidade_ids`) e não escolhe perfil nem grupo. `nome` obrigatório até 150 caracteres; `email` válido e único entre clientes e colaboradores; `telefone` com 10 ou 11 dígitos; `cargo` até 120; `status` `ativo`, `pendente` ou `inativo`; `perfil_id` de cliente (sem ele vale o perfil base).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ClienteCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_cliente(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ClienteCriar,
) -> Result<tipos::Cliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_cliente(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ClienteCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ClienteCriar", typeDescriptionLink: "#tipo-clientecriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cliente>` · Rust: `Result<tipos::Cliente, ErroAoChamarServico>` · veja [`Cliente`](#tipo-cliente).

## `buscar_auto_complete_cliente` [#buscar_auto_complete_cliente]

<Rota metodo="GET" caminho="/cliente/autocomplete" credencial />

Lista básica de clientes para seleção

Cliente é o usuário de fora da Termotubos: entra pela área `/app` e cada unidade tem um cliente só (`unidade.cliente_id`). Exige a permissão `ver` no módulo `Configuracoes`; quem não é colaborador interno vê só os clientes das próprias unidades. Devolve id, nome e e-mail em ordem alfabética; `busca` procura no nome e no e-mail; `tamanho` de 1 a 50 (padrão 10). Com `tipo` (`uf`, `cidade` ou `vendedor`; só colaborador interno) devolve, em vez da página, as opções do filtro da tela tiradas do cadastro do Tiny (`valor`, `rotulo`, `clientes`), da mais usada para a menos usada, até 50; `busca` procura trecho (sem acento).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaClienteAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_cliente(credencial_de_acesso, { tipo: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteCliente,
) -> Result<tipos::PaginaClienteAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_cliente(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteCliente { tipo: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaClienteAutoComplete>` · Rust: `Result<tipos::PaginaClienteAutoComplete, ErroAoChamarServico>` · veja [`PaginaClienteAutoComplete`](#tipo-paginaclienteautocomplete).

## `buscar_pelo_filtro_cliente` [#buscar_pelo_filtro_cliente]

<Rota metodo="GET" caminho="/cliente/filtro" credencial />

Busca clientes por filtro

Cliente é o usuário de fora da Termotubos: entra pela área `/app` e cada unidade tem um cliente só (`unidade.cliente_id`). Exige a permissão `ver` no módulo `Configuracoes`; quem não é colaborador interno vê só os clientes das próprias unidades. Até 50 por página (`pagina`, a partir de 1, padrão 1), em ordem alfabética; `nome` e `email` procuram o trecho, os demais são exatos. `acesso` tem padrão `com` (só quem tem login no portal); `sem`, `solicitacoes` ou `todos` para os outros, porque o cadastro do Tiny inteiro tem dezenas de milhares de clientes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Cliente>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_cliente(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroCliente,
) -> Result<Vec<tipos::Cliente>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_cliente(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroCliente { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.acesso": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Cliente>>` · Rust: `Result<Vec<tipos::Cliente>, ErroAoChamarServico>`

## `buscar_informacoes_paginador_cliente` [#buscar_informacoes_paginador_cliente]

<Rota metodo="GET" caminho="/cliente/paginador" credencial />

Total, páginas e contagens dos clientes

Mesma permissão e mesmos parâmetros de `GET /cliente` (`cursor` não muda a conta). Devolve `total` (clientes com os filtros e o `acesso`), `paginas` (total dividido por `tamanho`, arredondado para cima, no mínimo 1), `tamanho` (sempre 50), `contagens` por acesso (`todos`, `com_acesso`, `sem_acesso`, `solicitacoes`), que usam os outros filtros e ignoram o `acesso`, e `sincronizado_em` (a última sincronização com o Tiny; nulo se nunca houve).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_informacoes_paginador_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarInformacoesPaginadorCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ClientePaginador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_informacoes_paginador_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_informacoes_paginador_cliente(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_informacoes_paginador_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarInformacoesPaginadorCliente,
) -> Result<tipos::ClientePaginador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_informacoes_paginador_cliente(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarInformacoesPaginadorCliente { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.acesso": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_pessoa": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.situacao_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ClientePaginador>` · Rust: `Result<tipos::ClientePaginador, ErroAoChamarServico>` · veja [`ClientePaginador`](#tipo-clientepaginador).

## `sincronizar_cliente` [#sincronizar_cliente]

<Rota metodo="POST" caminho="/cliente/sincronizar" credencial />

Sincroniza um lote de clientes do Tiny

Só colaborador interno com `editar` no módulo `Configuracoes`. Traz 10 páginas (500 clientes) do TermoIntranetAPI pelo `termo_core` (token do próprio app no TermoAuth) e grava na tabela `cliente`: cliente que já entra no portal é casado pelo CNPJ da unidade dele e só recebe os campos do Tiny (`id_api`, `codigo`, `id_tiny`, `cpf_cnpj`, `tipo_pessoa`, `nome_fantasia`, `email_tiny`, `telefone_tiny`, `celular`, `cidade`, `uf`, `vendedor`, `situacao_tiny`); os demais entram sem login (`email` nulo, `status` `inativo`). A listagem de lá é por cursor: a primeira chamada vai sem `cursor` e a seguinte manda o `proximo_cursor` recebido (nulo no fim). `total` é o total de clientes ativos na intranet. O backend também sincroniza sozinho (`SINCRONIZACAO_CLIENTE_MINUTOS`, `_PAGINAS` e `_COMPLETA_HORAS`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function sincronizar_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ClienteSincronizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SincronizacaoClientes>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { sincronizar_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await sincronizar_cliente(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn sincronizar_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ClienteSincronizar,
) -> Result<tipos::SincronizacaoClientes, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::sincronizar_cliente(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ClienteSincronizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ClienteSincronizar", typeDescriptionLink: "#tipo-clientesincronizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SincronizacaoClientes>` · Rust: `Result<tipos::SincronizacaoClientes, ErroAoChamarServico>` · veja [`SincronizacaoClientes`](#tipo-sincronizacaoclientes).

## `buscar_pelo_id_cliente` [#buscar_pelo_id_cliente]

<Rota metodo="GET" caminho="/cliente/{id}" credencial />

Busca o cliente pelo id

Cliente é o usuário de fora da Termotubos: entra pela área `/app` e cada unidade tem um cliente só (`unidade.cliente_id`). O próprio cliente sempre se vê; ver outro exige a permissão `ver` em `Configuracoes` e, fora do colaborador interno, que ele seja de uma unidade da sessão. Traz unidades, perfil e grupo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_cliente(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Cliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_cliente(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cliente>` · Rust: `Result<tipos::Cliente, ErroAoChamarServico>` · veja [`Cliente`](#tipo-cliente).

## `atualizar_pelo_id_cliente` [#atualizar_pelo_id_cliente]

<Rota metodo="PATCH" caminho="/cliente/{id}" credencial />

Atualiza o cliente

Cliente é o usuário de fora da Termotubos: entra pela área `/app` e cada unidade tem um cliente só (`unidade.cliente_id`). Atualização parcial. Sem `usuarios.gerenciar`, o próprio cliente só altera nome, telefone, cargo e `presente` (heartbeat que grava `ultimo_acesso_em`). `unidade_ids` substitui as unidades do cliente.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ClienteAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_cliente(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ClienteAtualizar,
) -> Result<tipos::Cliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_cliente(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ClienteAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ClienteAtualizar", typeDescriptionLink: "#tipo-clienteatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cliente>` · Rust: `Result<tipos::Cliente, ErroAoChamarServico>` · veja [`Cliente`](#tipo-cliente).

## `deletar_pelo_id_cliente` [#deletar_pelo_id_cliente]

<Rota metodo="DELETE" caminho="/cliente/{id}" credencial />

Exclui o cliente

Cliente é o usuário de fora da Termotubos: entra pela área `/app` e cada unidade tem um cliente só (`unidade.cliente_id`). Exige `usuarios.gerenciar`; as unidades do cliente ficam sem cliente. Exclusão lógica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_cliente } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_cliente(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_cliente(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Cliente [#tipo-cliente]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cliente } from "termo_core/portal";

export interface Cliente {
  atualizado_em: string;
  cargo?: string | null;
  celular?: string | null;
  cidade?: string | null;
  codigo?: string | null;
  cpf_cnpj?: string | null;
  criado_em: string;
  email?: string | null;
  email_tiny?: string | null;
  id: string;
  id_api?: number | null;
  id_tiny?: number | null;
  nome: string;
  nome_fantasia?: string | null;
  sincronizado_em?: string | null;
  situacao_tiny?: string | null;
  status: string;
  telefone?: string | null;
  telefone_tiny?: string | null;
  tipo_pessoa?: string | null;
  uf?: string | null;
  ultimo_acesso_em?: string | null;
  unidades: Array<UnidadeDoCliente>;
  vendedor?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Cliente;

pub struct Cliente {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cargo: Option<String>,
    pub celular: Option<String>,
    pub cidade: Option<String>,
    pub codigo: Option<String>,
    pub cpf_cnpj: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: Option<String>,
    pub email_tiny: Option<String>,
    pub id: uuid::Uuid,
    pub id_api: Option<i64>,
    pub id_tiny: Option<i64>,
    pub nome: String,
    pub nome_fantasia: Option<String>,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub situacao_tiny: Option<String>,
    pub status: String,
    pub telefone: Option<String>,
    pub telefone_tiny: Option<String>,
    pub tipo_pessoa: Option<String>,
    pub uf: Option<String>,
    pub ultimo_acesso_em: Option<chrono::DateTime<chrono::Utc>>,
    pub unidades: Vec<UnidadeDoCliente>,
    pub vendedor: Option<String>,
}
```

</Tab>
</Tabs>

### ClienteAtualizar [#tipo-clienteatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteAtualizar } from "termo_core/portal";

export interface ClienteAtualizar {
  cargo?: string | null;
  email?: string | null;
  nome?: string | null;
  presente?: boolean | null;
  status?: string | null;
  telefone?: string | null;
  unidade_ids?: Array<string> | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ClienteAtualizar;

pub struct ClienteAtualizar {
    pub cargo: Option<String>,
    pub email: Option<String>,
    pub nome: Option<String>,
    pub presente: Option<bool>,
    pub status: Option<String>,
    pub telefone: Option<String>,
    pub unidade_ids: Option<Vec<uuid::Uuid>>,
}
```

</Tab>
</Tabs>

### ClienteCriar [#tipo-clientecriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteCriar } from "termo_core/portal";

export interface ClienteCriar {
  cargo?: string | null;
  email: string;
  nome: string;
  status?: string | null;
  telefone?: string | null;
  unidade_ids?: Array<string> | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ClienteCriar;

pub struct ClienteCriar {
    pub cargo: Option<String>,
    pub email: String,
    pub nome: String,
    pub status: Option<String>,
    pub telefone: Option<String>,
    pub unidade_ids: Option<Vec<uuid::Uuid>>,
}
```

</Tab>
</Tabs>

### ClientePaginador [#tipo-clientepaginador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClientePaginador } from "termo_core/portal";

export interface ClientePaginador {
  contagens: ContagemClientes;
  paginas: number;
  sincronizado_em?: string | null;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ClientePaginador;

pub struct ClientePaginador {
    pub contagens: ContagemClientes,
    pub paginas: i64,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### ClienteSincronizar [#tipo-clientesincronizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteSincronizar } from "termo_core/portal";

export interface ClienteSincronizar {
  cursor?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ClienteSincronizar;

pub struct ClienteSincronizar {
    pub cursor: Option<i64>,
}
```

</Tab>
</Tabs>

### ContagemClientes [#tipo-contagemclientes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContagemClientes } from "termo_core/portal";

export interface ContagemClientes {
  com_acesso: number;
  sem_acesso: number;
  solicitacoes: number;
  todos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContagemClientes;

pub struct ContagemClientes {
    pub com_acesso: i64,
    pub sem_acesso: i64,
    pub solicitacoes: i64,
    pub todos: i64,
}
```

</Tab>
</Tabs>

### PaginaClienteAutoComplete [#tipo-paginaclienteautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteAutoComplete } from "termo_core/portal";

export interface PaginaClienteAutoComplete {
  itens: Array<PaginaClienteAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaClienteAutoComplete;

pub struct PaginaClienteAutoComplete {
    pub itens: Vec<PaginaClienteAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaClienteAutoCompleteItensItem [#tipo-paginaclienteautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaClienteAutoCompleteItensItem {
  email?: string | null;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaClienteAutoCompleteItensItem;

pub struct PaginaClienteAutoCompleteItensItem {
    pub email: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### SincronizacaoClientes [#tipo-sincronizacaoclientes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SincronizacaoClientes } from "termo_core/portal";

export interface SincronizacaoClientes {
  cursor?: number | null;
  gravados: number;
  proximo_cursor?: number | null;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::SincronizacaoClientes;

pub struct SincronizacaoClientes {
    pub cursor: Option<i64>,
    pub gravados: i64,
    pub proximo_cursor: Option<i64>,
    pub total: i64,
}
```

</Tab>
</Tabs>

### UnidadeDoCliente [#tipo-unidadedocliente]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UnidadeDoCliente } from "termo_core/portal";

export interface UnidadeDoCliente {
  cnpj: string;
  id: string;
  razao_social: string;
  status?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::UnidadeDoCliente;

pub struct UnidadeDoCliente {
    pub cnpj: String,
    pub id: uuid::Uuid,
    pub razao_social: String,
    pub status: Option<String>,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/portal/colaborador)

> 7 funções do TermoPortal para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista colaboradores paginados |
| [`criar_colaborador`](#criar_colaborador) | `POST /colaborador` | Cadastra o colaborador |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca o colaborador pelo id |
| [`atualizar_pelo_id_colaborador`](#atualizar_pelo_id_colaborador) | `PATCH /colaborador/{id}` | Atualiza o colaborador |
| [`deletar_pelo_id_colaborador`](#deletar_pelo_id_colaborador) | `DELETE /colaborador/{id}` | Exclui o colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista colaboradores paginados

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Exige colaborador interno.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `criar_colaborador` [#criar_colaborador]

<Rota metodo="POST" caminho="/colaborador" credencial />

Cadastra o colaborador

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Exige colaborador interno com `usuarios.gerenciar`. `perfil_id` de colaborador (sem ele vale o perfil `acesso-inicial`, só leitura); só administrador atribui perfil de administrador.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ColaboradorCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_colaborador(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ColaboradorCriar,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_colaborador(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorCriar", typeDescriptionLink: "#tipo-colaboradorcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Exige colaborador interno. Devolve id, nome e e-mail em ordem alfabética; `busca` procura no nome e no e-mail; `tamanho` de 1 a 50 (padrão 10).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Exige colaborador interno. Até 50 por página (`pagina`, a partir de 1, padrão 1), em ordem alfabética; `nome` e `email` procuram o trecho, os demais são exatos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroColaborador { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca o colaborador pelo id

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Exige colaborador interno.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `atualizar_pelo_id_colaborador` [#atualizar_pelo_id_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}" credencial />

Atualiza o colaborador

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Atualização parcial. Exige colaborador interno com `usuarios.gerenciar`; o próprio colaborador só altera nome, telefone, cargo e `presente` (heartbeat que grava `ultimo_acesso_em`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorAtualizar,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorAtualizar", typeDescriptionLink: "#tipo-colaboradoratualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `deletar_pelo_id_colaborador` [#deletar_pelo_id_colaborador]

<Rota metodo="DELETE" caminho="/colaborador/{id}" credencial />

Exclui o colaborador

Colaborador é o usuário da Termotubos: entra pela área `/painel` e também pode abrir o `/app`. Exige colaborador interno com `usuarios.gerenciar`. Exclusão lógica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_colaborador } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/portal";

export interface Colaborador {
  atualizado_em: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  foto_url?: string | null;
  id: string;
  nome: string;
  perfil_id: string;
  perfil_nome: string;
  status: string;
  telefone?: string | null;
  ultimo_acesso_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Colaborador;

pub struct Colaborador {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub foto_url: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub perfil_id: uuid::Uuid,
    pub perfil_nome: String,
    pub status: String,
    pub telefone: Option<String>,
    pub ultimo_acesso_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>

### ColaboradorAtualizar [#tipo-colaboradoratualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorAtualizar } from "termo_core/portal";

export interface ColaboradorAtualizar {
  cargo?: string | null;
  nome?: string | null;
  perfil_id?: string | null;
  presente?: boolean | null;
  status?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ColaboradorAtualizar;

pub struct ColaboradorAtualizar {
    pub cargo: Option<String>,
    pub nome: Option<String>,
    pub perfil_id: Option<uuid::Uuid>,
    pub presente: Option<bool>,
    pub status: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorCriar [#tipo-colaboradorcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorCriar } from "termo_core/portal";

export interface ColaboradorCriar {
  cargo?: string | null;
  email: string;
  nome: string;
  perfil_id?: string | null;
  status?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ColaboradorCriar;

pub struct ColaboradorCriar {
    pub cargo: Option<String>,
    pub email: String,
    pub nome: String,
    pub perfil_id: Option<uuid::Uuid>,
    pub status: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/portal";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/portal";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/portal";

export interface PaginaColaboradorItensItem {
  atualizado_em: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  foto_url?: string | null;
  id: string;
  nome: string;
  perfil_id: string;
  perfil_nome: string;
  status: string;
  telefone?: string | null;
  ultimo_acesso_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub foto_url: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub perfil_id: uuid::Uuid,
    pub perfil_nome: String,
    pub status: String,
    pub telefone: Option<String>,
    pub ultimo_acesso_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/portal/configuracao)

> 7 funções do TermoPortal para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_configuracao`](#buscar_paginador_configuracao) | `GET /configuracao` | Lista as configurações paginadas |
| [`criar_configuracao`](#criar_configuracao) | `POST /configuracao` | Grava uma configuração do portal |
| [`buscar_auto_complete_configuracao`](#buscar_auto_complete_configuracao) | `GET /configuracao/autocomplete` | Lista básica de configurações para seleção |
| [`buscar_pelo_filtro_configuracao`](#buscar_pelo_filtro_configuracao) | `GET /configuracao/filtro` | Busca configurações por filtro |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao/{id}` | Busca uma configuração pelo id |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao/{id}` | Atualiza o valor de uma configuração |
| [`deletar_pelo_id_configuracao`](#deletar_pelo_id_configuracao) | `DELETE /configuracao/{id}` | Exclui uma configuração |

## `buscar_paginador_configuracao` [#buscar_paginador_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Lista as configurações paginadas

Exige só uma sessão válida (qualquer pessoa logada no portal). Ordem de chave. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorConfiguracao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfiguracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_configuracao(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorConfiguracao,
) -> Result<tipos::PaginaConfiguracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_configuracao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorConfiguracao { pagina: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfiguracao>` · Rust: `Result<tipos::PaginaConfiguracao, ErroAoChamarServico>` · veja [`PaginaConfiguracao`](#tipo-paginaconfiguracao).

## `criar_configuracao` [#criar_configuracao]

<Rota metodo="POST" caminho="/configuracao" credencial />

Grava uma configuração do portal

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Configuração chave/valor do portal (vitrine). `chave` precisa ser uma das chaves conhecidas (ex.: `produtos_mostrar_preco`) e `valor` (texto) segue o tipo da chave: booleano `true`/`false`, hora `HH:MM`, decimal ou texto com limite. Cada chave existe uma vez só.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoCriar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoCriar", typeDescriptionLink: "#tipo-configuracaocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `buscar_auto_complete_configuracao` [#buscar_auto_complete_configuracao]

<Rota metodo="GET" caminho="/configuracao/autocomplete" credencial />

Lista básica de configurações para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve só id e chave, em ordem de chave. `busca` procura o trecho na chave. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConfiguracao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfiguracaoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_configuracao(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConfiguracao,
) -> Result<tipos::PaginaConfiguracaoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_configuracao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteConfiguracao { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfiguracaoAutoComplete>` · Rust: `Result<tipos::PaginaConfiguracaoAutoComplete, ErroAoChamarServico>` · veja [`PaginaConfiguracaoAutoComplete`](#tipo-paginaconfiguracaoautocomplete).

## `buscar_pelo_filtro_configuracao` [#buscar_pelo_filtro_configuracao]

<Rota metodo="GET" caminho="/configuracao/filtro" credencial />

Busca configurações por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve as configurações não excluídas que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), em ordem de chave. `chave` é exata; `prefixo` pega as chaves que começam com o texto (ex.: `produtos_`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroConfiguracao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Configuracao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_configuracao(credencial_de_acesso, { chave: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroConfiguracao,
) -> Result<Vec<tipos::Configuracao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_configuracao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroConfiguracao { chave: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.chave": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.prefixo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Configuracao>>` · Rust: `Result<Vec<tipos::Configuracao>, ErroAoChamarServico>`

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao/{id}" credencial />

Busca uma configuração pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Configuração excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_configuracao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao/{id}" credencial />

Atualiza o valor de uma configuração

Exige a permissão `editar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Troca o `valor`, validado pelo tipo da chave.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `deletar_pelo_id_configuracao` [#deletar_pelo_id_configuracao]

<Rota metodo="DELETE" caminho="/configuracao/{id}" credencial />

Exclui uma configuração

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_configuracao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_configuracao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_configuracao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/portal";

export interface Configuracao {
  atualizado_em: string;
  chave: string;
  criado_em: string;
  id: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Configuracao;

pub struct Configuracao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chave: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub valor: String,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/portal";

export interface ConfiguracaoAtualizar {
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub valor: String,
}
```

</Tab>
</Tabs>

### ConfiguracaoCriar [#tipo-configuracaocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoCriar } from "termo_core/portal";

export interface ConfiguracaoCriar {
  chave: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ConfiguracaoCriar;

pub struct ConfiguracaoCriar {
    pub chave: String,
    pub valor: String,
}
```

</Tab>
</Tabs>

### PaginaConfiguracao [#tipo-paginaconfiguracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfiguracao } from "termo_core/portal";

export interface PaginaConfiguracao {
  itens: Array<PaginaConfiguracaoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaConfiguracao;

pub struct PaginaConfiguracao {
    pub itens: Vec<PaginaConfiguracaoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfiguracaoAutoComplete [#tipo-paginaconfiguracaoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfiguracaoAutoComplete } from "termo_core/portal";

export interface PaginaConfiguracaoAutoComplete {
  itens: Array<PaginaConfiguracaoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaConfiguracaoAutoComplete;

pub struct PaginaConfiguracaoAutoComplete {
    pub itens: Vec<PaginaConfiguracaoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfiguracaoAutoCompleteItensItem [#tipo-paginaconfiguracaoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfiguracaoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaConfiguracaoAutoCompleteItensItem {
  chave: string;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaConfiguracaoAutoCompleteItensItem;

pub struct PaginaConfiguracaoAutoCompleteItensItem {
    pub chave: String,
    pub id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PaginaConfiguracaoItensItem [#tipo-paginaconfiguracaoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfiguracaoItensItem } from "termo_core/portal";

export interface PaginaConfiguracaoItensItem {
  atualizado_em: string;
  chave: string;
  criado_em: string;
  id: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaConfiguracaoItensItem;

pub struct PaginaConfiguracaoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chave: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub valor: String,
}
```

</Tab>
</Tabs>


# Configuração provedor (/docs/servicos/portal/configuracao_provedor)

> 2 funções do TermoPortal para configuração provedor.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao_provedor`](#buscar_pelo_id_configuracao_provedor) | `GET /configuracao_provedor` | Mostra a situação do segredo do app gerado no TermoAuth |
| [`atualizar_pelo_id_configuracao_provedor`](#atualizar_pelo_id_configuracao_provedor) | `PATCH /configuracao_provedor` | Grava ou limpa o segredo do app gerado no TermoAuth |

## `buscar_pelo_id_configuracao_provedor` [#buscar_pelo_id_configuracao_provedor]

<Rota metodo="GET" caminho="/configuracao_provedor" credencial />

Mostra a situação do segredo do app gerado no TermoAuth

Só um master do TermoAuth (e-mail `@termotubos.com.br`) lê. Nunca devolve o valor: `segredo_do_app_gerado_no_termo_auth` traz só `configurado` e o final mascarado (`final_visivel`). `criptografia_disponivel` é falso quando o servidor está sem a `GLOBAL_SECRET_CRIPTOGRAFIA`; nesse caso o segredo aparece como não configurado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao_provedor(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfiguracaoProvedor>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao_provedor } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao_provedor(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao_provedor(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::ConfiguracaoProvedor, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_configuracao_provedor(
    &credencial_de_acesso,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfiguracaoProvedor>` · Rust: `Result<tipos::ConfiguracaoProvedor, ErroAoChamarServico>` · veja [`ConfiguracaoProvedor`](#tipo-configuracaoprovedor).

## `atualizar_pelo_id_configuracao_provedor` [#atualizar_pelo_id_configuracao_provedor]

<Rota metodo="PATCH" caminho="/configuracao_provedor" credencial />

Grava ou limpa o segredo do app gerado no TermoAuth

Só um master do TermoAuth (e-mail `@termotubos.com.br`) grava. O segredo do app `portal-b2b` é guardado cifrado (AES-256-GCM com a `GLOBAL_SECRET_CRIPTOGRAFIA`) e entregue na hora ao `termo_core`, sem deploy. Campo ausente não muda nada, texto troca o segredo e `null` (ou texto vazio) limpa. No máximo 2.000 caracteres, sem quebra de linha.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao_provedor(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoProvedorAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfiguracaoProvedor>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao_provedor } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao_provedor(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao_provedor(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoProvedorAtualizar,
) -> Result<tipos::ConfiguracaoProvedor, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_configuracao_provedor(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoProvedorAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoProvedorAtualizar", typeDescriptionLink: "#tipo-configuracaoprovedoratualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfiguracaoProvedor>` · Rust: `Result<tipos::ConfiguracaoProvedor, ErroAoChamarServico>` · veja [`ConfiguracaoProvedor`](#tipo-configuracaoprovedor).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ConfiguracaoProvedor [#tipo-configuracaoprovedor]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoProvedor } from "termo_core/portal";

export interface ConfiguracaoProvedor {
  atualizado_em: string;
  atualizado_por?: string | null;
  criptografia_disponivel: boolean;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ConfiguracaoProvedor;

pub struct ConfiguracaoProvedor {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub atualizado_por: Option<String>,
    pub criptografia_disponivel: bool,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoProvedorAtualizar [#tipo-configuracaoprovedoratualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoProvedorAtualizar } from "termo_core/portal";

export interface ConfiguracaoProvedorAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ConfiguracaoProvedorAtualizar;

pub struct ConfiguracaoProvedorAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/portal";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Contato (/docs/servicos/portal/contato)

> 7 funções do TermoPortal para contato.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_contato`](#buscar_paginador_contato) | `GET /contato` | Lista os contatos paginados |
| [`criar_contato`](#criar_contato) | `POST /contato` | Cadastra um contato de unidade |
| [`buscar_auto_complete_contato`](#buscar_auto_complete_contato) | `GET /contato/autocomplete` | Lista básica de contatos para seleção |
| [`buscar_pelo_filtro_contato`](#buscar_pelo_filtro_contato) | `GET /contato/filtro` | Busca contatos por filtro |
| [`buscar_pelo_id_contato`](#buscar_pelo_id_contato) | `GET /contato/{id}` | Busca um contato pelo id |
| [`atualizar_pelo_id_contato`](#atualizar_pelo_id_contato) | `PATCH /contato/{id}` | Atualiza um contato |
| [`deletar_pelo_id_contato`](#deletar_pelo_id_contato) | `DELETE /contato/{id}` | Exclui um contato |

## `buscar_paginador_contato` [#buscar_paginador_contato]

<Rota metodo="GET" caminho="/contato" credencial />

Lista os contatos paginados

Exige só uma sessão válida (qualquer pessoa logada no portal). Ordem alfabética. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_contato(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorContato = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaContato>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_contato(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorContato,
) -> Result<tipos::PaginaContato, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_contato(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorContato { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaContato>` · Rust: `Result<tipos::PaginaContato, ErroAoChamarServico>` · veja [`PaginaContato`](#tipo-paginacontato).

## `criar_contato` [#criar_contato]

<Rota metodo="POST" caminho="/contato" credencial />

Cadastra um contato de unidade

Exige só uma sessão válida (qualquer pessoa logada no portal). Contato de uma unidade cliente. `unidade_id` precisa ser uma unidade da sessão (colaborador interno acessa todas); `nome` obrigatório até 150 caracteres; `cargo` até 120; `email` válido; `telefone` com 10 ou 11 dígitos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_contato(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ContatoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Contato>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_contato(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ContatoCriar,
) -> Result<tipos::Contato, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_contato(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ContatoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ContatoCriar", typeDescriptionLink: "#tipo-contatocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Contato>` · Rust: `Result<tipos::Contato, ErroAoChamarServico>` · veja [`Contato`](#tipo-contato).

## `buscar_auto_complete_contato` [#buscar_auto_complete_contato]

<Rota metodo="GET" caminho="/contato/autocomplete" credencial />

Lista básica de contatos para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve só id e nome, em ordem alfabética. `busca` procura no nome. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_contato(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteContato = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaContatoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_contato(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteContato,
) -> Result<tipos::PaginaContatoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_contato(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteContato { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaContatoAutoComplete>` · Rust: `Result<tipos::PaginaContatoAutoComplete, ErroAoChamarServico>` · veja [`PaginaContatoAutoComplete`](#tipo-paginacontatoautocomplete).

## `buscar_pelo_filtro_contato` [#buscar_pelo_filtro_contato]

<Rota metodo="GET" caminho="/contato/filtro" credencial />

Busca contatos por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve os contatos não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), em ordem alfabética. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `nome` e `email` procuram o trecho.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_contato(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroContato = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Contato>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_contato(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroContato,
) -> Result<Vec<tipos::Contato>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_contato(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroContato { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Contato>>` · Rust: `Result<Vec<tipos::Contato>, ErroAoChamarServico>`

## `buscar_pelo_id_contato` [#buscar_pelo_id_contato]

<Rota metodo="GET" caminho="/contato/{id}" credencial />

Busca um contato pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Contato excluído, ou de unidade fora da sessão, responde 404.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_contato(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Contato>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_contato(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Contato, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_contato(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Contato>` · Rust: `Result<tipos::Contato, ErroAoChamarServico>` · veja [`Contato`](#tipo-contato).

## `atualizar_pelo_id_contato` [#atualizar_pelo_id_contato]

<Rota metodo="PATCH" caminho="/contato/{id}" credencial />

Atualiza um contato

Exige só uma sessão válida (qualquer pessoa logada no portal). Mesmas validações do cadastro. Contato de unidade fora da sessão responde 404. Atualização parcial: campo ausente mantém o valor atual. Campos: `nome` é obrigatório quando enviado (mesmo limite do cadastro); `cargo` até 120 caracteres; `email` precisa ser válido; `telefone` com 10 ou 11 dígitos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_contato(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ContatoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Contato>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_contato(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ContatoAtualizar,
) -> Result<tipos::Contato, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_contato(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ContatoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ContatoAtualizar", typeDescriptionLink: "#tipo-contatoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Contato>` · Rust: `Result<tipos::Contato, ErroAoChamarServico>` · veja [`Contato`](#tipo-contato).

## `deletar_pelo_id_contato` [#deletar_pelo_id_contato]

<Rota metodo="DELETE" caminho="/contato/{id}" credencial />

Exclui um contato

Exige só uma sessão válida (qualquer pessoa logada no portal). Contato de unidade fora da sessão responde 404. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_contato(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_contato } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_contato(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_contato(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_contato(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Contato [#tipo-contato]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Contato } from "termo_core/portal";

export interface Contato {
  atualizado_em: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  id: string;
  nome: string;
  telefone?: string | null;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Contato;

pub struct Contato {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
    pub telefone: Option<String>,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### ContatoAtualizar [#tipo-contatoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContatoAtualizar } from "termo_core/portal";

export interface ContatoAtualizar {
  cargo?: string | null;
  email?: string | null;
  nome?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContatoAtualizar;

pub struct ContatoAtualizar {
    pub cargo: Option<String>,
    pub email: Option<String>,
    pub nome: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ContatoCriar [#tipo-contatocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContatoCriar } from "termo_core/portal";

export interface ContatoCriar {
  cargo?: string | null;
  email: string;
  nome: string;
  telefone?: string | null;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContatoCriar;

pub struct ContatoCriar {
    pub cargo: Option<String>,
    pub email: String,
    pub nome: String,
    pub telefone: Option<String>,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PaginaContato [#tipo-paginacontato]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaContato } from "termo_core/portal";

export interface PaginaContato {
  itens: Array<PaginaContatoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaContato;

pub struct PaginaContato {
    pub itens: Vec<PaginaContatoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaContatoAutoComplete [#tipo-paginacontatoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaContatoAutoComplete } from "termo_core/portal";

export interface PaginaContatoAutoComplete {
  itens: Array<PaginaContatoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaContatoAutoComplete;

pub struct PaginaContatoAutoComplete {
    pub itens: Vec<PaginaContatoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaContatoAutoCompleteItensItem [#tipo-paginacontatoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaContatoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaContatoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaContatoAutoCompleteItensItem;

pub struct PaginaContatoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaContatoItensItem [#tipo-paginacontatoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaContatoItensItem } from "termo_core/portal";

export interface PaginaContatoItensItem {
  atualizado_em: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  id: string;
  nome: string;
  telefone?: string | null;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaContatoItensItem;

pub struct PaginaContatoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
    pub telefone: Option<String>,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>


# Cotação (/docs/servicos/portal/cotacao)

> 7 funções do TermoPortal para cotação.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_cotacao`](#buscar_paginador_cotacao) | `GET /cotacao` | Lista as cotações paginadas |
| [`criar_cotacao`](#criar_cotacao) | `POST /cotacao` | Cria uma cotação (carrinho enviado) |
| [`buscar_auto_complete_cotacao`](#buscar_auto_complete_cotacao) | `GET /cotacao/autocomplete` | Lista básica de cotações para seleção |
| [`buscar_pelo_filtro_cotacao`](#buscar_pelo_filtro_cotacao) | `GET /cotacao/filtro` | Busca cotações por filtro |
| [`buscar_pelo_id_cotacao`](#buscar_pelo_id_cotacao) | `GET /cotacao/{id}` | Busca uma cotação pelo id |
| [`atualizar_pelo_id_cotacao`](#atualizar_pelo_id_cotacao) | `PATCH /cotacao/{id}` | Muda o status de uma cotação |
| [`deletar_pelo_id_cotacao`](#deletar_pelo_id_cotacao) | `DELETE /cotacao/{id}` | Exclui uma cotação |

## `buscar_paginador_cotacao` [#buscar_paginador_cotacao]

<Rota metodo="GET" caminho="/cotacao" credencial />

Lista as cotações paginadas

Exige a permissão `ver` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Das mais novas para as mais antigas; `status` opcional. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCotacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCotacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_cotacao(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCotacao,
) -> Result<tipos::PaginaCotacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_cotacao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorCotacao { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCotacao>` · Rust: `Result<tipos::PaginaCotacao, ErroAoChamarServico>` · veja [`PaginaCotacao`](#tipo-paginacotacao).

## `criar_cotacao` [#criar_cotacao]

<Rota metodo="POST" caminho="/cotacao" credencial />

Cria uma cotação (carrinho enviado)

Exige a permissão `criar` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Monta a cotação no servidor a partir dos itens (`produto_id`, `quantidade` acima de zero e até 9999, `embalagem_fechada`, `preco_unitario` visto pelo cliente), com 1 a 200 itens e sem produto repetido. Recalcula preços por faixa, confere `total_esperado` e grava com o status inicial. A unidade precisa ser da sessão (colaborador interno acessa todas) e, para quem não é colaborador interno, o autor é sempre quem chama. `acima_do_limite` indica que a cotação passa o limite de faturamento da unidade. Campos: `unidade_id` (uuid) é a unidade compradora, da sessão; `autor_cliente_id` é a pessoa autora (uuid; para quem não é colaborador interno vale sempre a própria pessoa); `itens` é a lista de 1 a 200 itens, cada um com `produto_id`, `quantidade`, `embalagem_fechada` e `preco_unitario`; `economia_tier` é a economia do grupo de cliente vista no carrinho (decimal, informativo).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.CotacaoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cotacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_cotacao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::CotacaoCriar,
) -> Result<tipos::Cotacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_cotacao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.CotacaoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::CotacaoCriar", typeDescriptionLink: "#tipo-cotacaocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cotacao>` · Rust: `Result<tipos::Cotacao, ErroAoChamarServico>` · veja [`Cotacao`](#tipo-cotacao).

## `buscar_auto_complete_cotacao` [#buscar_auto_complete_cotacao]

<Rota metodo="GET" caminho="/cotacao/autocomplete" credencial />

Lista básica de cotações para seleção

Exige a permissão `ver` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Devolve id e `rotulo` (unidade, autor e data), em ordem da razão social. `busca` procura na razão social e no autor. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteCotacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCotacaoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_cotacao(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteCotacao,
) -> Result<tipos::PaginaCotacaoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_cotacao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteCotacao { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCotacaoAutoComplete>` · Rust: `Result<tipos::PaginaCotacaoAutoComplete, ErroAoChamarServico>` · veja [`PaginaCotacaoAutoComplete`](#tipo-paginacotacaoautocomplete).

## `buscar_pelo_filtro_cotacao` [#buscar_pelo_filtro_cotacao]

<Rota metodo="GET" caminho="/cotacao/filtro" credencial />

Busca cotações por filtro

Exige a permissão `ver` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Devolve as cotações não excluídas que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), das mais novas para as mais antigas. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `autor_cliente_id` e `status` (`rascunho`, `esperando_aprovacao`, `concluido`, `nao_aprovado`, `em_transporte`) são exatos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroCotacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Cotacao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_cotacao(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroCotacao,
) -> Result<Vec<tipos::Cotacao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_cotacao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroCotacao { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.autor_cliente_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Cotacao>>` · Rust: `Result<Vec<tipos::Cotacao>, ErroAoChamarServico>`

## `buscar_pelo_id_cotacao` [#buscar_pelo_id_cotacao]

<Rota metodo="GET" caminho="/cotacao/{id}" credencial />

Busca uma cotação pelo id

Exige a permissão `ver` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Cotação excluída, ou de unidade fora da sessão, responde 404. Traz itens e totais.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cotacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_cotacao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Cotacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_cotacao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cotacao>` · Rust: `Result<tipos::Cotacao, ErroAoChamarServico>` · veja [`Cotacao`](#tipo-cotacao).

## `atualizar_pelo_id_cotacao` [#atualizar_pelo_id_cotacao]

<Rota metodo="PATCH" caminho="/cotacao/{id}" credencial />

Muda o status de uma cotação

Exige a permissão `editar` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Muda `status` (`rascunho`, `esperando_aprovacao`, `concluido`, `nao_aprovado`, `em_transporte`). Só colaborador interno marca `concluido` ou `em_transporte`; aprovar cotação acima do limite de faturamento exige `confirmar_acima_do_limite: true`. Cotação de unidade fora da sessão responde 404. Atualização parcial: campo ausente mantém o valor atual. Campos: `confirmar_acima_do_limite` (booleano) confirma o aviso de limite de faturamento ao aprovar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.CotacaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cotacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_cotacao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::CotacaoAtualizar,
) -> Result<tipos::Cotacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_cotacao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.CotacaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::CotacaoAtualizar", typeDescriptionLink: "#tipo-cotacaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cotacao>` · Rust: `Result<tipos::Cotacao, ErroAoChamarServico>` · veja [`Cotacao`](#tipo-cotacao).

## `deletar_pelo_id_cotacao` [#deletar_pelo_id_cotacao]

<Rota metodo="DELETE" caminho="/cotacao/{id}" credencial />

Exclui uma cotação

Exige a permissão `excluir` no módulo `Cotacoes` do perfil de quem chama (administrador e master têm tudo). Cotação de unidade fora da sessão responde 404. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_cotacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_cotacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_cotacao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_cotacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_cotacao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Cotacao [#tipo-cotacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cotacao } from "termo_core/portal";

export interface Cotacao {
  acima_do_limite: boolean;
  atualizado_em: string;
  autor_cliente_id: string;
  autor_nome: string;
  criado_em: string;
  desconto: number;
  economia_tier?: number | null;
  id: string;
  itens: Array<CotacaoItem>;
  quantidade_itens: number;
  status: string;
  subtotal: number;
  total: number;
  total_skus: number;
  unidade_id: string;
  unidade_razao_social: string;
  valor_frete: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Cotacao;

pub struct Cotacao {
    pub acima_do_limite: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub autor_cliente_id: uuid::Uuid,
    pub autor_nome: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub desconto: f64,
    pub economia_tier: Option<f64>,
    pub id: uuid::Uuid,
    pub itens: Vec<CotacaoItem>,
    pub quantidade_itens: f64,
    pub status: String,
    pub subtotal: f64,
    pub total: f64,
    pub total_skus: i32,
    pub unidade_id: uuid::Uuid,
    pub unidade_razao_social: String,
    pub valor_frete: f64,
}
```

</Tab>
</Tabs>

### CotacaoAtualizar [#tipo-cotacaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CotacaoAtualizar } from "termo_core/portal";

export interface CotacaoAtualizar {
  confirmar_acima_do_limite?: boolean | null;
  status?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CotacaoAtualizar;

pub struct CotacaoAtualizar {
    pub confirmar_acima_do_limite: Option<bool>,
    pub status: Option<String>,
}
```

</Tab>
</Tabs>

### CotacaoCriar [#tipo-cotacaocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CotacaoCriar } from "termo_core/portal";

export interface CotacaoCriar {
  autor_cliente_id: string;
  economia_tier?: number | null;
  itens: Array<CotacaoItemCriar>;
  total_esperado?: number | null;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CotacaoCriar;

pub struct CotacaoCriar {
    pub autor_cliente_id: uuid::Uuid,
    pub economia_tier: Option<f64>,
    pub itens: Vec<CotacaoItemCriar>,
    pub total_esperado: Option<f64>,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### CotacaoItem [#tipo-cotacaoitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CotacaoItem } from "termo_core/portal";

export interface CotacaoItem {
  embalagem_fechada: boolean;
  imagem_url?: string | null;
  incremento_minimo: number;
  nome: string;
  preco_unitario: number;
  produto_id: string;
  quantidade: number;
  quantidade_minima: number;
  sku: string;
  unidade: string;
  unidade_medida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CotacaoItem;

pub struct CotacaoItem {
    pub embalagem_fechada: bool,
    pub imagem_url: Option<String>,
    pub incremento_minimo: f64,
    pub nome: String,
    pub preco_unitario: f64,
    pub produto_id: uuid::Uuid,
    pub quantidade: f64,
    pub quantidade_minima: f64,
    pub sku: String,
    pub unidade: String,
    pub unidade_medida: String,
}
```

</Tab>
</Tabs>

### CotacaoItemCriar [#tipo-cotacaoitemcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CotacaoItemCriar } from "termo_core/portal";

export interface CotacaoItemCriar {
  embalagem_fechada?: boolean | null;
  preco_unitario?: number | null;
  produto_id: string;
  quantidade: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CotacaoItemCriar;

pub struct CotacaoItemCriar {
    pub embalagem_fechada: Option<bool>,
    pub preco_unitario: Option<f64>,
    pub produto_id: uuid::Uuid,
    pub quantidade: f64,
}
```

</Tab>
</Tabs>

### PaginaCotacao [#tipo-paginacotacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCotacao } from "termo_core/portal";

export interface PaginaCotacao {
  itens: Array<PaginaCotacaoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCotacao;

pub struct PaginaCotacao {
    pub itens: Vec<PaginaCotacaoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaCotacaoAutoComplete [#tipo-paginacotacaoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCotacaoAutoComplete } from "termo_core/portal";

export interface PaginaCotacaoAutoComplete {
  itens: Array<PaginaCotacaoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCotacaoAutoComplete;

pub struct PaginaCotacaoAutoComplete {
    pub itens: Vec<PaginaCotacaoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaCotacaoAutoCompleteItensItem [#tipo-paginacotacaoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCotacaoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaCotacaoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCotacaoAutoCompleteItensItem;

pub struct PaginaCotacaoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaCotacaoItensItem [#tipo-paginacotacaoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCotacaoItensItem } from "termo_core/portal";

export interface PaginaCotacaoItensItem {
  acima_do_limite: boolean;
  atualizado_em: string;
  autor_cliente_id: string;
  autor_nome: string;
  criado_em: string;
  desconto: number;
  economia_tier?: number | null;
  id: string;
  itens: Array<CotacaoItem>;
  quantidade_itens: number;
  status: string;
  subtotal: number;
  total: number;
  total_skus: number;
  unidade_id: string;
  unidade_razao_social: string;
  valor_frete: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaCotacaoItensItem;

pub struct PaginaCotacaoItensItem {
    pub acima_do_limite: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub autor_cliente_id: uuid::Uuid,
    pub autor_nome: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub desconto: f64,
    pub economia_tier: Option<f64>,
    pub id: uuid::Uuid,
    pub itens: Vec<CotacaoItem>,
    pub quantidade_itens: f64,
    pub status: String,
    pub subtotal: f64,
    pub total: f64,
    pub total_skus: i32,
    pub unidade_id: uuid::Uuid,
    pub unidade_razao_social: String,
    pub valor_frete: f64,
}
```

</Tab>
</Tabs>


# Dashboards (/docs/servicos/portal/dashboards)

> 1 função do TermoPortal para dashboards.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`painel_buscar_top_empresas_pedido_dashboards`](#painel_buscar_top_empresas_pedido_dashboards) | `GET /dashboards/painel/top_empresas_pedido` | As 10 empresas que mais enviaram pedidos no período |

## `painel_buscar_top_empresas_pedido_dashboards` [#painel_buscar_top_empresas_pedido_dashboards]

<Rota metodo="GET" caminho="/dashboards/painel/top_empresas_pedido" credencial />

As 10 empresas que mais enviaram pedidos no período

Dashboard do painel: só colaborador interno com o módulo Dashboard. Conta os pedidos de venda do Tiny (`pedido_venda_tiny`, sem os cancelados) de cada empresa (a unidade do pedido; sem unidade, o documento ou o nome do cliente) com a data entre `inicio` e `fim` (hoje, no horário de Brasília). `periodo`: `dia` (hoje), `semana` (desde segunda), `semestre` (desde 1º de janeiro ou 1º de julho) ou `ano` (desde 1º de janeiro); sem ele, `semana`. Ordem: mais pedidos, depois maior valor. `total_pedidos` e `total_empresas` são de todas as empresas do período, não só das 10. O resultado fica 30 minutos em cache na memória do backend (`atualizado_em` e `proxima_atualizacao_em`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function painel_buscar_top_empresas_pedido_dashboards(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDePainelBuscarTopEmpresasPedidoDashboards = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TopEmpresasPedido>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { painel_buscar_top_empresas_pedido_dashboards } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await painel_buscar_top_empresas_pedido_dashboards(credencial_de_acesso, { periodo: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn painel_buscar_top_empresas_pedido_dashboards(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDePainelBuscarTopEmpresasPedidoDashboards,
) -> Result<tipos::TopEmpresasPedido, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::painel_buscar_top_empresas_pedido_dashboards(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDePainelBuscarTopEmpresasPedidoDashboards { periodo: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.periodo": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TopEmpresasPedido>` · Rust: `Result<tipos::TopEmpresasPedido, ErroAoChamarServico>` · veja [`TopEmpresasPedido`](#tipo-topempresaspedido).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### TopEmpresaPedido [#tipo-topempresapedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TopEmpresaPedido } from "termo_core/portal";

export interface TopEmpresaPedido {
  documento?: string | null;
  nome: string;
  posicao: number;
  quantidade_pedidos: number;
  unidade_id?: string | null;
  valor_total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::TopEmpresaPedido;

pub struct TopEmpresaPedido {
    pub documento: Option<String>,
    pub nome: String,
    pub posicao: i64,
    pub quantidade_pedidos: i64,
    pub unidade_id: Option<uuid::Uuid>,
    pub valor_total: f64,
}
```

</Tab>
</Tabs>

### TopEmpresasPedido [#tipo-topempresaspedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TopEmpresasPedido } from "termo_core/portal";

export interface TopEmpresasPedido {
  atualizado_em: string;
  empresas: Array<TopEmpresaPedido>;
  fim: string;
  inicio: string;
  periodo: string;
  proxima_atualizacao_em: string;
  total_empresas: number;
  total_pedidos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::TopEmpresasPedido;

pub struct TopEmpresasPedido {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub empresas: Vec<TopEmpresaPedido>,
    pub fim: chrono::NaiveDate,
    pub inicio: chrono::NaiveDate,
    pub periodo: String,
    pub proxima_atualizacao_em: chrono::DateTime<chrono::Utc>,
    pub total_empresas: i64,
    pub total_pedidos: i64,
}
```

</Tab>
</Tabs>


# Endereço (/docs/servicos/portal/endereco)

> 7 funções do TermoPortal para endereço.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_endereco`](#buscar_paginador_endereco) | `GET /endereco` | Lista os endereços paginados |
| [`criar_endereco`](#criar_endereco) | `POST /endereco` | Cadastra um endereço de unidade |
| [`buscar_auto_complete_endereco`](#buscar_auto_complete_endereco) | `GET /endereco/autocomplete` | Lista básica de endereços para seleção |
| [`buscar_pelo_filtro_endereco`](#buscar_pelo_filtro_endereco) | `GET /endereco/filtro` | Busca endereços por filtro |
| [`buscar_pelo_id_endereco`](#buscar_pelo_id_endereco) | `GET /endereco/{id}` | Busca um endereço pelo id |
| [`atualizar_pelo_id_endereco`](#atualizar_pelo_id_endereco) | `PATCH /endereco/{id}` | Atualiza um endereço |
| [`deletar_pelo_id_endereco`](#deletar_pelo_id_endereco) | `DELETE /endereco/{id}` | Exclui um endereço |

## `buscar_paginador_endereco` [#buscar_paginador_endereco]

<Rota metodo="GET" caminho="/endereco" credencial />

Lista os endereços paginados

Exige só uma sessão válida (qualquer pessoa logada no portal). Ordem: tipo, data de cadastro. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorEndereco = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEndereco>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_endereco(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorEndereco,
) -> Result<tipos::PaginaEndereco, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_endereco(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorEndereco { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEndereco>` · Rust: `Result<tipos::PaginaEndereco, ErroAoChamarServico>` · veja [`PaginaEndereco`](#tipo-paginaendereco).

## `criar_endereco` [#criar_endereco]

<Rota metodo="POST" caminho="/endereco" credencial />

Cadastra um endereço de unidade

Exige só uma sessão válida (qualquer pessoa logada no portal). Endereço de uma unidade cliente. `unidade_id` precisa ser uma unidade da sessão (colaborador interno acessa todas); `tipo` é `entrega` ou `cobranca` (no máximo um de cobrança por unidade); `cep` com 8 dígitos; `logradouro` e `cidade` obrigatórios; `estado` é a sigla da UF. Campos: `apelido` até 60 caracteres; `numero` até 20 caracteres; `complemento` até 120 caracteres; `bairro` até 120 caracteres.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.EnderecoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Endereco>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_endereco(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::EnderecoCriar,
) -> Result<tipos::Endereco, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_endereco(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.EnderecoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EnderecoCriar", typeDescriptionLink: "#tipo-enderecocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Endereco>` · Rust: `Result<tipos::Endereco, ErroAoChamarServico>` · veja [`Endereco`](#tipo-endereco).

## `buscar_auto_complete_endereco` [#buscar_auto_complete_endereco]

<Rota metodo="GET" caminho="/endereco/autocomplete" credencial />

Lista básica de endereços para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve id e `rotulo` (apelido ou logradouro com cidade), em ordem alfabética. `busca` procura no endereço; `tipo` filtra. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteEndereco = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEnderecoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_endereco(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteEndereco,
) -> Result<tipos::PaginaEnderecoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_endereco(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteEndereco { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEnderecoAutoComplete>` · Rust: `Result<tipos::PaginaEnderecoAutoComplete, ErroAoChamarServico>` · veja [`PaginaEnderecoAutoComplete`](#tipo-paginaenderecoautocomplete).

## `buscar_pelo_filtro_endereco` [#buscar_pelo_filtro_endereco]

<Rota metodo="GET" caminho="/endereco/filtro" credencial />

Busca endereços por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve os endereços não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), por tipo e data de cadastro. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `tipo` (`entrega` ou `cobranca`) e `cep` (só dígitos) são exatos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroEndereco = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Endereco>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_endereco(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroEndereco,
) -> Result<Vec<tipos::Endereco>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_endereco(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroEndereco { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cep": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Endereco>>` · Rust: `Result<Vec<tipos::Endereco>, ErroAoChamarServico>`

## `buscar_pelo_id_endereco` [#buscar_pelo_id_endereco]

<Rota metodo="GET" caminho="/endereco/{id}" credencial />

Busca um endereço pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Endereço excluído, ou de unidade fora da sessão, responde 404.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Endereco>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_endereco(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Endereco, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_endereco(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Endereco>` · Rust: `Result<tipos::Endereco, ErroAoChamarServico>` · veja [`Endereco`](#tipo-endereco).

## `atualizar_pelo_id_endereco` [#atualizar_pelo_id_endereco]

<Rota metodo="PATCH" caminho="/endereco/{id}" credencial />

Atualiza um endereço

Exige só uma sessão válida (qualquer pessoa logada no portal). Mesmas validações do cadastro; a unidade não muda. Endereço de unidade fora da sessão responde 404. Atualização parcial: campo ausente mantém o valor atual. Campos: `tipo` é `entrega` ou `cobranca`; `apelido` até 60 caracteres; `cep` com 8 dígitos; `logradouro` até 200 caracteres; `numero` até 20 caracteres; `complemento` até 120 caracteres; `bairro` até 120 caracteres; `cidade` até 120 caracteres; `estado` é a sigla da UF.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.EnderecoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Endereco>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_endereco(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::EnderecoAtualizar,
) -> Result<tipos::Endereco, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_endereco(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.EnderecoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EnderecoAtualizar", typeDescriptionLink: "#tipo-enderecoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Endereco>` · Rust: `Result<tipos::Endereco, ErroAoChamarServico>` · veja [`Endereco`](#tipo-endereco).

## `deletar_pelo_id_endereco` [#deletar_pelo_id_endereco]

<Rota metodo="DELETE" caminho="/endereco/{id}" credencial />

Exclui um endereço

Exige só uma sessão válida (qualquer pessoa logada no portal). Endereço de unidade fora da sessão responde 404. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_endereco(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_endereco } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_endereco(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_endereco(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_endereco(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Endereco [#tipo-endereco]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Endereco } from "termo_core/portal";

export interface Endereco {
  apelido?: string | null;
  atualizado_em: string;
  bairro?: string | null;
  cep: string;
  cidade: string;
  complemento?: string | null;
  criado_em: string;
  estado: string;
  id: string;
  logradouro: string;
  numero?: string | null;
  tipo: string;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Endereco;

pub struct Endereco {
    pub apelido: Option<String>,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bairro: Option<String>,
    pub cep: String,
    pub cidade: String,
    pub complemento: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub estado: String,
    pub id: uuid::Uuid,
    pub logradouro: String,
    pub numero: Option<String>,
    pub tipo: String,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### EnderecoAtualizar [#tipo-enderecoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EnderecoAtualizar } from "termo_core/portal";

export interface EnderecoAtualizar {
  apelido?: string | null;
  bairro?: string | null;
  cep?: string | null;
  cidade?: string | null;
  complemento?: string | null;
  estado?: string | null;
  logradouro?: string | null;
  numero?: string | null;
  tipo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::EnderecoAtualizar;

pub struct EnderecoAtualizar {
    pub apelido: Option<String>,
    pub bairro: Option<String>,
    pub cep: Option<String>,
    pub cidade: Option<String>,
    pub complemento: Option<String>,
    pub estado: Option<String>,
    pub logradouro: Option<String>,
    pub numero: Option<String>,
    pub tipo: Option<String>,
}
```

</Tab>
</Tabs>

### EnderecoCriar [#tipo-enderecocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EnderecoCriar } from "termo_core/portal";

export interface EnderecoCriar {
  apelido?: string | null;
  bairro?: string | null;
  cep: string;
  cidade: string;
  complemento?: string | null;
  estado: string;
  logradouro: string;
  numero?: string | null;
  tipo: string;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::EnderecoCriar;

pub struct EnderecoCriar {
    pub apelido: Option<String>,
    pub bairro: Option<String>,
    pub cep: String,
    pub cidade: String,
    pub complemento: Option<String>,
    pub estado: String,
    pub logradouro: String,
    pub numero: Option<String>,
    pub tipo: String,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PaginaEndereco [#tipo-paginaendereco]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEndereco } from "termo_core/portal";

export interface PaginaEndereco {
  itens: Array<PaginaEnderecoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaEndereco;

pub struct PaginaEndereco {
    pub itens: Vec<PaginaEnderecoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEnderecoAutoComplete [#tipo-paginaenderecoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEnderecoAutoComplete } from "termo_core/portal";

export interface PaginaEnderecoAutoComplete {
  itens: Array<PaginaEnderecoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaEnderecoAutoComplete;

pub struct PaginaEnderecoAutoComplete {
    pub itens: Vec<PaginaEnderecoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEnderecoAutoCompleteItensItem [#tipo-paginaenderecoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEnderecoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaEnderecoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaEnderecoAutoCompleteItensItem;

pub struct PaginaEnderecoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaEnderecoItensItem [#tipo-paginaenderecoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEnderecoItensItem } from "termo_core/portal";

export interface PaginaEnderecoItensItem {
  apelido?: string | null;
  atualizado_em: string;
  bairro?: string | null;
  cep: string;
  cidade: string;
  complemento?: string | null;
  criado_em: string;
  estado: string;
  id: string;
  logradouro: string;
  numero?: string | null;
  tipo: string;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaEnderecoItensItem;

pub struct PaginaEnderecoItensItem {
    pub apelido: Option<String>,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bairro: Option<String>,
    pub cep: String,
    pub cidade: String,
    pub complemento: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub estado: String,
    pub id: uuid::Uuid,
    pub logradouro: String,
    pub numero: Option<String>,
    pub tipo: String,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>


# Expedição (/docs/servicos/portal/expedicao)

> 3 funções do TermoPortal para expedição.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_expedicao`](#buscar_paginador_expedicao) | `GET /expedicao` | Lista as entregas (expedições) do ERP |
| [`buscar_auto_complete_expedicao`](#buscar_auto_complete_expedicao) | `GET /expedicao/autocomplete` | Lista transportadoras ou vendedores das entregas |
| [`buscar_pelo_id_expedicao`](#buscar_pelo_id_expedicao) | `GET /expedicao/{id}` | Busca uma entrega pelo id do ERP |

## `buscar_paginador_expedicao` [#buscar_paginador_expedicao]

<Rota metodo="GET" caminho="/expedicao" credencial />

Lista as entregas (expedições) do ERP

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Consulta na hora a API de logística da Termotubos (notas expedidas pelo Tiny). Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só vê as entregas do CNPJ dela, sem dados do vendedor; colaborador interno pode omitir e ver todas. Filtros: `situacao` (`todas`, `aguardando`, `transito`, `entregue`, `atrasada`; padrão `todas`), `busca` (texto), `inicio` e `fim` (AAAA-MM-DD, data de emissão), `transportadora` (CNPJ) e `vendedor` (id do vendedor no Tiny). 50 entregas por página; `pagina` começa em 1. A resposta traz `itens`, `pagina`, `total_paginas`, `total_registros`, a contagem por situação e um resumo (notas de hoje, entregues no mês, próxima entrega). Até 60 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_expedicao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorExpedicao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaExpedicoes>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_expedicao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_expedicao(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_expedicao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorExpedicao,
) -> Result<tipos::PaginaExpedicoes, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_expedicao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorExpedicao { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaExpedicoes>` · Rust: `Result<tipos::PaginaExpedicoes, ErroAoChamarServico>` · veja [`PaginaExpedicoes`](#tipo-paginaexpedicoes).

## `buscar_auto_complete_expedicao` [#buscar_auto_complete_expedicao]

<Rota metodo="GET" caminho="/expedicao/autocomplete" credencial />

Lista transportadoras ou vendedores das entregas

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Opções para os filtros da tela de entregas, tiradas da API de logística (no máximo 50, da mais usada para a menos usada): `tipo` `transportadora` ou `vendedor` (vendedor só para colaborador interno). Cada opção traz `valor` (CNPJ da transportadora ou id do vendedor), `rotulo` e a quantidade de `entregas`. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão. Lista inteira, sem paginação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_expedicao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteExpedicao,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.OpcaoDeFiltro>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_expedicao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_expedicao(credencial_de_acesso, { tipo });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_expedicao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteExpedicao,
) -> Result<Vec<tipos::OpcaoDeFiltro>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_expedicao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteExpedicao { tipo, ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tipo": { type: "string", required: true, description: "Rust: String" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.OpcaoDeFiltro>>` · Rust: `Result<Vec<tipos::OpcaoDeFiltro>, ErroAoChamarServico>`

## `buscar_pelo_id_expedicao` [#buscar_pelo_id_expedicao]

<Rota metodo="GET" caminho="/expedicao/{id}" credencial />

Busca uma entrega pelo id do ERP

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Consulta a entrega na API de logística (nota, transportadora, previsão, rastreio, ocorrência). Quem não é colaborador interno só abre entregas do CNPJ das próprias unidades (as outras respondem 404) e não recebe os dados do vendedor.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_expedicao(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ExpedicaoTermotubos>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_expedicao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_expedicao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_expedicao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::ExpedicaoTermotubos, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_expedicao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ExpedicaoTermotubos>` · Rust: `Result<tipos::ExpedicaoTermotubos, ErroAoChamarServico>` · veja [`ExpedicaoTermotubos`](#tipo-expedicaotermotubos).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ContagemExpedicoes [#tipo-contagemexpedicoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContagemExpedicoes } from "termo_core/portal";

export interface ContagemExpedicoes {
  aguardando: number;
  atrasadas: number;
  entregues: number;
  todas: number;
  transito: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContagemExpedicoes;

pub struct ContagemExpedicoes {
    pub aguardando: i64,
    pub atrasadas: i64,
    pub entregues: i64,
    pub todas: i64,
    pub transito: i64,
}
```

</Tab>
</Tabs>

### ExpedicaoTermotubos [#tipo-expedicaotermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ExpedicaoTermotubos } from "termo_core/portal";

export interface ExpedicaoTermotubos {
  atualizado_em?: string | null;
  cep?: string | null;
  cidade?: string | null;
  cliente?: string | null;
  cliente_documento?: string | null;
  codigo_rastreio?: string | null;
  emissao?: string | null;
  entrega?: string | null;
  envio?: string | null;
  frete?: number | null;
  id: number;
  link_rastreio?: string | null;
  nota_fiscal?: number | null;
  nota_tiny_id?: number | null;
  ocorrencia?: string | null;
  peso_kg?: number | null;
  previsao?: string | null;
  situacao?: string | null;
  situacao_id?: number | null;
  transportadora?: string | null;
  transportadora_documento?: string | null;
  uf?: string | null;
  valor_mercadorias?: number | null;
  valor_nota?: number | null;
  vendedor?: string | null;
  vendedor_tiny_id?: number | null;
  volumes?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ExpedicaoTermotubos;

pub struct ExpedicaoTermotubos {
    pub atualizado_em: Option<String>,
    pub cep: Option<String>,
    pub cidade: Option<String>,
    pub cliente: Option<String>,
    pub cliente_documento: Option<String>,
    pub codigo_rastreio: Option<String>,
    pub emissao: Option<String>,
    pub entrega: Option<String>,
    pub envio: Option<String>,
    pub frete: Option<f64>,
    pub id: i64,
    pub link_rastreio: Option<String>,
    pub nota_fiscal: Option<i64>,
    pub nota_tiny_id: Option<i64>,
    pub ocorrencia: Option<String>,
    pub peso_kg: Option<f64>,
    pub previsao: Option<String>,
    pub situacao: Option<String>,
    pub situacao_id: Option<i64>,
    pub transportadora: Option<String>,
    pub transportadora_documento: Option<String>,
    pub uf: Option<String>,
    pub valor_mercadorias: Option<f64>,
    pub valor_nota: Option<f64>,
    pub vendedor: Option<String>,
    pub vendedor_tiny_id: Option<i64>,
    pub volumes: Option<i64>,
}
```

</Tab>
</Tabs>

### OpcaoDeFiltro [#tipo-opcaodefiltro]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { OpcaoDeFiltro } from "termo_core/portal";

export interface OpcaoDeFiltro {
  entregas: number;
  rotulo: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::OpcaoDeFiltro;

pub struct OpcaoDeFiltro {
    pub entregas: i64,
    pub rotulo: String,
    pub valor: String,
}
```

</Tab>
</Tabs>

### PaginaExpedicoes [#tipo-paginaexpedicoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaExpedicoes } from "termo_core/portal";

export interface PaginaExpedicoes {
  contagens: ContagemExpedicoes;
  itens: Array<ExpedicaoTermotubos>;
  pagina: number;
  resumo: ResumoExpedicoes;
  total_paginas: number;
  total_registros: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaExpedicoes;

pub struct PaginaExpedicoes {
    pub contagens: ContagemExpedicoes,
    pub itens: Vec<ExpedicaoTermotubos>,
    pub pagina: i32,
    pub resumo: ResumoExpedicoes,
    pub total_paginas: i32,
    pub total_registros: i64,
}
```

</Tab>
</Tabs>

### ResumoExpedicoes [#tipo-resumoexpedicoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResumoExpedicoes } from "termo_core/portal";

export interface ResumoExpedicoes {
  entregues_no_mes: number;
  notas_hoje: number;
  proxima_entrega?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ResumoExpedicoes;

pub struct ResumoExpedicoes {
    pub entregues_no_mes: i64,
    pub notas_hoje: i64,
    pub proxima_entrega: Option<String>,
}
```

</Tab>
</Tabs>


# Fatura (/docs/servicos/portal/fatura)

> 7 funções do TermoPortal para fatura.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_fatura`](#buscar_paginador_fatura) | `GET /fatura` | Lista as faturas paginadas |
| [`criar_fatura`](#criar_fatura) | `POST /fatura` | Cadastra uma fatura |
| [`buscar_auto_complete_fatura`](#buscar_auto_complete_fatura) | `GET /fatura/autocomplete` | Lista básica de faturas para seleção |
| [`buscar_pelo_filtro_fatura`](#buscar_pelo_filtro_fatura) | `GET /fatura/filtro` | Busca faturas por filtro |
| [`buscar_pelo_id_fatura`](#buscar_pelo_id_fatura) | `GET /fatura/{id}` | Busca uma fatura pelo id |
| [`atualizar_pelo_id_fatura`](#atualizar_pelo_id_fatura) | `PATCH /fatura/{id}` | Atualiza uma fatura |
| [`deletar_pelo_id_fatura`](#deletar_pelo_id_fatura) | `DELETE /fatura/{id}` | Exclui uma fatura |

## `buscar_paginador_fatura` [#buscar_paginador_fatura]

<Rota metodo="GET" caminho="/fatura" credencial />

Lista as faturas paginadas

Exige a permissão `ver` no módulo `Financeiro` do perfil de quem chama (administrador e master têm tudo). Do vencimento mais recente para o mais antigo. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorFatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_fatura(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorFatura,
) -> Result<tipos::PaginaFatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_fatura(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorFatura { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFatura>` · Rust: `Result<tipos::PaginaFatura, ErroAoChamarServico>` · veja [`PaginaFatura`](#tipo-paginafatura).

## `criar_fatura` [#criar_fatura]

<Rota metodo="POST" caminho="/fatura" credencial />

Cadastra uma fatura

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Fatura (boleto/título) de uma unidade cliente, mostrada no Financeiro do portal. `documento` (até 60 caracteres) é único; `unidade_id` precisa ser da sessão (colaborador interno acessa todas); `pedido_id` opcional precisa ser um pedido da mesma unidade; `vencimento` (AAAA-MM-DD); `valor`; `status_rotulo` (até 60 caracteres, texto exibido) e `tom` (`sucesso`, `alerta`, `perigo`, `informacao` ou `neutro`, a cor do selo).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.FaturaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Fatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_fatura(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::FaturaCriar,
) -> Result<tipos::Fatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_fatura(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.FaturaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::FaturaCriar", typeDescriptionLink: "#tipo-faturacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Fatura>` · Rust: `Result<tipos::Fatura, ErroAoChamarServico>` · veja [`Fatura`](#tipo-fatura).

## `buscar_auto_complete_fatura` [#buscar_auto_complete_fatura]

<Rota metodo="GET" caminho="/fatura/autocomplete" credencial />

Lista básica de faturas para seleção

Exige a permissão `ver` no módulo `Financeiro` do perfil de quem chama (administrador e master têm tudo). Devolve só id e documento, em ordem alfabética. `busca` procura no documento. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteFatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaFaturaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_fatura(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteFatura,
) -> Result<tipos::PaginaFaturaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_fatura(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteFatura { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaFaturaAutoComplete>` · Rust: `Result<tipos::PaginaFaturaAutoComplete, ErroAoChamarServico>` · veja [`PaginaFaturaAutoComplete`](#tipo-paginafaturaautocomplete).

## `buscar_pelo_filtro_fatura` [#buscar_pelo_filtro_fatura]

<Rota metodo="GET" caminho="/fatura/filtro" credencial />

Busca faturas por filtro

Exige a permissão `ver` no módulo `Financeiro` do perfil de quem chama (administrador e master têm tudo). Devolve as faturas não excluídas que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), do vencimento mais recente para o mais antigo. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `pedido_id` e `documento` são exatos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroFatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Fatura>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_fatura(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroFatura,
) -> Result<Vec<tipos::Fatura>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_fatura(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroFatura { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pedido_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.documento": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Fatura>>` · Rust: `Result<Vec<tipos::Fatura>, ErroAoChamarServico>`

## `buscar_pelo_id_fatura` [#buscar_pelo_id_fatura]

<Rota metodo="GET" caminho="/fatura/{id}" credencial />

Busca uma fatura pelo id

Exige a permissão `ver` no módulo `Financeiro` do perfil de quem chama (administrador e master têm tudo). Fatura excluída, ou de unidade fora da sessão, responde 404.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Fatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_fatura(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Fatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_fatura(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Fatura>` · Rust: `Result<tipos::Fatura, ErroAoChamarServico>` · veja [`Fatura`](#tipo-fatura).

## `atualizar_pelo_id_fatura` [#atualizar_pelo_id_fatura]

<Rota metodo="PATCH" caminho="/fatura/{id}" credencial />

Atualiza uma fatura

Exige a permissão `editar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Mesmas regras do cadastro; `pedido_id` aceita `null` para desvincular. A unidade não muda. Fatura de unidade fora da sessão responde 404. Atualização parcial: campo ausente mantém o valor atual. Campos: `documento` até 60 caracteres e único; `vencimento` em AAAA-MM-DD; `valor` é decimal; `status_rotulo` até 60 caracteres (texto do selo); `tom` é `sucesso`, `alerta`, `perigo`, `informacao` ou `neutro`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.FaturaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Fatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_fatura(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::FaturaAtualizar,
) -> Result<tipos::Fatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_fatura(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.FaturaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::FaturaAtualizar", typeDescriptionLink: "#tipo-faturaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Fatura>` · Rust: `Result<tipos::Fatura, ErroAoChamarServico>` · veja [`Fatura`](#tipo-fatura).

## `deletar_pelo_id_fatura` [#deletar_pelo_id_fatura]

<Rota metodo="DELETE" caminho="/fatura/{id}" credencial />

Exclui uma fatura

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Fatura de unidade fora da sessão responde 404. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_fatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_fatura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_fatura(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_fatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_fatura(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Fatura [#tipo-fatura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Fatura } from "termo_core/portal";

export interface Fatura {
  atualizado_em: string;
  criado_em: string;
  documento: string;
  id: string;
  pedido_id?: string | null;
  pedido_numero?: string | null;
  status_rotulo: string;
  tom: string;
  unidade_id: string;
  unidade_razao_social: string;
  valor: number;
  vencimento: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Fatura;

pub struct Fatura {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub documento: String,
    pub id: uuid::Uuid,
    pub pedido_id: Option<uuid::Uuid>,
    pub pedido_numero: Option<String>,
    pub status_rotulo: String,
    pub tom: String,
    pub unidade_id: uuid::Uuid,
    pub unidade_razao_social: String,
    pub valor: f64,
    pub vencimento: chrono::NaiveDate,
}
```

</Tab>
</Tabs>

### FaturaAtualizar [#tipo-faturaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FaturaAtualizar } from "termo_core/portal";

export interface FaturaAtualizar {
  documento?: string | null;
  pedido_id?: string | null;
  status_rotulo?: string | null;
  tom?: string | null;
  valor?: number | null;
  vencimento?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::FaturaAtualizar;

pub struct FaturaAtualizar {
    pub documento: Option<String>,
    pub pedido_id: Option<uuid::Uuid>,
    pub status_rotulo: Option<String>,
    pub tom: Option<String>,
    pub valor: Option<f64>,
    pub vencimento: Option<chrono::NaiveDate>,
}
```

</Tab>
</Tabs>

### FaturaCriar [#tipo-faturacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { FaturaCriar } from "termo_core/portal";

export interface FaturaCriar {
  documento: string;
  pedido_id?: string | null;
  status_rotulo: string;
  tom?: string | null;
  unidade_id: string;
  valor: number;
  vencimento: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::FaturaCriar;

pub struct FaturaCriar {
    pub documento: String,
    pub pedido_id: Option<uuid::Uuid>,
    pub status_rotulo: String,
    pub tom: Option<String>,
    pub unidade_id: uuid::Uuid,
    pub valor: f64,
    pub vencimento: chrono::NaiveDate,
}
```

</Tab>
</Tabs>

### PaginaFatura [#tipo-paginafatura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFatura } from "termo_core/portal";

export interface PaginaFatura {
  itens: Array<PaginaFaturaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaFatura;

pub struct PaginaFatura {
    pub itens: Vec<PaginaFaturaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaFaturaAutoComplete [#tipo-paginafaturaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaAutoComplete } from "termo_core/portal";

export interface PaginaFaturaAutoComplete {
  itens: Array<PaginaFaturaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaFaturaAutoComplete;

pub struct PaginaFaturaAutoComplete {
    pub itens: Vec<PaginaFaturaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaFaturaAutoCompleteItensItem [#tipo-paginafaturaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaFaturaAutoCompleteItensItem {
  documento: string;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaFaturaAutoCompleteItensItem;

pub struct PaginaFaturaAutoCompleteItensItem {
    pub documento: String,
    pub id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PaginaFaturaItensItem [#tipo-paginafaturaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaFaturaItensItem } from "termo_core/portal";

export interface PaginaFaturaItensItem {
  atualizado_em: string;
  criado_em: string;
  documento: string;
  id: string;
  pedido_id?: string | null;
  pedido_numero?: string | null;
  status_rotulo: string;
  tom: string;
  unidade_id: string;
  unidade_razao_social: string;
  valor: number;
  vencimento: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaFaturaItensItem;

pub struct PaginaFaturaItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub documento: String,
    pub id: uuid::Uuid,
    pub pedido_id: Option<uuid::Uuid>,
    pub pedido_numero: Option<String>,
    pub status_rotulo: String,
    pub tom: String,
    pub unidade_id: uuid::Uuid,
    pub unidade_razao_social: String,
    pub valor: f64,
    pub vencimento: chrono::NaiveDate,
}
```

</Tab>
</Tabs>


# TermoPortal (/docs/servicos/portal)

> API do Portal B2B da Termotubos: catálogo (produtos), unidades clientes, pessoas e perfis, cotações, pedidos, faturas e notas fiscais, entregas e pedidos de venda do ERP, indicadores e configurações.…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

API do Portal B2B da Termotubos: catálogo (produtos), unidades clientes, pessoas e perfis, cotações, pedidos, faturas e notas fiscais, entregas e pedidos de venda do ERP, indicadores e configurações. Respostas em JSON com nomes em snake_case; erro sempre `{ "erro": "mensagem" }`. As listagens paginadas antigas devolvem `{ itens, total, pagina, tamanho }`; as do padrão novo devolvem só o array da página em `GET /<feature>` e o paginador (totais e contagens) em `GET /<feature>/paginador`, com os mesmos filtros.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::portal` (feature `portal`) |
| Importação TypeScript | `termo_core/portal` ou `import { portal } from "termo_core"` |
| Funções | 158 |
| Entidades | 31 |
| Versão do contrato | `0.1.27` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51011` |
| `SANDBOX` | `https://sandbox-api-portal.termotubos.com.br` |
| `PRODUCTION` | `https://api-portal.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Arquivo" href="/docs/servicos/portal/arquivo" description="3 funções" />
  <Card title="Boletim técnico" href="/docs/servicos/portal/boletim_tecnico" description="8 funções" />
  <Card title="Boletim técnico medida" href="/docs/servicos/portal/boletim_tecnico_medida" description="8 funções" />
  <Card title="Catálogo atributo" href="/docs/servicos/portal/catalogo_atributo" description="7 funções" />
  <Card title="Cliente" href="/docs/servicos/portal/cliente" description="9 funções" />
  <Card title="Contato" href="/docs/servicos/portal/contato" description="7 funções" />
  <Card title="Cotação" href="/docs/servicos/portal/cotacao" description="7 funções" />
  <Card title="Dashboards" href="/docs/servicos/portal/dashboards" description="1 função" />
  <Card title="Endereço" href="/docs/servicos/portal/endereco" description="7 funções" />
  <Card title="Expedição" href="/docs/servicos/portal/expedicao" description="3 funções" />
  <Card title="Fatura" href="/docs/servicos/portal/fatura" description="7 funções" />
  <Card title="Indicador compra" href="/docs/servicos/portal/indicador_compra" description="1 função" />
  <Card title="Indicador venda" href="/docs/servicos/portal/indicador_venda" description="1 função" />
  <Card title="Nota fiscal" href="/docs/servicos/portal/nota_fiscal" description="6 funções" />
  <Card title="Painel produto" href="/docs/servicos/portal/painel_produto" description="2 funções" />
  <Card title="Pedido" href="/docs/servicos/portal/pedido" description="7 funções" />
  <Card title="Pedido venda" href="/docs/servicos/portal/pedido_venda" description="3 funções" />
  <Card title="Pedido venda Tiny" href="/docs/servicos/portal/pedido_venda_tiny" description="5 funções" />
  <Card title="Perfil" href="/docs/servicos/portal/perfil" description="7 funções" />
  <Card title="Produto" href="/docs/servicos/portal/produto" description="7 funções" />
  <Card title="Produto conflito sincronização" href="/docs/servicos/portal/produto_conflito_sincronizacao" description="7 funções" />
  <Card title="Produto estrutura" href="/docs/servicos/portal/produto_estrutura" description="1 função" />
  <Card title="Produto Termotubos" href="/docs/servicos/portal/produto_termotubos" description="5 funções" />
  <Card title="Produto Tiny" href="/docs/servicos/portal/produto_tiny" description="1 função" />
  <Card title="Rastreamento" href="/docs/servicos/portal/rastreamento" description="7 funções" />
  <Card title="Tabela auxiliar" href="/docs/servicos/portal/tabela_auxiliar" description="7 funções" />
  <Card title="Unidade" href="/docs/servicos/portal/unidade" description="7 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Colaborador" href="/docs/servicos/portal/colaborador" description="7 funções" />
  <Card title="Configuração" href="/docs/servicos/portal/configuracao" description="7 funções" />
  <Card title="Configuração provedor" href="/docs/servicos/portal/configuracao_provedor" description="2 funções" />
  <Card title="Versão" href="/docs/servicos/portal/versao" description="1 função" />
</Cards>


# Indicador compra (/docs/servicos/portal/indicador_compra)

> 1 função do TermoPortal para indicador compra.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_filtro_indicador_compra`](#buscar_pelo_filtro_indicador_compra) | `GET /indicador_compra/filtro` | Indicadores de compra de uma unidade |

## `buscar_pelo_filtro_indicador_compra` [#buscar_pelo_filtro_indicador_compra]

<Rota metodo="GET" caminho="/indicador_compra/filtro" credencial />

Indicadores de compra de uma unidade

Exige a permissão `ver` no módulo `Dashboard` do perfil de quem chama (administrador e master têm tudo). Soma na hora as compras (notas emitidas pelo Tiny) do CNPJ da unidade `unidade_id`: total comprado, comparação com o período anterior (períodos de até 731 dias), notas, produtos diferentes, última compra, compras por mês, por tipo e os produtos mais comprados (até 6). `unidade_id` é obrigatório e precisa ser uma unidade da sessão (colaborador interno acessa todas). `inicio` e `fim` em AAAA-MM-DD (padrão: últimos 365 dias). `amostra: true` indica soma parcial. Até 30 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_indicador_compra(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroIndicadorCompra = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.IndicadoresDeCompra>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_indicador_compra } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_indicador_compra(credencial_de_acesso, { inicio: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_indicador_compra(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroIndicadorCompra,
) -> Result<tipos::IndicadoresDeCompra, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_indicador_compra(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroIndicadorCompra { inicio: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.IndicadoresDeCompra>` · Rust: `Result<tipos::IndicadoresDeCompra, ErroAoChamarServico>` · veja [`IndicadoresDeCompra`](#tipo-indicadoresdecompra).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### CompraDoMes [#tipo-compradomes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CompraDoMes } from "termo_core/portal";

export interface CompraDoMes {
  comprado: number;
  mes: string;
  notas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CompraDoMes;

pub struct CompraDoMes {
    pub comprado: f64,
    pub mes: String,
    pub notas: i64,
}
```

</Tab>
</Tabs>

### CompraPorTipo [#tipo-compraportipo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CompraPorTipo } from "termo_core/portal";

export interface CompraPorTipo {
  comprado: number;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::CompraPorTipo;

pub struct CompraPorTipo {
    pub comprado: f64,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### IndicadoresDeCompra [#tipo-indicadoresdecompra]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { IndicadoresDeCompra } from "termo_core/portal";

export interface IndicadoresDeCompra {
  amostra: boolean;
  anterior?: number | null;
  comprado: number;
  fim: string;
  inicio: string;
  itens: number;
  notas: number;
  por_mes: Array<CompraDoMes>;
  por_tipo: Array<CompraPorTipo>;
  produtos: Array<ProdutoComprado>;
  produtos_diferentes: number;
  ultima_compra?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::IndicadoresDeCompra;

pub struct IndicadoresDeCompra {
    pub amostra: bool,
    pub anterior: Option<f64>,
    pub comprado: f64,
    pub fim: String,
    pub inicio: String,
    pub itens: i64,
    pub notas: i64,
    pub por_mes: Vec<CompraDoMes>,
    pub por_tipo: Vec<CompraPorTipo>,
    pub produtos: Vec<ProdutoComprado>,
    pub produtos_diferentes: i64,
    pub ultima_compra: Option<String>,
}
```

</Tab>
</Tabs>

### ProdutoComprado [#tipo-produtocomprado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoComprado } from "termo_core/portal";

export interface ProdutoComprado {
  comprado: number;
  descricao: string;
  familia?: string | null;
  quantidade: number;
  sku: string;
  tipo?: string | null;
  ultima_compra?: string | null;
  ultima_quantidade: number;
  vezes: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoComprado;

pub struct ProdutoComprado {
    pub comprado: f64,
    pub descricao: String,
    pub familia: Option<String>,
    pub quantidade: f64,
    pub sku: String,
    pub tipo: Option<String>,
    pub ultima_compra: Option<String>,
    pub ultima_quantidade: f64,
    pub vezes: i64,
}
```

</Tab>
</Tabs>


# Indicador venda (/docs/servicos/portal/indicador_venda)

> 1 função do TermoPortal para indicador venda.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_filtro_indicador_venda`](#buscar_pelo_filtro_indicador_venda) | `GET /indicador_venda/filtro` | Indicadores de venda do painel |

## `buscar_pelo_filtro_indicador_venda` [#buscar_pelo_filtro_indicador_venda]

<Rota metodo="GET" caminho="/indicador_venda/filtro" credencial />

Indicadores de venda do painel

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Só colaborador interno. Soma na hora os pedidos de venda do Tiny no período: total vendido e pedidos, comparação com o período anterior (períodos de até 92 dias), vendas de hoje, pedidos para aprovar, cancelados, vendas por dia, por canal, por vendedor e maiores clientes (até 6 no ranking). `inicio` e `fim` em AAAA-MM-DD (padrão: últimos 30 dias; até 366 dias). `amostra: true` indica que o período tinha pedidos demais e a soma usou parte deles. Até 20 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_indicador_venda(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroIndicadorVenda = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.IndicadoresDeVenda>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_indicador_venda } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_indicador_venda(credencial_de_acesso, { inicio: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_indicador_venda(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroIndicadorVenda,
) -> Result<tipos::IndicadoresDeVenda, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_indicador_venda(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroIndicadorVenda { inicio: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.IndicadoresDeVenda>` · Rust: `Result<tipos::IndicadoresDeVenda, ErroAoChamarServico>` · veja [`IndicadoresDeVenda`](#tipo-indicadoresdevenda).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### IndicadoresDeVenda [#tipo-indicadoresdevenda]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { IndicadoresDeVenda } from "termo_core/portal";

export interface IndicadoresDeVenda {
  amostra: boolean;
  anterior?: Totais | null;
  cancelados: number;
  fim: string;
  hoje: Totais;
  inicio: string;
  maiores_clientes: Array<VendaAgrupada>;
  para_aprovar: number;
  periodo: Totais;
  por_canal: Array<VendaAgrupada>;
  por_dia: Array<VendaDoDia>;
  por_vendedor: Array<VendaAgrupada>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::IndicadoresDeVenda;

pub struct IndicadoresDeVenda {
    pub amostra: bool,
    pub anterior: Option<Totais>,
    pub cancelados: i64,
    pub fim: String,
    pub hoje: Totais,
    pub inicio: String,
    pub maiores_clientes: Vec<VendaAgrupada>,
    pub para_aprovar: i64,
    pub periodo: Totais,
    pub por_canal: Vec<VendaAgrupada>,
    pub por_dia: Vec<VendaDoDia>,
    pub por_vendedor: Vec<VendaAgrupada>,
}
```

</Tab>
</Tabs>

### Totais [#tipo-totais]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Totais } from "termo_core/portal";

export interface Totais {
  pedidos: number;
  vendido: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Totais;

pub struct Totais {
    pub pedidos: i64,
    pub vendido: f64,
}
```

</Tab>
</Tabs>

### VendaAgrupada [#tipo-vendaagrupada]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VendaAgrupada } from "termo_core/portal";

export interface VendaAgrupada {
  chave?: string | null;
  pedidos: number;
  rotulo: string;
  vendido: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::VendaAgrupada;

pub struct VendaAgrupada {
    pub chave: Option<String>,
    pub pedidos: i64,
    pub rotulo: String,
    pub vendido: f64,
}
```

</Tab>
</Tabs>

### VendaDoDia [#tipo-vendadodia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VendaDoDia } from "termo_core/portal";

export interface VendaDoDia {
  data: string;
  pedidos: number;
  vendido: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::VendaDoDia;

pub struct VendaDoDia {
    pub data: String,
    pub pedidos: i64,
    pub vendido: f64,
}
```

</Tab>
</Tabs>


# Nota fiscal (/docs/servicos/portal/nota_fiscal)

> 6 funções do TermoPortal para nota fiscal.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_nota_fiscal`](#buscar_paginador_nota_fiscal) | `GET /nota_fiscal` | Uma página das notas fiscais, por cursor |
| [`buscar_informacoes_paginador_nota_fiscal`](#buscar_informacoes_paginador_nota_fiscal) | `GET /nota_fiscal/paginador` | Total, páginas e contagens das notas fiscais |
| [`buscar_sincronizacao_nota_fiscal`](#buscar_sincronizacao_nota_fiscal) | `GET /nota_fiscal/sincronizacao` | Status da sincronização das notas fiscais |
| [`iniciar_sincronizacao_nota_fiscal`](#iniciar_sincronizacao_nota_fiscal) | `POST /nota_fiscal/sincronizacao` | Inicia a sincronização das notas fiscais em segundo plano |
| [`cancelar_sincronizacao_nota_fiscal`](#cancelar_sincronizacao_nota_fiscal) | `DELETE /nota_fiscal/sincronizacao` | Cancela a sincronização das notas fiscais em andamento |
| [`buscar_pelo_id_nota_fiscal`](#buscar_pelo_id_nota_fiscal) | `GET /nota_fiscal/{id}` | Busca uma nota fiscal pelo id do Tiny |

## `buscar_paginador_nota_fiscal` [#buscar_paginador_nota_fiscal]

<Rota metodo="GET" caminho="/nota_fiscal" credencial />

Uma página das notas fiscais, por cursor

Exige a permissão `ver` no módulo `Financeiro` do perfil de quem chama (administrador e master têm tudo). Lê a tabela `nota_fiscal`, que o backend sincroniza sozinho com as notas emitidas no Tiny (pela API da Termotubos), com parcelas e situação financeira; a emissão mais recente vem primeiro e a resposta é só o array das 50 notas da página. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só vê as notas do CNPJ dela; colaborador interno pode omitir e ver todas. Filtros: `filtro` (`todas`, `hoje`, `mes`; padrão `todas`; `hoje` e `mes` trocam o período), `busca` (CPF/CNPJ, número da nota ou nome do cliente), `inicio` e `fim` (AAAA-MM-DD) e `vendedor` (id no Tiny, só colaborador). A paginação é por cursor: a primeira página vai sem `cursor` e a seguinte manda em `cursor` o `id` da última nota recebida. Total, páginas e contagens vêm de `GET /nota_fiscal/paginador`, com o mesmo filtro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_nota_fiscal(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorNotaFiscal = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.NotaFiscal>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_nota_fiscal } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_nota_fiscal(credencial_de_acesso, { filtro: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_nota_fiscal(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorNotaFiscal,
) -> Result<Vec<tipos::NotaFiscal>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_nota_fiscal(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorNotaFiscal { filtro: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.filtro": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.natureza": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor_nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.condicao_pagamento": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.NotaFiscal>>` · Rust: `Result<Vec<tipos::NotaFiscal>, ErroAoChamarServico>`

## `buscar_informacoes_paginador_nota_fiscal` [#buscar_informacoes_paginador_nota_fiscal]

<Rota metodo="GET" caminho="/nota_fiscal/paginador" credencial />

Total, páginas e contagens das notas fiscais

Mesma permissão, mesmos filtros e mesma regra de unidade de `GET /nota_fiscal` (o `cursor` é ignorado). Devolve `total` e `paginas` com o filtro escolhido, `tamanho` (50), `sincronizado_em` (a última sincronização; nulo se nunca houve) e `contagens` (`todas`, `hoje`, `mes`), que usam os outros filtros e trocam o período pelo do bloco.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_informacoes_paginador_nota_fiscal(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarInformacoesPaginadorNotaFiscal = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.NotaFiscalPaginador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_informacoes_paginador_nota_fiscal } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_informacoes_paginador_nota_fiscal(credencial_de_acesso, { filtro: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_informacoes_paginador_nota_fiscal(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarInformacoesPaginadorNotaFiscal,
) -> Result<tipos::NotaFiscalPaginador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_informacoes_paginador_nota_fiscal(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarInformacoesPaginadorNotaFiscal { filtro: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.filtro": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.natureza": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor_nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.condicao_pagamento": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.NotaFiscalPaginador>` · Rust: `Result<tipos::NotaFiscalPaginador, ErroAoChamarServico>` · veja [`NotaFiscalPaginador`](#tipo-notafiscalpaginador).

## `buscar_sincronizacao_nota_fiscal` [#buscar_sincronizacao_nota_fiscal]

<Rota metodo="GET" caminho="/nota_fiscal/sincronizacao" credencial />

Status da sincronização das notas fiscais

Só colaborador interno com `ver` no módulo `Financeiro`. Devolve a sincronização em andamento ou a última que terminou: `rodando`, `pagina` de `total_paginas` (páginas da API), `progresso` (percentual), `gravados`, `cancelada`, `concluida`, `erro`, `iniciada_em` e `terminada_em`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_sincronizacao_nota_fiscal(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusSincronizacaoNotasFiscais>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_sincronizacao_nota_fiscal } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_sincronizacao_nota_fiscal(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_sincronizacao_nota_fiscal(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusSincronizacaoNotasFiscais, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_sincronizacao_nota_fiscal(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusSincronizacaoNotasFiscais>` · Rust: `Result<tipos::StatusSincronizacaoNotasFiscais, ErroAoChamarServico>` · veja [`StatusSincronizacaoNotasFiscais`](#tipo-statussincronizacaonotasfiscais).

## `iniciar_sincronizacao_nota_fiscal` [#iniciar_sincronizacao_nota_fiscal]

<Rota metodo="POST" caminho="/nota_fiscal/sincronizacao" credencial />

Inicia a sincronização das notas fiscais em segundo plano

Só colaborador interno com `ver` no módulo `Financeiro`. Traz as notas fiscais emitidas no Tiny (pela API de notas fiscais da Termotubos) para a tabela `nota_fiscal`, com as parcelas lidas do XML das notas válidas que ainda não as têm, sem filtro de data (histórico inteiro), lote por lote, em segundo plano no servidor: a tela pode ser fechada. Responde 202 com o status inicial; acompanhe por `GET /nota_fiscal/sincronizacao`. O status fica em memória e se perde se o servidor reiniciar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function iniciar_sincronizacao_nota_fiscal(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusSincronizacaoNotasFiscais>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { iniciar_sincronizacao_nota_fiscal } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await iniciar_sincronizacao_nota_fiscal(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn iniciar_sincronizacao_nota_fiscal(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusSincronizacaoNotasFiscais, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::iniciar_sincronizacao_nota_fiscal(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusSincronizacaoNotasFiscais>` · Rust: `Result<tipos::StatusSincronizacaoNotasFiscais, ErroAoChamarServico>` · veja [`StatusSincronizacaoNotasFiscais`](#tipo-statussincronizacaonotasfiscais).

## `cancelar_sincronizacao_nota_fiscal` [#cancelar_sincronizacao_nota_fiscal]

<Rota metodo="DELETE" caminho="/nota_fiscal/sincronizacao" credencial />

Cancela a sincronização das notas fiscais em andamento

Só colaborador interno com `ver` no módulo `Financeiro`. Para antes do próximo lote; o que já foi gravado fica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function cancelar_sincronizacao_nota_fiscal(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { cancelar_sincronizacao_nota_fiscal } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await cancelar_sincronizacao_nota_fiscal(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn cancelar_sincronizacao_nota_fiscal(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::cancelar_sincronizacao_nota_fiscal(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `buscar_pelo_id_nota_fiscal` [#buscar_pelo_id_nota_fiscal]

<Rota metodo="GET" caminho="/nota_fiscal/{id}" credencial />

Busca uma nota fiscal pelo id do Tiny

Exige a permissão `ver` no módulo `Financeiro` do perfil de quem chama (administrador e master têm tudo). Lê a nota da tabela `nota_fiscal` com itens, parcelas (vencimento, valor, situação) e situação financeira. Com `xml=1`, devolve o XML da nota como download (`application/xml`), buscado na hora na API da Termotubos. Quem não é colaborador interno só abre notas do CNPJ das próprias unidades (as outras respondem 404).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_nota_fiscal(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  parametros: ParametrosDeBuscarPeloIdNotaFiscal = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.NotaFiscal>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_nota_fiscal } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_nota_fiscal(credencial_de_acesso, id, { xml: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_nota_fiscal(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
    parametros: &ParametrosDeBuscarPeloIdNotaFiscal,
) -> Result<tipos::NotaFiscal, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_nota_fiscal(
    &credencial_de_acesso,
    id,
    &termo_core::portal::ParametrosDeBuscarPeloIdNotaFiscal { xml: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "parametros.xml": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.NotaFiscal>` · Rust: `Result<tipos::NotaFiscal, ErroAoChamarServico>` · veja [`NotaFiscal`](#tipo-notafiscal).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ContagemNotasFiscais [#tipo-contagemnotasfiscais]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContagemNotasFiscais } from "termo_core/portal";

export interface ContagemNotasFiscais {
  hoje: number;
  mes: number;
  todas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContagemNotasFiscais;

pub struct ContagemNotasFiscais {
    pub hoje: i64,
    pub mes: i64,
    pub todas: i64,
}
```

</Tab>
</Tabs>

### ItemNotaFiscal [#tipo-itemnotafiscal]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ItemNotaFiscal } from "termo_core/portal";

export interface ItemNotaFiscal {
  descricao?: string | null;
  preco_unitario?: number | null;
  quantidade?: number | null;
  sku?: string | null;
  total?: number | null;
  unidade?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ItemNotaFiscal;

pub struct ItemNotaFiscal {
    pub descricao: Option<String>,
    pub preco_unitario: Option<f64>,
    pub quantidade: Option<f64>,
    pub sku: Option<String>,
    pub total: Option<f64>,
    pub unidade: Option<String>,
}
```

</Tab>
</Tabs>

### NotaFiscal [#tipo-notafiscal]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotaFiscal } from "termo_core/portal";

export type NotaFiscal = NotaFiscalTermotubos & NotaFiscalParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::NotaFiscal;

pub type NotaFiscal = serde_json::Value;
```

</Tab>
</Tabs>

### NotaFiscalPaginador [#tipo-notafiscalpaginador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotaFiscalPaginador } from "termo_core/portal";

export interface NotaFiscalPaginador {
  contagens: ContagemNotasFiscais;
  paginas: number;
  sincronizado_em?: string | null;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::NotaFiscalPaginador;

pub struct NotaFiscalPaginador {
    pub contagens: ContagemNotasFiscais,
    pub paginas: i64,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### NotaFiscalParte2 [#tipo-notafiscalparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotaFiscalParte2 } from "termo_core/portal";

export interface NotaFiscalParte2 {
  parcelas: Array<ParcelaNotaFiscal>;
  parcelas_lidas: boolean;
  proximo_vencimento?: string | null;
  sincronizado_em?: string | null;
  situacao_financeira: string;
  tom: string;
}
```

</Tab>
<Tab value="Rust">

`termo_core::portal::NotaFiscalParte2`

</Tab>
</Tabs>

### NotaFiscalTermotubos [#tipo-notafiscaltermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotaFiscalTermotubos } from "termo_core/portal";

export interface NotaFiscalTermotubos {
  chave_acesso?: string | null;
  cliente?: string | null;
  cliente_documento?: string | null;
  cliente_tiny_id?: number | null;
  condicao_pagamento?: string | null;
  emissao?: string | null;
  frete?: number | null;
  id: number;
  itens: Array<ItemNotaFiscal>;
  natureza?: string | null;
  nota_tiny_id?: number | null;
  numero?: number | null;
  outros?: number | null;
  pedido_numero?: number | null;
  serie?: string | null;
  situacao?: string | null;
  situacao_id?: number | null;
  transportadora?: string | null;
  valor_produtos?: number | null;
  valor_total?: number | null;
  vendedor?: string | null;
  vendedor_tiny_id?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::NotaFiscalTermotubos;

pub struct NotaFiscalTermotubos {
    pub chave_acesso: Option<String>,
    pub cliente: Option<String>,
    pub cliente_documento: Option<String>,
    pub cliente_tiny_id: Option<i64>,
    pub condicao_pagamento: Option<String>,
    pub emissao: Option<String>,
    pub frete: Option<f64>,
    pub id: i64,
    pub itens: Vec<ItemNotaFiscal>,
    pub natureza: Option<String>,
    pub nota_tiny_id: Option<i64>,
    pub numero: Option<i64>,
    pub outros: Option<f64>,
    pub pedido_numero: Option<i64>,
    pub serie: Option<String>,
    pub situacao: Option<String>,
    pub situacao_id: Option<i64>,
    pub transportadora: Option<String>,
    pub valor_produtos: Option<f64>,
    pub valor_total: Option<f64>,
    pub vendedor: Option<String>,
    pub vendedor_tiny_id: Option<i64>,
}
```

</Tab>
</Tabs>

### ParcelaNotaFiscal [#tipo-parcelanotafiscal]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ParcelaNotaFiscal } from "termo_core/portal";

export interface ParcelaNotaFiscal {
  forma_pagamento?: string | null;
  numero: string;
  parcela: number;
  parcelas: number;
  situacao: string;
  tom: string;
  valor: number;
  vencimento: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ParcelaNotaFiscal;

pub struct ParcelaNotaFiscal {
    pub forma_pagamento: Option<String>,
    pub numero: String,
    pub parcela: i64,
    pub parcelas: i64,
    pub situacao: String,
    pub tom: String,
    pub valor: f64,
    pub vencimento: String,
}
```

</Tab>
</Tabs>

### StatusSincronizacaoNotasFiscais [#tipo-statussincronizacaonotasfiscais]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { StatusSincronizacaoNotasFiscais } from "termo_core/portal";

export interface StatusSincronizacaoNotasFiscais {
  cancelada: boolean;
  concluida: boolean;
  erro?: string | null;
  gravados: number;
  iniciada_em?: string | null;
  pagina: number;
  progresso: number;
  rodando: boolean;
  terminada_em?: string | null;
  total_paginas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::StatusSincronizacaoNotasFiscais;

pub struct StatusSincronizacaoNotasFiscais {
    pub cancelada: bool,
    pub concluida: bool,
    pub erro: Option<String>,
    pub gravados: i64,
    pub iniciada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub pagina: i32,
    pub progresso: i32,
    pub rodando: bool,
    pub terminada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub total_paginas: i32,
}
```

</Tab>
</Tabs>


# Painel produto (/docs/servicos/portal/painel_produto)

> 2 funções do TermoPortal para painel produto.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_painel_produto`](#buscar_paginador_painel_produto) | `GET /painel_produto` | Uma página da lista de Produtos do painel, por cursor |
| [`buscar_informacoes_paginador_painel_produto`](#buscar_informacoes_paginador_painel_produto) | `GET /painel_produto/paginador` | Total e páginas da lista de Produtos do painel |

## `buscar_paginador_painel_produto` [#buscar_paginador_painel_produto]

<Rota metodo="GET" caminho="/painel_produto" credencial />

Uma página da lista de Produtos do painel, por cursor

Só colaborador interno (mesma regra da leitura de `produto_conflito_sincronizacao`). Lê a tabela `produto` inteira de um cache em memória (descartado a cada gravação em produto ou em conflito de sincronização, e recarregado do banco no máximo a cada 10 minutos), em ordem alfabética do nome (sem diferença de maiúscula; empate pelo id), e devolve só o array das 50 linhas da página. A paginação é por cursor: a primeira página vai sem `cursor`, e a seguinte manda em `cursor` o `id` da última linha recebida. `busca` (sem acento e sem maiúscula) procura o texto no nome ou no SKU. `ultima_sincronizacao` (data ISO, AAAA-MM-DD ou data e hora com fuso) é o início da última sincronização do painel: produto criado depois dela vem com `estado` `novo` e produto da API sincronizado depois dela, `mudou`; com conflito de sincronização pendente, `conflito`; senão, `em-dia`. Total e páginas vêm de `GET /painel_produto/paginador`, com a mesma `busca`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_painel_produto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPainelProduto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PainelProdutoLinha>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_painel_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_painel_produto(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_painel_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPainelProduto,
) -> Result<Vec<tipos::PainelProdutoLinha>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_painel_produto(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorPainelProduto { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ultima_sincronizacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.categoria_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.marca_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ncm": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.garantia": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.embalagem_rotulo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.sku_categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.sku_medida": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.sku_cor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.na_vitrine": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.com_estoque": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PainelProdutoLinha>>` · Rust: `Result<Vec<tipos::PainelProdutoLinha>, ErroAoChamarServico>`

## `buscar_informacoes_paginador_painel_produto` [#buscar_informacoes_paginador_painel_produto]

<Rota metodo="GET" caminho="/painel_produto/paginador" credencial />

Total e páginas da lista de Produtos do painel

Só colaborador interno (mesma regra da leitura de `produto_conflito_sincronizacao`). Recebe os mesmos parâmetros de `GET /painel_produto` (`cursor` e `ultima_sincronizacao` não mudam a conta) e devolve `total` (produtos com a `busca`), `paginas` (total dividido por `tamanho`, arredondado para cima, no mínimo 1) e `tamanho` (sempre 50).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_informacoes_paginador_painel_produto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarInformacoesPaginadorPainelProduto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PainelProdutoPaginador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_informacoes_paginador_painel_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_informacoes_paginador_painel_produto(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_informacoes_paginador_painel_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarInformacoesPaginadorPainelProduto,
) -> Result<tipos::PainelProdutoPaginador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_informacoes_paginador_painel_produto(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarInformacoesPaginadorPainelProduto { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cursor": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ultima_sincronizacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.categoria_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.marca_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ncm": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.garantia": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.embalagem_rotulo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.sku_categoria": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.sku_medida": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.sku_cor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.na_vitrine": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.com_estoque": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PainelProdutoPaginador>` · Rust: `Result<tipos::PainelProdutoPaginador, ErroAoChamarServico>` · veja [`PainelProdutoPaginador`](#tipo-painelprodutopaginador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PainelProdutoLinha [#tipo-painelprodutolinha]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PainelProdutoLinha } from "termo_core/portal";

export interface PainelProdutoLinha {
  chave: string;
  codigo: string;
  configurado: boolean;
  cor: string;
  estado: string;
  estoque?: number | null;
  id: string;
  imagem?: string | null;
  na_vitrine: boolean;
  nome: string;
  origem: string;
  preco: number;
  sincronizado_em?: string | null;
  skus: Array<string>;
  tem_imagem: boolean;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PainelProdutoLinha;

pub struct PainelProdutoLinha {
    pub chave: String,
    pub codigo: String,
    pub configurado: bool,
    pub cor: String,
    pub estado: String,
    pub estoque: Option<i64>,
    pub id: uuid::Uuid,
    pub imagem: Option<String>,
    pub na_vitrine: bool,
    pub nome: String,
    pub origem: String,
    pub preco: f64,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub skus: Vec<String>,
    pub tem_imagem: bool,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### PainelProdutoPaginador [#tipo-painelprodutopaginador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PainelProdutoPaginador } from "termo_core/portal";

export interface PainelProdutoPaginador {
  paginas: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PainelProdutoPaginador;

pub struct PainelProdutoPaginador {
    pub paginas: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>


# Pedido (/docs/servicos/portal/pedido)

> 7 funções do TermoPortal para pedido.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_pedido`](#buscar_paginador_pedido) | `GET /pedido` | Lista os pedidos paginados |
| [`criar_pedido`](#criar_pedido) | `POST /pedido` | Cadastra um pedido |
| [`buscar_auto_complete_pedido`](#buscar_auto_complete_pedido) | `GET /pedido/autocomplete` | Lista básica de pedidos para seleção |
| [`buscar_pelo_filtro_pedido`](#buscar_pelo_filtro_pedido) | `GET /pedido/filtro` | Busca pedidos por filtro |
| [`buscar_pelo_id_pedido`](#buscar_pelo_id_pedido) | `GET /pedido/{id}` | Busca um pedido pelo id |
| [`atualizar_pelo_id_pedido`](#atualizar_pelo_id_pedido) | `PATCH /pedido/{id}` | Atualiza um pedido |
| [`deletar_pelo_id_pedido`](#deletar_pelo_id_pedido) | `DELETE /pedido/{id}` | Exclui um pedido |

## `buscar_paginador_pedido` [#buscar_paginador_pedido]

<Rota metodo="GET" caminho="/pedido" credencial />

Lista os pedidos paginados

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Do faturamento mais recente para o mais antigo. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPedido = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPedido>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_pedido(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPedido,
) -> Result<tipos::PaginaPedido, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_pedido(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorPedido { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPedido>` · Rust: `Result<tipos::PaginaPedido, ErroAoChamarServico>` · veja [`PaginaPedido`](#tipo-paginapedido).

## `criar_pedido` [#criar_pedido]

<Rota metodo="POST" caminho="/pedido" credencial />

Cadastra um pedido

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Pedido faturado de uma unidade cliente, mostrado em Pedidos do portal. `numero` (até 40 caracteres) é único; `unidade_id` precisa ser da sessão (colaborador interno acessa todas); `nota_fiscal` e `cotacao_origem` opcionais; `data_faturamento` e `previsao_entrega` (AAAA-MM-DD); `status_rotulo` (até 60 caracteres, texto exibido) e `tom` (`sucesso`, `alerta`, `perigo`, `informacao` ou `neutro`); `entregue` tem padrão `false`; `itens` opcionais com `sku`, `produto` e `quantidade` (texto).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PedidoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Pedido>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_pedido(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PedidoCriar,
) -> Result<tipos::Pedido, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_pedido(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PedidoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PedidoCriar", typeDescriptionLink: "#tipo-pedidocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Pedido>` · Rust: `Result<tipos::Pedido, ErroAoChamarServico>` · veja [`Pedido`](#tipo-pedido).

## `buscar_auto_complete_pedido` [#buscar_auto_complete_pedido]

<Rota metodo="GET" caminho="/pedido/autocomplete" credencial />

Lista básica de pedidos para seleção

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Devolve id e `rotulo` (número e nota fiscal), em ordem do número. `busca` procura no número e na nota. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePedido = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPedidoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_pedido(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePedido,
) -> Result<tipos::PaginaPedidoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_pedido(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompletePedido { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPedidoAutoComplete>` · Rust: `Result<tipos::PaginaPedidoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPedidoAutoComplete`](#tipo-paginapedidoautocomplete).

## `buscar_pelo_filtro_pedido` [#buscar_pelo_filtro_pedido]

<Rota metodo="GET" caminho="/pedido/filtro" credencial />

Busca pedidos por filtro

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Devolve os pedidos não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), do faturamento mais recente para o mais antigo. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da própria sessão; colaborador interno pode omitir e vê todas. `numero` compara com o número ou com a nota fiscal; `entregue` filtra.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPedido = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Pedido>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_pedido(credencial_de_acesso, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPedido,
) -> Result<Vec<tipos::Pedido>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_pedido(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroPedido { unidade_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.numero": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.entregue": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Pedido>>` · Rust: `Result<Vec<tipos::Pedido>, ErroAoChamarServico>`

## `buscar_pelo_id_pedido` [#buscar_pelo_id_pedido]

<Rota metodo="GET" caminho="/pedido/{id}" credencial />

Busca um pedido pelo id

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Pedido excluído, ou de unidade fora da sessão, responde 404.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Pedido>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_pedido(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Pedido, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_pedido(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Pedido>` · Rust: `Result<tipos::Pedido, ErroAoChamarServico>` · veja [`Pedido`](#tipo-pedido).

## `atualizar_pelo_id_pedido` [#atualizar_pelo_id_pedido]

<Rota metodo="PATCH" caminho="/pedido/{id}" credencial />

Atualiza um pedido

Exige a permissão `editar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Mesmas regras do cadastro; `nota_fiscal` e `cotacao_origem` aceitam `null` para apagar; `itens`, quando enviado, substitui a lista. A unidade não muda. Pedido de unidade fora da sessão responde 404. Cada item de `itens` tem `sku`, `produto` (nome) e `quantidade` (texto). Atualização parcial: campo ausente mantém o valor atual. Campos: `numero` até 40 caracteres e único; `data_faturamento` em AAAA-MM-DD; `status_rotulo` até 60 caracteres (texto do selo); `tom` é `sucesso`, `alerta`, `perigo`, `informacao` ou `neutro`; `previsao_entrega` em AAAA-MM-DD; `entregue` (booleano) marca o pedido como entregue.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PedidoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Pedido>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_pedido(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PedidoAtualizar,
) -> Result<tipos::Pedido, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_pedido(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PedidoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PedidoAtualizar", typeDescriptionLink: "#tipo-pedidoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Pedido>` · Rust: `Result<tipos::Pedido, ErroAoChamarServico>` · veja [`Pedido`](#tipo-pedido).

## `deletar_pelo_id_pedido` [#deletar_pelo_id_pedido]

<Rota metodo="DELETE" caminho="/pedido/{id}" credencial />

Exclui um pedido

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Recusa pedido com faturas vinculadas. Pedido de unidade fora da sessão responde 404. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_pedido(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_pedido } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_pedido(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_pedido(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_pedido(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaPedido [#tipo-paginapedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPedido } from "termo_core/portal";

export interface PaginaPedido {
  itens: Array<PaginaPedidoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPedido;

pub struct PaginaPedido {
    pub itens: Vec<PaginaPedidoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPedidoAutoComplete [#tipo-paginapedidoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPedidoAutoComplete } from "termo_core/portal";

export interface PaginaPedidoAutoComplete {
  itens: Array<PaginaPedidoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPedidoAutoComplete;

pub struct PaginaPedidoAutoComplete {
    pub itens: Vec<PaginaPedidoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPedidoAutoCompleteItensItem [#tipo-paginapedidoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPedidoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaPedidoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPedidoAutoCompleteItensItem;

pub struct PaginaPedidoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaPedidoItensItem [#tipo-paginapedidoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPedidoItensItem } from "termo_core/portal";

export interface PaginaPedidoItensItem {
  atualizado_em: string;
  cotacao_origem?: string | null;
  criado_em: string;
  data_faturamento: string;
  entregue: boolean;
  id: string;
  itens: Array<PedidoItem>;
  nota_fiscal?: string | null;
  numero: string;
  previsao_entrega: string;
  status_rotulo: string;
  tom: string;
  unidade_cnpj: string;
  unidade_id: string;
  unidade_razao_social: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPedidoItensItem;

pub struct PaginaPedidoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cotacao_origem: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub data_faturamento: chrono::NaiveDate,
    pub entregue: bool,
    pub id: uuid::Uuid,
    pub itens: Vec<PedidoItem>,
    pub nota_fiscal: Option<String>,
    pub numero: String,
    pub previsao_entrega: chrono::NaiveDate,
    pub status_rotulo: String,
    pub tom: String,
    pub unidade_cnpj: String,
    pub unidade_id: uuid::Uuid,
    pub unidade_razao_social: String,
}
```

</Tab>
</Tabs>

### Pedido [#tipo-pedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Pedido } from "termo_core/portal";

export interface Pedido {
  atualizado_em: string;
  cotacao_origem?: string | null;
  criado_em: string;
  data_faturamento: string;
  entregue: boolean;
  id: string;
  itens: Array<PedidoItem>;
  nota_fiscal?: string | null;
  numero: string;
  previsao_entrega: string;
  status_rotulo: string;
  tom: string;
  unidade_cnpj: string;
  unidade_id: string;
  unidade_razao_social: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Pedido;

pub struct Pedido {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cotacao_origem: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub data_faturamento: chrono::NaiveDate,
    pub entregue: bool,
    pub id: uuid::Uuid,
    pub itens: Vec<PedidoItem>,
    pub nota_fiscal: Option<String>,
    pub numero: String,
    pub previsao_entrega: chrono::NaiveDate,
    pub status_rotulo: String,
    pub tom: String,
    pub unidade_cnpj: String,
    pub unidade_id: uuid::Uuid,
    pub unidade_razao_social: String,
}
```

</Tab>
</Tabs>

### PedidoAtualizar [#tipo-pedidoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoAtualizar } from "termo_core/portal";

export interface PedidoAtualizar {
  cotacao_origem?: string | null;
  data_faturamento?: string | null;
  entregue?: boolean | null;
  itens?: Array<PedidoItem> | null;
  nota_fiscal?: string | null;
  numero?: string | null;
  previsao_entrega?: string | null;
  status_rotulo?: string | null;
  tom?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoAtualizar;

pub struct PedidoAtualizar {
    pub cotacao_origem: Option<String>,
    pub data_faturamento: Option<chrono::NaiveDate>,
    pub entregue: Option<bool>,
    pub itens: Option<Vec<PedidoItem>>,
    pub nota_fiscal: Option<String>,
    pub numero: Option<String>,
    pub previsao_entrega: Option<chrono::NaiveDate>,
    pub status_rotulo: Option<String>,
    pub tom: Option<String>,
}
```

</Tab>
</Tabs>

### PedidoCriar [#tipo-pedidocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoCriar } from "termo_core/portal";

export interface PedidoCriar {
  cotacao_origem?: string | null;
  data_faturamento: string;
  entregue?: boolean | null;
  itens?: Array<PedidoItem> | null;
  nota_fiscal?: string | null;
  numero: string;
  previsao_entrega: string;
  status_rotulo: string;
  tom?: string | null;
  unidade_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoCriar;

pub struct PedidoCriar {
    pub cotacao_origem: Option<String>,
    pub data_faturamento: chrono::NaiveDate,
    pub entregue: Option<bool>,
    pub itens: Option<Vec<PedidoItem>>,
    pub nota_fiscal: Option<String>,
    pub numero: String,
    pub previsao_entrega: chrono::NaiveDate,
    pub status_rotulo: String,
    pub tom: Option<String>,
    pub unidade_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PedidoItem [#tipo-pedidoitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoItem } from "termo_core/portal";

export interface PedidoItem {
  produto: string;
  quantidade: string;
  sku: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoItem;

pub struct PedidoItem {
    pub produto: String,
    pub quantidade: String,
    pub sku: String,
}
```

</Tab>
</Tabs>


# Pedido venda (/docs/servicos/portal/pedido_venda)

> 3 funções do TermoPortal para pedido venda.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_pedido_venda`](#buscar_paginador_pedido_venda) | `GET /pedido_venda` | Lista os pedidos de venda do ERP |
| [`buscar_pelo_filtro_pedido_venda`](#buscar_pelo_filtro_pedido_venda) | `GET /pedido_venda/filtro` | Acha o pedido de venda de uma entrega |
| [`buscar_pelo_id_pedido_venda`](#buscar_pelo_id_pedido_venda) | `GET /pedido_venda/{id}` | Busca um pedido de venda do ERP pelo id |

## `buscar_paginador_pedido_venda` [#buscar_paginador_pedido_venda]

<Rota metodo="GET" caminho="/pedido_venda" credencial />

Lista os pedidos de venda do ERP

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Consulta na hora os pedidos de venda do Tiny pela API da Termotubos. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só vê os pedidos do CNPJ dela, sem vendedor, canal e observações internas; colaborador interno pode omitir e ver todos. Filtros: `situacao` (`todos`, `aberto`, `aprovado`, `faturado`, `pronto`, `enviado`, `entregue`, `cancelado`; padrão `todos`), `busca` (texto), `inicio` e `fim` (AAAA-MM-DD) e `vendedor` (id no Tiny). 50 pedidos por página; `pagina` começa em 1. A resposta traz `itens`, `pagina`, `total_paginas`, `total_registros`, a contagem por situação e um resumo (pedidos de hoje e do mês). Até 60 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_pedido_venda(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPedidoVenda = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPedidosVenda>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_pedido_venda } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_pedido_venda(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_pedido_venda(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPedidoVenda,
) -> Result<tipos::PaginaPedidosVenda, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_pedido_venda(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorPedidoVenda { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPedidosVenda>` · Rust: `Result<tipos::PaginaPedidosVenda, ErroAoChamarServico>` · veja [`PaginaPedidosVenda`](#tipo-paginapedidosvenda).

## `buscar_pelo_filtro_pedido_venda` [#buscar_pelo_filtro_pedido_venda]

<Rota metodo="GET" caminho="/pedido_venda/filtro" credencial />

Acha o pedido de venda de uma entrega

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Procura no Tiny o pedido de venda que gerou a entrega `expedicao_id` (id da entrega na API de logística) e devolve o `id` do pedido, para abrir em `GET /pedido_venda/{id}`. Quem não é colaborador interno só acha pedidos das próprias unidades.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_pedido_venda(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPedidoVenda,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PedidoDaEntrega>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_pedido_venda } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_pedido_venda(credencial_de_acesso, { expedicao_id });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_pedido_venda(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPedidoVenda,
) -> Result<tipos::PedidoDaEntrega, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_pedido_venda(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroPedidoVenda { expedicao_id },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.expedicao_id": { type: "number", required: true, description: "Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PedidoDaEntrega>` · Rust: `Result<tipos::PedidoDaEntrega, ErroAoChamarServico>` · veja [`PedidoDaEntrega`](#tipo-pedidodaentrega).

## `buscar_pelo_id_pedido_venda` [#buscar_pelo_id_pedido_venda]

<Rota metodo="GET" caminho="/pedido_venda/{id}" credencial />

Busca um pedido de venda do ERP pelo id

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Consulta o pedido no Tiny com itens, valores, pagamento e rastreio, mais a entrega ligada a ele quando houver. Quem não é colaborador interno só abre pedidos do CNPJ das próprias unidades (os outros respondem 404) e não recebe vendedor, canal e observações internas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_pedido_venda(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PedidoVendaDetalhe>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_pedido_venda } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_pedido_venda(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_pedido_venda(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::PedidoVendaDetalhe, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_pedido_venda(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PedidoVendaDetalhe>` · Rust: `Result<tipos::PedidoVendaDetalhe, ErroAoChamarServico>` · veja [`PedidoVendaDetalhe`](#tipo-pedidovendadetalhe).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ContagemPedidosVenda [#tipo-contagempedidosvenda]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContagemPedidosVenda } from "termo_core/portal";

export interface ContagemPedidosVenda {
  aberto: number;
  aprovado: number;
  cancelado: number;
  entregue: number;
  enviado: number;
  faturado: number;
  pronto: number;
  todos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContagemPedidosVenda;

pub struct ContagemPedidosVenda {
    pub aberto: i64,
    pub aprovado: i64,
    pub cancelado: i64,
    pub entregue: i64,
    pub enviado: i64,
    pub faturado: i64,
    pub pronto: i64,
    pub todos: i64,
}
```

</Tab>
</Tabs>

### ExpedicaoTermotubos [#tipo-expedicaotermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ExpedicaoTermotubos } from "termo_core/portal";

export interface ExpedicaoTermotubos {
  atualizado_em?: string | null;
  cep?: string | null;
  cidade?: string | null;
  cliente?: string | null;
  cliente_documento?: string | null;
  codigo_rastreio?: string | null;
  emissao?: string | null;
  entrega?: string | null;
  envio?: string | null;
  frete?: number | null;
  id: number;
  link_rastreio?: string | null;
  nota_fiscal?: number | null;
  nota_tiny_id?: number | null;
  ocorrencia?: string | null;
  peso_kg?: number | null;
  previsao?: string | null;
  situacao?: string | null;
  situacao_id?: number | null;
  transportadora?: string | null;
  transportadora_documento?: string | null;
  uf?: string | null;
  valor_mercadorias?: number | null;
  valor_nota?: number | null;
  vendedor?: string | null;
  vendedor_tiny_id?: number | null;
  volumes?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ExpedicaoTermotubos;

pub struct ExpedicaoTermotubos {
    pub atualizado_em: Option<String>,
    pub cep: Option<String>,
    pub cidade: Option<String>,
    pub cliente: Option<String>,
    pub cliente_documento: Option<String>,
    pub codigo_rastreio: Option<String>,
    pub emissao: Option<String>,
    pub entrega: Option<String>,
    pub envio: Option<String>,
    pub frete: Option<f64>,
    pub id: i64,
    pub link_rastreio: Option<String>,
    pub nota_fiscal: Option<i64>,
    pub nota_tiny_id: Option<i64>,
    pub ocorrencia: Option<String>,
    pub peso_kg: Option<f64>,
    pub previsao: Option<String>,
    pub situacao: Option<String>,
    pub situacao_id: Option<i64>,
    pub transportadora: Option<String>,
    pub transportadora_documento: Option<String>,
    pub uf: Option<String>,
    pub valor_mercadorias: Option<f64>,
    pub valor_nota: Option<f64>,
    pub vendedor: Option<String>,
    pub vendedor_tiny_id: Option<i64>,
    pub volumes: Option<i64>,
}
```

</Tab>
</Tabs>

### ItemPedidoVenda [#tipo-itempedidovenda]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ItemPedidoVenda } from "termo_core/portal";

export interface ItemPedidoVenda {
  descricao?: string | null;
  preco_unitario?: number | null;
  quantidade?: number | null;
  sku?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ItemPedidoVenda;

pub struct ItemPedidoVenda {
    pub descricao: Option<String>,
    pub preco_unitario: Option<f64>,
    pub quantidade: Option<f64>,
    pub sku: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaPedidosVenda [#tipo-paginapedidosvenda]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPedidosVenda } from "termo_core/portal";

export interface PaginaPedidosVenda {
  contagens: ContagemPedidosVenda;
  itens: Array<PedidoVendaTermotubos>;
  pagina: number;
  resumo: ResumoPedidosVenda;
  total_paginas: number;
  total_registros: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPedidosVenda;

pub struct PaginaPedidosVenda {
    pub contagens: ContagemPedidosVenda,
    pub itens: Vec<PedidoVendaTermotubos>,
    pub pagina: i32,
    pub resumo: ResumoPedidosVenda,
    pub total_paginas: i32,
    pub total_registros: i64,
}
```

</Tab>
</Tabs>

### PedidoDaEntrega [#tipo-pedidodaentrega]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoDaEntrega } from "termo_core/portal";

export interface PedidoDaEntrega {
  id: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoDaEntrega;

pub struct PedidoDaEntrega {
    pub id: i64,
}
```

</Tab>
</Tabs>

### PedidoVendaDetalhe [#tipo-pedidovendadetalhe]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoVendaDetalhe } from "termo_core/portal";

export type PedidoVendaDetalhe = PedidoVendaTermotubos & PedidoVendaDetalheParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoVendaDetalhe;

pub type PedidoVendaDetalhe = serde_json::Value;
```

</Tab>
</Tabs>

### PedidoVendaDetalheParte2 [#tipo-pedidovendadetalheparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoVendaDetalheParte2 } from "termo_core/portal";

export interface PedidoVendaDetalheParte2 {
  entrega?: ExpedicaoTermotubos | null;
}
```

</Tab>
<Tab value="Rust">

`termo_core::portal::PedidoVendaDetalheParte2`

</Tab>
</Tabs>

### PedidoVendaTermotubos [#tipo-pedidovendatermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoVendaTermotubos } from "termo_core/portal";

export interface PedidoVendaTermotubos {
  canal?: string | null;
  cidade?: string | null;
  cliente?: string | null;
  cliente_documento?: string | null;
  cliente_tiny_id?: number | null;
  codigo_rastreio?: string | null;
  data?: string | null;
  desconto?: number | null;
  entregue_em?: string | null;
  enviado_em?: string | null;
  faturado_em?: string | null;
  forma_envio?: string | null;
  frete?: number | null;
  id: number;
  itens: Array<ItemPedidoVenda>;
  link_rastreio?: string | null;
  marcadores: Array<string>;
  nota_tiny_id?: number | null;
  numero?: number | null;
  numero_no_canal?: string | null;
  observacoes?: string | null;
  observacoes_internas?: string | null;
  outros?: number | null;
  pagamento?: string | null;
  previsao?: string | null;
  situacao_id?: number | null;
  transportadora?: string | null;
  uf?: string | null;
  valor?: number | null;
  valor_produtos?: number | null;
  vendedor?: string | null;
  vendedor_tiny_id?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoVendaTermotubos;

pub struct PedidoVendaTermotubos {
    pub canal: Option<String>,
    pub cidade: Option<String>,
    pub cliente: Option<String>,
    pub cliente_documento: Option<String>,
    pub cliente_tiny_id: Option<i64>,
    pub codigo_rastreio: Option<String>,
    pub data: Option<String>,
    pub desconto: Option<f64>,
    pub entregue_em: Option<String>,
    pub enviado_em: Option<String>,
    pub faturado_em: Option<String>,
    pub forma_envio: Option<String>,
    pub frete: Option<f64>,
    pub id: i64,
    pub itens: Vec<ItemPedidoVenda>,
    pub link_rastreio: Option<String>,
    pub marcadores: Vec<String>,
    pub nota_tiny_id: Option<i64>,
    pub numero: Option<i64>,
    pub numero_no_canal: Option<String>,
    pub observacoes: Option<String>,
    pub observacoes_internas: Option<String>,
    pub outros: Option<f64>,
    pub pagamento: Option<String>,
    pub previsao: Option<String>,
    pub situacao_id: Option<i64>,
    pub transportadora: Option<String>,
    pub uf: Option<String>,
    pub valor: Option<f64>,
    pub valor_produtos: Option<f64>,
    pub vendedor: Option<String>,
    pub vendedor_tiny_id: Option<i64>,
}
```

</Tab>
</Tabs>

### ResumoPedidosVenda [#tipo-resumopedidosvenda]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResumoPedidosVenda } from "termo_core/portal";

export interface ResumoPedidosVenda {
  pedidos_hoje: number;
  pedidos_no_mes: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ResumoPedidosVenda;

pub struct ResumoPedidosVenda {
    pub pedidos_hoje: i64,
    pub pedidos_no_mes: i64,
}
```

</Tab>
</Tabs>


# Pedido venda Tiny (/docs/servicos/portal/pedido_venda_tiny)

> 5 funções do TermoPortal para pedido venda tiny.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_pedido_venda_tiny`](#buscar_paginador_pedido_venda_tiny) | `GET /pedido_venda_tiny` | Paginador dos pedidos de venda salvos no portal |
| [`criar_pedido_venda_tiny`](#criar_pedido_venda_tiny) | `POST /pedido_venda_tiny` | Sincroniza um lote de pedidos de venda com a Intranet |
| [`buscar_auto_complete_pedido_venda_tiny`](#buscar_auto_complete_pedido_venda_tiny) | `GET /pedido_venda_tiny/autocomplete` | Autocomplete dos pedidos de venda salvos no portal |
| [`buscar_pelo_filtro_pedido_venda_tiny`](#buscar_pelo_filtro_pedido_venda_tiny) | `GET /pedido_venda_tiny/filtro` | Uma página de pedidos de venda salvos no portal |
| [`buscar_pelo_id_pedido_venda_tiny`](#buscar_pelo_id_pedido_venda_tiny) | `GET /pedido_venda_tiny/{id}` | Um pedido de venda salvo no portal |

## `buscar_paginador_pedido_venda_tiny` [#buscar_paginador_pedido_venda_tiny]

<Rota metodo="GET" caminho="/pedido_venda_tiny" credencial />

Paginador dos pedidos de venda salvos no portal

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só recebe os pedidos do CNPJ dela, sem vendedor, canal e marcadores; colaborador interno pode omitir e ver todos. Lê a cópia dos pedidos de venda da Intranet salva no banco do portal (atualizada por `POST /pedido_venda_tiny`) e devolve só a paginação, sem os itens (eles vêm de `GET /pedido_venda_tiny/filtro`): `pagina`, `por_pagina` (sempre 50), `total_paginas`, `total_registros` da situação pedida, a contagem por situação e `sincronizado_em` (a última sincronização). Filtros iguais aos da lista: `situacao` (`todos`, `aberto`, `aprovado`, `faturado`, `pronto`, `enviado`, `entregue`, `cancelado`; padrão `todos`), `busca` (CNPJ/CPF, número do pedido ou nome do cliente), `inicio` e `fim` (AAAA-MM-DD, data do pedido) e `vendedor` (id do vendedor no Tiny, só para colaborador interno).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_pedido_venda_tiny(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPedidoVendaTiny = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginadorPedidosVendaTiny>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_pedido_venda_tiny } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_pedido_venda_tiny(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_pedido_venda_tiny(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPedidoVendaTiny,
) -> Result<tipos::PaginadorPedidosVendaTiny, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_pedido_venda_tiny(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorPedidoVendaTiny { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor_nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.canal": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.forma_envio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.marcadores": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginadorPedidosVendaTiny>` · Rust: `Result<tipos::PaginadorPedidosVendaTiny, ErroAoChamarServico>` · veja [`PaginadorPedidosVendaTiny`](#tipo-paginadorpedidosvendatiny).

## `criar_pedido_venda_tiny` [#criar_pedido_venda_tiny]

<Rota metodo="POST" caminho="/pedido_venda_tiny" credencial />

Sincroniza um lote de pedidos de venda com a Intranet

Só colaborador interno com a permissão `ver` no módulo `Pedidos`. Lê 10 páginas (500 pedidos) da Intranet a partir de `pagina` (começa em 1) e grava no banco do portal, criando ou atualizando pelo id da Intranet. `modo`: `recentes` (padrão, os pedidos dos últimos 90 dias) ou `tudo` (todos os pedidos). Para sincronizar tudo, chame de novo com `proxima_pagina` até ela vir `null`. O backend também sincroniza sozinho: os últimos dias a cada 15 min e os últimos 90 dias a cada 6 h (`SINCRONIZACAO_*` no `.env`). Até 120 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_pedido_venda_tiny(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PedidoVendaTinySincronizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SincronizacaoPedidosVendaTiny>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_pedido_venda_tiny } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_pedido_venda_tiny(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_pedido_venda_tiny(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PedidoVendaTinySincronizar,
) -> Result<tipos::SincronizacaoPedidosVendaTiny, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_pedido_venda_tiny(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PedidoVendaTinySincronizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PedidoVendaTinySincronizar", typeDescriptionLink: "#tipo-pedidovendatinysincronizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SincronizacaoPedidosVendaTiny>` · Rust: `Result<tipos::SincronizacaoPedidosVendaTiny, ErroAoChamarServico>` · veja [`SincronizacaoPedidosVendaTiny`](#tipo-sincronizacaopedidosvendatiny).

## `buscar_auto_complete_pedido_venda_tiny` [#buscar_auto_complete_pedido_venda_tiny]

<Rota metodo="GET" caminho="/pedido_venda_tiny/autocomplete" credencial />

Autocomplete dos pedidos de venda salvos no portal

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só recebe pedidos do CNPJ dela. Devolve só `id` (id na Intranet) e `rotulo` (`#número - cliente`), em ordem alfabética do cliente. `busca`: número do pedido (até 10 dígitos, `#` opcional) ou palavras do nome do cliente (por prefixo, sem acento). `pagina` começa em 1; `tamanho` padrão 10, máximo 50.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_pedido_venda_tiny(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePedidoVendaTiny = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPedidosVendaTinyAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_pedido_venda_tiny } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_pedido_venda_tiny(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_pedido_venda_tiny(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePedidoVendaTiny,
) -> Result<tipos::PaginaPedidosVendaTinyAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_pedido_venda_tiny(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompletePedidoVendaTiny { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPedidosVendaTinyAutoComplete>` · Rust: `Result<tipos::PaginaPedidosVendaTinyAutoComplete, ErroAoChamarServico>` · veja [`PaginaPedidosVendaTinyAutoComplete`](#tipo-paginapedidosvendatinyautocomplete).

## `buscar_pelo_filtro_pedido_venda_tiny` [#buscar_pelo_filtro_pedido_venda_tiny]

<Rota metodo="GET" caminho="/pedido_venda_tiny/filtro" credencial />

Uma página de pedidos de venda salvos no portal

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só recebe os pedidos do CNPJ dela, sem vendedor, canal e marcadores; colaborador interno pode omitir e ver todos. Devolve só os itens de uma página (sempre 50, sem como mudar), do pedido mais recente para o mais antigo; a paginação e as contagens vêm de `GET /pedido_venda_tiny`. `pagina` começa em 1. Filtros: `situacao` (`todos`, `aberto`, `aprovado`, `faturado`, `pronto`, `enviado`, `entregue`, `cancelado`; padrão `todos`), `busca` (14 ou 11 dígitos = CNPJ/CPF; até 10 dígitos = número do pedido; texto = palavras do nome do cliente, por prefixo e sem acento), `inicio` e `fim` (AAAA-MM-DD, data do pedido) e `vendedor` (id do vendedor no Tiny). O detalhe de um pedido continua em `GET /pedido_venda/{id}`, com o `id` daqui.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_pedido_venda_tiny(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPedidoVendaTiny = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PedidoVendaTiny>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_pedido_venda_tiny } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_pedido_venda_tiny(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_pedido_venda_tiny(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPedidoVendaTiny,
) -> Result<Vec<tipos::PedidoVendaTiny>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_pedido_venda_tiny(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroPedidoVendaTiny { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor_nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.canal": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.forma_envio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.marcadores": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PedidoVendaTiny>>` · Rust: `Result<Vec<tipos::PedidoVendaTiny>, ErroAoChamarServico>`

## `buscar_pelo_id_pedido_venda_tiny` [#buscar_pelo_id_pedido_venda_tiny]

<Rota metodo="GET" caminho="/pedido_venda_tiny/{id}" credencial />

Um pedido de venda salvo no portal

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só acha pedidos do CNPJ dela, sem vendedor, canal e marcadores. `id` é o id do pedido na Intranet (o mesmo da lista). Devolve só o resumo salvo no portal; os itens e o detalhe completo vêm de `GET /pedido_venda/{id}`. Pedidos são só leitura: não há `PATCH` nem `DELETE`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_pedido_venda_tiny(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  parametros: ParametrosDeBuscarPeloIdPedidoVendaTiny = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PedidoVendaTiny>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_pedido_venda_tiny } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_pedido_venda_tiny(credencial_de_acesso, id, { unidade_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_pedido_venda_tiny(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
    parametros: &ParametrosDeBuscarPeloIdPedidoVendaTiny,
) -> Result<tipos::PedidoVendaTiny, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_pedido_venda_tiny(
    &credencial_de_acesso,
    id,
    &termo_core::portal::ParametrosDeBuscarPeloIdPedidoVendaTiny { unidade_id: Some(Default::default()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PedidoVendaTiny>` · Rust: `Result<tipos::PedidoVendaTiny, ErroAoChamarServico>` · veja [`PedidoVendaTiny`](#tipo-pedidovendatiny).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ContagemPedidosVenda [#tipo-contagempedidosvenda]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContagemPedidosVenda } from "termo_core/portal";

export interface ContagemPedidosVenda {
  aberto: number;
  aprovado: number;
  cancelado: number;
  entregue: number;
  enviado: number;
  faturado: number;
  pronto: number;
  todos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContagemPedidosVenda;

pub struct ContagemPedidosVenda {
    pub aberto: i64,
    pub aprovado: i64,
    pub cancelado: i64,
    pub entregue: i64,
    pub enviado: i64,
    pub faturado: i64,
    pub pronto: i64,
    pub todos: i64,
}
```

</Tab>
</Tabs>

### PaginadorPedidosVendaTiny [#tipo-paginadorpedidosvendatiny]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginadorPedidosVendaTiny } from "termo_core/portal";

export interface PaginadorPedidosVendaTiny {
  contagens: ContagemPedidosVenda;
  pagina: number;
  por_pagina: number;
  sincronizado_em?: string | null;
  total_paginas: number;
  total_registros: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginadorPedidosVendaTiny;

pub struct PaginadorPedidosVendaTiny {
    pub contagens: ContagemPedidosVenda,
    pub pagina: i32,
    pub por_pagina: i64,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub total_paginas: i64,
    pub total_registros: i64,
}
```

</Tab>
</Tabs>

### PaginaPedidosVendaTinyAutoComplete [#tipo-paginapedidosvendatinyautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPedidosVendaTinyAutoComplete } from "termo_core/portal";

export interface PaginaPedidosVendaTinyAutoComplete {
  itens: Array<PedidoVendaTinyAutoComplete>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPedidosVendaTinyAutoComplete;

pub struct PaginaPedidosVendaTinyAutoComplete {
    pub itens: Vec<PedidoVendaTinyAutoComplete>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PedidoVendaTiny [#tipo-pedidovendatiny]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoVendaTiny } from "termo_core/portal";

export interface PedidoVendaTiny {
  canal?: string | null;
  cidade?: string | null;
  cliente?: string | null;
  cliente_documento?: string | null;
  codigo_rastreio?: string | null;
  data?: string | null;
  forma_envio?: string | null;
  id: number;
  link_rastreio?: string | null;
  marcadores: Array<string>;
  numero?: number | null;
  numero_no_canal?: string | null;
  previsao?: string | null;
  situacao_id?: number | null;
  transportadora?: string | null;
  uf?: string | null;
  valor?: number | null;
  vendedor?: string | null;
  vendedor_tiny_id?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoVendaTiny;

pub struct PedidoVendaTiny {
    pub canal: Option<String>,
    pub cidade: Option<String>,
    pub cliente: Option<String>,
    pub cliente_documento: Option<String>,
    pub codigo_rastreio: Option<String>,
    pub data: Option<chrono::NaiveDate>,
    pub forma_envio: Option<String>,
    pub id: i64,
    pub link_rastreio: Option<String>,
    pub marcadores: Vec<String>,
    pub numero: Option<i64>,
    pub numero_no_canal: Option<String>,
    pub previsao: Option<chrono::NaiveDate>,
    pub situacao_id: Option<i64>,
    pub transportadora: Option<String>,
    pub uf: Option<String>,
    pub valor: Option<f64>,
    pub vendedor: Option<String>,
    pub vendedor_tiny_id: Option<i64>,
}
```

</Tab>
</Tabs>

### PedidoVendaTinyAutoComplete [#tipo-pedidovendatinyautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoVendaTinyAutoComplete } from "termo_core/portal";

export interface PedidoVendaTinyAutoComplete {
  id: number;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoVendaTinyAutoComplete;

pub struct PedidoVendaTinyAutoComplete {
    pub id: i64,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PedidoVendaTinySincronizar [#tipo-pedidovendatinysincronizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PedidoVendaTinySincronizar } from "termo_core/portal";

export interface PedidoVendaTinySincronizar {
  modo?: string | null;
  pagina?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PedidoVendaTinySincronizar;

pub struct PedidoVendaTinySincronizar {
    pub modo: Option<String>,
    pub pagina: Option<i32>,
}
```

</Tab>
</Tabs>

### SincronizacaoPedidosVendaTiny [#tipo-sincronizacaopedidosvendatiny]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SincronizacaoPedidosVendaTiny } from "termo_core/portal";

export interface SincronizacaoPedidosVendaTiny {
  gravados: number;
  modo: string;
  pagina: number;
  proxima_pagina?: number | null;
  total_paginas: number;
  total_registros: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::SincronizacaoPedidosVendaTiny;

pub struct SincronizacaoPedidosVendaTiny {
    pub gravados: i64,
    pub modo: String,
    pub pagina: i32,
    pub proxima_pagina: Option<i32>,
    pub total_paginas: i32,
    pub total_registros: i64,
}
```

</Tab>
</Tabs>


# Perfil (/docs/servicos/portal/perfil)

> 7 funções do TermoPortal para perfil.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil`](#buscar_paginador_perfil) | `GET /perfil` | Lista os perfis paginados |
| [`criar_perfil`](#criar_perfil) | `POST /perfil` | Cadastra um perfil de acesso |
| [`buscar_auto_complete_perfil`](#buscar_auto_complete_perfil) | `GET /perfil/autocomplete` | Lista básica de perfis para seleção |
| [`buscar_pelo_filtro_perfil`](#buscar_pelo_filtro_perfil) | `GET /perfil/filtro` | Busca perfis por filtro |
| [`buscar_pelo_id_perfil`](#buscar_pelo_id_perfil) | `GET /perfil/{id}` | Busca um perfil pelo id |
| [`atualizar_pelo_id_perfil`](#atualizar_pelo_id_perfil) | `PATCH /perfil/{id}` | Atualiza um perfil de acesso |
| [`deletar_pelo_id_perfil`](#deletar_pelo_id_perfil) | `DELETE /perfil/{id}` | Exclui um perfil de acesso |

## `buscar_paginador_perfil` [#buscar_paginador_perfil]

<Rota metodo="GET" caminho="/perfil" credencial />

Lista os perfis paginados

Exige só uma sessão válida (qualquer pessoa logada no portal). Ordem alfabética. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfil = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfil>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfil,
) -> Result<tipos::PaginaPerfil, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_perfil(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorPerfil { pagina: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfil>` · Rust: `Result<tipos::PaginaPerfil, ErroAoChamarServico>` · veja [`PaginaPerfil`](#tipo-paginaperfil).

## `criar_perfil` [#criar_perfil]

<Rota metodo="POST" caminho="/perfil" credencial />

Cadastra um perfil de acesso

Exige perfil administrador ou master. Perfil de acesso (RBAC) das pessoas do portal. `nome` obrigatório, até 120 caracteres e único (o `slug` sai do nome); `resumo` até 500; `tipo` é `termotubos` ou `cliente`; `base: true` marca o perfil dado ao cliente novo (só um, só de cliente, nunca administrador); `permissoes` por módulo (`Dashboard`, `Pedidos`, `Financeiro`, `Catalogo`, `Cotacoes`, `Assistente`, `Configuracoes`) com `ver`, `criar`, `editar`, `excluir` e a exibição no menu; `permissoes_administrativas` entre `contexto_administrativo.entrar`, `unidades.ler`, `pedidos.ler_todos`, `cotacoes.ler_todas`, `financeiro.ler_todos` e `usuarios.gerenciar`. Cada item de `permissoes` tem `modulo`, `pagina` (página do módulo; `*` vale para o módulo inteiro, padrão), `ver`, `criar`, `editar`, `excluir` (booleanos) e `mostrar_na_sidebar` e `mostrar_nas_configuracoes` (booleanos, exibição no menu). Campos: `base` (booleano) marca o perfil dado ao cliente novo (só um, só de cliente).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Perfil>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilCriar,
) -> Result<tipos::Perfil, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_perfil(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilCriar", typeDescriptionLink: "#tipo-perfilcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Perfil>` · Rust: `Result<tipos::Perfil, ErroAoChamarServico>` · veja [`Perfil`](#tipo-perfil).

## `buscar_auto_complete_perfil` [#buscar_auto_complete_perfil]

<Rota metodo="GET" caminho="/perfil/autocomplete" credencial />

Lista básica de perfis para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve só id e nome, em ordem alfabética. `busca` procura no nome. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfil = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfil,
) -> Result<tipos::PaginaPerfilAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_perfil(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompletePerfil { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAutoComplete`](#tipo-paginaperfilautocomplete).

## `buscar_pelo_filtro_perfil` [#buscar_pelo_filtro_perfil]

<Rota metodo="GET" caminho="/perfil/filtro" credencial />

Busca perfis por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve os perfis não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), em ordem alfabética. `nome` procura o trecho; `slug`, `base` e `tipo` são exatos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfil = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Perfil>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfil,
) -> Result<Vec<tipos::Perfil>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_perfil(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroPerfil { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.slug": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.base": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Perfil>>` · Rust: `Result<Vec<tipos::Perfil>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil` [#buscar_pelo_id_perfil]

<Rota metodo="GET" caminho="/perfil/{id}" credencial />

Busca um perfil pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Perfil excluído não é encontrado. Traz permissões e quantidade de pessoas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Perfil>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Perfil, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_perfil(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Perfil>` · Rust: `Result<tipos::Perfil, ErroAoChamarServico>` · veja [`Perfil`](#tipo-perfil).

## `atualizar_pelo_id_perfil` [#atualizar_pelo_id_perfil]

<Rota metodo="PATCH" caminho="/perfil/{id}" credencial />

Atualiza um perfil de acesso

Exige perfil administrador ou master. Mesmas regras do cadastro; o tipo não muda. `permissoes` e `permissoes_administrativas`, quando enviados, substituem as anteriores. Cada item de `permissoes` tem `modulo`, `pagina` (página do módulo; `*` vale para o módulo inteiro, padrão), `ver`, `criar`, `editar`, `excluir` (booleanos) e `mostrar_na_sidebar` e `mostrar_nas_configuracoes` (booleanos, exibição no menu). Atualização parcial: campo ausente mantém o valor atual. Campos: `nome` é obrigatório quando enviado (mesmo limite do cadastro); `resumo` até 500 caracteres; `base` (booleano) marca o perfil dado ao cliente novo (só um, só de cliente).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Perfil>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAtualizar,
) -> Result<tipos::Perfil, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_perfil(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAtualizar", typeDescriptionLink: "#tipo-perfilatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Perfil>` · Rust: `Result<tipos::Perfil, ErroAoChamarServico>` · veja [`Perfil`](#tipo-perfil).

## `deletar_pelo_id_perfil` [#deletar_pelo_id_perfil]

<Rota metodo="DELETE" caminho="/perfil/{id}" credencial />

Exclui um perfil de acesso

Exige perfil administrador ou master. Recusa o perfil base e perfis com pessoas vinculadas. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_perfil(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaPerfil [#tipo-paginaperfil]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfil } from "termo_core/portal";

export interface PaginaPerfil {
  itens: Array<PaginaPerfilItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPerfil;

pub struct PaginaPerfil {
    pub itens: Vec<PaginaPerfilItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAutoComplete [#tipo-paginaperfilautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAutoComplete } from "termo_core/portal";

export interface PaginaPerfilAutoComplete {
  itens: Array<PaginaPerfilAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPerfilAutoComplete;

pub struct PaginaPerfilAutoComplete {
    pub itens: Vec<PaginaPerfilAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAutoCompleteItensItem [#tipo-paginaperfilautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaPerfilAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPerfilAutoCompleteItensItem;

pub struct PaginaPerfilAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilItensItem [#tipo-paginaperfilitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilItensItem } from "termo_core/portal";

export interface PaginaPerfilItensItem {
  atualizado_em: string;
  base: boolean;
  criado_em: string;
  id: string;
  nome: string;
  permissoes: Array<PerfilPermissao>;
  permissoes_administrativas: Array<string>;
  quantidade_pessoas: number;
  resumo?: string | null;
  slug: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaPerfilItensItem;

pub struct PaginaPerfilItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub base: bool,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Vec<PerfilPermissao>,
    pub permissoes_administrativas: Vec<String>,
    pub quantidade_pessoas: i64,
    pub resumo: Option<String>,
    pub slug: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### Perfil [#tipo-perfil]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Perfil } from "termo_core/portal";

export interface Perfil {
  atualizado_em: string;
  base: boolean;
  criado_em: string;
  id: string;
  nome: string;
  permissoes: Array<PerfilPermissao>;
  permissoes_administrativas: Array<string>;
  quantidade_pessoas: number;
  resumo?: string | null;
  slug: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Perfil;

pub struct Perfil {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub base: bool,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Vec<PerfilPermissao>,
    pub permissoes_administrativas: Vec<String>,
    pub quantidade_pessoas: i64,
    pub resumo: Option<String>,
    pub slug: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### PerfilAtualizar [#tipo-perfilatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAtualizar } from "termo_core/portal";

export interface PerfilAtualizar {
  base?: boolean | null;
  nome?: string | null;
  permissoes?: Array<PerfilPermissaoEntrada> | null;
  permissoes_administrativas?: Array<string> | null;
  resumo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PerfilAtualizar;

pub struct PerfilAtualizar {
    pub base: Option<bool>,
    pub nome: Option<String>,
    pub permissoes: Option<Vec<PerfilPermissaoEntrada>>,
    pub permissoes_administrativas: Option<Vec<String>>,
    pub resumo: Option<String>,
}
```

</Tab>
</Tabs>

### PerfilCriar [#tipo-perfilcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilCriar } from "termo_core/portal";

export interface PerfilCriar {
  base?: boolean | null;
  nome: string;
  permissoes?: Array<PerfilPermissaoEntrada> | null;
  permissoes_administrativas?: Array<string> | null;
  resumo?: string | null;
  tipo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PerfilCriar;

pub struct PerfilCriar {
    pub base: Option<bool>,
    pub nome: String,
    pub permissoes: Option<Vec<PerfilPermissaoEntrada>>,
    pub permissoes_administrativas: Option<Vec<String>>,
    pub resumo: Option<String>,
    pub tipo: Option<String>,
}
```

</Tab>
</Tabs>

### PerfilPermissao [#tipo-perfilpermissao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilPermissao } from "termo_core/portal";

export interface PerfilPermissao {
  criar: boolean;
  editar: boolean;
  excluir: boolean;
  modulo: string;
  mostrar_na_sidebar: boolean;
  mostrar_nas_configuracoes: boolean;
  pagina: string;
  ver: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PerfilPermissao;

pub struct PerfilPermissao {
    pub criar: bool,
    pub editar: bool,
    pub excluir: bool,
    pub modulo: String,
    pub mostrar_na_sidebar: bool,
    pub mostrar_nas_configuracoes: bool,
    pub pagina: String,
    pub ver: bool,
}
```

</Tab>
</Tabs>

### PerfilPermissaoEntrada [#tipo-perfilpermissaoentrada]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilPermissaoEntrada } from "termo_core/portal";

export interface PerfilPermissaoEntrada {
  criar: boolean;
  editar: boolean;
  excluir: boolean;
  modulo: string;
  mostrar_na_sidebar?: boolean | null;
  mostrar_nas_configuracoes?: boolean | null;
  pagina?: string | null;
  ver: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PerfilPermissaoEntrada;

pub struct PerfilPermissaoEntrada {
    pub criar: bool,
    pub editar: bool,
    pub excluir: bool,
    pub modulo: String,
    pub mostrar_na_sidebar: Option<bool>,
    pub mostrar_nas_configuracoes: Option<bool>,
    pub pagina: Option<String>,
    pub ver: bool,
}
```

</Tab>
</Tabs>


# Produto (/docs/servicos/portal/produto)

> 7 funções do TermoPortal para produto.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_produto`](#buscar_paginador_produto) | `GET /produto` | Lista os produtos paginados |
| [`criar_produto`](#criar_produto) | `POST /produto` | Cadastra um produto |
| [`buscar_auto_complete_produto`](#buscar_auto_complete_produto) | `GET /produto/autocomplete` | Lista básica de produtos para seleção |
| [`buscar_pelo_filtro_produto`](#buscar_pelo_filtro_produto) | `GET /produto/filtro` | Busca produtos por filtro |
| [`buscar_pelo_id_produto`](#buscar_pelo_id_produto) | `GET /produto/{id}` | Busca um produto pelo id |
| [`atualizar_pelo_id_produto`](#atualizar_pelo_id_produto) | `PATCH /produto/{id}` | Atualiza um produto |
| [`deletar_pelo_id_produto`](#deletar_pelo_id_produto) | `DELETE /produto/{id}` | Exclui um produto |

## `buscar_paginador_produto` [#buscar_paginador_produto]

<Rota metodo="GET" caminho="/produto" credencial />

Lista os produtos paginados

Exige só uma sessão válida (qualquer pessoa logada no portal). `ordem` aceita `relevancia` (padrão: relevância, depois nome), `menor-preco`/`maior-preco` (preço à vista, ou o preço base quando o à vista é zero), `az`/`za` (nome), `mais-novo`/`mais-antigo` (data de cadastro); o desempate é sempre nome e id; outro valor responde 400 `Ordem inválida`. Filtros opcionais (todos combinam com E): `sku` exato e `skus` vários separados por vírgula (sem diferenciar maiúsculas); `nome` procura o trecho no nome, no SKU e no nome comercial, sem diferenciar maiúsculas nem acentos; `ativo`, `lancamento`, `importado_da_api`, `demonstracao` e `preco_definido_no_portal` são exatos; `tem_imagem` (ao menos uma imagem), `tem_estoque` (estoque maior que zero), `tem_descricao`, `tem_nome_comercial`, `tem_heuristica_pendente` e `enriquecido` (já enriquecido pelo Tiny) aceitam `true` ou `false`; `estoque_minimo`/`estoque_maximo` e `preco_minimo`/`preco_maximo` são faixas inclusivas; `unidade` é exata e `cor`, `material`, `diametro`, `categoria_tiny` e `marca_tiny` procuram o trecho; `criado_desde`/`criado_ate` e `atualizado_desde`/`atualizado_ate` são datas AAAA-MM-DD inclusivas. Para quem não é colaborador interno, os dados do Tiny vêm vazios. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`. Para quem não é colaborador interno, `estoque` vem `null` (a quantidade nunca é mostrada ao cliente) e `disponivel` diz se há estoque.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_produto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorProduto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaProduto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_produto(credencial_de_acesso, { sku: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorProduto,
) -> Result<tipos::PaginaProduto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_produto(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorProduto { sku: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.skus": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.lancamento": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.importado_da_api": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.demonstracao": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.preco_definido_no_portal": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_imagem": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_estoque": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.estoque_minimo": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.estoque_maximo": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.preco_minimo": { type: "number", required: false, description: "Rust: Option<f64>" },
    "parametros.preco_maximo": { type: "number", required: false, description: "Rust: Option<f64>" },
    "parametros.tem_descricao": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_nome_comercial": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_heuristica_pendente": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.enriquecido": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.unidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.material": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.diametro": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.categoria_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.marca_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.criado_desde": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.criado_ate": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.atualizado_desde": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.atualizado_ate": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.ordem": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaProduto>` · Rust: `Result<tipos::PaginaProduto, ErroAoChamarServico>` · veja [`PaginaProduto`](#tipo-paginaproduto).

## `criar_produto` [#criar_produto]

<Rota metodo="POST" caminho="/produto" credencial />

Cadastra um produto

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Produto do catálogo. `sku` até 32 letras, números, ponto, hífen e `_`, único; `nome` de 2 a 200 caracteres; `preco` e `preco_a_vista` maiores que zero (à vista não maior que o base); `unidade` de venda obrigatória; `estoque` não negativo; `incremento_minimo` e `quantidade_minima` maiores que zero; até 15 `imagens` (URLs; a primeira é a principal). Campos: `aplicacao` é o texto de onde o produto é usado; `embalagem` é o texto da embalagem de venda; `unidade_medida` é a unidade das quantidades (ex.: `m`, `un`); `embalagem_rotulo` é o nome da embalagem fechada (ex.: caixa); `embalagem_quantidade` é quantas unidades vêm na embalagem fechada (não negativa); `embalagem_preco` é o preço da embalagem fechada (não negativo); `diametro`, `material`, `cor` e `temperatura` são atributos técnicos em texto; `material` é atributo técnico em texto; `temperatura` é atributo técnico em texto; `lancamento` (booleano) marca o produto como lançamento; `relevancia` (inteiro) ordena a vitrine, da maior para a menor; `descricao` é o texto longo da vitrine (até 5000 caracteres); `especificacoes_texto` é a ficha técnica em texto (até 5000 caracteres); `outras_informacoes` é texto livre extra (até 2000 caracteres); `demonstracao` (booleano) marca produto de demonstração; `importado_da_api` (booleano) marca produto vindo do Tiny; `heuristica_pendente` é a lista de campos que ainda precisam de revisão manual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_produto(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ProdutoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Produto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_produto(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ProdutoCriar,
) -> Result<tipos::Produto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_produto(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ProdutoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProdutoCriar", typeDescriptionLink: "#tipo-produtocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Produto>` · Rust: `Result<tipos::Produto, ErroAoChamarServico>` · veja [`Produto`](#tipo-produto).

## `buscar_auto_complete_produto` [#buscar_auto_complete_produto]

<Rota metodo="GET" caminho="/produto/autocomplete" credencial />

Lista básica de produtos para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve id, SKU e nome, em ordem alfabética do nome. `busca` procura no nome e no SKU; `ativo` filtra. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_produto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteProduto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaProdutoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_produto(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteProduto,
) -> Result<tipos::PaginaProdutoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_produto(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteProduto { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaProdutoAutoComplete>` · Rust: `Result<tipos::PaginaProdutoAutoComplete, ErroAoChamarServico>` · veja [`PaginaProdutoAutoComplete`](#tipo-paginaprodutoautocomplete).

## `buscar_pelo_filtro_produto` [#buscar_pelo_filtro_produto]

<Rota metodo="GET" caminho="/produto/filtro" credencial />

Busca produtos por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve os produtos não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1). `ordem` aceita `relevancia` (padrão: relevância, depois nome), `menor-preco`/`maior-preco` (preço à vista, ou o preço base quando o à vista é zero), `az`/`za` (nome), `mais-novo`/`mais-antigo` (data de cadastro); o desempate é sempre nome e id; outro valor responde 400 `Ordem inválida`. Filtros opcionais (todos combinam com E): `sku` exato e `skus` vários separados por vírgula (sem diferenciar maiúsculas); `nome` procura o trecho no nome, no SKU e no nome comercial, sem diferenciar maiúsculas nem acentos; `ativo`, `lancamento`, `importado_da_api`, `demonstracao` e `preco_definido_no_portal` são exatos; `tem_imagem` (ao menos uma imagem), `tem_estoque` (estoque maior que zero), `tem_descricao`, `tem_nome_comercial`, `tem_heuristica_pendente` e `enriquecido` (já enriquecido pelo Tiny) aceitam `true` ou `false`; `estoque_minimo`/`estoque_maximo` e `preco_minimo`/`preco_maximo` são faixas inclusivas; `unidade` é exata e `cor`, `material`, `diametro`, `categoria_tiny` e `marca_tiny` procuram o trecho; `criado_desde`/`criado_ate` e `atualizado_desde`/`atualizado_ate` são datas AAAA-MM-DD inclusivas. Para quem não é colaborador interno, os dados do Tiny vêm vazios. Para quem não é colaborador interno, `estoque` vem `null` (a quantidade nunca é mostrada ao cliente) e `disponivel` diz se há estoque.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_produto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroProduto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Produto>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_produto(credencial_de_acesso, { sku: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroProduto,
) -> Result<Vec<tipos::Produto>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_produto(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroProduto { sku: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.skus": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.lancamento": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.importado_da_api": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.demonstracao": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.preco_definido_no_portal": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_imagem": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_estoque": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.estoque_minimo": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.estoque_maximo": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.preco_minimo": { type: "number", required: false, description: "Rust: Option<f64>" },
    "parametros.preco_maximo": { type: "number", required: false, description: "Rust: Option<f64>" },
    "parametros.tem_descricao": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_nome_comercial": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tem_heuristica_pendente": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.enriquecido": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.unidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.material": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.diametro": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.categoria_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.marca_tiny": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.criado_desde": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.criado_ate": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.atualizado_desde": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.atualizado_ate": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.ordem": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Produto>>` · Rust: `Result<Vec<tipos::Produto>, ErroAoChamarServico>`

## `buscar_pelo_id_produto` [#buscar_pelo_id_produto]

<Rota metodo="GET" caminho="/produto/{id}" credencial />

Busca um produto pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Produto excluído não é encontrado. Para quem não é colaborador interno, os dados do Tiny (`preco_tiny`, `preco_a_vista_tiny`, `categoria_tiny`, `marca_tiny`, `enriquecido_em`) vêm vazios. Para quem não é colaborador interno, `estoque` vem `null` (a quantidade nunca é mostrada ao cliente) e `disponivel` diz se há estoque.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_produto(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Produto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_produto(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Produto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_produto(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Produto>` · Rust: `Result<tipos::Produto, ErroAoChamarServico>` · veja [`Produto`](#tipo-produto).

## `atualizar_pelo_id_produto` [#atualizar_pelo_id_produto]

<Rota metodo="PATCH" caminho="/produto/{id}" credencial />

Atualiza um produto

Exige a permissão `editar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Mesmas validações do cadastro (o SKU não muda). `embalagem_quantidade` e `embalagem_preco` aceitam `null` para apagar; `preco_definido_no_portal` protege o preço da sincronização com o Tiny. Atualização parcial: campo ausente mantém o valor atual. Campos: `nome` de 2 a 200 caracteres; `aplicacao` é o texto de onde o produto é usado; `unidade` é a unidade de venda (obrigatória quando enviada); `embalagem` é o texto da embalagem de venda; `unidade_medida` é a unidade das quantidades (ex.: `m`, `un`); `embalagem_rotulo` é o nome da embalagem fechada (ex.: caixa); `incremento_minimo` maior que zero; `diametro`, `material`, `cor` e `temperatura` são atributos técnicos em texto; `material` é atributo técnico em texto; `temperatura` é atributo técnico em texto; `lancamento` (booleano) marca o produto como lançamento; `relevancia` (inteiro) ordena a vitrine, da maior para a menor; `imagens` até 15 URLs, sem itens vazios; `descricao` é o texto longo da vitrine (até 5000 caracteres); `especificacoes_texto` é a ficha técnica em texto (até 5000 caracteres); `outras_informacoes` é texto livre extra (até 2000 caracteres); `heuristica_pendente` é a lista de campos que ainda precisam de revisão manual. `nome_comercial` é o nome mostrado ao cliente e `resumo_caracteristicas` a linha curta de características do card; os dois aceitam texto ou `null` para limpar (vazio também limpa).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_produto(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ProdutoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Produto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_produto(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ProdutoAtualizar,
) -> Result<tipos::Produto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_produto(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ProdutoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProdutoAtualizar", typeDescriptionLink: "#tipo-produtoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Produto>` · Rust: `Result<tipos::Produto, ErroAoChamarServico>` · veja [`Produto`](#tipo-produto).

## `deletar_pelo_id_produto` [#deletar_pelo_id_produto]

<Rota metodo="DELETE" caminho="/produto/{id}" credencial />

Exclui um produto

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_produto(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_produto } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_produto(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_produto(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_produto(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaProduto [#tipo-paginaproduto]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProduto } from "termo_core/portal";

export interface PaginaProduto {
  itens: Array<PaginaProdutoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProduto;

pub struct PaginaProduto {
    pub itens: Vec<PaginaProdutoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaProdutoAutoComplete [#tipo-paginaprodutoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoAutoComplete } from "termo_core/portal";

export interface PaginaProdutoAutoComplete {
  itens: Array<PaginaProdutoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoAutoComplete;

pub struct PaginaProdutoAutoComplete {
    pub itens: Vec<PaginaProdutoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaProdutoAutoCompleteItensItem [#tipo-paginaprodutoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaProdutoAutoCompleteItensItem {
  id: string;
  nome: string;
  sku: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoAutoCompleteItensItem;

pub struct PaginaProdutoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
    pub sku: String,
}
```

</Tab>
</Tabs>

### PaginaProdutoItensItem [#tipo-paginaprodutoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoItensItem } from "termo_core/portal";

export interface PaginaProdutoItensItem {
  aplicacao?: string | null;
  ativo: boolean;
  atualizado_em: string;
  categoria_tiny?: string | null;
  cor?: string | null;
  criado_em: string;
  demonstracao: boolean;
  descricao?: string | null;
  diametro?: string | null;
  disponivel: boolean;
  embalagem?: string | null;
  embalagem_altura?: number | null;
  embalagem_comprimento?: number | null;
  embalagem_largura?: number | null;
  embalagem_preco?: number | null;
  embalagem_quantidade?: number | null;
  embalagem_rotulo?: string | null;
  enriquecido_em?: string | null;
  especificacoes_texto?: string | null;
  estoque?: number | null;
  garantia?: string | null;
  gtin?: string | null;
  gtin_embalagem?: string | null;
  heuristica_pendente: Array<string>;
  id: string;
  imagens: Array<string>;
  importado_da_api: boolean;
  incremento_minimo: number;
  lancamento: boolean;
  marca_tiny?: string | null;
  material?: string | null;
  ncm?: string | null;
  nome: string;
  nome_comercial?: string | null;
  nome_tiny?: string | null;
  origem_fiscal?: number | null;
  outras_informacoes?: string | null;
  peso_bruto?: number | null;
  peso_liquido?: number | null;
  preco: number;
  preco_a_vista: number;
  preco_a_vista_tiny?: number | null;
  preco_definido_no_portal: boolean;
  preco_tiny?: number | null;
  quantidade_minima: number;
  relevancia: number;
  resumo_caracteristicas?: string | null;
  sincronizado_em?: string | null;
  sku: string;
  temperatura?: string | null;
  tipo_tiny?: string | null;
  unidade: string;
  unidade_medida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoItensItem;

pub struct PaginaProdutoItensItem {
    pub aplicacao: Option<String>,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria_tiny: Option<String>,
    pub cor: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub demonstracao: bool,
    pub descricao: Option<String>,
    pub diametro: Option<String>,
    pub disponivel: bool,
    pub embalagem: Option<String>,
    pub embalagem_altura: Option<f64>,
    pub embalagem_comprimento: Option<f64>,
    pub embalagem_largura: Option<f64>,
    pub embalagem_preco: Option<f64>,
    pub embalagem_quantidade: Option<i32>,
    pub embalagem_rotulo: Option<String>,
    pub enriquecido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub especificacoes_texto: Option<String>,
    pub estoque: Option<i32>,
    pub garantia: Option<String>,
    pub gtin: Option<String>,
    pub gtin_embalagem: Option<String>,
    pub heuristica_pendente: Vec<String>,
    pub id: uuid::Uuid,
    pub imagens: Vec<String>,
    pub importado_da_api: bool,
    pub incremento_minimo: f64,
    pub lancamento: bool,
    pub marca_tiny: Option<String>,
    pub material: Option<String>,
    pub ncm: Option<String>,
    pub nome: String,
    pub nome_comercial: Option<String>,
    pub nome_tiny: Option<String>,
    pub origem_fiscal: Option<i32>,
    pub outras_informacoes: Option<String>,
    pub peso_bruto: Option<f64>,
    pub peso_liquido: Option<f64>,
    pub preco: f64,
    pub preco_a_vista: f64,
    pub preco_a_vista_tiny: Option<f64>,
    pub preco_definido_no_portal: bool,
    pub preco_tiny: Option<f64>,
    pub quantidade_minima: f64,
    pub relevancia: i32,
    pub resumo_caracteristicas: Option<String>,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub sku: String,
    pub temperatura: Option<String>,
    pub tipo_tiny: Option<String>,
    pub unidade: String,
    pub unidade_medida: String,
}
```

</Tab>
</Tabs>

### Produto [#tipo-produto]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Produto } from "termo_core/portal";

export interface Produto {
  aplicacao?: string | null;
  ativo: boolean;
  atualizado_em: string;
  categoria_tiny?: string | null;
  cor?: string | null;
  criado_em: string;
  demonstracao: boolean;
  descricao?: string | null;
  diametro?: string | null;
  disponivel: boolean;
  embalagem?: string | null;
  embalagem_altura?: number | null;
  embalagem_comprimento?: number | null;
  embalagem_largura?: number | null;
  embalagem_preco?: number | null;
  embalagem_quantidade?: number | null;
  embalagem_rotulo?: string | null;
  enriquecido_em?: string | null;
  especificacoes_texto?: string | null;
  estoque?: number | null;
  garantia?: string | null;
  gtin?: string | null;
  gtin_embalagem?: string | null;
  heuristica_pendente: Array<string>;
  id: string;
  imagens: Array<string>;
  importado_da_api: boolean;
  incremento_minimo: number;
  lancamento: boolean;
  marca_tiny?: string | null;
  material?: string | null;
  ncm?: string | null;
  nome: string;
  nome_comercial?: string | null;
  nome_tiny?: string | null;
  origem_fiscal?: number | null;
  outras_informacoes?: string | null;
  peso_bruto?: number | null;
  peso_liquido?: number | null;
  preco: number;
  preco_a_vista: number;
  preco_a_vista_tiny?: number | null;
  preco_definido_no_portal: boolean;
  preco_tiny?: number | null;
  quantidade_minima: number;
  relevancia: number;
  resumo_caracteristicas?: string | null;
  sincronizado_em?: string | null;
  sku: string;
  temperatura?: string | null;
  tipo_tiny?: string | null;
  unidade: string;
  unidade_medida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Produto;

pub struct Produto {
    pub aplicacao: Option<String>,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub categoria_tiny: Option<String>,
    pub cor: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub demonstracao: bool,
    pub descricao: Option<String>,
    pub diametro: Option<String>,
    pub disponivel: bool,
    pub embalagem: Option<String>,
    pub embalagem_altura: Option<f64>,
    pub embalagem_comprimento: Option<f64>,
    pub embalagem_largura: Option<f64>,
    pub embalagem_preco: Option<f64>,
    pub embalagem_quantidade: Option<i32>,
    pub embalagem_rotulo: Option<String>,
    pub enriquecido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub especificacoes_texto: Option<String>,
    pub estoque: Option<i32>,
    pub garantia: Option<String>,
    pub gtin: Option<String>,
    pub gtin_embalagem: Option<String>,
    pub heuristica_pendente: Vec<String>,
    pub id: uuid::Uuid,
    pub imagens: Vec<String>,
    pub importado_da_api: bool,
    pub incremento_minimo: f64,
    pub lancamento: bool,
    pub marca_tiny: Option<String>,
    pub material: Option<String>,
    pub ncm: Option<String>,
    pub nome: String,
    pub nome_comercial: Option<String>,
    pub nome_tiny: Option<String>,
    pub origem_fiscal: Option<i32>,
    pub outras_informacoes: Option<String>,
    pub peso_bruto: Option<f64>,
    pub peso_liquido: Option<f64>,
    pub preco: f64,
    pub preco_a_vista: f64,
    pub preco_a_vista_tiny: Option<f64>,
    pub preco_definido_no_portal: bool,
    pub preco_tiny: Option<f64>,
    pub quantidade_minima: f64,
    pub relevancia: i32,
    pub resumo_caracteristicas: Option<String>,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub sku: String,
    pub temperatura: Option<String>,
    pub tipo_tiny: Option<String>,
    pub unidade: String,
    pub unidade_medida: String,
}
```

</Tab>
</Tabs>

### ProdutoAtualizar [#tipo-produtoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoAtualizar } from "termo_core/portal";

export interface ProdutoAtualizar {
  aplicacao?: string | null;
  ativo?: boolean | null;
  cor?: string | null;
  descricao?: string | null;
  diametro?: string | null;
  embalagem?: string | null;
  embalagem_preco?: number | null;
  embalagem_quantidade?: number | null;
  embalagem_rotulo?: string | null;
  especificacoes_texto?: string | null;
  estoque?: number | null;
  heuristica_pendente?: Array<string> | null;
  imagens?: Array<string> | null;
  incremento_minimo?: number | null;
  lancamento?: boolean | null;
  material?: string | null;
  nome?: string | null;
  nome_comercial?: string | null;
  outras_informacoes?: string | null;
  preco?: number | null;
  preco_a_vista?: number | null;
  preco_definido_no_portal?: boolean | null;
  quantidade_minima?: number | null;
  relevancia?: number | null;
  resumo_caracteristicas?: string | null;
  temperatura?: string | null;
  unidade?: string | null;
  unidade_medida?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoAtualizar;

pub struct ProdutoAtualizar {
    pub aplicacao: Option<String>,
    pub ativo: Option<bool>,
    pub cor: Option<String>,
    pub descricao: Option<String>,
    pub diametro: Option<String>,
    pub embalagem: Option<String>,
    pub embalagem_preco: Option<f64>,
    pub embalagem_quantidade: Option<i32>,
    pub embalagem_rotulo: Option<String>,
    pub especificacoes_texto: Option<String>,
    pub estoque: Option<i32>,
    pub heuristica_pendente: Option<Vec<String>>,
    pub imagens: Option<Vec<String>>,
    pub incremento_minimo: Option<f64>,
    pub lancamento: Option<bool>,
    pub material: Option<String>,
    pub nome: Option<String>,
    pub nome_comercial: Option<String>,
    pub outras_informacoes: Option<String>,
    pub preco: Option<f64>,
    pub preco_a_vista: Option<f64>,
    pub preco_definido_no_portal: Option<bool>,
    pub quantidade_minima: Option<f64>,
    pub relevancia: Option<i32>,
    pub resumo_caracteristicas: Option<String>,
    pub temperatura: Option<String>,
    pub unidade: Option<String>,
    pub unidade_medida: Option<String>,
}
```

</Tab>
</Tabs>

### ProdutoCriar [#tipo-produtocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoCriar } from "termo_core/portal";

export interface ProdutoCriar {
  aplicacao?: string | null;
  ativo?: boolean | null;
  cor?: string | null;
  demonstracao?: boolean | null;
  descricao?: string | null;
  diametro?: string | null;
  embalagem?: string | null;
  embalagem_preco?: number | null;
  embalagem_quantidade?: number | null;
  embalagem_rotulo?: string | null;
  especificacoes_texto?: string | null;
  estoque?: number | null;
  heuristica_pendente?: Array<string> | null;
  imagens?: Array<string> | null;
  importado_da_api?: boolean | null;
  incremento_minimo?: number | null;
  lancamento?: boolean | null;
  material?: string | null;
  nome: string;
  outras_informacoes?: string | null;
  preco: number;
  preco_a_vista: number;
  quantidade_minima?: number | null;
  relevancia?: number | null;
  sku: string;
  temperatura?: string | null;
  unidade: string;
  unidade_medida?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoCriar;

pub struct ProdutoCriar {
    pub aplicacao: Option<String>,
    pub ativo: Option<bool>,
    pub cor: Option<String>,
    pub demonstracao: Option<bool>,
    pub descricao: Option<String>,
    pub diametro: Option<String>,
    pub embalagem: Option<String>,
    pub embalagem_preco: Option<f64>,
    pub embalagem_quantidade: Option<i32>,
    pub embalagem_rotulo: Option<String>,
    pub especificacoes_texto: Option<String>,
    pub estoque: Option<i32>,
    pub heuristica_pendente: Option<Vec<String>>,
    pub imagens: Option<Vec<String>>,
    pub importado_da_api: Option<bool>,
    pub incremento_minimo: Option<f64>,
    pub lancamento: Option<bool>,
    pub material: Option<String>,
    pub nome: String,
    pub outras_informacoes: Option<String>,
    pub preco: f64,
    pub preco_a_vista: f64,
    pub quantidade_minima: Option<f64>,
    pub relevancia: Option<i32>,
    pub sku: String,
    pub temperatura: Option<String>,
    pub unidade: String,
    pub unidade_medida: Option<String>,
}
```

</Tab>
</Tabs>


# Produto conflito sincronização (/docs/servicos/portal/produto_conflito_sincronizacao)

> 7 funções do TermoPortal para produto conflito sincronização.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_produto_conflito_sincronizacao`](#buscar_paginador_produto_conflito_sincronizacao) | `GET /produto_conflito_sincronizacao` | Lista os conflitos de sincronização paginados |
| [`criar_produto_conflito_sincronizacao`](#criar_produto_conflito_sincronizacao) | `POST /produto_conflito_sincronizacao` | Registra um conflito de sincronização de produto |
| [`buscar_auto_complete_produto_conflito_sincronizacao`](#buscar_auto_complete_produto_conflito_sincronizacao) | `GET /produto_conflito_sincronizacao/autocomplete` | Lista básica de conflitos de sincronização para seleção |
| [`buscar_pelo_filtro_produto_conflito_sincronizacao`](#buscar_pelo_filtro_produto_conflito_sincronizacao) | `GET /produto_conflito_sincronizacao/filtro` | Busca conflitos de sincronização por filtro |
| [`buscar_pelo_id_produto_conflito_sincronizacao`](#buscar_pelo_id_produto_conflito_sincronizacao) | `GET /produto_conflito_sincronizacao/{id}` | Busca um conflito de sincronização pelo id |
| [`atualizar_pelo_id_produto_conflito_sincronizacao`](#atualizar_pelo_id_produto_conflito_sincronizacao) | `PATCH /produto_conflito_sincronizacao/{id}` | Resolve um conflito de sincronização |
| [`deletar_pelo_id_produto_conflito_sincronizacao`](#deletar_pelo_id_produto_conflito_sincronizacao) | `DELETE /produto_conflito_sincronizacao/{id}` | Exclui um conflito de sincronização |

## `buscar_paginador_produto_conflito_sincronizacao` [#buscar_paginador_produto_conflito_sincronizacao]

<Rota metodo="GET" caminho="/produto_conflito_sincronizacao" credencial />

Lista os conflitos de sincronização paginados

Exige só uma sessão válida (qualquer pessoa logada no portal). Dos mais novos para os mais antigos; `resolvido` opcional filtra. Paginado com 50 itens por página (fixo); `pagina` começa em 1 (padrão 1). A resposta traz `itens`, `total` (registros que casam), `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorProdutoConflitoSincronizacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaProdutoConflitoSincronizacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_produto_conflito_sincronizacao(credencial_de_acesso, { resolvido: true });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorProdutoConflitoSincronizacao,
) -> Result<tipos::PaginaProdutoConflitoSincronizacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorProdutoConflitoSincronizacao { resolvido: Some(true), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.resolvido": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaProdutoConflitoSincronizacao>` · Rust: `Result<tipos::PaginaProdutoConflitoSincronizacao, ErroAoChamarServico>` · veja [`PaginaProdutoConflitoSincronizacao`](#tipo-paginaprodutoconflitosincronizacao).

## `criar_produto_conflito_sincronizacao` [#criar_produto_conflito_sincronizacao]

<Rota metodo="POST" caminho="/produto_conflito_sincronizacao" credencial />

Registra um conflito de sincronização de produto

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Conflito entre o valor do portal e o da API da Termotubos (Tiny) num campo monitorado do produto. `campo` é `preco`, `preco_a_vista` ou `estoque`; `valor_local` e `valor_api` em texto (o da API precisa ser numérico). Campos: `produto_id` (uuid) é o produto do conflito.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ProdutoConflitoSincronizacaoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ProdutoConflitoSincronizacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_produto_conflito_sincronizacao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ProdutoConflitoSincronizacaoCriar,
) -> Result<tipos::ProdutoConflitoSincronizacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ProdutoConflitoSincronizacaoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProdutoConflitoSincronizacaoCriar", typeDescriptionLink: "#tipo-produtoconflitosincronizacaocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ProdutoConflitoSincronizacao>` · Rust: `Result<tipos::ProdutoConflitoSincronizacao, ErroAoChamarServico>` · veja [`ProdutoConflitoSincronizacao`](#tipo-produtoconflitosincronizacao).

## `buscar_auto_complete_produto_conflito_sincronizacao` [#buscar_auto_complete_produto_conflito_sincronizacao]

<Rota metodo="GET" caminho="/produto_conflito_sincronizacao/autocomplete" credencial />

Lista básica de conflitos de sincronização para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve id e `rotulo` (`SKU - campo`), em ordem alfabética. `busca` procura no SKU e no campo; `resolvido` filtra. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteProdutoConflitoSincronizacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaProdutoConflitoSincronizacaoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_produto_conflito_sincronizacao(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteProdutoConflitoSincronizacao,
) -> Result<tipos::PaginaProdutoConflitoSincronizacaoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteProdutoConflitoSincronizacao { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaProdutoConflitoSincronizacaoAutoComplete>` · Rust: `Result<tipos::PaginaProdutoConflitoSincronizacaoAutoComplete, ErroAoChamarServico>` · veja [`PaginaProdutoConflitoSincronizacaoAutoComplete`](#tipo-paginaprodutoconflitosincronizacaoautocomplete).

## `buscar_pelo_filtro_produto_conflito_sincronizacao` [#buscar_pelo_filtro_produto_conflito_sincronizacao]

<Rota metodo="GET" caminho="/produto_conflito_sincronizacao/filtro" credencial />

Busca conflitos de sincronização por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve os conflitos não excluídos que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), dos mais novos para os mais antigos. `produto_id` e `campo` são exatos; `resolvido` separa pendentes (`false`) e resolvidos (`true`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroProdutoConflitoSincronizacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ProdutoConflitoSincronizacao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_produto_conflito_sincronizacao(credencial_de_acesso, { produto_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroProdutoConflitoSincronizacao,
) -> Result<Vec<tipos::ProdutoConflitoSincronizacao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroProdutoConflitoSincronizacao { produto_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.produto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.campo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.resolvido": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ProdutoConflitoSincronizacao>>` · Rust: `Result<Vec<tipos::ProdutoConflitoSincronizacao>, ErroAoChamarServico>`

## `buscar_pelo_id_produto_conflito_sincronizacao` [#buscar_pelo_id_produto_conflito_sincronizacao]

<Rota metodo="GET" caminho="/produto_conflito_sincronizacao/{id}" credencial />

Busca um conflito de sincronização pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Conflito excluído não é encontrado. Traz SKU e nome do produto.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ProdutoConflitoSincronizacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_produto_conflito_sincronizacao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ProdutoConflitoSincronizacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ProdutoConflitoSincronizacao>` · Rust: `Result<tipos::ProdutoConflitoSincronizacao, ErroAoChamarServico>` · veja [`ProdutoConflitoSincronizacao`](#tipo-produtoconflitosincronizacao).

## `atualizar_pelo_id_produto_conflito_sincronizacao` [#atualizar_pelo_id_produto_conflito_sincronizacao]

<Rota metodo="PATCH" caminho="/produto_conflito_sincronizacao/{id}" credencial />

Resolve um conflito de sincronização

Exige a permissão `editar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Resolve um conflito pendente: `resolucao` `local` mantém o valor do portal e `api` aplica o valor da API no produto.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ProdutoConflitoSincronizacaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ProdutoConflitoSincronizacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_produto_conflito_sincronizacao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ProdutoConflitoSincronizacaoAtualizar,
) -> Result<tipos::ProdutoConflitoSincronizacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ProdutoConflitoSincronizacaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProdutoConflitoSincronizacaoAtualizar", typeDescriptionLink: "#tipo-produtoconflitosincronizacaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ProdutoConflitoSincronizacao>` · Rust: `Result<tipos::ProdutoConflitoSincronizacao, ErroAoChamarServico>` · veja [`ProdutoConflitoSincronizacao`](#tipo-produtoconflitosincronizacao).

## `deletar_pelo_id_produto_conflito_sincronizacao` [#deletar_pelo_id_produto_conflito_sincronizacao]

<Rota metodo="DELETE" caminho="/produto_conflito_sincronizacao/{id}" credencial />

Exclui um conflito de sincronização

Exige a permissão `excluir` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_produto_conflito_sincronizacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_produto_conflito_sincronizacao } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_produto_conflito_sincronizacao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_produto_conflito_sincronizacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_produto_conflito_sincronizacao(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaProdutoConflitoSincronizacao [#tipo-paginaprodutoconflitosincronizacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoConflitoSincronizacao } from "termo_core/portal";

export interface PaginaProdutoConflitoSincronizacao {
  itens: Array<PaginaProdutoConflitoSincronizacaoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoConflitoSincronizacao;

pub struct PaginaProdutoConflitoSincronizacao {
    pub itens: Vec<PaginaProdutoConflitoSincronizacaoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaProdutoConflitoSincronizacaoAutoComplete [#tipo-paginaprodutoconflitosincronizacaoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoConflitoSincronizacaoAutoComplete } from "termo_core/portal";

export interface PaginaProdutoConflitoSincronizacaoAutoComplete {
  itens: Array<PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoConflitoSincronizacaoAutoComplete;

pub struct PaginaProdutoConflitoSincronizacaoAutoComplete {
    pub itens: Vec<PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem [#tipo-paginaprodutoconflitosincronizacaoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem;

pub struct PaginaProdutoConflitoSincronizacaoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaProdutoConflitoSincronizacaoItensItem [#tipo-paginaprodutoconflitosincronizacaoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProdutoConflitoSincronizacaoItensItem } from "termo_core/portal";

export interface PaginaProdutoConflitoSincronizacaoItensItem {
  atualizado_em: string;
  campo: string;
  criado_em: string;
  id: string;
  produto_id: string;
  produto_nome: string;
  produto_sku: string;
  resolucao?: string | null;
  resolvido_em?: string | null;
  valor_api: string;
  valor_local: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaProdutoConflitoSincronizacaoItensItem;

pub struct PaginaProdutoConflitoSincronizacaoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub campo: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub produto_id: uuid::Uuid,
    pub produto_nome: String,
    pub produto_sku: String,
    pub resolucao: Option<String>,
    pub resolvido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub valor_api: String,
    pub valor_local: String,
}
```

</Tab>
</Tabs>

### ProdutoConflitoSincronizacao [#tipo-produtoconflitosincronizacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoConflitoSincronizacao } from "termo_core/portal";

export interface ProdutoConflitoSincronizacao {
  atualizado_em: string;
  campo: string;
  criado_em: string;
  id: string;
  produto_id: string;
  produto_nome: string;
  produto_sku: string;
  resolucao?: string | null;
  resolvido_em?: string | null;
  valor_api: string;
  valor_local: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoConflitoSincronizacao;

pub struct ProdutoConflitoSincronizacao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub campo: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub produto_id: uuid::Uuid,
    pub produto_nome: String,
    pub produto_sku: String,
    pub resolucao: Option<String>,
    pub resolvido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub valor_api: String,
    pub valor_local: String,
}
```

</Tab>
</Tabs>

### ProdutoConflitoSincronizacaoAtualizar [#tipo-produtoconflitosincronizacaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoConflitoSincronizacaoAtualizar } from "termo_core/portal";

export interface ProdutoConflitoSincronizacaoAtualizar {
  resolucao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoConflitoSincronizacaoAtualizar;

pub struct ProdutoConflitoSincronizacaoAtualizar {
    pub resolucao: String,
}
```

</Tab>
</Tabs>

### ProdutoConflitoSincronizacaoCriar [#tipo-produtoconflitosincronizacaocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoConflitoSincronizacaoCriar } from "termo_core/portal";

export interface ProdutoConflitoSincronizacaoCriar {
  campo: string;
  produto_id: string;
  valor_api: string;
  valor_local: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoConflitoSincronizacaoCriar;

pub struct ProdutoConflitoSincronizacaoCriar {
    pub campo: String,
    pub produto_id: uuid::Uuid,
    pub valor_api: String,
    pub valor_local: String,
}
```

</Tab>
</Tabs>


# Produto estrutura (/docs/servicos/portal/produto_estrutura)

> 1 função do TermoPortal para produto estrutura.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_filtro_produto_estrutura`](#buscar_pelo_filtro_produto_estrutura) | `GET /produto_estrutura/filtro` | Busca as embalagens e os componentes de um produto |

## `buscar_pelo_filtro_produto_estrutura` [#buscar_pelo_filtro_produto_estrutura]

<Rota metodo="GET" caminho="/produto_estrutura/filtro" credencial />

Busca as embalagens e os componentes de um produto

Exige só uma sessão válida (qualquer pessoa logada no portal). Consulta ao vivo a estrutura do Tiny na API da Termotubos para o `sku` informado (obrigatório, não vazio) e liga cada SKU ao produto do portal. `contido_em` são as embalagens e kits que contêm o produto (por exemplo, a caixa com N unidades) e `contem` são os itens que o produto contém; cada relação traz `sku`, `quantidade`, `tipo`, `descricao_tiny` e `produto` (o produto do portal com o mesmo SKU, com `nome_comercial`, preços, unidade, imagem, `ativo` e `disponivel`, ou `null` quando não existe no portal). Para quem não é colaborador interno, só aparecem as relações com produto ativo no portal e `descricao_tiny` vem `null`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_produto_estrutura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroProdutoEstrutura,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ProdutoEstrutura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_produto_estrutura } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_produto_estrutura(credencial_de_acesso, { sku });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_produto_estrutura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroProdutoEstrutura,
) -> Result<tipos::ProdutoEstrutura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_produto_estrutura(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroProdutoEstrutura { sku },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku": { type: "string", required: true, description: "Rust: String" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ProdutoEstrutura>` · Rust: `Result<tipos::ProdutoEstrutura, ErroAoChamarServico>` · veja [`ProdutoEstrutura`](#tipo-produtoestrutura).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ProdutoEstrutura [#tipo-produtoestrutura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoEstrutura } from "termo_core/portal";

export interface ProdutoEstrutura {
  contem: Array<RelacaoEstrutura>;
  contido_em: Array<RelacaoEstrutura>;
  sku: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoEstrutura;

pub struct ProdutoEstrutura {
    pub contem: Vec<RelacaoEstrutura>,
    pub contido_em: Vec<RelacaoEstrutura>,
    pub sku: String,
}
```

</Tab>
</Tabs>

### ProdutoRelacionado [#tipo-produtorelacionado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoRelacionado } from "termo_core/portal";

export interface ProdutoRelacionado {
  ativo: boolean;
  disponivel: boolean;
  id: string;
  imagem_url?: string | null;
  nome: string;
  nome_comercial?: string | null;
  preco: number;
  preco_a_vista: number;
  resumo_caracteristicas?: string | null;
  sku: string;
  unidade: string;
  unidade_medida: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoRelacionado;

pub struct ProdutoRelacionado {
    pub ativo: bool,
    pub disponivel: bool,
    pub id: uuid::Uuid,
    pub imagem_url: Option<String>,
    pub nome: String,
    pub nome_comercial: Option<String>,
    pub preco: f64,
    pub preco_a_vista: f64,
    pub resumo_caracteristicas: Option<String>,
    pub sku: String,
    pub unidade: String,
    pub unidade_medida: String,
}
```

</Tab>
</Tabs>

### RelacaoEstrutura [#tipo-relacaoestrutura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RelacaoEstrutura } from "termo_core/portal";

export interface RelacaoEstrutura {
  descricao_tiny?: string | null;
  produto?: ProdutoRelacionado | null;
  quantidade: number;
  sku: string;
  tipo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::RelacaoEstrutura;

pub struct RelacaoEstrutura {
    pub descricao_tiny: Option<String>,
    pub produto: Option<ProdutoRelacionado>,
    pub quantidade: f64,
    pub sku: String,
    pub tipo: Option<String>,
}
```

</Tab>
</Tabs>


# Produto Termotubos (/docs/servicos/portal/produto_termotubos)

> 5 funções do TermoPortal para produto termotubos.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`criar_produto_termotubos`](#criar_produto_termotubos) | `POST /produto_termotubos` | Importa ou sincroniza produtos do Tiny pelo SKU |
| [`buscar_pelo_filtro_produto_termotubos`](#buscar_pelo_filtro_produto_termotubos) | `GET /produto_termotubos/filtro` | Busca produtos no catálogo da Termotubos (Tiny) |
| [`buscar_sincronizacao_produto_termotubos`](#buscar_sincronizacao_produto_termotubos) | `GET /produto_termotubos/sincronizacao` | Status da sincronização do catálogo com o Tiny |
| [`iniciar_sincronizacao_produto_termotubos`](#iniciar_sincronizacao_produto_termotubos) | `POST /produto_termotubos/sincronizacao` | Inicia a sincronização do catálogo com o Tiny em segundo plano |
| [`cancelar_sincronizacao_produto_termotubos`](#cancelar_sincronizacao_produto_termotubos) | `DELETE /produto_termotubos/sincronizacao` | Cancela a sincronização do catálogo em andamento |

## `criar_produto_termotubos` [#criar_produto_termotubos]

<Rota metodo="POST" caminho="/produto_termotubos" credencial />

Importa ou sincroniza produtos do Tiny pelo SKU

Exige a permissão `criar` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Importa no portal os produtos do Tiny pelos `skus` (1 a 100 por vez; vazios e repetidos são descartados). Produto novo é criado; produto que já existe é atualizado, e diferença de preço ou estoque em produto com preço definido no portal vira conflito de sincronização. Responde 200 com o resultado de cada SKU (`criado`, `atualizado`, `conflito` ou `falha`) e os totais. Até 10 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_produto_termotubos(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ProdutoTermotubosCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ImportacaoProdutos>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_produto_termotubos } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_produto_termotubos(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_produto_termotubos(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ProdutoTermotubosCriar,
) -> Result<tipos::ImportacaoProdutos, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_produto_termotubos(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ProdutoTermotubosCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProdutoTermotubosCriar", typeDescriptionLink: "#tipo-produtotermotuboscriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ImportacaoProdutos>` · Rust: `Result<tipos::ImportacaoProdutos, ErroAoChamarServico>` · veja [`ImportacaoProdutos`](#tipo-importacaoprodutos).

## `buscar_pelo_filtro_produto_termotubos` [#buscar_pelo_filtro_produto_termotubos]

<Rota metodo="GET" caminho="/produto_termotubos/filtro" credencial />

Busca produtos no catálogo da Termotubos (Tiny)

Exige a permissão `ver` no módulo `Configuracoes` do perfil de quem chama (administrador e master têm tudo). Consulta o catálogo do Tiny pela API da Termotubos para importar produtos no portal. `busca` aceita SKUs separados por vírgula, ponto e vírgula ou espaço; termo terminado em `*` busca pelo prefixo (ex.: `B68*`). `apenas_ativos` filtra; `pagina` começa em 1 e `por_pagina` tem padrão 20 e vai de 1 a 50 (vale também para a busca por termos, paginada no servidor com `tem_mais`, `total_paginas` e `total_registros`). Cada item diz se já existe no portal (`ja_existe`). Termos inválidos voltam em `termos_invalidos`; `truncado: true` indica que a busca por prefixo foi cortada. Até 30 chamadas por minuto por pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_produto_termotubos(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroProdutoTermotubos = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.BuscaTermotubos>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_produto_termotubos } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_produto_termotubos(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_produto_termotubos(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroProdutoTermotubos,
) -> Result<tipos::BuscaTermotubos, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_produto_termotubos(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroProdutoTermotubos { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.apenas_ativos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.por_pagina": { type: "number", required: false, description: "Rust: Option<i32>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.BuscaTermotubos>` · Rust: `Result<tipos::BuscaTermotubos, ErroAoChamarServico>` · veja [`BuscaTermotubos`](#tipo-buscatermotubos).

## `buscar_sincronizacao_produto_termotubos` [#buscar_sincronizacao_produto_termotubos]

<Rota metodo="GET" caminho="/produto_termotubos/sincronizacao" credencial />

Status da sincronização do catálogo com o Tiny

Exige a permissão `ver` no módulo `Configuracoes`. Devolve a sincronização em andamento ou a última que terminou: `etapa` (`lendo` ou `gravando`), `gravados` de `total`, `cancelada`, `erro` e o `resumo` (conferidos, criados, atualizados, conflitos e falhas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_sincronizacao_produto_termotubos(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusSincronizacaoCatalogo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_sincronizacao_produto_termotubos } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_sincronizacao_produto_termotubos(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_sincronizacao_produto_termotubos(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusSincronizacaoCatalogo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_sincronizacao_produto_termotubos(
    &credencial_de_acesso,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusSincronizacaoCatalogo>` · Rust: `Result<tipos::StatusSincronizacaoCatalogo, ErroAoChamarServico>` · veja [`StatusSincronizacaoCatalogo`](#tipo-statussincronizacaocatalogo).

## `iniciar_sincronizacao_produto_termotubos` [#iniciar_sincronizacao_produto_termotubos]

<Rota metodo="POST" caminho="/produto_termotubos/sincronizacao" credencial />

Inicia a sincronização do catálogo com o Tiny em segundo plano

Exige a permissão `criar` no módulo `Configuracoes`. Lê o catálogo do Tiny e grava no portal o que é novo ou mudou, em segundo plano no servidor: a tela pode ser fechada. `apenas_ativos` lê só os produtos ativos. Responde 202 com o status inicial; acompanhe por `GET /produto_termotubos/sincronizacao`. O status fica em memória e se perde se o servidor reiniciar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function iniciar_sincronizacao_produto_termotubos(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeIniciarSincronizacaoProdutoTermotubos = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusSincronizacaoCatalogo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { iniciar_sincronizacao_produto_termotubos } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await iniciar_sincronizacao_produto_termotubos(credencial_de_acesso, { apenas_ativos: true });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn iniciar_sincronizacao_produto_termotubos(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeIniciarSincronizacaoProdutoTermotubos,
) -> Result<tipos::StatusSincronizacaoCatalogo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::iniciar_sincronizacao_produto_termotubos(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeIniciarSincronizacaoProdutoTermotubos { apenas_ativos: Some(true) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.apenas_ativos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusSincronizacaoCatalogo>` · Rust: `Result<tipos::StatusSincronizacaoCatalogo, ErroAoChamarServico>` · veja [`StatusSincronizacaoCatalogo`](#tipo-statussincronizacaocatalogo).

## `cancelar_sincronizacao_produto_termotubos` [#cancelar_sincronizacao_produto_termotubos]

<Rota metodo="DELETE" caminho="/produto_termotubos/sincronizacao" credencial />

Cancela a sincronização do catálogo em andamento

Exige a permissão `excluir` no módulo `Configuracoes`. Para depois do lote em gravação; o que já foi gravado fica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function cancelar_sincronizacao_produto_termotubos(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { cancelar_sincronizacao_produto_termotubos } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await cancelar_sincronizacao_produto_termotubos(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn cancelar_sincronizacao_produto_termotubos(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::cancelar_sincronizacao_produto_termotubos(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### BuscaTermotubos [#tipo-buscatermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { BuscaTermotubos } from "termo_core/portal";

export interface BuscaTermotubos {
  itens: Array<ItemCatalogoTermotubos>;
  pagina: number;
  tem_mais: boolean;
  termos_invalidos: Array<TermoInvalido>;
  total_paginas?: number | null;
  total_registros?: number | null;
  truncado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::BuscaTermotubos;

pub struct BuscaTermotubos {
    pub itens: Vec<ItemCatalogoTermotubos>,
    pub pagina: i32,
    pub tem_mais: bool,
    pub termos_invalidos: Vec<TermoInvalido>,
    pub total_paginas: Option<i32>,
    pub total_registros: Option<i64>,
    pub truncado: bool,
}
```

</Tab>
</Tabs>

### ImportacaoProdutos [#tipo-importacaoprodutos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ImportacaoProdutos } from "termo_core/portal";

export interface ImportacaoProdutos {
  atualizados: number;
  conflitos: number;
  criados: number;
  falhas: number;
  itens: Array<ItemSincronizado>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ImportacaoProdutos;

pub struct ImportacaoProdutos {
    pub atualizados: i64,
    pub conflitos: i64,
    pub criados: i64,
    pub falhas: i64,
    pub itens: Vec<ItemSincronizado>,
}
```

</Tab>
</Tabs>

### ItemCatalogoTermotubos [#tipo-itemcatalogotermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ItemCatalogoTermotubos } from "termo_core/portal";

export interface ItemCatalogoTermotubos {
  ativo?: boolean | null;
  estoque?: number | null;
  imagem_url?: string | null;
  ja_existe: boolean;
  ncm?: string | null;
  nome: string;
  preco: number;
  preco_a_vista?: number | null;
  sku: string;
  tem_imagem: boolean;
  unidade?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ItemCatalogoTermotubos;

pub struct ItemCatalogoTermotubos {
    pub ativo: Option<bool>,
    pub estoque: Option<i32>,
    pub imagem_url: Option<String>,
    pub ja_existe: bool,
    pub ncm: Option<String>,
    pub nome: String,
    pub preco: f64,
    pub preco_a_vista: Option<f64>,
    pub sku: String,
    pub tem_imagem: bool,
    pub unidade: Option<String>,
}
```

</Tab>
</Tabs>

### ItemSincronizado [#tipo-itemsincronizado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ItemSincronizado } from "termo_core/portal";

export interface ItemSincronizado {
  detalhe?: string | null;
  motivo?: string | null;
  nome?: string | null;
  produto_id?: string | null;
  resultado: string;
  sku: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ItemSincronizado;

pub struct ItemSincronizado {
    pub detalhe: Option<String>,
    pub motivo: Option<String>,
    pub nome: Option<String>,
    pub produto_id: Option<uuid::Uuid>,
    pub resultado: String,
    pub sku: String,
}
```

</Tab>
</Tabs>

### ProdutoTermotubosCriar [#tipo-produtotermotuboscriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoTermotubosCriar } from "termo_core/portal";

export interface ProdutoTermotubosCriar {
  skus: Array<string>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoTermotubosCriar;

pub struct ProdutoTermotubosCriar {
    pub skus: Vec<String>,
}
```

</Tab>
</Tabs>

### ResumoSincronizacaoCatalogo [#tipo-resumosincronizacaocatalogo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResumoSincronizacaoCatalogo } from "termo_core/portal";

export interface ResumoSincronizacaoCatalogo {
  atualizados: number;
  conferidos: number;
  conflitos: number;
  criados: number;
  falhas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ResumoSincronizacaoCatalogo;

pub struct ResumoSincronizacaoCatalogo {
    pub atualizados: i64,
    pub conferidos: i64,
    pub conflitos: i64,
    pub criados: i64,
    pub falhas: i64,
}
```

</Tab>
</Tabs>

### StatusSincronizacaoCatalogo [#tipo-statussincronizacaocatalogo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { StatusSincronizacaoCatalogo } from "termo_core/portal";

export interface StatusSincronizacaoCatalogo {
  cancelada: boolean;
  erro?: string | null;
  etapa?: string | null;
  gravados: number;
  iniciada_em?: string | null;
  resumo: ResumoSincronizacaoCatalogo;
  rodando: boolean;
  terminada_em?: string | null;
  total?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::StatusSincronizacaoCatalogo;

pub struct StatusSincronizacaoCatalogo {
    pub cancelada: bool,
    pub erro: Option<String>,
    pub etapa: Option<String>,
    pub gravados: i64,
    pub iniciada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub resumo: ResumoSincronizacaoCatalogo,
    pub rodando: bool,
    pub terminada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub total: Option<i64>,
}
```

</Tab>
</Tabs>

### TermoInvalido [#tipo-termoinvalido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TermoInvalido } from "termo_core/portal";

export interface TermoInvalido {
  motivo: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::TermoInvalido;

pub struct TermoInvalido {
    pub motivo: String,
    pub valor: String,
}
```

</Tab>
</Tabs>


# Produto Tiny (/docs/servicos/portal/produto_tiny)

> 1 função do TermoPortal para produto tiny.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_filtro_produto_tiny`](#buscar_pelo_filtro_produto_tiny) | `GET /produto_tiny/filtro` | Busca os dados internos de um produto no Tiny |

## `buscar_pelo_filtro_produto_tiny` [#buscar_pelo_filtro_produto_tiny]

<Rota metodo="GET" caminho="/produto_tiny/filtro" credencial />

Busca os dados internos de um produto no Tiny

Só colaborador interno da Termotubos. Consulta ao vivo, na API da Termotubos, o produto do Tiny com o `sku` informado (obrigatório, não vazio): `dados` (preço, custo, custo médio, saldo, reservado, disponível, localização, observações, categoria completa e datas do Tiny), `depositos` (saldo, reservado e disponível por depósito, e se o depósito conta na venda), `historico_estoque` e `historico_preco`. Nada disso é mostrado ao cliente.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_produto_tiny(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroProdutoTiny,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ProdutoTiny>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_produto_tiny } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_produto_tiny(credencial_de_acesso, { sku });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_produto_tiny(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroProdutoTiny,
) -> Result<tipos::ProdutoTiny, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_produto_tiny(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroProdutoTiny { sku },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.sku": { type: "string", required: true, description: "Rust: String" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ProdutoTiny>` · Rust: `Result<tipos::ProdutoTiny, ErroAoChamarServico>` · veja [`ProdutoTiny`](#tipo-produtotiny).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### DadosInternosProdutoTermotubos [#tipo-dadosinternosprodutotermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DadosInternosProdutoTermotubos } from "termo_core/portal";

export interface DadosInternosProdutoTermotubos {
  alterado_no_tiny?: string | null;
  categoria_completa?: string | null;
  criado_no_tiny?: string | null;
  custo?: number | null;
  custo_medio?: number | null;
  disponivel?: number | null;
  estoque_atualizado_em?: string | null;
  id_api: number;
  localizacao?: string | null;
  observacoes?: string | null;
  preco?: number | null;
  reservado?: number | null;
  saldo?: number | null;
  sincronizado_na_api?: string | null;
  tiny_id?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::DadosInternosProdutoTermotubos;

pub struct DadosInternosProdutoTermotubos {
    pub alterado_no_tiny: Option<String>,
    pub categoria_completa: Option<String>,
    pub criado_no_tiny: Option<String>,
    pub custo: Option<f64>,
    pub custo_medio: Option<f64>,
    pub disponivel: Option<f64>,
    pub estoque_atualizado_em: Option<String>,
    pub id_api: i64,
    pub localizacao: Option<String>,
    pub observacoes: Option<String>,
    pub preco: Option<f64>,
    pub reservado: Option<f64>,
    pub saldo: Option<f64>,
    pub sincronizado_na_api: Option<String>,
    pub tiny_id: Option<i64>,
}
```

</Tab>
</Tabs>

### DepositoProdutoTermotubos [#tipo-depositoprodutotermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DepositoProdutoTermotubos } from "termo_core/portal";

export interface DepositoProdutoTermotubos {
  atualizado_em?: string | null;
  conta_na_venda: boolean;
  deposito_tiny_id?: number | null;
  disponivel?: number | null;
  nome: string;
  reservado?: number | null;
  saldo?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::DepositoProdutoTermotubos;

pub struct DepositoProdutoTermotubos {
    pub atualizado_em: Option<String>,
    pub conta_na_venda: bool,
    pub deposito_tiny_id: Option<i64>,
    pub disponivel: Option<f64>,
    pub nome: String,
    pub reservado: Option<f64>,
    pub saldo: Option<f64>,
}
```

</Tab>
</Tabs>

### HistoricoEstoqueTermotubos [#tipo-historicoestoquetermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { HistoricoEstoqueTermotubos } from "termo_core/portal";

export interface HistoricoEstoqueTermotubos {
  data: string;
  disponivel?: number | null;
  reservado?: number | null;
  saldo?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::HistoricoEstoqueTermotubos;

pub struct HistoricoEstoqueTermotubos {
    pub data: String,
    pub disponivel: Option<f64>,
    pub reservado: Option<f64>,
    pub saldo: Option<f64>,
}
```

</Tab>
</Tabs>

### HistoricoPrecoTermotubos [#tipo-historicoprecotermotubos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { HistoricoPrecoTermotubos } from "termo_core/portal";

export interface HistoricoPrecoTermotubos {
  custo?: number | null;
  custo_medio?: number | null;
  data: string;
  preco?: number | null;
  preco_promocional?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::HistoricoPrecoTermotubos;

pub struct HistoricoPrecoTermotubos {
    pub custo: Option<f64>,
    pub custo_medio: Option<f64>,
    pub data: String,
    pub preco: Option<f64>,
    pub preco_promocional: Option<f64>,
}
```

</Tab>
</Tabs>

### ProdutoTiny [#tipo-produtotiny]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProdutoTiny } from "termo_core/portal";

export interface ProdutoTiny {
  dados?: DadosInternosProdutoTermotubos | null;
  depositos: Array<DepositoProdutoTermotubos>;
  historico_estoque: Array<HistoricoEstoqueTermotubos>;
  historico_preco: Array<HistoricoPrecoTermotubos>;
  sku: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ProdutoTiny;

pub struct ProdutoTiny {
    pub dados: Option<DadosInternosProdutoTermotubos>,
    pub depositos: Vec<DepositoProdutoTermotubos>,
    pub historico_estoque: Vec<HistoricoEstoqueTermotubos>,
    pub historico_preco: Vec<HistoricoPrecoTermotubos>,
    pub sku: String,
}
```

</Tab>
</Tabs>


# Rastreamento (/docs/servicos/portal/rastreamento)

> 7 funções do TermoPortal para rastreamento.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_rastreamento`](#buscar_paginador_rastreamento) | `GET /rastreamento` | Uma página das entregas (expedições), por cursor |
| [`buscar_auto_complete_rastreamento`](#buscar_auto_complete_rastreamento) | `GET /rastreamento/autocomplete` | Transportadoras ou vendedores das entregas |
| [`buscar_informacoes_paginador_rastreamento`](#buscar_informacoes_paginador_rastreamento) | `GET /rastreamento/paginador` | Total, páginas e contagens por situação das entregas |
| [`buscar_sincronizacao_rastreamento`](#buscar_sincronizacao_rastreamento) | `GET /rastreamento/sincronizacao` | Status da sincronização das entregas |
| [`iniciar_sincronizacao_rastreamento`](#iniciar_sincronizacao_rastreamento) | `POST /rastreamento/sincronizacao` | Inicia a sincronização das entregas em segundo plano |
| [`cancelar_sincronizacao_rastreamento`](#cancelar_sincronizacao_rastreamento) | `DELETE /rastreamento/sincronizacao` | Cancela a sincronização das entregas em andamento |
| [`buscar_pelo_id_rastreamento`](#buscar_pelo_id_rastreamento) | `GET /rastreamento/{id}` | Busca uma entrega pelo id da logística |

## `buscar_paginador_rastreamento` [#buscar_paginador_rastreamento]

<Rota metodo="GET" caminho="/rastreamento" credencial />

Uma página das entregas (expedições), por cursor

Exige a permissão `ver` no módulo `Pedidos` do perfil de quem chama (administrador e master têm tudo). Lê a tabela `rastreamento`, a cópia das entregas da API de logística da Termotubos mantida pela sincronização do backend (rodada rápida a cada 15 min com os últimos 30 dias e completa a cada 6 h com os últimos 120 dias). Ordem: emissão mais recente primeiro (empate pelo id). Devolve só o array das 50 entregas da página; a seguinte manda em `cursor` o `id` da última entrega recebida. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão e só vê as entregas do CNPJ dela, sem dados do vendedor. Filtros: `situacao` (`todas`, `aguardando`, `transito`, `entregue`, `atrasada`; padrão `todas`), `busca` (CPF/CNPJ do cliente, número da nota fiscal ou nome do cliente, sem acento), `inicio` e `fim` (AAAA-MM-DD, data de emissão), `transportadora` (nome) e `vendedor` (id do vendedor no Tiny). Total, páginas e contagens vêm de `GET /rastreamento/paginador`, com os mesmos filtros.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorRastreamento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Rastreamento>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_rastreamento(credencial_de_acesso, { situacao: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorRastreamento,
) -> Result<Vec<tipos::Rastreamento>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_rastreamento(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorRastreamento { situacao: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.auxiliar_uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_vendedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Rastreamento>>` · Rust: `Result<Vec<tipos::Rastreamento>, ErroAoChamarServico>`

## `buscar_auto_complete_rastreamento` [#buscar_auto_complete_rastreamento]

<Rota metodo="GET" caminho="/rastreamento/autocomplete" credencial />

Transportadoras ou vendedores das entregas

Exige a permissão `ver` no módulo `Pedidos`. Opções para os filtros da tela de rastreamento, tiradas da tabela `rastreamento` (entregas dos últimos 30 dias no painel, 12 meses para um cliente), da mais usada para a menos usada, no máximo 50: `tipo` `transportadora` (valor = nome) ou `vendedor` (valor = id no Tiny; só colaborador interno). Cada opção traz `valor`, `rotulo` e a quantidade de `entregas`. Quem não é colaborador interno precisa informar `unidade_id` de uma unidade da sessão. Lista inteira, sem paginação.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteRastreamento,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.OpcaoDeFiltro>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_rastreamento(credencial_de_acesso, { tipo });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteRastreamento,
) -> Result<Vec<tipos::OpcaoDeFiltro>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_rastreamento(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteRastreamento { tipo, ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tipo": { type: "string", required: true, description: "Rust: String" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.OpcaoDeFiltro>>` · Rust: `Result<Vec<tipos::OpcaoDeFiltro>, ErroAoChamarServico>`

## `buscar_informacoes_paginador_rastreamento` [#buscar_informacoes_paginador_rastreamento]

<Rota metodo="GET" caminho="/rastreamento/paginador" credencial />

Total, páginas e contagens por situação das entregas

Mesma permissão e mesmos parâmetros de `GET /rastreamento` (`cursor` não muda a conta). Devolve `total` (entregas com os filtros e a situação), `paginas` (total dividido por `tamanho`, arredondado para cima, no mínimo 1), `tamanho` (sempre 50), `sincronizado_em` (a última sincronização; nulo se nunca houve) e `contagens` por situação (`todas`, `aguardando`, `transito`, `entregues`, `atrasadas`), que usam os outros filtros e ignoram a `situacao`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_informacoes_paginador_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarInformacoesPaginadorRastreamento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.RastreamentoPaginador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_informacoes_paginador_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_informacoes_paginador_rastreamento(credencial_de_acesso, { situacao: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_informacoes_paginador_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarInformacoesPaginadorRastreamento,
) -> Result<tipos::RastreamentoPaginador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_informacoes_paginador_rastreamento(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarInformacoesPaginadorRastreamento { situacao: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.vendedor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.unidade_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cursor": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.auxiliar_uf": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_vendedor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_transportadora": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.auxiliar_situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.RastreamentoPaginador>` · Rust: `Result<tipos::RastreamentoPaginador, ErroAoChamarServico>` · veja [`RastreamentoPaginador`](#tipo-rastreamentopaginador).

## `buscar_sincronizacao_rastreamento` [#buscar_sincronizacao_rastreamento]

<Rota metodo="GET" caminho="/rastreamento/sincronizacao" credencial />

Status da sincronização das entregas

Só colaborador interno com `ver` no módulo `Pedidos`. Devolve a sincronização em andamento ou a última que terminou: `rodando`, `pagina` de `total_paginas` (páginas da API), `progresso` (percentual), `gravados`, `cancelada`, `concluida`, `erro`, `iniciada_em` e `terminada_em`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_sincronizacao_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusSincronizacaoRastreamento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_sincronizacao_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_sincronizacao_rastreamento(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_sincronizacao_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusSincronizacaoRastreamento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_sincronizacao_rastreamento(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusSincronizacaoRastreamento>` · Rust: `Result<tipos::StatusSincronizacaoRastreamento, ErroAoChamarServico>` · veja [`StatusSincronizacaoRastreamento`](#tipo-statussincronizacaorastreamento).

## `iniciar_sincronizacao_rastreamento` [#iniciar_sincronizacao_rastreamento]

<Rota metodo="POST" caminho="/rastreamento/sincronizacao" credencial />

Inicia a sincronização das entregas em segundo plano

Só colaborador interno com `ver` no módulo `Pedidos`. Traz as entregas (expedições) da API de logística da Termotubos para a tabela `rastreamento`, sem filtro de data (histórico inteiro), lote por lote, em segundo plano no servidor: a tela pode ser fechada. Responde 202 com o status inicial; acompanhe por `GET /rastreamento/sincronizacao`. O status fica em memória e se perde se o servidor reiniciar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function iniciar_sincronizacao_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusSincronizacaoRastreamento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { iniciar_sincronizacao_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await iniciar_sincronizacao_rastreamento(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn iniciar_sincronizacao_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusSincronizacaoRastreamento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::iniciar_sincronizacao_rastreamento(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusSincronizacaoRastreamento>` · Rust: `Result<tipos::StatusSincronizacaoRastreamento, ErroAoChamarServico>` · veja [`StatusSincronizacaoRastreamento`](#tipo-statussincronizacaorastreamento).

## `cancelar_sincronizacao_rastreamento` [#cancelar_sincronizacao_rastreamento]

<Rota metodo="DELETE" caminho="/rastreamento/sincronizacao" credencial />

Cancela a sincronização das entregas em andamento

Só colaborador interno com `ver` no módulo `Pedidos`. Para antes do próximo lote; o que já foi gravado fica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function cancelar_sincronizacao_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { cancelar_sincronizacao_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await cancelar_sincronizacao_rastreamento(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn cancelar_sincronizacao_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::cancelar_sincronizacao_rastreamento(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `buscar_pelo_id_rastreamento` [#buscar_pelo_id_rastreamento]

<Rota metodo="GET" caminho="/rastreamento/{id}" credencial />

Busca uma entrega pelo id da logística

Exige a permissão `ver` no módulo `Pedidos`. Lê a entrega da tabela `rastreamento` (nota, transportadora, previsão, rastreio, ocorrência). Quem não é colaborador interno só abre entregas do CNPJ das próprias unidades (as outras respondem 404) e não recebe os dados do vendedor.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_rastreamento(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Rastreamento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_rastreamento } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_rastreamento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_rastreamento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::Rastreamento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_rastreamento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Rastreamento>` · Rust: `Result<tipos::Rastreamento, ErroAoChamarServico>` · veja [`Rastreamento`](#tipo-rastreamento).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ContagemRastreamento [#tipo-contagemrastreamento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ContagemRastreamento } from "termo_core/portal";

export interface ContagemRastreamento {
  aguardando: number;
  atrasadas: number;
  entregues: number;
  todas: number;
  transito: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::ContagemRastreamento;

pub struct ContagemRastreamento {
    pub aguardando: i64,
    pub atrasadas: i64,
    pub entregues: i64,
    pub todas: i64,
    pub transito: i64,
}
```

</Tab>
</Tabs>

### OpcaoDeFiltro [#tipo-opcaodefiltro]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { OpcaoDeFiltro } from "termo_core/portal";

export interface OpcaoDeFiltro {
  entregas: number;
  rotulo: string;
  valor: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::OpcaoDeFiltro;

pub struct OpcaoDeFiltro {
    pub entregas: i64,
    pub rotulo: String,
    pub valor: String,
}
```

</Tab>
</Tabs>

### Rastreamento [#tipo-rastreamento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Rastreamento } from "termo_core/portal";

export interface Rastreamento {
  atualizado_em?: string | null;
  cep?: string | null;
  cidade?: string | null;
  cliente?: string | null;
  cliente_documento?: string | null;
  codigo_rastreio?: string | null;
  emissao?: string | null;
  entrega?: string | null;
  envio?: string | null;
  frete?: number | null;
  id: number;
  link_rastreio?: string | null;
  nota_fiscal?: number | null;
  nota_tiny_id?: number | null;
  ocorrencia?: string | null;
  peso_kg?: number | null;
  previsao?: string | null;
  sincronizado_em: string;
  situacao?: string | null;
  situacao_id?: number | null;
  transportadora?: string | null;
  transportadora_documento?: string | null;
  uf?: string | null;
  valor_mercadorias?: number | null;
  valor_nota?: number | null;
  vendedor?: string | null;
  vendedor_tiny_id?: number | null;
  volumes?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Rastreamento;

pub struct Rastreamento {
    pub atualizado_em: Option<String>,
    pub cep: Option<String>,
    pub cidade: Option<String>,
    pub cliente: Option<String>,
    pub cliente_documento: Option<String>,
    pub codigo_rastreio: Option<String>,
    pub emissao: Option<chrono::NaiveDate>,
    pub entrega: Option<chrono::NaiveDate>,
    pub envio: Option<chrono::NaiveDate>,
    pub frete: Option<f64>,
    pub id: i64,
    pub link_rastreio: Option<String>,
    pub nota_fiscal: Option<i64>,
    pub nota_tiny_id: Option<i64>,
    pub ocorrencia: Option<String>,
    pub peso_kg: Option<f64>,
    pub previsao: Option<chrono::NaiveDate>,
    pub sincronizado_em: chrono::DateTime<chrono::Utc>,
    pub situacao: Option<String>,
    pub situacao_id: Option<i64>,
    pub transportadora: Option<String>,
    pub transportadora_documento: Option<String>,
    pub uf: Option<String>,
    pub valor_mercadorias: Option<f64>,
    pub valor_nota: Option<f64>,
    pub vendedor: Option<String>,
    pub vendedor_tiny_id: Option<i64>,
    pub volumes: Option<i64>,
}
```

</Tab>
</Tabs>

### RastreamentoPaginador [#tipo-rastreamentopaginador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RastreamentoPaginador } from "termo_core/portal";

export interface RastreamentoPaginador {
  contagens: ContagemRastreamento;
  paginas: number;
  sincronizado_em?: string | null;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::RastreamentoPaginador;

pub struct RastreamentoPaginador {
    pub contagens: ContagemRastreamento,
    pub paginas: i64,
    pub sincronizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### StatusSincronizacaoRastreamento [#tipo-statussincronizacaorastreamento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { StatusSincronizacaoRastreamento } from "termo_core/portal";

export interface StatusSincronizacaoRastreamento {
  cancelada: boolean;
  concluida: boolean;
  erro?: string | null;
  gravados: number;
  iniciada_em?: string | null;
  pagina: number;
  progresso: number;
  rodando: boolean;
  terminada_em?: string | null;
  total_paginas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::StatusSincronizacaoRastreamento;

pub struct StatusSincronizacaoRastreamento {
    pub cancelada: bool,
    pub concluida: bool,
    pub erro: Option<String>,
    pub gravados: i64,
    pub iniciada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub pagina: i32,
    pub progresso: i32,
    pub rodando: bool,
    pub terminada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub total_paginas: i32,
}
```

</Tab>
</Tabs>


# Tabela auxiliar (/docs/servicos/portal/tabela_auxiliar)

> 7 funções do TermoPortal para tabela auxiliar.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_tabela_auxiliar`](#buscar_paginador_tabela_auxiliar) | `GET /tabela_auxiliar` | Lista os valores auxiliares paginados |
| [`criar_tabela_auxiliar`](#criar_tabela_auxiliar) | `POST /tabela_auxiliar` | Cadastra um valor auxiliar |
| [`buscar_auto_complete_tabela_auxiliar`](#buscar_auto_complete_tabela_auxiliar) | `GET /tabela_auxiliar/autocomplete` | Lista básica de valores de um campo para seleção |
| [`buscar_pelo_filtro_tabela_auxiliar`](#buscar_pelo_filtro_tabela_auxiliar) | `GET /tabela_auxiliar/filtro` | Busca valores auxiliares por filtro |
| [`buscar_pelo_id_tabela_auxiliar`](#buscar_pelo_id_tabela_auxiliar) | `GET /tabela_auxiliar/{id}` | Busca um valor auxiliar pelo id |
| [`atualizar_pelo_id_tabela_auxiliar`](#atualizar_pelo_id_tabela_auxiliar) | `PATCH /tabela_auxiliar/{id}` | Atualiza o label de um valor auxiliar |
| [`deletar_pelo_id_tabela_auxiliar`](#deletar_pelo_id_tabela_auxiliar) | `DELETE /tabela_auxiliar/{id}` | Exclui um valor auxiliar |

## `buscar_paginador_tabela_auxiliar` [#buscar_paginador_tabela_auxiliar]

<Rota metodo="GET" caminho="/tabela_auxiliar" credencial />

Lista os valores auxiliares paginados

Exige sessão. Ordenado por tabela, campo e label. `tabela` e `campo` filtram (opcionais). Paginado com 50 itens por página (fixo); `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorTabelaAuxiliar = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTabelaAuxiliar>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_tabela_auxiliar(credencial_de_acesso, { tabela: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorTabelaAuxiliar,
) -> Result<tipos::PaginaTabelaAuxiliar, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_tabela_auxiliar(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorTabelaAuxiliar { tabela: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tabela": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.campo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTabelaAuxiliar>` · Rust: `Result<tipos::PaginaTabelaAuxiliar, ErroAoChamarServico>` · veja [`PaginaTabelaAuxiliar`](#tipo-paginatabelaauxiliar).

## `criar_tabela_auxiliar` [#criar_tabela_auxiliar]

<Rota metodo="POST" caminho="/tabela_auxiliar" credencial />

Cadastra um valor auxiliar

Exige o módulo `Configuracoes` (criar). Valor de um campo que chega das integrações sem cadastro próprio (ex.: `tabela=produto`, `campo=marca_tiny`). `tabela`, `campo` e `label` obrigatórios; o trio é único. A sincronização do catálogo preenche a tabela sozinha.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.TabelaAuxiliarCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TabelaAuxiliar>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_tabela_auxiliar(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::TabelaAuxiliarCriar,
) -> Result<tipos::TabelaAuxiliar, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_tabela_auxiliar(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.TabelaAuxiliarCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TabelaAuxiliarCriar", typeDescriptionLink: "#tipo-tabelaauxiliarcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TabelaAuxiliar>` · Rust: `Result<tipos::TabelaAuxiliar, ErroAoChamarServico>` · veja [`TabelaAuxiliar`](#tipo-tabelaauxiliar).

## `buscar_auto_complete_tabela_auxiliar` [#buscar_auto_complete_tabela_auxiliar]

<Rota metodo="GET" caminho="/tabela_auxiliar/autocomplete" credencial />

Lista básica de valores de um campo para seleção

Exige sessão. `tabela` e `campo` obrigatórios (ex.: `produto` e `marca_tiny`). Devolve só id e label, em ordem alfabética. `busca` procura no label. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteTabelaAuxiliar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTabelaAuxiliarAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_tabela_auxiliar(credencial_de_acesso, { tabela, campo });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteTabelaAuxiliar,
) -> Result<tipos::PaginaTabelaAuxiliarAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_tabela_auxiliar(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteTabelaAuxiliar { tabela, campo, ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tabela": { type: "string", required: true, description: "Rust: String" },
    "parametros.campo": { type: "string", required: true, description: "Rust: String" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTabelaAuxiliarAutoComplete>` · Rust: `Result<tipos::PaginaTabelaAuxiliarAutoComplete, ErroAoChamarServico>` · veja [`PaginaTabelaAuxiliarAutoComplete`](#tipo-paginatabelaauxiliarautocomplete).

## `buscar_pelo_filtro_tabela_auxiliar` [#buscar_pelo_filtro_tabela_auxiliar]

<Rota metodo="GET" caminho="/tabela_auxiliar/filtro" credencial />

Busca valores auxiliares por filtro

Exige sessão. Até 50 por página (`pagina`, a partir de 1, padrão 1). `tabela` e `campo` são exatos; `label` procura o trecho.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroTabelaAuxiliar = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.TabelaAuxiliar>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_tabela_auxiliar(credencial_de_acesso, { tabela: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroTabelaAuxiliar,
) -> Result<Vec<tipos::TabelaAuxiliar>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_tabela_auxiliar(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroTabelaAuxiliar { tabela: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tabela": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.campo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.label": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.TabelaAuxiliar>>` · Rust: `Result<Vec<tipos::TabelaAuxiliar>, ErroAoChamarServico>`

## `buscar_pelo_id_tabela_auxiliar` [#buscar_pelo_id_tabela_auxiliar]

<Rota metodo="GET" caminho="/tabela_auxiliar/{id}" credencial />

Busca um valor auxiliar pelo id

Exige sessão. Registro excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TabelaAuxiliar>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_tabela_auxiliar(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::TabelaAuxiliar, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_tabela_auxiliar(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TabelaAuxiliar>` · Rust: `Result<tipos::TabelaAuxiliar, ErroAoChamarServico>` · veja [`TabelaAuxiliar`](#tipo-tabelaauxiliar).

## `atualizar_pelo_id_tabela_auxiliar` [#atualizar_pelo_id_tabela_auxiliar]

<Rota metodo="PATCH" caminho="/tabela_auxiliar/{id}" credencial />

Atualiza o label de um valor auxiliar

Exige o módulo `Configuracoes` (editar). Muda só o `label`; campo ausente mantém o valor atual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.TabelaAuxiliarAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TabelaAuxiliar>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_tabela_auxiliar(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::TabelaAuxiliarAtualizar,
) -> Result<tipos::TabelaAuxiliar, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_tabela_auxiliar(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.TabelaAuxiliarAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TabelaAuxiliarAtualizar", typeDescriptionLink: "#tipo-tabelaauxiliaratualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TabelaAuxiliar>` · Rust: `Result<tipos::TabelaAuxiliar, ErroAoChamarServico>` · veja [`TabelaAuxiliar`](#tipo-tabelaauxiliar).

## `deletar_pelo_id_tabela_auxiliar` [#deletar_pelo_id_tabela_auxiliar]

<Rota metodo="DELETE" caminho="/tabela_auxiliar/{id}" credencial />

Exclui um valor auxiliar

Exige o módulo `Configuracoes` (excluir). A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_tabela_auxiliar(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_tabela_auxiliar } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_tabela_auxiliar(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_tabela_auxiliar(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_tabela_auxiliar(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaTabelaAuxiliar [#tipo-paginatabelaauxiliar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTabelaAuxiliar } from "termo_core/portal";

export interface PaginaTabelaAuxiliar {
  itens: Array<PaginaTabelaAuxiliarItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaTabelaAuxiliar;

pub struct PaginaTabelaAuxiliar {
    pub itens: Vec<PaginaTabelaAuxiliarItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTabelaAuxiliarAutoComplete [#tipo-paginatabelaauxiliarautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTabelaAuxiliarAutoComplete } from "termo_core/portal";

export interface PaginaTabelaAuxiliarAutoComplete {
  itens: Array<PaginaTabelaAuxiliarAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaTabelaAuxiliarAutoComplete;

pub struct PaginaTabelaAuxiliarAutoComplete {
    pub itens: Vec<PaginaTabelaAuxiliarAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTabelaAuxiliarAutoCompleteItensItem [#tipo-paginatabelaauxiliarautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTabelaAuxiliarAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaTabelaAuxiliarAutoCompleteItensItem {
  id: string;
  label: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaTabelaAuxiliarAutoCompleteItensItem;

pub struct PaginaTabelaAuxiliarAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub label: String,
}
```

</Tab>
</Tabs>

### PaginaTabelaAuxiliarItensItem [#tipo-paginatabelaauxiliaritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTabelaAuxiliarItensItem } from "termo_core/portal";

export interface PaginaTabelaAuxiliarItensItem {
  atualizado_em: string;
  campo: string;
  criado_em: string;
  id: string;
  label: string;
  tabela: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaTabelaAuxiliarItensItem;

pub struct PaginaTabelaAuxiliarItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub campo: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub label: String,
    pub tabela: String,
}
```

</Tab>
</Tabs>

### TabelaAuxiliar [#tipo-tabelaauxiliar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TabelaAuxiliar } from "termo_core/portal";

export interface TabelaAuxiliar {
  atualizado_em: string;
  campo: string;
  criado_em: string;
  id: string;
  label: string;
  tabela: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::TabelaAuxiliar;

pub struct TabelaAuxiliar {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub campo: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub label: String,
    pub tabela: String,
}
```

</Tab>
</Tabs>

### TabelaAuxiliarAtualizar [#tipo-tabelaauxiliaratualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TabelaAuxiliarAtualizar } from "termo_core/portal";

export interface TabelaAuxiliarAtualizar {
  label?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::TabelaAuxiliarAtualizar;

pub struct TabelaAuxiliarAtualizar {
    pub label: Option<String>,
}
```

</Tab>
</Tabs>

### TabelaAuxiliarCriar [#tipo-tabelaauxiliarcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TabelaAuxiliarCriar } from "termo_core/portal";

export interface TabelaAuxiliarCriar {
  campo: string;
  label: string;
  tabela: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::TabelaAuxiliarCriar;

pub struct TabelaAuxiliarCriar {
    pub campo: String,
    pub label: String,
    pub tabela: String,
}
```

</Tab>
</Tabs>


# Unidade (/docs/servicos/portal/unidade)

> 7 funções do TermoPortal para unidade.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_unidade`](#buscar_paginador_unidade) | `GET /unidade` | Lista as unidades paginadas |
| [`criar_unidade`](#criar_unidade) | `POST /unidade` | Cadastra uma unidade ou pede uma nova unidade |
| [`buscar_auto_complete_unidade`](#buscar_auto_complete_unidade) | `GET /unidade/autocomplete` | Lista básica de unidades para seleção |
| [`buscar_pelo_filtro_unidade`](#buscar_pelo_filtro_unidade) | `GET /unidade/filtro` | Busca unidades por filtro |
| [`buscar_pelo_id_unidade`](#buscar_pelo_id_unidade) | `GET /unidade/{id}` | Busca uma unidade pelo id |
| [`atualizar_pelo_id_unidade`](#atualizar_pelo_id_unidade) | `PATCH /unidade/{id}` | Atualiza uma unidade |
| [`deletar_pelo_id_unidade`](#deletar_pelo_id_unidade) | `DELETE /unidade/{id}` | Exclui uma unidade |

## `buscar_paginador_unidade` [#buscar_paginador_unidade]

<Rota metodo="GET" caminho="/unidade" credencial />

Lista as unidades paginadas

Exige só uma sessão válida (qualquer pessoa logada no portal). Colaborador interno vê todas, em ordem alfabética. Cliente recebe numa página só as unidades da própria sessão (`tamanho` igual à quantidade). Para colaborador interno: 50 itens por página (fixo), `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorUnidade = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaUnidade>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_unidade(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorUnidade,
) -> Result<tipos::PaginaUnidade, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_paginador_unidade(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPaginadorUnidade { pagina: Some(1) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaUnidade>` · Rust: `Result<tipos::PaginaUnidade, ErroAoChamarServico>` · veja [`PaginaUnidade`](#tipo-paginaunidade).

## `criar_unidade` [#criar_unidade]

<Rota metodo="POST" caminho="/unidade" credencial />

Cadastra uma unidade ou pede uma nova unidade

Exige só uma sessão válida (qualquer pessoa logada no portal). Unidade cliente (unidade) do portal. Colaborador interno com a permissão administrativa `usuarios.gerenciar` cadastra qualquer unidade; cliente só pede uma nova unidade, que nasce `pendente`, ligada a ele e sem matriz ou limite (no máximo 3 pedidos em análise). `cnpj` (CNPJ ou CPF válido) é único; `razao_social` obrigatória até 150 caracteres; `email_comercial` obrigatório e válido; `telefone_comercial` com 10 ou 11 dígitos; `status` `ativo`, `pendente` ou `inativo`; `limite_faturamento` zero ou mais; `aviso_limite_percentual` de 1 a 100; `matriz_id` precisa ser uma unidade que não é filial. Com `tiny`, confere antes se o documento tem conta no Tiny. Até 20 chamadas por minuto por pessoa. `tiny.verificado_por_pessoa_id` (uuid, opcional) registra quem conferiu o cadastro no Tiny. Campos: `nome_fantasia` até 150 caracteres; `inscricao_estadual` até 30 caracteres; `inscricao_municipal` até 30 caracteres; `site` é o endereço do site (URL válida); `responsavel_principal` até 150 caracteres; `contato_financeiro` até 150 caracteres; `contato_compras` até 150 caracteres.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.UnidadeCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Unidade>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_unidade(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::UnidadeCriar,
) -> Result<tipos::Unidade, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::criar_unidade(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.UnidadeCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::UnidadeCriar", typeDescriptionLink: "#tipo-unidadecriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Unidade>` · Rust: `Result<tipos::Unidade, ErroAoChamarServico>` · veja [`Unidade`](#tipo-unidade).

## `buscar_auto_complete_unidade` [#buscar_auto_complete_unidade]

<Rota metodo="GET" caminho="/unidade/autocomplete" credencial />

Lista básica de unidades para seleção

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve id, razão social e CNPJ, em ordem alfabética. `busca` procura na razão social ou no CNPJ; `status` filtra. Cliente recebe só as unidades da própria sessão. `tamanho` tem padrão 10 e vai de 1 a 50; `pagina` começa em 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteUnidade = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaUnidadeAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_unidade(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteUnidade,
) -> Result<tipos::PaginaUnidadeAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_auto_complete_unidade(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarAutoCompleteUnidade { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaUnidadeAutoComplete>` · Rust: `Result<tipos::PaginaUnidadeAutoComplete, ErroAoChamarServico>` · veja [`PaginaUnidadeAutoComplete`](#tipo-paginaunidadeautocomplete).

## `buscar_pelo_filtro_unidade` [#buscar_pelo_filtro_unidade]

<Rota metodo="GET" caminho="/unidade/filtro" credencial />

Busca unidades por filtro

Exige só uma sessão válida (qualquer pessoa logada no portal). Devolve as unidades não excluídas que casam com o filtro, até 50 por página (`pagina`, a partir de 1, padrão 1), em ordem alfabética. Cliente só recebe as unidades da própria sessão. `razao_social` procura o trecho na razão social ou no nome fantasia; `cnpj` procura os dígitos; `status`, `matriz_id` e `cliente_id` são exatos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroUnidade = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Unidade>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_unidade(credencial_de_acesso, { razao_social: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroUnidade,
) -> Result<Vec<tipos::Unidade>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_filtro_unidade(
    &credencial_de_acesso,
    &termo_core::portal::ParametrosDeBuscarPeloFiltroUnidade { razao_social: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.razao_social": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cnpj": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.matriz_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.cliente_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Unidade>>` · Rust: `Result<Vec<tipos::Unidade>, ErroAoChamarServico>`

## `buscar_pelo_id_unidade` [#buscar_pelo_id_unidade]

<Rota metodo="GET" caminho="/unidade/{id}" credencial />

Busca uma unidade pelo id

Exige só uma sessão válida (qualquer pessoa logada no portal). Unidade excluída, ou fora da sessão, responde 404. Traz filiais, pessoas vinculadas, matriz e uso do limite de faturamento.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Unidade>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_unidade(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Unidade, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::buscar_pelo_id_unidade(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Unidade>` · Rust: `Result<tipos::Unidade, ErroAoChamarServico>` · veja [`Unidade`](#tipo-unidade).

## `atualizar_pelo_id_unidade` [#atualizar_pelo_id_unidade]

<Rota metodo="PATCH" caminho="/unidade/{id}" credencial />

Atualiza uma unidade

Exige só uma sessão válida (qualquer pessoa logada no portal). Exige também a permissão `editar` no módulo `Configuracoes`. Só colaborador interno muda `matriz_id`, `status`, `limite_faturamento`, `aviso_limite_percentual` e `cliente_id` (envie `null` em `matriz_id`, `limite_faturamento` ou `cliente_id` para apagar). `cliente_id` vincula a unidade a um cliente, que passa a ver a unidade no portal. Uma unidade com filiais não vira filial e não pode ser matriz de si mesma. Unidade fora da sessão responde 404; o CNPJ não muda. Atualização parcial: campo ausente mantém o valor atual. Campos: `razao_social` até 150 caracteres; `nome_fantasia` até 150 caracteres; `inscricao_estadual` até 30 caracteres; `inscricao_municipal` até 30 caracteres; `telefone_comercial` com 10 ou 11 dígitos; `email_comercial` precisa ser válido; `site` é o endereço do site (URL válida); `responsavel_principal` até 150 caracteres; `contato_financeiro` até 150 caracteres; `contato_compras` até 150 caracteres.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.UnidadeAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Unidade>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_unidade(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::UnidadeAtualizar,
) -> Result<tipos::Unidade, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::portal::atualizar_pelo_id_unidade(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.UnidadeAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::UnidadeAtualizar", typeDescriptionLink: "#tipo-unidadeatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Unidade>` · Rust: `Result<tipos::Unidade, ErroAoChamarServico>` · veja [`Unidade`](#tipo-unidade).

## `deletar_pelo_id_unidade` [#deletar_pelo_id_unidade]

<Rota metodo="DELETE" caminho="/unidade/{id}" credencial />

Exclui uma unidade

Exige só uma sessão válida (qualquer pessoa logada no portal). Exige também a permissão `excluir` no módulo `Configuracoes`. Recusa unidade com filiais. Unidade fora da sessão responde 404. A exclusão é lógica: o registro some das leituras, mas a linha não é apagada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_unidade(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_unidade } from "termo_core/portal";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_unidade(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_unidade(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::portal::deletar_pelo_id_unidade(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaUnidade [#tipo-paginaunidade]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUnidade } from "termo_core/portal";

export interface PaginaUnidade {
  itens: Array<PaginaUnidadeItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaUnidade;

pub struct PaginaUnidade {
    pub itens: Vec<PaginaUnidadeItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaUnidadeAutoComplete [#tipo-paginaunidadeautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUnidadeAutoComplete } from "termo_core/portal";

export interface PaginaUnidadeAutoComplete {
  itens: Array<PaginaUnidadeAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaUnidadeAutoComplete;

pub struct PaginaUnidadeAutoComplete {
    pub itens: Vec<PaginaUnidadeAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaUnidadeAutoCompleteItensItem [#tipo-paginaunidadeautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUnidadeAutoCompleteItensItem } from "termo_core/portal";

export interface PaginaUnidadeAutoCompleteItensItem {
  cnpj: string;
  id: string;
  razao_social: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaUnidadeAutoCompleteItensItem;

pub struct PaginaUnidadeAutoCompleteItensItem {
    pub cnpj: String,
    pub id: uuid::Uuid,
    pub razao_social: String,
}
```

</Tab>
</Tabs>

### PaginaUnidadeItensItem [#tipo-paginaunidadeitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUnidadeItensItem } from "termo_core/portal";

export interface PaginaUnidadeItensItem {
  atualizado_em: string;
  aviso_limite_percentual: number;
  cliente_email?: string | null;
  cliente_id?: string | null;
  cliente_nome?: string | null;
  cnpj: string;
  contato_compras?: string | null;
  contato_financeiro?: string | null;
  criado_em: string;
  email_comercial?: string | null;
  filiais: Array<UnidadeReferencia>;
  id: string;
  inscricao_estadual?: string | null;
  inscricao_municipal?: string | null;
  limite_faturamento?: number | null;
  limite_usado: number;
  matriz_id?: string | null;
  matriz_razao_social?: string | null;
  nome_fantasia?: string | null;
  razao_social: string;
  responsavel_principal?: string | null;
  site?: string | null;
  status: string;
  telefone_comercial?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::PaginaUnidadeItensItem;

pub struct PaginaUnidadeItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub aviso_limite_percentual: i32,
    pub cliente_email: Option<String>,
    pub cliente_id: Option<uuid::Uuid>,
    pub cliente_nome: Option<String>,
    pub cnpj: String,
    pub contato_compras: Option<String>,
    pub contato_financeiro: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email_comercial: Option<String>,
    pub filiais: Vec<UnidadeReferencia>,
    pub id: uuid::Uuid,
    pub inscricao_estadual: Option<String>,
    pub inscricao_municipal: Option<String>,
    pub limite_faturamento: Option<f64>,
    pub limite_usado: f64,
    pub matriz_id: Option<uuid::Uuid>,
    pub matriz_razao_social: Option<String>,
    pub nome_fantasia: Option<String>,
    pub razao_social: String,
    pub responsavel_principal: Option<String>,
    pub site: Option<String>,
    pub status: String,
    pub telefone_comercial: Option<String>,
}
```

</Tab>
</Tabs>

### Unidade [#tipo-unidade]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Unidade } from "termo_core/portal";

export interface Unidade {
  atualizado_em: string;
  aviso_limite_percentual: number;
  cliente_email?: string | null;
  cliente_id?: string | null;
  cliente_nome?: string | null;
  cnpj: string;
  contato_compras?: string | null;
  contato_financeiro?: string | null;
  criado_em: string;
  email_comercial?: string | null;
  filiais: Array<UnidadeReferencia>;
  id: string;
  inscricao_estadual?: string | null;
  inscricao_municipal?: string | null;
  limite_faturamento?: number | null;
  limite_usado: number;
  matriz_id?: string | null;
  matriz_razao_social?: string | null;
  nome_fantasia?: string | null;
  razao_social: string;
  responsavel_principal?: string | null;
  site?: string | null;
  status: string;
  telefone_comercial?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::Unidade;

pub struct Unidade {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub aviso_limite_percentual: i32,
    pub cliente_email: Option<String>,
    pub cliente_id: Option<uuid::Uuid>,
    pub cliente_nome: Option<String>,
    pub cnpj: String,
    pub contato_compras: Option<String>,
    pub contato_financeiro: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email_comercial: Option<String>,
    pub filiais: Vec<UnidadeReferencia>,
    pub id: uuid::Uuid,
    pub inscricao_estadual: Option<String>,
    pub inscricao_municipal: Option<String>,
    pub limite_faturamento: Option<f64>,
    pub limite_usado: f64,
    pub matriz_id: Option<uuid::Uuid>,
    pub matriz_razao_social: Option<String>,
    pub nome_fantasia: Option<String>,
    pub razao_social: String,
    pub responsavel_principal: Option<String>,
    pub site: Option<String>,
    pub status: String,
    pub telefone_comercial: Option<String>,
}
```

</Tab>
</Tabs>

### UnidadeAtualizar [#tipo-unidadeatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UnidadeAtualizar } from "termo_core/portal";

export interface UnidadeAtualizar {
  aviso_limite_percentual?: number | null;
  cliente_id?: string | null;
  contato_compras?: string | null;
  contato_financeiro?: string | null;
  email_comercial?: string | null;
  inscricao_estadual?: string | null;
  inscricao_municipal?: string | null;
  limite_faturamento?: number | null;
  matriz_id?: string | null;
  nome_fantasia?: string | null;
  razao_social?: string | null;
  responsavel_principal?: string | null;
  site?: string | null;
  status?: string | null;
  telefone_comercial?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::UnidadeAtualizar;

pub struct UnidadeAtualizar {
    pub aviso_limite_percentual: Option<i32>,
    pub cliente_id: Option<uuid::Uuid>,
    pub contato_compras: Option<String>,
    pub contato_financeiro: Option<String>,
    pub email_comercial: Option<String>,
    pub inscricao_estadual: Option<String>,
    pub inscricao_municipal: Option<String>,
    pub limite_faturamento: Option<f64>,
    pub matriz_id: Option<uuid::Uuid>,
    pub nome_fantasia: Option<String>,
    pub razao_social: Option<String>,
    pub responsavel_principal: Option<String>,
    pub site: Option<String>,
    pub status: Option<String>,
    pub telefone_comercial: Option<String>,
}
```

</Tab>
</Tabs>

### UnidadeCriar [#tipo-unidadecriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UnidadeCriar } from "termo_core/portal";

export interface UnidadeCriar {
  aviso_limite_percentual?: number | null;
  cnpj: string;
  contato_compras?: string | null;
  contato_financeiro?: string | null;
  email_comercial: string;
  inscricao_estadual?: string | null;
  inscricao_municipal?: string | null;
  limite_faturamento?: number | null;
  matriz_id?: string | null;
  nome_fantasia?: string | null;
  razao_social: string;
  responsavel_principal?: string | null;
  site?: string | null;
  status?: string | null;
  telefone_comercial?: string | null;
  tiny?: UnidadeCriarTiny | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::UnidadeCriar;

pub struct UnidadeCriar {
    pub aviso_limite_percentual: Option<i32>,
    pub cnpj: String,
    pub contato_compras: Option<String>,
    pub contato_financeiro: Option<String>,
    pub email_comercial: String,
    pub inscricao_estadual: Option<String>,
    pub inscricao_municipal: Option<String>,
    pub limite_faturamento: Option<f64>,
    pub matriz_id: Option<uuid::Uuid>,
    pub nome_fantasia: Option<String>,
    pub razao_social: String,
    pub responsavel_principal: Option<String>,
    pub site: Option<String>,
    pub status: Option<String>,
    pub telefone_comercial: Option<String>,
    pub tiny: Option<UnidadeCriarTiny>,
}
```

</Tab>
</Tabs>

### UnidadeCriarTiny [#tipo-unidadecriartiny]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UnidadeCriarTiny } from "termo_core/portal";

export type UnidadeCriarTiny = Record<string, unknown>;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::UnidadeCriarTiny;

pub type UnidadeCriarTiny = serde_json::Map<String, serde_json::Value>;
```

</Tab>
</Tabs>

### UnidadeReferencia [#tipo-unidadereferencia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UnidadeReferencia } from "termo_core/portal";

export interface UnidadeReferencia {
  cnpj: string;
  id: string;
  razao_social: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::UnidadeReferencia;

pub struct UnidadeReferencia {
    pub cnpj: String,
    pub id: uuid::Uuid,
    pub razao_social: String,
}
```

</Tab>
</Tabs>


# Versão (/docs/servicos/portal/versao)

> 1 função do TermoPortal para versão.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as portal from "termo_core/portal";
// ou: import { portal } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["portal"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_versao`](#buscar_pelo_id_versao) | `GET /` | Versão da API |

## `buscar_pelo_id_versao` [#buscar_pelo_id_versao]

<Rota metodo="GET" caminho="/" />

Versão da API

Rota pública: não exige sessão. Confere se a API está no ar e devolve a versão publicada do backend.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_versao(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDaApi>
```

```ts title="Exemplo"
import { buscar_pelo_id_versao } from "termo_core/portal";

const resposta = await buscar_pelo_id_versao();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_versao() -> Result<tipos::VersaoDaApi, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::portal::buscar_pelo_id_versao().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDaApi>` · Rust: `Result<tipos::VersaoDaApi, ErroAoChamarServico>` · veja [`VersaoDaApi`](#tipo-versaodaapi).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### VersaoDaApi [#tipo-versaodaapi]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDaApi } from "termo_core/portal";

export interface VersaoDaApi {
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::portal::VersaoDaApi;

pub struct VersaoDaApi {
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>


# TermoQuality (/docs/servicos/quality)

> Cliente do TermoQuality no termo_core.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as quality from "termo_core/quality";
// ou: import { quality } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["quality"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::quality` (feature `quality`) |
| Importação TypeScript | `termo_core/quality` ou `import { quality } from "termo_core"` |
| Funções | 0 |
| Entidades | 0 |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51071` |
| `SANDBOX` | `https://sandbox-api-quality.termotubos.com.br` |
| `PRODUCTION` | `https://api-quality.termotubos.com.br` |

<Callout type="info" title="Ainda sem funções">O TermoQuality ainda não publicou o `openapi.json` no sandbox, então o módulo existe mas não tem funções. Elas aparecem aqui sozinhas assim que o contrato for publicado e o gerador rodar.</Callout>


# Auth (/docs/servicos/sell/auth)

> 8 funções do TermoSell para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_auth`](#buscar_paginador_auth) | `GET /auth` | Lista os acessos com paginação |
| [`criar_auth`](#criar_auth) | `POST /auth` | Cria um acesso |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Busca o acesso de quem está logado |
| [`buscar_auto_complete_auth`](#buscar_auto_complete_auth) | `GET /auth/autocomplete` | Lista básica de acessos para seleção |
| [`buscar_pelo_filtro_auth`](#buscar_pelo_filtro_auth) | `GET /auth/filtro` | Busca acessos por filtro |
| [`buscar_pelo_id_auth`](#buscar_pelo_id_auth) | `GET /auth/{id}` | Busca um acesso pelo id |
| [`atualizar_pelo_id_auth`](#atualizar_pelo_id_auth) | `PATCH /auth/{id}` | Atualiza um acesso pelo id |
| [`deletar_pelo_id_auth`](#deletar_pelo_id_auth) | `DELETE /auth/{id}` | Exclui um acesso pelo id |

## `buscar_paginador_auth` [#buscar_paginador_auth]

<Rota metodo="GET" caminho="/auth" credencial />

Lista os acessos com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena por perfil e depois por e-mail. Acessos excluídos não aparecem. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_auth(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAuth,
) -> Result<tipos::PaginaAuth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_auth(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorAuth { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuth>` · Rust: `Result<tipos::PaginaAuth, ErroAoChamarServico>` · veja [`PaginaAuth`](#tipo-paginaauth).

## `criar_auth` [#criar_auth]

<Rota metodo="POST" caminho="/auth" credencial />

Cria um acesso

Exige a permissão `criar` da área `colaboradores`. Cadastra quem pode entrar no TermoSell. `email` é obrigatório, com até 160 caracteres, e é gravado em minúsculas, sem espaços nas pontas; `perfil` é `colaborador` ou `cliente`. O acesso nasce ativo e sem nenhuma permissão. Para a pessoa conseguir entrar, o e-mail precisa ser `@termotubos.com.br` e existir no TermoAuth com o mesmo endereço. Para cadastrar um cliente, prefira `POST /cliente`, que cria o acesso junto.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_auth(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AuthCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_auth(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AuthCriar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::criar_auth(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AuthCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthCriar", typeDescriptionLink: "#tipo-authcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Busca o acesso de quem está logado

Livre para qualquer usuário autenticado com acesso ativo, mesmo sem nenhuma permissão liberada. Devolve o acesso de quem chamou (id, e-mail, nome, perfil e se é master do TermoAuth) e as permissões por área (`clientes`, `colaboradores` e `configuracoes`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões e, no primeiro pedido, ganha o acesso e o colaborador automaticamente. `nome` vem do TermoAuth e, se estiver vazio, repete o e-mail. É a chamada que o painel faz antes de mostrar qualquer tela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## `buscar_auto_complete_auth` [#buscar_auto_complete_auth]

<Rota metodo="GET" caminho="/auth/autocomplete" credencial />

Lista básica de acessos para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só id, e-mail e perfil, em ordem alfabética de e-mail, para escolher um acesso. `busca` procura por trecho do e-mail, sem diferenciar maiúsculas; `perfil` compara o valor exato. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_auth(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAuth,
) -> Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_auth(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteAuth { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthAutoComplete>` · Rust: `Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>` · veja [`PaginaAuthAutoComplete`](#tipo-paginaauthautocomplete).

## `buscar_pelo_filtro_auth` [#buscar_pelo_filtro_auth]

<Rota metodo="GET" caminho="/auth/filtro" credencial />

Busca acessos por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os acessos que casam com o filtro, sem paginação, em ordem alfabética de e-mail. `email` procura por trecho, sem diferenciar maiúsculas; `perfil` compara o valor exato (`colaborador` ou `cliente`); `ativo` filtra pela situação. Sem filtro, devolve todos. Acessos excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Auth>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_auth(credencial_de_acesso, { email: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAuth,
) -> Result<Vec<tipos::Auth>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_auth(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroAuth { email: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Auth>>` · Rust: `Result<Vec<tipos::Auth>, ErroAoChamarServico>`

## `buscar_pelo_id_auth` [#buscar_pelo_id_auth]

<Rota metodo="GET" caminho="/auth/{id}" credencial />

Busca um acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Acesso excluído responde `404`. `vinculado` diz se há um colaborador ou um cliente ligado ao acesso, e `nome` é o nome desse colaborador ou a razão social desse cliente. `master` diz se a pessoa é master do TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `atualizar_pelo_id_auth` [#atualizar_pelo_id_auth]

<Rota metodo="PATCH" caminho="/auth/{id}" credencial />

Atualiza um acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `email` (até 160 caracteres, gravado em minúsculas) e `ativo` (acesso inativo é barrado em todas as rotas). O perfil não muda. O acesso de um master do TermoAuth não pode ser alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AuthAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_auth(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AuthAtualizar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_auth(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AuthAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthAtualizar", typeDescriptionLink: "#tipo-authatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `deletar_pelo_id_auth` [#deletar_pelo_id_auth]

<Rota metodo="DELETE" caminho="/auth/{id}" credencial />

Exclui um acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica: o acesso some das consultas e a pessoa deixa de entrar, mas o registro fica guardado e não há como restaurar. Acesso com colaborador ou cliente vinculado não pode ser excluído por aqui (exclua o cliente, que leva o acesso junto). O acesso de um master do TermoAuth não pode ser excluído.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_auth } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/sell";

export interface AcessoAtual {
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::AcessoAtual;

pub struct AcessoAtual {
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/sell";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Auth [#tipo-auth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Auth } from "termo_core/sell";

export interface Auth {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Auth;

pub struct Auth {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### AuthAtualizar [#tipo-authatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthAtualizar } from "termo_core/sell";

export interface AuthAtualizar {
  ativo?: boolean | null;
  email?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::AuthAtualizar;

pub struct AuthAtualizar {
    pub ativo: Option<bool>,
    pub email: Option<String>,
}
```

</Tab>
</Tabs>

### AuthCriar [#tipo-authcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthCriar } from "termo_core/sell";

export interface AuthCriar {
  email: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::AuthCriar;

pub struct AuthCriar {
    pub email: String,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuth [#tipo-paginaauth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuth } from "termo_core/sell";

export interface PaginaAuth {
  itens: Array<PaginaAuthItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaAuth;

pub struct PaginaAuth {
    pub itens: Vec<PaginaAuthItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoComplete [#tipo-paginaauthautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoComplete } from "termo_core/sell";

export interface PaginaAuthAutoComplete {
  itens: Array<PaginaAuthAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaAuthAutoComplete;

pub struct PaginaAuthAutoComplete {
    pub itens: Vec<PaginaAuthAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteItensItem [#tipo-paginaauthautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaAuthAutoCompleteItensItem {
  email: string;
  id: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaAuthAutoCompleteItensItem;

pub struct PaginaAuthAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthItensItem [#tipo-paginaauthitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthItensItem } from "termo_core/sell";

export interface PaginaAuthItensItem {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaAuthItensItem;

pub struct PaginaAuthItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/sell";

export interface Permissoes {
  clientes?: Acoes;
  colaboradores?: Acoes;
  configuracoes?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Permissoes;

pub struct Permissoes {
    pub clientes: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub configuracoes: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Cliente (/docs/servicos/sell/cliente)

> 10 funções do TermoSell para cliente.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_cliente`](#buscar_paginador_cliente) | `GET /cliente` | Lista os clientes com paginação |
| [`criar_cliente`](#criar_cliente) | `POST /cliente` | Cadastra um cliente |
| [`buscar_auto_complete_cliente`](#buscar_auto_complete_cliente) | `GET /cliente/autocomplete` | Lista básica de clientes para seleção |
| [`buscar_pelo_filtro_cliente`](#buscar_pelo_filtro_cliente) | `GET /cliente/filtro` | Busca clientes por filtro |
| [`buscar_sincronizacao_cliente`](#buscar_sincronizacao_cliente) | `GET /cliente/sincronizar` | Status da sincronização dos clientes com o TermoIntranetAPI |
| [`sincronizar_com_intranet_cliente`](#sincronizar_com_intranet_cliente) | `POST /cliente/sincronizar` | Inicia a sincronização dos clientes com o TermoIntranetAPI em segundo plano |
| [`cancelar_sincronizacao_cliente`](#cancelar_sincronizacao_cliente) | `DELETE /cliente/sincronizar` | Cancela a sincronização dos clientes em andamento |
| [`buscar_pelo_id_cliente`](#buscar_pelo_id_cliente) | `GET /cliente/{id}` | Busca um cliente pelo id |
| [`atualizar_pelo_id_cliente`](#atualizar_pelo_id_cliente) | `PATCH /cliente/{id}` | Atualiza um cliente pelo id |
| [`deletar_pelo_id_cliente`](#deletar_pelo_id_cliente) | `DELETE /cliente/{id}` | Exclui um cliente pelo id |

## `buscar_paginador_cliente` [#buscar_paginador_cliente]

<Rota metodo="GET" caminho="/cliente" credencial />

Lista os clientes com paginação

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Ordena pela razão social. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaCliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_cliente(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorCliente,
) -> Result<tipos::PaginaCliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_cliente(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorCliente { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.atendente_ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.estados": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaCliente>` · Rust: `Result<tipos::PaginaCliente, ErroAoChamarServico>` · veja [`PaginaCliente`](#tipo-paginacliente).

## `criar_cliente` [#criar_cliente]

<Rota metodo="POST" caminho="/cliente" credencial />

Cadastra um cliente

Exige a permissão `criar` da área `clientes`. Cria o cliente e, na mesma transação, o acesso dele com perfil `cliente` e o `email` informado. Obrigatórios: `razao_social` (até 150 caracteres), `cnpj` (exatamente 14 dígitos, só números; pode se repetir, porque a intranet repete CNPJ) e `email` (até 160 caracteres, gravado em minúsculas). Opcionais: `nome_fantasia` (até 150), `telefone` (até 20; é por ele que o robô reconhece o cliente no WhatsApp), `cidade` (até 120) e `estado` (2 letras, gravado em maiúsculas). Texto vazio nos opcionais vira `null`. O cliente nasce ativo e com `atendente_ativo` desligado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ClienteCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_cliente(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ClienteCriar,
) -> Result<tipos::Cliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::criar_cliente(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ClienteCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ClienteCriar", typeDescriptionLink: "#tipo-clientecriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cliente>` · Rust: `Result<tipos::Cliente, ErroAoChamarServico>` · veja [`Cliente`](#tipo-cliente).

## `buscar_auto_complete_cliente` [#buscar_auto_complete_cliente]

<Rota metodo="GET" caminho="/cliente/autocomplete" credencial />

Lista básica de clientes para seleção

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve só id, razão social e CNPJ, em ordem alfabética da razão social. `busca` procura o trecho na razão social (sem diferenciar maiúsculas) ou no CNPJ. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaClienteAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_cliente(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteCliente,
) -> Result<tipos::PaginaClienteAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_cliente(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteCliente { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaClienteAutoComplete>` · Rust: `Result<tipos::PaginaClienteAutoComplete, ErroAoChamarServico>` · veja [`PaginaClienteAutoComplete`](#tipo-paginaclienteautocomplete).

## `buscar_pelo_filtro_cliente` [#buscar_pelo_filtro_cliente]

<Rota metodo="GET" caminho="/cliente/filtro" credencial />

Busca clientes por filtro

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve todos os clientes que casam com o filtro, sem paginação, em ordem alfabética da razão social. `razao_social` procura o trecho na razão social ou no nome fantasia; `email` e `cidade` procuram por trecho; todos sem diferenciar maiúsculas. `cnpj` procura o trecho no CNPJ (só dígitos); `telefone` compara só os dígitos, por trecho; `estado` compara a sigla exata; `ativo` e `atendente_ativo` filtram pela situação. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroCliente = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Cliente>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_cliente(credencial_de_acesso, { razao_social: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroCliente,
) -> Result<Vec<tipos::Cliente>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_cliente(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroCliente { razao_social: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.razao_social": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cnpj": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cidade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.estado": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.telefone": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.atendente_ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Cliente>>` · Rust: `Result<Vec<tipos::Cliente>, ErroAoChamarServico>`

## `buscar_sincronizacao_cliente` [#buscar_sincronizacao_cliente]

<Rota metodo="GET" caminho="/cliente/sincronizar" credencial />

Status da sincronização dos clientes com o TermoIntranetAPI

Só para o master do TermoAuth. Devolve a sincronização em andamento ou a última que terminou: `rodando`, `paginas` gravadas, `cancelada`, `erro` (sem permissão no TermoIntranetAPI, indisponibilidade ou falha no banco) e os totais em `resultado`. O status fica em memória e se perde se o servidor reiniciar; o que já foi gravado fica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_sincronizacao_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusDaSincronizacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_sincronizacao_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_sincronizacao_cliente(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_sincronizacao_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusDaSincronizacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_sincronizacao_cliente(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusDaSincronizacao>` · Rust: `Result<tipos::StatusDaSincronizacao, ErroAoChamarServico>` · veja [`StatusDaSincronizacao`](#tipo-statusdasincronizacao).

## `sincronizar_com_intranet_cliente` [#sincronizar_com_intranet_cliente]

<Rota metodo="POST" caminho="/cliente/sincronizar" credencial />

Inicia a sincronização dos clientes com o TermoIntranetAPI em segundo plano

Só para o master do TermoAuth. Percorre toda a lista de clientes do TermoIntranetAPI (`GET /cliente`, paginada por cursor) usando o próprio token de quem chamou e grava aqui: entra todo cliente, pessoa física ou jurídica, com ou sem documento (`cnpj` guarda só os dígitos do CPF ou CNPJ, ou fica vazio); `ignorados` conta só o id repetido na mesma página. Cliente que já existe com o mesmo CNPJ e ainda sem vínculo recebe o `intranet_cliente_id`; cliente já vinculado tem razão social, nome fantasia, telefone (celular, ou telefone fixo na falta dele, só dígitos), e-mail, cidade e estado sobrescritos pela intranet; cliente novo é criado com `atendente_ativo` desligado. Os campos do TermoSell (`ativo`, `atendente_ativo`, `chatwoot_contato_id`) nunca são tocados. Roda em segundo plano no servidor e grava cada página no banco assim que chega: a tela pode ser fechada. Responde 202 com o status inicial; acompanhe por `GET /cliente/sincronizar`. Sem corpo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function sincronizar_com_intranet_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.StatusDaSincronizacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { sincronizar_com_intranet_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await sincronizar_com_intranet_cliente(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn sincronizar_com_intranet_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::StatusDaSincronizacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::sincronizar_com_intranet_cliente(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.StatusDaSincronizacao>` · Rust: `Result<tipos::StatusDaSincronizacao, ErroAoChamarServico>` · veja [`StatusDaSincronizacao`](#tipo-statusdasincronizacao).

## `cancelar_sincronizacao_cliente` [#cancelar_sincronizacao_cliente]

<Rota metodo="DELETE" caminho="/cliente/sincronizar" credencial />

Cancela a sincronização dos clientes em andamento

Só para o master do TermoAuth. Para antes da próxima página; o que já foi gravado fica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function cancelar_sincronizacao_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { cancelar_sincronizacao_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await cancelar_sincronizacao_cliente(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn cancelar_sincronizacao_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::cancelar_sincronizacao_cliente(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `buscar_pelo_id_cliente` [#buscar_pelo_id_cliente]

<Rota metodo="GET" caminho="/cliente/{id}" credencial />

Busca um cliente pelo id

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve o cliente com o e-mail do acesso e o `ultimo_pedido` dele na intranet (`null` quando não foi possível consultar). Cliente excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ClienteDetalhe>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_cliente(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ClienteDetalhe, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_cliente(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ClienteDetalhe>` · Rust: `Result<tipos::ClienteDetalhe, ErroAoChamarServico>` · veja [`ClienteDetalhe`](#tipo-clientedetalhe).

## `atualizar_pelo_id_cliente` [#atualizar_pelo_id_cliente]

<Rota metodo="PATCH" caminho="/cliente/{id}" credencial />

Atualiza um cliente pelo id

Exige a permissão `editar` da área `clientes`. Atualização parcial: só os campos enviados mudam. `razao_social` não pode ficar vazia (até 150 caracteres); `nome_fantasia` (até 150), `telefone` (até 20), `cidade` (até 120) e `estado` (2 letras) aceitam texto vazio para apagar o valor. `ativo` liga ou desliga o cliente e `atendente_ativo` liga ou desliga o atendimento pelo robô no WhatsApp: o robô só responde cliente ativo com `atendente_ativo` ligado; os demais vão direto para a equipe. CNPJ e e-mail não mudam por aqui.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ClienteAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Cliente>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_cliente(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ClienteAtualizar,
) -> Result<tipos::Cliente, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_cliente(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ClienteAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ClienteAtualizar", typeDescriptionLink: "#tipo-clienteatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Cliente>` · Rust: `Result<tipos::Cliente, ErroAoChamarServico>` · veja [`Cliente`](#tipo-cliente).

## `deletar_pelo_id_cliente` [#deletar_pelo_id_cliente]

<Rota metodo="DELETE" caminho="/cliente/{id}" credencial />

Exclui um cliente pelo id

Exige a permissão `deletar` da área `clientes`. A exclusão é lógica e leva junto o acesso do cliente, na mesma transação: os dois somem das consultas, o CNPJ e o e-mail ficam livres para um novo cadastro e não há como restaurar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_cliente(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_cliente } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_cliente(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_cliente(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_cliente(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Cliente [#tipo-cliente]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Cliente } from "termo_core/sell";

export interface Cliente {
  atendente_ativo: boolean;
  ativo: boolean;
  atualizado_em: string;
  chatwoot_contato_id?: number | null;
  cidade?: string | null;
  cnpj: string;
  criado_em: string;
  email?: string | null;
  estado?: string | null;
  id: string;
  intranet_cliente_id?: number | null;
  nome_fantasia?: string | null;
  razao_social: string;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Cliente;

pub struct Cliente {
    pub atendente_ativo: bool,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chatwoot_contato_id: Option<i64>,
    pub cidade: Option<String>,
    pub cnpj: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: Option<String>,
    pub estado: Option<String>,
    pub id: uuid::Uuid,
    pub intranet_cliente_id: Option<i64>,
    pub nome_fantasia: Option<String>,
    pub razao_social: String,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ClienteAtualizar [#tipo-clienteatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteAtualizar } from "termo_core/sell";

export interface ClienteAtualizar {
  atendente_ativo?: boolean | null;
  ativo?: boolean | null;
  cidade?: string | null;
  estado?: string | null;
  nome_fantasia?: string | null;
  razao_social?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ClienteAtualizar;

pub struct ClienteAtualizar {
    pub atendente_ativo: Option<bool>,
    pub ativo: Option<bool>,
    pub cidade: Option<String>,
    pub estado: Option<String>,
    pub nome_fantasia: Option<String>,
    pub razao_social: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ClienteCriar [#tipo-clientecriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteCriar } from "termo_core/sell";

export interface ClienteCriar {
  cidade?: string | null;
  cnpj: string;
  email: string;
  estado?: string | null;
  nome_fantasia?: string | null;
  razao_social: string;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ClienteCriar;

pub struct ClienteCriar {
    pub cidade: Option<String>,
    pub cnpj: String,
    pub email: String,
    pub estado: Option<String>,
    pub nome_fantasia: Option<String>,
    pub razao_social: String,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ClienteDetalhe [#tipo-clientedetalhe]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteDetalhe } from "termo_core/sell";

export type ClienteDetalhe = Cliente & ClienteDetalheParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ClienteDetalhe;

pub type ClienteDetalhe = serde_json::Value;
```

</Tab>
</Tabs>

### ClienteDetalheParte2 [#tipo-clientedetalheparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ClienteDetalheParte2 } from "termo_core/sell";

export interface ClienteDetalheParte2 {
  ultimo_pedido?: Pedido | null;
}
```

</Tab>
<Tab value="Rust">

`termo_core::sell::ClienteDetalheParte2`

</Tab>
</Tabs>

### ItemPedido [#tipo-itempedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ItemPedido } from "termo_core/sell";

export interface ItemPedido {
  descricao: string;
  quantidade: number;
  unidade: string;
  valor_unitario: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ItemPedido;

pub struct ItemPedido {
    pub descricao: String,
    pub quantidade: f64,
    pub unidade: String,
    pub valor_unitario: f64,
}
```

</Tab>
</Tabs>

### PaginaCliente [#tipo-paginacliente]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaCliente } from "termo_core/sell";

export interface PaginaCliente {
  itens: Array<PaginaClienteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaCliente;

pub struct PaginaCliente {
    pub itens: Vec<PaginaClienteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaClienteAutoComplete [#tipo-paginaclienteautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteAutoComplete } from "termo_core/sell";

export interface PaginaClienteAutoComplete {
  itens: Array<PaginaClienteAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaClienteAutoComplete;

pub struct PaginaClienteAutoComplete {
    pub itens: Vec<PaginaClienteAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaClienteAutoCompleteItensItem [#tipo-paginaclienteautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaClienteAutoCompleteItensItem {
  cnpj: string;
  id: string;
  razao_social: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaClienteAutoCompleteItensItem;

pub struct PaginaClienteAutoCompleteItensItem {
    pub cnpj: String,
    pub id: uuid::Uuid,
    pub razao_social: String,
}
```

</Tab>
</Tabs>

### PaginaClienteItensItem [#tipo-paginaclienteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaClienteItensItem } from "termo_core/sell";

export interface PaginaClienteItensItem {
  atendente_ativo: boolean;
  ativo: boolean;
  atualizado_em: string;
  chatwoot_contato_id?: number | null;
  cidade?: string | null;
  cnpj: string;
  criado_em: string;
  email?: string | null;
  estado?: string | null;
  id: string;
  intranet_cliente_id?: number | null;
  nome_fantasia?: string | null;
  razao_social: string;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaClienteItensItem;

pub struct PaginaClienteItensItem {
    pub atendente_ativo: bool,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chatwoot_contato_id: Option<i64>,
    pub cidade: Option<String>,
    pub cnpj: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: Option<String>,
    pub estado: Option<String>,
    pub id: uuid::Uuid,
    pub intranet_cliente_id: Option<i64>,
    pub nome_fantasia: Option<String>,
    pub razao_social: String,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### Pedido [#tipo-pedido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Pedido } from "termo_core/sell";

export interface Pedido {
  cliente_id: string;
  emitido_em: string;
  itens: Array<ItemPedido>;
  numero: string;
  valor_total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Pedido;

pub struct Pedido {
    pub cliente_id: uuid::Uuid,
    pub emitido_em: chrono::DateTime<chrono::Utc>,
    pub itens: Vec<ItemPedido>,
    pub numero: String,
    pub valor_total: f64,
}
```

</Tab>
</Tabs>

### ResultadoDaSincronizacao [#tipo-resultadodasincronizacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResultadoDaSincronizacao } from "termo_core/sell";

export interface ResultadoDaSincronizacao {
  atualizados: number;
  criados: number;
  ignorados: number;
  recebidos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ResultadoDaSincronizacao;

pub struct ResultadoDaSincronizacao {
    pub atualizados: i64,
    pub criados: i64,
    pub ignorados: i64,
    pub recebidos: i64,
}
```

</Tab>
</Tabs>

### StatusDaSincronizacao [#tipo-statusdasincronizacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { StatusDaSincronizacao } from "termo_core/sell";

export interface StatusDaSincronizacao {
  cancelada: boolean;
  erro?: string | null;
  iniciada_em?: string | null;
  paginas: number;
  resultado: ResultadoDaSincronizacao;
  rodando: boolean;
  terminada_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::StatusDaSincronizacao;

pub struct StatusDaSincronizacao {
    pub cancelada: bool,
    pub erro: Option<String>,
    pub iniciada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub paginas: i64,
    pub resultado: ResultadoDaSincronizacao,
    pub rodando: bool,
    pub terminada_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/sell/colaborador)

> 5 funções do TermoSell para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista os colaboradores com paginação |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista os colaboradores com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena por nome. Quando quem chama é master do TermoAuth, antes de listar o TermoSell busca no TermoAuth os colaboradores `@termotubos.com.br` que ainda não existem aqui e os cadastra sem nenhuma permissão. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e e-mail, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail (a busca rápida da tela); `nome`, `email` e `cargo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação; `perfil_acesso_id` filtra pelo perfil de acesso. Sem filtro, devolve todos. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização e pelos eventos do TermoWebhook) e `setor`, `cargo` e `funcao` vêm de lá.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve o colaborador com o e-mail e o `master` do acesso dele. Colaborador excluído responde `404`. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização e pelos eventos do TermoWebhook) e `setor`, `cargo` e `funcao` vêm de lá.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoSell: `perfil_acesso_id` aponta para um perfil de `GET /perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/sell";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/sell";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/sell";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/sell";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/sell";

export interface PaginaColaboradorItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>


# Config system Chatwoot (/docs/servicos/sell/config_system_chatwoot)

> 7 funções do TermoSell para config system chatwoot.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_config_system_chatwoot`](#buscar_paginador_config_system_chatwoot) | `GET /config_system_chatwoot` | Lista as configurações do Chatwoot com paginação |
| [`criar_config_system_chatwoot`](#criar_config_system_chatwoot) | `POST /config_system_chatwoot` | Conecta a conta do Chatwoot |
| [`buscar_auto_complete_config_system_chatwoot`](#buscar_auto_complete_config_system_chatwoot) | `GET /config_system_chatwoot/autocomplete` | Lista básica de configurações do Chatwoot para seleção |
| [`buscar_pelo_filtro_config_system_chatwoot`](#buscar_pelo_filtro_config_system_chatwoot) | `GET /config_system_chatwoot/filtro` | Busca configurações do Chatwoot por filtro |
| [`buscar_pelo_id_config_system_chatwoot`](#buscar_pelo_id_config_system_chatwoot) | `GET /config_system_chatwoot/{id}` | Busca a configuração do Chatwoot pelo id |
| [`atualizar_pelo_id_config_system_chatwoot`](#atualizar_pelo_id_config_system_chatwoot) | `PATCH /config_system_chatwoot/{id}` | Atualiza a configuração do Chatwoot pelo id |
| [`deletar_pelo_id_config_system_chatwoot`](#deletar_pelo_id_config_system_chatwoot) | `DELETE /config_system_chatwoot/{id}` | Exclui a configuração do Chatwoot pelo id |

## `buscar_paginador_config_system_chatwoot` [#buscar_paginador_config_system_chatwoot]

<Rota metodo="GET" caminho="/config_system_chatwoot" credencial />

Lista as configurações do Chatwoot com paginação

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Ordena por nome. Para cada item, consulta o Chatwoot na hora: `chave_valida` diz se o token de acesso funcionou e `erro_chave` traz o motivo da recusa. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos. O token de acesso nunca volta: as respostas trazem só `token_acesso_mascarado`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorConfigSystemChatwoot = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfigSystemChatwootValidada>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_config_system_chatwoot(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorConfigSystemChatwoot,
) -> Result<tipos::PaginaConfigSystemChatwootValidada, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_config_system_chatwoot(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorConfigSystemChatwoot { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfigSystemChatwootValidada>` · Rust: `Result<tipos::PaginaConfigSystemChatwootValidada, ErroAoChamarServico>` · veja [`PaginaConfigSystemChatwootValidada`](#tipo-paginaconfigsystemchatwootvalidada).

## `criar_config_system_chatwoot` [#criar_config_system_chatwoot]

<Rota metodo="POST" caminho="/config_system_chatwoot" credencial />

Conecta a conta do Chatwoot

Exige a permissão `criar` da área `configuracoes`. O TermoSell usa uma única conta do Chatwoot: com uma configuração já cadastrada, responde `409` (edite a existente). `nome` (até 100 caracteres), `endereco` do Chatwoot (`http://` ou `https://`, até 200), `conta_id` (maior que zero), `token_acesso` (de 8 a 200 caracteres) e `endereco_publico` (o endereço `https://` deste backend que o Chatwoot vai chamar, até 200) são obrigatórios. Antes de gravar, cria no Chatwoot o robô de atendimento que avisa o TermoSell das mensagens; se o Chatwoot recusar, responde `400` com o motivo. A configuração nasce ativa. O token de acesso nunca volta: as respostas trazem só `token_acesso_mascarado`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfigSystemChatwootCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfigSystemChatwoot>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_config_system_chatwoot(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfigSystemChatwootCriar,
) -> Result<tipos::ConfigSystemChatwoot, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::criar_config_system_chatwoot(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfigSystemChatwootCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfigSystemChatwootCriar", typeDescriptionLink: "#tipo-configsystemchatwootcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfigSystemChatwoot>` · Rust: `Result<tipos::ConfigSystemChatwoot, ErroAoChamarServico>` · veja [`ConfigSystemChatwoot`](#tipo-configsystemchatwoot).

## `buscar_auto_complete_config_system_chatwoot` [#buscar_auto_complete_config_system_chatwoot]

<Rota metodo="GET" caminho="/config_system_chatwoot/autocomplete" credencial />

Lista básica de configurações do Chatwoot para seleção

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e endereço das configurações ativas, em ordem alfabética de nome. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConfigSystemChatwoot = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfigSystemChatwootAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_config_system_chatwoot(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConfigSystemChatwoot,
) -> Result<tipos::PaginaConfigSystemChatwootAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_config_system_chatwoot(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteConfigSystemChatwoot { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfigSystemChatwootAutoComplete>` · Rust: `Result<tipos::PaginaConfigSystemChatwootAutoComplete, ErroAoChamarServico>` · veja [`PaginaConfigSystemChatwootAutoComplete`](#tipo-paginaconfigsystemchatwootautocomplete).

## `buscar_pelo_filtro_config_system_chatwoot` [#buscar_pelo_filtro_config_system_chatwoot]

<Rota metodo="GET" caminho="/config_system_chatwoot/filtro" credencial />

Busca configurações do Chatwoot por filtro

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve todas as configurações que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` e `endereco` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação. O token de acesso nunca volta: as respostas trazem só `token_acesso_mascarado`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroConfigSystemChatwoot = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ConfigSystemChatwoot>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_config_system_chatwoot(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroConfigSystemChatwoot,
) -> Result<Vec<tipos::ConfigSystemChatwoot>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_config_system_chatwoot(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroConfigSystemChatwoot { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.endereco": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ConfigSystemChatwoot>>` · Rust: `Result<Vec<tipos::ConfigSystemChatwoot>, ErroAoChamarServico>`

## `buscar_pelo_id_config_system_chatwoot` [#buscar_pelo_id_config_system_chatwoot]

<Rota metodo="GET" caminho="/config_system_chatwoot/{id}" credencial />

Busca a configuração do Chatwoot pelo id

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Configuração excluída responde `404`. `robo_chatwoot_id` é o id do robô de atendimento criado no Chatwoot. O token de acesso nunca volta: as respostas trazem só `token_acesso_mascarado`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfigSystemChatwoot>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_config_system_chatwoot(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::ConfigSystemChatwoot, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_config_system_chatwoot(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfigSystemChatwoot>` · Rust: `Result<tipos::ConfigSystemChatwoot, ErroAoChamarServico>` · veja [`ConfigSystemChatwoot`](#tipo-configsystemchatwoot).

## `atualizar_pelo_id_config_system_chatwoot` [#atualizar_pelo_id_config_system_chatwoot]

<Rota metodo="PATCH" caminho="/config_system_chatwoot/{id}" credencial />

Atualiza a configuração do Chatwoot pelo id

Exige a permissão `editar` da área `configuracoes`. Atualização parcial: só `nome` (até 100), `token_acesso` (de 8 a 200), `endereco_publico` (`https://`, até 200) e `ativo` mudam; o endereço e a conta do Chatwoot não. Trocar o token ou o endereço público atualiza antes o robô de atendimento no Chatwoot, e trocar o endereço público também refaz o webhook de cada número da Z-API ligado a esta conta; se o Chatwoot ou a Z-API recusarem, nada é gravado e a resposta é `400` com o motivo. O token de acesso nunca volta: as respostas trazem só `token_acesso_mascarado`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ConfigSystemChatwootAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConfigSystemChatwoot>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_config_system_chatwoot(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ConfigSystemChatwootAtualizar,
) -> Result<tipos::ConfigSystemChatwoot, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_config_system_chatwoot(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ConfigSystemChatwootAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfigSystemChatwootAtualizar", typeDescriptionLink: "#tipo-configsystemchatwootatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConfigSystemChatwoot>` · Rust: `Result<tipos::ConfigSystemChatwoot, ErroAoChamarServico>` · veja [`ConfigSystemChatwoot`](#tipo-configsystemchatwoot).

## `deletar_pelo_id_config_system_chatwoot` [#deletar_pelo_id_config_system_chatwoot]

<Rota metodo="DELETE" caminho="/config_system_chatwoot/{id}" credencial />

Exclui a configuração do Chatwoot pelo id

Exige a permissão `deletar` da área `configuracoes`. A exclusão é lógica e não há como restaurar. Só exclui a configuração que não tem números de WhatsApp (Z-API) vinculados; exclua ou desvincule os números antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_config_system_chatwoot(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_config_system_chatwoot } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_config_system_chatwoot(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_config_system_chatwoot(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_config_system_chatwoot(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ConfigSystemChatwoot [#tipo-configsystemchatwoot]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemChatwoot } from "termo_core/sell";

export interface ConfigSystemChatwoot {
  ativo: boolean;
  atualizado_em: string;
  conta_id: number;
  criado_em: string;
  endereco: string;
  endereco_publico: string;
  id: string;
  nome: string;
  robo_chatwoot_id: number;
  token_acesso_mascarado: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ConfigSystemChatwoot;

pub struct ConfigSystemChatwoot {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub conta_id: i32,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub endereco: String,
    pub endereco_publico: String,
    pub id: uuid::Uuid,
    pub nome: String,
    pub robo_chatwoot_id: i32,
    pub token_acesso_mascarado: String,
}
```

</Tab>
</Tabs>

### ConfigSystemChatwootAtualizar [#tipo-configsystemchatwootatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemChatwootAtualizar } from "termo_core/sell";

export interface ConfigSystemChatwootAtualizar {
  ativo?: boolean | null;
  endereco_publico?: string | null;
  nome?: string | null;
  token_acesso?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ConfigSystemChatwootAtualizar;

pub struct ConfigSystemChatwootAtualizar {
    pub ativo: Option<bool>,
    pub endereco_publico: Option<String>,
    pub nome: Option<String>,
    pub token_acesso: Option<String>,
}
```

</Tab>
</Tabs>

### ConfigSystemChatwootCriar [#tipo-configsystemchatwootcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfigSystemChatwootCriar } from "termo_core/sell";

export interface ConfigSystemChatwootCriar {
  conta_id: number;
  endereco: string;
  endereco_publico: string;
  nome: string;
  token_acesso: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ConfigSystemChatwootCriar;

pub struct ConfigSystemChatwootCriar {
    pub conta_id: i32,
    pub endereco: String,
    pub endereco_publico: String,
    pub nome: String,
    pub token_acesso: String,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemChatwootAutoComplete [#tipo-paginaconfigsystemchatwootautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemChatwootAutoComplete } from "termo_core/sell";

export interface PaginaConfigSystemChatwootAutoComplete {
  itens: Array<PaginaConfigSystemChatwootAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemChatwootAutoComplete;

pub struct PaginaConfigSystemChatwootAutoComplete {
    pub itens: Vec<PaginaConfigSystemChatwootAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemChatwootAutoCompleteItensItem [#tipo-paginaconfigsystemchatwootautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemChatwootAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaConfigSystemChatwootAutoCompleteItensItem {
  endereco: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemChatwootAutoCompleteItensItem;

pub struct PaginaConfigSystemChatwootAutoCompleteItensItem {
    pub endereco: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemChatwootValidada [#tipo-paginaconfigsystemchatwootvalidada]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemChatwootValidada } from "termo_core/sell";

export interface PaginaConfigSystemChatwootValidada {
  itens: Array<ConfigSystemChatwoot & PaginaConfigSystemChatwootValidadaItensItemParte2>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemChatwootValidada;

pub struct PaginaConfigSystemChatwootValidada {
    pub itens: Vec<serde_json::Value>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemChatwootValidadaItensItemParte2 [#tipo-paginaconfigsystemchatwootvalidadaitensitemparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemChatwootValidadaItensItemParte2 } from "termo_core/sell";

export interface PaginaConfigSystemChatwootValidadaItensItemParte2 {
  chave_valida: boolean;
  erro_chave?: string | null;
}
```

</Tab>
<Tab value="Rust">

`termo_core::sell::PaginaConfigSystemChatwootValidadaItensItemParte2`

</Tab>
</Tabs>


# Config system WhatsApp (/docs/servicos/sell/config_system_whatsapp)

> 2 funções do TermoSell para config system whatsapp.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_auto_complete_config_system_whatsapp`](#buscar_auto_complete_config_system_whatsapp) | `GET /config_system_whatsapp/autocomplete` | Lista básica dos números de WhatsApp conectados por QR Code para seleção |
| [`deletar_pelo_id_config_system_whatsapp`](#deletar_pelo_id_config_system_whatsapp) | `DELETE /config_system_whatsapp/{id}` | Exclui um número de WhatsApp conectado por QR Code pelo id |

## `buscar_auto_complete_config_system_whatsapp` [#buscar_auto_complete_config_system_whatsapp]

<Rota metodo="GET" caminho="/config_system_whatsapp/autocomplete" credencial />

Lista básica dos números de WhatsApp conectados por QR Code para seleção

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e número (vazio até o celular ler o QR Code) de cada número conectado pelo QR Code, em ordem alfabética de nome. `busca` procura o trecho no nome (sem diferenciar maiúsculas) ou no número. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_config_system_whatsapp(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConfigSystemWhatsapp = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfigSystemWhatsappAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_config_system_whatsapp } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_config_system_whatsapp(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_config_system_whatsapp(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConfigSystemWhatsapp,
) -> Result<tipos::PaginaConfigSystemWhatsappAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_config_system_whatsapp(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteConfigSystemWhatsapp { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfigSystemWhatsappAutoComplete>` · Rust: `Result<tipos::PaginaConfigSystemWhatsappAutoComplete, ErroAoChamarServico>` · veja [`PaginaConfigSystemWhatsappAutoComplete`](#tipo-paginaconfigsystemwhatsappautocomplete).

## `deletar_pelo_id_config_system_whatsapp` [#deletar_pelo_id_config_system_whatsapp]

<Rota metodo="DELETE" caminho="/config_system_whatsapp/{id}" credencial />

Exclui um número de WhatsApp conectado por QR Code pelo id

Exige a permissão `deletar` da área `configuracoes`. Desvincula o aparelho do celular (some de "Aparelhos conectados"), apaga a sessão guardada e faz a exclusão lógica, sem como restaurar: o TermoSell deixa de atender as mensagens que chegam pelo número.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_config_system_whatsapp(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_config_system_whatsapp } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_config_system_whatsapp(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_config_system_whatsapp(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_config_system_whatsapp(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaConfigSystemWhatsappAutoComplete [#tipo-paginaconfigsystemwhatsappautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemWhatsappAutoComplete } from "termo_core/sell";

export interface PaginaConfigSystemWhatsappAutoComplete {
  itens: Array<PaginaConfigSystemWhatsappAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemWhatsappAutoComplete;

pub struct PaginaConfigSystemWhatsappAutoComplete {
    pub itens: Vec<PaginaConfigSystemWhatsappAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemWhatsappAutoCompleteItensItem [#tipo-paginaconfigsystemwhatsappautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemWhatsappAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaConfigSystemWhatsappAutoCompleteItensItem {
  id: string;
  nome: string;
  numero?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemWhatsappAutoCompleteItensItem;

pub struct PaginaConfigSystemWhatsappAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
    pub numero: Option<String>,
}
```

</Tab>
</Tabs>


# Config system Z-API (/docs/servicos/sell/config_system_z_api)

> 2 funções do TermoSell para config system z-api.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_auto_complete_config_system_z_api`](#buscar_auto_complete_config_system_z_api) | `GET /config_system_z_api/autocomplete` | Lista básica dos números de WhatsApp (Z-API) para seleção |
| [`deletar_pelo_id_config_system_z_api`](#deletar_pelo_id_config_system_z_api) | `DELETE /config_system_z_api/{id}` | Exclui um número de WhatsApp (Z-API) pelo id |

## `buscar_auto_complete_config_system_z_api` [#buscar_auto_complete_config_system_z_api]

<Rota metodo="GET" caminho="/config_system_z_api/autocomplete" credencial />

Lista básica dos números de WhatsApp (Z-API) para seleção

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e número de cada número de WhatsApp conectado pela Z-API, em ordem alfabética de nome. `busca` procura o trecho no nome (sem diferenciar maiúsculas) ou no número. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_config_system_z_api(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConfigSystemZApi = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConfigSystemZApiAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_config_system_z_api } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_config_system_z_api(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_config_system_z_api(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConfigSystemZApi,
) -> Result<tipos::PaginaConfigSystemZApiAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_config_system_z_api(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteConfigSystemZApi { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConfigSystemZApiAutoComplete>` · Rust: `Result<tipos::PaginaConfigSystemZApiAutoComplete, ErroAoChamarServico>` · veja [`PaginaConfigSystemZApiAutoComplete`](#tipo-paginaconfigsystemzapiautocomplete).

## `deletar_pelo_id_config_system_z_api` [#deletar_pelo_id_config_system_z_api]

<Rota metodo="DELETE" caminho="/config_system_z_api/{id}" credencial />

Exclui um número de WhatsApp (Z-API) pelo id

Exige a permissão `deletar` da área `configuracoes`. A exclusão é lógica e não há como restaurar: o número some das consultas e o TermoSell deixa de atender as mensagens que chegam por ele.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_config_system_z_api(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_config_system_z_api } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_config_system_z_api(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_config_system_z_api(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_config_system_z_api(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaConfigSystemZApiAutoComplete [#tipo-paginaconfigsystemzapiautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemZApiAutoComplete } from "termo_core/sell";

export interface PaginaConfigSystemZApiAutoComplete {
  itens: Array<PaginaConfigSystemZApiAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemZApiAutoComplete;

pub struct PaginaConfigSystemZApiAutoComplete {
    pub itens: Vec<PaginaConfigSystemZApiAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConfigSystemZApiAutoCompleteItensItem [#tipo-paginaconfigsystemzapiautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConfigSystemZApiAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaConfigSystemZApiAutoCompleteItensItem {
  id: string;
  nome: string;
  numero: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConfigSystemZApiAutoCompleteItensItem;

pub struct PaginaConfigSystemZApiAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
    pub numero: String,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/sell/configuracao)

> 2 funções do TermoSell para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao` | Mostra a configuração do app (segredo do TermoAuth) |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao` | Grava o segredo do app gerado no TermoAuth |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Mostra a configuração do app (segredo do TermoAuth)

Só um master do TermoAuth. O segredo do app gerado no TermoAuth nunca volta: a resposta traz só `configurado` e os últimos caracteres mascarados em `final_visivel`. `criptografia_disponivel` é falso quando o servidor está sem a `GLOBAL_SECRET_CRIPTOGRAFIA`; nesse caso nada pode ser lido nem gravado. `atualizado_em` é nulo enquanto ninguém gravou a configuração.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao" credencial />

Grava o segredo do app gerado no TermoAuth

Só um master do TermoAuth. Campo ausente fica como está, texto troca e `null` limpa. O segredo é gravado cifrado (AES-256-GCM com a `GLOBAL_SECRET_CRIPTOGRAFIA`) e entregue na hora ao `termo_core`, sem deploy. Até 2.000 caracteres, sem quebra de linha.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/sell";

export interface Configuracao {
  atualizado_em?: string | null;
  atualizado_por?: string | null;
  criptografia_disponivel: boolean;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Configuracao;

pub struct Configuracao {
    pub atualizado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub atualizado_por: Option<String>,
    pub criptografia_disponivel: bool,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/sell";

export interface ConfiguracaoAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/sell";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Conversa (/docs/servicos/sell/conversa)

> 8 funções do TermoSell para conversa.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_conversa`](#buscar_paginador_conversa) | `GET /conversa` | Lista as conversas com paginação |
| [`criar_conversa`](#criar_conversa) | `POST /conversa` | Não cria conversa pela tela |
| [`buscar_auto_complete_conversa`](#buscar_auto_complete_conversa) | `GET /conversa/autocomplete` | Lista básica de conversas para seleção |
| [`buscar_pelo_filtro_conversa`](#buscar_pelo_filtro_conversa) | `GET /conversa/filtro` | Busca conversas por filtro |
| [`buscar_pelo_id_conversa`](#buscar_pelo_id_conversa) | `GET /conversa/{id}` | Busca uma conversa pelo id |
| [`atualizar_pelo_id_conversa`](#atualizar_pelo_id_conversa) | `PATCH /conversa/{id}` | Atualiza uma conversa pelo id |
| [`deletar_pelo_id_conversa`](#deletar_pelo_id_conversa) | `DELETE /conversa/{id}` | Exclui uma conversa do histórico pelo id |
| [`buscar_mensagens_conversa`](#buscar_mensagens_conversa) | `GET /conversa/{id}/mensagens` | Lista as mensagens de uma conversa |

## `buscar_paginador_conversa` [#buscar_paginador_conversa]

<Rota metodo="GET" caminho="/conversa" credencial />

Lista as conversas com paginação

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Ordena da última mensagem mais recente para a mais antiga. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `status` (opcional) limita a um status. `total` conta os registros não excluídos que casam com o `status`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorConversa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConversa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_conversa(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorConversa,
) -> Result<tipos::PaginaConversa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_conversa(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorConversa { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConversa>` · Rust: `Result<tipos::PaginaConversa, ErroAoChamarServico>` · veja [`PaginaConversa`](#tipo-paginaconversa).

## `criar_conversa` [#criar_conversa]

<Rota metodo="POST" caminho="/conversa" credencial />

Não cria conversa pela tela

Exige a permissão `criar` da área `clientes`, mas responde sempre `403`: a conversa é registrada pelos webhooks do Chatwoot e da Z-API, que gravam toda mensagem visível que passa pela conta do Chatwoot. Sem corpo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await criar_conversa(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::criar_conversa(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `buscar_auto_complete_conversa` [#buscar_auto_complete_conversa]

<Rota metodo="GET" caminho="/conversa/autocomplete" credencial />

Lista básica de conversas para seleção

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve só id, id da conversa no Chatwoot, nome e telefone do contato, em ordem alfabética do nome do contato. `busca` procura o trecho no nome do contato (sem diferenciar maiúsculas) ou no telefone. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteConversa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaConversaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_conversa(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteConversa,
) -> Result<tipos::PaginaConversaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_conversa(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteConversa { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaConversaAutoComplete>` · Rust: `Result<tipos::PaginaConversaAutoComplete, ErroAoChamarServico>` · veja [`PaginaConversaAutoComplete`](#tipo-paginaconversaautocomplete).

## `buscar_pelo_filtro_conversa` [#buscar_pelo_filtro_conversa]

<Rota metodo="GET" caminho="/conversa/filtro" credencial />

Busca conversas por filtro

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve até 500 conversas que casam com o filtro, da última mensagem mais recente para a mais antiga. `cliente_id`, `robo_id`, `config_system_z_api_id` e `chatwoot_conversa_id` comparam o valor exato; `status` compara o status exato; `contato` procura o trecho no nome do contato, na razão social do cliente ou nos dígitos do telefone; `texto` procura o trecho no conteúdo de qualquer mensagem da conversa; todos sem diferenciar maiúsculas. Sem filtro, devolve as 500 mais recentes. É por `cliente_id` que a guia "Histórico de conversas" do cliente lê o histórico.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroConversa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Conversa>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_conversa(credencial_de_acesso, { cliente_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroConversa,
) -> Result<Vec<tipos::Conversa>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_conversa(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroConversa { cliente_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.cliente_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.robo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.config_system_z_api_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.chatwoot_conversa_id": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.contato": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.texto": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Conversa>>` · Rust: `Result<Vec<tipos::Conversa>, ErroAoChamarServico>`

## `buscar_pelo_id_conversa` [#buscar_pelo_id_conversa]

<Rota metodo="GET" caminho="/conversa/{id}" credencial />

Busca uma conversa pelo id

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve a conversa do histórico interno com o nome do número do WhatsApp, do cliente e do robô, o `status` espelhado do Chatwoot (`pending` com o robô, `open` com a equipe, `resolved`, `snoozed`), a etapa atual do fluxo, a última mensagem de cada lado, `transferida_em`/`transferida_motivo` (`sem_resposta` quando o gatilho passou a conversa para a equipe), `quantidade_mensagens` e `chatwoot_endereco_conversa` (link da conversa no painel do Chatwoot). Datas em RFC 3339. Conversa excluída responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Conversa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_conversa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Conversa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_conversa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Conversa>` · Rust: `Result<tipos::Conversa, ErroAoChamarServico>` · veja [`Conversa`](#tipo-conversa).

## `atualizar_pelo_id_conversa` [#atualizar_pelo_id_conversa]

<Rota metodo="PATCH" caminho="/conversa/{id}" credencial />

Atualiza uma conversa pelo id

Exige a permissão `editar` da área `clientes`. Atualização parcial: só os campos enviados mudam. `cliente_id` vincula a conversa a um cliente, `robo_id` a um robô e `status` corrige o status gravado (`pending`, `open`, `resolved` ou `snoozed`) sem alterar nada no Chatwoot. As mensagens e os demais campos vêm só dos webhooks.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ConversaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Conversa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_conversa(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ConversaAtualizar,
) -> Result<tipos::Conversa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_conversa(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ConversaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConversaAtualizar", typeDescriptionLink: "#tipo-conversaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Conversa>` · Rust: `Result<tipos::Conversa, ErroAoChamarServico>` · veja [`Conversa`](#tipo-conversa).

## `deletar_pelo_id_conversa` [#deletar_pelo_id_conversa]

<Rota metodo="DELETE" caminho="/conversa/{id}" credencial />

Exclui uma conversa do histórico pelo id

Exige a permissão `deletar` da área `clientes`. A exclusão é lógica e leva junto as mensagens, na mesma transação: a conversa some do histórico interno e não há como restaurar. A conversa no Chatwoot não é alterada; uma mensagem nova dela cria um registro novo no histórico.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_conversa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_conversa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `buscar_mensagens_conversa` [#buscar_mensagens_conversa]

<Rota metodo="GET" caminho="/conversa/{id}/mensagens" credencial />

Lista as mensagens de uma conversa

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Devolve as mensagens gravadas no histórico interno, em ordem de envio, sem as notas privadas da equipe. `autor` é `contato`, `atendente` ou `robo`; `etapa_id` é a etapa do fluxo em que o robô mandou a mensagem; `criada_em` é a data de criação no Chatwoot, em RFC 3339. `anexos` lista os arquivos da mensagem (`tipo` do Chatwoot, `nome`, `endereco` no Chatwoot); cada um é copiado para o TermoBucket (arquivo privado do app `spark-sell`) logo depois do webhook e, quando já está lá, traz `arquivo_id`, `tipo_mime`, `tamanho` e `url`, o download assinado por 15 minutos. O que falhar é tentado de novo a cada 30 minutos, até 5 vezes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_mensagens_conversa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ConversaMensagem>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_mensagens_conversa } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_mensagens_conversa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_mensagens_conversa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<Vec<tipos::ConversaMensagem>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_mensagens_conversa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ConversaMensagem>>` · Rust: `Result<Vec<tipos::ConversaMensagem>, ErroAoChamarServico>`

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AnexoDaMensagem [#tipo-anexodamensagem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AnexoDaMensagem } from "termo_core/sell";

export interface AnexoDaMensagem {
  arquivo_id?: string | null;
  endereco: string;
  nome: string;
  tamanho?: number | null;
  tentativas?: number;
  tipo: string;
  tipo_mime?: string | null;
  url?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::AnexoDaMensagem;

pub struct AnexoDaMensagem {
    pub arquivo_id: Option<uuid::Uuid>,
    pub endereco: String,
    pub nome: String,
    pub tamanho: Option<i64>,
    pub tentativas: Option<i32>,
    pub tipo: String,
    pub tipo_mime: Option<String>,
    pub url: Option<String>,
}
```

</Tab>
</Tabs>

### Conversa [#tipo-conversa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Conversa } from "termo_core/sell";

export interface Conversa {
  atualizado_em: string;
  chatwoot_contato_id?: number | null;
  chatwoot_conversa_id: number;
  chatwoot_endereco_conversa?: string | null;
  cliente_id?: string | null;
  cliente_razao_social?: string | null;
  config_system_chatwoot_id: string;
  config_system_whatsapp_id?: string | null;
  config_system_whatsapp_nome?: string | null;
  config_system_z_api_id?: string | null;
  config_system_z_api_nome?: string | null;
  contato_nome: string;
  contato_telefone: string;
  criado_em: string;
  etapa_id?: string | null;
  id: string;
  quantidade_mensagens: number;
  robo_id?: string | null;
  robo_nome?: string | null;
  status: string;
  transferida_em?: string | null;
  transferida_motivo?: string | null;
  ultima_mensagem: string;
  ultima_mensagem_do_contato_em?: string | null;
  ultima_mensagem_do_robo_em?: string | null;
  ultima_mensagem_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Conversa;

pub struct Conversa {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chatwoot_contato_id: Option<i64>,
    pub chatwoot_conversa_id: i64,
    pub chatwoot_endereco_conversa: Option<String>,
    pub cliente_id: Option<uuid::Uuid>,
    pub cliente_razao_social: Option<String>,
    pub config_system_chatwoot_id: uuid::Uuid,
    pub config_system_whatsapp_id: Option<uuid::Uuid>,
    pub config_system_whatsapp_nome: Option<String>,
    pub config_system_z_api_id: Option<uuid::Uuid>,
    pub config_system_z_api_nome: Option<String>,
    pub contato_nome: String,
    pub contato_telefone: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub etapa_id: Option<String>,
    pub id: uuid::Uuid,
    pub quantidade_mensagens: i64,
    pub robo_id: Option<uuid::Uuid>,
    pub robo_nome: Option<String>,
    pub status: String,
    pub transferida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub transferida_motivo: Option<String>,
    pub ultima_mensagem: String,
    pub ultima_mensagem_do_contato_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultima_mensagem_do_robo_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultima_mensagem_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>

### ConversaAtualizar [#tipo-conversaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConversaAtualizar } from "termo_core/sell";

export interface ConversaAtualizar {
  cliente_id?: string | null;
  robo_id?: string | null;
  status?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ConversaAtualizar;

pub struct ConversaAtualizar {
    pub cliente_id: Option<uuid::Uuid>,
    pub robo_id: Option<uuid::Uuid>,
    pub status: Option<String>,
}
```

</Tab>
</Tabs>

### ConversaMensagem [#tipo-conversamensagem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConversaMensagem } from "termo_core/sell";

export interface ConversaMensagem {
  anexos: Array<AnexoDaMensagem>;
  autor: string;
  chatwoot_mensagem_id: number;
  conteudo: string;
  conversa_id: string;
  criada_em: string;
  etapa_id?: string | null;
  id: string;
  quantidade_anexos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ConversaMensagem;

pub struct ConversaMensagem {
    pub anexos: Vec<AnexoDaMensagem>,
    pub autor: String,
    pub chatwoot_mensagem_id: i64,
    pub conteudo: String,
    pub conversa_id: uuid::Uuid,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub etapa_id: Option<String>,
    pub id: uuid::Uuid,
    pub quantidade_anexos: i32,
}
```

</Tab>
</Tabs>

### PaginaConversa [#tipo-paginaconversa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversa } from "termo_core/sell";

export interface PaginaConversa {
  itens: Array<PaginaConversaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConversa;

pub struct PaginaConversa {
    pub itens: Vec<PaginaConversaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConversaAutoComplete [#tipo-paginaconversaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaAutoComplete } from "termo_core/sell";

export interface PaginaConversaAutoComplete {
  itens: Array<PaginaConversaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConversaAutoComplete;

pub struct PaginaConversaAutoComplete {
    pub itens: Vec<PaginaConversaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaConversaAutoCompleteItensItem [#tipo-paginaconversaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaConversaAutoCompleteItensItem {
  chatwoot_conversa_id: number;
  contato_nome: string;
  contato_telefone: string;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConversaAutoCompleteItensItem;

pub struct PaginaConversaAutoCompleteItensItem {
    pub chatwoot_conversa_id: i64,
    pub contato_nome: String,
    pub contato_telefone: String,
    pub id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### PaginaConversaItensItem [#tipo-paginaconversaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaConversaItensItem } from "termo_core/sell";

export interface PaginaConversaItensItem {
  atualizado_em: string;
  chatwoot_contato_id?: number | null;
  chatwoot_conversa_id: number;
  chatwoot_endereco_conversa?: string | null;
  cliente_id?: string | null;
  cliente_razao_social?: string | null;
  config_system_chatwoot_id: string;
  config_system_whatsapp_id?: string | null;
  config_system_whatsapp_nome?: string | null;
  config_system_z_api_id?: string | null;
  config_system_z_api_nome?: string | null;
  contato_nome: string;
  contato_telefone: string;
  criado_em: string;
  etapa_id?: string | null;
  id: string;
  quantidade_mensagens: number;
  robo_id?: string | null;
  robo_nome?: string | null;
  status: string;
  transferida_em?: string | null;
  transferida_motivo?: string | null;
  ultima_mensagem: string;
  ultima_mensagem_do_contato_em?: string | null;
  ultima_mensagem_do_robo_em?: string | null;
  ultima_mensagem_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaConversaItensItem;

pub struct PaginaConversaItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chatwoot_contato_id: Option<i64>,
    pub chatwoot_conversa_id: i64,
    pub chatwoot_endereco_conversa: Option<String>,
    pub cliente_id: Option<uuid::Uuid>,
    pub cliente_razao_social: Option<String>,
    pub config_system_chatwoot_id: uuid::Uuid,
    pub config_system_whatsapp_id: Option<uuid::Uuid>,
    pub config_system_whatsapp_nome: Option<String>,
    pub config_system_z_api_id: Option<uuid::Uuid>,
    pub config_system_z_api_nome: Option<String>,
    pub contato_nome: String,
    pub contato_telefone: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub etapa_id: Option<String>,
    pub id: uuid::Uuid,
    pub quantidade_mensagens: i64,
    pub robo_id: Option<uuid::Uuid>,
    pub robo_nome: Option<String>,
    pub status: String,
    pub transferida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub transferida_motivo: Option<String>,
    pub ultima_mensagem: String,
    pub ultima_mensagem_do_contato_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultima_mensagem_do_robo_em: Option<chrono::DateTime<chrono::Utc>>,
    pub ultima_mensagem_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>


# Dashboard (/docs/servicos/sell/dashboard)

> 1 função do TermoSell para dashboard.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_filtro_dashboard`](#buscar_pelo_filtro_dashboard) | `GET /dashboard/filtro` | Indicadores gerenciais do atendimento |

## `buscar_pelo_filtro_dashboard` [#buscar_pelo_filtro_dashboard]

<Rota metodo="GET" caminho="/dashboard/filtro" credencial />

Indicadores gerenciais do atendimento

Exige qualquer permissão da área `clientes` (qualquer ação liberada na área já libera a leitura). Monta o painel do atendimento a partir do histórico interno de conversas. `dias` é o período (padrão 30, entre 1 e 365) contado em dias inteiros no horário de Brasília, de `inicio` até agora; `robo_id` (opcional) limita às conversas de um robô. `indicadores` traz as conversas novas do período e do período anterior de mesmo tamanho, as conversas e os clientes com mensagem do contato no período, as mensagens recebidas, do robô e da equipe, as conversas novas que passaram para a equipe (transferidas, abertas ou com mensagem de atendente), as resolvidas só pelo robô, as transferidas pelo gatilho de cliente sem resposta, as conversas em aberto cuja última mensagem é do contato e a mediana, em segundos, da primeira resposta (qualquer lado) e da primeira resposta da equipe. `situacao_atual` conta todas as conversas por `status`, sem recorte de período. `por_dia` e `por_hora` distribuem as mensagens no horário de Brasília; `por_robo` e `por_canal` agrupam as conversas; `aguardando_resposta` lista as 10 conversas em aberto que esperam resposta há mais tempo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_dashboard(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroDashboard = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Dashboard>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_dashboard } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_dashboard(credencial_de_acesso, { dias: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_dashboard(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroDashboard,
) -> Result<tipos::Dashboard, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_dashboard(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroDashboard { dias: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.dias": { type: "number", required: false, description: "Rust: Option<i32>" },
    "parametros.robo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Dashboard>` · Rust: `Result<tipos::Dashboard, ErroAoChamarServico>` · veja [`Dashboard`](#tipo-dashboard).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Dashboard [#tipo-dashboard]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Dashboard } from "termo_core/sell";

export interface Dashboard {
  aguardando_resposta: Array<DashboardAguardando>;
  dias: number;
  gerado_em: string;
  indicadores: DashboardIndicadores;
  inicio: string;
  por_canal: Array<DashboardCanal>;
  por_dia: Array<DashboardDia>;
  por_hora: Array<DashboardHora>;
  por_robo: Array<DashboardRobo>;
  situacao_atual: Array<DashboardSituacao>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Dashboard;

pub struct Dashboard {
    pub aguardando_resposta: Vec<DashboardAguardando>,
    pub dias: i32,
    pub gerado_em: chrono::DateTime<chrono::Utc>,
    pub indicadores: DashboardIndicadores,
    pub inicio: chrono::DateTime<chrono::Utc>,
    pub por_canal: Vec<DashboardCanal>,
    pub por_dia: Vec<DashboardDia>,
    pub por_hora: Vec<DashboardHora>,
    pub por_robo: Vec<DashboardRobo>,
    pub situacao_atual: Vec<DashboardSituacao>,
}
```

</Tab>
</Tabs>

### DashboardAguardando [#tipo-dashboardaguardando]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardAguardando } from "termo_core/sell";

export interface DashboardAguardando {
  aguardando_desde: string;
  cliente_razao_social?: string | null;
  contato_nome: string;
  contato_telefone: string;
  id: string;
  robo_nome?: string | null;
  status: string;
  ultima_mensagem: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardAguardando;

pub struct DashboardAguardando {
    pub aguardando_desde: chrono::DateTime<chrono::Utc>,
    pub cliente_razao_social: Option<String>,
    pub contato_nome: String,
    pub contato_telefone: String,
    pub id: uuid::Uuid,
    pub robo_nome: Option<String>,
    pub status: String,
    pub ultima_mensagem: String,
}
```

</Tab>
</Tabs>

### DashboardCanal [#tipo-dashboardcanal]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardCanal } from "termo_core/sell";

export interface DashboardCanal {
  canal_id?: string | null;
  canal_nome: string;
  canal_tipo: string;
  conversas: number;
  mensagens_recebidas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardCanal;

pub struct DashboardCanal {
    pub canal_id: Option<uuid::Uuid>,
    pub canal_nome: String,
    pub canal_tipo: String,
    pub conversas: i64,
    pub mensagens_recebidas: i64,
}
```

</Tab>
</Tabs>

### DashboardDia [#tipo-dashboarddia]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardDia } from "termo_core/sell";

export interface DashboardDia {
  conversas_novas: number;
  dia: string;
  mensagens_da_equipe: number;
  mensagens_do_robo: number;
  mensagens_recebidas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardDia;

pub struct DashboardDia {
    pub conversas_novas: i64,
    pub dia: chrono::NaiveDate,
    pub mensagens_da_equipe: i64,
    pub mensagens_do_robo: i64,
    pub mensagens_recebidas: i64,
}
```

</Tab>
</Tabs>

### DashboardHora [#tipo-dashboardhora]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardHora } from "termo_core/sell";

export interface DashboardHora {
  hora: number;
  mensagens_recebidas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardHora;

pub struct DashboardHora {
    pub hora: i32,
    pub mensagens_recebidas: i64,
}
```

</Tab>
</Tabs>

### DashboardIndicadores [#tipo-dashboardindicadores]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardIndicadores } from "termo_core/sell";

export interface DashboardIndicadores {
  aguardando_resposta: number;
  clientes_atendidos: number;
  conversas_atendidas: number;
  conversas_novas: number;
  conversas_novas_periodo_anterior: number;
  mensagens_da_equipe: number;
  mensagens_do_robo: number;
  mensagens_recebidas: number;
  passadas_para_equipe: number;
  primeira_resposta_da_equipe_segundos?: number | null;
  primeira_resposta_segundos?: number | null;
  resolvidas_pelo_robo: number;
  transferidas_sem_resposta: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardIndicadores;

pub struct DashboardIndicadores {
    pub aguardando_resposta: i64,
    pub clientes_atendidos: i64,
    pub conversas_atendidas: i64,
    pub conversas_novas: i64,
    pub conversas_novas_periodo_anterior: i64,
    pub mensagens_da_equipe: i64,
    pub mensagens_do_robo: i64,
    pub mensagens_recebidas: i64,
    pub passadas_para_equipe: i64,
    pub primeira_resposta_da_equipe_segundos: Option<f64>,
    pub primeira_resposta_segundos: Option<f64>,
    pub resolvidas_pelo_robo: i64,
    pub transferidas_sem_resposta: i64,
}
```

</Tab>
</Tabs>

### DashboardRobo [#tipo-dashboardrobo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardRobo } from "termo_core/sell";

export interface DashboardRobo {
  conversas: number;
  passadas_para_equipe: number;
  resolvidas_pelo_robo: number;
  robo_id?: string | null;
  robo_nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardRobo;

pub struct DashboardRobo {
    pub conversas: i64,
    pub passadas_para_equipe: i64,
    pub resolvidas_pelo_robo: i64,
    pub robo_id: Option<uuid::Uuid>,
    pub robo_nome: String,
}
```

</Tab>
</Tabs>

### DashboardSituacao [#tipo-dashboardsituacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DashboardSituacao } from "termo_core/sell";

export interface DashboardSituacao {
  quantidade: number;
  status: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::DashboardSituacao;

pub struct DashboardSituacao {
    pub quantidade: i64,
    pub status: String,
}
```

</Tab>
</Tabs>


# TermoSell (/docs/servicos/sell)

> Atendimento comercial da Termotubos pelo WhatsApp: cadastro de clientes, robôs de atendimento com IA (fluxo em etapas e ferramentas), conexão com o Chatwoot e com os números da Z-API, modelos de IA e…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Atendimento comercial da Termotubos pelo WhatsApp: cadastro de clientes, robôs de atendimento com IA (fluxo em etapas e ferramentas), conexão com o Chatwoot e com os números da Z-API, modelos de IA e administração dos acessos dos colaboradores. As rotas do painel usam o token do usuário logado no TermoAuth; os webhooks são chamados pelo Chatwoot, pela Z-API e pelo TermoWebhook. Erros voltam como `{ "erro": "mensagem" }`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::sell` (feature `sell`) |
| Importação TypeScript | `termo_core/sell` ou `import { sell } from "termo_core"` |
| Funções | 73 |
| Entidades | 14 |
| Versão do contrato | `0.1.25` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51021` |
| `SANDBOX` | `https://sandbox-api-sell.termotubos.com.br` |
| `PRODUCTION` | `https://api-sell.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Cliente" href="/docs/servicos/sell/cliente" description="10 funções" />
  <Card title="Conversa" href="/docs/servicos/sell/conversa" description="8 funções" />
  <Card title="Dashboard" href="/docs/servicos/sell/dashboard" description="1 função" />
  <Card title="Robô" href="/docs/servicos/sell/robo" description="9 funções" />
  <Card title="Robô ferramenta" href="/docs/servicos/sell/robo_ferramenta" description="7 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/sell/auth" description="8 funções" />
  <Card title="Colaborador" href="/docs/servicos/sell/colaborador" description="5 funções" />
  <Card title="Config system Chatwoot" href="/docs/servicos/sell/config_system_chatwoot" description="7 funções" />
  <Card title="Config system WhatsApp" href="/docs/servicos/sell/config_system_whatsapp" description="2 funções" />
  <Card title="Config system Z-API" href="/docs/servicos/sell/config_system_z_api" description="2 funções" />
  <Card title="Configuração" href="/docs/servicos/sell/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/sell/perfil_acesso" description="7 funções" />
  <Card title="Teste" href="/docs/servicos/sell/test" description="2 funções" />
  <Card title="Webhooks" href="/docs/servicos/sell/webhooks" description="3 funções" />
</Cards>


# Perfil acesso (/docs/servicos/sell/perfil_acesso)

> 7 funções do TermoSell para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso com paginação |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcesso>` · Rust: `Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>` · veja [`PaginaPerfilAcesso`](#tipo-paginaperfilacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoSell dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`clientes`, `colaboradores`, `configuracoes`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoComplete`](#tipo-paginaperfilacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/sell";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcesso [#tipo-paginaperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcesso } from "termo_core/sell";

export interface PaginaPerfilAcesso {
  itens: Array<PaginaPerfilAcessoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaPerfilAcesso;

pub struct PaginaPerfilAcesso {
    pub itens: Vec<PaginaPerfilAcessoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoComplete [#tipo-paginaperfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoComplete } from "termo_core/sell";

export interface PaginaPerfilAcessoAutoComplete {
  itens: Array<PaginaPerfilAcessoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaPerfilAcessoAutoComplete;

pub struct PaginaPerfilAcessoAutoComplete {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteItensItem [#tipo-paginaperfilacessoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaPerfilAcessoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaPerfilAcessoAutoCompleteItensItem;

pub struct PaginaPerfilAcessoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoItensItem [#tipo-paginaperfilacessoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoItensItem } from "termo_core/sell";

export interface PaginaPerfilAcessoItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaPerfilAcessoItensItem;

pub struct PaginaPerfilAcessoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/sell";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/sell";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/sell";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/sell";

export interface Permissoes {
  clientes?: Acoes;
  colaboradores?: Acoes;
  configuracoes?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Permissoes;

pub struct Permissoes {
    pub clientes: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub configuracoes: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Robô (/docs/servicos/sell/robo)

> 9 funções do TermoSell para robô.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_robo`](#buscar_paginador_robo) | `GET /robo` | Lista os robôs com paginação |
| [`criar_robo`](#criar_robo) | `POST /robo` | Cadastra um robô de atendimento |
| [`buscar_auto_complete_robo`](#buscar_auto_complete_robo) | `GET /robo/autocomplete` | Lista básica de robôs para seleção |
| [`buscar_equipes_robo`](#buscar_equipes_robo) | `GET /robo/equipes` | Lista as equipes do Chatwoot |
| [`buscar_pelo_filtro_robo`](#buscar_pelo_filtro_robo) | `GET /robo/filtro` | Busca robôs por filtro |
| [`buscar_modelos_robo`](#buscar_modelos_robo) | `GET /robo/modelos` | Lista os modelos de IA que o robô pode usar |
| [`buscar_pelo_id_robo`](#buscar_pelo_id_robo) | `GET /robo/{id}` | Busca um robô pelo id |
| [`atualizar_pelo_id_robo`](#atualizar_pelo_id_robo) | `PATCH /robo/{id}` | Atualiza um robô pelo id |
| [`deletar_pelo_id_robo`](#deletar_pelo_id_robo) | `DELETE /robo/{id}` | Exclui um robô pelo id |

## `buscar_paginador_robo` [#buscar_paginador_robo]

<Rota metodo="GET" caminho="/robo" credencial />

Lista os robôs com paginação

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Ordena por nome. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_robo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorRobo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaRobo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_robo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorRobo,
) -> Result<tipos::PaginaRobo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_robo(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorRobo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaRobo>` · Rust: `Result<tipos::PaginaRobo, ErroAoChamarServico>` · veja [`PaginaRobo`](#tipo-paginarobo).

## `criar_robo` [#criar_robo]

<Rota metodo="POST" caminho="/robo" credencial />

Cadastra um robô de atendimento

Exige a permissão `criar` da área `configuracoes`. `nome` é obrigatório (até 80 caracteres, único entre os robôs); `modelo` é a IA preferida do gateway do TermoAI, um `provedor` de `GET /robo/modelos` (opcional, até 80; vazio deixa o TermoAI escolher); `descricao` vai até 200 e `prompt_base` até 4000 (padrão vazio). Sem `fluxo`, o robô nasce só com a etapa de início. O robô nasce ativo, na versão 1. `fluxo` é o caminho do atendimento: `nos` (até 40 etapas, exatamente uma do tipo `inicio`; os outros tipos são `inicio_contato_novo`, `instrucao`, `mensagem`, `botoes`, `atendimento` e `gatilho`) e `ligacoes` (`origem`, `destino` e `origem_saida`, que é o id do botão ou da regra de onde a ligação sai, `null` no início e na mensagem). Cada etapa fora o início precisa de `nome` (até 60 caracteres); `objetivo` vai até 200, `instrucao` até 2000 e `mensagem` até 1000; `ferramentas` lista até 20 ids de ferramentas do robô. A `instrucao` precisa de 1 a 10 `regras` de saída (`condicao` até 200 caracteres); `botoes` precisa de 1 a 10 botões (`rotulo` até 20 caracteres) e de texto fixo em `mensagem` ou, com `mensagem_por_ia`, da `instrucao` para a IA escrever; `mensagem` também exige texto fixo ou `mensagem_por_ia`; `atendimento` encerra o robô, passa a conversa para a equipe do Chatwoot em `equipe_id` (opcional, de `GET /robo/equipes`) e não tem saída; `gatilho` (no máximo um, sem ligação de entrada nem de saída) é o gatilho de cliente sem resposta: `minutos_sem_resposta` (1 a 1440) e `equipe_id` opcional, e uma varredura a cada minuto passa para essa equipe toda conversa com o robô em que o cliente ficou esse tempo sem responder. Ids de etapas, botões e regras são únicos; nenhuma ligação volta ao início nem liga a etapa nela mesma, e cada saída tem no máximo uma próxima etapa. `inicio_contato_novo` (no máximo um, sem ligação de entrada) é o início de quem não está na lista de clientes: só vale com `atender_contatos_novos` ligado e, sem ele ou sem ligação, o contato novo sai pelo `inicio`. O texto fixo aceita marcadores como `{{cliente.nome}}` e `{{ultimo_pedido.itens}}`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_robo(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.RoboCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Robo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_robo(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::RoboCriar,
) -> Result<tipos::Robo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::criar_robo(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.RoboCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::RoboCriar", typeDescriptionLink: "#tipo-robocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Robo>` · Rust: `Result<tipos::Robo, ErroAoChamarServico>` · veja [`Robo`](#tipo-robo).

## `buscar_auto_complete_robo` [#buscar_auto_complete_robo]

<Rota metodo="GET" caminho="/robo/autocomplete" credencial />

Lista básica de robôs para seleção

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e modelo, em ordem alfabética de nome. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_robo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteRobo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaRoboAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_robo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteRobo,
) -> Result<tipos::PaginaRoboAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_robo(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteRobo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaRoboAutoComplete>` · Rust: `Result<tipos::PaginaRoboAutoComplete, ErroAoChamarServico>` · veja [`PaginaRoboAutoComplete`](#tipo-paginaroboautocomplete).

## `buscar_equipes_robo` [#buscar_equipes_robo]

<Rota metodo="GET" caminho="/robo/equipes" credencial />

Lista as equipes do Chatwoot

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Consulta na hora a conta do Chatwoot ativa e devolve as equipes dela (id e nome), para escolher a `equipe_id` da etapa `atendimento` ou do `gatilho` do fluxo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_equipes_robo(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.EquipeChatwoot>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_equipes_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_equipes_robo(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_equipes_robo(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<Vec<tipos::EquipeChatwoot>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_equipes_robo(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.EquipeChatwoot>>` · Rust: `Result<Vec<tipos::EquipeChatwoot>, ErroAoChamarServico>`

## `buscar_pelo_filtro_robo` [#buscar_pelo_filtro_robo]

<Rota metodo="GET" caminho="/robo/filtro" credencial />

Busca robôs por filtro

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve todos os robôs que casam com o filtro, com o fluxo, sem paginação, em ordem alfabética de nome. `nome` e `modelo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_robo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroRobo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Robo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_robo(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroRobo,
) -> Result<Vec<tipos::Robo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_robo(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroRobo { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.modelo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Robo>>` · Rust: `Result<Vec<tipos::Robo>, ErroAoChamarServico>`

## `buscar_modelos_robo` [#buscar_modelos_robo]

<Rota metodo="GET" caminho="/robo/modelos" credencial />

Lista os modelos de IA que o robô pode usar

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Consulta na hora o gateway do TermoAI (`GET /gateway/modelos`, categoria `texto_para_texto`, com o token do aplicativo) e devolve as IAs com chave ativa lá: `provedor` (o valor que vai em `modelo` do robô), `empresa`, `modelo`, `url_da_logo`, `logo_monocromatica`, `gratuito`, `aceita_ferramentas` e `chaves_ativas`. O robô com `modelo` vazio deixa o TermoAI escolher; com um `provedor`, o TermoAI usa essa IA primeiro e só troca para outra quando ela falha.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_modelos_robo(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.ModeloDoGateway>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_modelos_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_modelos_robo(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_modelos_robo(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<Vec<tipos::ModeloDoGateway>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_modelos_robo(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.ModeloDoGateway>>` · Rust: `Result<Vec<tipos::ModeloDoGateway>, ErroAoChamarServico>`

## `buscar_pelo_id_robo` [#buscar_pelo_id_robo]

<Rota metodo="GET" caminho="/robo/{id}" credencial />

Busca um robô pelo id

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve o robô com o fluxo completo. Robô excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_robo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Robo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_robo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Robo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_robo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Robo>` · Rust: `Result<tipos::Robo, ErroAoChamarServico>` · veja [`Robo`](#tipo-robo).

## `atualizar_pelo_id_robo` [#atualizar_pelo_id_robo]

<Rota metodo="PATCH" caminho="/robo/{id}" credencial />

Atualiza um robô pelo id

Exige a permissão `editar` da área `configuracoes`. Atualização parcial: só os campos enviados mudam, com os mesmos limites do cadastro; `descricao` vazia apaga o valor `ativo` liga ou desliga o robô e `atender_contatos_novos` decide se o robô atende quem não está na lista de clientes (cliente cadastrado com o atendente desligado continua indo para a equipe). `fluxo`, quando enviado, substitui o fluxo inteiro. Enviar `prompt_base` ou `fluxo` sobe a `versao` em 1. `fluxo` é o caminho do atendimento: `nos` (até 40 etapas, exatamente uma do tipo `inicio`; os outros tipos são `inicio_contato_novo`, `instrucao`, `mensagem`, `botoes`, `atendimento` e `gatilho`) e `ligacoes` (`origem`, `destino` e `origem_saida`, que é o id do botão ou da regra de onde a ligação sai, `null` no início e na mensagem). Cada etapa fora o início precisa de `nome` (até 60 caracteres); `objetivo` vai até 200, `instrucao` até 2000 e `mensagem` até 1000; `ferramentas` lista até 20 ids de ferramentas do robô. A `instrucao` precisa de 1 a 10 `regras` de saída (`condicao` até 200 caracteres); `botoes` precisa de 1 a 10 botões (`rotulo` até 20 caracteres) e de texto fixo em `mensagem` ou, com `mensagem_por_ia`, da `instrucao` para a IA escrever; `mensagem` também exige texto fixo ou `mensagem_por_ia`; `atendimento` encerra o robô, passa a conversa para a equipe do Chatwoot em `equipe_id` (opcional, de `GET /robo/equipes`) e não tem saída; `gatilho` (no máximo um, sem ligação de entrada nem de saída) é o gatilho de cliente sem resposta: `minutos_sem_resposta` (1 a 1440) e `equipe_id` opcional, e uma varredura a cada minuto passa para essa equipe toda conversa com o robô em que o cliente ficou esse tempo sem responder. Ids de etapas, botões e regras são únicos; nenhuma ligação volta ao início nem liga a etapa nela mesma, e cada saída tem no máximo uma próxima etapa. `inicio_contato_novo` (no máximo um, sem ligação de entrada) é o início de quem não está na lista de clientes: só vale com `atender_contatos_novos` ligado e, sem ele ou sem ligação, o contato novo sai pelo `inicio`. O texto fixo aceita marcadores como `{{cliente.nome}}` e `{{ultimo_pedido.itens}}`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_robo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.RoboAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Robo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_robo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::RoboAtualizar,
) -> Result<tipos::Robo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_robo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.RoboAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::RoboAtualizar", typeDescriptionLink: "#tipo-roboatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Robo>` · Rust: `Result<tipos::Robo, ErroAoChamarServico>` · veja [`Robo`](#tipo-robo).

## `deletar_pelo_id_robo` [#deletar_pelo_id_robo]

<Rota metodo="DELETE" caminho="/robo/{id}" credencial />

Exclui um robô pelo id

Exige a permissão `deletar` da área `configuracoes`. A exclusão é lógica: o robô some das consultas, o nome fica livre para um novo cadastro e não há como restaurar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_robo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_robo } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_robo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_robo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_robo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EquipeChatwoot [#tipo-equipechatwoot]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EquipeChatwoot } from "termo_core/sell";

export interface EquipeChatwoot {
  id: number;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::EquipeChatwoot;

pub struct EquipeChatwoot {
    pub id: i64,
    pub nome: String,
}
```

</Tab>
</Tabs>

### ModeloDoGateway [#tipo-modelodogateway]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ModeloDoGateway } from "termo_core/sell";

export interface ModeloDoGateway {
  aceita_ferramentas: boolean;
  chaves_ativas: number;
  empresa: string;
  gratuito: boolean;
  logo_monocromatica: boolean;
  modelo: string;
  provedor: string;
  url_da_logo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::ModeloDoGateway;

pub struct ModeloDoGateway {
    pub aceita_ferramentas: bool,
    pub chaves_ativas: i64,
    pub empresa: String,
    pub gratuito: bool,
    pub logo_monocromatica: bool,
    pub modelo: String,
    pub provedor: String,
    pub url_da_logo: String,
}
```

</Tab>
</Tabs>

### PaginaRobo [#tipo-paginarobo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRobo } from "termo_core/sell";

export interface PaginaRobo {
  itens: Array<PaginaRoboItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRobo;

pub struct PaginaRobo {
    pub itens: Vec<PaginaRoboItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaRoboAutoComplete [#tipo-paginaroboautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboAutoComplete } from "termo_core/sell";

export interface PaginaRoboAutoComplete {
  itens: Array<PaginaRoboAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboAutoComplete;

pub struct PaginaRoboAutoComplete {
    pub itens: Vec<PaginaRoboAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaRoboAutoCompleteItensItem [#tipo-paginaroboautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaRoboAutoCompleteItensItem {
  id: string;
  modelo: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboAutoCompleteItensItem;

pub struct PaginaRoboAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub modelo: String,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaRoboItensItem [#tipo-paginaroboitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboItensItem } from "termo_core/sell";

export interface PaginaRoboItensItem {
  atender_contatos_novos: boolean;
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao?: string | null;
  fluxo: RoboFluxo;
  id: string;
  modelo: string;
  nome: string;
  prompt_base: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboItensItem;

pub struct PaginaRoboItensItem {
    pub atender_contatos_novos: bool,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub fluxo: RoboFluxo,
    pub id: uuid::Uuid,
    pub modelo: String,
    pub nome: String,
    pub prompt_base: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>

### Robo [#tipo-robo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Robo } from "termo_core/sell";

export interface Robo {
  atender_contatos_novos: boolean;
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao?: string | null;
  fluxo: RoboFluxo;
  id: string;
  modelo: string;
  nome: string;
  prompt_base: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::Robo;

pub struct Robo {
    pub atender_contatos_novos: bool,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub fluxo: RoboFluxo,
    pub id: uuid::Uuid,
    pub modelo: String,
    pub nome: String,
    pub prompt_base: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>

### RoboAtualizar [#tipo-roboatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboAtualizar } from "termo_core/sell";

export interface RoboAtualizar {
  atender_contatos_novos?: boolean | null;
  ativo?: boolean | null;
  descricao?: string | null;
  fluxo?: RoboFluxo | null;
  modelo?: string | null;
  nome?: string | null;
  prompt_base?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboAtualizar;

pub struct RoboAtualizar {
    pub atender_contatos_novos: Option<bool>,
    pub ativo: Option<bool>,
    pub descricao: Option<String>,
    pub fluxo: Option<RoboFluxo>,
    pub modelo: Option<String>,
    pub nome: Option<String>,
    pub prompt_base: Option<String>,
}
```

</Tab>
</Tabs>

### RoboBotao [#tipo-robobotao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboBotao } from "termo_core/sell";

export interface RoboBotao {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboBotao;

pub struct RoboBotao {
    pub id: String,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### RoboCriar [#tipo-robocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboCriar } from "termo_core/sell";

export interface RoboCriar {
  descricao?: string | null;
  fluxo?: RoboFluxo | null;
  modelo?: string;
  nome: string;
  prompt_base?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboCriar;

pub struct RoboCriar {
    pub descricao: Option<String>,
    pub fluxo: Option<RoboFluxo>,
    pub modelo: Option<String>,
    pub nome: String,
    pub prompt_base: Option<String>,
}
```

</Tab>
</Tabs>

### RoboFluxo [#tipo-robofluxo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboFluxo } from "termo_core/sell";

export interface RoboFluxo {
  ligacoes?: Array<RoboLigacao>;
  nos?: Array<RoboNo>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboFluxo;

pub struct RoboFluxo {
    pub ligacoes: Option<Vec<RoboLigacao>>,
    pub nos: Option<Vec<RoboNo>>,
}
```

</Tab>
</Tabs>

### RoboLigacao [#tipo-roboligacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboLigacao } from "termo_core/sell";

export interface RoboLigacao {
  destino: string;
  id: string;
  origem: string;
  origem_saida?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboLigacao;

pub struct RoboLigacao {
    pub destino: String,
    pub id: String,
    pub origem: String,
    pub origem_saida: Option<String>,
}
```

</Tab>
</Tabs>

### RoboNo [#tipo-robono]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboNo } from "termo_core/sell";

export interface RoboNo {
  botoes?: Array<RoboBotao>;
  equipe_id?: number | null;
  ferramentas?: Array<string>;
  id: string;
  instrucao?: string;
  mensagem?: string;
  mensagem_por_ia?: boolean;
  minutos_sem_resposta?: number | null;
  nome?: string;
  objetivo?: string;
  posicao: RoboPosicao;
  regras?: Array<RoboRegra>;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboNo;

pub struct RoboNo {
    pub botoes: Option<Vec<RoboBotao>>,
    pub equipe_id: Option<i64>,
    pub ferramentas: Option<Vec<uuid::Uuid>>,
    pub id: String,
    pub instrucao: Option<String>,
    pub mensagem: Option<String>,
    pub mensagem_por_ia: Option<bool>,
    pub minutos_sem_resposta: Option<i32>,
    pub nome: Option<String>,
    pub objetivo: Option<String>,
    pub posicao: RoboPosicao,
    pub regras: Option<Vec<RoboRegra>>,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### RoboPosicao [#tipo-roboposicao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboPosicao } from "termo_core/sell";

export interface RoboPosicao {
  x?: number;
  y?: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboPosicao;

pub struct RoboPosicao {
    pub x: Option<f64>,
    pub y: Option<f64>,
}
```

</Tab>
</Tabs>

### RoboRegra [#tipo-roboregra]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboRegra } from "termo_core/sell";

export interface RoboRegra {
  condicao: string;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboRegra;

pub struct RoboRegra {
    pub condicao: String,
    pub id: String,
}
```

</Tab>
</Tabs>


# Robô ferramenta (/docs/servicos/sell/robo_ferramenta)

> 7 funções do TermoSell para robô ferramenta.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_robo_ferramenta`](#buscar_paginador_robo_ferramenta) | `GET /robo_ferramenta` | Lista as ferramentas com paginação |
| [`criar_robo_ferramenta`](#criar_robo_ferramenta) | `POST /robo_ferramenta` | Cadastra uma ferramenta do robô |
| [`buscar_auto_complete_robo_ferramenta`](#buscar_auto_complete_robo_ferramenta) | `GET /robo_ferramenta/autocomplete` | Lista básica de ferramentas para seleção |
| [`buscar_pelo_filtro_robo_ferramenta`](#buscar_pelo_filtro_robo_ferramenta) | `GET /robo_ferramenta/filtro` | Busca ferramentas por filtro |
| [`buscar_pelo_id_robo_ferramenta`](#buscar_pelo_id_robo_ferramenta) | `GET /robo_ferramenta/{id}` | Busca uma ferramenta pelo id |
| [`atualizar_pelo_id_robo_ferramenta`](#atualizar_pelo_id_robo_ferramenta) | `PATCH /robo_ferramenta/{id}` | Atualiza uma ferramenta pelo id |
| [`deletar_pelo_id_robo_ferramenta`](#deletar_pelo_id_robo_ferramenta) | `DELETE /robo_ferramenta/{id}` | Exclui uma ferramenta pelo id |

## `buscar_paginador_robo_ferramenta` [#buscar_paginador_robo_ferramenta]

<Rota metodo="GET" caminho="/robo_ferramenta" credencial />

Lista as ferramentas com paginação

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Ordena pelo rótulo. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorRoboFerramenta = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaRoboFerramenta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_robo_ferramenta(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorRoboFerramenta,
) -> Result<tipos::PaginaRoboFerramenta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_paginador_robo_ferramenta(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPaginadorRoboFerramenta { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaRoboFerramenta>` · Rust: `Result<tipos::PaginaRoboFerramenta, ErroAoChamarServico>` · veja [`PaginaRoboFerramenta`](#tipo-paginaroboferramenta).

## `criar_robo_ferramenta` [#criar_robo_ferramenta]

<Rota metodo="POST" caminho="/robo_ferramenta" credencial />

Cadastra uma ferramenta do robô

Exige a permissão `criar` da área `configuracoes`. Cadastra uma ferramenta que as etapas do robô podem liberar para a IA. `nome` é o nome técnico (só letras minúsculas, números e `_`, até 60 caracteres, único); `rotulo` (até 80) e `descricao` (até 500) são obrigatórios; `tipo` é `leitura` ou `escrita`; `exige_confirmacao` tem padrão `false`; `esquema` é o JSON Schema dos parâmetros (padrão: objeto sem propriedades). A ferramenta nasce ativa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.RoboFerramentaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.RoboFerramenta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_robo_ferramenta(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::RoboFerramentaCriar,
) -> Result<tipos::RoboFerramenta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::criar_robo_ferramenta(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.RoboFerramentaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::RoboFerramentaCriar", typeDescriptionLink: "#tipo-roboferramentacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.RoboFerramenta>` · Rust: `Result<tipos::RoboFerramenta, ErroAoChamarServico>` · veja [`RoboFerramenta`](#tipo-roboferramenta).

## `buscar_auto_complete_robo_ferramenta` [#buscar_auto_complete_robo_ferramenta]

<Rota metodo="GET" caminho="/robo_ferramenta/autocomplete" credencial />

Lista básica de ferramentas para seleção

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome técnico e rótulo das ferramentas ativas, em ordem alfabética do rótulo. `busca` procura por trecho do rótulo ou do nome técnico, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteRoboFerramenta = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaRoboFerramentaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_robo_ferramenta(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteRoboFerramenta,
) -> Result<tipos::PaginaRoboFerramentaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_auto_complete_robo_ferramenta(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarAutoCompleteRoboFerramenta { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaRoboFerramentaAutoComplete>` · Rust: `Result<tipos::PaginaRoboFerramentaAutoComplete, ErroAoChamarServico>` · veja [`PaginaRoboFerramentaAutoComplete`](#tipo-paginaroboferramentaautocomplete).

## `buscar_pelo_filtro_robo_ferramenta` [#buscar_pelo_filtro_robo_ferramenta]

<Rota metodo="GET" caminho="/robo_ferramenta/filtro" credencial />

Busca ferramentas por filtro

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Devolve todas as ferramentas que casam com o filtro, sem paginação, em ordem alfabética do rótulo. `nome` procura por trecho do nome técnico, sem diferenciar maiúsculas; `tipo` compara o valor exato (`leitura` ou `escrita`); `ativo` filtra pela situação. Sem filtro, devolve todas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroRoboFerramenta = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.RoboFerramenta>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_robo_ferramenta(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroRoboFerramenta,
) -> Result<Vec<tipos::RoboFerramenta>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_filtro_robo_ferramenta(
    &credencial_de_acesso,
    &termo_core::sell::ParametrosDeBuscarPeloFiltroRoboFerramenta { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.RoboFerramenta>>` · Rust: `Result<Vec<tipos::RoboFerramenta>, ErroAoChamarServico>`

## `buscar_pelo_id_robo_ferramenta` [#buscar_pelo_id_robo_ferramenta]

<Rota metodo="GET" caminho="/robo_ferramenta/{id}" credencial />

Busca uma ferramenta pelo id

Exige qualquer permissão da área `configuracoes` (qualquer ação liberada na área já libera a leitura). Ferramenta excluída responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.RoboFerramenta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_robo_ferramenta(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::RoboFerramenta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::buscar_pelo_id_robo_ferramenta(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.RoboFerramenta>` · Rust: `Result<tipos::RoboFerramenta, ErroAoChamarServico>` · veja [`RoboFerramenta`](#tipo-roboferramenta).

## `atualizar_pelo_id_robo_ferramenta` [#atualizar_pelo_id_robo_ferramenta]

<Rota metodo="PATCH" caminho="/robo_ferramenta/{id}" credencial />

Atualiza uma ferramenta pelo id

Exige a permissão `editar` da área `configuracoes`. Atualização parcial: só os campos enviados mudam. `rotulo` (até 80) e `descricao` (até 500) não podem ficar vazios; `tipo` é `leitura` ou `escrita`; `esquema` substitui o JSON Schema inteiro; `ativo` liga ou desliga a ferramenta. O nome técnico não muda.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.RoboFerramentaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.RoboFerramenta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_robo_ferramenta(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::RoboFerramentaAtualizar,
) -> Result<tipos::RoboFerramenta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::sell::atualizar_pelo_id_robo_ferramenta(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.RoboFerramentaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::RoboFerramentaAtualizar", typeDescriptionLink: "#tipo-roboferramentaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.RoboFerramenta>` · Rust: `Result<tipos::RoboFerramenta, ErroAoChamarServico>` · veja [`RoboFerramenta`](#tipo-roboferramenta).

## `deletar_pelo_id_robo_ferramenta` [#deletar_pelo_id_robo_ferramenta]

<Rota metodo="DELETE" caminho="/robo_ferramenta/{id}" credencial />

Exclui uma ferramenta pelo id

Exige a permissão `deletar` da área `configuracoes`. A exclusão é lógica: a ferramenta some das consultas, o nome técnico fica livre e não há como restaurar.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_robo_ferramenta(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_robo_ferramenta } from "termo_core/sell";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_robo_ferramenta(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_robo_ferramenta(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::sell::deletar_pelo_id_robo_ferramenta(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaRoboFerramenta [#tipo-paginaroboferramenta]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboFerramenta } from "termo_core/sell";

export interface PaginaRoboFerramenta {
  itens: Array<PaginaRoboFerramentaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboFerramenta;

pub struct PaginaRoboFerramenta {
    pub itens: Vec<PaginaRoboFerramentaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaRoboFerramentaAutoComplete [#tipo-paginaroboferramentaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboFerramentaAutoComplete } from "termo_core/sell";

export interface PaginaRoboFerramentaAutoComplete {
  itens: Array<PaginaRoboFerramentaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboFerramentaAutoComplete;

pub struct PaginaRoboFerramentaAutoComplete {
    pub itens: Vec<PaginaRoboFerramentaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaRoboFerramentaAutoCompleteItensItem [#tipo-paginaroboferramentaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboFerramentaAutoCompleteItensItem } from "termo_core/sell";

export interface PaginaRoboFerramentaAutoCompleteItensItem {
  id: string;
  nome: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboFerramentaAutoCompleteItensItem;

pub struct PaginaRoboFerramentaAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaRoboFerramentaItensItem [#tipo-paginaroboferramentaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaRoboFerramentaItensItem } from "termo_core/sell";

export interface PaginaRoboFerramentaItensItem {
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao: string;
  esquema: Record<string, unknown>;
  exige_confirmacao: boolean;
  id: string;
  nome: string;
  rotulo: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::PaginaRoboFerramentaItensItem;

pub struct PaginaRoboFerramentaItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub esquema: serde_json::Map<String, serde_json::Value>,
    pub exige_confirmacao: bool,
    pub id: uuid::Uuid,
    pub nome: String,
    pub rotulo: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### RoboFerramenta [#tipo-roboferramenta]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboFerramenta } from "termo_core/sell";

export interface RoboFerramenta {
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao: string;
  esquema: Record<string, unknown>;
  exige_confirmacao: boolean;
  id: string;
  nome: string;
  rotulo: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboFerramenta;

pub struct RoboFerramenta {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub esquema: serde_json::Map<String, serde_json::Value>,
    pub exige_confirmacao: bool,
    pub id: uuid::Uuid,
    pub nome: String,
    pub rotulo: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### RoboFerramentaAtualizar [#tipo-roboferramentaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboFerramentaAtualizar } from "termo_core/sell";

export interface RoboFerramentaAtualizar {
  ativo?: boolean | null;
  descricao?: string | null;
  esquema?: Record<string, unknown> | null;
  exige_confirmacao?: boolean | null;
  rotulo?: string | null;
  tipo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboFerramentaAtualizar;

pub struct RoboFerramentaAtualizar {
    pub ativo: Option<bool>,
    pub descricao: Option<String>,
    pub esquema: Option<serde_json::Map<String, serde_json::Value>>,
    pub exige_confirmacao: Option<bool>,
    pub rotulo: Option<String>,
    pub tipo: Option<String>,
}
```

</Tab>
</Tabs>

### RoboFerramentaCriar [#tipo-roboferramentacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { RoboFerramentaCriar } from "termo_core/sell";

export interface RoboFerramentaCriar {
  descricao: string;
  esquema?: Record<string, unknown> | null;
  exige_confirmacao?: boolean | null;
  nome: string;
  rotulo: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::RoboFerramentaCriar;

pub struct RoboFerramentaCriar {
    pub descricao: String,
    pub esquema: Option<serde_json::Map<String, serde_json::Value>>,
    pub exige_confirmacao: Option<bool>,
    pub nome: String,
    pub rotulo: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/sell/test)

> 2 funções do TermoSell para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true` e a versão do backend publicada, no formato semver.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/sell";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::sell::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` e a versão do backend no ar (semver) sempre que o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/sell";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::sell::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/sell";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/sell";

export interface VersaoDoBackend {
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::VersaoDoBackend;

pub struct VersaoDoBackend {
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>


# Webhooks (/docs/servicos/sell/webhooks)

> 3 funções do TermoSell para webhooks.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as sell from "termo_core/sell";
// ou: import { sell } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["sell"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`receber_evento_chatwoot_webhooks`](#receber_evento_chatwoot_webhooks) | `POST /webhooks/chatwoot` | Recebe os eventos do Chatwoot |
| [`receber_evento_termo_webhook_webhooks`](#receber_evento_termo_webhook_webhooks) | `POST /webhooks/termowebhook` | Recebe as entregas do TermoWebhook |
| [`receber_evento_z_api_webhooks`](#receber_evento_z_api_webhooks) | `POST /webhooks/z_api` | Recebe as mensagens do WhatsApp pela Z-API |

## `receber_evento_chatwoot_webhooks` [#receber_evento_chatwoot_webhooks]

<Rota metodo="POST" caminho="/webhooks/chatwoot" />

Recebe os eventos do Chatwoot

Pública, sem token do usuário: é chamada pelo robô de atendimento que o TermoSell cria na conta do Chatwoot, com o `segredo` da configuração no endereço. O corpo é o evento do Chatwoot como ele envia. Só `message_created` que não é nota privada e chega por uma caixa ligada a um número da Z-API é tratado: mensagem da equipe vai para o WhatsApp pela Z-API, e mensagem do cliente numa conversa pendente é respondida pelo robô em segundo plano, seguindo o fluxo do robô do número. O resto é ignorado com `200`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_chatwoot_webhooks(
  parametros: ParametrosDeReceberEventoChatwootWebhooks,
  corpo_da_requisicao: tipos.EventoDoChatwoot,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { receber_evento_chatwoot_webhooks } from "termo_core/sell";

await receber_evento_chatwoot_webhooks({ segredo }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_chatwoot_webhooks(
    parametros: &ParametrosDeReceberEventoChatwootWebhooks,
    corpo_da_requisicao: &tipos::EventoDoChatwoot,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::sell::receber_evento_chatwoot_webhooks(
    &termo_core::sell::ParametrosDeReceberEventoChatwootWebhooks { segredo },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.segredo": { type: "string", required: true, description: "Segredo do webhook que o TermoSell gerou e embutiu no endereço cadastrado no serviço externo · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.EventoDoChatwoot", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EventoDoChatwoot", typeDescriptionLink: "#tipo-eventodochatwoot" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `receber_evento_termo_webhook_webhooks` [#receber_evento_termo_webhook_webhooks]

<Rota metodo="POST" caminho="/webhooks/termowebhook" />

Recebe as entregas do TermoWebhook

Pública, sem token do usuário: é chamada pelo TermoWebhook, o hub de eventos da Termotubos, para entregar os eventos que o TermoSell assina. A entrega é conferida pela assinatura Ed25519 do hub (chave pública em `/.well-known/jwks.json` do TermoWebhook), pela data e pelo destino, que precisa ser o próprio TermoSell. Eventos tratados: `colaborador.criado` e `colaborador.atualizado`, versões 1 e 2, publicados pelo TermoAuth: criam ou atualizam o colaborador e o acesso dele (a v2 também traz setor, cargo e função), descartando o evento mais antigo que o último aplicado. Qualquer outro tipo responde `200` sem fazer nada. Como o hub entrega pelo menos uma vez, repetir o mesmo evento é seguro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_termo_webhook_webhooks(
  parametros: ParametrosDeReceberEventoTermoWebhookWebhooks,
  corpo_da_requisicao: tipos.EntregaDoTermoWebhook,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { receber_evento_termo_webhook_webhooks } from "termo_core/sell";

await receber_evento_termo_webhook_webhooks({ "X-TermoWebhook-Data": 1, "X-TermoWebhook-Chave": "...", "X-TermoWebhook-Destino": "...", "X-TermoWebhook-Assinatura": "..." }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_termo_webhook_webhooks(
    parametros: &ParametrosDeReceberEventoTermoWebhookWebhooks,
    corpo_da_requisicao: &tipos::EntregaDoTermoWebhook,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::sell::receber_evento_termo_webhook_webhooks(
    &termo_core::sell::ParametrosDeReceberEventoTermoWebhookWebhooks { x_termo_webhook_data, x_termo_webhook_chave, x_termo_webhook_destino, x_termo_webhook_assinatura },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.X-TermoWebhook-Data": { type: "number", required: true, description: "Horário Unix em segundos usado na assinatura\n\nEnviado no cabeçalho X-TermoWebhook-Data. · Rust: i64" },
    "parametros.X-TermoWebhook-Chave": { type: "string", required: true, description: "Id (kid) da chave do hub que assinou a entrega\n\nEnviado no cabeçalho X-TermoWebhook-Chave. · Rust: String" },
    "parametros.X-TermoWebhook-Destino": { type: "string", required: true, description: "Id do aplicativo destino no hub, que precisa ser o do TermoSell\n\nEnviado no cabeçalho X-TermoWebhook-Destino. · Rust: String" },
    "parametros.X-TermoWebhook-Assinatura": { type: "string", required: true, description: "ed25519=<base64url> da assinatura de <data>.<destino>.<corpo>\n\nEnviado no cabeçalho X-TermoWebhook-Assinatura. · Rust: String" },
    "corpo_da_requisicao": { type: "tipos.EntregaDoTermoWebhook", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EntregaDoTermoWebhook", typeDescriptionLink: "#tipo-entregadotermowebhook" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## `receber_evento_z_api_webhooks` [#receber_evento_z_api_webhooks]

<Rota metodo="POST" caminho="/webhooks/z_api" />

Recebe as mensagens do WhatsApp pela Z-API

Pública, sem token do usuário: é chamada pela Z-API, com o `segredo` do número no endereço. O corpo é o evento da Z-API como ela envia; o `instanceId` dele precisa ser o da instância do número dono do `segredo`. Mensagem recebida de conversa individual, num número ativo e ligado a uma caixa do Chatwoot, é registrada no Chatwoot (a mesma mensagem não é registrada duas vezes); grupos, canais, transmissões e ecos do próprio sistema são ignorados com `200`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_z_api_webhooks(
  parametros: ParametrosDeReceberEventoZApiWebhooks,
  corpo_da_requisicao: tipos.EventoDaZApi,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { receber_evento_z_api_webhooks } from "termo_core/sell";

await receber_evento_z_api_webhooks({ segredo }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_z_api_webhooks(
    parametros: &ParametrosDeReceberEventoZApiWebhooks,
    corpo_da_requisicao: &tipos::EventoDaZApi,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::sell::receber_evento_z_api_webhooks(
    &termo_core::sell::ParametrosDeReceberEventoZApiWebhooks { segredo },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.segredo": { type: "string", required: true, description: "Segredo do webhook que o TermoSell gerou e embutiu no endereço cadastrado no serviço externo · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.EventoDaZApi", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EventoDaZApi", typeDescriptionLink: "#tipo-eventodazapi" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EntregaDoTermoWebhook [#tipo-entregadotermowebhook]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaDoTermoWebhook } from "termo_core/sell";

export interface EntregaDoTermoWebhook {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::EntregaDoTermoWebhook;

pub struct EntregaDoTermoWebhook {
    pub dados: serde_json::Map<String, serde_json::Value>,
    pub entidade_id: String,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>

### EventoDaZApi [#tipo-eventodazapi]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoDaZApi } from "termo_core/sell";

export type EventoDaZApi = Record<string, unknown>;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::EventoDaZApi;

pub type EventoDaZApi = serde_json::Map<String, serde_json::Value>;
```

</Tab>
</Tabs>

### EventoDoChatwoot [#tipo-eventodochatwoot]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoDoChatwoot } from "termo_core/sell";

export type EventoDoChatwoot = Record<string, unknown>;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::sell::EventoDoChatwoot;

pub type EventoDoChatwoot = serde_json::Map<String, serde_json::Value>;
```

</Tab>
</Tabs>


# TermoStatus (/docs/servicos/status)

> Cliente do TermoStatus no termo_core.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as status from "termo_core/status";
// ou: import { status } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["status"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::status` (feature `status`) |
| Importação TypeScript | `termo_core/status` ou `import { status } from "termo_core"` |
| Funções | 0 |
| Entidades | 0 |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51131` |
| `SANDBOX` | `https://sandbox-api-status.termotubos.com.br` |
| `PRODUCTION` | `https://api-status.termotubos.com.br` |

<Callout type="info" title="Ainda sem funções">O TermoStatus ainda não publicou o `openapi.json` no sandbox, então o módulo existe mas não tem funções. Elas aparecem aqui sozinhas assim que o contrato for publicado e o gerador rodar.</Callout>


# TermoStudio (/docs/servicos/studio)

> Cliente do TermoStudio no termo_core.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as studio from "termo_core/studio";
// ou: import { studio } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["studio"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::studio` (feature `studio`) |
| Importação TypeScript | `termo_core/studio` ou `import { studio } from "termo_core"` |
| Funções | 0 |
| Entidades | 0 |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | o mesmo do sandbox (`https://sandbox-api-studio.termotubos.com.br`) |
| `SANDBOX` | `https://sandbox-api-studio.termotubos.com.br` |
| `PRODUCTION` | `https://api-studio.termotubos.com.br` |

<Callout type="info" title="Ainda sem funções">O TermoStudio ainda não publicou o `openapi.json` no sandbox, então o módulo existe mas não tem funções. Elas aparecem aqui sozinhas assim que o contrato for publicado e o gerador rodar.</Callout>


# Anexo (/docs/servicos/support/anexo)

> 5 funções do TermoSupport para anexo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`criar_anexo`](#criar_anexo) | `POST /anexo` | Anexa um arquivo ou link |
| [`buscar_pelo_filtro_anexo`](#buscar_pelo_filtro_anexo) | `GET /anexo/filtro` | Lista os anexos de uma tarefa ou ticket |
| [`buscar_pelo_id_anexo`](#buscar_pelo_id_anexo) | `GET /anexo/{id}` | Baixa um anexo pelo id |
| [`atualizar_pelo_id_anexo`](#atualizar_pelo_id_anexo) | `PATCH /anexo/{id}` | Renomeia um anexo pelo id |
| [`deletar_pelo_id_anexo`](#deletar_pelo_id_anexo) | `DELETE /anexo/{id}` | Exclui um anexo pelo id |

## `criar_anexo` [#criar_anexo]

<Rota metodo="POST" caminho="/anexo" credencial />

Anexa um arquivo ou link

Exige a permissão `criar` na área `projetos` ou `tickets`. Anexa a uma tarefa (`tarefa_id`) ou ticket (`ticket_id`), nunca aos dois. Mande o arquivo em `arquivo_base64` (com ou sem o prefixo `data:...;base64,`, até 10 MB, `tipo_mime` informa o formato) ou um link em `url` (`http://` ou `https://`, até 1000 caracteres). Com `importar_url: true`, o servidor baixa a imagem de `url` e guarda o arquivo no lugar do link (é o caminho para anexar imagens pelo MCP): só `https://`, sem redirecionamento, servidor de IP público, resposta `image/*` de até 10 MB; o `tipo_mime` vem da resposta. `nome` é obrigatório (até 200). O arquivo vai para o TermoBucket (privado, app `termo-suporte`); se o bucket falhar, fica no banco até a rotina do backend levá-lo. O corpo aceita até 16 MiB. A atividade da tarefa ou do ticket ganha a linha do anexo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_anexo(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AnexoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Anexo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_anexo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_anexo(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_anexo(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AnexoCriar,
) -> Result<tipos::Anexo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_anexo(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AnexoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AnexoCriar", typeDescriptionLink: "#tipo-anexocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Anexo>` · Rust: `Result<tipos::Anexo, ErroAoChamarServico>` · veja [`Anexo`](#tipo-anexo).

## `buscar_pelo_filtro_anexo` [#buscar_pelo_filtro_anexo]

<Rota metodo="GET" caminho="/anexo/filtro" credencial />

Lista os anexos de uma tarefa ou ticket

Exige a permissão de leitura na área `projetos` ou `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve até 500 anexos, do mais novo para o mais antigo, sem o conteúdo dos arquivos. Informe `tarefa_id` ou `ticket_id`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_anexo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAnexo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Anexo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_anexo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_anexo(credencial_de_acesso, { tarefa_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_anexo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAnexo,
) -> Result<Vec<tipos::Anexo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_anexo(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroAnexo { tarefa_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tarefa_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ticket_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Anexo>>` · Rust: `Result<Vec<tipos::Anexo>, ErroAoChamarServico>`

## `buscar_pelo_id_anexo` [#buscar_pelo_id_anexo]

<Rota metodo="GET" caminho="/anexo/{id}" credencial />

Baixa um anexo pelo id

Exige a permissão de leitura na área `projetos` ou `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve os dados do anexo e, quando é arquivo, `url_download`: endereço de download assinado do TermoBucket (arquivo privado do app `termo-suporte`), válido por 15 minutos. `conteudo_base64` só vem preenchido enquanto o arquivo ainda está no banco (o TermoBucket falhou no envio; a rotina do backend leva ao bucket a cada 30 minutos). Os dois ficam vazios quando o anexo é um link.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_anexo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AnexoComConteudo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_anexo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_anexo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_anexo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::AnexoComConteudo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_anexo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AnexoComConteudo>` · Rust: `Result<tipos::AnexoComConteudo, ErroAoChamarServico>` · veja [`AnexoComConteudo`](#tipo-anexocomconteudo).

## `atualizar_pelo_id_anexo` [#atualizar_pelo_id_anexo]

<Rota metodo="PATCH" caminho="/anexo/{id}" credencial />

Renomeia um anexo pelo id

Exige a permissão `editar` na área `projetos` ou `tickets`. Troca o `nome` (obrigatório, até 200 caracteres).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_anexo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AnexoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Anexo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_anexo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_anexo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_anexo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AnexoAtualizar,
) -> Result<tipos::Anexo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_anexo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AnexoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AnexoAtualizar", typeDescriptionLink: "#tipo-anexoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Anexo>` · Rust: `Result<tipos::Anexo, ErroAoChamarServico>` · veja [`Anexo`](#tipo-anexo).

## `deletar_pelo_id_anexo` [#deletar_pelo_id_anexo]

<Rota metodo="DELETE" caminho="/anexo/{id}" credencial />

Exclui um anexo pelo id

Exige a permissão `deletar` na área `projetos` ou `tickets`. Exclusão lógica.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_anexo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_anexo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_anexo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_anexo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_anexo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Anexo [#tipo-anexo]

Arquivo (guardado no TermoBucket) ou link anexado a uma tarefa ou ticket. A lista não traz o arquivo:
ele vem só no `buscarPeloId`, pela URL de download assinada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Anexo } from "termo_core/support";

export interface Anexo {
  atualizado_em: string;
  autor?: ColaboradorResumo | null;
  criado_em: string;
  id: string;
  nome: string;
  tamanho: number;
  tarefa_id?: string | null;
  ticket_id?: string | null;
  tipo_mime: string;
  url?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Anexo;

pub struct Anexo {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub autor: Option<ColaboradorResumo>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub tamanho: i32,
    pub tarefa_id: Option<uuid::Uuid>,
    pub ticket_id: Option<uuid::Uuid>,
    pub tipo_mime: String,
    pub url: Option<String>,
}
```

</Tab>
</Tabs>

### AnexoAtualizar [#tipo-anexoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AnexoAtualizar } from "termo_core/support";

export interface AnexoAtualizar {
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AnexoAtualizar;

pub struct AnexoAtualizar {
    pub nome: String,
}
```

</Tab>
</Tabs>

### AnexoComConteudo [#tipo-anexocomconteudo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AnexoComConteudo } from "termo_core/support";

export type AnexoComConteudo = Anexo & AnexoComConteudoParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AnexoComConteudo;

pub type AnexoComConteudo = serde_json::Value;
```

</Tab>
</Tabs>

### AnexoComConteudoParte2 [#tipo-anexocomconteudoparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AnexoComConteudoParte2 } from "termo_core/support";

export interface AnexoComConteudoParte2 {
  /**
   * O arquivo em base64, só enquanto ele ainda não foi levado ao TermoBucket.
   */
  conteudo_base64?: string | null;
  /**
   * URL de download do arquivo no TermoBucket, assinada por 15 minutos (vazia quando o anexo é um link).
   */
  url_download?: string | null;
}
```

</Tab>
<Tab value="Rust">

`termo_core::support::AnexoComConteudoParte2`

</Tab>
</Tabs>

### AnexoCriar [#tipo-anexocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AnexoCriar } from "termo_core/support";

export interface AnexoCriar {
  /**
   * O arquivo em base64, com ou sem o prefixo `data:...;base64,`. Mande este ou `url`.
   */
  arquivo_base64?: string | null;
  /**
   * Com `true`, o servidor baixa a imagem de `url` (só `https`, `image/*`, até 10 MB) e guarda o
   * arquivo, como se ele tivesse vindo em `arquivo_base64`; o link não fica no anexo.
   */
  importar_url?: boolean | null;
  nome: string;
  tarefa_id?: string | null;
  ticket_id?: string | null;
  tipo_mime?: string | null;
  /**
   * Link externo (documento, print no drive). Mande este ou `arquivo_base64`.
   */
  url?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AnexoCriar;

pub struct AnexoCriar {
    /// O arquivo em base64, com ou sem o prefixo `data:...;base64,`. Mande este ou `url`.
    pub arquivo_base64: Option<String>,
    /// Com `true`, o servidor baixa a imagem de `url` (só `https`, `image/*`, até 10 MB) e guarda o
    /// arquivo, como se ele tivesse vindo em `arquivo_base64`; o link não fica no anexo.
    pub importar_url: Option<bool>,
    pub nome: String,
    pub tarefa_id: Option<uuid::Uuid>,
    pub ticket_id: Option<uuid::Uuid>,
    pub tipo_mime: Option<String>,
    /// Link externo (documento, print no drive). Mande este ou `arquivo_base64`.
    pub url: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorResumo [#tipo-colaboradorresumo]

Quem aparece como dono, membro, responsável, solicitante ou autor nos projetos, tarefas e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorResumo } from "termo_core/support";

export interface ColaboradorResumo {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorResumo;

pub struct ColaboradorResumo {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>


# Aplicativo (/docs/servicos/support/aplicativo)

> 4 funções do TermoSupport para aplicativo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_aplicativo`](#buscar_paginador_aplicativo) | `GET /aplicativo` | Lista os aplicativos paginados |
| [`buscar_auto_complete_aplicativo`](#buscar_auto_complete_aplicativo) | `GET /aplicativo/autocomplete` | Lista básica de aplicativos para seleção |
| [`buscar_pelo_filtro_aplicativo`](#buscar_pelo_filtro_aplicativo) | `GET /aplicativo/filtro` | Busca aplicativos por filtro |
| [`buscar_pelo_id_aplicativo`](#buscar_pelo_id_aplicativo) | `GET /aplicativo/{id}` | Busca um aplicativo pelo id |

## `buscar_paginador_aplicativo` [#buscar_paginador_aplicativo]

<Rota metodo="GET" caminho="/aplicativo" credencial />

Lista os aplicativos paginados

Exige a permissão de leitura na área `aplicativos`. A lista de aplicativos é a do TermoAuth (não há cadastro, edição nem exclusão no TermoSupport): antes de responder, a rota busca os apps no TermoAuth pelo `termo_core` com o token de quem chamou e espelha nome, endereço, descrição e cor. Para um master do TermoAuth vem a lista inteira (`todos=true`) e o que sumiu de lá fica inativo; para os demais, só entram ou se atualizam os apps que a pessoa pode abrir. Falha no TermoAuth não impede a resposta: vem o que já estava sincronizado. A sincronização também roda quando um master entra. Lista os aplicativos sincronizados (com `termoauth_id`) em ordem alfabética do nome, sempre 50 por página: `tamanho` é ignorado. `pagina` começa em 1 (padrão 1; valores menores viram 1). `total` é a quantidade de aplicativos não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_aplicativo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_aplicativo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAplicativo,
) -> Result<tipos::PaginaAplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_aplicativo(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorAplicativo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativo>` · Rust: `Result<tipos::PaginaAplicativo, ErroAoChamarServico>` · veja [`PaginaAplicativo`](#tipo-paginaaplicativo).

## `buscar_auto_complete_aplicativo` [#buscar_auto_complete_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/autocomplete" credencial />

Lista básica de aplicativos para seleção

Exige a permissão de leitura na área `aplicativos`, `projetos` ou `tickets`. Devolve só id, nome e endereço, em ordem alfabética do nome, sem os excluídos. `somente_ativos=true` deixa de fora os aplicativos inativos (é o que usam os campos de projetos e tickets). `busca` procura o trecho no nome ou no endereço, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_aplicativo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_aplicativo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAplicativo,
) -> Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_aplicativo(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteAplicativo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.somente_ativos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativoAutoComplete>` · Rust: `Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>` · veja [`PaginaAplicativoAutoComplete`](#tipo-paginaaplicativoautocomplete).

## `buscar_pelo_filtro_aplicativo` [#buscar_pelo_filtro_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/filtro" credencial />

Busca aplicativos por filtro

Exige a permissão de leitura na área `aplicativos`. Devolve todos os aplicativos sincronizados com o TermoAuth que casam com o filtro, sem paginação, em ordem alfabética do nome. `nome` e `endereco` procuram o trecho no campo, sem diferenciar maiúsculas; `ativo` filtra pela situação. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Aplicativo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_aplicativo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_aplicativo(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAplicativo,
) -> Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_aplicativo(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroAplicativo { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.endereco": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Aplicativo>>` · Rust: `Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>`

## `buscar_pelo_id_aplicativo` [#buscar_pelo_id_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/{id}" credencial />

Busca um aplicativo pelo id

Exige a permissão de leitura na área `aplicativos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Aplicativo excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_aplicativo } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_aplicativo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Aplicativo [#tipo-aplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Aplicativo } from "termo_core/support";

export interface Aplicativo {
  ativo: boolean;
  atualizado_em: string;
  chave_publica: string;
  cor: string;
  criado_em: string;
  descricao?: string | null;
  endereco: string;
  id: string;
  logo?: string | null;
  nome: string;
  saudacao: string;
  /**
   * Id (slug) do app no TermoAuth, de onde vem a lista. Vazio só nas linhas antigas ainda não ligadas.
   */
  termoauth_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Aplicativo;

pub struct Aplicativo {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chave_publica: String,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub endereco: String,
    pub id: uuid::Uuid,
    pub logo: Option<String>,
    pub nome: String,
    pub saudacao: String,
    /// Id (slug) do app no TermoAuth, de onde vem a lista. Vazio só nas linhas antigas ainda não ligadas.
    pub termoauth_id: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaAplicativo [#tipo-paginaaplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativo } from "termo_core/support";

export interface PaginaAplicativo {
  itens: Array<PaginaAplicativoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAplicativo;

pub struct PaginaAplicativo {
    pub itens: Vec<PaginaAplicativoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoComplete [#tipo-paginaaplicativoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoComplete } from "termo_core/support";

export interface PaginaAplicativoAutoComplete {
  itens: Array<PaginaAplicativoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAplicativoAutoComplete;

pub struct PaginaAplicativoAutoComplete {
    pub itens: Vec<PaginaAplicativoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoCompleteItensItem [#tipo-paginaaplicativoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoCompleteItensItem } from "termo_core/support";

export interface PaginaAplicativoAutoCompleteItensItem {
  endereco: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAplicativoAutoCompleteItensItem;

pub struct PaginaAplicativoAutoCompleteItensItem {
    pub endereco: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaAplicativoItensItem [#tipo-paginaaplicativoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoItensItem } from "termo_core/support";

export interface PaginaAplicativoItensItem {
  ativo: boolean;
  atualizado_em: string;
  chave_publica: string;
  cor: string;
  criado_em: string;
  descricao?: string | null;
  endereco: string;
  id: string;
  logo?: string | null;
  nome: string;
  saudacao: string;
  /**
   * Id (slug) do app no TermoAuth, de onde vem a lista. Vazio só nas linhas antigas ainda não ligadas.
   */
  termoauth_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAplicativoItensItem;

pub struct PaginaAplicativoItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chave_publica: String,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub endereco: String,
    pub id: uuid::Uuid,
    pub logo: Option<String>,
    pub nome: String,
    pub saudacao: String,
    /// Id (slug) do app no TermoAuth, de onde vem a lista. Vazio só nas linhas antigas ainda não ligadas.
    pub termoauth_id: Option<String>,
}
```

</Tab>
</Tabs>


# Auth (/docs/servicos/support/auth)

> 8 funções do TermoSupport para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_auth`](#buscar_paginador_auth) | `GET /auth` | Lista os acessos paginados |
| [`criar_auth`](#criar_auth) | `POST /auth` | Cadastra um acesso |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Busca o acesso de quem está logado |
| [`buscar_auto_complete_auth`](#buscar_auto_complete_auth) | `GET /auth/autocomplete` | Lista básica de acessos para seleção |
| [`buscar_pelo_filtro_auth`](#buscar_pelo_filtro_auth) | `GET /auth/filtro` | Busca acessos por filtro |
| [`buscar_pelo_id_auth`](#buscar_pelo_id_auth) | `GET /auth/{id}` | Busca um acesso pelo id |
| [`atualizar_pelo_id_auth`](#atualizar_pelo_id_auth) | `PATCH /auth/{id}` | Atualiza um acesso pelo id |
| [`deletar_pelo_id_auth`](#deletar_pelo_id_auth) | `DELETE /auth/{id}` | Exclui um acesso pelo id |

## `buscar_paginador_auth` [#buscar_paginador_auth]

<Rota metodo="GET" caminho="/auth" credencial />

Lista os acessos paginados

Exige a permissão de leitura na área `colaboradores`. Lista os acessos não excluídos ordenados pelo perfil e depois pelo e-mail, sempre 50 por página: `tamanho` é ignorado. `pagina` começa em 1 (padrão 1; valores menores viram 1). `total` é a quantidade de acessos não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_auth(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAuth,
) -> Result<tipos::PaginaAuth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_auth(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorAuth { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuth>` · Rust: `Result<tipos::PaginaAuth, ErroAoChamarServico>` · veja [`PaginaAuth`](#tipo-paginaauth).

## `criar_auth` [#criar_auth]

<Rota metodo="POST" caminho="/auth" credencial />

Cadastra um acesso

Exige a permissão `criar` na área `colaboradores`. Cadastra quem pode entrar no TermoSupport, sem perfil de acesso: o perfil é escolhido depois em `PATCH /colaborador/{id}/perfil_acesso`. `email` é obrigatório (até 160 caracteres, formato de e-mail), é gravado em minúsculas e é único entre os acessos não excluídos; para entrar, a pessoa precisa existir no TermoAuth com o mesmo e-mail do domínio @termotubos.com.br. `perfil` só aceita `colaborador`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_auth(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AuthCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_auth(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AuthCriar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_auth(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AuthCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthCriar", typeDescriptionLink: "#tipo-authcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Busca o acesso de quem está logado

Livre para qualquer usuário autenticado com cadastro ativo, mesmo sem nenhuma permissão liberada. Devolve o cadastro de quem chamou, o `colaborador_id` (o colaborador vinculado ao acesso, usado como responsável, autor e destinatário das notificações), o `perfil_acesso` (nome do perfil de acesso do colaborador, nulo quando ainda não tem perfil) e as `permissoes` desse perfil por área (`aplicativos`, `colaboradores`, `projetos` e `tickets`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões e, no primeiro acesso, ganha o cadastro automaticamente. `nome` vem do TermoAuth e, se estiver vazio, repete o e-mail. É a chamada que o painel faz antes de mostrar qualquer tela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## `buscar_auto_complete_auth` [#buscar_auto_complete_auth]

<Rota metodo="GET" caminho="/auth/autocomplete" credencial />

Lista básica de acessos para seleção

Exige a permissão de leitura na área `colaboradores`. Devolve só id, e-mail e perfil, em ordem alfabética do e-mail, sem os excluídos. `busca` procura o trecho no e-mail, sem diferenciar maiúsculas, e `perfil` é exato. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_auth(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAuth,
) -> Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_auth(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteAuth { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthAutoComplete>` · Rust: `Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>` · veja [`PaginaAuthAutoComplete`](#tipo-paginaauthautocomplete).

## `buscar_pelo_filtro_auth` [#buscar_pelo_filtro_auth]

<Rota metodo="GET" caminho="/auth/filtro" credencial />

Busca acessos por filtro

Exige a permissão de leitura na área `colaboradores`. Devolve todos os acessos não excluídos que casam com o filtro, sem paginação, em ordem alfabética do e-mail. `email` procura o trecho no e-mail, sem diferenciar maiúsculas; `perfil` é exato; `ativo` filtra pela situação. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Auth>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_auth(credencial_de_acesso, { email: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAuth,
) -> Result<Vec<tipos::Auth>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_auth(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroAuth { email: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Auth>>` · Rust: `Result<Vec<tipos::Auth>, ErroAoChamarServico>`

## `buscar_pelo_id_auth` [#buscar_pelo_id_auth]

<Rota metodo="GET" caminho="/auth/{id}" credencial />

Busca um acesso pelo id

Exige a permissão de leitura na área `colaboradores` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). `nome` vem do colaborador vinculado, e `vinculado` diz se existe um. Acesso excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `atualizar_pelo_id_auth` [#atualizar_pelo_id_auth]

<Rota metodo="PATCH" caminho="/auth/{id}" credencial />

Atualiza um acesso pelo id

Exige a permissão `editar` na área `colaboradores`. Atualização parcial: só os campos enviados mudam. `email` segue as regras do cadastro (até 160 caracteres, formato de e-mail, único) e `ativo: false` bloqueia a entrada da pessoa no TermoSupport. O acesso de um master do TermoAuth não pode ser alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AuthAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_auth(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AuthAtualizar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_auth(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AuthAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthAtualizar", typeDescriptionLink: "#tipo-authatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `deletar_pelo_id_auth` [#deletar_pelo_id_auth]

<Rota metodo="DELETE" caminho="/auth/{id}" credencial />

Exclui um acesso pelo id

Exige a permissão `deletar` na área `colaboradores`. A exclusão é lógica: o acesso some das leituras e o e-mail fica livre para um novo cadastro, mas o registro não é apagado e não há como restaurá-lo. Só exclui acesso sem colaborador vinculado, e o acesso de um master do TermoAuth não pode ser excluído.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_auth } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/support";

export interface AcessoAtual {
  colaborador_id?: string | null;
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AcessoAtual;

pub struct AcessoAtual {
    pub colaborador_id: Option<uuid::Uuid>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/support";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Auth [#tipo-auth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Auth } from "termo_core/support";

export interface Auth {
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Auth;

pub struct Auth {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### AuthAtualizar [#tipo-authatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthAtualizar } from "termo_core/support";

export interface AuthAtualizar {
  ativo?: boolean | null;
  email?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AuthAtualizar;

pub struct AuthAtualizar {
    pub ativo: Option<bool>,
    pub email: Option<String>,
}
```

</Tab>
</Tabs>

### AuthCriar [#tipo-authcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthCriar } from "termo_core/support";

export interface AuthCriar {
  email: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AuthCriar;

pub struct AuthCriar {
    pub email: String,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuth [#tipo-paginaauth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuth } from "termo_core/support";

export interface PaginaAuth {
  itens: Array<PaginaAuthItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAuth;

pub struct PaginaAuth {
    pub itens: Vec<PaginaAuthItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoComplete [#tipo-paginaauthautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoComplete } from "termo_core/support";

export interface PaginaAuthAutoComplete {
  itens: Array<PaginaAuthAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAuthAutoComplete;

pub struct PaginaAuthAutoComplete {
    pub itens: Vec<PaginaAuthAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteItensItem [#tipo-paginaauthautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteItensItem } from "termo_core/support";

export interface PaginaAuthAutoCompleteItensItem {
  email: string;
  id: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAuthAutoCompleteItensItem;

pub struct PaginaAuthAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthItensItem [#tipo-paginaauthitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthItensItem } from "termo_core/support";

export interface PaginaAuthItensItem {
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaAuthItensItem;

pub struct PaginaAuthItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/support";

export interface Permissoes {
  aplicativos?: Acoes;
  colaboradores?: Acoes;
  projetos?: Acoes;
  tickets?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub projetos: Option<Acoes>,
    pub tickets: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/support/colaborador)

> 5 funções do TermoSupport para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista os colaboradores paginados |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Escolhe o perfil de acesso do colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista os colaboradores paginados

Exige a permissão de leitura na área `colaboradores`. Lista os colaboradores não excluídos em ordem alfabética do nome, sempre 50 por página: `tamanho` é ignorado. `pagina` começa em 1 (padrão 1; valores menores viram 1). `nome`, `setor` e `cargo` procuram o trecho no campo, sem diferenciar maiúsculas, e `ativo` filtra pela situação. `total` é a quantidade de colaboradores não excluídos que casam com esses filtros. Quando quem chama é master do TermoAuth, antes de listar o backend traz do TermoAuth os colaboradores @termotubos.com.br que ainda não existem aqui, já com o perfil de acesso "Acesso inicial" (só leitura em todas as áreas); falha nessa sincronização não impede a lista.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige a permissão de leitura na área `colaboradores`, `projetos` ou `tickets`. Devolve só id, nome e e-mail, em ordem alfabética do nome, sem os excluídos. `somente_ativos=true` deixa de fora quem está inativo no TermoSupport (é o que usam os campos de responsável e membros). `busca` procura o trecho no nome ou no e-mail, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.somente_ativos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige a permissão de leitura na área `colaboradores`. Devolve todos os colaboradores não excluídos que casam com o filtro, sem paginação, em ordem alfabética do nome. `busca` procura o trecho no nome ou no e-mail; `nome`, `email`, `setor` e `cargo` procuram o trecho no campo, sem diferenciar maiúsculas; `ativo` filtra pela situação e `perfil_acesso_id` pelo perfil de acesso. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige a permissão de leitura na área `colaboradores` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). O colaborador é do TermoAuth, que é o único que cria e altera: aqui ele chega pelos eventos do TermoAuth e pela sincronização feita quando um master abre a lista, e só se lê. `email` e `master` vêm do acesso vinculado; `setor`, `cargo` e `funcao` vêm do TermoAuth; `perfil_acesso_id` e `perfil_acesso` (nome) são o perfil de acesso escolhido aqui, nulos quando ainda não há perfil. Colaborador excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Escolhe o perfil de acesso do colaborador

Exige a permissão `editar` na área `colaboradores`. É a única escrita no colaborador: troca o perfil de acesso que define o que a pessoa enxerga. `perfil_acesso_id` nulo tira o perfil, e a pessoa fica sem nenhuma área. O colaborador de um master do TermoAuth tem tudo liberado e não recebe perfil. A troca vale na próxima requisição da pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/support";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/support";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/support";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/support";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/support";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/support";

export interface PaginaColaboradorItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>


# Comentário (/docs/servicos/support/comentario)

> 6 funções do TermoSupport para comentário.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_comentario`](#buscar_paginador_comentario) | `GET /comentario` | Lista os comentários paginados |
| [`criar_comentario`](#criar_comentario) | `POST /comentario` | Comenta numa tarefa ou ticket |
| [`buscar_pelo_filtro_comentario`](#buscar_pelo_filtro_comentario) | `GET /comentario/filtro` | Lista a conversa de uma tarefa ou ticket |
| [`buscar_pelo_id_comentario`](#buscar_pelo_id_comentario) | `GET /comentario/{id}` | Busca um comentário pelo id |
| [`atualizar_pelo_id_comentario`](#atualizar_pelo_id_comentario) | `PATCH /comentario/{id}` | Edita um comentário pelo id |
| [`deletar_pelo_id_comentario`](#deletar_pelo_id_comentario) | `DELETE /comentario/{id}` | Exclui um comentário pelo id |

## `buscar_paginador_comentario` [#buscar_paginador_comentario]

<Rota metodo="GET" caminho="/comentario" credencial />

Lista os comentários paginados

Exige a permissão de leitura na área `projetos` ou `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Do mais novo para o mais antigo, sempre 50 por página: `tamanho` é ignorado. `tarefa_id` e `ticket_id` limitam a uma tarefa ou ticket.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_comentario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorComentario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaComentario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_comentario } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_comentario(credencial_de_acesso, { tarefa_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_comentario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorComentario,
) -> Result<tipos::PaginaComentario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_comentario(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorComentario { tarefa_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tarefa_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ticket_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaComentario>` · Rust: `Result<tipos::PaginaComentario, ErroAoChamarServico>` · veja [`PaginaComentario`](#tipo-paginacomentario).

## `criar_comentario` [#criar_comentario]

<Rota metodo="POST" caminho="/comentario" credencial />

Comenta numa tarefa ou ticket

Exige a permissão `criar` na área `projetos` ou `tickets`. Grava o comentário de quem está logado em uma tarefa (`tarefa_id`) ou um ticket (`ticket_id`), nunca nos dois. `texto` é obrigatório (até 10000 caracteres). `interno` (só no ticket) vira nota que o solicitante não acompanha. `mencionados` são os colaboradores marcados com @, que recebem notificação; o responsável e o criador da tarefa (ou o responsável e o solicitante do ticket) também são avisados. A primeira resposta pública da equipe num ticket novo registra a primeira resposta e o põe em atendimento.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_comentario(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ComentarioCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Comentario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_comentario } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_comentario(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_comentario(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ComentarioCriar,
) -> Result<tipos::Comentario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_comentario(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ComentarioCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ComentarioCriar", typeDescriptionLink: "#tipo-comentariocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Comentario>` · Rust: `Result<tipos::Comentario, ErroAoChamarServico>` · veja [`Comentario`](#tipo-comentario).

## `buscar_pelo_filtro_comentario` [#buscar_pelo_filtro_comentario]

<Rota metodo="GET" caminho="/comentario/filtro" credencial />

Lista a conversa de uma tarefa ou ticket

Exige a permissão de leitura na área `projetos` ou `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve até 1000 comentários do mais antigo para o mais novo. Informe `tarefa_id` ou `ticket_id`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_comentario(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroComentario = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Comentario>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_comentario } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_comentario(credencial_de_acesso, { tarefa_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_comentario(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroComentario,
) -> Result<Vec<tipos::Comentario>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_comentario(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroComentario { tarefa_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tarefa_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ticket_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Comentario>>` · Rust: `Result<Vec<tipos::Comentario>, ErroAoChamarServico>`

## `buscar_pelo_id_comentario` [#buscar_pelo_id_comentario]

<Rota metodo="GET" caminho="/comentario/{id}" credencial />

Busca um comentário pelo id

Exige a permissão de leitura na área `projetos` ou `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Comentário excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_comentario(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Comentario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_comentario } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_comentario(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_comentario(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Comentario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_comentario(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Comentario>` · Rust: `Result<tipos::Comentario, ErroAoChamarServico>` · veja [`Comentario`](#tipo-comentario).

## `atualizar_pelo_id_comentario` [#atualizar_pelo_id_comentario]

<Rota metodo="PATCH" caminho="/comentario/{id}" credencial />

Edita um comentário pelo id

Exige a permissão `editar` na área `projetos` ou `tickets`. Troca o `texto` (obrigatório, até 10000 caracteres). Só quem escreveu edita; o comentário passa a mostrar `editado`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_comentario(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ComentarioAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Comentario>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_comentario } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_comentario(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_comentario(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ComentarioAtualizar,
) -> Result<tipos::Comentario, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_comentario(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ComentarioAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ComentarioAtualizar", typeDescriptionLink: "#tipo-comentarioatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Comentario>` · Rust: `Result<tipos::Comentario, ErroAoChamarServico>` · veja [`Comentario`](#tipo-comentario).

## `deletar_pelo_id_comentario` [#deletar_pelo_id_comentario]

<Rota metodo="DELETE" caminho="/comentario/{id}" credencial />

Exclui um comentário pelo id

Exige a permissão `deletar` na área `projetos` ou `tickets`. Exclusão lógica. Só quem escreveu exclui.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_comentario(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_comentario } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_comentario(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_comentario(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_comentario(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ColaboradorResumo [#tipo-colaboradorresumo]

Quem aparece como dono, membro, responsável, solicitante ou autor nos projetos, tarefas e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorResumo } from "termo_core/support";

export interface ColaboradorResumo {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorResumo;

pub struct ColaboradorResumo {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### Comentario [#tipo-comentario]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Comentario } from "termo_core/support";

export interface Comentario {
  atualizado_em: string;
  autor?: ColaboradorResumo | null;
  autor_nome: string;
  criado_em: string;
  editado: boolean;
  id: string;
  /**
   * Nota interna do ticket: só a equipe vê.
   */
  interno: boolean;
  tarefa_id?: string | null;
  texto: string;
  ticket_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Comentario;

pub struct Comentario {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub autor: Option<ColaboradorResumo>,
    pub autor_nome: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub editado: bool,
    pub id: uuid::Uuid,
    /// Nota interna do ticket: só a equipe vê.
    pub interno: bool,
    pub tarefa_id: Option<uuid::Uuid>,
    pub texto: String,
    pub ticket_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### ComentarioAtualizar [#tipo-comentarioatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ComentarioAtualizar } from "termo_core/support";

export interface ComentarioAtualizar {
  texto: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ComentarioAtualizar;

pub struct ComentarioAtualizar {
    pub texto: String,
}
```

</Tab>
</Tabs>

### ComentarioCriar [#tipo-comentariocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ComentarioCriar } from "termo_core/support";

export interface ComentarioCriar {
  interno?: boolean;
  /**
   * Colaboradores marcados com @ no texto: recebem uma notificação.
   */
  mencionados?: Array<string>;
  tarefa_id?: string | null;
  texto: string;
  ticket_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ComentarioCriar;

pub struct ComentarioCriar {
    pub interno: Option<bool>,
    /// Colaboradores marcados com @ no texto: recebem uma notificação.
    pub mencionados: Option<Vec<uuid::Uuid>>,
    pub tarefa_id: Option<uuid::Uuid>,
    pub texto: String,
    pub ticket_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaComentario [#tipo-paginacomentario]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaComentario } from "termo_core/support";

export interface PaginaComentario {
  itens: Array<PaginaComentarioItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaComentario;

pub struct PaginaComentario {
    pub itens: Vec<PaginaComentarioItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaComentarioItensItem [#tipo-paginacomentarioitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaComentarioItensItem } from "termo_core/support";

export interface PaginaComentarioItensItem {
  atualizado_em: string;
  autor?: ColaboradorResumo | null;
  autor_nome: string;
  criado_em: string;
  editado: boolean;
  id: string;
  /**
   * Nota interna do ticket: só a equipe vê.
   */
  interno: boolean;
  tarefa_id?: string | null;
  texto: string;
  ticket_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaComentarioItensItem;

pub struct PaginaComentarioItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub autor: Option<ColaboradorResumo>,
    pub autor_nome: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub editado: bool,
    pub id: uuid::Uuid,
    /// Nota interna do ticket: só a equipe vê.
    pub interno: bool,
    pub tarefa_id: Option<uuid::Uuid>,
    pub texto: String,
    pub ticket_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/support/configuracao)

> 2 funções do TermoSupport para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao` | Busca a configuração do app |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao` | Atualiza o segredo do app |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Busca a configuração do app

Só um master do TermoAuth. Devolve a situação do segredo do app gerado no TermoAuth, que o TermoSupport usa para falar com os outros serviços da Termotubos. O valor nunca é devolvido: só `configurado` e o final mascarado. `criptografia_disponivel` falso indica que o servidor não consegue ler nem gravar o segredo; nesse caso ele aparece como não configurado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao" credencial />

Atualiza o segredo do app

Só um master do TermoAuth. Grava o segredo do app gerado no TermoAuth, criptografado, e passa a usá-lo na hora, sem deploy. Campo ausente não muda, texto troca (até 2000 caracteres, sem quebra de linha; espaços nas pontas são removidos) e `null` ou texto vazio apaga o segredo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/support";

export interface Configuracao {
  atualizado_em: string;
  atualizado_por?: string | null;
  criptografia_disponivel: boolean;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Configuracao;

pub struct Configuracao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub atualizado_por: Option<String>,
    pub criptografia_disponivel: bool,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/support";

export interface ConfiguracaoAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/support";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Documento (/docs/servicos/support/documento)

> 7 funções do TermoSupport para documento.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_documento`](#buscar_paginador_documento) | `GET /documento` | Lista os documentos paginados |
| [`criar_documento`](#criar_documento) | `POST /documento` | Cadastra um documento de um aplicativo |
| [`buscar_auto_complete_documento`](#buscar_auto_complete_documento) | `GET /documento/autocomplete` | Lista básica de documentos para seleção |
| [`buscar_pelo_filtro_documento`](#buscar_pelo_filtro_documento) | `GET /documento/filtro` | Busca documentos por filtro |
| [`buscar_pelo_id_documento`](#buscar_pelo_id_documento) | `GET /documento/{id}` | Busca um documento pelo id |
| [`atualizar_pelo_id_documento`](#atualizar_pelo_id_documento) | `PATCH /documento/{id}` | Atualiza um documento pelo id |
| [`deletar_pelo_id_documento`](#deletar_pelo_id_documento) | `DELETE /documento/{id}` | Exclui um documento pelo id |

## `buscar_paginador_documento` [#buscar_paginador_documento]

<Rota metodo="GET" caminho="/documento" credencial />

Lista os documentos paginados

Exige a permissão de leitura na área `aplicativos`. Lista os documentos não excluídos em ordem alfabética do nome, sempre 50 por página: `tamanho` é ignorado. `aplicativo_id` limita a um aplicativo. `pagina` começa em 1 (padrão 1; valores menores viram 1). `total` conta os documentos com o mesmo filtro de aplicativo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_documento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorDocumento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDocumento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_documento(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorDocumento,
) -> Result<tipos::PaginaDocumento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_documento(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorDocumento { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDocumento>` · Rust: `Result<tipos::PaginaDocumento, ErroAoChamarServico>` · veja [`PaginaDocumento`](#tipo-paginadocumento).

## `criar_documento` [#criar_documento]

<Rota metodo="POST" caminho="/documento" credencial />

Cadastra um documento de um aplicativo

Exige a permissão `criar` na área `aplicativos`. Cadastra um documento da base de conhecimento de um aplicativo. `aplicativo_id` precisa ser de um aplicativo não excluído. `nome` é obrigatório (até 120 caracteres). `tipo` é `TEXTO`, `TXT`, `MD` ou `PDF`, sem diferenciar maiúsculas (padrão `TEXTO`, gravado em maiúsculas). O conteúdo vem em `conteudo` (texto) ou em `arquivo_base64` (o arquivo em base64, com ou sem o prefixo `data:...;base64,`); quando `arquivo_base64` vem preenchido, `conteudo` é ignorado. Com `tipo` `PDF` o backend extrai o texto do PDF; nos demais tipos o arquivo precisa ser texto UTF-8. O texto final não pode ficar vazio, e `caracteres` é o tamanho dele. O corpo aceita até 8 MiB (um PDF de cerca de 5 MB em base64).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_documento(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.DocumentoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Documento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_documento(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::DocumentoCriar,
) -> Result<tipos::Documento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_documento(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.DocumentoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::DocumentoCriar", typeDescriptionLink: "#tipo-documentocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Documento>` · Rust: `Result<tipos::Documento, ErroAoChamarServico>` · veja [`Documento`](#tipo-documento).

## `buscar_auto_complete_documento` [#buscar_auto_complete_documento]

<Rota metodo="GET" caminho="/documento/autocomplete" credencial />

Lista básica de documentos para seleção

Exige a permissão de leitura na área `aplicativos`. Devolve só id, nome e tipo, em ordem alfabética do nome, sem os excluídos. `aplicativo_id` limita a um aplicativo e `busca` procura o trecho no nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_documento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteDocumento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaDocumentoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_documento(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteDocumento,
) -> Result<tipos::PaginaDocumentoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_documento(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteDocumento { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaDocumentoAutoComplete>` · Rust: `Result<tipos::PaginaDocumentoAutoComplete, ErroAoChamarServico>` · veja [`PaginaDocumentoAutoComplete`](#tipo-paginadocumentoautocomplete).

## `buscar_pelo_filtro_documento` [#buscar_pelo_filtro_documento]

<Rota metodo="GET" caminho="/documento/filtro" credencial />

Busca documentos por filtro

Exige a permissão de leitura na área `aplicativos`. Devolve todos os documentos não excluídos que casam com o filtro, sem paginação, em ordem alfabética do nome, com o texto inteiro. `aplicativo_id` limita a um aplicativo; `nome` e `conteudo` procuram o trecho no campo, sem diferenciar maiúsculas; `tipo` é exato (`TEXTO`, `TXT`, `MD` ou `PDF`, sem diferenciar maiúsculas). Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_documento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroDocumento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Documento>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_documento(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroDocumento,
) -> Result<Vec<tipos::Documento>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_documento(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroDocumento { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.conteudo": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Documento>>` · Rust: `Result<Vec<tipos::Documento>, ErroAoChamarServico>`

## `buscar_pelo_id_documento` [#buscar_pelo_id_documento]

<Rota metodo="GET" caminho="/documento/{id}" credencial />

Busca um documento pelo id

Exige a permissão de leitura na área `aplicativos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve o documento com o texto inteiro em `conteudo`. Documento excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_documento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Documento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_documento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Documento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_documento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Documento>` · Rust: `Result<tipos::Documento, ErroAoChamarServico>` · veja [`Documento`](#tipo-documento).

## `atualizar_pelo_id_documento` [#atualizar_pelo_id_documento]

<Rota metodo="PATCH" caminho="/documento/{id}" credencial />

Atualiza um documento pelo id

Exige a permissão `editar` na área `aplicativos`. Atualização parcial: só os campos enviados mudam; o aplicativo do documento não muda. `nome` não pode ficar vazio (até 120 caracteres) e `tipo` é `TEXTO`, `TXT`, `MD` ou `PDF`. Mandar `conteudo` ou `arquivo_base64` troca o texto, com as mesmas regras do cadastro (o arquivo é lido pelo `tipo` enviado ou, sem ele, pelo tipo atual do documento) e o texto final não pode ficar vazio. O corpo aceita até 8 MiB.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_documento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.DocumentoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Documento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_documento(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::DocumentoAtualizar,
) -> Result<tipos::Documento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_documento(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.DocumentoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::DocumentoAtualizar", typeDescriptionLink: "#tipo-documentoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Documento>` · Rust: `Result<tipos::Documento, ErroAoChamarServico>` · veja [`Documento`](#tipo-documento).

## `deletar_pelo_id_documento` [#deletar_pelo_id_documento]

<Rota metodo="DELETE" caminho="/documento/{id}" credencial />

Exclui um documento pelo id

Exige a permissão `deletar` na área `aplicativos`. A exclusão é lógica: o documento some das leituras, mas o registro não é apagado e não há como restaurá-lo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_documento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_documento } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_documento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_documento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_documento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Documento [#tipo-documento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Documento } from "termo_core/support";

export interface Documento {
  aplicativo_id: string;
  atualizado_em: string;
  caracteres: number;
  conteudo: string;
  criado_em: string;
  id: string;
  nome: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Documento;

pub struct Documento {
    pub aplicativo_id: uuid::Uuid,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub caracteres: i32,
    pub conteudo: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### DocumentoAtualizar [#tipo-documentoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DocumentoAtualizar } from "termo_core/support";

export interface DocumentoAtualizar {
  arquivo_base64?: string | null;
  conteudo?: string | null;
  nome?: string | null;
  tipo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::DocumentoAtualizar;

pub struct DocumentoAtualizar {
    pub arquivo_base64: Option<String>,
    pub conteudo: Option<String>,
    pub nome: Option<String>,
    pub tipo: Option<String>,
}
```

</Tab>
</Tabs>

### DocumentoCriar [#tipo-documentocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { DocumentoCriar } from "termo_core/support";

export interface DocumentoCriar {
  aplicativo_id: string;
  arquivo_base64?: string | null;
  conteudo?: string;
  nome: string;
  tipo?: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::DocumentoCriar;

pub struct DocumentoCriar {
    pub aplicativo_id: uuid::Uuid,
    pub arquivo_base64: Option<String>,
    pub conteudo: Option<String>,
    pub nome: String,
    pub tipo: Option<String>,
}
```

</Tab>
</Tabs>

### PaginaDocumento [#tipo-paginadocumento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDocumento } from "termo_core/support";

export interface PaginaDocumento {
  itens: Array<PaginaDocumentoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaDocumento;

pub struct PaginaDocumento {
    pub itens: Vec<PaginaDocumentoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaDocumentoAutoComplete [#tipo-paginadocumentoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDocumentoAutoComplete } from "termo_core/support";

export interface PaginaDocumentoAutoComplete {
  itens: Array<PaginaDocumentoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaDocumentoAutoComplete;

pub struct PaginaDocumentoAutoComplete {
    pub itens: Vec<PaginaDocumentoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaDocumentoAutoCompleteItensItem [#tipo-paginadocumentoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDocumentoAutoCompleteItensItem } from "termo_core/support";

export interface PaginaDocumentoAutoCompleteItensItem {
  id: string;
  nome: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaDocumentoAutoCompleteItensItem;

pub struct PaginaDocumentoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### PaginaDocumentoItensItem [#tipo-paginadocumentoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaDocumentoItensItem } from "termo_core/support";

export interface PaginaDocumentoItensItem {
  aplicativo_id: string;
  atualizado_em: string;
  caracteres: number;
  conteudo: string;
  criado_em: string;
  id: string;
  nome: string;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaDocumentoItensItem;

pub struct PaginaDocumentoItensItem {
    pub aplicativo_id: uuid::Uuid,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub caracteres: i32,
    pub conteudo: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub tipo: String,
}
```

</Tab>
</Tabs>


# Etiqueta (/docs/servicos/support/etiqueta)

> 7 funções do TermoSupport para etiqueta.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_etiqueta`](#buscar_paginador_etiqueta) | `GET /etiqueta` | Lista as etiquetas paginadas |
| [`criar_etiqueta`](#criar_etiqueta) | `POST /etiqueta` | Cadastra uma etiqueta |
| [`buscar_auto_complete_etiqueta`](#buscar_auto_complete_etiqueta) | `GET /etiqueta/autocomplete` | Lista básica de etiquetas para seleção |
| [`buscar_pelo_filtro_etiqueta`](#buscar_pelo_filtro_etiqueta) | `GET /etiqueta/filtro` | Busca etiquetas por filtro |
| [`buscar_pelo_id_etiqueta`](#buscar_pelo_id_etiqueta) | `GET /etiqueta/{id}` | Busca uma etiqueta pelo id |
| [`atualizar_pelo_id_etiqueta`](#atualizar_pelo_id_etiqueta) | `PATCH /etiqueta/{id}` | Atualiza uma etiqueta pelo id |
| [`deletar_pelo_id_etiqueta`](#deletar_pelo_id_etiqueta) | `DELETE /etiqueta/{id}` | Exclui uma etiqueta pelo id |

## `buscar_paginador_etiqueta` [#buscar_paginador_etiqueta]

<Rota metodo="GET" caminho="/etiqueta" credencial />

Lista as etiquetas paginadas

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Lista em ordem alfabética, sempre 50 por página: `tamanho` é ignorado. `pagina` começa em 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorEtiqueta = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEtiqueta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_etiqueta(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorEtiqueta,
) -> Result<tipos::PaginaEtiqueta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_etiqueta(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorEtiqueta { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEtiqueta>` · Rust: `Result<tipos::PaginaEtiqueta, ErroAoChamarServico>` · veja [`PaginaEtiqueta`](#tipo-paginaetiqueta).

## `criar_etiqueta` [#criar_etiqueta]

<Rota metodo="POST" caminho="/etiqueta" credencial />

Cadastra uma etiqueta

Exige a permissão `criar` na área `projetos`. Cria uma etiqueta para marcar tarefas (Backend, Frontend, Dados...). `nome` é obrigatório (até 40 caracteres) e único sem diferenciar maiúsculas. `cor` segue o formato `#00397c` (padrão `#00397c`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.EtiquetaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Etiqueta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_etiqueta(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::EtiquetaCriar,
) -> Result<tipos::Etiqueta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_etiqueta(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.EtiquetaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EtiquetaCriar", typeDescriptionLink: "#tipo-etiquetacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Etiqueta>` · Rust: `Result<tipos::Etiqueta, ErroAoChamarServico>` · veja [`Etiqueta`](#tipo-etiqueta).

## `buscar_auto_complete_etiqueta` [#buscar_auto_complete_etiqueta]

<Rota metodo="GET" caminho="/etiqueta/autocomplete" credencial />

Lista básica de etiquetas para seleção

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve id, nome e cor, em ordem alfabética. `busca` procura o trecho no nome. `pagina` começa em 1 e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteEtiqueta = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEtiquetaResumo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_etiqueta(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteEtiqueta,
) -> Result<tipos::PaginaEtiquetaResumo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_etiqueta(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteEtiqueta { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEtiquetaResumo>` · Rust: `Result<tipos::PaginaEtiquetaResumo, ErroAoChamarServico>` · veja [`PaginaEtiquetaResumo`](#tipo-paginaetiquetaresumo).

## `buscar_pelo_filtro_etiqueta` [#buscar_pelo_filtro_etiqueta]

<Rota metodo="GET" caminho="/etiqueta/filtro" credencial />

Busca etiquetas por filtro

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve todas as etiquetas não excluídas, em ordem alfabética. `nome` procura o trecho no nome, sem diferenciar maiúsculas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroEtiqueta = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Etiqueta>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_etiqueta(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroEtiqueta,
) -> Result<Vec<tipos::Etiqueta>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_etiqueta(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroEtiqueta { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Etiqueta>>` · Rust: `Result<Vec<tipos::Etiqueta>, ErroAoChamarServico>`

## `buscar_pelo_id_etiqueta` [#buscar_pelo_id_etiqueta]

<Rota metodo="GET" caminho="/etiqueta/{id}" credencial />

Busca uma etiqueta pelo id

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Etiqueta excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Etiqueta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_etiqueta(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Etiqueta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_etiqueta(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Etiqueta>` · Rust: `Result<tipos::Etiqueta, ErroAoChamarServico>` · veja [`Etiqueta`](#tipo-etiqueta).

## `atualizar_pelo_id_etiqueta` [#atualizar_pelo_id_etiqueta]

<Rota metodo="PATCH" caminho="/etiqueta/{id}" credencial />

Atualiza uma etiqueta pelo id

Exige a permissão `editar` na área `projetos`. Atualização parcial de `nome` e `cor`, com as mesmas regras do cadastro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.EtiquetaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Etiqueta>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_etiqueta(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::EtiquetaAtualizar,
) -> Result<tipos::Etiqueta, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_etiqueta(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.EtiquetaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EtiquetaAtualizar", typeDescriptionLink: "#tipo-etiquetaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Etiqueta>` · Rust: `Result<tipos::Etiqueta, ErroAoChamarServico>` · veja [`Etiqueta`](#tipo-etiqueta).

## `deletar_pelo_id_etiqueta` [#deletar_pelo_id_etiqueta]

<Rota metodo="DELETE" caminho="/etiqueta/{id}" credencial />

Exclui uma etiqueta pelo id

Exige a permissão `deletar` na área `projetos`. Exclusão lógica: a etiqueta some das leituras e sai das tarefas que a usavam.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_etiqueta(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_etiqueta } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_etiqueta(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_etiqueta(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_etiqueta(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Etiqueta [#tipo-etiqueta]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Etiqueta } from "termo_core/support";

export interface Etiqueta {
  atualizado_em: string;
  cor: string;
  criado_em: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Etiqueta;

pub struct Etiqueta {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### EtiquetaAtualizar [#tipo-etiquetaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EtiquetaAtualizar } from "termo_core/support";

export interface EtiquetaAtualizar {
  cor?: string | null;
  nome?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::EtiquetaAtualizar;

pub struct EtiquetaAtualizar {
    pub cor: Option<String>,
    pub nome: Option<String>,
}
```

</Tab>
</Tabs>

### EtiquetaCriar [#tipo-etiquetacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EtiquetaCriar } from "termo_core/support";

export interface EtiquetaCriar {
  cor?: string | null;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::EtiquetaCriar;

pub struct EtiquetaCriar {
    pub cor: Option<String>,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaEtiqueta [#tipo-paginaetiqueta]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEtiqueta } from "termo_core/support";

export interface PaginaEtiqueta {
  itens: Array<PaginaEtiquetaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaEtiqueta;

pub struct PaginaEtiqueta {
    pub itens: Vec<PaginaEtiquetaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEtiquetaItensItem [#tipo-paginaetiquetaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEtiquetaItensItem } from "termo_core/support";

export interface PaginaEtiquetaItensItem {
  atualizado_em: string;
  cor: string;
  criado_em: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaEtiquetaItensItem;

pub struct PaginaEtiquetaItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaEtiquetaResumo [#tipo-paginaetiquetaresumo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEtiquetaResumo } from "termo_core/support";

export interface PaginaEtiquetaResumo {
  itens: Array<PaginaEtiquetaResumoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaEtiquetaResumo;

pub struct PaginaEtiquetaResumo {
    pub itens: Vec<PaginaEtiquetaResumoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEtiquetaResumoItensItem [#tipo-paginaetiquetaresumoitensitem]

A etiqueta como aparece dentro da tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEtiquetaResumoItensItem } from "termo_core/support";

export interface PaginaEtiquetaResumoItensItem {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaEtiquetaResumoItensItem;

pub struct PaginaEtiquetaResumoItensItem {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>


# Histórico (/docs/servicos/support/historico)

> 1 função do TermoSupport para histórico.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_filtro_historico`](#buscar_pelo_filtro_historico) | `GET /historico/filtro` | Atividade de uma tarefa ou ticket |

## `buscar_pelo_filtro_historico` [#buscar_pelo_filtro_historico]

<Rota metodo="GET" caminho="/historico/filtro" credencial />

Atividade de uma tarefa ou ticket

Exige a permissão de leitura na área `projetos` ou `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve até 500 linhas de atividade, da mais nova para a mais antiga: criação, mudanças de campo, anexos. O histórico é gravado pelo próprio sistema e não tem cadastro, edição nem exclusão. Informe `tarefa_id` ou `ticket_id`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_historico(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroHistorico = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Historico>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_historico } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_historico(credencial_de_acesso, { tarefa_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_historico(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroHistorico,
) -> Result<Vec<tipos::Historico>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_historico(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroHistorico { tarefa_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tarefa_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ticket_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Historico>>` · Rust: `Result<Vec<tipos::Historico>, ErroAoChamarServico>`

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### ColaboradorResumo [#tipo-colaboradorresumo]

Quem aparece como dono, membro, responsável, solicitante ou autor nos projetos, tarefas e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorResumo } from "termo_core/support";

export interface ColaboradorResumo {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorResumo;

pub struct ColaboradorResumo {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### Historico [#tipo-historico]

Uma linha da atividade de uma tarefa ou ticket, gravada pelo próprio sistema a cada mudança.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Historico } from "termo_core/support";

export interface Historico {
  autor?: ColaboradorResumo | null;
  criado_em: string;
  descricao: string;
  id: string;
  tarefa_id?: string | null;
  ticket_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Historico;

pub struct Historico {
    pub autor: Option<ColaboradorResumo>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub id: uuid::Uuid,
    pub tarefa_id: Option<uuid::Uuid>,
    pub ticket_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>


# TermoSupport (/docs/servicos/support)

> Suporte e gestão de projetos da Termotubos. A API é o painel: cadastro dos aplicativos atendidos e dos documentos da base de conhecimento de cada um (área aplicativos); projetos ligados aos aplicativ…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Suporte e gestão de projetos da Termotubos. A API é o painel: cadastro dos aplicativos atendidos e dos documentos da base de conhecimento de cada um (área `aplicativos`); projetos ligados aos aplicativos, com seções (colunas do quadro), tarefas, subtarefas e etiquetas (área `projetos`); tickets de suporte de cada aplicativo, com SLA (área `tickets`); comentários, anexos e atividade das tarefas e tickets (áreas `projetos` ou `tickets`); a caixa de entrada de notificações de cada colaborador (`/notificacao`, livre); e a administração dos colaboradores, dos acessos e dos perfis de acesso (área `colaboradores`), além do segredo do app gerado no TermoAuth (`/configuracao`, só master do TermoAuth), sempre com o token do usuário logado no TermoAuth. O TermoWebhook entrega os eventos de colaborador do TermoAuth em `POST /webhooks/termowebhook`, e os aplicativos abrem tickets pela chave pública em `POST /publico/ticket`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::support` (feature `support`) |
| Importação TypeScript | `termo_core/support` ou `import { support } from "termo_core"` |
| Funções | 90 |
| Entidades | 17 |
| Versão do contrato | `0.2.5` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51051` |
| `SANDBOX` | `https://sandbox-api-support.termotubos.com.br` |
| `PRODUCTION` | `https://api-support.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Anexo" href="/docs/servicos/support/anexo" description="5 funções" />
  <Card title="Aplicativo" href="/docs/servicos/support/aplicativo" description="4 funções" />
  <Card title="Comentário" href="/docs/servicos/support/comentario" description="6 funções" />
  <Card title="Documento" href="/docs/servicos/support/documento" description="7 funções" />
  <Card title="Etiqueta" href="/docs/servicos/support/etiqueta" description="7 funções" />
  <Card title="Histórico" href="/docs/servicos/support/historico" description="1 função" />
  <Card title="Notificação" href="/docs/servicos/support/notificacao" description="6 funções" />
  <Card title="Projeto" href="/docs/servicos/support/projeto" description="7 funções" />
  <Card title="Seção" href="/docs/servicos/support/secao" description="7 funções" />
  <Card title="Tarefa" href="/docs/servicos/support/tarefa" description="7 funções" />
  <Card title="Ticket" href="/docs/servicos/support/ticket" description="8 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/support/auth" description="8 funções" />
  <Card title="Colaborador" href="/docs/servicos/support/colaborador" description="5 funções" />
  <Card title="Configuração" href="/docs/servicos/support/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/support/perfil_acesso" description="7 funções" />
  <Card title="Teste" href="/docs/servicos/support/test" description="2 funções" />
  <Card title="Webhooks" href="/docs/servicos/support/webhooks" description="1 função" />
</Cards>


# Notificação (/docs/servicos/support/notificacao)

> 6 funções do TermoSupport para notificação.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_notificacao`](#buscar_paginador_notificacao) | `GET /notificacao` | Caixa de entrada paginada |
| [`marcar_todas_notificacao`](#marcar_todas_notificacao) | `PATCH /notificacao` | Marca todas as notificações como lidas |
| [`buscar_pelo_filtro_notificacao`](#buscar_pelo_filtro_notificacao) | `GET /notificacao/filtro` | Busca notificações por filtro |
| [`buscar_pelo_id_notificacao`](#buscar_pelo_id_notificacao) | `GET /notificacao/{id}` | Busca uma notificação pelo id |
| [`atualizar_pelo_id_notificacao`](#atualizar_pelo_id_notificacao) | `PATCH /notificacao/{id}` | Marca uma notificação como lida ou não lida |
| [`deletar_pelo_id_notificacao`](#deletar_pelo_id_notificacao) | `DELETE /notificacao/{id}` | Exclui uma notificação pelo id |

## `buscar_paginador_notificacao` [#buscar_paginador_notificacao]

<Rota metodo="GET" caminho="/notificacao" credencial />

Caixa de entrada paginada

Livre para qualquer usuário autenticado: vale sempre para o colaborador de quem está logado. Lista as notificações da pessoa, da mais nova para a mais antiga, sempre 50 por página: `tamanho` é ignorado. `lida` filtra; `nao_lidas` traz o total ainda não lido (o número do sino), com qualquer filtro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_notificacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorNotificacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaNotificacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_notificacao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_notificacao(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_notificacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorNotificacao,
) -> Result<tipos::PaginaNotificacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_notificacao(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorNotificacao { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.lida": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaNotificacao>` · Rust: `Result<tipos::PaginaNotificacao, ErroAoChamarServico>` · veja [`PaginaNotificacao`](#tipo-paginanotificacao).

## `marcar_todas_notificacao` [#marcar_todas_notificacao]

<Rota metodo="PATCH" caminho="/notificacao" credencial />

Marca todas as notificações como lidas

Livre para qualquer usuário autenticado: vale sempre para o colaborador de quem está logado. Marca de uma vez todas as notificações da pessoa como lidas (ou como não lidas, com `lida: false`). Devolve quantas mudaram em `alteradas`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function marcar_todas_notificacao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.NotificacaoMarcarTodas,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.NotificacoesMarcadas>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { marcar_todas_notificacao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await marcar_todas_notificacao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn marcar_todas_notificacao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::NotificacaoMarcarTodas,
) -> Result<tipos::NotificacoesMarcadas, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::marcar_todas_notificacao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.NotificacaoMarcarTodas", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::NotificacaoMarcarTodas", typeDescriptionLink: "#tipo-notificacaomarcartodas" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.NotificacoesMarcadas>` · Rust: `Result<tipos::NotificacoesMarcadas, ErroAoChamarServico>` · veja [`NotificacoesMarcadas`](#tipo-notificacoesmarcadas).

## `buscar_pelo_filtro_notificacao` [#buscar_pelo_filtro_notificacao]

<Rota metodo="GET" caminho="/notificacao/filtro" credencial />

Busca notificações por filtro

Livre para qualquer usuário autenticado: vale sempre para o colaborador de quem está logado. Devolve até 500 notificações da pessoa, da mais nova para a mais antiga. `lida` filtra lidas ou não lidas e `tipo` é `ATRIBUICAO`, `COMENTARIO`, `MENCAO`, `STATUS`, `PRAZO` ou `TICKET`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_notificacao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroNotificacao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Notificacao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_notificacao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_notificacao(credencial_de_acesso, { lida: true });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_notificacao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroNotificacao,
) -> Result<Vec<tipos::Notificacao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_notificacao(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroNotificacao { lida: Some(true), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.lida": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Notificacao>>` · Rust: `Result<Vec<tipos::Notificacao>, ErroAoChamarServico>`

## `buscar_pelo_id_notificacao` [#buscar_pelo_id_notificacao]

<Rota metodo="GET" caminho="/notificacao/{id}" credencial />

Busca uma notificação pelo id

Livre para qualquer usuário autenticado: vale sempre para o colaborador de quem está logado. Só encontra as notificações da própria pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_notificacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Notificacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_notificacao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_notificacao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_notificacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Notificacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_notificacao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Notificacao>` · Rust: `Result<tipos::Notificacao, ErroAoChamarServico>` · veja [`Notificacao`](#tipo-notificacao).

## `atualizar_pelo_id_notificacao` [#atualizar_pelo_id_notificacao]

<Rota metodo="PATCH" caminho="/notificacao/{id}" credencial />

Marca uma notificação como lida ou não lida

Livre para qualquer usuário autenticado: vale sempre para o colaborador de quem está logado. Muda `lida` de uma notificação da própria pessoa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_notificacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.NotificacaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Notificacao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_notificacao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_notificacao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_notificacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::NotificacaoAtualizar,
) -> Result<tipos::Notificacao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_notificacao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.NotificacaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::NotificacaoAtualizar", typeDescriptionLink: "#tipo-notificacaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Notificacao>` · Rust: `Result<tipos::Notificacao, ErroAoChamarServico>` · veja [`Notificacao`](#tipo-notificacao).

## `deletar_pelo_id_notificacao` [#deletar_pelo_id_notificacao]

<Rota metodo="DELETE" caminho="/notificacao/{id}" credencial />

Exclui uma notificação pelo id

Livre para qualquer usuário autenticado: vale sempre para o colaborador de quem está logado. Tira a notificação da caixa de entrada (exclusão lógica).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_notificacao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_notificacao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_notificacao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_notificacao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_notificacao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Notificacao [#tipo-notificacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Notificacao } from "termo_core/support";

export interface Notificacao {
  criado_em: string;
  descricao?: string | null;
  id: string;
  lida: boolean;
  link: string;
  tarefa_id?: string | null;
  ticket_id?: string | null;
  tipo: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Notificacao;

pub struct Notificacao {
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub lida: bool,
    pub link: String,
    pub tarefa_id: Option<uuid::Uuid>,
    pub ticket_id: Option<uuid::Uuid>,
    pub tipo: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### NotificacaoAtualizar [#tipo-notificacaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotificacaoAtualizar } from "termo_core/support";

export interface NotificacaoAtualizar {
  lida: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::NotificacaoAtualizar;

pub struct NotificacaoAtualizar {
    pub lida: bool,
}
```

</Tab>
</Tabs>

### NotificacaoMarcarTodas [#tipo-notificacaomarcartodas]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotificacaoMarcarTodas } from "termo_core/support";

export interface NotificacaoMarcarTodas {
  lida?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::NotificacaoMarcarTodas;

pub struct NotificacaoMarcarTodas {
    pub lida: Option<bool>,
}
```

</Tab>
</Tabs>

### NotificacoesMarcadas [#tipo-notificacoesmarcadas]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { NotificacoesMarcadas } from "termo_core/support";

export interface NotificacoesMarcadas {
  alteradas: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::NotificacoesMarcadas;

pub struct NotificacoesMarcadas {
    pub alteradas: i64,
}
```

</Tab>
</Tabs>

### PaginaNotificacao [#tipo-paginanotificacao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaNotificacao } from "termo_core/support";

export interface PaginaNotificacao {
  itens: Array<PaginaNotificacaoItensItem>;
  /**
   * Quantas notificações da pessoa ainda não foram lidas (o número do sino).
   */
  nao_lidas: number;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaNotificacao;

pub struct PaginaNotificacao {
    pub itens: Vec<PaginaNotificacaoItensItem>,
    /// Quantas notificações da pessoa ainda não foram lidas (o número do sino).
    pub nao_lidas: i64,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaNotificacaoItensItem [#tipo-paginanotificacaoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaNotificacaoItensItem } from "termo_core/support";

export interface PaginaNotificacaoItensItem {
  criado_em: string;
  descricao?: string | null;
  id: string;
  lida: boolean;
  link: string;
  tarefa_id?: string | null;
  ticket_id?: string | null;
  tipo: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaNotificacaoItensItem;

pub struct PaginaNotificacaoItensItem {
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub lida: bool,
    pub link: String,
    pub tarefa_id: Option<uuid::Uuid>,
    pub ticket_id: Option<uuid::Uuid>,
    pub tipo: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>


# Perfil acesso (/docs/servicos/support/perfil_acesso)

> 7 funções do TermoSupport para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso paginados |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso paginados

Exige a permissão de leitura na área `colaboradores`. Lista os perfis não excluídos em ordem alfabética do nome, sempre 50 por página: `tamanho` é ignorado. `pagina` começa em 1 (padrão 1; valores menores viram 1). `total` é a quantidade de perfis não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcesso>` · Rust: `Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>` · veja [`PaginaPerfilAcesso`](#tipo-paginaperfilacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` na área `colaboradores`. O perfil diz o que quem o recebe enxerga. `nome` é obrigatório (até 80 caracteres) e único entre os perfis não excluídos, sem diferenciar maiúsculas; `descricao` é opcional (até 200 caracteres). `permissoes` tem as áreas `aplicativos` (aplicativos e documentos), `colaboradores` (colaboradores, acessos e perfis de acesso), `projetos` (projetos, seções, tarefas e etiquetas) e `tickets`, cada uma com `ler`, `criar`, `editar` e `deletar`; área ou ação ausente vale `false`, e qualquer ação liberada numa área também libera a leitura dela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige a permissão de leitura na área `colaboradores`. Devolve só id e nome, em ordem alfabética do nome, sem os excluídos. `busca` procura o trecho no nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoComplete`](#tipo-paginaperfilacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige a permissão de leitura na área `colaboradores`. Devolve todos os perfis não excluídos que casam com o filtro, sem paginação, em ordem alfabética do nome. `nome` procura o trecho no nome, sem diferenciar maiúsculas. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige a permissão de leitura na área `colaboradores` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve o perfil com as permissões e `colaboradores`, a quantidade de colaboradores não excluídos que usam o perfil. Perfil excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` na área `colaboradores`. Só os campos enviados mudam; ao menos um de `nome`, `descricao` e `permissoes` é obrigatório. `descricao` vazia apaga a descrição. `permissoes` substitui o conjunto inteiro: área ou ação ausente vale `false`. Vale na próxima requisição de cada colaborador com o perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` na área `colaboradores`. A exclusão é lógica. Perfil que algum colaborador não excluído ainda usa não pode ser excluído: troque o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/support";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcesso [#tipo-paginaperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcesso } from "termo_core/support";

export interface PaginaPerfilAcesso {
  itens: Array<PaginaPerfilAcessoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaPerfilAcesso;

pub struct PaginaPerfilAcesso {
    pub itens: Vec<PaginaPerfilAcessoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoComplete [#tipo-paginaperfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoComplete } from "termo_core/support";

export interface PaginaPerfilAcessoAutoComplete {
  itens: Array<PaginaPerfilAcessoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaPerfilAcessoAutoComplete;

pub struct PaginaPerfilAcessoAutoComplete {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteItensItem [#tipo-paginaperfilacessoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteItensItem } from "termo_core/support";

export interface PaginaPerfilAcessoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaPerfilAcessoAutoCompleteItensItem;

pub struct PaginaPerfilAcessoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoItensItem [#tipo-paginaperfilacessoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoItensItem } from "termo_core/support";

export interface PaginaPerfilAcessoItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaPerfilAcessoItensItem;

pub struct PaginaPerfilAcessoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/support";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/support";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/support";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/support";

export interface Permissoes {
  aplicativos?: Acoes;
  colaboradores?: Acoes;
  projetos?: Acoes;
  tickets?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub projetos: Option<Acoes>,
    pub tickets: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Projeto (/docs/servicos/support/projeto)

> 7 funções do TermoSupport para projeto.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_projeto`](#buscar_paginador_projeto) | `GET /projeto` | Lista os projetos paginados |
| [`criar_projeto`](#criar_projeto) | `POST /projeto` | Cadastra um projeto |
| [`buscar_auto_complete_projeto`](#buscar_auto_complete_projeto) | `GET /projeto/autocomplete` | Lista básica de projetos para seleção |
| [`buscar_pelo_filtro_projeto`](#buscar_pelo_filtro_projeto) | `GET /projeto/filtro` | Busca projetos por filtro |
| [`buscar_pelo_id_projeto`](#buscar_pelo_id_projeto) | `GET /projeto/{id}` | Busca um projeto pelo id |
| [`atualizar_pelo_id_projeto`](#atualizar_pelo_id_projeto) | `PATCH /projeto/{id}` | Atualiza um projeto pelo id |
| [`deletar_pelo_id_projeto`](#deletar_pelo_id_projeto) | `DELETE /projeto/{id}` | Exclui um projeto pelo id |

## `buscar_paginador_projeto` [#buscar_paginador_projeto]

<Rota metodo="GET" caminho="/projeto" credencial />

Lista os projetos paginados

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Lista os projetos do mais recente atualizado para o mais antigo, sempre 50 por página: `tamanho` é ignorado. Aceita os mesmos filtros do `GET /projeto/filtro`. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorProjeto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaProjeto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_projeto(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorProjeto,
) -> Result<tipos::PaginaProjeto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_projeto(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorProjeto { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.membro_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.arquivado": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaProjeto>` · Rust: `Result<tipos::PaginaProjeto, ErroAoChamarServico>` · veja [`PaginaProjeto`](#tipo-paginaprojeto).

## `criar_projeto` [#criar_projeto]

<Rota metodo="POST" caminho="/projeto" credencial />

Cadastra um projeto

Exige a permissão `criar` na área `projetos`. `visibilidade` é `ORGANIZACAO` (padrão: todos com a área `projetos` veem) ou `MEMBROS` (só quem está vinculado ao projeto). Cria o projeto ligado aos aplicativos de `aplicativo_ids`, com os membros de `membro_ids` (o dono e quem criou entram sempre como membros). `nome` é obrigatório (até 120 caracteres); `descricao` vai até 5000; `cor` no formato `#00397c`; `status` é `NO_PRAZO` (padrão), `EM_RISCO`, `ATRASADO`, `PAUSADO` ou `CONCLUIDO`; `dono_id` tem padrão em quem criou; `inicio` não pode passar do `prazo`. `secoes` são os nomes das colunas do quadro, na ordem (padrão "A fazer", "Em andamento" e "Concluído").

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ProjetoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Projeto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_projeto(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ProjetoCriar,
) -> Result<tipos::Projeto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_projeto(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ProjetoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProjetoCriar", typeDescriptionLink: "#tipo-projetocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Projeto>` · Rust: `Result<tipos::Projeto, ErroAoChamarServico>` · veja [`Projeto`](#tipo-projeto).

## `buscar_auto_complete_projeto` [#buscar_auto_complete_projeto]

<Rota metodo="GET" caminho="/projeto/autocomplete" credencial />

Lista básica de projetos para seleção

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve id, nome e cor dos projetos não arquivados, em ordem alfabética. `busca` procura no nome e `aplicativo_id` limita aos projetos do aplicativo. `pagina` começa em 1 e `tamanho` tem padrão 10. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteProjeto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaProjetoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_projeto(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteProjeto,
) -> Result<tipos::PaginaProjetoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_projeto(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteProjeto { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaProjetoAutoComplete>` · Rust: `Result<tipos::PaginaProjetoAutoComplete, ErroAoChamarServico>` · veja [`PaginaProjetoAutoComplete`](#tipo-paginaprojetoautocomplete).

## `buscar_pelo_filtro_projeto` [#buscar_pelo_filtro_projeto]

<Rota metodo="GET" caminho="/projeto/filtro" credencial />

Busca projetos por filtro

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve até 500 projetos em ordem alfabética. `busca` procura no nome e na descrição; `status` é exato; `aplicativo_id` traz os projetos ligados ao aplicativo; `membro_id` os projetos em que o colaborador é dono ou membro; `arquivado` tem padrão `false`. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroProjeto = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Projeto>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_projeto(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroProjeto,
) -> Result<Vec<tipos::Projeto>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_projeto(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroProjeto { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Trecho do nome ou da descrição. · Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.membro_id": { type: "string", required: false, description: "Projetos em que o colaborador é dono ou membro. · Rust: Option<uuid::Uuid>" },
    "parametros.arquivado": { type: "boolean", required: false, description: "Padrão false: os arquivados só aparecem quando pedidos. · Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Projeto>>` · Rust: `Result<Vec<tipos::Projeto>, ErroAoChamarServico>`

## `buscar_pelo_id_projeto` [#buscar_pelo_id_projeto]

<Rota metodo="GET" caminho="/projeto/{id}" credencial />

Busca um projeto pelo id

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve o projeto com dono, aplicativos, membros e a contagem das tarefas principais (total, concluídas e atrasadas). Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Projeto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_projeto(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Projeto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_projeto(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Projeto>` · Rust: `Result<tipos::Projeto, ErroAoChamarServico>` · veja [`Projeto`](#tipo-projeto).

## `atualizar_pelo_id_projeto` [#atualizar_pelo_id_projeto]

<Rota metodo="PATCH" caminho="/projeto/{id}" credencial />

Atualiza um projeto pelo id

Exige a permissão `editar` na área `projetos`. Atualização parcial com as regras do cadastro (inclusive `visibilidade`: `ORGANIZACAO` ou `MEMBROS`). Texto vazio em `descricao` apaga; `null` em `dono_id`, `inicio` ou `prazo` apaga o valor. `aplicativo_ids` e `membro_ids`, quando enviados, substituem a lista inteira (o dono continua membro). `arquivado` tira o projeto das listas. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ProjetoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Projeto>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_projeto(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ProjetoAtualizar,
) -> Result<tipos::Projeto, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_projeto(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ProjetoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ProjetoAtualizar", typeDescriptionLink: "#tipo-projetoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Projeto>` · Rust: `Result<tipos::Projeto, ErroAoChamarServico>` · veja [`Projeto`](#tipo-projeto).

## `deletar_pelo_id_projeto` [#deletar_pelo_id_projeto]

<Rota metodo="DELETE" caminho="/projeto/{id}" credencial />

Exclui um projeto pelo id

Exige a permissão `deletar` na área `projetos`. Exclusão lógica do projeto, das colunas e das tarefas dele. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_projeto(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_projeto } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_projeto(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_projeto(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_projeto(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AplicativoResumo [#tipo-aplicativoresumo]

O aplicativo como aparece dentro dos projetos e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AplicativoResumo } from "termo_core/support";

export interface AplicativoResumo {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AplicativoResumo;

pub struct AplicativoResumo {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### ColaboradorResumo [#tipo-colaboradorresumo]

Quem aparece como dono, membro, responsável, solicitante ou autor nos projetos, tarefas e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorResumo } from "termo_core/support";

export interface ColaboradorResumo {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorResumo;

pub struct ColaboradorResumo {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaProjeto [#tipo-paginaprojeto]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProjeto } from "termo_core/support";

export interface PaginaProjeto {
  itens: Array<PaginaProjetoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaProjeto;

pub struct PaginaProjeto {
    pub itens: Vec<PaginaProjetoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaProjetoAutoComplete [#tipo-paginaprojetoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProjetoAutoComplete } from "termo_core/support";

export interface PaginaProjetoAutoComplete {
  itens: Array<PaginaProjetoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaProjetoAutoComplete;

pub struct PaginaProjetoAutoComplete {
    pub itens: Vec<PaginaProjetoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaProjetoAutoCompleteItensItem [#tipo-paginaprojetoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProjetoAutoCompleteItensItem } from "termo_core/support";

export interface PaginaProjetoAutoCompleteItensItem {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaProjetoAutoCompleteItensItem;

pub struct PaginaProjetoAutoCompleteItensItem {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaProjetoItensItem [#tipo-paginaprojetoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaProjetoItensItem } from "termo_core/support";

export interface PaginaProjetoItensItem {
  aplicativos: Array<AplicativoResumo>;
  arquivado: boolean;
  atualizado_em: string;
  cor: string;
  criado_em: string;
  descricao?: string | null;
  dono?: ColaboradorResumo | null;
  id: string;
  inicio?: string | null;
  membros: Array<ColaboradorResumo>;
  nome: string;
  prazo?: string | null;
  status: string;
  /**
   * Tarefas principais abertas com o prazo já vencido.
   */
  tarefas_atrasadas: number;
  tarefas_concluidas: number;
  /**
   * Tarefas principais (sem contar subtarefas).
   */
  total_tarefas: number;
  /**
   * `ORGANIZACAO` (todos com a área `projetos` veem) ou `MEMBROS` (só o dono e os membros).
   */
  visibilidade: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaProjetoItensItem;

pub struct PaginaProjetoItensItem {
    pub aplicativos: Vec<AplicativoResumo>,
    pub arquivado: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub dono: Option<ColaboradorResumo>,
    pub id: uuid::Uuid,
    pub inicio: Option<chrono::NaiveDate>,
    pub membros: Vec<ColaboradorResumo>,
    pub nome: String,
    pub prazo: Option<chrono::NaiveDate>,
    pub status: String,
    /// Tarefas principais abertas com o prazo já vencido.
    pub tarefas_atrasadas: i64,
    pub tarefas_concluidas: i64,
    /// Tarefas principais (sem contar subtarefas).
    pub total_tarefas: i64,
    /// `ORGANIZACAO` (todos com a área `projetos` veem) ou `MEMBROS` (só o dono e os membros).
    pub visibilidade: String,
}
```

</Tab>
</Tabs>

### Projeto [#tipo-projeto]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Projeto } from "termo_core/support";

export interface Projeto {
  aplicativos: Array<AplicativoResumo>;
  arquivado: boolean;
  atualizado_em: string;
  cor: string;
  criado_em: string;
  descricao?: string | null;
  dono?: ColaboradorResumo | null;
  id: string;
  inicio?: string | null;
  membros: Array<ColaboradorResumo>;
  nome: string;
  prazo?: string | null;
  status: string;
  /**
   * Tarefas principais abertas com o prazo já vencido.
   */
  tarefas_atrasadas: number;
  tarefas_concluidas: number;
  /**
   * Tarefas principais (sem contar subtarefas).
   */
  total_tarefas: number;
  /**
   * `ORGANIZACAO` (todos com a área `projetos` veem) ou `MEMBROS` (só o dono e os membros).
   */
  visibilidade: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Projeto;

pub struct Projeto {
    pub aplicativos: Vec<AplicativoResumo>,
    pub arquivado: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub cor: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub dono: Option<ColaboradorResumo>,
    pub id: uuid::Uuid,
    pub inicio: Option<chrono::NaiveDate>,
    pub membros: Vec<ColaboradorResumo>,
    pub nome: String,
    pub prazo: Option<chrono::NaiveDate>,
    pub status: String,
    /// Tarefas principais abertas com o prazo já vencido.
    pub tarefas_atrasadas: i64,
    pub tarefas_concluidas: i64,
    /// Tarefas principais (sem contar subtarefas).
    pub total_tarefas: i64,
    /// `ORGANIZACAO` (todos com a área `projetos` veem) ou `MEMBROS` (só o dono e os membros).
    pub visibilidade: String,
}
```

</Tab>
</Tabs>

### ProjetoAtualizar [#tipo-projetoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProjetoAtualizar } from "termo_core/support";

export interface ProjetoAtualizar {
  aplicativo_ids?: Array<string> | null;
  arquivado?: boolean | null;
  cor?: string | null;
  descricao?: string | null;
  dono_id?: string | null;
  inicio?: string | null;
  membro_ids?: Array<string> | null;
  nome?: string | null;
  prazo?: string | null;
  status?: string | null;
  visibilidade?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ProjetoAtualizar;

pub struct ProjetoAtualizar {
    pub aplicativo_ids: Option<Vec<uuid::Uuid>>,
    pub arquivado: Option<bool>,
    pub cor: Option<String>,
    pub descricao: Option<String>,
    pub dono_id: Option<uuid::Uuid>,
    pub inicio: Option<chrono::NaiveDate>,
    pub membro_ids: Option<Vec<uuid::Uuid>>,
    pub nome: Option<String>,
    pub prazo: Option<chrono::NaiveDate>,
    pub status: Option<String>,
    pub visibilidade: Option<String>,
}
```

</Tab>
</Tabs>

### ProjetoCriar [#tipo-projetocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ProjetoCriar } from "termo_core/support";

export interface ProjetoCriar {
  aplicativo_ids?: Array<string>;
  cor?: string | null;
  descricao?: string | null;
  dono_id?: string | null;
  inicio?: string | null;
  membro_ids?: Array<string>;
  nome: string;
  prazo?: string | null;
  /**
   * Nomes das colunas do quadro, na ordem. Sem elas o projeto nasce com "A fazer", "Em andamento" e "Concluído".
   */
  secoes?: Array<string> | null;
  status?: string | null;
  /**
   * `ORGANIZACAO` (padrão) ou `MEMBROS`.
   */
  visibilidade?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ProjetoCriar;

pub struct ProjetoCriar {
    pub aplicativo_ids: Option<Vec<uuid::Uuid>>,
    pub cor: Option<String>,
    pub descricao: Option<String>,
    pub dono_id: Option<uuid::Uuid>,
    pub inicio: Option<chrono::NaiveDate>,
    pub membro_ids: Option<Vec<uuid::Uuid>>,
    pub nome: String,
    pub prazo: Option<chrono::NaiveDate>,
    /// Nomes das colunas do quadro, na ordem. Sem elas o projeto nasce com "A fazer", "Em andamento" e "Concluído".
    pub secoes: Option<Vec<String>>,
    pub status: Option<String>,
    /// `ORGANIZACAO` (padrão) ou `MEMBROS`.
    pub visibilidade: Option<String>,
}
```

</Tab>
</Tabs>


# Seção (/docs/servicos/support/secao)

> 7 funções do TermoSupport para seção.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_secao`](#buscar_paginador_secao) | `GET /secao` | Lista as seções paginadas |
| [`criar_secao`](#criar_secao) | `POST /secao` | Cadastra uma seção (coluna do quadro) |
| [`buscar_auto_complete_secao`](#buscar_auto_complete_secao) | `GET /secao/autocomplete` | Lista básica de seções para seleção |
| [`buscar_pelo_filtro_secao`](#buscar_pelo_filtro_secao) | `GET /secao/filtro` | Busca seções por filtro |
| [`buscar_pelo_id_secao`](#buscar_pelo_id_secao) | `GET /secao/{id}` | Busca uma seção pelo id |
| [`atualizar_pelo_id_secao`](#atualizar_pelo_id_secao) | `PATCH /secao/{id}` | Atualiza uma seção pelo id |
| [`deletar_pelo_id_secao`](#deletar_pelo_id_secao) | `DELETE /secao/{id}` | Exclui uma seção pelo id |

## `buscar_paginador_secao` [#buscar_paginador_secao]

<Rota metodo="GET" caminho="/secao" credencial />

Lista as seções paginadas

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Lista na ordem do quadro, sempre 50 por página: `tamanho` é ignorado. `projeto_id` limita a um projeto.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_secao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorSecao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSecao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_secao(credencial_de_acesso, { projeto_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorSecao,
) -> Result<tipos::PaginaSecao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_secao(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorSecao { projeto_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.projeto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSecao>` · Rust: `Result<tipos::PaginaSecao, ErroAoChamarServico>` · veja [`PaginaSecao`](#tipo-paginasecao).

## `criar_secao` [#criar_secao]

<Rota metodo="POST" caminho="/secao" credencial />

Cadastra uma seção (coluna do quadro)

Exige a permissão `criar` na área `projetos`. Cria a coluna no projeto. `nome` é obrigatório (até 80 caracteres). Sem `ordem`, entra no fim do quadro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_secao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.SecaoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Secao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_secao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::SecaoCriar,
) -> Result<tipos::Secao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_secao(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.SecaoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SecaoCriar", typeDescriptionLink: "#tipo-secaocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Secao>` · Rust: `Result<tipos::Secao, ErroAoChamarServico>` · veja [`Secao`](#tipo-secao).

## `buscar_auto_complete_secao` [#buscar_auto_complete_secao]

<Rota metodo="GET" caminho="/secao/autocomplete" credencial />

Lista básica de seções para seleção

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve id e nome em ordem alfabética. `projeto_id` limita a um projeto e `busca` procura no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_secao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteSecao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSecaoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_secao(credencial_de_acesso, { projeto_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteSecao,
) -> Result<tipos::PaginaSecaoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_secao(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteSecao { projeto_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.projeto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSecaoAutoComplete>` · Rust: `Result<tipos::PaginaSecaoAutoComplete, ErroAoChamarServico>` · veja [`PaginaSecaoAutoComplete`](#tipo-paginasecaoautocomplete).

## `buscar_pelo_filtro_secao` [#buscar_pelo_filtro_secao]

<Rota metodo="GET" caminho="/secao/filtro" credencial />

Busca seções por filtro

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve as colunas na ordem do quadro. `projeto_id` limita a um projeto e `nome` procura o trecho no nome.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_secao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroSecao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Secao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_secao(credencial_de_acesso, { projeto_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroSecao,
) -> Result<Vec<tipos::Secao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_secao(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroSecao { projeto_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.projeto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Secao>>` · Rust: `Result<Vec<tipos::Secao>, ErroAoChamarServico>`

## `buscar_pelo_id_secao` [#buscar_pelo_id_secao]

<Rota metodo="GET" caminho="/secao/{id}" credencial />

Busca uma seção pelo id

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Seção excluída não é encontrada.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_secao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Secao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_secao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Secao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_secao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Secao>` · Rust: `Result<tipos::Secao, ErroAoChamarServico>` · veja [`Secao`](#tipo-secao).

## `atualizar_pelo_id_secao` [#atualizar_pelo_id_secao]

<Rota metodo="PATCH" caminho="/secao/{id}" credencial />

Atualiza uma seção pelo id

Exige a permissão `editar` na área `projetos`. Renomeia (`nome`) ou reposiciona (`ordem`, decimal: para pôr entre duas colunas use a média das ordens delas).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_secao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.SecaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Secao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_secao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::SecaoAtualizar,
) -> Result<tipos::Secao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_secao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.SecaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SecaoAtualizar", typeDescriptionLink: "#tipo-secaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Secao>` · Rust: `Result<tipos::Secao, ErroAoChamarServico>` · veja [`Secao`](#tipo-secao).

## `deletar_pelo_id_secao` [#deletar_pelo_id_secao]

<Rota metodo="DELETE" caminho="/secao/{id}" credencial />

Exclui uma seção pelo id

Exige a permissão `deletar` na área `projetos`. Exclusão lógica: as tarefas da coluna vão para a primeira coluna que sobrar no projeto.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_secao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_secao } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_secao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_secao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_secao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaSecao [#tipo-paginasecao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSecao } from "termo_core/support";

export interface PaginaSecao {
  itens: Array<PaginaSecaoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaSecao;

pub struct PaginaSecao {
    pub itens: Vec<PaginaSecaoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSecaoAutoComplete [#tipo-paginasecaoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSecaoAutoComplete } from "termo_core/support";

export interface PaginaSecaoAutoComplete {
  itens: Array<PaginaSecaoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaSecaoAutoComplete;

pub struct PaginaSecaoAutoComplete {
    pub itens: Vec<PaginaSecaoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSecaoAutoCompleteItensItem [#tipo-paginasecaoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSecaoAutoCompleteItensItem } from "termo_core/support";

export interface PaginaSecaoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaSecaoAutoCompleteItensItem;

pub struct PaginaSecaoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaSecaoItensItem [#tipo-paginasecaoitensitem]

Uma coluna do quadro do projeto. A `ordem` é decimal para encaixar uma coluna entre duas sem
renumerar as outras.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSecaoItensItem } from "termo_core/support";

export interface PaginaSecaoItensItem {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  ordem: number;
  projeto_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaSecaoItensItem;

pub struct PaginaSecaoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub ordem: f64,
    pub projeto_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### Secao [#tipo-secao]

Uma coluna do quadro do projeto. A `ordem` é decimal para encaixar uma coluna entre duas sem
renumerar as outras.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Secao } from "termo_core/support";

export interface Secao {
  atualizado_em: string;
  criado_em: string;
  id: string;
  nome: string;
  ordem: number;
  projeto_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Secao;

pub struct Secao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub ordem: f64,
    pub projeto_id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### SecaoAtualizar [#tipo-secaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SecaoAtualizar } from "termo_core/support";

export interface SecaoAtualizar {
  nome?: string | null;
  ordem?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::SecaoAtualizar;

pub struct SecaoAtualizar {
    pub nome: Option<String>,
    pub ordem: Option<f64>,
}
```

</Tab>
</Tabs>

### SecaoCriar [#tipo-secaocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SecaoCriar } from "termo_core/support";

export interface SecaoCriar {
  nome: string;
  /**
   * Sem ordem, a seção entra no fim do quadro.
   */
  ordem?: number | null;
  projeto_id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::SecaoCriar;

pub struct SecaoCriar {
    pub nome: String,
    /// Sem ordem, a seção entra no fim do quadro.
    pub ordem: Option<f64>,
    pub projeto_id: uuid::Uuid,
}
```

</Tab>
</Tabs>


# Tarefa (/docs/servicos/support/tarefa)

> 7 funções do TermoSupport para tarefa.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_tarefa`](#buscar_paginador_tarefa) | `GET /tarefa` | Lista as tarefas paginadas |
| [`criar_tarefa`](#criar_tarefa) | `POST /tarefa` | Cadastra uma tarefa |
| [`buscar_auto_complete_tarefa`](#buscar_auto_complete_tarefa) | `GET /tarefa/autocomplete` | Lista básica de tarefas para seleção |
| [`buscar_pelo_filtro_tarefa`](#buscar_pelo_filtro_tarefa) | `GET /tarefa/filtro` | Busca tarefas por filtro |
| [`buscar_pelo_id_tarefa`](#buscar_pelo_id_tarefa) | `GET /tarefa/{id}` | Busca uma tarefa pelo id |
| [`atualizar_pelo_id_tarefa`](#atualizar_pelo_id_tarefa) | `PATCH /tarefa/{id}` | Atualiza uma tarefa pelo id |
| [`deletar_pelo_id_tarefa`](#deletar_pelo_id_tarefa) | `DELETE /tarefa/{id}` | Exclui uma tarefa pelo id |

## `buscar_paginador_tarefa` [#buscar_paginador_tarefa]

<Rota metodo="GET" caminho="/tarefa" credencial />

Lista as tarefas paginadas

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Lista da mais recente para a mais antiga, sempre 50 por página: `tamanho` é ignorado. Filtra por `projeto_id`, `responsavel_id`, `concluida` e `busca` (título). Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorTarefa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTarefa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_tarefa(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorTarefa,
) -> Result<tipos::PaginaTarefa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_tarefa(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorTarefa { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.projeto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.responsavel_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.concluida": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTarefa>` · Rust: `Result<tipos::PaginaTarefa, ErroAoChamarServico>` · veja [`PaginaTarefa`](#tipo-paginatarefa).

## `criar_tarefa` [#criar_tarefa]

<Rota metodo="POST" caminho="/tarefa" credencial />

Cadastra uma tarefa

Exige a permissão `criar` na área `projetos`. Cria a tarefa no projeto. Sem `secao_id`, entra na primeira coluna; com `tarefa_pai_id`, vira subtarefa (sem coluna; subtarefa não tem subtarefas). `ticket_id` liga a tarefa ao ticket de suporte que a originou. `titulo` é obrigatório (até 300 caracteres); `descricao` até 20000; `prioridade` é `BAIXA`, `MEDIA`, `ALTA` ou `URGENTE`; `estimativa` de 0 a 10000 pontos; `inicio` não pode passar do `prazo`. Quem criou fica como criador, a atividade ganha a linha de criação e o responsável recebe uma notificação. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.TarefaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Tarefa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_tarefa(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::TarefaCriar,
) -> Result<tipos::Tarefa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_tarefa(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.TarefaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TarefaCriar", typeDescriptionLink: "#tipo-tarefacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Tarefa>` · Rust: `Result<tipos::Tarefa, ErroAoChamarServico>` · veja [`Tarefa`](#tipo-tarefa).

## `buscar_auto_complete_tarefa` [#buscar_auto_complete_tarefa]

<Rota metodo="GET" caminho="/tarefa/autocomplete" credencial />

Lista básica de tarefas para seleção

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve id, título e nome do projeto, em ordem alfabética. `busca` procura no título e `projeto_id` limita a um projeto. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteTarefa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTarefaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_tarefa(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteTarefa,
) -> Result<tipos::PaginaTarefaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_tarefa(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteTarefa { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.projeto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTarefaAutoComplete>` · Rust: `Result<tipos::PaginaTarefaAutoComplete, ErroAoChamarServico>` · veja [`PaginaTarefaAutoComplete`](#tipo-paginatarefaautocomplete).

## `buscar_pelo_filtro_tarefa` [#buscar_pelo_filtro_tarefa]

<Rota metodo="GET" caminho="/tarefa/filtro" credencial />

Busca tarefas por filtro

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve até 2000 tarefas. É a leitura do quadro, da lista, do calendário, do cronograma e de "Minhas tarefas". Os filtros se somam: `projeto_id`, `secao_id`, `responsavel_id`, `tarefa_pai_id` (subtarefas de uma tarefa), `ticket_id`, `aplicativo_id` (projetos ligados ao aplicativo), `etiqueta_id`, `somente_principais` (sem subtarefas), `concluida`, `prazo_de`/`prazo_ate` e `busca` (título ou descrição). A ordem é a do quadro (coluna e posição) ou, com `ordenar_por_prazo=true`, o prazo mais próximo primeiro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroTarefa = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Tarefa>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_tarefa(credencial_de_acesso, { projeto_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroTarefa,
) -> Result<Vec<tipos::Tarefa>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_tarefa(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroTarefa { projeto_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.projeto_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.secao_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.responsavel_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tarefa_pai_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ticket_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Tarefas dos projetos ligados a esse aplicativo. · Rust: Option<uuid::Uuid>" },
    "parametros.etiqueta_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.somente_principais": { type: "boolean", required: false, description: "true deixa de fora as subtarefas. · Rust: Option<bool>" },
    "parametros.concluida": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.prazo_de": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.prazo_ate": { type: "string", required: false, description: "Rust: Option<chrono::NaiveDate>" },
    "parametros.busca": { type: "string", required: false, description: "Trecho do título ou da descrição. · Rust: Option<String>" },
    "parametros.ordenar_por_prazo": { type: "boolean", required: false, description: "true ordena pelo prazo (mais próximo primeiro); senão pela coluna e pela ordem do quadro. · Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Tarefa>>` · Rust: `Result<Vec<tipos::Tarefa>, ErroAoChamarServico>`

## `buscar_pelo_id_tarefa` [#buscar_pelo_id_tarefa]

<Rota metodo="GET" caminho="/tarefa/{id}" credencial />

Busca uma tarefa pelo id

Exige a permissão de leitura na área `projetos` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve a tarefa com projeto, coluna, responsável, criador, etiquetas e as contagens de subtarefas, comentários e anexos. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Tarefa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_tarefa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Tarefa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_tarefa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Tarefa>` · Rust: `Result<tipos::Tarefa, ErroAoChamarServico>` · veja [`Tarefa`](#tipo-tarefa).

## `atualizar_pelo_id_tarefa` [#atualizar_pelo_id_tarefa]

<Rota metodo="PATCH" caminho="/tarefa/{id}" credencial />

Atualiza uma tarefa pelo id

Exige a permissão `editar` na área `projetos`. Atualização parcial com as regras do cadastro. Mover no quadro é mandar `secao_id` (coluna do mesmo projeto) e `ordem` (decimal: a média entre os vizinhos). `null` em `responsavel_id`, `inicio`, `prazo`, `prioridade` ou `estimativa` apaga o valor; texto vazio em `descricao` apaga. `concluida` grava ou apaga `concluida_em`. `etiqueta_ids` substitui a lista. Cada mudança entra na atividade da tarefa; o novo responsável e, ao concluir, o criador recebem notificação. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.TarefaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Tarefa>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_tarefa(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::TarefaAtualizar,
) -> Result<tipos::Tarefa, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_tarefa(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.TarefaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TarefaAtualizar", typeDescriptionLink: "#tipo-tarefaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Tarefa>` · Rust: `Result<tipos::Tarefa, ErroAoChamarServico>` · veja [`Tarefa`](#tipo-tarefa).

## `deletar_pelo_id_tarefa` [#deletar_pelo_id_tarefa]

<Rota metodo="DELETE" caminho="/tarefa/{id}" credencial />

Exclui uma tarefa pelo id

Exige a permissão `deletar` na área `projetos`. Exclusão lógica da tarefa e das subtarefas dela. Visibilidade: projeto com `visibilidade` `MEMBROS` só aparece para o dono, os membros e o master do TermoAuth; para os demais ele, as tarefas e as seções dele somem das listas e o acesso pelo id (ou por `projeto_id`/`tarefa_id`/`secao_id` na query) responde `404`. O responsável sempre enxerga a própria tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_tarefa(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_tarefa } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_tarefa(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_tarefa(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_tarefa(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AplicativoResumo [#tipo-aplicativoresumo]

O aplicativo como aparece dentro dos projetos e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AplicativoResumo } from "termo_core/support";

export interface AplicativoResumo {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AplicativoResumo;

pub struct AplicativoResumo {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### ColaboradorResumo [#tipo-colaboradorresumo]

Quem aparece como dono, membro, responsável, solicitante ou autor nos projetos, tarefas e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorResumo } from "termo_core/support";

export interface ColaboradorResumo {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorResumo;

pub struct ColaboradorResumo {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### EtiquetaResumo [#tipo-etiquetaresumo]

A etiqueta como aparece dentro da tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EtiquetaResumo } from "termo_core/support";

export interface EtiquetaResumo {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::EtiquetaResumo;

pub struct EtiquetaResumo {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaTarefa [#tipo-paginatarefa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTarefa } from "termo_core/support";

export interface PaginaTarefa {
  itens: Array<PaginaTarefaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTarefa;

pub struct PaginaTarefa {
    pub itens: Vec<PaginaTarefaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTarefaAutoComplete [#tipo-paginatarefaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTarefaAutoComplete } from "termo_core/support";

export interface PaginaTarefaAutoComplete {
  itens: Array<PaginaTarefaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTarefaAutoComplete;

pub struct PaginaTarefaAutoComplete {
    pub itens: Vec<PaginaTarefaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTarefaAutoCompleteItensItem [#tipo-paginatarefaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTarefaAutoCompleteItensItem } from "termo_core/support";

export interface PaginaTarefaAutoCompleteItensItem {
  id: string;
  projeto_nome: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTarefaAutoCompleteItensItem;

pub struct PaginaTarefaAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub projeto_nome: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### PaginaTarefaItensItem [#tipo-paginatarefaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTarefaItensItem } from "termo_core/support";

export interface PaginaTarefaItensItem {
  anexos_total: number;
  atualizado_em: string;
  comentarios_total: number;
  concluida: boolean;
  concluida_em?: string | null;
  criado_em: string;
  criador?: ColaboradorResumo | null;
  descricao?: string | null;
  /**
   * Esforço em pontos (o número do cartão).
   */
  estimativa?: number | null;
  etiquetas: Array<EtiquetaResumo>;
  id: string;
  inicio?: string | null;
  marco: boolean;
  ordem: number;
  prazo?: string | null;
  prioridade?: string | null;
  projeto_cor: string;
  projeto_id: string;
  projeto_nome: string;
  responsavel?: ColaboradorResumo | null;
  /**
   * Coluna do quadro. Subtarefa não tem coluna.
   */
  secao_id?: string | null;
  secao_nome?: string | null;
  subtarefas_concluidas: number;
  subtarefas_total: number;
  tarefa_pai_id?: string | null;
  tarefa_pai_titulo?: string | null;
  /**
   * Ticket de suporte que deu origem à tarefa.
   */
  ticket_id?: string | null;
  ticket_numero?: number | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTarefaItensItem;

pub struct PaginaTarefaItensItem {
    pub anexos_total: i64,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub comentarios_total: i64,
    pub concluida: bool,
    pub concluida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub criador: Option<ColaboradorResumo>,
    pub descricao: Option<String>,
    /// Esforço em pontos (o número do cartão).
    pub estimativa: Option<i32>,
    pub etiquetas: Vec<EtiquetaResumo>,
    pub id: uuid::Uuid,
    pub inicio: Option<chrono::NaiveDate>,
    pub marco: bool,
    pub ordem: f64,
    pub prazo: Option<chrono::NaiveDate>,
    pub prioridade: Option<String>,
    pub projeto_cor: String,
    pub projeto_id: uuid::Uuid,
    pub projeto_nome: String,
    pub responsavel: Option<ColaboradorResumo>,
    /// Coluna do quadro. Subtarefa não tem coluna.
    pub secao_id: Option<uuid::Uuid>,
    pub secao_nome: Option<String>,
    pub subtarefas_concluidas: i64,
    pub subtarefas_total: i64,
    pub tarefa_pai_id: Option<uuid::Uuid>,
    pub tarefa_pai_titulo: Option<String>,
    /// Ticket de suporte que deu origem à tarefa.
    pub ticket_id: Option<uuid::Uuid>,
    pub ticket_numero: Option<i64>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### Tarefa [#tipo-tarefa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Tarefa } from "termo_core/support";

export interface Tarefa {
  anexos_total: number;
  atualizado_em: string;
  comentarios_total: number;
  concluida: boolean;
  concluida_em?: string | null;
  criado_em: string;
  criador?: ColaboradorResumo | null;
  descricao?: string | null;
  /**
   * Esforço em pontos (o número do cartão).
   */
  estimativa?: number | null;
  etiquetas: Array<EtiquetaResumo>;
  id: string;
  inicio?: string | null;
  marco: boolean;
  ordem: number;
  prazo?: string | null;
  prioridade?: string | null;
  projeto_cor: string;
  projeto_id: string;
  projeto_nome: string;
  responsavel?: ColaboradorResumo | null;
  /**
   * Coluna do quadro. Subtarefa não tem coluna.
   */
  secao_id?: string | null;
  secao_nome?: string | null;
  subtarefas_concluidas: number;
  subtarefas_total: number;
  tarefa_pai_id?: string | null;
  tarefa_pai_titulo?: string | null;
  /**
   * Ticket de suporte que deu origem à tarefa.
   */
  ticket_id?: string | null;
  ticket_numero?: number | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Tarefa;

pub struct Tarefa {
    pub anexos_total: i64,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub comentarios_total: i64,
    pub concluida: bool,
    pub concluida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub criador: Option<ColaboradorResumo>,
    pub descricao: Option<String>,
    /// Esforço em pontos (o número do cartão).
    pub estimativa: Option<i32>,
    pub etiquetas: Vec<EtiquetaResumo>,
    pub id: uuid::Uuid,
    pub inicio: Option<chrono::NaiveDate>,
    pub marco: bool,
    pub ordem: f64,
    pub prazo: Option<chrono::NaiveDate>,
    pub prioridade: Option<String>,
    pub projeto_cor: String,
    pub projeto_id: uuid::Uuid,
    pub projeto_nome: String,
    pub responsavel: Option<ColaboradorResumo>,
    /// Coluna do quadro. Subtarefa não tem coluna.
    pub secao_id: Option<uuid::Uuid>,
    pub secao_nome: Option<String>,
    pub subtarefas_concluidas: i64,
    pub subtarefas_total: i64,
    pub tarefa_pai_id: Option<uuid::Uuid>,
    pub tarefa_pai_titulo: Option<String>,
    /// Ticket de suporte que deu origem à tarefa.
    pub ticket_id: Option<uuid::Uuid>,
    pub ticket_numero: Option<i64>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### TarefaAtualizar [#tipo-tarefaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TarefaAtualizar } from "termo_core/support";

export interface TarefaAtualizar {
  concluida?: boolean | null;
  descricao?: string | null;
  estimativa?: number | null;
  etiqueta_ids?: Array<string> | null;
  inicio?: string | null;
  marco?: boolean | null;
  ordem?: number | null;
  prazo?: string | null;
  prioridade?: string | null;
  responsavel_id?: string | null;
  secao_id?: string | null;
  titulo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TarefaAtualizar;

pub struct TarefaAtualizar {
    pub concluida: Option<bool>,
    pub descricao: Option<String>,
    pub estimativa: Option<i32>,
    pub etiqueta_ids: Option<Vec<uuid::Uuid>>,
    pub inicio: Option<chrono::NaiveDate>,
    pub marco: Option<bool>,
    pub ordem: Option<f64>,
    pub prazo: Option<chrono::NaiveDate>,
    pub prioridade: Option<String>,
    pub responsavel_id: Option<uuid::Uuid>,
    pub secao_id: Option<uuid::Uuid>,
    pub titulo: Option<String>,
}
```

</Tab>
</Tabs>

### TarefaCriar [#tipo-tarefacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TarefaCriar } from "termo_core/support";

export interface TarefaCriar {
  descricao?: string | null;
  estimativa?: number | null;
  etiqueta_ids?: Array<string>;
  inicio?: string | null;
  marco?: boolean;
  /**
   * Sem ordem, a tarefa entra no fim da coluna.
   */
  ordem?: number | null;
  prazo?: string | null;
  prioridade?: string | null;
  projeto_id: string;
  responsavel_id?: string | null;
  /**
   * Sem seção (e sem tarefa pai), a tarefa entra na primeira coluna do projeto.
   */
  secao_id?: string | null;
  /**
   * Preenchido, cria uma subtarefa (sem coluna) dessa tarefa.
   */
  tarefa_pai_id?: string | null;
  ticket_id?: string | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TarefaCriar;

pub struct TarefaCriar {
    pub descricao: Option<String>,
    pub estimativa: Option<i32>,
    pub etiqueta_ids: Option<Vec<uuid::Uuid>>,
    pub inicio: Option<chrono::NaiveDate>,
    pub marco: Option<bool>,
    /// Sem ordem, a tarefa entra no fim da coluna.
    pub ordem: Option<f64>,
    pub prazo: Option<chrono::NaiveDate>,
    pub prioridade: Option<String>,
    pub projeto_id: uuid::Uuid,
    pub responsavel_id: Option<uuid::Uuid>,
    /// Sem seção (e sem tarefa pai), a tarefa entra na primeira coluna do projeto.
    pub secao_id: Option<uuid::Uuid>,
    /// Preenchido, cria uma subtarefa (sem coluna) dessa tarefa.
    pub tarefa_pai_id: Option<uuid::Uuid>,
    pub ticket_id: Option<uuid::Uuid>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### Ticket [#tipo-ticket]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Ticket } from "termo_core/support";

export interface Ticket {
  anexos_total: number;
  aplicativo: AplicativoResumo;
  /**
   * `true` quando o prazo passou antes de o ticket ser resolvido.
   */
  atrasado: boolean;
  atualizado_em: string;
  canal: string;
  comentarios_total: number;
  criado_em: string;
  descricao: string;
  fechado_em?: string | null;
  id: string;
  /**
   * Número sequencial mostrado como #1024.
   */
  numero: number;
  origem_url?: string | null;
  /**
   * Prazo de atendimento (SLA).
   */
  prazo?: string | null;
  primeira_resposta_em?: string | null;
  prioridade: string;
  resolvido_em?: string | null;
  responsavel?: ColaboradorResumo | null;
  solicitante?: ColaboradorResumo | null;
  solicitante_email?: string | null;
  solicitante_nome: string;
  status: string;
  tarefas: Array<TicketTarefa>;
  tipo: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Ticket;

pub struct Ticket {
    pub anexos_total: i64,
    pub aplicativo: AplicativoResumo,
    /// `true` quando o prazo passou antes de o ticket ser resolvido.
    pub atrasado: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub canal: String,
    pub comentarios_total: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub fechado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub id: uuid::Uuid,
    /// Número sequencial mostrado como #1024.
    pub numero: i64,
    pub origem_url: Option<String>,
    /// Prazo de atendimento (SLA).
    pub prazo: Option<chrono::DateTime<chrono::Utc>>,
    pub primeira_resposta_em: Option<chrono::DateTime<chrono::Utc>>,
    pub prioridade: String,
    pub resolvido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub responsavel: Option<ColaboradorResumo>,
    pub solicitante: Option<ColaboradorResumo>,
    pub solicitante_email: Option<String>,
    pub solicitante_nome: String,
    pub status: String,
    pub tarefas: Vec<TicketTarefa>,
    pub tipo: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### TicketTarefa [#tipo-tickettarefa]

Tarefa de projeto criada a partir do ticket.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TicketTarefa } from "termo_core/support";

export interface TicketTarefa {
  concluida: boolean;
  id: string;
  projeto_id: string;
  projeto_nome: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TicketTarefa;

pub struct TicketTarefa {
    pub concluida: bool,
    pub id: uuid::Uuid,
    pub projeto_id: uuid::Uuid,
    pub projeto_nome: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/support/test)

> 2 funções do TermoSupport para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true`, a versão do projeto (`versao`) e a do backend (`versao_backend`) publicadas, no formato semver.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/support";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::support::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` e a versão do backend no ar (semver) sempre que o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/support";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::support::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/support";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/support";

export interface VersaoDoBackend {
  sucesso: boolean;
  versao: string;
  versao_backend: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::VersaoDoBackend;

pub struct VersaoDoBackend {
    pub sucesso: bool,
    pub versao: String,
    pub versao_backend: String,
}
```

</Tab>
</Tabs>


# Ticket (/docs/servicos/support/ticket)

> 8 funções do TermoSupport para ticket.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`criar_pelo_aplicativo_ticket`](#criar_pelo_aplicativo_ticket) | `POST /publico/ticket` | Abre um ticket pelo aplicativo atendido |
| [`buscar_paginador_ticket`](#buscar_paginador_ticket) | `GET /ticket` | Fila de tickets paginada |
| [`criar_ticket`](#criar_ticket) | `POST /ticket` | Abre um ticket de suporte |
| [`buscar_auto_complete_ticket`](#buscar_auto_complete_ticket) | `GET /ticket/autocomplete` | Lista básica de tickets para seleção |
| [`buscar_pelo_filtro_ticket`](#buscar_pelo_filtro_ticket) | `GET /ticket/filtro` | Busca tickets por filtro |
| [`buscar_pelo_id_ticket`](#buscar_pelo_id_ticket) | `GET /ticket/{id}` | Busca um ticket pelo id |
| [`atualizar_pelo_id_ticket`](#atualizar_pelo_id_ticket) | `PATCH /ticket/{id}` | Atualiza um ticket pelo id |
| [`deletar_pelo_id_ticket`](#deletar_pelo_id_ticket) | `DELETE /ticket/{id}` | Exclui um ticket pelo id |

## `criar_pelo_aplicativo_ticket` [#criar_pelo_aplicativo_ticket]

<Rota metodo="POST" caminho="/publico/ticket" />

Abre um ticket pelo aplicativo atendido

Rota pública, sem o token do TermoAuth: o backend do aplicativo se identifica pela chave pública dele (`pk_live_...`, a mesma do cadastro do aplicativo) no cabeçalho `X-Chave-Publica`. Só aplicativo ativo abre ticket. `titulo` (até 200), `descricao` (até 20000) e `solicitante_nome` (até 120) são obrigatórios; `solicitante_email`, `origem_url` (a tela onde o problema aconteceu), `tipo` e `prioridade` seguem as regras do `POST /ticket`. O ticket entra na fila com o canal `APLICATIVO`, o status `NOVO` e o prazo do SLA. Chamada de servidor para servidor: o navegador recebe erro de CORS.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_pelo_aplicativo_ticket(
  parametros: ParametrosDeCriarPeloAplicativoTicket,
  corpo_da_requisicao: tipos.TicketDoAplicativo,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TicketAberto>
```

```ts title="Exemplo"
import { criar_pelo_aplicativo_ticket } from "termo_core/support";

const resposta = await criar_pelo_aplicativo_ticket({ "X-Chave-Publica": "..." }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_pelo_aplicativo_ticket(
    parametros: &ParametrosDeCriarPeloAplicativoTicket,
    corpo_da_requisicao: &tipos::TicketDoAplicativo,
) -> Result<tipos::TicketAberto, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::support::criar_pelo_aplicativo_ticket(
    &termo_core::support::ParametrosDeCriarPeloAplicativoTicket { x_chave_publica },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.X-Chave-Publica": { type: "string", required: true, description: "Chave pública do aplicativo (pk_live_...)\n\nEnviado no cabeçalho X-Chave-Publica. · Rust: String" },
    "corpo_da_requisicao": { type: "tipos.TicketDoAplicativo", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TicketDoAplicativo", typeDescriptionLink: "#tipo-ticketdoaplicativo" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TicketAberto>` · Rust: `Result<tipos::TicketAberto, ErroAoChamarServico>` · veja [`TicketAberto`](#tipo-ticketaberto).

## `buscar_paginador_ticket` [#buscar_paginador_ticket]

<Rota metodo="GET" caminho="/ticket" credencial />

Fila de tickets paginada

Exige a permissão de leitura na área `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). A fila de atendimento: abertos primeiro, do mais urgente e com prazo mais próximo para o menos urgente; depois os resolvidos e fechados. Sempre 50 por página: `tamanho` é ignorado. Aceita os mesmos filtros do `GET /ticket/filtro`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorTicket = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTicket>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_ticket(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorTicket,
) -> Result<tipos::PaginaTicket, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_paginador_ticket(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPaginadorTicket { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.abertos": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.responsavel_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.sem_responsavel": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.solicitante_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.prioridade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.atrasados": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTicket>` · Rust: `Result<tipos::PaginaTicket, ErroAoChamarServico>` · veja [`PaginaTicket`](#tipo-paginaticket).

## `criar_ticket` [#criar_ticket]

<Rota metodo="POST" caminho="/ticket" credencial />

Abre um ticket de suporte

Exige a permissão `criar` na área `tickets`. Abre o ticket para um aplicativo. `titulo` (até 200) e `descricao` (até 20000) são obrigatórios. `tipo` é `BUG`, `DUVIDA` (padrão), `MELHORIA`, `ACESSO` ou `OUTRO`; `prioridade` é `BAIXA`, `MEDIA` (padrão), `ALTA` ou `URGENTE`; `canal` é `PAINEL` (padrão), `APLICATIVO`, `EMAIL`, `WHATSAPP` ou `TELEFONE`. O solicitante é o colaborador de `solicitante_id`, ou alguém de fora por `solicitante_nome` e `solicitante_email`; sem nenhum, é quem abriu. Sem `prazo`, vale o SLA da prioridade (urgente 4 h, alta 24 h, média 72 h, baixa 7 dias). Com `responsavel_id` o ticket já nasce em atendimento e o responsável é notificado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.TicketCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Ticket>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_ticket(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::TicketCriar,
) -> Result<tipos::Ticket, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::criar_ticket(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.TicketCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TicketCriar", typeDescriptionLink: "#tipo-ticketcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Ticket>` · Rust: `Result<tipos::Ticket, ErroAoChamarServico>` · veja [`Ticket`](#tipo-ticket).

## `buscar_auto_complete_ticket` [#buscar_auto_complete_ticket]

<Rota metodo="GET" caminho="/ticket/autocomplete" credencial />

Lista básica de tickets para seleção

Exige a permissão de leitura na área `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve id, número e título, do número maior para o menor. `busca` procura no título ou pelo número; `aplicativo_id` limita a um aplicativo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteTicket = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTicketAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_ticket(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteTicket,
) -> Result<tipos::PaginaTicketAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_auto_complete_ticket(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarAutoCompleteTicket { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTicketAutoComplete>` · Rust: `Result<tipos::PaginaTicketAutoComplete, ErroAoChamarServico>` · veja [`PaginaTicketAutoComplete`](#tipo-paginaticketautocomplete).

## `buscar_pelo_filtro_ticket` [#buscar_pelo_filtro_ticket]

<Rota metodo="GET" caminho="/ticket/filtro" credencial />

Busca tickets por filtro

Exige a permissão de leitura na área `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve até 2000 tickets do mais novo para o mais antigo. Os filtros se somam: `aplicativo_id`, `status`, `abertos` (sem os resolvidos e fechados; `false` só eles), `responsavel_id`, `sem_responsavel`, `solicitante_id`, `prioridade`, `tipo`, `atrasados` e `busca` (título, descrição, solicitante ou número, com ou sem #).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroTicket = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Ticket>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_ticket(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroTicket,
) -> Result<Vec<tipos::Ticket>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_filtro_ticket(
    &credencial_de_acesso,
    &termo_core::support::ParametrosDeBuscarPeloFiltroTicket { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.abertos": { type: "boolean", required: false, description: "true traz só os que não estão resolvidos nem fechados; false, só os resolvidos e fechados. · Rust: Option<bool>" },
    "parametros.responsavel_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.sem_responsavel": { type: "boolean", required: false, description: "true traz só os tickets sem responsável. · Rust: Option<bool>" },
    "parametros.solicitante_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.prioridade": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.atrasados": { type: "boolean", required: false, description: "true traz só os que estouraram o prazo. · Rust: Option<bool>" },
    "parametros.busca": { type: "string", required: false, description: "Trecho do título, da descrição, do solicitante ou o número. · Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Ticket>>` · Rust: `Result<Vec<tipos::Ticket>, ErroAoChamarServico>`

## `buscar_pelo_id_ticket` [#buscar_pelo_id_ticket]

<Rota metodo="GET" caminho="/ticket/{id}" credencial />

Busca um ticket pelo id

Exige a permissão de leitura na área `tickets` (qualquer das ações `ler`, `criar`, `editar` ou `deletar` libera a leitura). Devolve o ticket com aplicativo, solicitante, responsável, prazo (e se está atrasado), as tarefas de projeto criadas a partir dele e as contagens de comentários e anexos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Ticket>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_ticket(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Ticket, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::buscar_pelo_id_ticket(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Ticket>` · Rust: `Result<tipos::Ticket, ErroAoChamarServico>` · veja [`Ticket`](#tipo-ticket).

## `atualizar_pelo_id_ticket` [#atualizar_pelo_id_ticket]

<Rota metodo="PATCH" caminho="/ticket/{id}" credencial />

Atualiza um ticket pelo id

Exige a permissão `editar` na área `tickets`. Atualização parcial com as regras da abertura, mais `status` (`NOVO`, `EM_ATENDIMENTO`, `AGUARDANDO`, `RESOLVIDO`, `FECHADO`). Resolver ou fechar grava a data; reabrir apaga. Sair de `NOVO` conta como primeira resposta. Trocar a `prioridade` sem mandar `prazo` refaz o prazo pelo SLA a partir da abertura. `null` em `responsavel_id`, `prazo` ou `solicitante_email` apaga o valor. Cada mudança entra na atividade; o novo responsável e o solicitante (na troca de status) são notificados.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.TicketAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Ticket>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_ticket(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::TicketAtualizar,
) -> Result<tipos::Ticket, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::support::atualizar_pelo_id_ticket(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.TicketAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TicketAtualizar", typeDescriptionLink: "#tipo-ticketatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Ticket>` · Rust: `Result<tipos::Ticket, ErroAoChamarServico>` · veja [`Ticket`](#tipo-ticket).

## `deletar_pelo_id_ticket` [#deletar_pelo_id_ticket]

<Rota metodo="DELETE" caminho="/ticket/{id}" credencial />

Exclui um ticket pelo id

Exige a permissão `deletar` na área `tickets`. Exclusão lógica. As tarefas criadas a partir do ticket continuam nos projetos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_ticket(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_ticket } from "termo_core/support";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_ticket(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_ticket(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::support::deletar_pelo_id_ticket(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AplicativoResumo [#tipo-aplicativoresumo]

O aplicativo como aparece dentro dos projetos e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AplicativoResumo } from "termo_core/support";

export interface AplicativoResumo {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::AplicativoResumo;

pub struct AplicativoResumo {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### ColaboradorResumo [#tipo-colaboradorresumo]

Quem aparece como dono, membro, responsável, solicitante ou autor nos projetos, tarefas e tickets.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorResumo } from "termo_core/support";

export interface ColaboradorResumo {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::ColaboradorResumo;

pub struct ColaboradorResumo {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### EtiquetaResumo [#tipo-etiquetaresumo]

A etiqueta como aparece dentro da tarefa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EtiquetaResumo } from "termo_core/support";

export interface EtiquetaResumo {
  cor: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::EtiquetaResumo;

pub struct EtiquetaResumo {
    pub cor: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaTicket [#tipo-paginaticket]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTicket } from "termo_core/support";

export interface PaginaTicket {
  itens: Array<PaginaTicketItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTicket;

pub struct PaginaTicket {
    pub itens: Vec<PaginaTicketItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTicketAutoComplete [#tipo-paginaticketautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTicketAutoComplete } from "termo_core/support";

export interface PaginaTicketAutoComplete {
  itens: Array<PaginaTicketAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTicketAutoComplete;

pub struct PaginaTicketAutoComplete {
    pub itens: Vec<PaginaTicketAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTicketAutoCompleteItensItem [#tipo-paginaticketautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTicketAutoCompleteItensItem } from "termo_core/support";

export interface PaginaTicketAutoCompleteItensItem {
  id: string;
  numero: number;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTicketAutoCompleteItensItem;

pub struct PaginaTicketAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub numero: i64,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### PaginaTicketItensItem [#tipo-paginaticketitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTicketItensItem } from "termo_core/support";

export interface PaginaTicketItensItem {
  anexos_total: number;
  aplicativo: AplicativoResumo;
  /**
   * `true` quando o prazo passou antes de o ticket ser resolvido.
   */
  atrasado: boolean;
  atualizado_em: string;
  canal: string;
  comentarios_total: number;
  criado_em: string;
  descricao: string;
  fechado_em?: string | null;
  id: string;
  /**
   * Número sequencial mostrado como #1024.
   */
  numero: number;
  origem_url?: string | null;
  /**
   * Prazo de atendimento (SLA).
   */
  prazo?: string | null;
  primeira_resposta_em?: string | null;
  prioridade: string;
  resolvido_em?: string | null;
  responsavel?: ColaboradorResumo | null;
  solicitante?: ColaboradorResumo | null;
  solicitante_email?: string | null;
  solicitante_nome: string;
  status: string;
  tarefas: Array<TicketTarefa>;
  tipo: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::PaginaTicketItensItem;

pub struct PaginaTicketItensItem {
    pub anexos_total: i64,
    pub aplicativo: AplicativoResumo,
    /// `true` quando o prazo passou antes de o ticket ser resolvido.
    pub atrasado: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub canal: String,
    pub comentarios_total: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub fechado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub id: uuid::Uuid,
    /// Número sequencial mostrado como #1024.
    pub numero: i64,
    pub origem_url: Option<String>,
    /// Prazo de atendimento (SLA).
    pub prazo: Option<chrono::DateTime<chrono::Utc>>,
    pub primeira_resposta_em: Option<chrono::DateTime<chrono::Utc>>,
    pub prioridade: String,
    pub resolvido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub responsavel: Option<ColaboradorResumo>,
    pub solicitante: Option<ColaboradorResumo>,
    pub solicitante_email: Option<String>,
    pub solicitante_nome: String,
    pub status: String,
    pub tarefas: Vec<TicketTarefa>,
    pub tipo: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### Tarefa [#tipo-tarefa]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Tarefa } from "termo_core/support";

export interface Tarefa {
  anexos_total: number;
  atualizado_em: string;
  comentarios_total: number;
  concluida: boolean;
  concluida_em?: string | null;
  criado_em: string;
  criador?: ColaboradorResumo | null;
  descricao?: string | null;
  /**
   * Esforço em pontos (o número do cartão).
   */
  estimativa?: number | null;
  etiquetas: Array<EtiquetaResumo>;
  id: string;
  inicio?: string | null;
  marco: boolean;
  ordem: number;
  prazo?: string | null;
  prioridade?: string | null;
  projeto_cor: string;
  projeto_id: string;
  projeto_nome: string;
  responsavel?: ColaboradorResumo | null;
  /**
   * Coluna do quadro. Subtarefa não tem coluna.
   */
  secao_id?: string | null;
  secao_nome?: string | null;
  subtarefas_concluidas: number;
  subtarefas_total: number;
  tarefa_pai_id?: string | null;
  tarefa_pai_titulo?: string | null;
  /**
   * Ticket de suporte que deu origem à tarefa.
   */
  ticket_id?: string | null;
  ticket_numero?: number | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Tarefa;

pub struct Tarefa {
    pub anexos_total: i64,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub comentarios_total: i64,
    pub concluida: bool,
    pub concluida_em: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub criador: Option<ColaboradorResumo>,
    pub descricao: Option<String>,
    /// Esforço em pontos (o número do cartão).
    pub estimativa: Option<i32>,
    pub etiquetas: Vec<EtiquetaResumo>,
    pub id: uuid::Uuid,
    pub inicio: Option<chrono::NaiveDate>,
    pub marco: bool,
    pub ordem: f64,
    pub prazo: Option<chrono::NaiveDate>,
    pub prioridade: Option<String>,
    pub projeto_cor: String,
    pub projeto_id: uuid::Uuid,
    pub projeto_nome: String,
    pub responsavel: Option<ColaboradorResumo>,
    /// Coluna do quadro. Subtarefa não tem coluna.
    pub secao_id: Option<uuid::Uuid>,
    pub secao_nome: Option<String>,
    pub subtarefas_concluidas: i64,
    pub subtarefas_total: i64,
    pub tarefa_pai_id: Option<uuid::Uuid>,
    pub tarefa_pai_titulo: Option<String>,
    /// Ticket de suporte que deu origem à tarefa.
    pub ticket_id: Option<uuid::Uuid>,
    pub ticket_numero: Option<i64>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### Ticket [#tipo-ticket]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Ticket } from "termo_core/support";

export interface Ticket {
  anexos_total: number;
  aplicativo: AplicativoResumo;
  /**
   * `true` quando o prazo passou antes de o ticket ser resolvido.
   */
  atrasado: boolean;
  atualizado_em: string;
  canal: string;
  comentarios_total: number;
  criado_em: string;
  descricao: string;
  fechado_em?: string | null;
  id: string;
  /**
   * Número sequencial mostrado como #1024.
   */
  numero: number;
  origem_url?: string | null;
  /**
   * Prazo de atendimento (SLA).
   */
  prazo?: string | null;
  primeira_resposta_em?: string | null;
  prioridade: string;
  resolvido_em?: string | null;
  responsavel?: ColaboradorResumo | null;
  solicitante?: ColaboradorResumo | null;
  solicitante_email?: string | null;
  solicitante_nome: string;
  status: string;
  tarefas: Array<TicketTarefa>;
  tipo: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::Ticket;

pub struct Ticket {
    pub anexos_total: i64,
    pub aplicativo: AplicativoResumo,
    /// `true` quando o prazo passou antes de o ticket ser resolvido.
    pub atrasado: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub canal: String,
    pub comentarios_total: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub fechado_em: Option<chrono::DateTime<chrono::Utc>>,
    pub id: uuid::Uuid,
    /// Número sequencial mostrado como #1024.
    pub numero: i64,
    pub origem_url: Option<String>,
    /// Prazo de atendimento (SLA).
    pub prazo: Option<chrono::DateTime<chrono::Utc>>,
    pub primeira_resposta_em: Option<chrono::DateTime<chrono::Utc>>,
    pub prioridade: String,
    pub resolvido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub responsavel: Option<ColaboradorResumo>,
    pub solicitante: Option<ColaboradorResumo>,
    pub solicitante_email: Option<String>,
    pub solicitante_nome: String,
    pub status: String,
    pub tarefas: Vec<TicketTarefa>,
    pub tipo: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### TicketAberto [#tipo-ticketaberto]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TicketAberto } from "termo_core/support";

export interface TicketAberto {
  id: string;
  numero: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TicketAberto;

pub struct TicketAberto {
    pub id: uuid::Uuid,
    pub numero: i64,
}
```

</Tab>
</Tabs>

### TicketAtualizar [#tipo-ticketatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TicketAtualizar } from "termo_core/support";

export interface TicketAtualizar {
  aplicativo_id?: string | null;
  canal?: string | null;
  descricao?: string | null;
  prazo?: string | null;
  prioridade?: string | null;
  responsavel_id?: string | null;
  solicitante_email?: string | null;
  solicitante_nome?: string | null;
  status?: string | null;
  tipo?: string | null;
  titulo?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TicketAtualizar;

pub struct TicketAtualizar {
    pub aplicativo_id: Option<uuid::Uuid>,
    pub canal: Option<String>,
    pub descricao: Option<String>,
    pub prazo: Option<chrono::DateTime<chrono::Utc>>,
    pub prioridade: Option<String>,
    pub responsavel_id: Option<uuid::Uuid>,
    pub solicitante_email: Option<String>,
    pub solicitante_nome: Option<String>,
    pub status: Option<String>,
    pub tipo: Option<String>,
    pub titulo: Option<String>,
}
```

</Tab>
</Tabs>

### TicketCriar [#tipo-ticketcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TicketCriar } from "termo_core/support";

export interface TicketCriar {
  aplicativo_id: string;
  canal?: string | null;
  descricao: string;
  origem_url?: string | null;
  /**
   * Sem prazo, vale o SLA da prioridade.
   */
  prazo?: string | null;
  prioridade?: string | null;
  responsavel_id?: string | null;
  solicitante_email?: string | null;
  /**
   * Sem solicitante nem nome, quem abriu o ticket no painel é o solicitante.
   */
  solicitante_id?: string | null;
  solicitante_nome?: string | null;
  tipo?: string | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TicketCriar;

pub struct TicketCriar {
    pub aplicativo_id: uuid::Uuid,
    pub canal: Option<String>,
    pub descricao: String,
    pub origem_url: Option<String>,
    /// Sem prazo, vale o SLA da prioridade.
    pub prazo: Option<chrono::DateTime<chrono::Utc>>,
    pub prioridade: Option<String>,
    pub responsavel_id: Option<uuid::Uuid>,
    pub solicitante_email: Option<String>,
    /// Sem solicitante nem nome, quem abriu o ticket no painel é o solicitante.
    pub solicitante_id: Option<uuid::Uuid>,
    pub solicitante_nome: Option<String>,
    pub tipo: Option<String>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### TicketDoAplicativo [#tipo-ticketdoaplicativo]

O que o aplicativo manda para abrir um ticket pela chave pública.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TicketDoAplicativo } from "termo_core/support";

export interface TicketDoAplicativo {
  descricao: string;
  origem_url?: string | null;
  prioridade?: string | null;
  solicitante_email?: string | null;
  solicitante_nome: string;
  tipo?: string | null;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TicketDoAplicativo;

pub struct TicketDoAplicativo {
    pub descricao: String,
    pub origem_url: Option<String>,
    pub prioridade: Option<String>,
    pub solicitante_email: Option<String>,
    pub solicitante_nome: String,
    pub tipo: Option<String>,
    pub titulo: String,
}
```

</Tab>
</Tabs>

### TicketTarefa [#tipo-tickettarefa]

Tarefa de projeto criada a partir do ticket.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TicketTarefa } from "termo_core/support";

export interface TicketTarefa {
  concluida: boolean;
  id: string;
  projeto_id: string;
  projeto_nome: string;
  titulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::TicketTarefa;

pub struct TicketTarefa {
    pub concluida: bool,
    pub id: uuid::Uuid,
    pub projeto_id: uuid::Uuid,
    pub projeto_nome: String,
    pub titulo: String,
}
```

</Tab>
</Tabs>


# Webhooks (/docs/servicos/support/webhooks)

> 1 função do TermoSupport para webhooks.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as support from "termo_core/support";
// ou: import { support } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["support"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`receber_evento_termo_webhook_webhooks`](#receber_evento_termo_webhook_webhooks) | `POST /webhooks/termowebhook` | Recebe uma entrega de evento do TermoWebhook |

## `receber_evento_termo_webhook_webhooks` [#receber_evento_termo_webhook_webhooks]

<Rota metodo="POST" caminho="/webhooks/termowebhook" />

Recebe uma entrega de evento do TermoWebhook

Pública, sem token do usuário: só o TermoWebhook, o hub de eventos da Termotubos, chama esta rota, para entregar os eventos que o TermoSupport assina. Não é para ser chamada por pessoas nem por IAs.

**Assinatura.** Cada entrega vem assinada com a chave Ed25519 do hub sobre `<data>.<id do aplicativo assinante>.<corpo>`, com a data em `X-TermoWebhook-Data` (horário Unix em segundos, tolerância de 5 minutos), o id da chave em `X-TermoWebhook-Chave` e `X-TermoWebhook-Assinatura: ed25519=<base64url>`. A assinatura é conferida com as chaves públicas do hub.

**Eventos tratados.** `colaborador.criado` e `colaborador.atualizado`, versões 1 e 2, publicados pelo TermoAuth: criam ou atualizam o colaborador e o acesso dele (a versão 2 traz também setor, cargo e função). Evento repetido ou mais antigo que o último aplicado não muda nada. Tipo desconhecido é aceito com `200` e ignorado.

**Resposta.** Sem corpo. Qualquer resposta fora de `2xx` faz o hub reenviar a entrega mais tarde.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_termo_webhook_webhooks(
  parametros: ParametrosDeReceberEventoTermoWebhookWebhooks,
  corpo_da_requisicao: tipos.EntregaDoEvento,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { receber_evento_termo_webhook_webhooks } from "termo_core/support";

await receber_evento_termo_webhook_webhooks({ "X-TermoWebhook-Data": 1, "X-TermoWebhook-Chave": "...", "X-TermoWebhook-Assinatura": "..." }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_termo_webhook_webhooks(
    parametros: &ParametrosDeReceberEventoTermoWebhookWebhooks,
    corpo_da_requisicao: &tipos::EntregaDoEvento,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::support::receber_evento_termo_webhook_webhooks(
    &termo_core::support::ParametrosDeReceberEventoTermoWebhookWebhooks { x_termo_webhook_data, x_termo_webhook_chave, x_termo_webhook_assinatura },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.X-TermoWebhook-Data": { type: "number", required: true, description: "Horário Unix em segundos usado na assinatura; tolerância de 5 minutos\n\nEnviado no cabeçalho X-TermoWebhook-Data. · Rust: i64" },
    "parametros.X-TermoWebhook-Chave": { type: "string", required: true, description: "Id da chave pública do hub que assinou a entrega\n\nEnviado no cabeçalho X-TermoWebhook-Chave. · Rust: String" },
    "parametros.X-TermoWebhook-Assinatura": { type: "string", required: true, description: "ed25519=<base64url> da assinatura de <data>.<id do aplicativo assinante>.<corpo>\n\nEnviado no cabeçalho X-TermoWebhook-Assinatura. · Rust: String" },
    "corpo_da_requisicao": { type: "tipos.EntregaDoEvento", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EntregaDoEvento", typeDescriptionLink: "#tipo-entregadoevento" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EntregaDoEvento [#tipo-entregadoevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaDoEvento } from "termo_core/support";

export interface EntregaDoEvento {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  publicador: string;
  recebido_em: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::support::EntregaDoEvento;

pub struct EntregaDoEvento {
    pub dados: serde_json::Map<String, serde_json::Value>,
    pub entidade_id: String,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub publicador: String,
    pub recebido_em: chrono::DateTime<chrono::Utc>,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>


# Aplicativo (/docs/servicos/tracing/aplicativo)

> 7 funções do TermoTracing para aplicativo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_aplicativo`](#buscar_paginador_aplicativo) | `GET /aplicativo` | Lista os aplicativos paginados |
| [`criar_aplicativo`](#criar_aplicativo) | `POST /aplicativo` | Cadastra um aplicativo |
| [`buscar_auto_complete_aplicativo`](#buscar_auto_complete_aplicativo) | `GET /aplicativo/autocomplete` | Lista básica de aplicativos para seleção |
| [`buscar_pelo_filtro_aplicativo`](#buscar_pelo_filtro_aplicativo) | `GET /aplicativo/filtro` | Busca aplicativos por filtro |
| [`buscar_pelo_id_aplicativo`](#buscar_pelo_id_aplicativo) | `GET /aplicativo/{id}` | Busca um aplicativo pelo id |
| [`atualizar_pelo_id_aplicativo`](#atualizar_pelo_id_aplicativo) | `PATCH /aplicativo/{id}` | Atualiza um aplicativo pelo id |
| [`deletar_pelo_id_aplicativo`](#deletar_pelo_id_aplicativo) | `DELETE /aplicativo/{id}` | Exclui um aplicativo pelo id |

## `buscar_paginador_aplicativo` [#buscar_paginador_aplicativo]

<Rota metodo="GET" caminho="/aplicativo" credencial />

Lista os aplicativos paginados

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Lista os aplicativos não excluídos da conta em ordem alfabética do nome. `pagina` começa em 1 (padrão 1; menor que 1 vira 1). A página tem sempre 50 itens: o parâmetro `tamanho` é aceito, mas ignorado. A resposta traz `itens`, `total` (quantidade de registros que casam com os filtros), `pagina` e `tamanho` (50). Parâmetros de consulta, todos opcionais: `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: aceito, mas ignorado: a página tem sempre 50 itens.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_aplicativo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAplicativo,
) -> Result<tipos::PaginaAplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_aplicativo(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorAplicativo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativo>` · Rust: `Result<tipos::PaginaAplicativo, ErroAoChamarServico>` · veja [`PaginaAplicativo`](#tipo-paginaaplicativo).

## `criar_aplicativo` [#criar_aplicativo]

<Rota metodo="POST" caminho="/aplicativo" credencial />

Cadastra um aplicativo

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Cadastra um site ou sistema que vai enviar eventos ao TermoTracing. `nome` é obrigatório. `dominios` precisa ter ao menos um domínio válido (host com ponto, `localhost` ou curinga `*.dominio.com`, porta opcional); `https://`, caminho e ponto final são removidos. `franquia_mensal` (eventos por ciclo mensal) tem padrão 100000 e precisa ser maior que zero. `comportamento_ao_estourar` aceita `COBRAR_EXCEDENTE` (padrão) ou `PARAR_INGESTAO`. O backend gera a `chave` pública (prefixo `pk_live_`) que o script do site usa na ingestão; ela não é segredo, porque a ingestão só aceita os domínios cadastrados. Campos do corpo: `nome`: nome do aplicativo (obrigatório, não pode ficar vazio); `dominios`: domínios autorizados a enviar eventos; precisa de ao menos um válido (host com ponto, `localhost` ou `*.dominio.com`, porta opcional). `https://`, caminho e ponto final são removidos; `franquia_mensal`: eventos incluídos por ciclo mensal, maior que zero (padrão 100000); `comportamento_ao_estourar`: `COBRAR_EXCEDENTE` (padrão) segue recebendo e conta o excedente; `PARAR_INGESTAO` recusa os lotes depois da franquia.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AplicativoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_aplicativo(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AplicativoCriar,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::criar_aplicativo(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AplicativoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AplicativoCriar", typeDescriptionLink: "#tipo-aplicativocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## `buscar_auto_complete_aplicativo` [#buscar_auto_complete_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/autocomplete" credencial />

Lista básica de aplicativos para seleção

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve só id, nome e chave dos aplicativos não excluídos da conta, em ordem alfabética do nome. `busca` procura o trecho no nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`. Parâmetros de consulta, todos opcionais: `busca`: trecho do nome, sem diferenciar maiúsculas (opcional); `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: itens por página (padrão 10, sem máximo; menor que 1 vira 1).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_aplicativo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAplicativo,
) -> Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_aplicativo(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteAplicativo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativoAutoComplete>` · Rust: `Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>` · veja [`PaginaAplicativoAutoComplete`](#tipo-paginaaplicativoautocomplete).

## `buscar_pelo_filtro_aplicativo` [#buscar_pelo_filtro_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/filtro" credencial />

Busca aplicativos por filtro

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve todos os aplicativos não excluídos da conta que casam com o filtro, sem paginação, em ordem alfabética do nome. `nome` procura o trecho no nome e `dominio` em qualquer domínio cadastrado (sem diferenciar maiúsculas); `chave` compara a chave exata e `comportamento_ao_estourar` o valor exato (`COBRAR_EXCEDENTE` ou `PARAR_INGESTAO`). Sem filtro, devolve todos. Parâmetros de consulta, todos opcionais: `nome`: trecho do nome, sem diferenciar maiúsculas; `dominio`: trecho de um dos domínios cadastrados, sem diferenciar maiúsculas; `chave`: chave pública exata; `comportamento_ao_estourar`: `COBRAR_EXCEDENTE` ou `PARAR_INGESTAO`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Aplicativo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_aplicativo(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAplicativo,
) -> Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_aplicativo(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroAplicativo { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.dominio": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.chave": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.comportamento_ao_estourar": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Aplicativo>>` · Rust: `Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>`

## `buscar_pelo_id_aplicativo` [#buscar_pelo_id_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/{id}" credencial />

Busca um aplicativo pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve o aplicativo pelo id; registro excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_aplicativo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## `atualizar_pelo_id_aplicativo` [#atualizar_pelo_id_aplicativo]

<Rota metodo="PATCH" caminho="/aplicativo/{id}" credencial />

Atualiza um aplicativo pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Atualização parcial: só os campos enviados mudam. `nome` não pode ficar vazio; `dominios` substitui a lista inteira e precisa de ao menos um domínio válido; `franquia_mensal` precisa ser maior que zero; `comportamento_ao_estourar` aceita `COBRAR_EXCEDENTE` ou `PARAR_INGESTAO`. Com `rotacionar_chave: true` o backend gera uma `chave` nova e a antiga para de valer na ingestão. Campos do corpo, todos opcionais: `nome`: novo nome (não pode ficar vazio); `dominios`: nova lista de domínios, que substitui a atual; precisa de ao menos um válido; `franquia_mensal`: nova franquia mensal de eventos, maior que zero; `comportamento_ao_estourar`: `COBRAR_EXCEDENTE` ou `PARAR_INGESTAO`; `rotacionar_chave`: com `true`, gera uma chave nova e a antiga para de valer na ingestão.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AplicativoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_aplicativo(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AplicativoAtualizar,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_aplicativo(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AplicativoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AplicativoAtualizar", typeDescriptionLink: "#tipo-aplicativoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## `deletar_pelo_id_aplicativo` [#deletar_pelo_id_aplicativo]

<Rota metodo="DELETE" caminho="/aplicativo/{id}" credencial />

Exclui um aplicativo pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Exclusão lógica: o aplicativo some das leituras e a chave dele deixa de ser aceita na ingestão.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_aplicativo } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_aplicativo(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Aplicativo [#tipo-aplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Aplicativo } from "termo_core/tracing";

export interface Aplicativo {
  atualizado_em: string;
  chave: string;
  comportamento_ao_estourar: string;
  conta_email: string;
  conta_id: string;
  criado_em: string;
  dominios: Array<string>;
  franquia_mensal: number;
  id: string;
  nome: string;
  primeiro_evento_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Aplicativo;

pub struct Aplicativo {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chave: String,
    pub comportamento_ao_estourar: String,
    pub conta_email: String,
    pub conta_id: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub dominios: Vec<String>,
    pub franquia_mensal: i64,
    pub id: uuid::Uuid,
    pub nome: String,
    pub primeiro_evento_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>

### AplicativoAtualizar [#tipo-aplicativoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AplicativoAtualizar } from "termo_core/tracing";

export interface AplicativoAtualizar {
  comportamento_ao_estourar?: string | null;
  dominios?: Array<string> | null;
  franquia_mensal?: number | null;
  nome?: string | null;
  rotacionar_chave?: boolean | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::AplicativoAtualizar;

pub struct AplicativoAtualizar {
    pub comportamento_ao_estourar: Option<String>,
    pub dominios: Option<Vec<String>>,
    pub franquia_mensal: Option<i64>,
    pub nome: Option<String>,
    pub rotacionar_chave: Option<bool>,
}
```

</Tab>
</Tabs>

### AplicativoCriar [#tipo-aplicativocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AplicativoCriar } from "termo_core/tracing";

export interface AplicativoCriar {
  comportamento_ao_estourar?: string;
  dominios?: Array<string>;
  franquia_mensal?: number;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::AplicativoCriar;

pub struct AplicativoCriar {
    pub comportamento_ao_estourar: Option<String>,
    pub dominios: Option<Vec<String>>,
    pub franquia_mensal: Option<i64>,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaAplicativo [#tipo-paginaaplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativo } from "termo_core/tracing";

export interface PaginaAplicativo {
  itens: Array<PaginaAplicativoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAplicativo;

pub struct PaginaAplicativo {
    pub itens: Vec<PaginaAplicativoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoComplete [#tipo-paginaaplicativoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoComplete } from "termo_core/tracing";

export interface PaginaAplicativoAutoComplete {
  itens: Array<PaginaAplicativoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAplicativoAutoComplete;

pub struct PaginaAplicativoAutoComplete {
    pub itens: Vec<PaginaAplicativoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoCompleteItensItem [#tipo-paginaaplicativoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaAplicativoAutoCompleteItensItem {
  chave: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAplicativoAutoCompleteItensItem;

pub struct PaginaAplicativoAutoCompleteItensItem {
    pub chave: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaAplicativoItensItem [#tipo-paginaaplicativoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoItensItem } from "termo_core/tracing";

export interface PaginaAplicativoItensItem {
  atualizado_em: string;
  chave: string;
  comportamento_ao_estourar: string;
  conta_email: string;
  conta_id: string;
  criado_em: string;
  dominios: Array<string>;
  franquia_mensal: number;
  id: string;
  nome: string;
  primeiro_evento_em?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAplicativoItensItem;

pub struct PaginaAplicativoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub chave: String,
    pub comportamento_ao_estourar: String,
    pub conta_email: String,
    pub conta_id: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub dominios: Vec<String>,
    pub franquia_mensal: i64,
    pub id: uuid::Uuid,
    pub nome: String,
    pub primeiro_evento_em: Option<chrono::DateTime<chrono::Utc>>,
}
```

</Tab>
</Tabs>


# Auth (/docs/servicos/tracing/auth)

> 8 funções do TermoTracing para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_auth`](#buscar_paginador_auth) | `GET /auth` | Lista os acessos com paginação |
| [`criar_auth`](#criar_auth) | `POST /auth` | Cria um acesso |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Busca o acesso de quem está logado |
| [`buscar_auto_complete_auth`](#buscar_auto_complete_auth) | `GET /auth/autocomplete` | Lista básica de acessos para seleção |
| [`buscar_pelo_filtro_auth`](#buscar_pelo_filtro_auth) | `GET /auth/filtro` | Busca acessos por filtro |
| [`buscar_pelo_id_auth`](#buscar_pelo_id_auth) | `GET /auth/{id}` | Busca um acesso pelo id |
| [`atualizar_pelo_id_auth`](#atualizar_pelo_id_auth) | `PATCH /auth/{id}` | Atualiza um acesso pelo id |
| [`deletar_pelo_id_auth`](#deletar_pelo_id_auth) | `DELETE /auth/{id}` | Exclui um acesso pelo id |

## `buscar_paginador_auth` [#buscar_paginador_auth]

<Rota metodo="GET" caminho="/auth" credencial />

Lista os acessos com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena por perfil e depois por e-mail. Acessos excluídos não aparecem. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_auth(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAuth,
) -> Result<tipos::PaginaAuth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_auth(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorAuth { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuth>` · Rust: `Result<tipos::PaginaAuth, ErroAoChamarServico>` · veja [`PaginaAuth`](#tipo-paginaauth).

## `criar_auth` [#criar_auth]

<Rota metodo="POST" caminho="/auth" credencial />

Cria um acesso

Exige a permissão `criar` da área `colaboradores`. Cadastra quem pode entrar no TermoTracing. `email` é obrigatório, com até 160 caracteres, e é gravado em minúsculas, sem espaços nas pontas; `perfil` é `colaborador` ou `cliente`. O acesso nasce ativo e sem nenhuma permissão. Para a pessoa conseguir entrar, o e-mail precisa ser `@termotubos.com.br` e existir no TermoAuth com o mesmo endereço.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_auth(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AuthCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_auth(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AuthCriar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::criar_auth(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AuthCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthCriar", typeDescriptionLink: "#tipo-authcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Busca o acesso de quem está logado

Livre para qualquer usuário autenticado com acesso ativo, mesmo sem nenhuma permissão liberada. Devolve o acesso de quem chamou (id, e-mail, nome, perfil e se é master do TermoAuth) e as permissões por área (`rastreamento`, `aplicativos` e `colaboradores`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões e, no primeiro pedido, ganha o acesso e o colaborador automaticamente. `nome` vem do TermoAuth e, se estiver vazio, repete o e-mail. É a chamada que o painel faz antes de mostrar qualquer tela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## `buscar_auto_complete_auth` [#buscar_auto_complete_auth]

<Rota metodo="GET" caminho="/auth/autocomplete" credencial />

Lista básica de acessos para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só id, e-mail e perfil, em ordem alfabética de e-mail, para escolher um acesso. `busca` procura por trecho do e-mail, sem diferenciar maiúsculas; `perfil` compara o valor exato. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_auth(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAuth,
) -> Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_auth(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteAuth { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthAutoComplete>` · Rust: `Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>` · veja [`PaginaAuthAutoComplete`](#tipo-paginaauthautocomplete).

## `buscar_pelo_filtro_auth` [#buscar_pelo_filtro_auth]

<Rota metodo="GET" caminho="/auth/filtro" credencial />

Busca acessos por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os acessos que casam com o filtro, sem paginação, em ordem alfabética de e-mail. `email` procura por trecho, sem diferenciar maiúsculas; `perfil` compara o valor exato (`colaborador` ou `cliente`); `ativo` filtra pela situação. Sem filtro, devolve todos. Acessos excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Auth>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_auth(credencial_de_acesso, { email: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAuth,
) -> Result<Vec<tipos::Auth>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_auth(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroAuth { email: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Auth>>` · Rust: `Result<Vec<tipos::Auth>, ErroAoChamarServico>`

## `buscar_pelo_id_auth` [#buscar_pelo_id_auth]

<Rota metodo="GET" caminho="/auth/{id}" credencial />

Busca um acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Acesso excluído responde `404`. `vinculado` diz se há um colaborador ligado ao acesso, e `nome` é o nome desse colaborador. `master` diz se a pessoa é master do TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `atualizar_pelo_id_auth` [#atualizar_pelo_id_auth]

<Rota metodo="PATCH" caminho="/auth/{id}" credencial />

Atualiza um acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `email` (até 160 caracteres, gravado em minúsculas) e `ativo` (acesso inativo é barrado em todas as rotas). O perfil não muda. O acesso de um master do TermoAuth não pode ser alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AuthAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_auth(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AuthAtualizar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_auth(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AuthAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthAtualizar", typeDescriptionLink: "#tipo-authatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `deletar_pelo_id_auth` [#deletar_pelo_id_auth]

<Rota metodo="DELETE" caminho="/auth/{id}" credencial />

Exclui um acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica: o acesso some das consultas e a pessoa deixa de entrar, mas o registro fica guardado e não há como restaurar. Acesso com colaborador vinculado não pode ser excluído por aqui. O acesso de um master do TermoAuth não pode ser excluído.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_auth } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/tracing";

export interface AcessoAtual {
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::AcessoAtual;

pub struct AcessoAtual {
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/tracing";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Auth [#tipo-auth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Auth } from "termo_core/tracing";

export interface Auth {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Auth;

pub struct Auth {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### AuthAtualizar [#tipo-authatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthAtualizar } from "termo_core/tracing";

export interface AuthAtualizar {
  ativo?: boolean | null;
  email?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::AuthAtualizar;

pub struct AuthAtualizar {
    pub ativo: Option<bool>,
    pub email: Option<String>,
}
```

</Tab>
</Tabs>

### AuthCriar [#tipo-authcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthCriar } from "termo_core/tracing";

export interface AuthCriar {
  email: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::AuthCriar;

pub struct AuthCriar {
    pub email: String,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuth [#tipo-paginaauth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuth } from "termo_core/tracing";

export interface PaginaAuth {
  itens: Array<PaginaAuthItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAuth;

pub struct PaginaAuth {
    pub itens: Vec<PaginaAuthItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoComplete [#tipo-paginaauthautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoComplete } from "termo_core/tracing";

export interface PaginaAuthAutoComplete {
  itens: Array<PaginaAuthAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAuthAutoComplete;

pub struct PaginaAuthAutoComplete {
    pub itens: Vec<PaginaAuthAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteItensItem [#tipo-paginaauthautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaAuthAutoCompleteItensItem {
  email: string;
  id: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAuthAutoCompleteItensItem;

pub struct PaginaAuthAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthItensItem [#tipo-paginaauthitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthItensItem } from "termo_core/tracing";

export interface PaginaAuthItensItem {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaAuthItensItem;

pub struct PaginaAuthItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/tracing";

export interface Permissoes {
  aplicativos?: Acoes;
  colaboradores?: Acoes;
  rastreamento?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub rastreamento: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/tracing/colaborador)

> 5 funções do TermoTracing para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista os colaboradores com paginação |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista os colaboradores com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena por nome. Quando quem chama é master do TermoAuth, antes de listar o TermoTracing busca no TermoAuth os colaboradores `@termotubos.com.br` que ainda não existem aqui e os cadastra sem nenhuma permissão. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só id, nome e e-mail, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail (a busca rápida da tela); `nome`, `email` e `cargo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação; `perfil_acesso_id` filtra pelo perfil de acesso. Sem filtro, devolve todos. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização e pelos eventos do TermoWebhook) e `setor`, `cargo` e `funcao` vêm de lá.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve o colaborador com o e-mail e o `master` do acesso dele. Colaborador excluído responde `404`. O colaborador é do TermoAuth: aqui ele só é lido (chega pela sincronização e pelos eventos do TermoWebhook) e `setor`, `cargo` e `funcao` vêm de lá.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoTracing: `perfil_acesso_id` aponta para um perfil de `GET /perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/tracing";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/tracing";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/tracing";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/tracing";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/tracing";

export interface PaginaColaboradorItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/tracing/configuracao)

> 2 funções do TermoTracing para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao` | Busca a configuração do TermoTracing |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao` | Atualiza o segredo do app gerado no TermoAuth |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Busca a configuração do TermoTracing

Só um master do TermoAuth (os demais recebem `403`). A configuração é uma linha única e guarda o segredo do app `termo-tracing` gerado no TermoAuth, cifrado no banco com AES-256-GCM e a chave derivada de `GLOBAL_SECRET_CRIPTOGRAFIA`. O valor nunca volta: `segredo_do_app_gerado_no_termo_auth` traz só `configurado` e `final_visivel` (os 4 últimos caracteres, mascarados). Sem a `GLOBAL_SECRET_CRIPTOGRAFIA` no servidor, `criptografia_disponivel` vem `false` e o segredo aparece como não configurado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao" credencial />

Atualiza o segredo do app gerado no TermoAuth

Só um master do TermoAuth (os demais recebem `403`). `segredo_do_app_gerado_no_termo_auth` é obrigatório: uma string troca o segredo (até 2.000 caracteres, sem quebra de linha; espaços nas pontas são removidos) e `null` ou string vazia limpa. O valor é gravado cifrado e entregue na hora ao `termo_core`, que o usa para pedir o token de aplicativo no TermoAuth, sem deploy. Campo desconhecido no corpo responde `422`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/tracing";

export interface Configuracao {
  atualizado_em: string;
  atualizado_por?: string | null;
  criptografia_disponivel: boolean;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Configuracao;

pub struct Configuracao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub atualizado_por: Option<String>,
    pub criptografia_disponivel: bool,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/tracing";

export interface ConfiguracaoAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/tracing";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Erro (/docs/servicos/tracing/erro)

> 7 funções do TermoTracing para erro.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_erro`](#buscar_paginador_erro) | `GET /erro` | Lista os erros paginados |
| [`criar_erro`](#criar_erro) | `POST /erro` | Cadastra um erro |
| [`buscar_auto_complete_erro`](#buscar_auto_complete_erro) | `GET /erro/autocomplete` | Lista básica de erros para seleção |
| [`buscar_pelo_filtro_erro`](#buscar_pelo_filtro_erro) | `GET /erro/filtro` | Busca erros por filtro |
| [`buscar_pelo_id_erro`](#buscar_pelo_id_erro) | `GET /erro/{id}` | Busca um erro pelo id |
| [`atualizar_pelo_id_erro`](#atualizar_pelo_id_erro) | `PATCH /erro/{id}` | Atualiza um erro pelo id |
| [`deletar_pelo_id_erro`](#deletar_pelo_id_erro) | `DELETE /erro/{id}` | Exclui um erro pelo id |

## `buscar_paginador_erro` [#buscar_paginador_erro]

<Rota metodo="GET" caminho="/erro" credencial />

Lista os erros paginados

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Lista os grupos de erro não excluídos da conta, do que afetou mais usuários para o que afetou menos e, no empate, do que ocorreu mais vezes. `aplicativo_id` filtra pelo aplicativo e `status` pela situação (`ABERTO`, `RESOLVIDO` ou `IGNORADO`, sem diferenciar maiúsculas). `pagina` começa em 1 (padrão 1; menor que 1 vira 1). A página tem sempre 50 itens: o parâmetro `tamanho` é aceito, mas ignorado. A resposta traz `itens`, `total` (quantidade de registros que casam com os filtros), `pagina` e `tamanho` (50). Parâmetros de consulta, todos opcionais: `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: aceito, mas ignorado: a página tem sempre 50 itens; `aplicativo_id`: id do aplicativo (opcional); `status`: `ABERTO`, `RESOLVIDO` ou `IGNORADO`, sem diferenciar maiúsculas (opcional).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_erro(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorErro = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaErro>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_erro(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorErro,
) -> Result<tipos::PaginaErro, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_erro(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorErro { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaErro>` · Rust: `Result<tipos::PaginaErro, ErroAoChamarServico>` · veja [`PaginaErro`](#tipo-paginaerro).

## `criar_erro` [#criar_erro]

<Rota metodo="POST" caminho="/erro" credencial />

Cadastra um erro

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Registra a ocorrência de um erro num aplicativo da conta (os erros normalmente são agrupados sozinhos a partir dos eventos da ingestão). `aplicativo_id` precisa ser de um aplicativo da conta; `mensagem` é obrigatória; `tipo` aceita um dos tipos de evento (`ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` ou `PERSONALIZADO`). Erros com o mesmo tipo, mensagem, arquivo e linha formam um só grupo na conta: se o grupo já existe, a ocorrência soma 1 e o grupo existente é devolvido. Campos do corpo: `aplicativo_id`: id de um aplicativo da conta (obrigatório); `tipo`: tipo do erro (obrigatório): `ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` ou `PERSONALIZADO`; `mensagem`: mensagem do erro (obrigatória, não pode ficar vazia); `arquivo`: arquivo onde o erro ocorreu (opcional); `linha`: linha do erro (opcional); `pilha`: pilha de chamadas (opcional).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_erro(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ErroCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Erro>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_erro(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ErroCriar,
) -> Result<tipos::Erro, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::criar_erro(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ErroCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ErroCriar", typeDescriptionLink: "#tipo-errocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Erro>` · Rust: `Result<tipos::Erro, ErroAoChamarServico>` · veja [`Erro`](#tipo-erro).

## `buscar_auto_complete_erro` [#buscar_auto_complete_erro]

<Rota metodo="GET" caminho="/erro/autocomplete" credencial />

Lista básica de erros para seleção

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve só id e rótulo (a mensagem do erro), em ordem alfabética da mensagem. `busca` procura o trecho na mensagem, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`. Parâmetros de consulta, todos opcionais: `busca`: trecho da mensagem, sem diferenciar maiúsculas (opcional); `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: itens por página (padrão 10, sem máximo; menor que 1 vira 1).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_erro(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteErro = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaErroAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_erro(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteErro,
) -> Result<tipos::PaginaErroAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_erro(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteErro { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaErroAutoComplete>` · Rust: `Result<tipos::PaginaErroAutoComplete, ErroAoChamarServico>` · veja [`PaginaErroAutoComplete`](#tipo-paginaerroautocomplete).

## `buscar_pelo_filtro_erro` [#buscar_pelo_filtro_erro]

<Rota metodo="GET" caminho="/erro/filtro" credencial />

Busca erros por filtro

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve todos os grupos de erro não excluídos da conta que casam com o filtro, sem paginação, do que afetou mais usuários para o que afetou menos. `aplicativo_id` filtra pelo aplicativo; `mensagem` procura o trecho na mensagem; `tipo`, `status` (`ABERTO`, `RESOLVIDO` ou `IGNORADO`) e `navegador` comparam o valor exato, sem diferenciar maiúsculas; `inicio` traz os que ocorreram de novo a partir dessa data e hora e `fim` os que começaram até ela (ISO 8601). Sem filtro, devolve todos. Parâmetros de consulta, todos opcionais: `aplicativo_id`: id do aplicativo; `mensagem`: trecho da mensagem, sem diferenciar maiúsculas; `tipo`: tipo do erro (sem diferenciar maiúsculas): `ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` ou `PERSONALIZADO`; `status`: `ABERTO`, `RESOLVIDO` ou `IGNORADO` (sem diferenciar maiúsculas); `navegador`: navegador onde ocorreu (valor exato, sem diferenciar maiúsculas); `inicio`: erros com ocorrência a partir desta data e hora ISO 8601, por exemplo 2026-10-07T00:00:00Z; `fim`: erros cuja primeira ocorrência foi até esta data e hora ISO 8601.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_erro(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroErro = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Erro>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_erro(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroErro,
) -> Result<Vec<tipos::Erro>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_erro(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroErro { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.mensagem": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.status": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.navegador": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Erro>>` · Rust: `Result<Vec<tipos::Erro>, ErroAoChamarServico>`

## `buscar_pelo_id_erro` [#buscar_pelo_id_erro]

<Rota metodo="GET" caminho="/erro/{id}" credencial />

Busca um erro pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve o erro pelo id; registro excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_erro(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Erro>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_erro(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Erro, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_erro(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Erro>` · Rust: `Result<tipos::Erro, ErroAoChamarServico>` · veja [`Erro`](#tipo-erro).

## `atualizar_pelo_id_erro` [#atualizar_pelo_id_erro]

<Rota metodo="PATCH" caminho="/erro/{id}" credencial />

Atualiza um erro pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Atualização parcial: só os campos enviados mudam. Muda o `status` do grupo de erro: `ABERTO`, `RESOLVIDO` ou `IGNORADO`. Campos do corpo, todos opcionais: `status`: nova situação: `ABERTO`, `RESOLVIDO` ou `IGNORADO`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_erro(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ErroAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Erro>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_erro(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ErroAtualizar,
) -> Result<tipos::Erro, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_erro(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ErroAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ErroAtualizar", typeDescriptionLink: "#tipo-erroatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Erro>` · Rust: `Result<tipos::Erro, ErroAoChamarServico>` · veja [`Erro`](#tipo-erro).

## `deletar_pelo_id_erro` [#deletar_pelo_id_erro]

<Rota metodo="DELETE" caminho="/erro/{id}" credencial />

Exclui um erro pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Exclusão lógica: o registro some das leituras, mas não é apagado na hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_erro(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_erro } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_erro(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_erro(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_erro(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Erro [#tipo-erro]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Erro } from "termo_core/tracing";

export interface Erro {
  aplicativo_id: string;
  arquivo?: string | null;
  assinatura: string;
  conta_id: string;
  id: string;
  linha?: number | null;
  mensagem: string;
  navegadores: Array<string>;
  ocorrencias: number;
  paginas: Array<string>;
  pilha?: string | null;
  primeira_ocorrencia_em: string;
  status: string;
  tipo: string;
  ultima_ocorrencia_em: string;
  usuarios: Array<string>;
  usuarios_afetados: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Erro;

pub struct Erro {
    pub aplicativo_id: uuid::Uuid,
    pub arquivo: Option<String>,
    pub assinatura: String,
    pub conta_id: String,
    pub id: uuid::Uuid,
    pub linha: Option<i32>,
    pub mensagem: String,
    pub navegadores: Vec<String>,
    pub ocorrencias: i64,
    pub paginas: Vec<String>,
    pub pilha: Option<String>,
    pub primeira_ocorrencia_em: chrono::DateTime<chrono::Utc>,
    pub status: String,
    pub tipo: String,
    pub ultima_ocorrencia_em: chrono::DateTime<chrono::Utc>,
    pub usuarios: Vec<String>,
    pub usuarios_afetados: i64,
}
```

</Tab>
</Tabs>

### ErroAtualizar [#tipo-erroatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ErroAtualizar } from "termo_core/tracing";

export interface ErroAtualizar {
  status?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::ErroAtualizar;

pub struct ErroAtualizar {
    pub status: Option<String>,
}
```

</Tab>
</Tabs>

### ErroCriar [#tipo-errocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ErroCriar } from "termo_core/tracing";

export interface ErroCriar {
  aplicativo_id: string;
  arquivo?: string | null;
  linha?: number | null;
  mensagem: string;
  pilha?: string | null;
  tipo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::ErroCriar;

pub struct ErroCriar {
    pub aplicativo_id: uuid::Uuid,
    pub arquivo: Option<String>,
    pub linha: Option<i32>,
    pub mensagem: String,
    pub pilha: Option<String>,
    pub tipo: String,
}
```

</Tab>
</Tabs>

### PaginaErro [#tipo-paginaerro]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaErro } from "termo_core/tracing";

export interface PaginaErro {
  itens: Array<PaginaErroItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaErro;

pub struct PaginaErro {
    pub itens: Vec<PaginaErroItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaErroAutoComplete [#tipo-paginaerroautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaErroAutoComplete } from "termo_core/tracing";

export interface PaginaErroAutoComplete {
  itens: Array<PaginaErroAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaErroAutoComplete;

pub struct PaginaErroAutoComplete {
    pub itens: Vec<PaginaErroAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaErroAutoCompleteItensItem [#tipo-paginaerroautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaErroAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaErroAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaErroAutoCompleteItensItem;

pub struct PaginaErroAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaErroItensItem [#tipo-paginaerroitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaErroItensItem } from "termo_core/tracing";

export interface PaginaErroItensItem {
  aplicativo_id: string;
  arquivo?: string | null;
  assinatura: string;
  conta_id: string;
  id: string;
  linha?: number | null;
  mensagem: string;
  navegadores: Array<string>;
  ocorrencias: number;
  paginas: Array<string>;
  pilha?: string | null;
  primeira_ocorrencia_em: string;
  status: string;
  tipo: string;
  ultima_ocorrencia_em: string;
  usuarios: Array<string>;
  usuarios_afetados: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaErroItensItem;

pub struct PaginaErroItensItem {
    pub aplicativo_id: uuid::Uuid,
    pub arquivo: Option<String>,
    pub assinatura: String,
    pub conta_id: String,
    pub id: uuid::Uuid,
    pub linha: Option<i32>,
    pub mensagem: String,
    pub navegadores: Vec<String>,
    pub ocorrencias: i64,
    pub paginas: Vec<String>,
    pub pilha: Option<String>,
    pub primeira_ocorrencia_em: chrono::DateTime<chrono::Utc>,
    pub status: String,
    pub tipo: String,
    pub ultima_ocorrencia_em: chrono::DateTime<chrono::Utc>,
    pub usuarios: Vec<String>,
    pub usuarios_afetados: i64,
}
```

</Tab>
</Tabs>


# Evento (/docs/servicos/tracing/evento)

> 7 funções do TermoTracing para evento.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_evento`](#buscar_paginador_evento) | `GET /evento` | Lista os eventos paginados |
| [`buscar_auto_complete_evento`](#buscar_auto_complete_evento) | `GET /evento/autocomplete` | Lista básica de eventos para seleção |
| [`buscar_pelo_filtro_evento`](#buscar_pelo_filtro_evento) | `GET /evento/filtro` | Busca eventos por filtro |
| [`criar_evento`](#criar_evento) | `POST /evento/ingestao` | Recebe um lote de eventos de um site (ingestão) |
| [`buscar_pelo_id_evento`](#buscar_pelo_id_evento) | `GET /evento/{id}` | Busca um evento pelo id |
| [`atualizar_pelo_id_evento`](#atualizar_pelo_id_evento) | `PATCH /evento/{id}` | Atualiza um evento pelo id |
| [`deletar_pelo_id_evento`](#deletar_pelo_id_evento) | `DELETE /evento/{id}` | Exclui um evento pelo id |

## `buscar_paginador_evento` [#buscar_paginador_evento]

<Rota metodo="GET" caminho="/evento" credencial />

Lista os eventos paginados

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Lista os eventos não excluídos da conta. Com `sessao_id`, devolve a linha do tempo da sessão do mais antigo para o mais recente; sem ele, do mais recente para o mais antigo. `aplicativo_id` filtra pelo aplicativo. `pagina` começa em 1 (padrão 1; menor que 1 vira 1). A página tem sempre 50 itens: o parâmetro `tamanho` é aceito, mas ignorado. A resposta traz `itens`, `total` (quantidade de registros que casam com os filtros), `pagina` e `tamanho` (50). Parâmetros de consulta, todos opcionais: `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: aceito, mas ignorado: a página tem sempre 50 itens; `sessao_id`: id da sessão: com ele, a lista vem do mais antigo para o mais recente (opcional); `aplicativo_id`: id do aplicativo (opcional).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEvento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_evento } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_evento(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorEvento,
) -> Result<tipos::PaginaEvento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_evento(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorEvento { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.sessao_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEvento>` · Rust: `Result<tipos::PaginaEvento, ErroAoChamarServico>` · veja [`PaginaEvento`](#tipo-paginaevento).

## `buscar_auto_complete_evento` [#buscar_auto_complete_evento]

<Rota metodo="GET" caminho="/evento/autocomplete" credencial />

Lista básica de eventos para seleção

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve só id e rótulo (o nome do evento ou, sem nome, a mensagem ou o tipo), em ordem alfabética do rótulo. `busca` procura o trecho no rótulo, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`. Parâmetros de consulta, todos opcionais: `busca`: trecho do rótulo (nome, mensagem ou tipo), sem diferenciar maiúsculas (opcional); `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: itens por página (padrão 10, sem máximo; menor que 1 vira 1).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEventoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_evento } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_evento(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteEvento,
) -> Result<tipos::PaginaEventoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_evento(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteEvento { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEventoAutoComplete>` · Rust: `Result<tipos::PaginaEventoAutoComplete, ErroAoChamarServico>` · veja [`PaginaEventoAutoComplete`](#tipo-paginaeventoautocomplete).

## `buscar_pelo_filtro_evento` [#buscar_pelo_filtro_evento]

<Rota metodo="GET" caminho="/evento/filtro" credencial />

Busca eventos por filtro

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve todos os eventos não excluídos da conta que casam com o filtro, sem paginação, do mais antigo para o mais recente (`ocorrido_em`). `aplicativo_id` e `sessao_id` filtram pelo id; `tipo` compara o valor exato, sem diferenciar maiúsculas (`ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` ou `PERSONALIZADO`); `nome` procura o trecho no nome; `inicio` e `fim` (data e hora ISO 8601) limitam o `ocorrido_em`. Sem filtro, devolve todos. Os eventos ficam guardados por 30 dias. Parâmetros de consulta, todos opcionais: `aplicativo_id`: id do aplicativo; `sessao_id`: id da sessão; `tipo`: tipo do evento (sem diferenciar maiúsculas): `ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` ou `PERSONALIZADO`; `nome`: trecho do nome, sem diferenciar maiúsculas; `inicio`: eventos ocorridos a partir desta data e hora ISO 8601, por exemplo 2026-10-07T00:00:00Z; `fim`: eventos ocorridos até esta data e hora ISO 8601.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Evento>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_evento } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_evento(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroEvento,
) -> Result<Vec<tipos::Evento>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_evento(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroEvento { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.sessao_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tipo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Evento>>` · Rust: `Result<Vec<tipos::Evento>, ErroAoChamarServico>`

## `criar_evento` [#criar_evento]

<Rota metodo="POST" caminho="/evento/ingestao" />

Recebe um lote de eventos de um site (ingestão)

Rota pública, sem token: é a que o script instalado no site do cliente chama. O corpo é JSON, opcionalmente comprimido em gzip (`Content-Encoding: gzip`), com a `chave` pública do aplicativo, os dados da `sessao` e a lista de `eventos`. O cabeçalho `Origin` (ou, na falta dele, `Referer`) precisa ser de um dos domínios cadastrados no aplicativo. Cada lote aceita até 500 eventos (o excedente é recusado) e eventos de tipo desconhecido são recusados; cada chave aceita até 6000 eventos por minuto. Tipos aceitos: `ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` e `PERSONALIZADO`. Com o comportamento `PARAR_INGESTAO` e a franquia do mês esgotada, o lote é recusado. Os eventos aceitos são gravados em segundo plano; a resposta diz quantos foram aceitos e recusados. Campos do corpo: `chave`: chave pública do aplicativo (prefixo `pk_live_`), obrigatória; `sessao`: dados da sessão de navegação que enviou o lote; `eventos`: eventos do lote; até 500 por lote, o excedente é recusado. Campos de `sessao`: `sessao.sessao_externa`: identificador da sessão gerado pelo script (obrigatório); `sessao.anonimo_id`: identificador anônimo do visitante (obrigatório); `sessao.usuario_id`: id do usuário logado no site (opcional); `sessao.navegador`: navegador (padrão vazio); `sessao.sistema_operacional`: sistema operacional (padrão vazio); `sessao.dispositivo`: tipo de dispositivo (padrão vazio); `sessao.resolucao`: resolução da tela (padrão vazio); `sessao.pagina_inicial`: endereço da primeira página (padrão vazio). Campos de cada item de `eventos`: `evento_id`: identificador do evento no navegador, usado para não gravar o mesmo evento duas vezes (até 120 caracteres); `tipo`: tipo do evento (obrigatório): `ERRO_JS`, `PROMISE_REJEITADA`, `CONSOLE`, `REQUISICAO`, `NAVEGACAO`, `SAIDA`, `PULSO`, `CLIQUE`, `DESEMPENHO`, `IDENTIFICACAO` ou `PERSONALIZADO`; outro valor é recusado; `nome`: nome do evento (padrão vazio; cortado em 120 caracteres); `mensagem`: mensagem (cortada em 2000 caracteres); `pilha`: pilha de chamadas (cortada em 8000 caracteres); `arquivo`: arquivo do erro (cortado em 2000 caracteres); `linha`: linha do erro; `coluna`: coluna do erro; `url`: endereço da página ou da requisição (cortado em 2000 caracteres); `metodo`: método HTTP da requisição; `status`: status HTTP da requisição; `duracao_ms`: duração em milissegundos; `nivel`: nível do console; `seletor`: seletor CSS do elemento clicado (cortado em 500 caracteres); `texto`: texto do elemento clicado (cortado em 200 caracteres); `metrica`: nome da métrica de desempenho; `valor`: valor da métrica de desempenho; `usuario_id`: id do usuário logado no site; `payload`: dados livres (JSON); `ocorrido_em`: data e hora ISO 8601 em que o evento ocorreu (padrão: a hora do recebimento).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_evento(
  corpo_da_requisicao: tipos.EventoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ResultadoIngestao>
```

```ts title="Exemplo"
import { criar_evento } from "termo_core/tracing";

const resposta = await criar_evento(corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_evento(
    corpo_da_requisicao: &tipos::EventoCriar,
) -> Result<tipos::ResultadoIngestao, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::tracing::criar_evento(&corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "corpo_da_requisicao": { type: "tipos.EventoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EventoCriar", typeDescriptionLink: "#tipo-eventocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ResultadoIngestao>` · Rust: `Result<tipos::ResultadoIngestao, ErroAoChamarServico>` · veja [`ResultadoIngestao`](#tipo-resultadoingestao).

## `buscar_pelo_id_evento` [#buscar_pelo_id_evento]

<Rota metodo="GET" caminho="/evento/{id}" credencial />

Busca um evento pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve o evento pelo id; registro excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Evento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_evento } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_evento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Evento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_evento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Evento>` · Rust: `Result<tipos::Evento, ErroAoChamarServico>` · veja [`Evento`](#tipo-evento).

## `atualizar_pelo_id_evento` [#atualizar_pelo_id_evento]

<Rota metodo="PATCH" caminho="/evento/{id}" credencial />

Atualiza um evento pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Atualização parcial: só os campos enviados mudam. Muda o `nome` (cortado em 120 caracteres) e o `payload` (JSON livre) do evento. Campos do corpo, todos opcionais: `nome`: novo nome do evento (cortado em 120 caracteres); `payload`: novos dados livres do evento (JSON), que substituem os atuais.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.EventoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Evento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_evento } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_evento(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::EventoAtualizar,
) -> Result<tipos::Evento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_evento(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.EventoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EventoAtualizar", typeDescriptionLink: "#tipo-eventoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Evento>` · Rust: `Result<tipos::Evento, ErroAoChamarServico>` · veja [`Evento`](#tipo-evento).

## `deletar_pelo_id_evento` [#deletar_pelo_id_evento]

<Rota metodo="DELETE" caminho="/evento/{id}" credencial />

Exclui um evento pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Exclusão lógica: o registro some das leituras, mas não é apagado na hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_evento } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_evento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_evento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Evento [#tipo-evento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Evento } from "termo_core/tracing";

export interface Evento {
  aplicativo_id: string;
  arquivo?: string | null;
  coluna?: number | null;
  conta_id: string;
  criado_em: string;
  duracao_ms?: number | null;
  id: string;
  linha?: number | null;
  mensagem?: string | null;
  metodo?: string | null;
  metrica?: string | null;
  navegador: string;
  nivel?: string | null;
  nome: string;
  ocorrido_em: string;
  payload?: unknown;
  pilha?: string | null;
  seletor?: string | null;
  sessao_id: string;
  status?: number | null;
  texto?: string | null;
  tipo: string;
  url?: string | null;
  valor?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Evento;

pub struct Evento {
    pub aplicativo_id: uuid::Uuid,
    pub arquivo: Option<String>,
    pub coluna: Option<i32>,
    pub conta_id: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub duracao_ms: Option<i64>,
    pub id: uuid::Uuid,
    pub linha: Option<i32>,
    pub mensagem: Option<String>,
    pub metodo: Option<String>,
    pub metrica: Option<String>,
    pub navegador: String,
    pub nivel: Option<String>,
    pub nome: String,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub payload: Option<serde_json::Value>,
    pub pilha: Option<String>,
    pub seletor: Option<String>,
    pub sessao_id: uuid::Uuid,
    pub status: Option<i32>,
    pub texto: Option<String>,
    pub tipo: String,
    pub url: Option<String>,
    pub valor: Option<f64>,
}
```

</Tab>
</Tabs>

### EventoAtualizar [#tipo-eventoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoAtualizar } from "termo_core/tracing";

export interface EventoAtualizar {
  nome?: string | null;
  payload?: unknown;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::EventoAtualizar;

pub struct EventoAtualizar {
    pub nome: Option<String>,
    pub payload: Option<serde_json::Value>,
}
```

</Tab>
</Tabs>

### EventoCriar [#tipo-eventocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoCriar } from "termo_core/tracing";

export interface EventoCriar {
  chave: string;
  eventos: Array<EventoRecebido>;
  sessao: SessaoRecebida;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::EventoCriar;

pub struct EventoCriar {
    pub chave: String,
    pub eventos: Vec<EventoRecebido>,
    pub sessao: SessaoRecebida,
}
```

</Tab>
</Tabs>

### EventoRecebido [#tipo-eventorecebido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoRecebido } from "termo_core/tracing";

export interface EventoRecebido {
  arquivo?: string | null;
  coluna?: number | null;
  duracao_ms?: number | null;
  evento_id?: string | null;
  linha?: number | null;
  mensagem?: string | null;
  metodo?: string | null;
  metrica?: string | null;
  nivel?: string | null;
  nome?: string;
  ocorrido_em?: string | null;
  payload?: unknown;
  pilha?: string | null;
  seletor?: string | null;
  status?: number | null;
  texto?: string | null;
  tipo: string;
  url?: string | null;
  usuario_id?: string | null;
  valor?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::EventoRecebido;

pub struct EventoRecebido {
    pub arquivo: Option<String>,
    pub coluna: Option<i32>,
    pub duracao_ms: Option<i64>,
    pub evento_id: Option<String>,
    pub linha: Option<i32>,
    pub mensagem: Option<String>,
    pub metodo: Option<String>,
    pub metrica: Option<String>,
    pub nivel: Option<String>,
    pub nome: Option<String>,
    pub ocorrido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub payload: Option<serde_json::Value>,
    pub pilha: Option<String>,
    pub seletor: Option<String>,
    pub status: Option<i32>,
    pub texto: Option<String>,
    pub tipo: String,
    pub url: Option<String>,
    pub usuario_id: Option<String>,
    pub valor: Option<f64>,
}
```

</Tab>
</Tabs>

### PaginaEvento [#tipo-paginaevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEvento } from "termo_core/tracing";

export interface PaginaEvento {
  itens: Array<PaginaEventoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaEvento;

pub struct PaginaEvento {
    pub itens: Vec<PaginaEventoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEventoAutoComplete [#tipo-paginaeventoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEventoAutoComplete } from "termo_core/tracing";

export interface PaginaEventoAutoComplete {
  itens: Array<PaginaEventoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaEventoAutoComplete;

pub struct PaginaEventoAutoComplete {
    pub itens: Vec<PaginaEventoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEventoAutoCompleteItensItem [#tipo-paginaeventoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEventoAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaEventoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaEventoAutoCompleteItensItem;

pub struct PaginaEventoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaEventoItensItem [#tipo-paginaeventoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEventoItensItem } from "termo_core/tracing";

export interface PaginaEventoItensItem {
  aplicativo_id: string;
  arquivo?: string | null;
  coluna?: number | null;
  conta_id: string;
  criado_em: string;
  duracao_ms?: number | null;
  id: string;
  linha?: number | null;
  mensagem?: string | null;
  metodo?: string | null;
  metrica?: string | null;
  navegador: string;
  nivel?: string | null;
  nome: string;
  ocorrido_em: string;
  payload?: unknown;
  pilha?: string | null;
  seletor?: string | null;
  sessao_id: string;
  status?: number | null;
  texto?: string | null;
  tipo: string;
  url?: string | null;
  valor?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaEventoItensItem;

pub struct PaginaEventoItensItem {
    pub aplicativo_id: uuid::Uuid,
    pub arquivo: Option<String>,
    pub coluna: Option<i32>,
    pub conta_id: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub duracao_ms: Option<i64>,
    pub id: uuid::Uuid,
    pub linha: Option<i32>,
    pub mensagem: Option<String>,
    pub metodo: Option<String>,
    pub metrica: Option<String>,
    pub navegador: String,
    pub nivel: Option<String>,
    pub nome: String,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub payload: Option<serde_json::Value>,
    pub pilha: Option<String>,
    pub seletor: Option<String>,
    pub sessao_id: uuid::Uuid,
    pub status: Option<i32>,
    pub texto: Option<String>,
    pub tipo: String,
    pub url: Option<String>,
    pub valor: Option<f64>,
}
```

</Tab>
</Tabs>

### ResultadoIngestao [#tipo-resultadoingestao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResultadoIngestao } from "termo_core/tracing";

export interface ResultadoIngestao {
  aceitos: number;
  recusados: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::ResultadoIngestao;

pub struct ResultadoIngestao {
    pub aceitos: i64,
    pub recusados: i64,
}
```

</Tab>
</Tabs>

### SessaoRecebida [#tipo-sessaorecebida]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SessaoRecebida } from "termo_core/tracing";

export interface SessaoRecebida {
  anonimo_id: string;
  dispositivo?: string;
  navegador?: string;
  pagina_inicial?: string;
  resolucao?: string;
  sessao_externa: string;
  sistema_operacional?: string;
  usuario_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::SessaoRecebida;

pub struct SessaoRecebida {
    pub anonimo_id: String,
    pub dispositivo: Option<String>,
    pub navegador: Option<String>,
    pub pagina_inicial: Option<String>,
    pub resolucao: Option<String>,
    pub sessao_externa: String,
    pub sistema_operacional: Option<String>,
    pub usuario_id: Option<String>,
}
```

</Tab>
</Tabs>


# TermoTracing (/docs/servicos/tracing)

> Rastreamento de navegação e erros dos sites e sistemas da Termotubos. O script instalado em cada site envia lotes de eventos para POST /evento/ingestao com a chave pública do aplicativo, sem token; o…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Rastreamento de navegação e erros dos sites e sistemas da Termotubos. O script instalado em cada site envia lotes de eventos para `POST /evento/ingestao` com a chave pública do aplicativo, sem token; o resto da API é o painel (aplicativos, sessões, eventos, erros agrupados, uso mensal e administração dos acessos dos colaboradores) e usa o token do usuário logado no TermoAuth. O webhook `POST /webhooks/termowebhook` é chamado pelo TermoWebhook com os eventos de colaborador do TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::tracing` (feature `tracing`) |
| Importação TypeScript | `termo_core/tracing` ou `import { tracing } from "termo_core"` |
| Funções | 59 |
| Entidades | 11 |
| Versão do contrato | `0.1.9` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51111` |
| `SANDBOX` | `https://sandbox-api-tracing.termotubos.com.br` |
| `PRODUCTION` | `https://api-tracing.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Aplicativo" href="/docs/servicos/tracing/aplicativo" description="7 funções" />
  <Card title="Erro" href="/docs/servicos/tracing/erro" description="7 funções" />
  <Card title="Evento" href="/docs/servicos/tracing/evento" description="7 funções" />
  <Card title="Sessão" href="/docs/servicos/tracing/sessao" description="7 funções" />
  <Card title="Uso" href="/docs/servicos/tracing/uso" description="7 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/tracing/auth" description="8 funções" />
  <Card title="Colaborador" href="/docs/servicos/tracing/colaborador" description="5 funções" />
  <Card title="Configuração" href="/docs/servicos/tracing/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/tracing/perfil_acesso" description="7 funções" />
  <Card title="Teste" href="/docs/servicos/tracing/test" description="1 função" />
  <Card title="Webhooks" href="/docs/servicos/tracing/webhooks" description="1 função" />
</Cards>


# Perfil acesso (/docs/servicos/tracing/perfil_acesso)

> 7 funções do TermoTracing para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso com paginação |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcesso>` · Rust: `Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>` · veja [`PaginaPerfilAcesso`](#tipo-paginaperfilacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoTracing dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`rastreamento`, `aplicativos`, `colaboradores`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoComplete`](#tipo-paginaperfilacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/tracing";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcesso [#tipo-paginaperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcesso } from "termo_core/tracing";

export interface PaginaPerfilAcesso {
  itens: Array<PaginaPerfilAcessoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaPerfilAcesso;

pub struct PaginaPerfilAcesso {
    pub itens: Vec<PaginaPerfilAcessoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoComplete [#tipo-paginaperfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoComplete } from "termo_core/tracing";

export interface PaginaPerfilAcessoAutoComplete {
  itens: Array<PaginaPerfilAcessoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaPerfilAcessoAutoComplete;

pub struct PaginaPerfilAcessoAutoComplete {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteItensItem [#tipo-paginaperfilacessoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaPerfilAcessoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaPerfilAcessoAutoCompleteItensItem;

pub struct PaginaPerfilAcessoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoItensItem [#tipo-paginaperfilacessoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoItensItem } from "termo_core/tracing";

export interface PaginaPerfilAcessoItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaPerfilAcessoItensItem;

pub struct PaginaPerfilAcessoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/tracing";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/tracing";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/tracing";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/tracing";

export interface Permissoes {
  aplicativos?: Acoes;
  colaboradores?: Acoes;
  rastreamento?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub rastreamento: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Sessão (/docs/servicos/tracing/sessao)

> 7 funções do TermoTracing para sessão.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_sessao`](#buscar_paginador_sessao) | `GET /sessao` | Lista as sessões paginadas |
| [`criar_sessao`](#criar_sessao) | `POST /sessao` | Cadastra uma sessão |
| [`buscar_auto_complete_sessao`](#buscar_auto_complete_sessao) | `GET /sessao/autocomplete` | Lista básica de sessões para seleção |
| [`buscar_pelo_filtro_sessao`](#buscar_pelo_filtro_sessao) | `GET /sessao/filtro` | Busca sessões por filtro |
| [`buscar_pelo_id_sessao`](#buscar_pelo_id_sessao) | `GET /sessao/{id}` | Busca uma sessão pelo id |
| [`atualizar_pelo_id_sessao`](#atualizar_pelo_id_sessao) | `PATCH /sessao/{id}` | Atualiza uma sessão pelo id |
| [`deletar_pelo_id_sessao`](#deletar_pelo_id_sessao) | `DELETE /sessao/{id}` | Exclui uma sessão pelo id |

## `buscar_paginador_sessao` [#buscar_paginador_sessao]

<Rota metodo="GET" caminho="/sessao" credencial />

Lista as sessões paginadas

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Lista as sessões não excluídas da conta, da mais recente para a mais antiga. `aplicativo_id` filtra pelo aplicativo. `pagina` começa em 1 (padrão 1; menor que 1 vira 1). A página tem sempre 50 itens: o parâmetro `tamanho` é aceito, mas ignorado. A resposta traz `itens`, `total` (quantidade de registros que casam com os filtros), `pagina` e `tamanho` (50). Parâmetros de consulta, todos opcionais: `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: aceito, mas ignorado: a página tem sempre 50 itens; `aplicativo_id`: id do aplicativo (opcional).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorSessao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSessao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_sessao(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorSessao,
) -> Result<tipos::PaginaSessao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_sessao(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorSessao { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSessao>` · Rust: `Result<tipos::PaginaSessao, ErroAoChamarServico>` · veja [`PaginaSessao`](#tipo-paginasessao).

## `criar_sessao` [#criar_sessao]

<Rota metodo="POST" caminho="/sessao" credencial />

Cadastra uma sessão

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Grava uma sessão de navegação de um aplicativo da conta (as sessões normalmente nascem sozinhas na ingestão). `aplicativo_id` precisa ser de um aplicativo da conta; `sessao_externa` e `anonimo_id` são obrigatórios e não podem ficar vazios. `navegador`, `sistema_operacional`, `dispositivo`, `resolucao` e `pais` têm padrão `DESCONHECIDO`; `pagina_inicial` tem padrão vazio. Campos do corpo: `aplicativo_id`: id de um aplicativo da conta (obrigatório); `sessao_externa`: identificador da sessão no navegador (obrigatório, não pode ficar vazio); `anonimo_id`: identificador anônimo do visitante (obrigatório, não pode ficar vazio); `usuario_id`: id do usuário logado no site (opcional); `navegador`: navegador (padrão `DESCONHECIDO`); `sistema_operacional`: sistema operacional (padrão `DESCONHECIDO`); `dispositivo`: tipo de dispositivo (padrão `DESCONHECIDO`); `resolucao`: resolução da tela (padrão `DESCONHECIDO`); `pais`: código do país com duas letras (padrão `DESCONHECIDO`); `pagina_inicial`: endereço da primeira página (padrão vazio).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.SessaoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Sessao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_sessao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::SessaoCriar,
) -> Result<tipos::Sessao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::criar_sessao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.SessaoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SessaoCriar", typeDescriptionLink: "#tipo-sessaocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Sessao>` · Rust: `Result<tipos::Sessao, ErroAoChamarServico>` · veja [`Sessao`](#tipo-sessao).

## `buscar_auto_complete_sessao` [#buscar_auto_complete_sessao]

<Rota metodo="GET" caminho="/sessao/autocomplete" credencial />

Lista básica de sessões para seleção

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve só id e rótulo (`usuario_id` ou, sem ele, `anonimo_id`, mais a data e hora de início em UTC, no formato `DD/MM/AAAA HH:MM`), em ordem alfabética do rótulo. `busca` procura o trecho no rótulo, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`. Parâmetros de consulta, todos opcionais: `busca`: trecho do rótulo (usuário ou identificador anônimo e data de início), sem diferenciar maiúsculas (opcional); `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: itens por página (padrão 10, sem máximo; menor que 1 vira 1).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteSessao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSessaoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_sessao(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteSessao,
) -> Result<tipos::PaginaSessaoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_sessao(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteSessao { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSessaoAutoComplete>` · Rust: `Result<tipos::PaginaSessaoAutoComplete, ErroAoChamarServico>` · veja [`PaginaSessaoAutoComplete`](#tipo-paginasessaoautocomplete).

## `buscar_pelo_filtro_sessao` [#buscar_pelo_filtro_sessao]

<Rota metodo="GET" caminho="/sessao/filtro" credencial />

Busca sessões por filtro

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve todas as sessões não excluídas da conta que casam com o filtro, sem paginação, da mais recente para a mais antiga (`iniciada_em`). `usuario_id`, `anonimo_id`, `navegador` e `pais` comparam o valor exato, sem diferenciar maiúsculas; `com_erro` filtra quem teve (ou não) ao menos um erro; `inicio` e `fim` (data e hora ISO 8601) limitam o `iniciada_em`. Sem filtro, devolve todas. Parâmetros de consulta, todos opcionais: `aplicativo_id`: id do aplicativo; `usuario_id`: id do usuário logado no site (valor exato, sem diferenciar maiúsculas); `anonimo_id`: identificador anônimo do visitante (valor exato, sem diferenciar maiúsculas); `navegador`: navegador (valor exato, sem diferenciar maiúsculas); `pais`: código do país com duas letras (sem diferenciar maiúsculas); `com_erro`: `true` só sessões com algum erro; `false` só sessões sem erro; `inicio`: sessões iniciadas a partir desta data e hora ISO 8601, por exemplo 2026-10-07T00:00:00Z; `fim`: sessões iniciadas até esta data e hora ISO 8601.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroSessao = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Sessao>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_sessao(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroSessao,
) -> Result<Vec<tipos::Sessao>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_sessao(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroSessao { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.usuario_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.anonimo_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.navegador": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pais": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.com_erro": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.inicio": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "parametros.fim": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Sessao>>` · Rust: `Result<Vec<tipos::Sessao>, ErroAoChamarServico>`

## `buscar_pelo_id_sessao` [#buscar_pelo_id_sessao]

<Rota metodo="GET" caminho="/sessao/{id}" credencial />

Busca uma sessão pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve a sessão pelo id; registro excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Sessao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_sessao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Sessao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_sessao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Sessao>` · Rust: `Result<tipos::Sessao, ErroAoChamarServico>` · veja [`Sessao`](#tipo-sessao).

## `atualizar_pelo_id_sessao` [#atualizar_pelo_id_sessao]

<Rota metodo="PATCH" caminho="/sessao/{id}" credencial />

Atualiza uma sessão pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Atualização parcial: só os campos enviados mudam. Muda `usuario_id`, `pais` e `tempo_carregamento_ms` (em milissegundos) e marca a última atividade como agora. Campos do corpo, todos opcionais: `usuario_id`: novo id do usuário logado no site; `pais`: novo código do país com duas letras; `tempo_carregamento_ms`: tempo de carregamento da página inicial, em milissegundos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.SessaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Sessao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_sessao(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::SessaoAtualizar,
) -> Result<tipos::Sessao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_sessao(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.SessaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SessaoAtualizar", typeDescriptionLink: "#tipo-sessaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Sessao>` · Rust: `Result<tipos::Sessao, ErroAoChamarServico>` · veja [`Sessao`](#tipo-sessao).

## `deletar_pelo_id_sessao` [#deletar_pelo_id_sessao]

<Rota metodo="DELETE" caminho="/sessao/{id}" credencial />

Exclui uma sessão pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Exclusão lógica: o registro some das leituras, mas não é apagado na hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_sessao(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_sessao } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_sessao(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_sessao(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_sessao(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaSessao [#tipo-paginasessao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSessao } from "termo_core/tracing";

export interface PaginaSessao {
  itens: Array<PaginaSessaoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaSessao;

pub struct PaginaSessao {
    pub itens: Vec<PaginaSessaoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSessaoAutoComplete [#tipo-paginasessaoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSessaoAutoComplete } from "termo_core/tracing";

export interface PaginaSessaoAutoComplete {
  itens: Array<PaginaSessaoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaSessaoAutoComplete;

pub struct PaginaSessaoAutoComplete {
    pub itens: Vec<PaginaSessaoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSessaoAutoCompleteItensItem [#tipo-paginasessaoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSessaoAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaSessaoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaSessaoAutoCompleteItensItem;

pub struct PaginaSessaoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaSessaoItensItem [#tipo-paginasessaoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSessaoItensItem } from "termo_core/tracing";

export interface PaginaSessaoItensItem {
  anonimo_id: string;
  aplicativo_id: string;
  conta_id: string;
  dispositivo: string;
  id: string;
  iniciada_em: string;
  navegador: string;
  pagina_inicial: string;
  pais: string;
  quantidade_erros: number;
  quantidade_eventos: number;
  resolucao: string;
  sessao_externa: string;
  sistema_operacional: string;
  tempo_carregamento_ms?: number | null;
  ultima_atividade_em: string;
  usuario_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaSessaoItensItem;

pub struct PaginaSessaoItensItem {
    pub anonimo_id: String,
    pub aplicativo_id: uuid::Uuid,
    pub conta_id: String,
    pub dispositivo: String,
    pub id: uuid::Uuid,
    pub iniciada_em: chrono::DateTime<chrono::Utc>,
    pub navegador: String,
    pub pagina_inicial: String,
    pub pais: String,
    pub quantidade_erros: i64,
    pub quantidade_eventos: i64,
    pub resolucao: String,
    pub sessao_externa: String,
    pub sistema_operacional: String,
    pub tempo_carregamento_ms: Option<i64>,
    pub ultima_atividade_em: chrono::DateTime<chrono::Utc>,
    pub usuario_id: Option<String>,
}
```

</Tab>
</Tabs>

### Sessao [#tipo-sessao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Sessao } from "termo_core/tracing";

export interface Sessao {
  anonimo_id: string;
  aplicativo_id: string;
  conta_id: string;
  dispositivo: string;
  id: string;
  iniciada_em: string;
  navegador: string;
  pagina_inicial: string;
  pais: string;
  quantidade_erros: number;
  quantidade_eventos: number;
  resolucao: string;
  sessao_externa: string;
  sistema_operacional: string;
  tempo_carregamento_ms?: number | null;
  ultima_atividade_em: string;
  usuario_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Sessao;

pub struct Sessao {
    pub anonimo_id: String,
    pub aplicativo_id: uuid::Uuid,
    pub conta_id: String,
    pub dispositivo: String,
    pub id: uuid::Uuid,
    pub iniciada_em: chrono::DateTime<chrono::Utc>,
    pub navegador: String,
    pub pagina_inicial: String,
    pub pais: String,
    pub quantidade_erros: i64,
    pub quantidade_eventos: i64,
    pub resolucao: String,
    pub sessao_externa: String,
    pub sistema_operacional: String,
    pub tempo_carregamento_ms: Option<i64>,
    pub ultima_atividade_em: chrono::DateTime<chrono::Utc>,
    pub usuario_id: Option<String>,
}
```

</Tab>
</Tabs>

### SessaoAtualizar [#tipo-sessaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SessaoAtualizar } from "termo_core/tracing";

export interface SessaoAtualizar {
  pais?: string | null;
  tempo_carregamento_ms?: number | null;
  usuario_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::SessaoAtualizar;

pub struct SessaoAtualizar {
    pub pais: Option<String>,
    pub tempo_carregamento_ms: Option<i64>,
    pub usuario_id: Option<String>,
}
```

</Tab>
</Tabs>

### SessaoCriar [#tipo-sessaocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SessaoCriar } from "termo_core/tracing";

export interface SessaoCriar {
  anonimo_id: string;
  aplicativo_id: string;
  dispositivo?: string;
  navegador?: string;
  pagina_inicial?: string;
  pais?: string;
  resolucao?: string;
  sessao_externa: string;
  sistema_operacional?: string;
  usuario_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::SessaoCriar;

pub struct SessaoCriar {
    pub anonimo_id: String,
    pub aplicativo_id: uuid::Uuid,
    pub dispositivo: Option<String>,
    pub navegador: Option<String>,
    pub pagina_inicial: Option<String>,
    pub pais: Option<String>,
    pub resolucao: Option<String>,
    pub sessao_externa: String,
    pub sistema_operacional: Option<String>,
    pub usuario_id: Option<String>,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/tracing/test)

> 1 função do TermoTracing para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token e sem chave de aplicativo. Responde `200` com `sucesso: true`, `mensagem` e `versao` (a versão do backend no ar, em semver) sempre que o servidor está de pé; não consulta o banco nem o TermoAuth. É a rota que o deploy consulta depois de reiniciar o serviço.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/tracing";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::tracing::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/tracing";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>


# Uso (/docs/servicos/tracing/uso)

> 7 funções do TermoTracing para uso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_uso`](#buscar_paginador_uso) | `GET /uso` | Lista os registros de uso paginados |
| [`criar_uso`](#criar_uso) | `POST /uso` | Cadastra um registro de uso |
| [`buscar_auto_complete_uso`](#buscar_auto_complete_uso) | `GET /uso/autocomplete` | Lista básica de registros de uso para seleção |
| [`buscar_pelo_filtro_uso`](#buscar_pelo_filtro_uso) | `GET /uso/filtro` | Busca registros de uso por filtro |
| [`buscar_pelo_id_uso`](#buscar_pelo_id_uso) | `GET /uso/{id}` | Busca um registro de uso pelo id |
| [`atualizar_pelo_id_uso`](#atualizar_pelo_id_uso) | `PATCH /uso/{id}` | Atualiza um registro de uso pelo id |
| [`deletar_pelo_id_uso`](#deletar_pelo_id_uso) | `DELETE /uso/{id}` | Exclui um registro de uso pelo id |

## `buscar_paginador_uso` [#buscar_paginador_uso]

<Rota metodo="GET" caminho="/uso" credencial />

Lista os registros de uso paginados

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Lista os registros de uso diário não excluídos da conta, do dia mais recente para o mais antigo. `ciclo` (`AAAA-MM`) filtra pelo mês e `aplicativo_id` pelo aplicativo. `pagina` começa em 1 (padrão 1; menor que 1 vira 1). A página tem sempre 50 itens: o parâmetro `tamanho` é aceito, mas ignorado. A resposta traz `itens`, `total` (quantidade de registros que casam com os filtros), `pagina` e `tamanho` (50). Parâmetros de consulta, todos opcionais: `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: aceito, mas ignorado: a página tem sempre 50 itens; `ciclo`: ciclo mensal exato, no formato AAAA-MM (opcional); `aplicativo_id`: id do aplicativo (opcional).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_uso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorUso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaUso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_uso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorUso,
) -> Result<tipos::PaginaUso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_paginador_uso(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPaginadorUso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.ciclo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaUso>` · Rust: `Result<tipos::PaginaUso, ErroAoChamarServico>` · veja [`PaginaUso`](#tipo-paginauso).

## `criar_uso` [#criar_uso]

<Rota metodo="POST" caminho="/uso" credencial />

Cadastra um registro de uso

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Soma eventos aceitos e recusados ao uso diário de um aplicativo da conta (o uso normalmente é contado sozinho pela ingestão). `aplicativo_id` precisa ser de um aplicativo da conta; `dia` é obrigatório, no formato `AAAA-MM-DD`; `eventos_aceitos` e `eventos_recusados` têm padrão 0. Se já existe o registro daquele aplicativo naquele dia, os valores enviados são somados aos atuais e o registro existente é devolvido. O `ciclo` é o mês do dia (`AAAA-MM`). Campos do corpo: `aplicativo_id`: id de um aplicativo da conta (obrigatório); `dia`: dia no formato AAAA-MM-DD (obrigatório); `eventos_aceitos`: eventos aceitos a somar (padrão 0); `eventos_recusados`: eventos recusados a somar (padrão 0).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_uso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.UsoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Uso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_uso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::UsoCriar,
) -> Result<tipos::Uso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::criar_uso(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.UsoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::UsoCriar", typeDescriptionLink: "#tipo-usocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Uso>` · Rust: `Result<tipos::Uso, ErroAoChamarServico>` · veja [`Uso`](#tipo-uso).

## `buscar_auto_complete_uso` [#buscar_auto_complete_uso]

<Rota metodo="GET" caminho="/uso/autocomplete" credencial />

Lista básica de registros de uso para seleção

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve só id e rótulo (nome do aplicativo e dia), ordenados por ciclo e dia. `busca` procura o trecho no ciclo (`AAAA-MM`), sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. A resposta traz `itens`, `total`, `pagina` e `tamanho`. Parâmetros de consulta, todos opcionais: `busca`: trecho do ciclo (AAAA-MM), sem diferenciar maiúsculas (opcional); `pagina`: número da página, começando em 1 (padrão 1; menor que 1 vira 1); `tamanho`: itens por página (padrão 10, sem máximo; menor que 1 vira 1).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_uso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteUso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaUsoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_uso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteUso,
) -> Result<tipos::PaginaUsoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_auto_complete_uso(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarAutoCompleteUso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaUsoAutoComplete>` · Rust: `Result<tipos::PaginaUsoAutoComplete, ErroAoChamarServico>` · veja [`PaginaUsoAutoComplete`](#tipo-paginausoautocomplete).

## `buscar_pelo_filtro_uso` [#buscar_pelo_filtro_uso]

<Rota metodo="GET" caminho="/uso/filtro" credencial />

Busca registros de uso por filtro

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve todos os registros de uso diário não excluídos da conta que casam com o filtro, sem paginação, do dia mais antigo para o mais recente. `aplicativo_id` filtra pelo aplicativo; `ciclo` (`AAAA-MM`) pelo mês; `dia_inicial` e `dia_final` (`AAAA-MM-DD`) limitam o dia. Sem filtro, devolve todos. Parâmetros de consulta, todos opcionais: `aplicativo_id`: id do aplicativo; `ciclo`: ciclo mensal exato, no formato AAAA-MM; `dia_inicial`: primeiro dia, no formato AAAA-MM-DD; `dia_final`: último dia, no formato AAAA-MM-DD.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_uso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroUso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Uso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_uso(credencial_de_acesso, { aplicativo_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroUso,
) -> Result<Vec<tipos::Uso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_filtro_uso(
    &credencial_de_acesso,
    &termo_core::tracing::ParametrosDeBuscarPeloFiltroUso { aplicativo_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ciclo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.dia_inicial": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.dia_final": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Uso>>` · Rust: `Result<Vec<tipos::Uso>, ErroAoChamarServico>`

## `buscar_pelo_id_uso` [#buscar_pelo_id_uso]

<Rota metodo="GET" caminho="/uso/{id}" credencial />

Busca um registro de uso pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Devolve o registro de uso pelo id; registro excluído não é encontrado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_uso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Uso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_uso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Uso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::buscar_pelo_id_uso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Uso>` · Rust: `Result<tipos::Uso, ErroAoChamarServico>` · veja [`Uso`](#tipo-uso).

## `atualizar_pelo_id_uso` [#atualizar_pelo_id_uso]

<Rota metodo="PATCH" caminho="/uso/{id}" credencial />

Atualiza um registro de uso pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Atualização parcial: só os campos enviados mudam. Substitui `eventos_aceitos` e/ou `eventos_recusados` pelos valores enviados. Campos do corpo, todos opcionais: `eventos_aceitos`: novo total de eventos aceitos no dia; `eventos_recusados`: novo total de eventos recusados no dia.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_uso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.UsoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Uso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_uso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::UsoAtualizar,
) -> Result<tipos::Uso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::tracing::atualizar_pelo_id_uso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.UsoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::UsoAtualizar", typeDescriptionLink: "#tipo-usoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Uso>` · Rust: `Result<tipos::Uso, ErroAoChamarServico>` · veja [`Uso`](#tipo-uso).

## `deletar_pelo_id_uso` [#deletar_pelo_id_uso]

<Rota metodo="DELETE" caminho="/uso/{id}" credencial />

Exclui um registro de uso pelo id

Qualquer colaborador da Termotubos logado no TermoAuth (perfil `employee`); não há área de permissão própria. Cada conta só enxerga e altera os próprios registros (os do `sub` do token): registro de outra conta responde como não encontrado. Exclusão lógica: o registro some das leituras, mas não é apagado na hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_uso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_uso } from "termo_core/tracing";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_uso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_uso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::tracing::deletar_pelo_id_uso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaUso [#tipo-paginauso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUso } from "termo_core/tracing";

export interface PaginaUso {
  itens: Array<PaginaUsoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaUso;

pub struct PaginaUso {
    pub itens: Vec<PaginaUsoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaUsoAutoComplete [#tipo-paginausoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsoAutoComplete } from "termo_core/tracing";

export interface PaginaUsoAutoComplete {
  itens: Array<PaginaUsoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaUsoAutoComplete;

pub struct PaginaUsoAutoComplete {
    pub itens: Vec<PaginaUsoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaUsoAutoCompleteItensItem [#tipo-paginausoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsoAutoCompleteItensItem } from "termo_core/tracing";

export interface PaginaUsoAutoCompleteItensItem {
  id: string;
  rotulo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaUsoAutoCompleteItensItem;

pub struct PaginaUsoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub rotulo: String,
}
```

</Tab>
</Tabs>

### PaginaUsoItensItem [#tipo-paginausoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaUsoItensItem } from "termo_core/tracing";

export interface PaginaUsoItensItem {
  aplicativo_id: string;
  aplicativo_nome: string;
  atualizado_em: string;
  ciclo: string;
  conta_id: string;
  criado_em: string;
  dia: string;
  eventos_aceitos: number;
  eventos_recusados: number;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::PaginaUsoItensItem;

pub struct PaginaUsoItensItem {
    pub aplicativo_id: uuid::Uuid,
    pub aplicativo_nome: String,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub ciclo: String,
    pub conta_id: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub dia: String,
    pub eventos_aceitos: i64,
    pub eventos_recusados: i64,
    pub id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### Uso [#tipo-uso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Uso } from "termo_core/tracing";

export interface Uso {
  aplicativo_id: string;
  aplicativo_nome: string;
  atualizado_em: string;
  ciclo: string;
  conta_id: string;
  criado_em: string;
  dia: string;
  eventos_aceitos: number;
  eventos_recusados: number;
  id: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::Uso;

pub struct Uso {
    pub aplicativo_id: uuid::Uuid,
    pub aplicativo_nome: String,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub ciclo: String,
    pub conta_id: String,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub dia: String,
    pub eventos_aceitos: i64,
    pub eventos_recusados: i64,
    pub id: uuid::Uuid,
}
```

</Tab>
</Tabs>

### UsoAtualizar [#tipo-usoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UsoAtualizar } from "termo_core/tracing";

export interface UsoAtualizar {
  eventos_aceitos?: number | null;
  eventos_recusados?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::UsoAtualizar;

pub struct UsoAtualizar {
    pub eventos_aceitos: Option<i64>,
    pub eventos_recusados: Option<i64>,
}
```

</Tab>
</Tabs>

### UsoCriar [#tipo-usocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { UsoCriar } from "termo_core/tracing";

export interface UsoCriar {
  aplicativo_id: string;
  dia: string;
  eventos_aceitos?: number;
  eventos_recusados?: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::UsoCriar;

pub struct UsoCriar {
    pub aplicativo_id: uuid::Uuid,
    pub dia: String,
    pub eventos_aceitos: Option<i64>,
    pub eventos_recusados: Option<i64>,
}
```

</Tab>
</Tabs>


# Webhooks (/docs/servicos/tracing/webhooks)

> 1 função do TermoTracing para webhooks.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as tracing from "termo_core/tracing";
// ou: import { tracing } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["tracing"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`receber_evento_termo_webhook_webhooks`](#receber_evento_termo_webhook_webhooks) | `POST /webhooks/termowebhook` | Recebe as entregas do TermoWebhook |

## `receber_evento_termo_webhook_webhooks` [#receber_evento_termo_webhook_webhooks]

<Rota metodo="POST" caminho="/webhooks/termowebhook" />

Recebe as entregas do TermoWebhook

Pública, sem token do usuário: é chamada pelo TermoWebhook, o hub de eventos da Termotubos, para entregar os eventos que o TermoTracing assina. A entrega é conferida pela assinatura Ed25519 do hub (chave pública em `/.well-known/jwks.json` do TermoWebhook), pela data e pelo destino, que precisa ser o próprio TermoTracing. Eventos tratados: `colaborador.criado` e `colaborador.atualizado`, versões 1 e 2, publicados pelo TermoAuth: criam ou atualizam o colaborador e o acesso dele (a v2 também traz setor, cargo e função), descartando o evento mais antigo que o último aplicado. Qualquer outro tipo responde `200` sem fazer nada. Como o hub entrega pelo menos uma vez, repetir o mesmo evento é seguro.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_termo_webhook_webhooks(
  parametros: ParametrosDeReceberEventoTermoWebhookWebhooks,
  corpo_da_requisicao: tipos.EntregaDoTermoWebhook,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { receber_evento_termo_webhook_webhooks } from "termo_core/tracing";

await receber_evento_termo_webhook_webhooks({ "X-TermoWebhook-Data": 1, "X-TermoWebhook-Chave": "...", "X-TermoWebhook-Destino": "...", "X-TermoWebhook-Assinatura": "..." }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_termo_webhook_webhooks(
    parametros: &ParametrosDeReceberEventoTermoWebhookWebhooks,
    corpo_da_requisicao: &tipos::EntregaDoTermoWebhook,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::tracing::receber_evento_termo_webhook_webhooks(
    &termo_core::tracing::ParametrosDeReceberEventoTermoWebhookWebhooks { x_termo_webhook_data, x_termo_webhook_chave, x_termo_webhook_destino, x_termo_webhook_assinatura },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.X-TermoWebhook-Data": { type: "number", required: true, description: "Horário Unix em segundos usado na assinatura\n\nEnviado no cabeçalho X-TermoWebhook-Data. · Rust: i64" },
    "parametros.X-TermoWebhook-Chave": { type: "string", required: true, description: "Id (kid) da chave do hub que assinou a entrega\n\nEnviado no cabeçalho X-TermoWebhook-Chave. · Rust: String" },
    "parametros.X-TermoWebhook-Destino": { type: "string", required: true, description: "Id do aplicativo destino no hub, que precisa ser o do TermoTracing\n\nEnviado no cabeçalho X-TermoWebhook-Destino. · Rust: String" },
    "parametros.X-TermoWebhook-Assinatura": { type: "string", required: true, description: "ed25519=<base64url> da assinatura de <data>.<destino>.<corpo>\n\nEnviado no cabeçalho X-TermoWebhook-Assinatura. · Rust: String" },
    "corpo_da_requisicao": { type: "tipos.EntregaDoTermoWebhook", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EntregaDoTermoWebhook", typeDescriptionLink: "#tipo-entregadotermowebhook" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EntregaDoTermoWebhook [#tipo-entregadotermowebhook]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaDoTermoWebhook } from "termo_core/tracing";

export interface EntregaDoTermoWebhook {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::tracing::EntregaDoTermoWebhook;

pub struct EntregaDoTermoWebhook {
    pub dados: serde_json::Map<String, serde_json::Value>,
    pub entidade_id: String,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>


# Aplicativo (/docs/servicos/webhook/aplicativo)

> 4 funções do TermoWebhook para aplicativo.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_aplicativo`](#buscar_paginador_aplicativo) | `GET /aplicativo` | Lista os aplicativos paginados |
| [`buscar_auto_complete_aplicativo`](#buscar_auto_complete_aplicativo) | `GET /aplicativo/autocomplete` | Lista básica de aplicativos para seleção |
| [`buscar_pelo_filtro_aplicativo`](#buscar_pelo_filtro_aplicativo) | `GET /aplicativo/filtro` | Busca aplicativos por filtro |
| [`buscar_pelo_id_aplicativo`](#buscar_pelo_id_aplicativo) | `GET /aplicativo/{id}` | Busca um aplicativo pelo id |

## `buscar_paginador_aplicativo` [#buscar_paginador_aplicativo]

<Rota metodo="GET" caminho="/aplicativo" credencial />

Lista os aplicativos paginados

Leitura liberada a quem tem a permissão `ler` em `aplicativos`, `contratos`, `assinaturas` ou `monitoramento`. Antes de listar, sincroniza com os apps do TermoAuth pelo `termo_core` (token de quem chama, se for master; senão o token de aplicativo do TermoWebhook, se o segredo do app estiver cadastrado): app novo entra ativo, nome e descrição seguem os do TermoAuth, e app que saiu do TermoAuth é excluído ou, se ainda é dono de tipos de evento ou tem assinaturas, fica inativo. Falha do TermoAuth não impede a listagem. Não existe criar, editar nem excluir aplicativo no TermoWebhook. Lista os aplicativos não excluídos em ordem alfabética do nome. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de aplicativos não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_aplicativo } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_aplicativo(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAplicativo,
) -> Result<tipos::PaginaAplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_aplicativo(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorAplicativo { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativo>` · Rust: `Result<tipos::PaginaAplicativo, ErroAoChamarServico>` · veja [`PaginaAplicativo`](#tipo-paginaaplicativo).

## `buscar_auto_complete_aplicativo` [#buscar_auto_complete_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/autocomplete" credencial />

Lista básica de aplicativos para seleção

Leitura liberada a quem tem a permissão `ler` em `aplicativos`, `contratos`, `assinaturas` ou `monitoramento`, para escolher o dono de um tipo de evento ou o assinante de uma assinatura. Devolve só id, nome e `ativo`, em ordem alfabética do nome, sem os excluídos. `busca` procura o trecho no nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAplicativoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_aplicativo } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_aplicativo(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAplicativo,
) -> Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_aplicativo(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompleteAplicativo { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAplicativoAutoComplete>` · Rust: `Result<tipos::PaginaAplicativoAutoComplete, ErroAoChamarServico>` · veja [`PaginaAplicativoAutoComplete`](#tipo-paginaaplicativoautocomplete).

## `buscar_pelo_filtro_aplicativo` [#buscar_pelo_filtro_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/filtro" credencial />

Busca aplicativos por filtro

Leitura liberada a quem tem a permissão `ler` em `aplicativos`, `contratos`, `assinaturas` ou `monitoramento`. Devolve todos os aplicativos não excluídos que casam com o filtro, sem paginação, em ordem alfabética do nome. `nome` procura o trecho no nome e na descrição, sem diferenciar maiúsculas; `ativo` filtra pela situação. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAplicativo = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Aplicativo>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_aplicativo } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_aplicativo(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAplicativo,
) -> Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_aplicativo(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroAplicativo { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Aplicativo>>` · Rust: `Result<Vec<tipos::Aplicativo>, ErroAoChamarServico>`

## `buscar_pelo_id_aplicativo` [#buscar_pelo_id_aplicativo]

<Rota metodo="GET" caminho="/aplicativo/{id}" credencial />

Busca um aplicativo pelo id

Leitura liberada a quem tem a permissão `ler` em `aplicativos`, `contratos`, `assinaturas` ou `monitoramento`. Aplicativo excluído não é encontrado. Os aplicativos são do TermoAuth e aqui são só leitura: `identificador_no_termoauth` é o id do app no TermoAuth (o `sub` do token de aplicativo) e não muda. `quantidade_de_tipos_de_evento` conta os tipos de que o aplicativo é dono e `quantidade_de_assinaturas` as assinaturas em que ele é o assinante.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_aplicativo(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Aplicativo>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_aplicativo } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_aplicativo(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_aplicativo(
    credencial_de_acesso: &CredencialDeAcesso,
    id: &str,
) -> Result<tipos::Aplicativo, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_aplicativo(&credencial_de_acesso, &id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: &str" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Aplicativo>` · Rust: `Result<tipos::Aplicativo, ErroAoChamarServico>` · veja [`Aplicativo`](#tipo-aplicativo).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Aplicativo [#tipo-aplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Aplicativo } from "termo_core/webhook";

export interface Aplicativo {
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao?: string | null;
  id: string;
  identificador_no_termoauth: string;
  nome: string;
  quantidade_de_assinaturas: number;
  quantidade_de_tipos_de_evento: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Aplicativo;

pub struct Aplicativo {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: String,
    pub identificador_no_termoauth: String,
    pub nome: String,
    pub quantidade_de_assinaturas: i64,
    pub quantidade_de_tipos_de_evento: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativo [#tipo-paginaaplicativo]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativo } from "termo_core/webhook";

export interface PaginaAplicativo {
  itens: Array<PaginaAplicativoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAplicativo;

pub struct PaginaAplicativo {
    pub itens: Vec<PaginaAplicativoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoComplete [#tipo-paginaaplicativoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoComplete } from "termo_core/webhook";

export interface PaginaAplicativoAutoComplete {
  itens: Array<PaginaAplicativoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAplicativoAutoComplete;

pub struct PaginaAplicativoAutoComplete {
    pub itens: Vec<PaginaAplicativoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAplicativoAutoCompleteItensItem [#tipo-paginaaplicativoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaAplicativoAutoCompleteItensItem {
  ativo: boolean;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAplicativoAutoCompleteItensItem;

pub struct PaginaAplicativoAutoCompleteItensItem {
    pub ativo: bool,
    pub id: String,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaAplicativoItensItem [#tipo-paginaaplicativoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAplicativoItensItem } from "termo_core/webhook";

export interface PaginaAplicativoItensItem {
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao?: string | null;
  id: string;
  identificador_no_termoauth: string;
  nome: string;
  quantidade_de_assinaturas: number;
  quantidade_de_tipos_de_evento: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAplicativoItensItem;

pub struct PaginaAplicativoItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: String,
    pub identificador_no_termoauth: String,
    pub nome: String,
    pub quantidade_de_assinaturas: i64,
    pub quantidade_de_tipos_de_evento: i64,
}
```

</Tab>
</Tabs>


# Assinatura (/docs/servicos/webhook/assinatura)

> 7 funções do TermoWebhook para assinatura.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_assinatura`](#buscar_paginador_assinatura) | `GET /assinatura` | Lista as assinaturas paginadas |
| [`criar_assinatura`](#criar_assinatura) | `POST /assinatura` | Cadastra uma assinatura |
| [`buscar_auto_complete_assinatura`](#buscar_auto_complete_assinatura) | `GET /assinatura/autocomplete` | Lista básica de assinaturas para seleção |
| [`buscar_pelo_filtro_assinatura`](#buscar_pelo_filtro_assinatura) | `GET /assinatura/filtro` | Busca assinaturas por filtro |
| [`buscar_pelo_id_assinatura`](#buscar_pelo_id_assinatura) | `GET /assinatura/{id}` | Busca uma assinatura pelo id |
| [`atualizar_pelo_id_assinatura`](#atualizar_pelo_id_assinatura) | `PATCH /assinatura/{id}` | Atualiza uma assinatura pelo id |
| [`deletar_pelo_id_assinatura`](#deletar_pelo_id_assinatura) | `DELETE /assinatura/{id}` | Exclui uma assinatura pelo id |

## `buscar_paginador_assinatura` [#buscar_paginador_assinatura]

<Rota metodo="GET" caminho="/assinatura" credencial />

Lista as assinaturas paginadas

Leitura liberada a quem tem a permissão `ler` em `assinaturas` ou `monitoramento`. Lista as assinaturas não excluídas, ordenadas pelo nome do aplicativo assinante e depois pelo nome do tipo de evento. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de assinaturas não excluídas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAssinatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAssinatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_assinatura(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAssinatura,
) -> Result<tipos::PaginaAssinatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_assinatura(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorAssinatura { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAssinatura>` · Rust: `Result<tipos::PaginaAssinatura, ErroAoChamarServico>` · veja [`PaginaAssinatura`](#tipo-paginaassinatura).

## `criar_assinatura` [#criar_assinatura]

<Rota metodo="POST" caminho="/assinatura" credencial />

Cadastra uma assinatura

Exige a permissão `criar` na área `assinaturas`. Inscreve um aplicativo para receber os eventos de um tipo numa versão do esquema: cada evento aceito dali em diante nessa versão vira uma entrega para `url_de_destino`. O aplicativo assinante e o tipo de evento precisam existir, e a versão precisa existir para o tipo e não estar desligada. Cada aplicativo assina um tipo uma vez só; para mudar de versão, atualize a assinatura existente. `url_de_destino` tem até 500 caracteres e precisa ser `https` (`http` só para localhost). `maximo_de_tentativas` vai de 1 a 20 e `tempo_limite_em_segundos` de 1 a 30 (padrão 5 em ambos); `ativa` tem padrão `true`. Não há segredo por assinatura: o hub assina cada entrega com a chave dele (Ed25519, chaves públicas em `GET /.well-known/jwks.json`) e o assinante confere só com a URL do hub e o id do próprio aplicativo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AssinaturaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Assinatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_assinatura(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AssinaturaCriar,
) -> Result<tipos::Assinatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_assinatura(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AssinaturaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AssinaturaCriar", typeDescriptionLink: "#tipo-assinaturacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Assinatura>` · Rust: `Result<tipos::Assinatura, ErroAoChamarServico>` · veja [`Assinatura`](#tipo-assinatura).

## `buscar_auto_complete_assinatura` [#buscar_auto_complete_assinatura]

<Rota metodo="GET" caminho="/assinatura/autocomplete" credencial />

Lista básica de assinaturas para seleção

Leitura liberada a quem tem a permissão `ler` em `assinaturas` ou `monitoramento`, por exemplo para escolher a assinatura de um reprocessamento. Devolve só id, nomes do assinante e do tipo, versão e `ativa`, ordenados pelo nome do aplicativo assinante e depois pelo nome do tipo, sem as excluídas. `busca` procura o trecho no nome do aplicativo assinante ou do tipo de evento, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAssinatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAssinaturaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_assinatura(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAssinatura,
) -> Result<tipos::PaginaAssinaturaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_assinatura(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompleteAssinatura { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAssinaturaAutoComplete>` · Rust: `Result<tipos::PaginaAssinaturaAutoComplete, ErroAoChamarServico>` · veja [`PaginaAssinaturaAutoComplete`](#tipo-paginaassinaturaautocomplete).

## `buscar_pelo_filtro_assinatura` [#buscar_pelo_filtro_assinatura]

<Rota metodo="GET" caminho="/assinatura/filtro" credencial />

Busca assinaturas por filtro

Leitura liberada a quem tem a permissão `ler` em `assinaturas` ou `monitoramento`. Devolve todas as assinaturas não excluídas que casam com o filtro, sem paginação, ordenadas pelo nome do aplicativo assinante e depois pelo nome do tipo de evento. `aplicativo_assinante_id`, `tipo_de_evento_id` e `ativa` filtram pelo valor exato. Sem filtro, devolve todas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAssinatura = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Assinatura>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_assinatura(credencial_de_acesso, { aplicativo_assinante_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAssinatura,
) -> Result<Vec<tipos::Assinatura>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_assinatura(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroAssinatura { aplicativo_assinante_id: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.aplicativo_assinante_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_de_evento_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.ativa": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Assinatura>>` · Rust: `Result<Vec<tipos::Assinatura>, ErroAoChamarServico>`

## `buscar_pelo_id_assinatura` [#buscar_pelo_id_assinatura]

<Rota metodo="GET" caminho="/assinatura/{id}" credencial />

Busca uma assinatura pelo id

Leitura liberada a quem tem a permissão `ler` em `assinaturas` ou `monitoramento`. Assinatura excluída não é encontrada. Traz os nomes do aplicativo assinante e do tipo de evento, a situação da versão assinada, quantas entregas estão na fila de erro (tentativas esgotadas) e quando foi a última entrega bem-sucedida.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Assinatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_assinatura(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Assinatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_assinatura(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Assinatura>` · Rust: `Result<tipos::Assinatura, ErroAoChamarServico>` · veja [`Assinatura`](#tipo-assinatura).

## `atualizar_pelo_id_assinatura` [#atualizar_pelo_id_assinatura]

<Rota metodo="PATCH" caminho="/assinatura/{id}" credencial />

Atualiza uma assinatura pelo id

Exige a permissão `editar` na área `assinaturas`. Atualização parcial: só os campos enviados mudam; o aplicativo assinante e o tipo de evento não mudam. `versao_do_esquema` troca a versão assinada e precisa existir para o tipo e não estar desligada (manter a versão atual é sempre aceito). `url_de_destino`, `maximo_de_tentativas` e `tempo_limite_em_segundos` seguem as regras do cadastro. Desativar a assinatura (`ativa: false`) faz ela deixar de receber eventos novos e cancela as entregas pendentes dela na mesma hora.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AssinaturaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Assinatura>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_assinatura(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AssinaturaAtualizar,
) -> Result<tipos::Assinatura, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_assinatura(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AssinaturaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AssinaturaAtualizar", typeDescriptionLink: "#tipo-assinaturaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Assinatura>` · Rust: `Result<tipos::Assinatura, ErroAoChamarServico>` · veja [`Assinatura`](#tipo-assinatura).

## `deletar_pelo_id_assinatura` [#deletar_pelo_id_assinatura]

<Rota metodo="DELETE" caminho="/assinatura/{id}" credencial />

Exclui uma assinatura pelo id

Exige a permissão `deletar` na área `assinaturas`. A exclusão é lógica: a assinatura some das leituras, para de gerar entregas e o aplicativo pode assinar o mesmo tipo de novo, mas o registro não é apagado e não há como restaurar. As entregas pendentes dela são canceladas na mesma hora; o histórico de entregas continua até vencer a retenção.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_assinatura(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_assinatura } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_assinatura(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_assinatura(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::webhook::deletar_pelo_id_assinatura(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Assinatura [#tipo-assinatura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Assinatura } from "termo_core/webhook";

export interface Assinatura {
  aplicativo_assinante_id: string;
  aplicativo_assinante_nome: string;
  ativa: boolean;
  atualizada_em: string;
  criada_em: string;
  entregas_na_fila_de_erro: number;
  id: string;
  maximo_de_tentativas: number;
  situacao_da_versao: string;
  tempo_limite_em_segundos: number;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  ultima_entrega_em?: string | null;
  url_de_destino: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Assinatura;

pub struct Assinatura {
    pub aplicativo_assinante_id: String,
    pub aplicativo_assinante_nome: String,
    pub ativa: bool,
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub entregas_na_fila_de_erro: i64,
    pub id: uuid::Uuid,
    pub maximo_de_tentativas: i32,
    pub situacao_da_versao: String,
    pub tempo_limite_em_segundos: i32,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub ultima_entrega_em: Option<chrono::DateTime<chrono::Utc>>,
    pub url_de_destino: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### AssinaturaAtualizar [#tipo-assinaturaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AssinaturaAtualizar } from "termo_core/webhook";

export interface AssinaturaAtualizar {
  ativa?: boolean | null;
  maximo_de_tentativas?: number | null;
  tempo_limite_em_segundos?: number | null;
  url_de_destino?: string | null;
  versao_do_esquema?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::AssinaturaAtualizar;

pub struct AssinaturaAtualizar {
    pub ativa: Option<bool>,
    pub maximo_de_tentativas: Option<i32>,
    pub tempo_limite_em_segundos: Option<i32>,
    pub url_de_destino: Option<String>,
    pub versao_do_esquema: Option<i32>,
}
```

</Tab>
</Tabs>

### AssinaturaCriar [#tipo-assinaturacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AssinaturaCriar } from "termo_core/webhook";

export interface AssinaturaCriar {
  aplicativo_assinante_id: string;
  ativa?: boolean | null;
  maximo_de_tentativas?: number | null;
  tempo_limite_em_segundos?: number | null;
  tipo_de_evento_id: string;
  url_de_destino: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::AssinaturaCriar;

pub struct AssinaturaCriar {
    pub aplicativo_assinante_id: String,
    pub ativa: Option<bool>,
    pub maximo_de_tentativas: Option<i32>,
    pub tempo_limite_em_segundos: Option<i32>,
    pub tipo_de_evento_id: uuid::Uuid,
    pub url_de_destino: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### PaginaAssinatura [#tipo-paginaassinatura]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAssinatura } from "termo_core/webhook";

export interface PaginaAssinatura {
  itens: Array<PaginaAssinaturaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAssinatura;

pub struct PaginaAssinatura {
    pub itens: Vec<PaginaAssinaturaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAssinaturaAutoComplete [#tipo-paginaassinaturaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAssinaturaAutoComplete } from "termo_core/webhook";

export interface PaginaAssinaturaAutoComplete {
  itens: Array<PaginaAssinaturaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAssinaturaAutoComplete;

pub struct PaginaAssinaturaAutoComplete {
    pub itens: Vec<PaginaAssinaturaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAssinaturaAutoCompleteItensItem [#tipo-paginaassinaturaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAssinaturaAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaAssinaturaAutoCompleteItensItem {
  aplicativo_assinante_nome: string;
  ativa: boolean;
  id: string;
  tipo_de_evento_nome: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAssinaturaAutoCompleteItensItem;

pub struct PaginaAssinaturaAutoCompleteItensItem {
    pub aplicativo_assinante_nome: String,
    pub ativa: bool,
    pub id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### PaginaAssinaturaItensItem [#tipo-paginaassinaturaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAssinaturaItensItem } from "termo_core/webhook";

export interface PaginaAssinaturaItensItem {
  aplicativo_assinante_id: string;
  aplicativo_assinante_nome: string;
  ativa: boolean;
  atualizada_em: string;
  criada_em: string;
  entregas_na_fila_de_erro: number;
  id: string;
  maximo_de_tentativas: number;
  situacao_da_versao: string;
  tempo_limite_em_segundos: number;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  ultima_entrega_em?: string | null;
  url_de_destino: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAssinaturaItensItem;

pub struct PaginaAssinaturaItensItem {
    pub aplicativo_assinante_id: String,
    pub aplicativo_assinante_nome: String,
    pub ativa: bool,
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub entregas_na_fila_de_erro: i64,
    pub id: uuid::Uuid,
    pub maximo_de_tentativas: i32,
    pub situacao_da_versao: String,
    pub tempo_limite_em_segundos: i32,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub ultima_entrega_em: Option<chrono::DateTime<chrono::Utc>>,
    pub url_de_destino: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>


# Auth (/docs/servicos/webhook/auth)

> 8 funções do TermoWebhook para auth.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_auth`](#buscar_paginador_auth) | `GET /auth` | Lista acessos com paginação |
| [`criar_auth`](#criar_auth) | `POST /auth` | Cria um acesso |
| [`buscar_acesso_auth`](#buscar_acesso_auth) | `GET /auth/acesso` | Busca o acesso de quem está logado |
| [`buscar_auto_complete_auth`](#buscar_auto_complete_auth) | `GET /auth/autocomplete` | Lista básica de acessos para seleção |
| [`buscar_pelo_filtro_auth`](#buscar_pelo_filtro_auth) | `GET /auth/filtro` | Busca acessos por filtro |
| [`buscar_pelo_id_auth`](#buscar_pelo_id_auth) | `GET /auth/{id}` | Busca um acesso pelo id |
| [`atualizar_pelo_id_auth`](#atualizar_pelo_id_auth) | `PATCH /auth/{id}` | Atualiza um acesso pelo id |
| [`deletar_pelo_id_auth`](#deletar_pelo_id_auth) | `DELETE /auth/{id}` | Exclui um acesso pelo id |

## `buscar_paginador_auth` [#buscar_paginador_auth]

<Rota metodo="GET" caminho="/auth" credencial />

Lista acessos com paginação

Exige qualquer permissão da área `colaboradores`. Ordena por perfil e depois por e-mail. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10, sem máximo. Acessos excluídos não aparecem nem entram no `total`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_auth(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorAuth,
) -> Result<tipos::PaginaAuth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_auth(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorAuth { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuth>` · Rust: `Result<tipos::PaginaAuth, ErroAoChamarServico>` · veja [`PaginaAuth`](#tipo-paginaauth).

## `criar_auth` [#criar_auth]

<Rota metodo="POST" caminho="/auth" credencial />

Cria um acesso

Exige a permissão `criar` da área `colaboradores`. Cadastra quem pode entrar no TermoWebhook: o e-mail é gravado em minúsculas, sem espaços nas pontas, com até 160 caracteres. O único perfil aceito é `colaborador`. O acesso nasce ativo e sem perfil de acesso. Para a pessoa conseguir entrar, o e-mail precisa ser `@termotubos.com.br` e existir no TermoAuth. O colaborador (nome, setor, cargo e função) não se cadastra aqui: vem só do TermoAuth, pelos eventos do TermoWebhook.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_auth(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.AuthCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_auth(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::AuthCriar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_auth(&credencial_de_acesso, &corpo_da_requisicao).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.AuthCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthCriar", typeDescriptionLink: "#tipo-authcriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `buscar_acesso_auth` [#buscar_acesso_auth]

<Rota metodo="GET" caminho="/auth/acesso" credencial />

Busca o acesso de quem está logado

Livre para qualquer usuário autenticado com cadastro ativo, mesmo sem nenhuma permissão liberada. Devolve o cadastro de quem chamou, o nome do perfil de acesso do colaborador em `perfil_acesso` (`null` quando ainda não tem) e as permissões que o perfil dá por área (`monitoramento`, `aplicativos`, `contratos`, `assinaturas` e `colaboradores`), cada uma com `ler`, `criar`, `editar` e `deletar`. Um master do TermoAuth recebe todas as permissões e, no primeiro acesso, ganha o cadastro automaticamente. `nome` vem do TermoAuth e, se estiver vazio, repete o e-mail. É a chamada que o painel faz antes de mostrar qualquer tela.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_acesso_auth(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.AcessoAtual>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_acesso_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_acesso_auth(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_acesso_auth(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::AcessoAtual, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_acesso_auth(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.AcessoAtual>` · Rust: `Result<tipos::AcessoAtual, ErroAoChamarServico>` · veja [`AcessoAtual`](#tipo-acessoatual).

## `buscar_auto_complete_auth` [#buscar_auto_complete_auth]

<Rota metodo="GET" caminho="/auth/autocomplete" credencial />

Lista básica de acessos para seleção

Exige qualquer permissão da área `colaboradores`. Devolve só id, e-mail e perfil, em ordem alfabética de e-mail, para escolher um acesso. `busca` procura por trecho do e-mail, sem diferenciar maiúsculas; `perfil` compara o valor exato. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10, sem máximo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaAuthAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_auth(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteAuth,
) -> Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_auth(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompleteAuth { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaAuthAutoComplete>` · Rust: `Result<tipos::PaginaAuthAutoComplete, ErroAoChamarServico>` · veja [`PaginaAuthAutoComplete`](#tipo-paginaauthautocomplete).

## `buscar_pelo_filtro_auth` [#buscar_pelo_filtro_auth]

<Rota metodo="GET" caminho="/auth/filtro" credencial />

Busca acessos por filtro

Exige qualquer permissão da área `colaboradores`. Devolve todos os acessos que casam com o filtro, sem paginação, em ordem alfabética de e-mail. `email` procura por trecho, sem diferenciar maiúsculas; `perfil` compara o valor exato; `ativo` filtra pela situação. Sem filtro, devolve todos. Acessos excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_auth(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroAuth = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Auth>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_auth(credencial_de_acesso, { email: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroAuth,
) -> Result<Vec<tipos::Auth>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_auth(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroAuth { email: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.perfil": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Auth>>` · Rust: `Result<Vec<tipos::Auth>, ErroAoChamarServico>`

## `buscar_pelo_id_auth` [#buscar_pelo_id_auth]

<Rota metodo="GET" caminho="/auth/{id}" credencial />

Busca um acesso pelo id

Exige qualquer permissão da área `colaboradores`. Acesso excluído responde `404`. `vinculado` diz se há um colaborador ligado ao acesso, e `nome` é o nome desse colaborador.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `atualizar_pelo_id_auth` [#atualizar_pelo_id_auth]

<Rota metodo="PATCH" caminho="/auth/{id}" credencial />

Atualiza um acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Só os campos enviados mudam: `email` (gravado em minúsculas, até 160 caracteres) e `ativo` (acesso inativo é barrado em todas as rotas). O acesso de um master do TermoAuth não pode ser alterado.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.AuthAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Auth>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_auth(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::AuthAtualizar,
) -> Result<tipos::Auth, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_auth(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.AuthAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::AuthAtualizar", typeDescriptionLink: "#tipo-authatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Auth>` · Rust: `Result<tipos::Auth, ErroAoChamarServico>` · veja [`Auth`](#tipo-auth).

## `deletar_pelo_id_auth` [#deletar_pelo_id_auth]

<Rota metodo="DELETE" caminho="/auth/{id}" credencial />

Exclui um acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica: o acesso some das consultas e a pessoa deixa de entrar, mas o registro fica guardado e não há como restaurar. Acesso com colaborador vinculado não pode ser excluído: o colaborador pertence ao TermoAuth e só sai de lá. O acesso de um master do TermoAuth não pode ser excluído.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_auth(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_auth } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_auth(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_auth(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::webhook::deletar_pelo_id_auth(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### AcessoAtual [#tipo-acessoatual]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AcessoAtual } from "termo_core/webhook";

export interface AcessoAtual {
  email: string;
  id: string;
  master: boolean;
  nome: string;
  perfil: string;
  perfil_acesso?: string | null;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::AcessoAtual;

pub struct AcessoAtual {
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil: String,
    pub perfil_acesso: Option<String>,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/webhook";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### Auth [#tipo-auth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Auth } from "termo_core/webhook";

export interface Auth {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Auth;

pub struct Auth {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### AuthAtualizar [#tipo-authatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthAtualizar } from "termo_core/webhook";

export interface AuthAtualizar {
  ativo?: boolean | null;
  email?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::AuthAtualizar;

pub struct AuthAtualizar {
    pub ativo: Option<bool>,
    pub email: Option<String>,
}
```

</Tab>
</Tabs>

### AuthCriar [#tipo-authcriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { AuthCriar } from "termo_core/webhook";

export interface AuthCriar {
  email: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::AuthCriar;

pub struct AuthCriar {
    pub email: String,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuth [#tipo-paginaauth]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuth } from "termo_core/webhook";

export interface PaginaAuth {
  itens: Array<PaginaAuthItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAuth;

pub struct PaginaAuth {
    pub itens: Vec<PaginaAuthItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoComplete [#tipo-paginaauthautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoComplete } from "termo_core/webhook";

export interface PaginaAuthAutoComplete {
  itens: Array<PaginaAuthAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAuthAutoComplete;

pub struct PaginaAuthAutoComplete {
    pub itens: Vec<PaginaAuthAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaAuthAutoCompleteItensItem [#tipo-paginaauthautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaAuthAutoCompleteItensItem {
  email: string;
  id: string;
  perfil: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAuthAutoCompleteItensItem;

pub struct PaginaAuthAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub perfil: String,
}
```

</Tab>
</Tabs>

### PaginaAuthItensItem [#tipo-paginaauthitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaAuthItensItem } from "termo_core/webhook";

export interface PaginaAuthItensItem {
  ativo: boolean;
  atualizado_em: string;
  bloqueado_ate?: string | null;
  criado_em: string;
  email: string;
  id: string;
  master: boolean;
  nome?: string | null;
  perfil: string;
  termoauth_id?: string | null;
  ultimo_login_em?: string | null;
  vinculado: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaAuthItensItem;

pub struct PaginaAuthItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub bloqueado_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: Option<String>,
    pub perfil: String,
    pub termoauth_id: Option<uuid::Uuid>,
    pub ultimo_login_em: Option<chrono::DateTime<chrono::Utc>>,
    pub vinculado: bool,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/webhook";

export interface Permissoes {
  aplicativos?: Acoes;
  assinaturas?: Acoes;
  colaboradores?: Acoes;
  contratos?: Acoes;
  monitoramento?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub assinaturas: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub contratos: Option<Acoes>,
    pub monitoramento: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Chave de assinatura (/docs/servicos/webhook/chave_de_assinatura)

> 1 função do TermoWebhook para chave de assinatura.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_chave_de_assinatura`](#buscar_paginador_chave_de_assinatura) | `GET /.well-known/jwks.json` | Chaves públicas que conferem as entregas |

## `buscar_paginador_chave_de_assinatura` [#buscar_paginador_chave_de_assinatura]

<Rota metodo="GET" caminho="/.well-known/jwks.json" />

Chaves públicas que conferem as entregas

Pública, sem token. Lista as chaves públicas Ed25519 (JWKS, `kty: OKP`, `crv: Ed25519`, `alg: EdDSA`) com que o hub assina cada entrega. O assinante confere `X-TermoWebhook-Assinatura: ed25519=<base64url>` sobre `<X-TermoWebhook-Data>.<id do próprio aplicativo>.<corpo>` com a chave do `kid` em `X-TermoWebhook-Chave`. Pode guardar em cache por 5 minutos e buscar de novo quando chegar um `kid` desconhecido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_chave_de_assinatura(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ConjuntoDeChaves>
```

```ts title="Exemplo"
import { buscar_paginador_chave_de_assinatura } from "termo_core/webhook";

const resposta = await buscar_paginador_chave_de_assinatura();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_chave_de_assinatura(

) -> Result<tipos::ConjuntoDeChaves, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::webhook::buscar_paginador_chave_de_assinatura().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ConjuntoDeChaves>` · Rust: `Result<tipos::ConjuntoDeChaves, ErroAoChamarServico>` · veja [`ConjuntoDeChaves`](#tipo-conjuntodechaves).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Chave [#tipo-chave]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Chave } from "termo_core/webhook";

export interface Chave {
  alg: string;
  crv: string;
  kid: string;
  kty: string;
  use: string;
  x: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Chave;

pub struct Chave {
    pub alg: String,
    pub crv: String,
    pub kid: String,
    pub kty: String,
    pub r#use: String,
    pub x: String,
}
```

</Tab>
</Tabs>

### ConjuntoDeChaves [#tipo-conjuntodechaves]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConjuntoDeChaves } from "termo_core/webhook";

export interface ConjuntoDeChaves {
  keys: Array<Chave>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::ConjuntoDeChaves;

pub struct ConjuntoDeChaves {
    pub keys: Vec<Chave>,
}
```

</Tab>
</Tabs>


# Colaborador (/docs/servicos/webhook/colaborador)

> 5 funções do TermoWebhook para colaborador.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_colaborador`](#buscar_paginador_colaborador) | `GET /colaborador` | Lista colaboradores com paginação |
| [`buscar_auto_complete_colaborador`](#buscar_auto_complete_colaborador) | `GET /colaborador/autocomplete` | Lista básica de colaboradores para seleção |
| [`buscar_pelo_filtro_colaborador`](#buscar_pelo_filtro_colaborador) | `GET /colaborador/filtro` | Busca colaboradores por filtro |
| [`buscar_pelo_id_colaborador`](#buscar_pelo_id_colaborador) | `GET /colaborador/{id}` | Busca um colaborador pelo id |
| [`vincular_perfil_acesso_colaborador`](#vincular_perfil_acesso_colaborador) | `PATCH /colaborador/{id}/perfil_acesso` | Define o perfil de acesso de um colaborador |

## `buscar_paginador_colaborador` [#buscar_paginador_colaborador]

<Rota metodo="GET" caminho="/colaborador" credencial />

Lista colaboradores com paginação

Só leitura: o colaborador é cadastrado, alterado e excluído no TermoAuth e chega aqui pelos eventos `colaborador.criado` e `colaborador.atualizado` do TermoWebhook; aqui só se escolhe o perfil de acesso dele (`PATCH /colaborador/{id}/perfil_acesso`). Exige qualquer permissão da área `colaboradores`. Ordena por nome. `nome`, `setor` e `cargo` filtram por trecho, sem diferenciar maiúsculas, e `ativo` pela situação. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. Colaboradores excluídos não aparecem nem entram no `total`, que conta os registros que casam com os filtros. Quando quem chama é master do TermoAuth, a lista antes traz do TermoAuth os colaboradores `@termotubos.com.br` que ainda não existem aqui, criando acesso e colaborador com o perfil de acesso "Acesso inicial" (só leitura em todas as áreas); quem já existe não é alterado e ninguém é excluído. Se o TermoAuth falhar, a lista sai mesmo assim, só sem a sincronização.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_colaborador } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_colaborador(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorColaborador,
) -> Result<tipos::PaginaColaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_colaborador(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorColaborador { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaborador>` · Rust: `Result<tipos::PaginaColaborador, ErroAoChamarServico>` · veja [`PaginaColaborador`](#tipo-paginacolaborador).

## `buscar_auto_complete_colaborador` [#buscar_auto_complete_colaborador]

<Rota metodo="GET" caminho="/colaborador/autocomplete" credencial />

Lista básica de colaboradores para seleção

Exige qualquer permissão da área `colaboradores`. Devolve só id, nome e e-mail, em ordem alfabética de nome, para escolher um colaborador. `busca` procura por trecho do nome ou do e-mail, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10, sem máximo.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaColaboradorAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_colaborador } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteColaborador,
) -> Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_colaborador(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompleteColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaColaboradorAutoComplete>` · Rust: `Result<tipos::PaginaColaboradorAutoComplete, ErroAoChamarServico>` · veja [`PaginaColaboradorAutoComplete`](#tipo-paginacolaboradorautocomplete).

## `buscar_pelo_filtro_colaborador` [#buscar_pelo_filtro_colaborador]

<Rota metodo="GET" caminho="/colaborador/filtro" credencial />

Busca colaboradores por filtro

Exige qualquer permissão da área `colaboradores`. Devolve todos os colaboradores que casam com o filtro, sem paginação, em ordem alfabética de nome. `busca` procura por trecho do nome ou do e-mail; `nome`, `email`, `setor` e `cargo` procuram por trecho, sem diferenciar maiúsculas; `ativo` filtra pela situação; `perfil_acesso_id` filtra pelo perfil de acesso. Sem filtro, devolve todos. Colaboradores excluídos não aparecem.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroColaborador = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Colaborador>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_colaborador } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_colaborador(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroColaborador,
) -> Result<Vec<tipos::Colaborador>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_colaborador(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroColaborador { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.email": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.setor": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.cargo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "parametros.perfil_acesso_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Colaborador>>` · Rust: `Result<Vec<tipos::Colaborador>, ErroAoChamarServico>`

## `buscar_pelo_id_colaborador` [#buscar_pelo_id_colaborador]

<Rota metodo="GET" caminho="/colaborador/{id}" credencial />

Busca um colaborador pelo id

Exige qualquer permissão da área `colaboradores`. Colaborador excluído responde `404`. Traz junto o e-mail do acesso, se ele é master do TermoAuth e o perfil de acesso (`perfil_acesso_id` e o nome em `perfil_acesso`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_colaborador } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_colaborador(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_colaborador(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## `vincular_perfil_acesso_colaborador` [#vincular_perfil_acesso_colaborador]

<Rota metodo="PATCH" caminho="/colaborador/{id}/perfil_acesso" credencial />

Define o perfil de acesso de um colaborador

Exige a permissão `editar` da área `colaboradores`. É a única escrita do colaborador feita pelo TermoWebhook: `perfil_acesso_id` aponta para um perfil de `GET /perfil_acesso/filtro` e passa a definir o que a pessoa enxerga; `null` tira o perfil e deixa a pessoa sem nenhuma área. O colaborador de um master do TermoAuth não aceita perfil (ele já tem tudo). Vale em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function vincular_perfil_acesso_colaborador(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.ColaboradorVincularPerfilAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Colaborador>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { vincular_perfil_acesso_colaborador } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await vincular_perfil_acesso_colaborador(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn vincular_perfil_acesso_colaborador(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::ColaboradorVincularPerfilAcesso,
) -> Result<tipos::Colaborador, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::vincular_perfil_acesso_colaborador(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.ColaboradorVincularPerfilAcesso", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ColaboradorVincularPerfilAcesso", typeDescriptionLink: "#tipo-colaboradorvincularperfilacesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Colaborador>` · Rust: `Result<tipos::Colaborador, ErroAoChamarServico>` · veja [`Colaborador`](#tipo-colaborador).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Colaborador [#tipo-colaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Colaborador } from "termo_core/webhook";

export interface Colaborador {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Colaborador;

pub struct Colaborador {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>

### ColaboradorVincularPerfilAcesso [#tipo-colaboradorvincularperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ColaboradorVincularPerfilAcesso } from "termo_core/webhook";

export interface ColaboradorVincularPerfilAcesso {
  perfil_acesso_id?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::ColaboradorVincularPerfilAcesso;

pub struct ColaboradorVincularPerfilAcesso {
    pub perfil_acesso_id: Option<uuid::Uuid>,
}
```

</Tab>
</Tabs>

### PaginaColaborador [#tipo-paginacolaborador]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaborador } from "termo_core/webhook";

export interface PaginaColaborador {
  itens: Array<PaginaColaboradorItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaColaborador;

pub struct PaginaColaborador {
    pub itens: Vec<PaginaColaboradorItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoComplete [#tipo-paginacolaboradorautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoComplete } from "termo_core/webhook";

export interface PaginaColaboradorAutoComplete {
  itens: Array<PaginaColaboradorAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaColaboradorAutoComplete;

pub struct PaginaColaboradorAutoComplete {
    pub itens: Vec<PaginaColaboradorAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaColaboradorAutoCompleteItensItem [#tipo-paginacolaboradorautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaColaboradorAutoCompleteItensItem {
  email: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaColaboradorAutoCompleteItensItem;

pub struct PaginaColaboradorAutoCompleteItensItem {
    pub email: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaColaboradorItensItem [#tipo-paginacolaboradoritensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaColaboradorItensItem } from "termo_core/webhook";

export interface PaginaColaboradorItensItem {
  ativo: boolean;
  atualizado_em: string;
  auth_id: string;
  cargo?: string | null;
  criado_em: string;
  email: string;
  funcao?: string | null;
  id: string;
  master: boolean;
  nome: string;
  perfil_acesso?: string | null;
  perfil_acesso_id?: string | null;
  setor?: string | null;
  telefone?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaColaboradorItensItem;

pub struct PaginaColaboradorItensItem {
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub auth_id: uuid::Uuid,
    pub cargo: Option<String>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub email: String,
    pub funcao: Option<String>,
    pub id: uuid::Uuid,
    pub master: bool,
    pub nome: String,
    pub perfil_acesso: Option<String>,
    pub perfil_acesso_id: Option<uuid::Uuid>,
    pub setor: Option<String>,
    pub telefone: Option<String>,
}
```

</Tab>
</Tabs>


# Configuração (/docs/servicos/webhook/configuracao)

> 2 funções do TermoWebhook para configuração.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_pelo_id_configuracao`](#buscar_pelo_id_configuracao) | `GET /configuracao` | Mostra se o segredo do app está cadastrado |
| [`atualizar_pelo_id_configuracao`](#atualizar_pelo_id_configuracao) | `PATCH /configuracao` | Grava ou limpa o segredo do app |

## `buscar_pelo_id_configuracao` [#buscar_pelo_id_configuracao]

<Rota metodo="GET" caminho="/configuracao" credencial />

Mostra se o segredo do app está cadastrado

Só o master do TermoAuth (os demais recebem `403`). Devolve a configuração única do TermoWebhook (tela `/painel/configuracoes/provedores`). O segredo do app gerado no TermoAuth nunca volta aberto: só `configurado` e o final mascarado (`final_visivel`). Fica cifrado no banco com AES-256-GCM e a chave derivada de `GLOBAL_SECRET_CRIPTOGRAFIA`; sem essa variável no servidor, ou se ela mudou, `configurado` vem `false`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_configuracao } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_configuracao(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_configuracao(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## `atualizar_pelo_id_configuracao` [#atualizar_pelo_id_configuracao]

<Rota metodo="PATCH" caminho="/configuracao" credencial />

Grava ou limpa o segredo do app

Só o master do TermoAuth (os demais recebem `403`). `segredo_do_app_gerado_no_termo_auth` ausente fica como está, string troca (até 2.000 caracteres, sem quebra de linha; vazia conta como limpar) e `null` limpa. O valor é cifrado com a `GLOBAL_SECRET_CRIPTOGRAFIA` e entregue na hora ao `termo_core`, sem deploy. A resposta é a mesma do `GET`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_configuracao(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.ConfiguracaoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.Configuracao>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_configuracao } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_configuracao(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_configuracao(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::ConfiguracaoAtualizar,
) -> Result<tipos::Configuracao, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_configuracao(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.ConfiguracaoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::ConfiguracaoAtualizar", typeDescriptionLink: "#tipo-configuracaoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.Configuracao>` · Rust: `Result<tipos::Configuracao, ErroAoChamarServico>` · veja [`Configuracao`](#tipo-configuracao).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Configuracao [#tipo-configuracao]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Configuracao } from "termo_core/webhook";

export interface Configuracao {
  atualizado_em: string;
  atualizado_por?: string | null;
  segredo_do_app_gerado_no_termo_auth: ValorProtegido;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Configuracao;

pub struct Configuracao {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub atualizado_por: Option<String>,
    pub segredo_do_app_gerado_no_termo_auth: ValorProtegido,
}
```

</Tab>
</Tabs>

### ConfiguracaoAtualizar [#tipo-configuracaoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ConfiguracaoAtualizar } from "termo_core/webhook";

export interface ConfiguracaoAtualizar {
  segredo_do_app_gerado_no_termo_auth?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::ConfiguracaoAtualizar;

pub struct ConfiguracaoAtualizar {
    pub segredo_do_app_gerado_no_termo_auth: Option<String>,
}
```

</Tab>
</Tabs>

### ValorProtegido [#tipo-valorprotegido]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ValorProtegido } from "termo_core/webhook";

export interface ValorProtegido {
  configurado: boolean;
  final_visivel?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::ValorProtegido;

pub struct ValorProtegido {
    pub configurado: bool,
    pub final_visivel: Option<String>,
}
```

</Tab>
</Tabs>


# Entrega (/docs/servicos/webhook/entrega)

> 4 funções do TermoWebhook para entrega.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_entrega`](#buscar_paginador_entrega) | `GET /entrega` | Lista entregas com paginação |
| [`buscar_pelo_filtro_entrega`](#buscar_pelo_filtro_entrega) | `GET /entrega/filtro` | Busca entregas por filtro |
| [`buscar_pelo_id_entrega`](#buscar_pelo_id_entrega) | `GET /entrega/{id}` | Busca uma entrega pelo id, com o histórico de tentativas |
| [`atualizar_pelo_id_entrega`](#atualizar_pelo_id_entrega) | `PATCH /entrega/{id}` | Descarta uma entrega |

## `buscar_paginador_entrega` [#buscar_paginador_entrega]

<Rota metodo="GET" caminho="/entrega" credencial />

Lista entregas com paginação

Exige a área `monitoramento`. As atualizadas mais recentemente vêm primeiro. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10. `situacao` é opcional e aceita os mesmos valores do filtro: `pendente`, `aguardando_nova_tentativa`, `entregue`, `tentativas_esgotadas`, `cancelada` ou `na_fila`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_entrega(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorEntrega = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEntrega>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_entrega } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_entrega(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_entrega(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorEntrega,
) -> Result<tipos::PaginaEntrega, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_entrega(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorEntrega { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEntrega>` · Rust: `Result<tipos::PaginaEntrega, ErroAoChamarServico>` · veja [`PaginaEntrega`](#tipo-paginaentrega).

## `buscar_pelo_filtro_entrega` [#buscar_pelo_filtro_entrega]

<Rota metodo="GET" caminho="/entrega/filtro" credencial />

Busca entregas por filtro

Exige a área `monitoramento`. Sem paginação: devolve no máximo 200 entregas, as criadas mais recentemente primeiro. Todos os filtros são opcionais e se somam. `situacao` é `pendente`, `aguardando_nova_tentativa`, `entregue`, `tentativas_esgotadas` (a fila de erro), `cancelada` ou `na_fila` (pendentes e aguardando nova tentativa juntas). Os demais filtram por assinatura, evento, aplicativo assinante e tipo de evento.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_entrega(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroEntrega = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Entrega>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_entrega } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_entrega(credencial_de_acesso, { situacao: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_entrega(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroEntrega,
) -> Result<Vec<tipos::Entrega>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_entrega(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroEntrega { situacao: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.assinatura_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.evento_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.aplicativo_assinante_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_de_evento_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Entrega>>` · Rust: `Result<Vec<tipos::Entrega>, ErroAoChamarServico>`

## `buscar_pelo_id_entrega` [#buscar_pelo_id_entrega]

<Rota metodo="GET" caminho="/entrega/{id}" credencial />

Busca uma entrega pelo id, com o histórico de tentativas

Exige a área `monitoramento`. Devolve a entrega (evento, assinatura, assinante, URL de destino e situação) e a lista `tentativas`, da mais recente para a mais antiga, com status HTTP, duração, erro e trecho da resposta de cada chamada ao assinante. `quantidade_de_tentativas` é o total histórico; `tentativas_no_ciclo_atual` zera a cada reprocessamento.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_entrega(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.EntregaDetalhada>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_entrega } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_entrega(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_entrega(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::EntregaDetalhada, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_entrega(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.EntregaDetalhada>` · Rust: `Result<tipos::EntregaDetalhada, ErroAoChamarServico>` · veja [`EntregaDetalhada`](#tipo-entregadetalhada).

## `atualizar_pelo_id_entrega` [#atualizar_pelo_id_entrega]

<Rota metodo="PATCH" caminho="/entrega/{id}" credencial />

Descarta uma entrega

Exige a área `monitoramento` com permissão de editar. O único valor aceito é `situacao = cancelada`: descarta a entrega, que deixa de ser reenviada. Só vale para entregas pendentes, aguardando nova tentativa ou na fila de erro; entrega já entregue ou já cancelada responde `409`. Para reenviar uma entrega, use o reprocessamento (`POST /solicitacao_de_reprocessamento`).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_entrega(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.EntregaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.EntregaDetalhada>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_entrega } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_entrega(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_entrega(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::EntregaAtualizar,
) -> Result<tipos::EntregaDetalhada, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_entrega(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.EntregaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EntregaAtualizar", typeDescriptionLink: "#tipo-entregaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.EntregaDetalhada>` · Rust: `Result<tipos::EntregaDetalhada, ErroAoChamarServico>` · veja [`EntregaDetalhada`](#tipo-entregadetalhada).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Entrega [#tipo-entrega]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Entrega } from "termo_core/webhook";

export interface Entrega {
  aplicativo_assinante_id: string;
  aplicativo_assinante_nome: string;
  assinatura_id: string;
  atualizada_em: string;
  criada_em: string;
  entidade_id: string;
  entregue_em?: string | null;
  evento_id: string;
  evento_recebido_em: string;
  id: string;
  maximo_de_tentativas: number;
  proxima_tentativa_em: string;
  quantidade_de_tentativas: number;
  situacao: string;
  tentativas_no_ciclo_atual: number;
  tipo_de_evento_nome: string;
  ultimo_erro?: string | null;
  url_de_destino: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Entrega;

pub struct Entrega {
    pub aplicativo_assinante_id: String,
    pub aplicativo_assinante_nome: String,
    pub assinatura_id: uuid::Uuid,
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub entidade_id: String,
    pub entregue_em: Option<chrono::DateTime<chrono::Utc>>,
    pub evento_id: uuid::Uuid,
    pub evento_recebido_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub maximo_de_tentativas: i32,
    pub proxima_tentativa_em: chrono::DateTime<chrono::Utc>,
    pub quantidade_de_tentativas: i32,
    pub situacao: String,
    pub tentativas_no_ciclo_atual: i32,
    pub tipo_de_evento_nome: String,
    pub ultimo_erro: Option<String>,
    pub url_de_destino: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### EntregaAtualizar [#tipo-entregaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaAtualizar } from "termo_core/webhook";

export interface EntregaAtualizar {
  situacao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EntregaAtualizar;

pub struct EntregaAtualizar {
    pub situacao: String,
}
```

</Tab>
</Tabs>

### EntregaDetalhada [#tipo-entregadetalhada]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaDetalhada } from "termo_core/webhook";

export type EntregaDetalhada = Entrega & EntregaDetalhadaParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EntregaDetalhada;

pub type EntregaDetalhada = serde_json::Value;
```

</Tab>
</Tabs>

### EntregaDetalhadaParte2 [#tipo-entregadetalhadaparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaDetalhadaParte2 } from "termo_core/webhook";

export interface EntregaDetalhadaParte2 {
  tentativas: Array<TentativaDeEntrega>;
}
```

</Tab>
<Tab value="Rust">

`termo_core::webhook::EntregaDetalhadaParte2`

</Tab>
</Tabs>

### PaginaEntrega [#tipo-paginaentrega]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEntrega } from "termo_core/webhook";

export interface PaginaEntrega {
  itens: Array<PaginaEntregaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaEntrega;

pub struct PaginaEntrega {
    pub itens: Vec<PaginaEntregaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEntregaItensItem [#tipo-paginaentregaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEntregaItensItem } from "termo_core/webhook";

export interface PaginaEntregaItensItem {
  aplicativo_assinante_id: string;
  aplicativo_assinante_nome: string;
  assinatura_id: string;
  atualizada_em: string;
  criada_em: string;
  entidade_id: string;
  entregue_em?: string | null;
  evento_id: string;
  evento_recebido_em: string;
  id: string;
  maximo_de_tentativas: number;
  proxima_tentativa_em: string;
  quantidade_de_tentativas: number;
  situacao: string;
  tentativas_no_ciclo_atual: number;
  tipo_de_evento_nome: string;
  ultimo_erro?: string | null;
  url_de_destino: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaEntregaItensItem;

pub struct PaginaEntregaItensItem {
    pub aplicativo_assinante_id: String,
    pub aplicativo_assinante_nome: String,
    pub assinatura_id: uuid::Uuid,
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub entidade_id: String,
    pub entregue_em: Option<chrono::DateTime<chrono::Utc>>,
    pub evento_id: uuid::Uuid,
    pub evento_recebido_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub maximo_de_tentativas: i32,
    pub proxima_tentativa_em: chrono::DateTime<chrono::Utc>,
    pub quantidade_de_tentativas: i32,
    pub situacao: String,
    pub tentativas_no_ciclo_atual: i32,
    pub tipo_de_evento_nome: String,
    pub ultimo_erro: Option<String>,
    pub url_de_destino: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### TentativaDeEntrega [#tipo-tentativadeentrega]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TentativaDeEntrega } from "termo_core/webhook";

export interface TentativaDeEntrega {
  codigo_de_status_http?: number | null;
  duracao_em_milissegundos?: number | null;
  erro?: string | null;
  id: number;
  iniciada_em: string;
  numero_da_tentativa: number;
  trecho_da_resposta?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::TentativaDeEntrega;

pub struct TentativaDeEntrega {
    pub codigo_de_status_http: Option<i32>,
    pub duracao_em_milissegundos: Option<i32>,
    pub erro: Option<String>,
    pub id: i64,
    pub iniciada_em: chrono::DateTime<chrono::Utc>,
    pub numero_da_tentativa: i32,
    pub trecho_da_resposta: Option<String>,
}
```

</Tab>
</Tabs>


# Esquema (/docs/servicos/webhook/esquema)

> 1 função do TermoWebhook para esquema.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_esquema`](#buscar_paginador_esquema) | `GET /esquemas.json` | Catálogo dos esquemas de evento vigentes |

## `buscar_paginador_esquema` [#buscar_paginador_esquema]

<Rota metodo="GET" caminho="/esquemas.json" />

Catálogo dos esquemas de evento vigentes

Pública, sem token. Lista todas as versões de esquema que não estão desligadas (ativas e descontinuadas), com o aplicativo dono, o tipo de evento e o JSON Schema dos dados, em ordem de aplicativo, tipo e versão. É a fonte de onde o gerador do TermoCore cria os contratos tipados do crate `termo_webhook`. Pode guardar em cache por 1 minuto.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_esquema(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.CatalogoDeEsquemas>
```

```ts title="Exemplo"
import { buscar_paginador_esquema } from "termo_core/webhook";

const resposta = await buscar_paginador_esquema();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_esquema(

) -> Result<tipos::CatalogoDeEsquemas, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::webhook::buscar_paginador_esquema().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.CatalogoDeEsquemas>` · Rust: `Result<tipos::CatalogoDeEsquemas, ErroAoChamarServico>` · veja [`CatalogoDeEsquemas`](#tipo-catalogodeesquemas).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### CatalogoDeEsquemas [#tipo-catalogodeesquemas]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { CatalogoDeEsquemas } from "termo_core/webhook";

export interface CatalogoDeEsquemas {
  esquemas: Array<EsquemaPublicado>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::CatalogoDeEsquemas;

pub struct CatalogoDeEsquemas {
    pub esquemas: Vec<EsquemaPublicado>,
}
```

</Tab>
</Tabs>

### EsquemaPublicado [#tipo-esquemapublicado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EsquemaPublicado } from "termo_core/webhook";

export interface EsquemaPublicado {
  aplicativo: string;
  descricao: string;
  esquema_dos_dados: Record<string, unknown>;
  situacao: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EsquemaPublicado;

pub struct EsquemaPublicado {
    pub aplicativo: String,
    pub descricao: String,
    pub esquema_dos_dados: serde_json::Map<String, serde_json::Value>,
    pub situacao: String,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>


# Evento (/docs/servicos/webhook/evento)

> 5 funções do TermoWebhook para evento.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_evento`](#buscar_paginador_evento) | `GET /evento` | Lista os eventos recebidos, paginados |
| [`criar_evento`](#criar_evento) | `POST /evento` | Publica um evento de teste pelo painel |
| [`buscar_pelo_filtro_evento`](#buscar_pelo_filtro_evento) | `GET /evento/filtro` | Busca eventos por filtro |
| [`buscar_resumo_evento`](#buscar_resumo_evento) | `GET /evento/resumo` | Visão geral do hub |
| [`buscar_pelo_id_evento`](#buscar_pelo_id_evento) | `GET /evento/{id}` | Busca um evento pelo id |

## `buscar_paginador_evento` [#buscar_paginador_evento]

<Rota metodo="GET" caminho="/evento" credencial />

Lista os eventos recebidos, paginados

Exige a área `monitoramento` com permissão de ler. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10; valores menores que 1 viram 1. Ordena do recebido mais recente para o mais antigo e traz, por evento, os contadores das entregas (total, concluídas, na fila e na fila de erro), sem os `dados`. `total` é a quantidade de eventos guardados.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEvento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_evento(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorEvento,
) -> Result<tipos::PaginaEvento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_evento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorEvento { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEvento>` · Rust: `Result<tipos::PaginaEvento, ErroAoChamarServico>` · veja [`PaginaEvento`](#tipo-paginaevento).

## `criar_evento` [#criar_evento]

<Rota metodo="POST" caminho="/evento" credencial />

Publica um evento de teste pelo painel

Exige a área `monitoramento` com permissão de criar. Publica um evento em nome do aplicativo dono do tipo, registra quem publicou e cria as entregas para todas as assinaturas ativas daquela versão. O id do evento é gerado pelo hub (UUIDv7). `entidade_id` é obrigatório, com no máximo 200 caracteres (os espaços nas pontas são removidos). `ocorrido_em` é opcional e, sem ele, vale o horário do recebimento. O tipo precisa estar ativo e a versão do esquema não pode estar desligada; `dados` é validado contra o JSON Schema da versão e os erros voltam no `422`, até 50 por resposta. Devolve o evento detalhado, já com as entregas criadas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_evento(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.EventoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.EventoDetalhado>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_evento(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::EventoCriar,
) -> Result<tipos::EventoDetalhado, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_evento(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.EventoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EventoCriar", typeDescriptionLink: "#tipo-eventocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.EventoDetalhado>` · Rust: `Result<tipos::EventoDetalhado, ErroAoChamarServico>` · veja [`EventoDetalhado`](#tipo-eventodetalhado).

## `buscar_pelo_filtro_evento` [#buscar_pelo_filtro_evento]

<Rota metodo="GET" caminho="/evento/filtro" credencial />

Busca eventos por filtro

Exige a área `monitoramento` com permissão de ler. Todos os filtros são opcionais e se somam: `id` do evento, `tipo_de_evento_id`, `aplicativo_publicador_id`, `entidade_id` (igualdade exata, sem os espaços nas pontas) e o intervalo `desde`/`ate` sobre o horário de recebimento (RFC 3339, inclusivo). Devolve no máximo 200 eventos, do recebido mais recente para o mais antigo, sem paginação e sem os `dados`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.Evento>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_evento(credencial_de_acesso, { id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroEvento,
) -> Result<Vec<tipos::Evento>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_evento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroEvento { id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.tipo_de_evento_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.aplicativo_publicador_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.entidade_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.desde": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "parametros.ate": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.Evento>>` · Rust: `Result<Vec<tipos::Evento>, ErroAoChamarServico>`

## `buscar_resumo_evento` [#buscar_resumo_evento]

<Rota metodo="GET" caminho="/evento/resumo" credencial />

Visão geral do hub

Exige a área `monitoramento` com permissão de ler. Devolve os totais das últimas 24 horas (eventos recebidos, recusados, entregas concluídas e tentativas com falha, contando como falha toda resposta fora de 2xx ou sem resposta), a situação atual da fila (entregas pendentes, aguardando nova tentativa e na fila de erro), os cadastros ativos (aplicativos, tipos de evento e assinaturas) e `por_hora`: 24 faixas de uma hora, da mais antiga até a hora atual, com eventos, recusados e entregas com falha.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_resumo_evento(
  credencial_de_acesso: CredencialDeAcesso,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.ResumoDosEventos>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_resumo_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_resumo_evento(credencial_de_acesso);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_resumo_evento(
    credencial_de_acesso: &CredencialDeAcesso,
) -> Result<tipos::ResumoDosEventos, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_resumo_evento(&credencial_de_acesso).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.ResumoDosEventos>` · Rust: `Result<tipos::ResumoDosEventos, ErroAoChamarServico>` · veja [`ResumoDosEventos`](#tipo-resumodoseventos).

## `buscar_pelo_id_evento` [#buscar_pelo_id_evento]

<Rota metodo="GET" caminho="/evento/{id}" credencial />

Busca um evento pelo id

Exige a área `monitoramento` com permissão de ler. Devolve o evento com os `dados` publicados, os contadores das entregas e a lista das entregas de cada assinante. Eventos mais velhos que a retenção do tipo são apagados de verdade e passam a responder `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.EventoDetalhado>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_evento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::EventoDetalhado, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_evento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.EventoDetalhado>` · Rust: `Result<tipos::EventoDetalhado, ErroAoChamarServico>` · veja [`EventoDetalhado`](#tipo-eventodetalhado).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Entrega [#tipo-entrega]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Entrega } from "termo_core/webhook";

export interface Entrega {
  aplicativo_assinante_id: string;
  aplicativo_assinante_nome: string;
  assinatura_id: string;
  atualizada_em: string;
  criada_em: string;
  entidade_id: string;
  entregue_em?: string | null;
  evento_id: string;
  evento_recebido_em: string;
  id: string;
  maximo_de_tentativas: number;
  proxima_tentativa_em: string;
  quantidade_de_tentativas: number;
  situacao: string;
  tentativas_no_ciclo_atual: number;
  tipo_de_evento_nome: string;
  ultimo_erro?: string | null;
  url_de_destino: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Entrega;

pub struct Entrega {
    pub aplicativo_assinante_id: String,
    pub aplicativo_assinante_nome: String,
    pub assinatura_id: uuid::Uuid,
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub entidade_id: String,
    pub entregue_em: Option<chrono::DateTime<chrono::Utc>>,
    pub evento_id: uuid::Uuid,
    pub evento_recebido_em: chrono::DateTime<chrono::Utc>,
    pub id: uuid::Uuid,
    pub maximo_de_tentativas: i32,
    pub proxima_tentativa_em: chrono::DateTime<chrono::Utc>,
    pub quantidade_de_tentativas: i32,
    pub situacao: String,
    pub tentativas_no_ciclo_atual: i32,
    pub tipo_de_evento_nome: String,
    pub ultimo_erro: Option<String>,
    pub url_de_destino: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### Evento [#tipo-evento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Evento } from "termo_core/webhook";

export interface Evento {
  aplicativo_publicador_id: string;
  aplicativo_publicador_nome: string;
  entidade_id: string;
  entregas_concluidas: number;
  entregas_na_fila: number;
  entregas_na_fila_de_erro: number;
  id: string;
  ocorrido_em: string;
  publicado_pelo_email?: string | null;
  quantidade_de_entregas: number;
  recebido_em: string;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Evento;

pub struct Evento {
    pub aplicativo_publicador_id: String,
    pub aplicativo_publicador_nome: String,
    pub entidade_id: String,
    pub entregas_concluidas: i64,
    pub entregas_na_fila: i64,
    pub entregas_na_fila_de_erro: i64,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub publicado_pelo_email: Option<String>,
    pub quantidade_de_entregas: i64,
    pub recebido_em: chrono::DateTime<chrono::Utc>,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### EventoCriar [#tipo-eventocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoCriar } from "termo_core/webhook";

export interface EventoCriar {
  dados: unknown;
  entidade_id: string;
  ocorrido_em?: string | null;
  tipo_de_evento_id: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EventoCriar;

pub struct EventoCriar {
    pub dados: serde_json::Value,
    pub entidade_id: String,
    pub ocorrido_em: Option<chrono::DateTime<chrono::Utc>>,
    pub tipo_de_evento_id: uuid::Uuid,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### EventoDetalhado [#tipo-eventodetalhado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoDetalhado } from "termo_core/webhook";

export type EventoDetalhado = Evento & EventoDetalhadoParte2;
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EventoDetalhado;

pub type EventoDetalhado = serde_json::Value;
```

</Tab>
</Tabs>

### EventoDetalhadoParte2 [#tipo-eventodetalhadoparte2]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoDetalhadoParte2 } from "termo_core/webhook";

export interface EventoDetalhadoParte2 {
  dados: unknown;
  entregas: Array<Entrega>;
}
```

</Tab>
<Tab value="Rust">

`termo_core::webhook::EventoDetalhadoParte2`

</Tab>
</Tabs>

### PaginaEvento [#tipo-paginaevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEvento } from "termo_core/webhook";

export interface PaginaEvento {
  itens: Array<PaginaEventoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaEvento;

pub struct PaginaEvento {
    pub itens: Vec<PaginaEventoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEventoItensItem [#tipo-paginaeventoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEventoItensItem } from "termo_core/webhook";

export interface PaginaEventoItensItem {
  aplicativo_publicador_id: string;
  aplicativo_publicador_nome: string;
  entidade_id: string;
  entregas_concluidas: number;
  entregas_na_fila: number;
  entregas_na_fila_de_erro: number;
  id: string;
  ocorrido_em: string;
  publicado_pelo_email?: string | null;
  quantidade_de_entregas: number;
  recebido_em: string;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  versao_do_esquema: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaEventoItensItem;

pub struct PaginaEventoItensItem {
    pub aplicativo_publicador_id: String,
    pub aplicativo_publicador_nome: String,
    pub entidade_id: String,
    pub entregas_concluidas: i64,
    pub entregas_na_fila: i64,
    pub entregas_na_fila_de_erro: i64,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub publicado_pelo_email: Option<String>,
    pub quantidade_de_entregas: i64,
    pub recebido_em: chrono::DateTime<chrono::Utc>,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub versao_do_esquema: i32,
}
```

</Tab>
</Tabs>

### ResumoDosEventos [#tipo-resumodoseventos]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResumoDosEventos } from "termo_core/webhook";

export interface ResumoDosEventos {
  aplicativos_ativos: number;
  assinaturas_ativas: number;
  entregas_aguardando_nova_tentativa: number;
  entregas_na_fila_de_erro: number;
  entregas_pendentes: number;
  entregues_nas_ultimas_24_horas: number;
  eventos_nas_ultimas_24_horas: number;
  por_hora: Array<ResumoDosEventosPorHora>;
  recusados_nas_ultimas_24_horas: number;
  tentativas_com_falha_nas_ultimas_24_horas: number;
  tipos_de_evento_ativos: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::ResumoDosEventos;

pub struct ResumoDosEventos {
    pub aplicativos_ativos: i64,
    pub assinaturas_ativas: i64,
    pub entregas_aguardando_nova_tentativa: i64,
    pub entregas_na_fila_de_erro: i64,
    pub entregas_pendentes: i64,
    pub entregues_nas_ultimas_24_horas: i64,
    pub eventos_nas_ultimas_24_horas: i64,
    pub por_hora: Vec<ResumoDosEventosPorHora>,
    pub recusados_nas_ultimas_24_horas: i64,
    pub tentativas_com_falha_nas_ultimas_24_horas: i64,
    pub tipos_de_evento_ativos: i64,
}
```

</Tab>
</Tabs>

### ResumoDosEventosPorHora [#tipo-resumodoseventosporhora]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { ResumoDosEventosPorHora } from "termo_core/webhook";

export interface ResumoDosEventosPorHora {
  entregas_com_falha: number;
  eventos: number;
  hora: string;
  recusados: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::ResumoDosEventosPorHora;

pub struct ResumoDosEventosPorHora {
    pub entregas_com_falha: i64,
    pub eventos: i64,
    pub hora: chrono::DateTime<chrono::Utc>,
    pub recusados: i64,
}
```

</Tab>
</Tabs>


# Evento recusado (/docs/servicos/webhook/evento_recusado)

> 3 funções do TermoWebhook para evento recusado.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_evento_recusado`](#buscar_paginador_evento_recusado) | `GET /evento_recusado` | Lista eventos recusados com paginação |
| [`buscar_pelo_filtro_evento_recusado`](#buscar_pelo_filtro_evento_recusado) | `GET /evento_recusado/filtro` | Busca eventos recusados por filtro |
| [`buscar_pelo_id_evento_recusado`](#buscar_pelo_id_evento_recusado) | `GET /evento_recusado/{id}` | Busca um evento recusado pelo id |

## `buscar_paginador_evento_recusado` [#buscar_paginador_evento_recusado]

<Rota metodo="GET" caminho="/evento_recusado" credencial />

Lista eventos recusados com paginação

Exige a área `monitoramento`. Os mais recentes vêm primeiro. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10. Recusados com mais de 30 dias são apagados pela limpeza diária.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_evento_recusado(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorEventoRecusado = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaEventoRecusado>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_evento_recusado } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_evento_recusado(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_evento_recusado(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorEventoRecusado,
) -> Result<tipos::PaginaEventoRecusado, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_evento_recusado(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorEventoRecusado { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaEventoRecusado>` · Rust: `Result<tipos::PaginaEventoRecusado, ErroAoChamarServico>` · veja [`PaginaEventoRecusado`](#tipo-paginaeventorecusado).

## `buscar_pelo_filtro_evento_recusado` [#buscar_pelo_filtro_evento_recusado]

<Rota metodo="GET" caminho="/evento_recusado/filtro" credencial />

Busca eventos recusados por filtro

Exige a área `monitoramento`. Sem paginação: devolve no máximo 200 recusados, os mais recentes primeiro. Todos os filtros são opcionais e se somam. `motivo` é `token_invalido`, `aplicativo_inativo`, `envelope_invalido`, `tipo_desconhecido`, `tipo_inativo`, `versao_inexistente`, `versao_desligada`, `publicador_nao_e_dono` ou `dados_fora_do_contrato`. `nome_do_tipo_informado` procura parte do nome, sem diferenciar maiúsculas. `desde` e `ate` (data e hora ISO 8601, inclusivos) limitam o momento da recusa.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_evento_recusado(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroEventoRecusado = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.EventoRecusado>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_evento_recusado } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_evento_recusado(credencial_de_acesso, { motivo: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_evento_recusado(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroEventoRecusado,
) -> Result<Vec<tipos::EventoRecusado>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_evento_recusado(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroEventoRecusado { motivo: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.motivo": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_publicador_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.nome_do_tipo_informado": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.desde": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "parametros.ate": { type: "string", required: false, description: "Rust: Option<chrono::DateTime<chrono::Utc>>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.EventoRecusado>>` · Rust: `Result<Vec<tipos::EventoRecusado>, ErroAoChamarServico>`

## `buscar_pelo_id_evento_recusado` [#buscar_pelo_id_evento_recusado]

<Rota metodo="GET" caminho="/evento_recusado/{id}" credencial />

Busca um evento recusado pelo id

Exige a área `monitoramento`. Devolve o que o publicador informou (aplicativo, id do evento, tipo e versão, quando foi possível ler), o `motivo` da recusa, os `erros_de_validacao` do JSON Schema (só em `dados_fora_do_contrato`) e um trecho do corpo recebido. Recusados ficam guardados por 30 dias.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_evento_recusado(
  credencial_de_acesso: CredencialDeAcesso,
  id: number,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.EventoRecusado>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_evento_recusado } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_evento_recusado(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_evento_recusado(
    credencial_de_acesso: &CredencialDeAcesso,
    id: i64,
) -> Result<tipos::EventoRecusado, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_evento_recusado(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "number", required: true, description: "Parâmetro do caminho da rota. · Rust: i64" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.EventoRecusado>` · Rust: `Result<tipos::EventoRecusado, ErroAoChamarServico>` · veja [`EventoRecusado`](#tipo-eventorecusado).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EventoRecusado [#tipo-eventorecusado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EventoRecusado } from "termo_core/webhook";

export interface EventoRecusado {
  aplicativo_publicador_id?: string | null;
  aplicativo_publicador_nome?: string | null;
  erros_de_validacao?: unknown;
  event_id_informado?: string | null;
  id: number;
  motivo: string;
  nome_do_tipo_informado?: string | null;
  recusado_em: string;
  trecho_do_payload?: string | null;
  versao_informada?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EventoRecusado;

pub struct EventoRecusado {
    pub aplicativo_publicador_id: Option<String>,
    pub aplicativo_publicador_nome: Option<String>,
    pub erros_de_validacao: Option<serde_json::Value>,
    pub event_id_informado: Option<String>,
    pub id: i64,
    pub motivo: String,
    pub nome_do_tipo_informado: Option<String>,
    pub recusado_em: chrono::DateTime<chrono::Utc>,
    pub trecho_do_payload: Option<String>,
    pub versao_informada: Option<i32>,
}
```

</Tab>
</Tabs>

### PaginaEventoRecusado [#tipo-paginaeventorecusado]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEventoRecusado } from "termo_core/webhook";

export interface PaginaEventoRecusado {
  itens: Array<PaginaEventoRecusadoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaEventoRecusado;

pub struct PaginaEventoRecusado {
    pub itens: Vec<PaginaEventoRecusadoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaEventoRecusadoItensItem [#tipo-paginaeventorecusadoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaEventoRecusadoItensItem } from "termo_core/webhook";

export interface PaginaEventoRecusadoItensItem {
  aplicativo_publicador_id?: string | null;
  aplicativo_publicador_nome?: string | null;
  erros_de_validacao?: unknown;
  event_id_informado?: string | null;
  id: number;
  motivo: string;
  nome_do_tipo_informado?: string | null;
  recusado_em: string;
  trecho_do_payload?: string | null;
  versao_informada?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaEventoRecusadoItensItem;

pub struct PaginaEventoRecusadoItensItem {
    pub aplicativo_publicador_id: Option<String>,
    pub aplicativo_publicador_nome: Option<String>,
    pub erros_de_validacao: Option<serde_json::Value>,
    pub event_id_informado: Option<String>,
    pub id: i64,
    pub motivo: String,
    pub nome_do_tipo_informado: Option<String>,
    pub recusado_em: chrono::DateTime<chrono::Utc>,
    pub trecho_do_payload: Option<String>,
    pub versao_informada: Option<i32>,
}
```

</Tab>
</Tabs>


# Eventos (/docs/servicos/webhook/eventos)

> 2 funções do TermoWebhook para eventos.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`receber_evento_eventos`](#receber_evento_eventos) | `POST /eventos` | Publica um evento no hub |
| [`webhooks_receber_evento_termo_webhook`](#webhooks_receber_evento_termo_webhook) | `POST /webhooks/termowebhook` | Recebe as entregas do hub como assinante |

## `receber_evento_eventos` [#receber_evento_eventos]

<Rota metodo="POST" caminho="/eventos" credencial />

Publica um evento no hub

Exige o token de aplicativo do TermoAuth (`Authorization: Bearer <token>`, `tipo: aplicativo`): é aqui que cada aplicativo publica os eventos dos dados de que é dono. Token de usuário não publica.

**Token.** O app troca o segredo dele (`SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH`) por um JWT de 15 minutos em `POST /token_de_app` do TermoAuth; o `termo_core` faz isso sozinho. O hub valida o JWT offline pelo JWKS do TermoAuth. O publicador é o aplicativo cujo `identificador_no_termoauth` é o `sub` do token; se ele ainda não existir, é criado na hora com o `name` do token, ativo e sem tipos de evento.

**Corpo.** JSON de até 1 MiB com o envelope `{ id, tipo, versao, entidade_id, ocorrido_em, dados }`: `id` é um UUID (de preferência UUIDv7) gerado pelo publicador e é a chave de idempotência; `tipo` é o nome do tipo de evento no catálogo; `versao` é o número da versão do esquema (maior que zero); `entidade_id` tem de 1 a 200 caracteres; `ocorrido_em` é RFC 3339; `dados` é validado contra o JSON Schema da versão.

**Ordem das verificações.** Token, aplicativo ativo, envelope, tipo cadastrado e ativo, publicador dono do tipo, versão cadastrada e não desligada, e os `dados` contra o contrato. Toda recusa fica registrada nos eventos recusados do painel com o `motivo` devolvido: `token_invalido`, `aplicativo_inativo`, `envelope_invalido`, `tipo_desconhecido`, `tipo_inativo`, `publicador_nao_e_dono`, `versao_inexistente`, `versao_desligada` ou `dados_fora_do_contrato`.

**Idempotência.** Um `id` já recebido responde `200` com `situacao: repetido` e não cria entregas de novo, então reenviar depois de uma falha de rede é seguro. Aceito, o evento é entregue a todas as assinaturas ativas da versão publicada, pelo menos uma vez cada. Publicar numa versão descontinuada é aceito, mas volta um `aviso` pedindo a migração.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function receber_evento_eventos(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.EnvelopeDoEvento,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PublicacaoRepetida>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { receber_evento_eventos } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await receber_evento_eventos(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn receber_evento_eventos(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::EnvelopeDoEvento,
) -> Result<tipos::PublicacaoRepetida, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::receber_evento_eventos(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.EnvelopeDoEvento", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EnvelopeDoEvento", typeDescriptionLink: "#tipo-envelopedoevento" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PublicacaoRepetida>` · Rust: `Result<tipos::PublicacaoRepetida, ErroAoChamarServico>` · veja [`PublicacaoRepetida`](#tipo-publicacaorepetida).

## `webhooks_receber_evento_termo_webhook` [#webhooks_receber_evento_termo_webhook]

<Rota metodo="POST" caminho="/webhooks/termowebhook" />

Recebe as entregas do hub como assinante

Pública, sem token do usuário: é onde o próprio TermoWebhook, como assinante, recebe as entregas do hub. A assinatura é conferida pelo crate `termo_core` (feature `webhook_receber`) com a chave pública do hub (endereço do hub pelo `AMBIENTE` + `/.well-known/jwks.json`) e o id do aplicativo, que é o mesmo do TermoAuth e vem do token de aplicativo (sem variável de ambiente).

**Eventos assinados.** `colaborador.criado` v1 cria o acesso e o colaborador de quem ainda não existe aqui, com o perfil de acesso "Acesso inicial" (só leitura em todas as áreas). `colaborador.atualizado` v1 grava e-mail e master, o nome só quando `nome` está em `campos_alterados`, e a troca de perfil liga ou desliga o acesso (virou cliente desliga, voltou a colaborador religa); quem é colaborador e ainda não existe é criado.

**Ordem e repetição.** A entrega é pelo menos uma vez e sem ordem garantida: a alteração só é aplicada quando o `ocorrido_em` é mais novo que o do último evento aplicado àquele acesso; o repetido ou atrasado responde `200` sem mudar nada. Tipo que o app não assina responde `200`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function webhooks_receber_evento_termo_webhook(
  parametros: ParametrosDeWebhooksReceberEventoTermoWebhook,
  corpo_da_requisicao: tipos.EntregaRecebida,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { webhooks_receber_evento_termo_webhook } from "termo_core/webhook";

await webhooks_receber_evento_termo_webhook({ "X-TermoWebhook-Data": 1, "X-TermoWebhook-Chave": "...", "X-TermoWebhook-Destino": "...", "X-TermoWebhook-Assinatura": "..." }, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn webhooks_receber_evento_termo_webhook(
    parametros: &ParametrosDeWebhooksReceberEventoTermoWebhook,
    corpo_da_requisicao: &tipos::EntregaRecebida,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
termo_core::webhook::webhooks_receber_evento_termo_webhook(
    &termo_core::webhook::ParametrosDeWebhooksReceberEventoTermoWebhook { x_termo_webhook_data, x_termo_webhook_chave, x_termo_webhook_destino, x_termo_webhook_assinatura },
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "parametros.X-TermoWebhook-Data": { type: "number", required: true, description: "Horário Unix em segundos da entrega; tolerância de 5 minutos\n\nEnviado no cabeçalho X-TermoWebhook-Data. · Rust: i64" },
    "parametros.X-TermoWebhook-Chave": { type: "string", required: true, description: "kid da chave do hub que assinou\n\nEnviado no cabeçalho X-TermoWebhook-Chave. · Rust: String" },
    "parametros.X-TermoWebhook-Destino": { type: "string", required: true, description: "Id do aplicativo assinante, o mesmo do TermoAuth\n\nEnviado no cabeçalho X-TermoWebhook-Destino. · Rust: String" },
    "parametros.X-TermoWebhook-Assinatura": { type: "string", required: true, description: "ed25519=<base64url> sobre <data>.<aplicativo_assinante_id>.<corpo>\n\nEnviado no cabeçalho X-TermoWebhook-Assinatura. · Rust: String" },
    "corpo_da_requisicao": { type: "tipos.EntregaRecebida", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::EntregaRecebida", typeDescriptionLink: "#tipo-entregarecebida" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### EntregaRecebida [#tipo-entregarecebida]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EntregaRecebida } from "termo_core/webhook";

export interface EntregaRecebida {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  publicador: string;
  recebido_em: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EntregaRecebida;

pub struct EntregaRecebida {
    pub dados: serde_json::Map<String, serde_json::Value>,
    pub entidade_id: String,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub publicador: String,
    pub recebido_em: chrono::DateTime<chrono::Utc>,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>

### EnvelopeDoEvento [#tipo-envelopedoevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { EnvelopeDoEvento } from "termo_core/webhook";

export interface EnvelopeDoEvento {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  tipo: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::EnvelopeDoEvento;

pub struct EnvelopeDoEvento {
    pub dados: serde_json::Map<String, serde_json::Value>,
    pub entidade_id: String,
    pub id: uuid::Uuid,
    pub ocorrido_em: chrono::DateTime<chrono::Utc>,
    pub tipo: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>

### PublicacaoRepetida [#tipo-publicacaorepetida]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PublicacaoRepetida } from "termo_core/webhook";

export interface PublicacaoRepetida {
  aviso?: string | null;
  id: string;
  situacao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PublicacaoRepetida;

pub struct PublicacaoRepetida {
    pub aviso: Option<String>,
    pub id: uuid::Uuid,
    pub situacao: String,
}
```

</Tab>
</Tabs>


# TermoWebhook (/docs/servicos/webhook)

> Hub central de eventos da Termotubos. Os apps publicam em POST /eventos com o token de aplicativo do TermoAuth e recebem as entregas assinadas com a chave Ed25519 do hub (chaves públicas em GET /.wel…

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

Hub central de eventos da Termotubos. Os apps publicam em `POST /eventos` com o token de aplicativo do TermoAuth e recebem as entregas assinadas com a chave Ed25519 do hub (chaves públicas em `GET /.well-known/jwks.json`); o resto da API é o painel (cadastros de aplicativos, contratos e assinaturas, monitoramento das entregas, perfis de acesso e colaboradores, que vêm só do TermoAuth) e usa o token do usuário logado no TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::webhook` (feature `webhook`) |
| Importação TypeScript | `termo_core/webhook` ou `import { webhook } from "termo_core"` |
| Funções | 69 |
| Entidades | 16 |
| Versão do contrato | `0.1.16` |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | `http://localhost:51081` |
| `SANDBOX` | `https://sandbox-api-webhook.termotubos.com.br` |
| `PRODUCTION` | `https://api-webhook.termotubos.com.br` |

## Entidades [#entidades]

<Cards>
  <Card title="Aplicativo" href="/docs/servicos/webhook/aplicativo" description="4 funções" />
  <Card title="Assinatura" href="/docs/servicos/webhook/assinatura" description="7 funções" />
  <Card title="Chave de assinatura" href="/docs/servicos/webhook/chave_de_assinatura" description="1 função" />
  <Card title="Entrega" href="/docs/servicos/webhook/entrega" description="4 funções" />
  <Card title="Esquema" href="/docs/servicos/webhook/esquema" description="1 função" />
  <Card title="Evento" href="/docs/servicos/webhook/evento" description="5 funções" />
  <Card title="Evento recusado" href="/docs/servicos/webhook/evento_recusado" description="3 funções" />
  <Card title="Eventos" href="/docs/servicos/webhook/eventos" description="2 funções" />
  <Card title="Solicitação de reprocessamento" href="/docs/servicos/webhook/solicitacao_de_reprocessamento" description="4 funções" />
  <Card title="Tipo de evento" href="/docs/servicos/webhook/tipo_de_evento" description="7 funções" />
  <Card title="Versão de esquema" href="/docs/servicos/webhook/versao_de_esquema" description="7 funções" />
</Cards>

## Login, painel e administração [#login-painel-e-administração]

<Cards>
  <Card title="Auth" href="/docs/servicos/webhook/auth" description="8 funções" />
  <Card title="Colaborador" href="/docs/servicos/webhook/colaborador" description="5 funções" />
  <Card title="Configuração" href="/docs/servicos/webhook/configuracao" description="2 funções" />
  <Card title="Perfil acesso" href="/docs/servicos/webhook/perfil_acesso" description="7 funções" />
  <Card title="Teste" href="/docs/servicos/webhook/test" description="2 funções" />
</Cards>

## Eventos [#eventos]

Além das rotas, o módulo `webhook` publica, recebe e guarda eventos. Veja a aba [Eventos](/docs/eventos).


# Perfil acesso (/docs/servicos/webhook/perfil_acesso)

> 7 funções do TermoWebhook para perfil acesso.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_perfil_acesso`](#buscar_paginador_perfil_acesso) | `GET /perfil_acesso` | Lista os perfis de acesso com paginação |
| [`criar_perfil_acesso`](#criar_perfil_acesso) | `POST /perfil_acesso` | Cria um perfil de acesso |
| [`buscar_auto_complete_perfil_acesso`](#buscar_auto_complete_perfil_acesso) | `GET /perfil_acesso/autocomplete` | Lista básica de perfis de acesso para seleção |
| [`buscar_pelo_filtro_perfil_acesso`](#buscar_pelo_filtro_perfil_acesso) | `GET /perfil_acesso/filtro` | Busca perfis de acesso por filtro |
| [`buscar_pelo_id_perfil_acesso`](#buscar_pelo_id_perfil_acesso) | `GET /perfil_acesso/{id}` | Busca um perfil de acesso pelo id |
| [`atualizar_pelo_id_perfil_acesso`](#atualizar_pelo_id_perfil_acesso) | `PATCH /perfil_acesso/{id}` | Atualiza um perfil de acesso pelo id |
| [`deletar_pelo_id_perfil_acesso`](#deletar_pelo_id_perfil_acesso) | `DELETE /perfil_acesso/{id}` | Exclui um perfil de acesso pelo id |

## `buscar_paginador_perfil_acesso` [#buscar_paginador_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso" credencial />

Lista os perfis de acesso com paginação

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Ordena pelo nome. `pagina` começa em 1 (padrão 1; valores menores viram 1). A página tem sempre 50 itens: `tamanho` é aceito, mas ignorado. `total` conta todos os registros não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_perfil_acesso(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorPerfilAcesso,
) -> Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorPerfilAcesso { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcesso>` · Rust: `Result<tipos::PaginaPerfilAcesso, ErroAoChamarServico>` · veja [`PaginaPerfilAcesso`](#tipo-paginaperfilacesso).

## `criar_perfil_acesso` [#criar_perfil_acesso]

<Rota metodo="POST" caminho="/perfil_acesso" credencial />

Cria um perfil de acesso

Exige a permissão `criar` da área `colaboradores`. O perfil de acesso é o conjunto de permissões que o TermoWebhook dá a um colaborador: cada colaborador aponta para um perfil (`PATCH /colaborador/{id}/perfil_acesso`) e enxerga o que o perfil libera. `nome` é obrigatório (até 80 caracteres, único sem diferenciar maiúsculas); `descricao` é opcional (até 200); `permissoes` traz, para cada área (`monitoramento`, `aplicativos`, `contratos`, `assinaturas` e `colaboradores`), as ações `ler`, `criar`, `editar` e `deletar` (o que não vier fica `false`). A resposta inclui `colaboradores`, quantas pessoas usam o perfil. O master do TermoAuth tem tudo liberado sem precisar de perfil.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.PerfilAcessoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_perfil_acesso(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::PerfilAcessoCriar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_perfil_acesso(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoCriar", typeDescriptionLink: "#tipo-perfilacessocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `buscar_auto_complete_perfil_acesso` [#buscar_auto_complete_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/autocomplete" credencial />

Lista básica de perfis de acesso para seleção

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve só o id e o nome, em ordem alfabética. `busca` procura por trecho do nome, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` conta os registros que casam com a busca.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompletePerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaPerfilAcessoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_perfil_acesso(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompletePerfilAcesso,
) -> Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompletePerfilAcesso { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaPerfilAcessoAutoComplete>` · Rust: `Result<tipos::PaginaPerfilAcessoAutoComplete, ErroAoChamarServico>` · veja [`PaginaPerfilAcessoAutoComplete`](#tipo-paginaperfilacessoautocomplete).

## `buscar_pelo_filtro_perfil_acesso` [#buscar_pelo_filtro_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/filtro" credencial />

Busca perfis de acesso por filtro

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Devolve todos os perfis que casam com o filtro, sem paginação, em ordem alfabética de nome. `nome` procura por trecho, sem diferenciar maiúsculas. Sem filtro, devolve todos (é o que a tela usa para listar e para escolher o perfil de um colaborador).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroPerfilAcesso = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.PerfilAcesso>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_perfil_acesso(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroPerfilAcesso,
) -> Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_perfil_acesso(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroPerfilAcesso { nome: Some("...".to_string()) },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.PerfilAcesso>>` · Rust: `Result<Vec<tipos::PerfilAcesso>, ErroAoChamarServico>`

## `buscar_pelo_id_perfil_acesso` [#buscar_pelo_id_perfil_acesso]

<Rota metodo="GET" caminho="/perfil_acesso/{id}" credencial />

Busca um perfil de acesso pelo id

Exige qualquer permissão da área `colaboradores` (qualquer ação liberada na área já libera a leitura). Perfil excluído responde `404`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `atualizar_pelo_id_perfil_acesso` [#atualizar_pelo_id_perfil_acesso]

<Rota metodo="PATCH" caminho="/perfil_acesso/{id}" credencial />

Atualiza um perfil de acesso pelo id

Exige a permissão `editar` da área `colaboradores`. Atualização parcial: só os campos enviados mudam. `nome` segue o limite do cadastro; `descricao` vazia apaga o valor; `permissoes`, quando enviado, substitui o conjunto inteiro (o que não vier fica `false`). Todo colaborador do perfil passa a valer com as novas permissões em até 5 minutos (cache do acesso).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.PerfilAcessoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PerfilAcesso>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_perfil_acesso(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::PerfilAcessoAtualizar,
) -> Result<tipos::PerfilAcesso, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_perfil_acesso(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.PerfilAcessoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::PerfilAcessoAtualizar", typeDescriptionLink: "#tipo-perfilacessoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PerfilAcesso>` · Rust: `Result<tipos::PerfilAcesso, ErroAoChamarServico>` · veja [`PerfilAcesso`](#tipo-perfilacesso).

## `deletar_pelo_id_perfil_acesso` [#deletar_pelo_id_perfil_acesso]

<Rota metodo="DELETE" caminho="/perfil_acesso/{id}" credencial />

Exclui um perfil de acesso pelo id

Exige a permissão `deletar` da área `colaboradores`. A exclusão é lógica e só é aceita quando nenhum colaborador usa o perfil: com gente vinculada responde `409`, e é preciso trocar o perfil dessas pessoas antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_perfil_acesso(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_perfil_acesso } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_perfil_acesso(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_perfil_acesso(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::webhook::deletar_pelo_id_perfil_acesso(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### Acoes [#tipo-acoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Acoes } from "termo_core/webhook";

export interface Acoes {
  criar?: boolean;
  deletar?: boolean;
  editar?: boolean;
  ler?: boolean;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Acoes;

pub struct Acoes {
    pub criar: Option<bool>,
    pub deletar: Option<bool>,
    pub editar: Option<bool>,
    pub ler: Option<bool>,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcesso [#tipo-paginaperfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcesso } from "termo_core/webhook";

export interface PaginaPerfilAcesso {
  itens: Array<PaginaPerfilAcessoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaPerfilAcesso;

pub struct PaginaPerfilAcesso {
    pub itens: Vec<PaginaPerfilAcessoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoComplete [#tipo-paginaperfilacessoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoComplete } from "termo_core/webhook";

export interface PaginaPerfilAcessoAutoComplete {
  itens: Array<PaginaPerfilAcessoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaPerfilAcessoAutoComplete;

pub struct PaginaPerfilAcessoAutoComplete {
    pub itens: Vec<PaginaPerfilAcessoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoAutoCompleteItensItem [#tipo-paginaperfilacessoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaPerfilAcessoAutoCompleteItensItem {
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaPerfilAcessoAutoCompleteItensItem;

pub struct PaginaPerfilAcessoAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaPerfilAcessoItensItem [#tipo-paginaperfilacessoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaPerfilAcessoItensItem } from "termo_core/webhook";

export interface PaginaPerfilAcessoItensItem {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaPerfilAcessoItensItem;

pub struct PaginaPerfilAcessoItensItem {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcesso [#tipo-perfilacesso]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcesso } from "termo_core/webhook";

export interface PerfilAcesso {
  atualizado_em: string;
  colaboradores: number;
  criado_em: string;
  descricao?: string | null;
  id: string;
  nome: string;
  permissoes: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PerfilAcesso;

pub struct PerfilAcesso {
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub colaboradores: i64,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: Option<String>,
    pub id: uuid::Uuid,
    pub nome: String,
    pub permissoes: Permissoes,
}
```

</Tab>
</Tabs>

### PerfilAcessoAtualizar [#tipo-perfilacessoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoAtualizar } from "termo_core/webhook";

export interface PerfilAcessoAtualizar {
  descricao?: string | null;
  nome?: string | null;
  permissoes?: Permissoes | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PerfilAcessoAtualizar;

pub struct PerfilAcessoAtualizar {
    pub descricao: Option<String>,
    pub nome: Option<String>,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### PerfilAcessoCriar [#tipo-perfilacessocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PerfilAcessoCriar } from "termo_core/webhook";

export interface PerfilAcessoCriar {
  descricao?: string | null;
  nome: string;
  permissoes?: Permissoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PerfilAcessoCriar;

pub struct PerfilAcessoCriar {
    pub descricao: Option<String>,
    pub nome: String,
    pub permissoes: Option<Permissoes>,
}
```

</Tab>
</Tabs>

### Permissoes [#tipo-permissoes]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { Permissoes } from "termo_core/webhook";

export interface Permissoes {
  aplicativos?: Acoes;
  assinaturas?: Acoes;
  colaboradores?: Acoes;
  contratos?: Acoes;
  monitoramento?: Acoes;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::Permissoes;

pub struct Permissoes {
    pub aplicativos: Option<Acoes>,
    pub assinaturas: Option<Acoes>,
    pub colaboradores: Option<Acoes>,
    pub contratos: Option<Acoes>,
    pub monitoramento: Option<Acoes>,
}
```

</Tab>
</Tabs>


# Solicitação de reprocessamento (/docs/servicos/webhook/solicitacao_de_reprocessamento)

> 4 funções do TermoWebhook para solicitação de reprocessamento.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_solicitacao_de_reprocessamento`](#buscar_paginador_solicitacao_de_reprocessamento) | `GET /solicitacao_de_reprocessamento` | Lista solicitações de reprocessamento com paginação |
| [`criar_solicitacao_de_reprocessamento`](#criar_solicitacao_de_reprocessamento) | `POST /solicitacao_de_reprocessamento` | Solicita o reprocessamento de entregas |
| [`buscar_pelo_filtro_solicitacao_de_reprocessamento`](#buscar_pelo_filtro_solicitacao_de_reprocessamento) | `GET /solicitacao_de_reprocessamento/filtro` | Busca solicitações de reprocessamento por filtro |
| [`buscar_pelo_id_solicitacao_de_reprocessamento`](#buscar_pelo_id_solicitacao_de_reprocessamento) | `GET /solicitacao_de_reprocessamento/{id}` | Busca uma solicitação de reprocessamento pelo id |

## `buscar_paginador_solicitacao_de_reprocessamento` [#buscar_paginador_solicitacao_de_reprocessamento]

<Rota metodo="GET" caminho="/solicitacao_de_reprocessamento" credencial />

Lista solicitações de reprocessamento com paginação

Exige a área `monitoramento`. As mais recentes vêm primeiro. `pagina` começa em 1 (padrão 1); `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_solicitacao_de_reprocessamento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorSolicitacaoDeReprocessamento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaSolicitacaoDeReprocessamento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_solicitacao_de_reprocessamento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_solicitacao_de_reprocessamento(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_solicitacao_de_reprocessamento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorSolicitacaoDeReprocessamento,
) -> Result<tipos::PaginaSolicitacaoDeReprocessamento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_solicitacao_de_reprocessamento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorSolicitacaoDeReprocessamento { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaSolicitacaoDeReprocessamento>` · Rust: `Result<tipos::PaginaSolicitacaoDeReprocessamento, ErroAoChamarServico>` · veja [`PaginaSolicitacaoDeReprocessamento`](#tipo-paginasolicitacaodereprocessamento).

## `criar_solicitacao_de_reprocessamento` [#criar_solicitacao_de_reprocessamento]

<Rota metodo="POST" caminho="/solicitacao_de_reprocessamento" credencial />

Solicita o reprocessamento de entregas

Exige a área `monitoramento` com permissão de criar. `motivo` é obrigatório (até 500 caracteres) e fica no histórico junto com quem pediu. O `alcance` define o que é reenviado:

- `entrega`: exige `entrega_id`. Reenvia aquela entrega agora, mesmo que já tenha sido entregue, cancelada ou esteja aguardando nova tentativa (se ela está pendente, nada muda). Para reenviar várias, faça uma solicitação por entrega.
- `fila_de_erro`: exige `assinatura_id`. Reabre todas as entregas da assinatura que esgotaram as tentativas.
- `periodo`: exige `assinatura_id` e `eventos_desde`; `eventos_ate` é opcional (sem ele, vai até agora) e não pode ser antes do início. Cria as entregas que faltam para os eventos recebidos no período e reabre as esgotadas e as canceladas; com `incluir_entregues = true`, reenvia também as já entregues.

Campos que não pertencem ao alcance escolhido são ignorados. A assinatura precisa estar ativa. Cada entrega reaberta recomeça o ciclo de tentativas. A resposta traz quantas entregas foram reabertas e quantas foram criadas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_solicitacao_de_reprocessamento(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.SolicitacaoDeReprocessamentoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SolicitacaoDeReprocessamento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_solicitacao_de_reprocessamento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_solicitacao_de_reprocessamento(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_solicitacao_de_reprocessamento(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::SolicitacaoDeReprocessamentoCriar,
) -> Result<tipos::SolicitacaoDeReprocessamento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_solicitacao_de_reprocessamento(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.SolicitacaoDeReprocessamentoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::SolicitacaoDeReprocessamentoCriar", typeDescriptionLink: "#tipo-solicitacaodereprocessamentocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SolicitacaoDeReprocessamento>` · Rust: `Result<tipos::SolicitacaoDeReprocessamento, ErroAoChamarServico>` · veja [`SolicitacaoDeReprocessamento`](#tipo-solicitacaodereprocessamento).

## `buscar_pelo_filtro_solicitacao_de_reprocessamento` [#buscar_pelo_filtro_solicitacao_de_reprocessamento]

<Rota metodo="GET" caminho="/solicitacao_de_reprocessamento/filtro" credencial />

Busca solicitações de reprocessamento por filtro

Exige a área `monitoramento`. Sem paginação: devolve no máximo 200 solicitações, as mais recentes primeiro. Filtros opcionais e somados: `assinatura_id` e `alcance` (`entrega`, `fila_de_erro` ou `periodo`; outro valor não encontra nada).

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_solicitacao_de_reprocessamento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroSolicitacaoDeReprocessamento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.SolicitacaoDeReprocessamento>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_solicitacao_de_reprocessamento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_solicitacao_de_reprocessamento(credencial_de_acesso, { assinatura_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_solicitacao_de_reprocessamento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroSolicitacaoDeReprocessamento,
) -> Result<Vec<tipos::SolicitacaoDeReprocessamento>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_solicitacao_de_reprocessamento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroSolicitacaoDeReprocessamento { assinatura_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.assinatura_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.alcance": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.SolicitacaoDeReprocessamento>>` · Rust: `Result<Vec<tipos::SolicitacaoDeReprocessamento>, ErroAoChamarServico>`

## `buscar_pelo_id_solicitacao_de_reprocessamento` [#buscar_pelo_id_solicitacao_de_reprocessamento]

<Rota metodo="GET" caminho="/solicitacao_de_reprocessamento/{id}" credencial />

Busca uma solicitação de reprocessamento pelo id

Exige a área `monitoramento`. Devolve quem pediu, o motivo, o alcance com seus parâmetros, a assinatura (assinante e tipo de evento) e quantas entregas foram reabertas e criadas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_solicitacao_de_reprocessamento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SolicitacaoDeReprocessamento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_solicitacao_de_reprocessamento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_solicitacao_de_reprocessamento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_solicitacao_de_reprocessamento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::SolicitacaoDeReprocessamento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_solicitacao_de_reprocessamento(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SolicitacaoDeReprocessamento>` · Rust: `Result<tipos::SolicitacaoDeReprocessamento, ErroAoChamarServico>` · veja [`SolicitacaoDeReprocessamento`](#tipo-solicitacaodereprocessamento).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaSolicitacaoDeReprocessamento [#tipo-paginasolicitacaodereprocessamento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSolicitacaoDeReprocessamento } from "termo_core/webhook";

export interface PaginaSolicitacaoDeReprocessamento {
  itens: Array<PaginaSolicitacaoDeReprocessamentoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaSolicitacaoDeReprocessamento;

pub struct PaginaSolicitacaoDeReprocessamento {
    pub itens: Vec<PaginaSolicitacaoDeReprocessamentoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaSolicitacaoDeReprocessamentoItensItem [#tipo-paginasolicitacaodereprocessamentoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaSolicitacaoDeReprocessamentoItensItem } from "termo_core/webhook";

export interface PaginaSolicitacaoDeReprocessamentoItensItem {
  alcance: string;
  aplicativo_assinante_nome: string;
  assinatura_id: string;
  entrega_id?: string | null;
  eventos_ate?: string | null;
  eventos_desde?: string | null;
  id: string;
  incluir_entregues: boolean;
  motivo: string;
  quantidade_de_entregas_criadas: number;
  quantidade_de_entregas_reabertas: number;
  solicitada_em: string;
  solicitada_por_auth_id: string;
  solicitada_por_email: string;
  tipo_de_evento_nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaSolicitacaoDeReprocessamentoItensItem;

pub struct PaginaSolicitacaoDeReprocessamentoItensItem {
    pub alcance: String,
    pub aplicativo_assinante_nome: String,
    pub assinatura_id: uuid::Uuid,
    pub entrega_id: Option<uuid::Uuid>,
    pub eventos_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub eventos_desde: Option<chrono::DateTime<chrono::Utc>>,
    pub id: uuid::Uuid,
    pub incluir_entregues: bool,
    pub motivo: String,
    pub quantidade_de_entregas_criadas: i32,
    pub quantidade_de_entregas_reabertas: i32,
    pub solicitada_em: chrono::DateTime<chrono::Utc>,
    pub solicitada_por_auth_id: uuid::Uuid,
    pub solicitada_por_email: String,
    pub tipo_de_evento_nome: String,
}
```

</Tab>
</Tabs>

### SolicitacaoDeReprocessamento [#tipo-solicitacaodereprocessamento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SolicitacaoDeReprocessamento } from "termo_core/webhook";

export interface SolicitacaoDeReprocessamento {
  alcance: string;
  aplicativo_assinante_nome: string;
  assinatura_id: string;
  entrega_id?: string | null;
  eventos_ate?: string | null;
  eventos_desde?: string | null;
  id: string;
  incluir_entregues: boolean;
  motivo: string;
  quantidade_de_entregas_criadas: number;
  quantidade_de_entregas_reabertas: number;
  solicitada_em: string;
  solicitada_por_auth_id: string;
  solicitada_por_email: string;
  tipo_de_evento_nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::SolicitacaoDeReprocessamento;

pub struct SolicitacaoDeReprocessamento {
    pub alcance: String,
    pub aplicativo_assinante_nome: String,
    pub assinatura_id: uuid::Uuid,
    pub entrega_id: Option<uuid::Uuid>,
    pub eventos_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub eventos_desde: Option<chrono::DateTime<chrono::Utc>>,
    pub id: uuid::Uuid,
    pub incluir_entregues: bool,
    pub motivo: String,
    pub quantidade_de_entregas_criadas: i32,
    pub quantidade_de_entregas_reabertas: i32,
    pub solicitada_em: chrono::DateTime<chrono::Utc>,
    pub solicitada_por_auth_id: uuid::Uuid,
    pub solicitada_por_email: String,
    pub tipo_de_evento_nome: String,
}
```

</Tab>
</Tabs>

### SolicitacaoDeReprocessamentoCriar [#tipo-solicitacaodereprocessamentocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SolicitacaoDeReprocessamentoCriar } from "termo_core/webhook";

export interface SolicitacaoDeReprocessamentoCriar {
  alcance: string;
  assinatura_id?: string | null;
  entrega_id?: string | null;
  eventos_ate?: string | null;
  eventos_desde?: string | null;
  incluir_entregues?: boolean;
  motivo: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::SolicitacaoDeReprocessamentoCriar;

pub struct SolicitacaoDeReprocessamentoCriar {
    pub alcance: String,
    pub assinatura_id: Option<uuid::Uuid>,
    pub entrega_id: Option<uuid::Uuid>,
    pub eventos_ate: Option<chrono::DateTime<chrono::Utc>>,
    pub eventos_desde: Option<chrono::DateTime<chrono::Utc>>,
    pub incluir_entregues: Option<bool>,
    pub motivo: String,
}
```

</Tab>
</Tabs>


# Teste (/docs/servicos/webhook/test)

> 2 funções do TermoWebhook para teste.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_versao_test`](#buscar_versao_test) | `GET /` | Versão do backend no ar |
| [`verificar_saude_test`](#verificar_saude_test) | `GET /test` | Verifica se o backend está no ar |

## `buscar_versao_test` [#buscar_versao_test]

<Rota metodo="GET" caminho="/" />

Versão do backend no ar

Pública, sem token. Devolve `sucesso: true` e a versão do backend que está publicada, no formato semver.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_versao_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDoBackend>
```

```ts title="Exemplo"
import { buscar_versao_test } from "termo_core/webhook";

const resposta = await buscar_versao_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_versao_test() -> Result<tipos::VersaoDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::webhook::buscar_versao_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDoBackend>` · Rust: `Result<tipos::VersaoDoBackend, ErroAoChamarServico>` · veja [`VersaoDoBackend`](#tipo-versaodobackend).

## `verificar_saude_test` [#verificar_saude_test]

<Rota metodo="GET" caminho="/test" />

Verifica se o backend está no ar

Pública, sem token. Responde `200` com `sucesso: true` e a versão do backend no ar (semver) sempre que o servidor está de pé; não consulta o banco nem o TermoAuth.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function verificar_saude_test(
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.SaudeDoBackend>
```

```ts title="Exemplo"
import { verificar_saude_test } from "termo_core/webhook";

const resposta = await verificar_saude_test();
```

</Tab>
<Tab value="Rust">

```rust
pub async fn verificar_saude_test() -> Result<tipos::SaudeDoBackend, ErroAoChamarServico>
```

```rust title="Exemplo"
let resposta = termo_core::webhook::verificar_saude_test().await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.SaudeDoBackend>` · Rust: `Result<tipos::SaudeDoBackend, ErroAoChamarServico>` · veja [`SaudeDoBackend`](#tipo-saudedobackend).

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### SaudeDoBackend [#tipo-saudedobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { SaudeDoBackend } from "termo_core/webhook";

export interface SaudeDoBackend {
  mensagem: string;
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::SaudeDoBackend;

pub struct SaudeDoBackend {
    pub mensagem: String,
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>

### VersaoDoBackend [#tipo-versaodobackend]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDoBackend } from "termo_core/webhook";

export interface VersaoDoBackend {
  sucesso: boolean;
  versao: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::VersaoDoBackend;

pub struct VersaoDoBackend {
    pub sucesso: bool,
    pub versao: String,
}
```

</Tab>
</Tabs>


# Tipo de evento (/docs/servicos/webhook/tipo_de_evento)

> 7 funções do TermoWebhook para tipo de evento.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_tipo_de_evento`](#buscar_paginador_tipo_de_evento) | `GET /tipo_de_evento` | Lista os tipos de evento paginados |
| [`criar_tipo_de_evento`](#criar_tipo_de_evento) | `POST /tipo_de_evento` | Cadastra um tipo de evento |
| [`buscar_auto_complete_tipo_de_evento`](#buscar_auto_complete_tipo_de_evento) | `GET /tipo_de_evento/autocomplete` | Lista básica de tipos de evento para seleção |
| [`buscar_pelo_filtro_tipo_de_evento`](#buscar_pelo_filtro_tipo_de_evento) | `GET /tipo_de_evento/filtro` | Busca tipos de evento por filtro |
| [`buscar_pelo_id_tipo_de_evento`](#buscar_pelo_id_tipo_de_evento) | `GET /tipo_de_evento/{id}` | Busca um tipo de evento pelo id |
| [`atualizar_pelo_id_tipo_de_evento`](#atualizar_pelo_id_tipo_de_evento) | `PATCH /tipo_de_evento/{id}` | Atualiza um tipo de evento pelo id |
| [`deletar_pelo_id_tipo_de_evento`](#deletar_pelo_id_tipo_de_evento) | `DELETE /tipo_de_evento/{id}` | Exclui um tipo de evento pelo id |

## `buscar_paginador_tipo_de_evento` [#buscar_paginador_tipo_de_evento]

<Rota metodo="GET" caminho="/tipo_de_evento" credencial />

Lista os tipos de evento paginados

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Lista os tipos não excluídos em ordem alfabética do nome. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de tipos não excluídos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorTipoDeEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTipoDeEvento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_tipo_de_evento(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorTipoDeEvento,
) -> Result<tipos::PaginaTipoDeEvento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_tipo_de_evento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorTipoDeEvento { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTipoDeEvento>` · Rust: `Result<tipos::PaginaTipoDeEvento, ErroAoChamarServico>` · veja [`PaginaTipoDeEvento`](#tipo-paginatipodeevento).

## `criar_tipo_de_evento` [#criar_tipo_de_evento]

<Rota metodo="POST" caminho="/tipo_de_evento" credencial />

Cadastra um tipo de evento

Exige a permissão `criar` na área `contratos`. `nome` segue o formato `dominio.acontecimento`, só com letras minúsculas, números e `_` (ex.: `pedido.faturado`), tem até 120 caracteres, é único entre os tipos não excluídos e não muda depois. `descricao` é obrigatória (até 500 caracteres). `aplicativo_dono_id` é o aplicativo que publica o tipo: só ele pode publicar eventos desse tipo. `dias_de_retencao` vai de 1 a 3650 (padrão 30): eventos mais velhos que isso são apagados de vez pela limpeza diária. `ativo` tem padrão `true`; tipo inativo tem as publicações recusadas. O tipo nasce sem versões: cadastre o esquema em `POST /versao_de_esquema`.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.TipoDeEventoCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TipoDeEvento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_tipo_de_evento(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::TipoDeEventoCriar,
) -> Result<tipos::TipoDeEvento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_tipo_de_evento(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.TipoDeEventoCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TipoDeEventoCriar", typeDescriptionLink: "#tipo-tipodeeventocriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TipoDeEvento>` · Rust: `Result<tipos::TipoDeEvento, ErroAoChamarServico>` · veja [`TipoDeEvento`](#tipo-tipodeevento).

## `buscar_auto_complete_tipo_de_evento` [#buscar_auto_complete_tipo_de_evento]

<Rota metodo="GET" caminho="/tipo_de_evento/autocomplete" credencial />

Lista básica de tipos de evento para seleção

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Devolve só id, nome, descrição e o id do aplicativo dono, em ordem alfabética do nome, sem os excluídos. `busca` procura o trecho no nome e na descrição, sem diferenciar maiúsculas. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteTipoDeEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaTipoDeEventoAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_tipo_de_evento(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteTipoDeEvento,
) -> Result<tipos::PaginaTipoDeEventoAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_tipo_de_evento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompleteTipoDeEvento { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaTipoDeEventoAutoComplete>` · Rust: `Result<tipos::PaginaTipoDeEventoAutoComplete, ErroAoChamarServico>` · veja [`PaginaTipoDeEventoAutoComplete`](#tipo-paginatipodeeventoautocomplete).

## `buscar_pelo_filtro_tipo_de_evento` [#buscar_pelo_filtro_tipo_de_evento]

<Rota metodo="GET" caminho="/tipo_de_evento/filtro" credencial />

Busca tipos de evento por filtro

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Devolve todos os tipos não excluídos que casam com o filtro, sem paginação, em ordem alfabética do nome. `nome` procura o trecho no nome e na descrição, sem diferenciar maiúsculas; `aplicativo_dono_id` e `ativo` filtram pelo valor exato. Sem filtro, devolve todos.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroTipoDeEvento = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.TipoDeEvento>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_tipo_de_evento(credencial_de_acesso, { nome: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroTipoDeEvento,
) -> Result<Vec<tipos::TipoDeEvento>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_tipo_de_evento(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroTipoDeEvento { nome: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.nome": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.aplicativo_dono_id": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.ativo": { type: "boolean", required: false, description: "Rust: Option<bool>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.TipoDeEvento>>` · Rust: `Result<Vec<tipos::TipoDeEvento>, ErroAoChamarServico>`

## `buscar_pelo_id_tipo_de_evento` [#buscar_pelo_id_tipo_de_evento]

<Rota metodo="GET" caminho="/tipo_de_evento/{id}" credencial />

Busca um tipo de evento pelo id

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Tipo excluído não é encontrado. Traz o nome do aplicativo dono, as versões do esquema não excluídas (número e situação, em ordem crescente), a quantidade de assinaturas e a data do último evento recebido.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TipoDeEvento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_tipo_de_evento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::TipoDeEvento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_tipo_de_evento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TipoDeEvento>` · Rust: `Result<tipos::TipoDeEvento, ErroAoChamarServico>` · veja [`TipoDeEvento`](#tipo-tipodeevento).

## `atualizar_pelo_id_tipo_de_evento` [#atualizar_pelo_id_tipo_de_evento]

<Rota metodo="PATCH" caminho="/tipo_de_evento/{id}" credencial />

Atualiza um tipo de evento pelo id

Exige a permissão `editar` na área `contratos`. Atualização parcial: só os campos enviados mudam; o `nome` não pode ser alterado. `descricao` não pode ficar vazia (até 500 caracteres), `dias_de_retencao` vai de 1 a 3650 e `aplicativo_dono_id` precisa ser um aplicativo existente. O dono não pode mudar enquanto houver eventos publicados pelo dono atual ainda dentro da retenção. Desativar o tipo faz as próximas publicações dele serem recusadas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.TipoDeEventoAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.TipoDeEvento>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_tipo_de_evento(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::TipoDeEventoAtualizar,
) -> Result<tipos::TipoDeEvento, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_tipo_de_evento(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.TipoDeEventoAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::TipoDeEventoAtualizar", typeDescriptionLink: "#tipo-tipodeeventoatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.TipoDeEvento>` · Rust: `Result<tipos::TipoDeEvento, ErroAoChamarServico>` · veja [`TipoDeEvento`](#tipo-tipodeevento).

## `deletar_pelo_id_tipo_de_evento` [#deletar_pelo_id_tipo_de_evento]

<Rota metodo="DELETE" caminho="/tipo_de_evento/{id}" credencial />

Exclui um tipo de evento pelo id

Exige a permissão `deletar` na área `contratos`. A exclusão é lógica: o tipo e todas as versões do esquema dele somem das leituras e o nome fica livre para um novo cadastro, mas nada é apagado e não há como restaurar. Só exclui tipo sem assinaturas; exclua-as antes. Os eventos já recebidos continuam até vencer a retenção.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_tipo_de_evento(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_tipo_de_evento } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_tipo_de_evento(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_tipo_de_evento(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::webhook::deletar_pelo_id_tipo_de_evento(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaTipoDeEvento [#tipo-paginatipodeevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTipoDeEvento } from "termo_core/webhook";

export interface PaginaTipoDeEvento {
  itens: Array<PaginaTipoDeEventoItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaTipoDeEvento;

pub struct PaginaTipoDeEvento {
    pub itens: Vec<PaginaTipoDeEventoItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTipoDeEventoAutoComplete [#tipo-paginatipodeeventoautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTipoDeEventoAutoComplete } from "termo_core/webhook";

export interface PaginaTipoDeEventoAutoComplete {
  itens: Array<PaginaTipoDeEventoAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaTipoDeEventoAutoComplete;

pub struct PaginaTipoDeEventoAutoComplete {
    pub itens: Vec<PaginaTipoDeEventoAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaTipoDeEventoAutoCompleteItensItem [#tipo-paginatipodeeventoautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTipoDeEventoAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaTipoDeEventoAutoCompleteItensItem {
  aplicativo_dono_id: string;
  descricao: string;
  id: string;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaTipoDeEventoAutoCompleteItensItem;

pub struct PaginaTipoDeEventoAutoCompleteItensItem {
    pub aplicativo_dono_id: String,
    pub descricao: String,
    pub id: uuid::Uuid,
    pub nome: String,
}
```

</Tab>
</Tabs>

### PaginaTipoDeEventoItensItem [#tipo-paginatipodeeventoitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaTipoDeEventoItensItem } from "termo_core/webhook";

export interface PaginaTipoDeEventoItensItem {
  aplicativo_dono_id: string;
  aplicativo_dono_nome: string;
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao: string;
  dias_de_retencao: number;
  id: string;
  nome: string;
  quantidade_de_assinaturas: number;
  ultimo_evento_em?: string | null;
  versoes: Array<VersaoResumida>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaTipoDeEventoItensItem;

pub struct PaginaTipoDeEventoItensItem {
    pub aplicativo_dono_id: String,
    pub aplicativo_dono_nome: String,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub dias_de_retencao: i32,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_assinaturas: i64,
    pub ultimo_evento_em: Option<chrono::DateTime<chrono::Utc>>,
    pub versoes: Vec<VersaoResumida>,
}
```

</Tab>
</Tabs>

### TipoDeEvento [#tipo-tipodeevento]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TipoDeEvento } from "termo_core/webhook";

export interface TipoDeEvento {
  aplicativo_dono_id: string;
  aplicativo_dono_nome: string;
  ativo: boolean;
  atualizado_em: string;
  criado_em: string;
  descricao: string;
  dias_de_retencao: number;
  id: string;
  nome: string;
  quantidade_de_assinaturas: number;
  ultimo_evento_em?: string | null;
  versoes: Array<VersaoResumida>;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::TipoDeEvento;

pub struct TipoDeEvento {
    pub aplicativo_dono_id: String,
    pub aplicativo_dono_nome: String,
    pub ativo: bool,
    pub atualizado_em: chrono::DateTime<chrono::Utc>,
    pub criado_em: chrono::DateTime<chrono::Utc>,
    pub descricao: String,
    pub dias_de_retencao: i32,
    pub id: uuid::Uuid,
    pub nome: String,
    pub quantidade_de_assinaturas: i64,
    pub ultimo_evento_em: Option<chrono::DateTime<chrono::Utc>>,
    pub versoes: Vec<VersaoResumida>,
}
```

</Tab>
</Tabs>

### TipoDeEventoAtualizar [#tipo-tipodeeventoatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TipoDeEventoAtualizar } from "termo_core/webhook";

export interface TipoDeEventoAtualizar {
  aplicativo_dono_id?: string | null;
  ativo?: boolean | null;
  descricao?: string | null;
  dias_de_retencao?: number | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::TipoDeEventoAtualizar;

pub struct TipoDeEventoAtualizar {
    pub aplicativo_dono_id: Option<String>,
    pub ativo: Option<bool>,
    pub descricao: Option<String>,
    pub dias_de_retencao: Option<i32>,
}
```

</Tab>
</Tabs>

### TipoDeEventoCriar [#tipo-tipodeeventocriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { TipoDeEventoCriar } from "termo_core/webhook";

export interface TipoDeEventoCriar {
  aplicativo_dono_id: string;
  ativo?: boolean | null;
  descricao: string;
  dias_de_retencao?: number | null;
  nome: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::TipoDeEventoCriar;

pub struct TipoDeEventoCriar {
    pub aplicativo_dono_id: String,
    pub ativo: Option<bool>,
    pub descricao: String,
    pub dias_de_retencao: Option<i32>,
    pub nome: String,
}
```

</Tab>
</Tabs>

### VersaoResumida [#tipo-versaoresumida]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoResumida } from "termo_core/webhook";

export interface VersaoResumida {
  situacao: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::VersaoResumida;

pub struct VersaoResumida {
    pub situacao: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>


# Versão de esquema (/docs/servicos/webhook/versao_de_esquema)

> 7 funções do TermoWebhook para versão de esquema.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["webhook"] }
```

</Tab>
</Tabs>

| Função | Rota | O que faz |
| --- | --- | --- |
| [`buscar_paginador_versao_de_esquema`](#buscar_paginador_versao_de_esquema) | `GET /versao_de_esquema` | Lista as versões do esquema paginadas |
| [`criar_versao_de_esquema`](#criar_versao_de_esquema) | `POST /versao_de_esquema` | Cadastra uma versão do esquema de um tipo de evento |
| [`buscar_auto_complete_versao_de_esquema`](#buscar_auto_complete_versao_de_esquema) | `GET /versao_de_esquema/autocomplete` | Lista básica de versões do esquema para seleção |
| [`buscar_pelo_filtro_versao_de_esquema`](#buscar_pelo_filtro_versao_de_esquema) | `GET /versao_de_esquema/filtro` | Busca versões do esquema por filtro |
| [`buscar_pelo_id_versao_de_esquema`](#buscar_pelo_id_versao_de_esquema) | `GET /versao_de_esquema/{id}` | Busca uma versão do esquema pelo id |
| [`atualizar_pelo_id_versao_de_esquema`](#atualizar_pelo_id_versao_de_esquema) | `PATCH /versao_de_esquema/{id}` | Atualiza uma versão do esquema pelo id |
| [`deletar_pelo_id_versao_de_esquema`](#deletar_pelo_id_versao_de_esquema) | `DELETE /versao_de_esquema/{id}` | Exclui uma versão do esquema pelo id |

## `buscar_paginador_versao_de_esquema` [#buscar_paginador_versao_de_esquema]

<Rota metodo="GET" caminho="/versao_de_esquema" credencial />

Lista as versões do esquema paginadas

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Lista as versões não excluídas, ordenadas pelo nome do tipo e da versão mais nova para a mais velha. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10, sem máximo; valores menores que 1 viram 1. `total` é a quantidade de versões não excluídas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_paginador_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPaginadorVersaoDeEsquema = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaVersaoDeEsquema>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_paginador_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_paginador_versao_de_esquema(credencial_de_acesso, { pagina: 1 });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_paginador_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPaginadorVersaoDeEsquema,
) -> Result<tipos::PaginaVersaoDeEsquema, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_paginador_versao_de_esquema(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPaginadorVersaoDeEsquema { pagina: Some(1), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaVersaoDeEsquema>` · Rust: `Result<tipos::PaginaVersaoDeEsquema, ErroAoChamarServico>` · veja [`PaginaVersaoDeEsquema`](#tipo-paginaversaodeesquema).

## `criar_versao_de_esquema` [#criar_versao_de_esquema]

<Rota metodo="POST" caminho="/versao_de_esquema" credencial />

Cadastra uma versão do esquema de um tipo de evento

Exige a permissão `criar` na área `contratos`. `esquema_dos_dados` é o JSON Schema (um objeto, até 256 KB) contra o qual o campo `dados` de cada evento publicado nessa versão é validado; um esquema que não compila é recusado. `versao` é opcional e maior que zero: sem ela, o backend usa a próxima depois da maior já cadastrada para o tipo, contando as excluídas, porque número de versão excluída não volta. `situacao` é `ativa` (padrão), `descontinuada` (ainda aceita publicações) ou `desligada` (recusa publicações e novas assinaturas). `versao_do_pacote_de_contratos` vai até 100 caracteres; sem ela, fica registrado que veio do cadastro manual no painel.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function criar_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.VersaoDeEsquemaCriar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDeEsquema>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { criar_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await criar_versao_de_esquema(credencial_de_acesso, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn criar_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    corpo_da_requisicao: &tipos::VersaoDeEsquemaCriar,
) -> Result<tipos::VersaoDeEsquema, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::criar_versao_de_esquema(
    &credencial_de_acesso,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "corpo_da_requisicao": { type: "tipos.VersaoDeEsquemaCriar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::VersaoDeEsquemaCriar", typeDescriptionLink: "#tipo-versaodeesquemacriar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDeEsquema>` · Rust: `Result<tipos::VersaoDeEsquema, ErroAoChamarServico>` · veja [`VersaoDeEsquema`](#tipo-versaodeesquema).

## `buscar_auto_complete_versao_de_esquema` [#buscar_auto_complete_versao_de_esquema]

<Rota metodo="GET" caminho="/versao_de_esquema/autocomplete" credencial />

Lista básica de versões do esquema para seleção

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Devolve só id, tipo de evento, número e situação, sem o JSON Schema, ordenados pelo nome do tipo e pelo número da versão, sem as excluídas. `busca` procura o trecho no nome do tipo de evento, sem diferenciar maiúsculas; `tipo_de_evento_id` restringe a um tipo. `pagina` começa em 1 (padrão 1) e `tamanho` tem padrão 10.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_auto_complete_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarAutoCompleteVersaoDeEsquema = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PaginaVersaoDeEsquemaAutoComplete>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_auto_complete_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_auto_complete_versao_de_esquema(credencial_de_acesso, { busca: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_auto_complete_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarAutoCompleteVersaoDeEsquema,
) -> Result<tipos::PaginaVersaoDeEsquemaAutoComplete, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_auto_complete_versao_de_esquema(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarAutoCompleteVersaoDeEsquema { busca: Some("...".to_string()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.busca": { type: "string", required: false, description: "Rust: Option<String>" },
    "parametros.tipo_de_evento_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.pagina": { type: "number", required: false, description: "Rust: Option<i64>" },
    "parametros.tamanho": { type: "number", required: false, description: "Rust: Option<i64>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.PaginaVersaoDeEsquemaAutoComplete>` · Rust: `Result<tipos::PaginaVersaoDeEsquemaAutoComplete, ErroAoChamarServico>` · veja [`PaginaVersaoDeEsquemaAutoComplete`](#tipo-paginaversaodeesquemaautocomplete).

## `buscar_pelo_filtro_versao_de_esquema` [#buscar_pelo_filtro_versao_de_esquema]

<Rota metodo="GET" caminho="/versao_de_esquema/filtro" credencial />

Busca versões do esquema por filtro

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Devolve todas as versões não excluídas que casam com o filtro, sem paginação, ordenadas pelo nome do tipo e da versão mais nova para a mais velha. `tipo_de_evento_id` filtra pelo tipo; `situacao` é `ativa`, `descontinuada` ou `desligada`. Sem filtro, devolve todas.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_filtro_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  parametros: ParametrosDeBuscarPeloFiltroVersaoDeEsquema = {},
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<Array<tipos.VersaoDeEsquema>>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_filtro_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_filtro_versao_de_esquema(credencial_de_acesso, { tipo_de_evento_id: "..." });
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_filtro_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    parametros: &ParametrosDeBuscarPeloFiltroVersaoDeEsquema,
) -> Result<Vec<tipos::VersaoDeEsquema>, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_filtro_versao_de_esquema(
    &credencial_de_acesso,
    &termo_core::webhook::ParametrosDeBuscarPeloFiltroVersaoDeEsquema { tipo_de_evento_id: Some(Default::default()), ..Default::default() },
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "parametros.tipo_de_evento_id": { type: "string", required: false, description: "Rust: Option<uuid::Uuid>" },
    "parametros.situacao": { type: "string", required: false, description: "Rust: Option<String>" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<Array<tipos.VersaoDeEsquema>>` · Rust: `Result<Vec<tipos::VersaoDeEsquema>, ErroAoChamarServico>`

## `buscar_pelo_id_versao_de_esquema` [#buscar_pelo_id_versao_de_esquema]

<Rota metodo="GET" caminho="/versao_de_esquema/{id}" credencial />

Busca uma versão do esquema pelo id

Leitura liberada a quem tem a permissão `ler` em `contratos`, `assinaturas` ou `monitoramento`. Versão excluída não é encontrada. Traz o JSON Schema completo, o nome do tipo de evento, a situação, quando deixou de ser ativa (`descontinuada_em`) e quantas assinaturas usam a versão.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function buscar_pelo_id_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDeEsquema>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { buscar_pelo_id_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await buscar_pelo_id_versao_de_esquema(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn buscar_pelo_id_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<tipos::VersaoDeEsquema, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::buscar_pelo_id_versao_de_esquema(
    &credencial_de_acesso,
    id,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDeEsquema>` · Rust: `Result<tipos::VersaoDeEsquema, ErroAoChamarServico>` · veja [`VersaoDeEsquema`](#tipo-versaodeesquema).

## `atualizar_pelo_id_versao_de_esquema` [#atualizar_pelo_id_versao_de_esquema]

<Rota metodo="PATCH" caminho="/versao_de_esquema/{id}" credencial />

Atualiza uma versão do esquema pelo id

Exige a permissão `editar` na área `contratos`. Atualização parcial: só os campos enviados mudam; o tipo de evento e o número da versão não mudam. `esquema_dos_dados` segue as mesmas regras do cadastro (objeto JSON Schema válido, até 256 KB) e passa a valer para as próximas publicações. `situacao` é `ativa`, `descontinuada` ou `desligada`: ao sair de `ativa` a data de `descontinuada_em` é registrada, e ao voltar para `ativa` ela é limpa; `desligada` recusa novas publicações nessa versão. `versao_do_pacote_de_contratos` vai até 100 caracteres; texto vazio mantém o valor atual.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function atualizar_pelo_id_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  corpo_da_requisicao: tipos.VersaoDeEsquemaAtualizar,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.VersaoDeEsquema>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { atualizar_pelo_id_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await atualizar_pelo_id_versao_de_esquema(credencial_de_acesso, id, corpo_da_requisicao);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn atualizar_pelo_id_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
    corpo_da_requisicao: &tipos::VersaoDeEsquemaAtualizar,
) -> Result<tipos::VersaoDeEsquema, ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

let resposta = termo_core::webhook::atualizar_pelo_id_versao_de_esquema(
    &credencial_de_acesso,
    id,
    &corpo_da_requisicao,
)
.await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "corpo_da_requisicao": { type: "tipos.VersaoDeEsquemaAtualizar", required: true, description: "Corpo JSON da requisição. · Rust: &tipos::VersaoDeEsquemaAtualizar", typeDescriptionLink: "#tipo-versaodeesquemaatualizar" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<tipos.VersaoDeEsquema>` · Rust: `Result<tipos::VersaoDeEsquema, ErroAoChamarServico>` · veja [`VersaoDeEsquema`](#tipo-versaodeesquema).

## `deletar_pelo_id_versao_de_esquema` [#deletar_pelo_id_versao_de_esquema]

<Rota metodo="DELETE" caminho="/versao_de_esquema/{id}" credencial />

Exclui uma versão do esquema pelo id

Exige a permissão `deletar` na área `contratos`. A exclusão é lógica: a versão some das leituras e passa a recusar publicações, mas o registro não é apagado e não há como restaurar; o número dela não pode ser reaproveitado. Só exclui versão sem assinaturas; migre-as para outra versão ou exclua-as antes.

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
function deletar_pelo_id_versao_de_esquema(
  credencial_de_acesso: CredencialDeAcesso,
  id: string,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>
```

```ts title="Exemplo"
import { CredencialDeAcesso } from "termo_core";
import { deletar_pelo_id_versao_de_esquema } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
await deletar_pelo_id_versao_de_esquema(credencial_de_acesso, id);
```

</Tab>
<Tab value="Rust">

```rust
pub async fn deletar_pelo_id_versao_de_esquema(
    credencial_de_acesso: &CredencialDeAcesso,
    id: uuid::Uuid,
) -> Result<(), ErroAoChamarServico>
```

```rust title="Exemplo"
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);

termo_core::webhook::deletar_pelo_id_versao_de_esquema(&credencial_de_acesso, id).await?;
```

</Tab>
</Tabs>

**Argumentos**

<TypeTable
  type={{
    "credencial_de_acesso": { type: "CredencialDeAcesso", required: true, description: "Token do usuário logado ou do aplicativo. · Rust: &CredencialDeAcesso" },
    "id": { type: "string", required: true, description: "Parâmetro do caminho da rota. · Rust: uuid::Uuid" },
    "opcoes_da_chamada": { type: "OpcoesDaChamada", required: false, description: "Só no TypeScript: sinal_de_cancelamento e tempo_limite_em_milissegundos (padrão 30 s)." },
  }}
/>

**Retorno**: `Promise<void>` · Rust: `Result<(), ErroAoChamarServico>` · sem corpo na resposta.

## Tipos [#tipos]

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

### PaginaVersaoDeEsquema [#tipo-paginaversaodeesquema]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaVersaoDeEsquema } from "termo_core/webhook";

export interface PaginaVersaoDeEsquema {
  itens: Array<PaginaVersaoDeEsquemaItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaVersaoDeEsquema;

pub struct PaginaVersaoDeEsquema {
    pub itens: Vec<PaginaVersaoDeEsquemaItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaVersaoDeEsquemaAutoComplete [#tipo-paginaversaodeesquemaautocomplete]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaVersaoDeEsquemaAutoComplete } from "termo_core/webhook";

export interface PaginaVersaoDeEsquemaAutoComplete {
  itens: Array<PaginaVersaoDeEsquemaAutoCompleteItensItem>;
  pagina: number;
  tamanho: number;
  total: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaVersaoDeEsquemaAutoComplete;

pub struct PaginaVersaoDeEsquemaAutoComplete {
    pub itens: Vec<PaginaVersaoDeEsquemaAutoCompleteItensItem>,
    pub pagina: i64,
    pub tamanho: i64,
    pub total: i64,
}
```

</Tab>
</Tabs>

### PaginaVersaoDeEsquemaAutoCompleteItensItem [#tipo-paginaversaodeesquemaautocompleteitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaVersaoDeEsquemaAutoCompleteItensItem } from "termo_core/webhook";

export interface PaginaVersaoDeEsquemaAutoCompleteItensItem {
  id: string;
  situacao: string;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  versao: number;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaVersaoDeEsquemaAutoCompleteItensItem;

pub struct PaginaVersaoDeEsquemaAutoCompleteItensItem {
    pub id: uuid::Uuid,
    pub situacao: String,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub versao: i32,
}
```

</Tab>
</Tabs>

### PaginaVersaoDeEsquemaItensItem [#tipo-paginaversaodeesquemaitensitem]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { PaginaVersaoDeEsquemaItensItem } from "termo_core/webhook";

export interface PaginaVersaoDeEsquemaItensItem {
  atualizada_em: string;
  criada_em: string;
  descontinuada_em?: string | null;
  esquema_dos_dados: Record<string, unknown>;
  id: string;
  quantidade_de_assinaturas: number;
  situacao: string;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  versao: number;
  versao_do_pacote_de_contratos: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::PaginaVersaoDeEsquemaItensItem;

pub struct PaginaVersaoDeEsquemaItensItem {
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub descontinuada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub esquema_dos_dados: serde_json::Map<String, serde_json::Value>,
    pub id: uuid::Uuid,
    pub quantidade_de_assinaturas: i64,
    pub situacao: String,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub versao: i32,
    pub versao_do_pacote_de_contratos: String,
}
```

</Tab>
</Tabs>

### VersaoDeEsquema [#tipo-versaodeesquema]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDeEsquema } from "termo_core/webhook";

export interface VersaoDeEsquema {
  atualizada_em: string;
  criada_em: string;
  descontinuada_em?: string | null;
  esquema_dos_dados: Record<string, unknown>;
  id: string;
  quantidade_de_assinaturas: number;
  situacao: string;
  tipo_de_evento_id: string;
  tipo_de_evento_nome: string;
  versao: number;
  versao_do_pacote_de_contratos: string;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::VersaoDeEsquema;

pub struct VersaoDeEsquema {
    pub atualizada_em: chrono::DateTime<chrono::Utc>,
    pub criada_em: chrono::DateTime<chrono::Utc>,
    pub descontinuada_em: Option<chrono::DateTime<chrono::Utc>>,
    pub esquema_dos_dados: serde_json::Map<String, serde_json::Value>,
    pub id: uuid::Uuid,
    pub quantidade_de_assinaturas: i64,
    pub situacao: String,
    pub tipo_de_evento_id: uuid::Uuid,
    pub tipo_de_evento_nome: String,
    pub versao: i32,
    pub versao_do_pacote_de_contratos: String,
}
```

</Tab>
</Tabs>

### VersaoDeEsquemaAtualizar [#tipo-versaodeesquemaatualizar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDeEsquemaAtualizar } from "termo_core/webhook";

export interface VersaoDeEsquemaAtualizar {
  esquema_dos_dados?: Record<string, unknown> | null;
  situacao?: string | null;
  versao_do_pacote_de_contratos?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::VersaoDeEsquemaAtualizar;

pub struct VersaoDeEsquemaAtualizar {
    pub esquema_dos_dados: Option<serde_json::Map<String, serde_json::Value>>,
    pub situacao: Option<String>,
    pub versao_do_pacote_de_contratos: Option<String>,
}
```

</Tab>
</Tabs>

### VersaoDeEsquemaCriar [#tipo-versaodeesquemacriar]

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
import type { VersaoDeEsquemaCriar } from "termo_core/webhook";

export interface VersaoDeEsquemaCriar {
  esquema_dos_dados: Record<string, unknown>;
  situacao?: string | null;
  tipo_de_evento_id: string;
  versao?: number | null;
  versao_do_pacote_de_contratos?: string | null;
}
```

</Tab>
<Tab value="Rust">

```rust
use termo_core::webhook::VersaoDeEsquemaCriar;

pub struct VersaoDeEsquemaCriar {
    pub esquema_dos_dados: serde_json::Map<String, serde_json::Value>,
    pub situacao: Option<String>,
    pub tipo_de_evento_id: uuid::Uuid,
    pub versao: Option<i32>,
    pub versao_do_pacote_de_contratos: Option<String>,
}
```

</Tab>
</Tabs>


# TermoWMS (/docs/servicos/wms)

> Cliente do TermoWMS no termo_core.

{/* Gerado por scripts/gerar_paginas_dos_sdks.ts a partir dos pacotes termo_core. Não edite à mão. */}

<Tabs groupId="linguagem" persist items={["TypeScript", "Rust"]}>
<Tab value="TypeScript">

```ts
// npm install termo_core --save-exact
import * as wms from "termo_core/wms";
// ou: import { wms } from "termo_core";
```

</Tab>
<Tab value="Rust">

```toml title="Cargo.toml"
termo_core = { version = "=0.1.15", default-features = false, features = ["wms"] }
```

</Tab>
</Tabs>

## Resumo [#resumo]

| | |
| --- | --- |
| Módulo Rust | `termo_core::wms` (feature `wms`) |
| Importação TypeScript | `termo_core/wms` ou `import { wms } from "termo_core"` |
| Funções | 0 |
| Entidades | 0 |

## Endereços por ambiente [#endereços-por-ambiente]

O SDK escolhe o endereço sozinho, pela variável `AMBIENTE`. Você nunca configura URL.

| `AMBIENTE` | Endereço |
| --- | --- |
| `LOCALHOST` | o mesmo do sandbox (`https://sandbox-api-wms.termotubos.com.br`) |
| `SANDBOX` | `https://sandbox-api-wms.termotubos.com.br` |
| `PRODUCTION` | `https://api-wms.termotubos.com.br` |

<Callout type="info" title="Ainda sem funções">O TermoWMS ainda não publicou o `openapi.json` no sandbox, então o módulo existe mas não tem funções. Elas aparecem aqui sozinhas assim que o contrato for publicado e o gerador rodar.</Callout>