# Chaves de API
Source: https://docs.salvy.com.br/api-reference/v3/api-keys

Crie e gerencie chaves de API de empresa e de organização para integrar seus sistemas com a Salvy

Toda requisição para a API da Salvy precisa de uma chave de API. Ela identifica sua empresa e autoriza o acesso aos recursos da plataforma.

## Acessando a página

Você pode criar, listar e revogar chaves a qualquer momento na página de API & Webhooks, disponível em Configurações > Funcionalidades, ou diretamente em app.salvy.com.br/settings/api.

## Criando uma chave

1. Acesse a página de [API & Webhooks](https://app.salvy.com.br/settings/api).
2. Clique em **Criar chave de API**.
3. Selecione o ambiente da chave (**Sandbox** ou **Produção**) no seletor exibido acima do campo de nome. Veja [Ambientes](/api-reference/v3/environments) para entender a diferença.
4. Dê um nome (opcional) à chave para identificá-la depois, por exemplo o sistema ou a finalidade em que ela será usada.
5. Clique em **Criar chave**.

> [!WARNING]
>
> A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de
> fechar a janela.

Após copiar a chave, use-a no cabeçalho `Authorization` das suas requisições:

```
Authorization: Bearer <sua_chave>
```

Consulte a [Introdução](/api-reference/v3/introduction) para mais detalhes sobre autenticação.

## Revogando uma chave

Para revogar uma chave, clique no ícone de lixeira na coluna **Ações** e confirme a ação.

> [!WARNING]
>
> A revogação é imediata e não pode ser desfeita. Qualquer sistema que esteja
> utilizando a chave deixará de acessar a API assim que a revogação for
> confirmada.

Chaves revogadas continuam visíveis na tabela com o status **Revogada**, junto com a data e o usuário responsável pela revogação, para fins de auditoria.

## Boas práticas

* Crie uma chave separada para cada sistema ou finalidade (como produção, homologação ou integrações diferentes). Isso facilita o rastreamento e a revogação quando necessário.
* A Salvy tem os ambientes **sandbox** e **produção**, definidos pela chave utilizada. Use chaves de sandbox para desenvolvimento e testes. Entenda a diferença em [Ambientes](/api-reference/v3/environments).
* Nunca compartilhe chaves em repositórios públicos, e-mails ou mensagens. Armazene-as em um cofre de segredos.
* Revogue imediatamente qualquer chave que possa ter sido exposta e crie uma nova em seu lugar.
* Utilize nomes descritivos ao criar chaves para facilitar a identificação posterior.

## Chaves de organização

Chaves de organização autenticam como a sua **organização inteira**, e não como uma única empresa. Com uma chave de organização, uma mesma integração alcança **todas as empresas** da sua organização, sem precisar manter uma chave por empresa.

### Limitações atuais

> [!WARNING]
>
> **Chaves de organização são somente leitura.** Elas atendem apenas requisições
> de leitura (`GET`). Operações de escrita (`POST`, `PUT`, `PATCH`, `DELETE`) são
> bloqueadas e retornam `403 Forbidden` com a mensagem *"Organization API keys
> cannot perform this operation yet"*. Para escrever, use uma chave de empresa —
> o suporte a mutações com chave de organização será adicionado no futuro.

* **Apenas produção.** Chaves de organização existem somente no ambiente de produção (prefixo `salvy_org_prod_`). Ainda não há sandbox para chaves de organização.
* **Apenas na v3.** Funcionam apenas na versão 3 da API (`/api/v3/`). Em versões anteriores, utilize chaves de empresa.

### Chave de empresa ou de organização?

| | Chave de empresa | Chave de organização |
| - | - | - |
| Abrangência | Uma empresa | Todas as empresas da organização |
| Onde é criada | Configurações da empresa (`/settings/api`) | Configurações da organização (`/organization/settings/api`) |
| Quem pode criar | Conforme a permissão de chaves de API | Apenas administradores da organização |
| Prefixo | `salvy_prod_` | `salvy_org_prod_` |

Os endpoints passam a considerar todas as empresas da organização. Por exemplo, uma listagem retorna os recursos de todas as empresas de uma só vez — você não informa a empresa a cada requisição.

### Criando uma chave de organização

> [!NOTE]
>
> Apenas administradores da organização têm acesso a esta página.

1. Acesse [Configurações da organização > API](https://app.salvy.com.br/organization/settings/api).
2. Clique em **Criar chave de API**.
3. Dê um nome (opcional) à chave para identificá-la depois, por exemplo o sistema ou a finalidade em que ela será usada.
4. Selecione os escopos que a chave poderá utilizar.
5. Clique em **Criar chave**.

> [!WARNING]
>
> A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de
> fechar a janela.

Chaves de organização são criadas no ambiente de **produção** (prefixo `salvy_org_prod_`). Use-a no cabeçalho `Authorization` das suas requisições:

```bash theme={null}
curl -X GET "https://api.salvy.com.br/api/v3/cost-centers" \
-H "Authorization: Bearer salvy_org_prod_sua_chave_aqui"
```

### Revogando uma chave

Para revogar uma chave, clique no ícone de lixeira na coluna **Ações** e confirme a ação.

> [!WARNING]
>
> A revogação é imediata e não pode ser desfeita. Qualquer sistema que esteja
> utilizando a chave deixará de acessar a API assim que a revogação for
> confirmada.

Chaves revogadas continuam visíveis na tabela com o status **Revogada**, junto com a data e o usuário responsável pela revogação, para fins de auditoria.


# Listar DDDs
Source: https://docs.salvy.com.br/api-reference/v3/area-codes/list

api-reference/v3/openapi.json GET /api/v3/area-codes
Lista os DDDs em que a empresa pode criar uma linha do tipo informado, ordenados por DDD crescente, indicando se há número disponível em cada um no momento. No ambiente sandbox, para `mobile-did`, retorna apenas o DDD 41, do número de demonstração `+5541963475701`.

**Escopo necessário:** `phone-account:read`

# Detalhar termo
Source: https://docs.salvy.com.br/api-reference/v3/asset-statements/get

api-reference/v3/openapi.json GET /api/v3/asset-statements/{id}
Busca um termo de responsabilidade ou de devolução de equipamentos por ID. Para baixar o PDF assinado, use `GET /asset-statements/{id}/signed-file`.

**Escopo necessário:** `asset-statement:read`

# Listar termos
Source: https://docs.salvy.com.br/api-reference/v3/asset-statements/list

api-reference/v3/openapi.json GET /api/v3/asset-statements
Lista os termos de responsabilidade e de devolução de equipamentos da empresa, incluindo os enviados pelo dashboard, ordenados por data de envio decrescente (`createdAt`), com desempate por ID crescente. Use `assetId` e `employeeId` para buscar os termos de um equipamento ou de um colaborador.

**Escopo necessário:** `asset-statement:read`

# Enviar termo
Source: https://docs.salvy.com.br/api-reference/v3/asset-statements/send

api-reference/v3/openapi.json POST /api/v3/asset-statements
Envia um termo de responsabilidade ou de devolução de equipamentos para assinatura eletrônica do colaborador, por e-mail. Ao enviar um termo de responsabilidade, os termos de responsabilidade pendentes de assinatura que incluem algum dos mesmos equipamentos são cancelados e substituídos pelo novo. Termos de devolução não são substituídos. No ambiente sandbox nenhum e-mail é enviado: use `POST /asset-statements/{id}/simulate-signature` para simular a assinatura.

**Escopo necessário:** `asset-statement:send`

# Baixar termo assinado
Source: https://docs.salvy.com.br/api-reference/v3/asset-statements/signed-file

api-reference/v3/openapi.json GET /api/v3/asset-statements/{id}/signed-file
Baixa o PDF assinado de um termo de responsabilidade ou de devolução de equipamentos. Retorna 409 (`asset-statement-not-signed`) enquanto o termo não foi assinado.

**Escopo necessário:** `asset-statement:read`

# Simular assinatura do termo
Source: https://docs.salvy.com.br/api-reference/v3/asset-statements/simulate-signature

api-reference/v3/openapi.json POST /api/v3/asset-statements/{id}/simulate-signature
Simula a assinatura de um termo pelo colaborador: o termo passa para `signed`, o PDF assinado fica disponível e o webhook `asset-statement.signed` é disparado. Disponível apenas no ambiente sandbox.

**Escopo necessário:** `asset-statement:simulate-signature`

# Arquivar equipamento
Source: https://docs.salvy.com.br/api-reference/v3/assets/archive

api-reference/v3/openapi.json POST /api/v3/assets/{id}/archive
Arquiva um equipamento por ID.

**Escopo necessário:** `asset:archive`

# Criar equipamento
Source: https://docs.salvy.com.br/api-reference/v3/assets/create

api-reference/v3/openapi.json POST /api/v3/assets
Cria um novo equipamento.

**Escopo necessário:** `asset:create`

# Registrar anotação na linha do tempo
Source: https://docs.salvy.com.br/api-reference/v3/assets/create-timeline-note

api-reference/v3/openapi.json POST /api/v3/assets/{id}/timeline-notes
Registra uma anotação na linha do tempo de um equipamento

**Escopo necessário:** `asset:update`

Este endpoint permite registrar uma anotação na linha do tempo de um equipamento, útil para documentar eventos como manutenções, trocas ou ocorrências relacionadas ao ativo.


# Remover equipamento
Source: https://docs.salvy.com.br/api-reference/v3/assets/delete

api-reference/v3/openapi.json DELETE /api/v3/assets/{id}
Remove um equipamento por ID. Diferente do arquivamento (POST /assets/:id/archive), que é reversível, a remoção é definitiva na API: o equipamento deixa de aparecer em buscas, listagens e buscas por ID.

**Escopo necessário:** `asset:delete`

# Detalhar equipamento
Source: https://docs.salvy.com.br/api-reference/v3/assets/get

api-reference/v3/openapi.json GET /api/v3/assets/{id}
Busca um equipamento pelo ID.

**Escopo necessário:** `asset:read`

# Listar equipamentos
Source: https://docs.salvy.com.br/api-reference/v3/assets/list

api-reference/v3/openapi.json GET /api/v3/assets
Lista os equipamentos da empresa, ordenados por data de criação decrescente (`createdAt`) por padrão, com desempate por ID crescente. Use `sortBy`/`sortOrder` para alterar o campo e a direção da ordenação.

**Escopo necessário:** `asset:read`

# Desarquivar equipamento
Source: https://docs.salvy.com.br/api-reference/v3/assets/unarchive

api-reference/v3/openapi.json POST /api/v3/assets/{id}/unarchive
Desarquiva um equipamento por ID.

**Escopo necessário:** `asset:archive`

# Atualizar equipamento
Source: https://docs.salvy.com.br/api-reference/v3/assets/update

api-reference/v3/openapi.json PATCH /api/v3/assets/{id}
Atualiza um equipamento por ID. Somente os campos enviados no corpo da requisição são alterados; campos omitidos permanecem inalterados.

**Escopo necessário:** `asset:update`

# Branding para integrações
Source: https://docs.salvy.com.br/api-reference/v3/branding

Quando uma integração usa a API ou Webhooks da Salvy, parte da experiência passa a acontecer fora da plataforma. Nesses casos, a assinatura powered by + logo Salvy identifica que aquela funcionalidade é viabilizada pela Salvy e ajuda a manter uma experiência consistente para o usuário final.

Pra garantir que a Salvy siga visível e consistente, definimos o uso da assinatura **powered by + logo Salvy**.

### 1. Assinatura obrigatória

* Forma oficial: **powered by \[logo Salvy]**
* Sempre escrito assim, com "powered by" em texto e **Salvy** representado pelo logo oficial.
* Não usar variações como "Powered By", "by Salvy", "Salvy inside" etc.

### 2. Como aplicar

**Tipografia**

* "powered by" em **[Inter](https://fonts.google.com/specimen/Inter).**
* Sempre em minúsculas: *powered by*.
* O "Salvy" nunca deve ser escrito em texto: sempre usar o logo.

**Cor**

* Texto "powered by" em preto (#232323), branco (#FFFFFF) ou cinza (#CBCBCB), sempre garantindo contraste suficiente com o fundo.
* Logo Salvy sempre na versão original (utilizar asset disponível para download nessa página).

**Tamanho**

* Para o uso vertical, o tamanho mínimo deve ser **→** 92 px x **↑** 85 px.
* Para o uso horizonal, o tamanho mínimo deve ser **→** 195 px x **↑** 49 px.

### 2.1 Formatos permitidos

**Horizontal (preferencial)**

* `powered by [logo Salvy]` na mesma linha.
* Ideal para rodapés, mensagens e telas com espaço horizontal.

**Vertical (alternativo)**

* "powered by" em cima
* \[logo Salvy] embaixo
* Usar só quando o espaço horizontal for limitado (ex.: layouts muito estreitos, mobile em coluna).

### 2.2 Regras de uso

* Não substituir o logo por texto.
* Não alterar o logo da Salvy (cor, proporção, efeitos).
* Não usar só o logo, sem o "powered by".
* Nunca quebrar o texto no meio (ex.: "powered" em cima e "by + logo" embaixo).
* Proporção do logo deve ser mantida nos dois formatos.
* Respeitar espaçamentos:
  * Horizontal → respiro lateral entre o texto e o logo.
  * Vertical → respiro vertical equivalente à altura do "by".

### 3. Exemplos

✅ Correto

`powered by [logo Salvy]` discreto, legível, no rodapé.

![powerdby-certo.png](https://mintcdn.com/salvy-88fe5c1a/WMdeF5Fcej9gPiz6/assets/powerdby-certo.png?fit=max\&auto=format\&n=WMdeF5Fcej9gPiz6\&q=85\&s=0c2510aeebf5da9e7840c525b7b82c34)

❌ Incorreto

"powered by Salvy" em texto puro | logo colorido aleatoriamente | proporções incorretas.

![powerdby-errado.png](https://mintcdn.com/salvy-88fe5c1a/WMdeF5Fcej9gPiz6/assets/powerdby-errado.png?fit=max\&auto=format\&n=WMdeF5Fcej9gPiz6\&q=85\&s=8f308fab00688c578ecd55c238e84d32)

### 4. Onde usar

* Rodapé de telas integradas.
* Mensagens automáticas enviadas pela API.
* Dashboards ou relatórios gerados pela integração.
* Pop-ups ou confirmações que dependem da Salvy.

### 5. Dúvidas?

Se ficar na dúvida sobre a aplicação ou precisar de exceção, fale com o time da Salvy.

### Assets - Logo Salvy

[fio. | Design system da Salvy](https://design.salvy.com.br/logo)


# Listar empresas
Source: https://docs.salvy.com.br/api-reference/v3/companies/list

api-reference/v3/openapi.json GET /api/v3/companies
Lista as empresas acessíveis pela credencial, ordenadas por identificador. Uma chave de empresa retorna apenas a própria empresa; uma chave de organização retorna todas as empresas da organização.

**Escopo necessário:** `company:read`

# Criar centro de custo
Source: https://docs.salvy.com.br/api-reference/v3/cost-centers/create

api-reference/v3/openapi.json POST /api/v3/cost-centers
Cria um novo centro de custo — o mesmo efeito de cadastrá-lo pelo painel.

**Escopo necessário:** `cost-center:create`

# Remover centro de custo
Source: https://docs.salvy.com.br/api-reference/v3/cost-centers/delete

api-reference/v3/openapi.json DELETE /api/v3/cost-centers/{id}
Exclui um centro de custo. As linhas e os colaboradores vinculados a ele são transferidos para o centro de custo informado em `replacementId`; quando `replacementId` é `null`, ficam sem centro de custo.

**Escopo necessário:** `cost-center:delete`

# Detalhar centro de custo
Source: https://docs.salvy.com.br/api-reference/v3/cost-centers/get

api-reference/v3/openapi.json GET /api/v3/cost-centers/{id}
Busca um centro de custo da empresa pelo ID.

**Escopo necessário:** `cost-center:read`

# Listar centros de custo
Source: https://docs.salvy.com.br/api-reference/v3/cost-centers/list

api-reference/v3/openapi.json GET /api/v3/cost-centers
Lista os centros de custo da empresa, ordenados por nome (A→Z), com desempate por ID crescente.

**Escopo necessário:** `cost-center:read`

# Atualizar centro de custo
Source: https://docs.salvy.com.br/api-reference/v3/cost-centers/update

api-reference/v3/openapi.json PATCH /api/v3/cost-centers/{id}
Atualiza um centro de custo por ID. Somente os campos enviados no corpo são alterados; campos omitidos permanecem inalterados.

**Escopo necessário:** `cost-center:update`

# Deprecação
Source: https://docs.salvy.com.br/api-reference/v3/deprecation

Identifique pelos cabeçalhos da resposta quando um endpoint está em fim de vida e quanto tempo você tem para migrar

Conforme a API evolui, alguns endpoints e versões saem de circulação. Quando isso acontece, a Salvy avisa **em toda resposta do endpoint afetado**, através de cabeçalhos HTTP padronizados.

Isso significa que a própria integração pode detectar a deprecação e avisar o seu time, sem depender de alguém ler um aviso na caixa de entrada.

> [!TIP]
>
> Se você fizer só uma coisa nesta página, faça esta: registre um log ou alerta
> sempre que uma resposta da Salvy vier com o cabeçalho `Sunset`.

## Por onde o aviso chega

* **Cabeçalhos HTTP** — em toda resposta do endpoint deprecado. É o único canal que acompanha cada requisição e, por isso, o único que a sua integração não corre o risco de perder.
* **Especificação OpenAPI** — a operação passa a ser publicada como deprecada, com as datas e o caminho de migração na descrição.
* **E-mail** — a Salvy também comunica as deprecações da API por e-mail para os contatos da sua empresa.

> [!WARNING]
>
> Quem recebe o aviso depende de quando a chave de API foi criada: para chaves
> a partir de 07/2026, avisamos quem criou a chave; para chaves anteriores, o
> e-mail de contato da empresa. Confirme com o seu contato na Salvy quem recebe
> esses avisos hoje, sobretudo se quem criou a chave não for mais quem mantém a
> integração.

## Como a Salvy sinaliza uma deprecação

Três cabeçalhos acompanham as respostas de um endpoint deprecado:

| Cabeçalho | O que informa | Exemplo |
| - | - | - |
| `Deprecation` | Quando o endpoint passou (ou passará) a ser considerado deprecado | `@1782863999` |
| `Sunset` | A partir de quando ele deixa de ser atendido | `Thu, 31 Dec 2026 23:59:59 GMT` |
| `Link` | Documentação da mudança e, quando existe, o endpoint substituto | veja abaixo |

Uma resposta completa se parece com isto:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1782863999
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.salvy.com.br/api-reference/deprecation>; rel="deprecation"; type="text/html",
      <https://api.salvy.com.br/api/v2/virtual-phone-accounts>; rel="successor-version"
```

* `rel="deprecation"` aponta para a página que explica a mudança e o caminho de migração.
* `rel="successor-version"` aponta para o endpoint que substitui o atual. Ele só aparece quando existe um substituto direto.

### Os dois formatos de data são diferentes

Não é um erro de digitação:

* `Deprecation` usa um **timestamp Unix em segundos**, prefixado por `@` — conforme a [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html).
* `Sunset` usa uma **data HTTP** (`IMF-fixdate`) — conforme a [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html).

Como são cabeçalhos padronizados, é possível que a sua biblioteca HTTP, gateway ou ferramenta de observabilidade já saiba interpretá-los.

## Como consumir os cabeçalhos

A checagem mínima é olhar para a presença de `Sunset`:

```js theme={null}
const response = await fetch(
  'https://api.salvy.com.br/api/v2/virtual-phone-accounts',
  {
    headers: { Authorization: `Bearer ${process.env.SALVY_API_KEY}` },
  },
);

const sunset = response.headers.get('Sunset');

if (sunset) {
  // Encaminhe para onde o seu time realmente olha: log estruturado,
  // Sentry, Slack, o que for.
  console.warn(
    `[salvy] endpoint deprecado, deixa de ser atendido em ${sunset}.`,
    `Detalhes: ${response.headers.get('Link')}`,
  );
}
```

Para inspecionar manualmente, basta pedir os cabeçalhos no `curl`:

```bash theme={null}
curl -i -X GET "https://api.salvy.com.br/api/v2/virtual-phone-accounts" \
-H "Authorization: Bearer salvy_prod_sua_chave_aqui"
```

> [!WARNING]
>
> Avise uma vez por processo, não uma vez por requisição. Um alerta a cada
> chamada transforma o aviso em ruído e o seu time passa a ignorá-lo.

## Em quais respostas os cabeçalhos aparecem

Os cabeçalhos acompanham as respostas **autenticadas** do endpoint, incluindo as de erro. Se você recebe um `404` ou um `422` de um endpoint deprecado, o aviso vem junto.

Eles **não** aparecem em respostas `401` e `403`, porque a autenticação é avaliada antes. Uma chave inválida devolve o erro de autenticação e nada mais.

## Onde mais a deprecação aparece

Além dos cabeçalhos, a deprecação é publicada na especificação OpenAPI da API pública:

* a operação é marcada com `deprecated: true`, o que faz ferramentas como Postman, Insomnia e geradores de cliente exibirem o endpoint como obsoleto;
* a descrição da operação começa com `[DEPRECADO]`, seguido das datas e do link de migração;
* os cabeçalhos acima estão documentados nas respostas da operação.

Ou seja: se a sua integração é gerada a partir da especificação, a informação chega até você sem esforço adicional.

## O que fazer quando você vê o aviso

**1. Registre**

Garanta que a presença de `Sunset` gere um log ou alerta em algum lugar que
o seu time acompanhe.

**2. Leia a documentação da mudança**

Abra a URL indicada em `rel="deprecation"`. Ela descreve o que muda e o que
é necessário para migrar.

**3. Migre para o substituto**

Quando houver `rel="successor-version"`, aponte a sua integração para o novo
endpoint. Diferenças de contrato estão descritas na documentação da mudança.

**4. Valide no sandbox**

Teste a integração migrada com uma chave `salvy_test_` antes de trocar em
produção. Veja [Ambientes](/api-reference/v3/environments).

> [!WARNING]
>
> A partir da data indicada em `Sunset`, a Salvy não garante mais o
> funcionamento do endpoint. Conclua a migração antes dessa data.

## Versões da API

Endpoints da API pública são versionados no caminho (`/api/v1/...`, `/api/v2/...`). Uma versão mais nova de um endpoint não invalida a anterior automaticamente: quando uma versão for deprecada, ela passará a responder com os cabeçalhos descritos nesta página.

Em caso de dúvida sobre um aviso de deprecação que você recebeu, fale com o seu contato na Salvy.


# Sincronizar colaboradores em lote
Source: https://docs.salvy.com.br/api-reference/v3/employees/batch-sync

api-reference/v3/openapi.json POST /api/v3/employees/batch-sync
Cria ou atualiza vários colaboradores de uma vez, identificados pelo `integrationId` de sua escolha. A requisição é aceita por inteiro ou recusada por inteiro: se algum colaborador for inválido, nenhum é alterado e a resposta aponta a posição dele na lista. Os colaboradores são sincronizados em segundo plano; a resposta traz o ID de uma tarefa para acompanhar o resultado em GET /tasks/{id}.

**Escopo necessário:** `employee:sync`

# Criar colaborador
Source: https://docs.salvy.com.br/api-reference/v3/employees/create

api-reference/v3/openapi.json POST /api/v3/employees
Cria um novo colaborador — o mesmo efeito de cadastrá-lo pelo painel. O colaborador retornado já vem com os dados consolidados, inclusive o que vier das suas integrações.

**Escopo necessário:** `employee:create`

# Remover colaborador
Source: https://docs.salvy.com.br/api-reference/v3/employees/delete

api-reference/v3/openapi.json DELETE /api/v3/employees/{id}
Remove um colaborador por ID, junto com tudo o que as suas integrações trouxeram sobre ele. O registro deixa de existir para a API e para o /sync — não há como desfazer pela API. Uma integração que volte a reportar a mesma pessoa cria um colaborador novo, com outro ID.

**Escopo necessário:** `employee:delete`

# Detalhar colaborador
Source: https://docs.salvy.com.br/api-reference/v3/employees/get

api-reference/v3/openapi.json GET /api/v3/employees/{id}
Busca um colaborador da empresa pelo ID.

**Escopo necessário:** `employee:read`

# Listar colaboradores
Source: https://docs.salvy.com.br/api-reference/v3/employees/list

api-reference/v3/openapi.json GET /api/v3/employees
Lista os colaboradores da empresa, ordenados por data de criação decrescente (`createdAt`) por padrão, com desempate por ID crescente. Use `sortBy`/`sortOrder` para alterar o campo e a direção da ordenação.

**Escopo necessário:** `employee:read`

# Atualizar colaborador
Source: https://docs.salvy.com.br/api-reference/v3/employees/update

api-reference/v3/openapi.json PATCH /api/v3/employees/{id}
Atualiza um colaborador por ID. Somente os campos enviados no corpo são alterados; campos omitidos permanecem inalterados. Editar pela API ou pelo painel dá no mesmo: vale a alteração mais recente, campo a campo. Enviar um campo como null apaga o que foi editado nele: se alguma integração informa esse campo, o valor dela volta a valer; senão, o campo fica vazio. O que vem de integração nunca se sobrepõe a uma edição. O colaborador retornado já vem com os dados consolidados.

**Escopo necessário:** `employee:update`

# Ambientes
Source: https://docs.salvy.com.br/api-reference/v3/environments

Entenda os ambientes de sandbox e produção da API da Salvy e como alternar entre eles

A API da Salvy oferece dois ambientes: sandbox e produção.

Você não precisa trocar a URL da API para alternar entre eles. O ambiente é definido pela chave de API utilizada.

* **Produção**: executa ações reais, como envio de SMS, e-mails, notificações e cobranças.
* **Sandbox**: ambiente isolado para desenvolvimento e testes. Nenhuma ação externa real (SMS, e-mail, notificações e outras) é executada.

> [!TIP]
>
> Você pode usar a mesma URL em desenvolvimento e produção. Para trocar de
> ambiente, basta trocar a chave de API.

## Como o ambiente é escolhido

Você não muda o endereço nem envia nenhum parâmetro especial. Basta usar a chave do ambiente desejado no cabeçalho `Authorization`. Você identifica o ambiente e o tipo da chave pelo prefixo:

| Tipo de chave | Produção | Sandbox |
| - | - | - |
| Empresa | `salvy_prod_` | `salvy_test_` |
| Organização | `salvy_org_prod_` | — |

> [!WARNING]
>
> Chaves de API de empresa anteriores a 07/2026 não têm prefixo.

> [!NOTE]
>
> Chaves de organização são emitidas apenas em **produção** por enquanto
> (prefixo `salvy_org_prod_`). O suporte a sandbox para chaves de organização
> será adicionado quando disponível.

```bash Produção theme={null}
curl -X GET "https://api.salvy.com.br/api/v3/cost-centers" \
-H "Authorization: Bearer salvy_prod_sua_chave_aqui"
```

```bash Sandbox theme={null}
curl -X GET "https://api.salvy.com.br/api/v3/cost-centers" \
-H "Authorization: Bearer salvy_test_sua_chave_aqui"
```

## Primeiros passos no sandbox

Para começar a testar, crie uma chave de sandbox. O passo a passo está no guia de [Chaves de API](/api-reference/v3/api-keys).

Quando você cria a primeira chave de sandbox, a Salvy cria automaticamente um ambiente de testes para a sua empresa.

Esse ambiente copia apenas o perfil da empresa (como razão social, CNPJ e endereço). Os dados operacionais começam vazios e as próximas chaves de sandbox utilizam esse mesmo ambiente.

### O que é replicado

* O **perfil** da sua empresa é copiado, para que o sandbox represente a sua organização.
* Os **dados** (linhas, colaboradores, equipamentos) não são copiados: o sandbox começa vazio. Você cria os dados de teste via API, da mesma forma que faria em produção.
* Tudo o que você cria no sandbox, como colaboradores, ativos, linhas e outros recursos, fica **isolado** de produção.

## Comportamento no sandbox

> [!WARNING]
>
> Uma resposta 2xx significa que a Salvy processou a requisição com sucesso. No
> sandbox, isso não significa que uma ação real (como o envio de uma mensagem)
> foi executada para um destinatário real.

Nenhuma operação no sandbox gera cobrança. Tudo o que você cria no sandbox fica isolado de produção.

### Linhas mobile-did no sandbox

No sandbox, a [criação de uma linha mobile-did](/api-reference/v3/phone-accounts/create-mobile-did) sempre retorna o **mesmo número de demonstração**, `+5541963475701`, para qualquer empresa. Nenhum número real é reservado.

* Apenas o **DDD 41** é aceito. Outro DDD retorna `409` com o código `phone-account-area-code-out-of-stock`.
* A [listagem de DDDs](/api-reference/v3/area-codes/list) com `productType=mobile-did` retorna apenas o DDD 41.

### Termos de equipamentos no sandbox

No sandbox, o [envio de um termo](/api-reference/v3/asset-statements/send) não manda e-mail para o colaborador e não gera um documento real para assinatura. O termo é criado com `status` `pending-signature`, como em produção.

Para testar o fluxo de assinatura:

1. Envie o termo com [Enviar termo](/api-reference/v3/asset-statements/send) e guarde o `id` retornado.
2. Simule a assinatura com [Simular assinatura do termo](/api-reference/v3/asset-statements/simulate-signature). O termo passa para `signed`, o PDF assinado fica disponível em [Baixar termo assinado](/api-reference/v3/asset-statements/signed-file) e o webhook [Termo assinado](/api-reference/v3/webhooks/asset-statement-signed) é disparado.

A simulação só está disponível com chaves de sandbox e para termos enviados no sandbox. Um termo cancelado não pode ter a assinatura simulada.

## Boas práticas e segurança

> [!WARNING]
>
> **Não misture as chaves.** Como o endereço é o mesmo nos dois ambientes, usar
> uma chave de produção em um teste executa ações reais, incluindo envios e
> cobranças. Confirme sempre o prefixo da chave antes de usá-la.

* Use chaves de **sandbox** (`salvy_test_`) em desenvolvimento e testes automatizados.
* Guarde as chaves de produção e de sandbox separadamente e com nomes descritivos. Veja [Chaves de API](/api-reference/v3/api-keys).
* Valide toda a sua integração no sandbox antes de trocar para uma chave de produção.


# Introdução
Source: https://docs.salvy.com.br/api-reference/v3/introduction

A API da Salvy permite integrar seus sistemas aos produtos da plataforma. Nesta documentação você encontrará tudo o que precisa para autenticar suas requisições, entender os ambientes disponíveis e começar a utilizar os endpoints.

Bem-vindo à documentação da API da Salvy! Esta API foi projetada para oferecer uma interface eficiente, segura e robusta para acessar e interagir com os serviços da Salvy. Aqui você encontrará todas as informações necessárias para integrar-se à nossa plataforma e começar a construir soluções incríveis.

## Endereço Base da API

Todas as requisições à API devem ser feitas para o seguinte endereço base:

```
https://api.salvy.com.br
```

Os endpoints da versão 3 ficam sob o caminho `/api/v3/`. Certifique-se de usar HTTPS em todas as suas requisições para garantir a segurança da comunicação.

A Salvy oferece os ambientes de produção e sandbox, ambos neste mesmo endereço base. O ambiente é definido pela chave de API utilizada. Saiba mais em [Ambientes](/api-reference/v3/environments).

## Autenticação

Para cada requisição o método de autenticação é baseado em **Bearer Token** para garantir acesso seguro aos seus recursos. Para cada requisição à API, é necessário incluir um token de autenticação válido no cabeçalho HTTP `Authorization`.

### Chaves de empresa e de organização

A Salvy tem dois tipos de chave, e o tipo define a abrangência da chave:

* **Chave de empresa**: acessa os recursos de **uma empresa**. Criada nas configurações da empresa.
* **Chave de organização**: acessa os recursos de **todas as empresas** da sua organização, com uma única chave. Criada por administradores nas configurações da organização. É **somente leitura** e existe apenas em produção — veja [Chaves de API](/api-reference/v3/api-keys).

Consulte o guia de [Chaves de API](/api-reference/v3/api-keys) para criar cada tipo e entender quando usar cada um.

### Como obter seu token

Você pode criar e gerenciar suas chaves de API diretamente no dashboard: chaves de empresa em [API & Webhooks](https://app.salvy.com.br/settings/api) e chaves de organização em [Configurações da organização > API](https://app.salvy.com.br/organization/settings/api).

> [!WARNING]
>
> A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de
> fechar a janela.

### Formato do Cabeçalho

O token deve ser enviado no seguinte formato:

```
Authorization: Bearer <seu_token>
```

* Substitua `<seu_token>` pelo token fornecido pela Salvy.
* O prefixo `Bearer` é obrigatório e deve ser seguido por um espaço antes do token.

### Exemplo de Requisição

Aqui está um exemplo de requisição usando `curl`:

```bash Chave de empresa theme={null}
curl -X GET "https://api.salvy.com.br/api/v3/cost-centers" \
-H "Authorization: Bearer salvy_prod_abc123def456gh789" \
-H "Content-Type: application/json"
```

```bash Chave de organização theme={null}
curl -X GET "https://api.salvy.com.br/api/v3/cost-centers" \
-H "Authorization: Bearer salvy_org_prod_abc123def456gh789" \
-H "Content-Type: application/json"
```

### Erros de Autenticação

Se o token não for fornecido ou for inválido, a API retornará um erro com o código de status `HTTP 401 Unauthorized`. Verifique se:

* O token está correto.
* O token não expirou.
* O cabeçalho Authorization segue o formato especificado.


# Detalhar fatura
Source: https://docs.salvy.com.br/api-reference/v3/invoices/get

api-reference/v3/openapi.json GET /api/v3/invoices/{id}
Busca uma fatura pelo ID, com os itens, a nota fiscal e o detalhamento por linha do que foi faturado no período.

**Escopo necessário:** `invoice:read`

# Listar faturas
Source: https://docs.salvy.com.br/api-reference/v3/invoices/list

api-reference/v3/openapi.json GET /api/v3/invoices
Lista as faturas, ordenadas por data de vencimento, utilize monthYear para pegar faturas referentes a um mês.

**Escopo necessário:** `invoice:read`

# Baixar PDF da nota fiscal
Source: https://docs.salvy.com.br/api-reference/v3/invoices/nfe-pdf

api-reference/v3/openapi.json GET /api/v3/invoices/{id}/nfe/pdf
Baixa o PDF (DANFE) da nota fiscal emitida da fatura, quando houver.

**Escopo necessário:** `invoice:read`

# Baixar XML da nota fiscal
Source: https://docs.salvy.com.br/api-reference/v3/invoices/nfe-xml

api-reference/v3/openapi.json GET /api/v3/invoices/{id}/nfe/xml
Baixa o XML da nota fiscal emitida da fatura, quando houver.

**Escopo necessário:** `invoice:read`

# Baixar PDF da fatura
Source: https://docs.salvy.com.br/api-reference/v3/invoices/pdf

api-reference/v3/openapi.json GET /api/v3/invoices/{id}/pdf
Baixa o PDF da fatura, com os dados de pagamento (boleto e Pix) da cobrança vigente. Não é a nota fiscal: para o DANFE, use `GET /invoices/{id}/nfe/pdf`. Não disponível no ambiente sandbox: sempre retorna 404.

**Escopo necessário:** `invoice:read`

# Listar linhas da fatura
Source: https://docs.salvy.com.br/api-reference/v3/invoices/phone-accounts

api-reference/v3/openapi.json GET /api/v3/invoices/{id}/phone-accounts
Lista o detalhamento por linha de uma fatura, da linha de maior valor para a de menor. Cada item traz os valores da linha no momento do fechamento da fatura. Vazio em faturas que não são de telecom, e em faturas de telecom fechadas antes do registro deste detalhamento.

**Escopo necessário:** `invoice:read`

# Migrando da v1 para a v3
Source: https://docs.salvy.com.br/api-reference/v3/migration-guide

O que muda ao trocar a v1 pela v3: o equivalente de cada endpoint, as mudanças de contrato e o que não tem substituto

A v1 da API está deprecada desde 11/08/2026 e **deixa de ser atendida em 01/02/2027**. Esta página mostra, endpoint por endpoint, onde cada chamada da v1 fica na v3 e o que muda no contrato.

> [!TIP]
>
> Migre e valide tudo no sandbox antes de trocar em produção: basta usar uma
> chave `salvy_test_`. Veja [Ambientes](/api-reference/v3/environments).

## Migrando com a ajuda de uma IA

Se você usa um assistente de código (Claude, ChatGPT, Cursor, Copilot…), copie o prompt abaixo e cole no assistente, dentro do repositório da sua integração. Ele lê este guia e a especificação da v3 e faz a migração por você, deixando o que não tiver equivalente para você decidir.

```text theme={null}
Migre a integração deste repositório da API da Salvy da v1 para a v3.

Fontes de verdade (leia antes de começar):
- Guia de migração: https://docs.salvy.com.br/api-reference/v3/migration-guide.md
- Especificação da v3: https://docs.salvy.com.br/api-reference/v3/openapi.json
- Índice da documentação: https://docs.salvy.com.br/llms.txt

O que fazer:
1. Encontre todas as chamadas para /api/v1/ no código.
2. Troque cada uma pelo equivalente na v3 indicado no guia, incluindo os métodos HTTP que mudaram.
3. Adapte as listagens para ler `data` e paginar com `page` e `pageSize` até `totalPages`.
4. Adapte o tratamento de erros: os campos que vinham em `publicDetails` passam a vir na raiz da resposta.
5. Na criação de números virtuais, renomeie os campos conforme o guia. No cancelamento, envie `reason`, que é obrigatório.
6. Troque POST /api/v1/employees/sync por POST /api/v3/employees/batch-sync, enviando os colaboradores em lote e acompanhando o resultado pela tarefa devolvida, conforme a seção de sincronização do guia.

Regras:
- Não invente endpoints, campos ou códigos de erro: use só o que está no guia e na especificação.
- Não remova funcionalidade silenciosamente. O redirecionamento de chamadas não existe na v3: remova o uso dele e liste cada ocorrência no resumo final, para que eu decida o que fazer.
- Atualize ou crie testes para cada chamada alterada.
- Não use chaves de produção. Para testar, use uma chave de sandbox (`salvy_test_`).

No final, me mostre um resumo com: cada chamada alterada (antes → depois), o que você não conseguiu migrar e por quê, e o que eu preciso validar manualmente.
```

> [!WARNING]
>
> Revise as mudanças antes de publicar. O assistente segue o guia, mas quem
> conhece as regras da sua integração é você.

## O que não muda

* **Endereço base e autenticação**: continuam `https://api.salvy.com.br` e o cabeçalho `Authorization: Bearer <chave>`. A mesma chave de API funciona nas duas versões.
* **Webhooks**: não dependem da versão da API. Os webhooks que você já recebe continuam iguais, e a v3 traz eventos novos. Veja [Webhooks](/api-reference/v3/webhooks/introduction).

## Onde cada endpoint da v1 fica na v3

| v1 | v3 | O que muda |
| - | - | - |
| `GET /api/v1/assets` | `GET /api/v3/assets` | Resposta paginada |
| `POST /api/v1/assets` | `POST /api/v3/assets` | — |
| `GET /api/v1/assets/{id}` | `GET /api/v3/assets/{id}` | — |
| `POST /api/v1/assets/{id}` | `PATCH /api/v3/assets/{id}` | O método passa a ser `PATCH`; os campos são os mesmos |
| `POST /api/v1/assets/{id}/archive` | `POST /api/v3/assets/{id}/archive` | — |
| `POST /api/v1/assets/{id}/timeline-notes` | `POST /api/v3/assets/{id}/timeline-notes` | — |
| `GET /api/v1/employees` | `GET /api/v3/employees` | Resposta paginada |
| `POST /api/v1/employees/sync` | `POST /api/v3/employees/batch-sync` | Recebe uma lista e responde com uma tarefa; veja [Sincronização de colaboradores](#sincronização-de-colaboradores) |
| `GET /api/v1/virtual-phone-accounts` | `GET /api/v3/phone-accounts` | Lista todos os tipos de linha; filtre por `productType` |
| `POST /api/v1/virtual-phone-accounts` | `POST /api/v3/phone-accounts/mobile-did` | Campos renomeados; sem redirecionamento |
| `DELETE /api/v1/virtual-phone-accounts/{id}` | `POST /api/v3/phone-accounts/{id}/cancel` | O método muda e `reason` passa a ser obrigatório |
| `PATCH /api/v1/virtual-phone-accounts/{id}/redirect` | sem equivalente | Veja [Redirecionamento de chamadas](#redirecionamento-de-chamadas) |
| `GET /api/v1/virtual-phone-accounts/area-codes` | `GET /api/v3/area-codes?productType=mobile-did` | `productType` é obrigatório |

## Mudanças de contrato

### Listagens paginadas

Na v1, as listagens devolvem todos os registros de uma vez, numa chave com o nome do recurso (`assets`, `employees`). Na v3, toda listagem devolve `data` e `pagination`:

```json theme={null}
{
  "data": [{ "id": "0198c2f1-3815-45b7-9e60-8e137cad845c" }],
  "pagination": { "page": 1, "pageSize": 50, "totalCount": 132, "totalPages": 3 }
}
```

* `page` começa em 1; `pageSize` tem padrão 50 e máximo 200.
* Para ler tudo, avance `page` até chegar em `totalPages`.
* As listagens da v3 também aceitam filtros e ordenação (`sortBy`, `sortOrder`). Consulte a página de cada endpoint.

### Formato dos erros

Na v1, os detalhes do erro vêm dentro de `publicDetails`. Na v3, eles vêm na raiz da resposta:

```json theme={null}
// v1
{ "code": "resource-not-found", "message": "…", "publicDetails": { } }

// v3
{ "code": "resource-not-found", "message": "…" }
```

Nos erros de validação (`422`), a v3 lista os campos inválidos em `details`:

```json theme={null}
{
  "code": "input-validation-error",
  "message": "…",
  "details": [{ "key": "areaCode", "message": "…" }]
}
```

Se a sua integração decide o que fazer a partir de `code`, nada muda. Se ela lê `publicDetails`, passe a ler os campos na raiz.

## Números virtuais

Na v3, números virtuais são linhas como as outras: ficam em `/phone-accounts`, ao lado das linhas móveis, e são identificados por `productType`.

### Criação

`POST /api/v3/phone-accounts/mobile-did` substitui `POST /api/v1/virtual-phone-accounts`:

| v1 | v3 |
| - | - |
| `identifier` | `name` |
| `costCenter` | `costCenterId` |
| `areaCode` | `areaCode` |
| `employeeId` | `employeeId` |
| `redirectPhoneNumber`, `redirectExpiresAt` | não existem |
| — | `groupId`, `customFields` (novos) |

Na v1, `costCenter` era um texto livre. Na v3, o centro de custo é um recurso próprio: crie-o com `POST /api/v3/cost-centers` (ou encontre um existente em `GET /api/v3/cost-centers`) e envie o `id` dele em `costCenterId`.

A criação aceita o cabeçalho `idempotency-key`: se a requisição for repetida com a mesma chave, a v3 devolve o número criado na primeira vez, sem criar outro.

### DDDs disponíveis

Para mostrar ao usuário só os DDDs em que dá para criar um número, use `GET /api/v3/area-codes?productType=mobile-did`. Cada DDD vem com `available`, que indica se há número disponível nele no momento; para listar só os disponíveis, envie `available=true`.

A disponibilidade muda ao longo do tempo, então consulte a lista perto do momento da compra. Na criação do número:

* se o DDD não existir, a resposta é `422` com o código `phone-account-area-code-invalid`;
* se não houver número disponível no momento, a resposta é `409` com o código `phone-account-area-code-out-of-stock`, o mesmo das linhas com chip (no v2, era `did-area-code-out-of-stock`). A indisponibilidade é temporária; tente novamente mais tarde.

### Redirecionamento de chamadas

O redirecionamento de chamadas não está disponível na v3. Números criados na v3 não têm redirecionamento, e `PATCH /api/v1/virtual-phone-accounts/{id}/redirect` não tem equivalente.

### SMS recebidos

Para receber os SMS de um número em tempo real, use o webhook [SMS recebido](/api-reference/v3/webhooks/sms-received). Para consultar os já recebidos, use `GET /api/v3/phone-accounts/{id}/sms-messages`.

### Cancelamento

`POST /api/v3/phone-accounts/{id}/cancel` substitui `DELETE /api/v1/virtual-phone-accounts/{id}`. Na v3, `reason` é obrigatório. O cancelamento também pode ser agendado para o fim do ciclo de faturamento com `type: "scheduled"`; veja [Cancelar linha](/api-reference/v3/phone-accounts/cancel).

## Sincronização de colaboradores

Na v3, a sincronização é feita em lote, com [Sincronizar colaboradores em lote](/api-reference/v3/employees/batch-sync). Ela casa cada colaborador pelo `integrationId`, como o `sync` da v1: atualiza quem já foi sincronizado com aquele identificador e cria quem ainda não existe.

O que muda em relação à v1:

* **O corpo é uma lista.** Envie `{ "employees": [ ... ] }`, com até 1.000 colaboradores por requisição, cada um com os mesmos campos de antes. O corpo da requisição é limitado a 1 MB; se a sua base passar disso, divida-a em mais de uma requisição.
* **A resposta é uma tarefa, não o colaborador.** A requisição responde `202` com um `taskId`. Acompanhe o andamento em [Detalhar tarefa](/api-reference/v3/tasks/get) ou pelos webhooks de tarefa, e veja o resultado de cada colaborador em [Listar resultados da tarefa](/api-reference/v3/tasks/results). Saiba mais em [Introdução a tarefas](/api-reference/v3/tasks/introduction).
* **A validação é da lista inteira.** Se algum colaborador for inválido, a resposta é `422`, aponta a posição dele e nenhum é alterado. Um `integrationId` repetido na mesma lista também é recusado.
* **A chave precisa do escopo `task:read`**, além de `employee:sync`, para ler o resultado da tarefa.

Para criar ou alterar um colaborador pontualmente, com a resposta na hora, use `POST /api/v3/employees` e `PATCH /api/v3/employees/{id}`.

## Checklist de migração

**1. Troque os caminhos**

Atualize cada chamada conforme a tabela acima, incluindo os métodos que mudaram.

**2. Adapte as listagens**

Passe a ler `data` e a paginar com `page` e `pageSize`.

**3. Adapte o tratamento de erros**

Se você lê `publicDetails`, leia os campos na raiz da resposta.

**4. Revise os números virtuais**

Renomeie os campos da criação, remova o redirecionamento e envie `reason` no cancelamento.

**5. Valide no sandbox**

Rode a integração com uma chave `salvy_test_` antes de publicar em produção.


# Criar grupo de linhas
Source: https://docs.salvy.com.br/api-reference/v3/phone-account-groups/create

api-reference/v3/openapi.json POST /api/v3/phone-account-groups
Cria um grupo de linhas — o mesmo efeito de cadastrá-lo pelo painel. Responde 201 com o grupo criado. Quando a empresa já tem um grupo com o mesmo nome, nada é criado nem alterado: responde 200 com o grupo existente, com a cor que ele já tinha.

**Escopo necessário:** `phone-account-group:create`

# Remover grupo de linhas
Source: https://docs.salvy.com.br/api-reference/v3/phone-account-groups/delete

api-reference/v3/openapi.json DELETE /api/v3/phone-account-groups/{id}
Exclui um grupo de linhas. As linhas que estavam no grupo continuam ativas e ficam sem grupo.

**Escopo necessário:** `phone-account-group:delete`

# Detalhar grupo de linhas
Source: https://docs.salvy.com.br/api-reference/v3/phone-account-groups/get

api-reference/v3/openapi.json GET /api/v3/phone-account-groups/{id}
Busca um grupo de linhas da empresa pelo ID.

**Escopo necessário:** `phone-account-group:read`

# Listar grupos de linhas
Source: https://docs.salvy.com.br/api-reference/v3/phone-account-groups/list

api-reference/v3/openapi.json GET /api/v3/phone-account-groups
Lista os grupos de linhas da empresa, ordenados por nome (A→Z), com desempate por ID crescente.

**Escopo necessário:** `phone-account-group:read`

# Atualizar grupo de linhas
Source: https://docs.salvy.com.br/api-reference/v3/phone-account-groups/update

api-reference/v3/openapi.json PATCH /api/v3/phone-account-groups/{id}
Atualiza um grupo de linhas por ID. Somente os campos enviados no corpo são alterados; campos omitidos permanecem inalterados.

**Escopo necessário:** `phone-account-group:update`

# Ativar linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/activate

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/activate
Re-tenta a ativação de uma linha existente (móvel). Não cria nova linha nem consome estoque. Re-tentar em uma linha já ativa ou em ativação não tem efeito e retorna o estado atual — a resposta pode continuar como "pending" (ex.: eSIM aguardando instalação).

**Escopo necessário:** `phone-account:create-mobile`

# Consultar saldo da linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/balance

api-reference/v3/openapi.json GET /api/v3/phone-accounts/{id}/balance
Consulta o saldo de dados de uma linha telefônica da empresa pelo ID. Quando a última medição já está antiga, o saldo é atualizado antes da resposta — por isso esta chamada pode demorar mais que ler o campo `dataBalanceGB` da linha, que sempre devolve a última medição disponível. Retorna 422 se a linha não estiver ativa.

**Escopo necessário:** `phone-account:read`

# Alterar centro de custo em lote
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/batch-update-cost-center

api-reference/v3/openapi.json POST /api/v3/phone-accounts/batch-update-cost-center
Aplica um centro de custo a várias linhas de uma vez. A requisição é aceita por inteiro ou recusada por inteiro: se alguma linha ou o centro de custo não pertencer à sua empresa, nada é alterado. As linhas são atualizadas em segundo plano; a resposta traz o ID de uma tarefa para acompanhar o resultado em GET /tasks/{id}.

**Escopo necessário:** `phone-account:update`

# Bloquear linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/block

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/block
Bloqueia uma linha telefônica pelo ID. Bloquear uma linha já bloqueada não tem efeito e retorna o estado atual.

**Escopo necessário:** `phone-account:block`

# Cancelar linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/cancel

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/cancel
Cancela uma linha telefônica pelo ID. Com `type` "immediate" (padrão), a linha é cancelada na hora, junto com qualquer portabilidade pendente para ela. Com `type` "scheduled", a linha continua funcionando até o fim do ciclo de faturamento atual e é cancelada nessa data, informada em `cancellationScheduledFor`; o agendamento pode ser desfeito em `POST /phone-accounts/{id}/unschedule-cancellation`. Nos dois casos, o mês corrente é cobrado. Agendar o cancelamento de uma linha que já o tem agendado não tem efeito, e só uma linha ativa pode ter o cancelamento agendado. Uma linha com portabilidade de saída em andamento não pode ser cancelada, nem na hora nem com agendamento, para que o número não se perca. Cancelar uma linha já cancelada não tem efeito e retorna o estado atual.

**Escopo necessário:** `phone-account:cancel`

# Criar linha móvel
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/create-mobile

api-reference/v3/openapi.json POST /api/v3/phone-accounts/mobile
Cria uma nova linha móvel. A linha nasce pendente de ativação, com a cobrança iniciando após a ativação. Disponível apenas para empresas liberadas para criar linhas móveis pela API: peça a liberação ao seu contato na Salvy. Depois de liberada, a empresa passa a ver o escopo `phone-account:create-mobile` ao criar ou editar uma chave.

**Escopo necessário:** `phone-account:create-mobile`

# Criar linha móvel (DID)
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/create-mobile-did

api-reference/v3/openapi.json POST /api/v3/phone-accounts/mobile-did
Cria uma nova linha móvel (mobile-did). A linha já nasce disponível para uso, com a cobrança começando apenas quando o número for validado em algum app (ex.: WhatsApp). No ambiente sandbox, aceita apenas o DDD 41 e sempre retorna o mesmo número de demonstração, `+5541963475701`; outro DDD retorna `phone-account-area-code-out-of-stock`.

**Escopo necessário:** `phone-account:create-mobile-did`

# Obter eSIM da linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/esim

api-reference/v3/openapi.json GET /api/v3/phone-accounts/{id}/esim
Consulta os dados de ativação do eSIM de uma linha móvel ou global da empresa pelo ID. Enquanto o eSIM ainda está sendo preparado, `status` retorna "provisioning" e os demais campos ficam nulos — repita a consulta em instantes. Quando o código está pronto, `status` é "ready" e os campos de ativação são preenchidos. Se o eSIM já foi instalado em um aparelho, `status` é "installed". Retorna 422 para linhas que não utilizam eSIM, como linhas com chip físico ou linhas de número virtual.

**Escopo necessário:** `phone-account:read-esim`

# Detalhar linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/get

api-reference/v3/openapi.json GET /api/v3/phone-accounts/{id}
Busca uma linha telefônica da empresa pelo ID.

**Escopo necessário:** `phone-account:read`

# Listar linhas
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/list

api-reference/v3/openapi.json GET /api/v3/phone-accounts
Lista as linhas telefônicas da empresa, ordenadas por data de criação decrescente (`createdAt`), com desempate por ID crescente.

**Escopo necessário:** `phone-account:read`

# Simular recebimento de SMS
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/simulate-sms

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/sms
Simula o recebimento de um SMS em um número virtual móvel (`mobile-did`). Disponível apenas no ambiente sandbox.

**Escopo necessário:** `phone-account:simulate-sms`

# Listar SMS da linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/sms-messages

api-reference/v3/openapi.json GET /api/v3/phone-accounts/{id}/sms-messages
Lista as mensagens SMS recebidas por uma linha telefônica, ordenadas por data de recebimento decrescente (`receivedAt`), com paginação. Útil para reprocessar notificações de webhook perdidas. Mensagens SMS só existem para números virtuais móveis (`mobile-did`); linhas de outros tipos retornam uma lista vazia.

**Escopo necessário:** `phone-account:read-sms`

# Adicionar dados à linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/top-up-data

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/top-up-data
Adiciona dados à franquia de uma linha telefônica pelo ID. Disponível apenas para linhas móveis e globais.

**Escopo necessário:** `phone-account:top-up`

# Desbloquear linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/unblock

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/unblock
Desbloqueia uma linha telefônica pelo ID. Desbloquear uma linha que já está ativa não tem efeito e retorna o estado atual. Um bloqueio colocado pela Salvy — inadimplência, cancelamento da empresa ou bloqueio parcial — não é levantado por aqui, e uma linha cancelada não pode ser desbloqueada.

**Escopo necessário:** `phone-account:unblock`

# Desfazer cancelamento agendado
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/unschedule-cancellation

api-reference/v3/openapi.json POST /api/v3/phone-accounts/{id}/unschedule-cancellation
Desfaz o cancelamento agendado para a linha com `type` "scheduled" em `POST /phone-accounts/{id}/cancel`: a linha continua funcionando depois do fim do ciclo de faturamento e `cancellationScheduledFor` volta a ser nulo. Quando não há cancelamento agendado para desfazer, a chamada não tem efeito e retorna o estado atual. Uma linha bloqueada não pode ter o cancelamento agendado desfeito.

**Escopo necessário:** `phone-account:cancel`

# Atualizar linha
Source: https://docs.salvy.com.br/api-reference/v3/phone-accounts/update

api-reference/v3/openapi.json PATCH /api/v3/phone-accounts/{id}
Atualiza uma linha telefônica pelo ID. Somente os campos enviados no corpo da requisição são alterados; campos omitidos permanecem inalterados.

**Escopo necessário:** `phone-account:update`

# Detalhar plano
Source: https://docs.salvy.com.br/api-reference/v3/plans/get

api-reference/v3/openapi.json GET /api/v3/plans/{id}
Busca um plano pelo ID. Retorna 404 quando o plano não existe, não é do tipo `mobile`, ou não está disponível para a sua empresa.

**Escopo necessário:** `plan:read`

# Listar planos
Source: https://docs.salvy.com.br/api-reference/v3/plans/list

api-reference/v3/openapi.json GET /api/v3/plans
Lista os planos disponíveis para a sua empresa, restritos a linhas móveis (`productType: "mobile"`) nesta versão. Ordenados por nome (`name`) crescente, com desempate por ID crescente. Este endpoint não é paginado.

**Escopo necessário:** `plan:read`

# Limites de requisição
Source: https://docs.salvy.com.br/api-reference/v3/rate-limits

Quantas requisições a sua empresa pode fazer por minuto, como acompanhar o limite pelos cabeçalhos e como tratar o 429

Para manter a API estável para todos os clientes, a Salvy limita quantas requisições cada empresa pode fazer por minuto. A sua integração consegue acompanhar esse limite pelos cabeçalhos de cada resposta e se ajustar antes de ser bloqueada.

## Qual é o limite

| O que é contado | Limite padrão |
| - | - |
| Requisições por empresa | **300 por minuto** |

* O limite é **por empresa**, não por chave de API: todas as chaves da mesma empresa dividem a mesma janela. Criar mais chaves não aumenta o limite.
* Chaves de organização contam na janela da **organização**, separada da janela de cada empresa.
* A janela é fixa de um minuto: ela começa na primeira requisição e zera quando o minuto termina.

> [!TIP]
>
> Se a sua integração precisa de mais do que isso, fale com o seu contato na
> Salvy. O limite pode ser ajustado por empresa.

## Como acompanhar o limite

As respostas autenticadas trazem dois cabeçalhos:

| Cabeçalho | O que informa | Exemplo |
| - | - | - |
| `RateLimit-Limit` | Quantas requisições a janela permite | `300` |
| `RateLimit-Remaining` | Quantas ainda cabem na janela atual | `287` |

Quando `RateLimit-Remaining` chegar perto de zero, espace as próximas chamadas em vez de esperar pelo bloqueio.

Os cabeçalhos não aparecem em respostas `401` e `403`, porque a autenticação é avaliada antes. Trate a ausência de `RateLimit-Remaining` como "sem informação", não como limite esgotado.

## Quando o limite é atingido

A requisição que passa do limite recebe `429 Too Many Requests` com o código `too-many-attempts`. O cabeçalho `Retry-After` diz, em segundos, quanto falta para a janela zerar:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 18
RateLimit-Limit: 300
RateLimit-Remaining: 0
```

Nada é executado numa requisição recusada. É seguro repeti-la depois do tempo indicado, inclusive quando for uma criação ou alteração.

### Outro 429: a proteção de borda

Além do limite por empresa, a Salvy tem uma proteção de borda contra picos vindos de um mesmo IP. Ela responde `429` com o código `too-many-requests` e **sem** `Retry-After`. Se receber esse código, aguarde alguns segundos e tente de novo com espera crescente.

## Como tratar o 429

```js theme={null}
async function callSalvy(url, init, attempt = 0) {
  const response = await fetch(url, {
    ...init,
    headers: {
      ...init?.headers,
      Authorization: `Bearer ${process.env.SALVY_API_KEY}`,
    },
  });

  if (response.status !== 429 || attempt >= 5) {
    return response;
  }

  // Sem Retry-After (proteção de borda), espera crescente: 1s, 2s, 4s...
  const retryAfter = Number(response.headers.get('Retry-After'));
  const waitSeconds = retryAfter > 0 ? retryAfter : 2 ** attempt;

  await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));

  return callSalvy(url, init, attempt + 1);
}
```

> [!WARNING]
>
> Não repita a requisição imediatamente em laço. Enquanto a janela não zerar,
> toda nova tentativa volta com `429`.

## Boas práticas

* **Sincronizações em lote**: distribua as chamadas ao longo do tempo em vez de disparar tudo de uma vez.
* **Várias integrações na mesma empresa**: lembre que elas dividem o mesmo limite. Um job pesado pode esgotar a janela de outra integração.
* **Agentes de IA e scripts**: limite a concorrência. Um laço sem pausa atinge 300 requisições em poucos segundos.
* **Teste no sandbox**: chaves `salvy_test_` seguem o mesmo limite. Veja [Ambientes](/api-reference/v3/environments).

## Corpo da resposta 429

O corpo segue o formato de erro da v3. O tempo de espera também vem no corpo, para clientes que não leem cabeçalhos:

```json theme={null}
{
  "code": "too-many-attempts",
  "message": "Muitas requisições em pouco tempo. Aguarde um instante e tente de novo.",
  "retryAfterSeconds": 18
}
```


# Admissão → colaborador + linha
Source: https://docs.salvy.com.br/api-reference/v3/recipes/admission-create-line

Quando o RH admite alguém, cadastre o colaborador na Salvy e peça uma linha para ele no mesmo centro de custo.

Toda admissão gera o mesmo trabalho manual: cadastrar a pessoa no painel, escolher o plano, pedir a linha e lembrar de colocar tudo no centro de custo certo. Quando isso depende de alguém, a linha atrasa ou vai para o centro de custo errado e aparece no rateio do mês seguinte.

Nesta receita, o próprio evento de admissão do seu sistema de RH dispara o cadastro: sua integração cria o colaborador na Salvy e pede uma linha com chip físico vinculada a ele, no mesmo centro de custo.

**Para quem é:** times de RH, TI ou de gestão de telecom que querem que a pessoa chegue no primeiro dia com a linha já pedida.

## O que você precisa

* Uma **chave de API de empresa**. Chaves de organização são somente leitura e não criam colaboradores nem linhas. Veja [Chaves de API](/api-reference/v3/api-keys).
* A **criação de linhas móveis pela API liberada** para a sua empresa. Ela não vem ligada por padrão: peça a liberação ao seu contato na Salvy.
* A chave com os escopos `cost-center:read`, `plan:read`, `employee:create` e `phone-account:create-mobile`. Este último só aparece para escolher depois que a criação de linhas móveis é liberada.
* Os dados da admissão vindos do seu sistema de RH: nome, e-mail profissional ou CPF e, se quiser, cargo, área e data de admissão.
* O **nome do plano** da linha e, se usar, o **centro de custo** (nome ou código).
* O **DDD** da linha e o **ICCID** do chip físico que a pessoa vai usar (o ICCID completo ou os últimos 7 a 10 dígitos).

| Etapa | Endpoint |
| - | - |
| 1. Encontrar o centro de custo | [`GET /api/v3/cost-centers`](/api-reference/v3/cost-centers/list) |
| 2. Encontrar o plano | [`GET /api/v3/plans`](/api-reference/v3/plans/list) |
| 3. Cadastrar o colaborador | [`POST /api/v3/employees`](/api-reference/v3/employees/create) |
| 4. Pedir a linha | [`POST /api/v3/phone-accounts/mobile`](/api-reference/v3/phone-accounts/create-mobile) |

## Passo a passo

**1. Encontre o centro de custo**

Liste os centros de custo ativos e procure pelo nome ou pelo código que o seu RH usa.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/cost-centers" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "status=active" \
  --data-urlencode "pageSize=200"
```

```json theme={null}
{
  "data": [
    { "id": "0198c2f1-3815-45b7-9e60-8e137cad845c", "code": "COMERCIAL", "name": "Comercial", "status": "active" }
  ],
  "pagination": { "page": 1, "pageSize": 200, "totalCount": 1, "totalPages": 1 }
}
```

Guarde o `id`. Se o centro de custo informado pelo RH não existir, pare aqui: seguir sem ele deixa o colaborador e a linha fora do rateio.

**2. Encontre o plano**

Liste os planos disponíveis para a sua empresa. Este endpoint não é paginado.

```bash theme={null}
curl "https://api.salvy.com.br/api/v3/plans" \
  -H "Authorization: Bearer $SALVY_API_KEY"
```

```json theme={null}
{
  "data": [
    { "id": "0197aa3e-3815-45b7-9e60-8e137cad845c", "name": "Plano 20GB", "productType": "mobile", "availableDataAmountGB": 20, "priceCents": 4500 }
  ]
}
```

Escolha o plano pelo nome exato e guarde o `id`. O plano define o valor mensal da linha (`priceCents`), então não escolha um plano automaticamente se o nome não bater.

**3. Cadastre o colaborador**

Crie o colaborador com status `active` e o centro de custo da etapa 1. Envie uma chave de idempotência montada a partir do evento de admissão, para que um reenvio do RH não crie o colaborador duas vezes.

```bash theme={null}
curl -X POST "https://api.salvy.com.br/api/v3/employees" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: admissao-joaosilva@empresa.com.br-2026-10-01-employee" \
  -d '{
    "fullName": "João da Silva",
    "status": "active",
    "workEmail": "joaosilva@empresa.com.br",
    "cpf": "198.099.750-07",
    "position": "Analista de Vendas",
    "area": "Comercial",
    "admittedAt": "2026-10-01",
    "costCenterId": "0198c2f1-3815-45b7-9e60-8e137cad845c"
  }'
```

A resposta (`201`) traz o colaborador criado. Guarde o `id`.

**4. Peça a linha**

Peça uma linha móvel com chip físico, vinculada ao colaborador e no mesmo centro de custo. Neste endpoint a chave de idempotência é obrigatória.

```bash theme={null}
curl -X POST "https://api.salvy.com.br/api/v3/phone-accounts/mobile" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: admissao-joaosilva@empresa.com.br-2026-10-01-phone-account" \
  -d '{
    "simType": "physical",
    "iccid": "1234567890",
    "subscriptionPlanId": "0197aa3e-3815-45b7-9e60-8e137cad845c",
    "areaCode": 11,
    "employeeId": "123e4567-e89b-12d3-a456-426614174000",
    "costCenterId": "0198c2f1-3815-45b7-9e60-8e137cad845c",
    "name": "Linha João da Silva"
  }'
```

A resposta (`202`) traz a linha com status `pending`. A linha nasce pendente de ativação, e a cobrança começa depois da ativação. Para saber quando ela pode ser usada, assine o webhook [`phone-account.activated`](/api-reference/v3/webhooks/phone-account-activated).

## Sem código: workflow do n8n

Se você usa o [n8n](https://n8n.io), baixe o workflow pronto com as quatro etapas. Ele tem dois gatilhos: um manual, para testar, e um webhook, para o seu sistema de RH chamar a cada admissão.

Baixar workflow do n8n

`admission-create-line.json`: importe no n8n e siga as notas dentro do workflow.

1. No n8n, crie um workflow e importe o arquivo (menu **⋯ > Import from File**, ou cole o conteúdo do arquivo no editor).
2. Crie uma credencial **Bearer Auth** com a sua chave de API e selecione-a nos quatro nós HTTP.
3. Preencha o nó **Dados de teste** e execute. O workflow começa em modo simulação (`dryRun = true` no nó **Configuração**): ele consulta centros de custo e planos e mostra o colaborador e a linha que seriam criados, com o valor do plano, sem criar nada.
4. Quando o resultado estiver certo, troque `dryRun` para `false`. Para rodar automaticamente, ative o workflow e faça o seu sistema de RH chamar a URL do nó **Webhook do RH** com os dados da admissão. O formato do corpo está nas notas do workflow.

> [!WARNING]
>
> A URL de um webhook do n8n é pública. Antes de ativar o workflow, configure
> uma autenticação no nó **Webhook do RH** (por exemplo, Header Auth).

## Como implementar

* **Gatilho:** um webhook do sistema de RH a cada admissão, uma rotina diária que busca as admissões do dia ou um botão no seu sistema interno.
* **Modo simulação primeiro.** Comece com uma versão que só consulta e mostra o colaborador e a linha que seriam criados, com o plano e o valor, sem fazer as chamadas de escrita. Confira o resultado e só depois ative as escritas.
* **Chaves de idempotência:** monte as chaves a partir do evento de admissão (e-mail ou CPF e data de admissão), nunca de algo que muda a cada execução.

## Cuidados

> [accordion] Teste no sandbox antes de usar em produção
>
> Em produção, a linha é criada de verdade e passa a ser cobrada depois de ativada. Valide o fluxo com uma chave de sandbox (`salvy_test_`) antes de trocar para a chave de produção. Veja [Ambientes](/api-reference/v3/environments).

> [accordion] Reenvios do RH não duplicam nada
>
> As duas criações usam uma chave de idempotência montada com o e-mail (ou o CPF) e a data de admissão. Se o RH reenviar a mesma admissão, a API devolve o colaborador e a linha já criados em vez de criar outros.
>
> * **Por quanto tempo:** a chave do colaborador vale por 24 horas; a da linha não expira. Depois de 24 horas, quem impede um colaborador duplicado é o e-mail profissional, que é único (veja abaixo).
> * **Depois de um erro:** a API só guarda as respostas de sucesso. Se uma chamada falhar, corrija o problema e reenvie com a mesma chave: a criação é feita de novo.
> * **Mesmos dados:** com a mesma chave e dados diferentes, a API recusa o pedido se a primeira chamada já tiver dado certo. Envie sempre `admittedAt`; sem ela, a chave muda de um dia para o outro.

> [accordion] E-mail profissional já cadastrado
>
> Se já existir um colaborador com o mesmo e-mail profissional, `POST /employees` retorna `409` com o código `employee-with-email-already-exists` e a linha não é pedida. Em uma readmissão, por exemplo, reative o colaborador existente com [`PATCH /api/v3/employees/{id}`](/api-reference/v3/employees/update) e peça a linha para ele.

> [accordion] Se o pedido da linha falhar
>
> Quando `POST /phone-accounts/mobile` retorna um erro, o colaborador já foi cadastrado. Corrija a causa e reenvie o mesmo evento: dentro de 24 horas, `POST /employees` devolve o colaborador já criado, e a linha é pedida de novo com a mesma chave.
>
> Uma resposta de sucesso significa que a linha foi criada como `pending`, não que já está ativa. A ativação acontece depois; assine o webhook [`phone-account.activated`](/api-reference/v3/webhooks/phone-account-activated) para saber quando a linha pode ser usada.

## Variações

* **eSIM em vez de chip físico.** Envie `simType: "esim"` sem `iccid`. Assine [`phone-account.esim-ready`](/api-reference/v3/webhooks/phone-account-esim-ready) para saber quando o código de ativação está pronto e busque-o em [Dados do eSIM](/api-reference/v3/phone-accounts/esim) para enviar à pessoa.
* **Avisar o gestor.** Ao final, envie para o Slack, Teams ou e-mail do gestor um resumo com o nome do colaborador, o plano e o status da linha.
* **Desligamento.** Para o caminho inverso, quando a pessoa sai da empresa, veja [Desligamento → bloqueio de linhas](/api-reference/v3/recipes/offboarding-block-lines).


# Rateio de telecom por centro de custo
Source: https://docs.salvy.com.br/api-reference/v3/recipes/cost-center-allocation

Todo mês, gere o rateio da fatura de telecom por centro de custo, pronto para o lançamento contábil.

Todo mês o time financeiro precisa distribuir o custo de telecom entre os centros de custo da empresa. Fazer isso copiando valores do painel é lento e quebra sempre que a tela muda.

Nesta receita, sua integração busca as faturas de telecom do mês, lê o custo de cada linha já com o centro de custo e gera dois arquivos: o **rateio por centro de custo**, pronto para o lançamento contábil, e o **detalhamento por linha**, para conferência.

**Para quem é:** times de financeiro, controladoria e contabilidade que fazem o rateio mensal de telecom.

## O que você precisa

* Uma **chave de API**. Como a receita só faz leituras, ela funciona com uma chave de empresa ou com uma **chave de organização**, que traz as faturas de todas as empresas da organização de uma vez. Veja [Chaves de API](/api-reference/v3/api-keys).
* Os centros de custo cadastrados na Salvy, de preferência com **código**, e as linhas associadas a eles.

| Etapa | Endpoint |
| - | - |
| 1. Buscar as faturas de telecom do mês | [`GET /api/v3/invoices`](/api-reference/v3/invoices/list) |
| 2. Ler o custo de cada linha da fatura | [`GET /api/v3/invoices/{id}/phone-accounts`](/api-reference/v3/invoices/phone-accounts) |
| 3. Agrupar por centro de custo e gerar os arquivos | na sua integração |

## Passo a passo

**1. Busque as faturas de telecom do mês**

Filtre as faturas pelo mês de referência (`AAAA-MM`) e pelo produto `telecom`.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/invoices" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "monthYear=2026-08" \
  --data-urlencode "product=telecom" \
  --data-urlencode "pageSize=200"
```

```json theme={null}
{
  "data": [
    {
      "id": "0198c2f1-3815-45b7-9e60-8e137cad845c",
      "companyId": "0198c2f1-3815-45b7-9e60-8e137cad8400",
      "status": "paid",
      "amountCents": 174108,
      "referenceMonth": "2026-08"
    }
  ],
  "pagination": { "page": 1, "pageSize": 200, "totalCount": 1, "totalPages": 1 }
}
```

Ignore as faturas com status `voided` (canceladas): elas não são cobradas e não devem entrar no rateio. Com uma chave de organização, a lista traz as faturas de todas as empresas, e o `companyId` indica de qual empresa é cada uma.

**2. Leia o custo de cada linha da fatura**

Para cada fatura, liste o detalhamento por linha. Cada item traz o custo da linha e o centro de custo e o colaborador dela.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/invoices/0198c2f1-3815-45b7-9e60-8e137cad845c/phone-accounts" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "pageSize=200" \
  --data-urlencode "page=1"
```

```json theme={null}
{
  "data": [
    {
      "phoneNumber": "+5541999887766",
      "name": "Comercial - Diretoria",
      "costCenter": { "id": "01a034c4-bd69-766f-a242-967a75248d94", "name": "Comercial", "code": "COMERCIAL" },
      "employee": { "id": "019cfd57-dbe7-726f-b071-b013de4818e5", "name": "Maria de Souza" },
      "subscriptionAmountCents": 5990,
      "meteredAmountCents": 4990,
      "oneTimeAmountCents": 0,
      "totalAmountCents": 10980
    }
  ],
  "pagination": { "page": 1, "pageSize": 200, "totalCount": 38, "totalPages": 1 }
}
```

Os valores, o centro de custo e o colaborador são os do **momento em que a fatura fechou**. Se uma linha mudou de centro de custo depois, o rateio continua usando o centro de custo em que ela estava no fechamento. Se `pagination.totalPages` for maior que 1, busque as páginas seguintes com o parâmetro `page`.

**3. Agrupe por centro de custo**

Some o `totalAmountCents` das linhas por centro de custo. Use o `code` do centro de custo como chave do lançamento contábil. Quando o centro de custo não tem código, use o nome, e agrupe as linhas sem centro de custo em um grupo à parte, como `SEM_CENTRO_DE_CUSTO`.

Com uma chave de organização, agrupe também pela empresa (`companyId` da fatura): duas empresas podem ter centros de custo com o mesmo código.

Os valores vêm em centavos. Divida por 100 só na hora de gerar o arquivo, para não acumular erros de arredondamento na soma.

## Sem código: workflow do n8n

Se você usa o [n8n](https://n8n.io), baixe o workflow pronto. Ele tem dois gatilhos: um manual, para testar com qualquer mês, e uma agenda mensal, que gera o rateio do mês anterior automaticamente.

Baixar workflow do n8n

`cost-center-allocation.json`: importe no n8n e siga as notas dentro do workflow.

1. No n8n, crie um workflow e importe o arquivo (menu **⋯ > Import from File**, ou cole o conteúdo do arquivo no editor).
2. Crie uma credencial **Bearer Auth** com a sua chave de API e selecione-a nos dois nós HTTP.
3. No nó **Dados de teste**, informe o mês em `mesReferencia` (`AAAA-MM`) ou deixe vazio para usar o mês anterior, e execute. O workflow gera os dois CSVs.
4. Para rodar todo mês, ative o workflow. As faturas são geradas no dia 1º de cada mês, e o nó **Agenda mensal** roda no dia 5, às 8h, com o mês anterior. Os dias entre a geração e a agenda são uma margem para a fatura já estar disponível.

## Como implementar

* **Gatilho:** uma rotina mensal. As faturas são geradas no dia 1º de cada mês; rodar no dia 5 dá margem para a fatura já estar disponível.
* **Formato dos arquivos:** gere os valores a partir dos centavos da API e use o formato que o seu ERP espera (separador de colunas e separador decimal).
* **Somente leitura:** a receita não altera nada na Salvy, então pode ser executada quantas vezes for preciso.

## Cuidados

> [accordion] Os valores são os do fechamento da fatura
>
> O detalhamento por linha guarda o custo, o centro de custo, o colaborador e o número de cada linha no momento em que a fatura fechou. Mudanças feitas depois (trocar o centro de custo de uma linha, por exemplo) só aparecem nas próximas faturas. Isso garante que o rateio de um mês já fechado não muda se você gerar o arquivo de novo.

> [accordion] Faturas antigas podem vir sem detalhamento
>
> Faturas de telecom fechadas antes de a Salvy registrar o detalhamento por linha retornam a lista vazia em `GET /invoices/{id}/phone-accounts`. Faturas de outros produtos (`asset-management`, `saas-management`) também não têm detalhamento por linha: por isso a receita filtra por `product=telecom`.

> [accordion] Rodar de novo é seguro
>
> A receita só faz leituras e não altera nada na Salvy. Você pode gerar o rateio de qualquer mês quantas vezes quiser, e o resultado de um mês fechado é sempre o mesmo.

> [accordion] Linhas sem centro de custo
>
> As linhas que estavam sem centro de custo no fechamento entram no grupo `SEM_CENTRO_DE_CUSTO`. Para reduzir esse grupo nos próximos meses, associe cada linha a um centro de custo, pelo painel ou por [`PATCH /api/v3/phone-accounts/{id}`](/api-reference/v3/phone-accounts/update).

## Variações

* **Vários meses de uma vez.** Troque `monthYear` por `fromMonthYear` e `toMonthYear` em [Listar faturas](/api-reference/v3/invoices/list) para gerar o rateio de um trimestre ou de um ano.
* **Enviar direto para o ERP ou para uma planilha.** Em vez de gravar arquivos, envie as linhas do rateio para o seu ERP, para o Google Sheets ou por e-mail para a controladoria.
* **Detalhar as cobranças pontuais.** Cada linha traz `oneTimeCharges`, com a categoria de cada cobrança pontual (como pacote de dados ou troca de chip), para quem precisa separar esses valores no lançamento.


# Consumo de dados: maiores e menores
Source: https://docs.salvy.com.br/api-reference/v3/recipes/data-usage-ranking

Descubra quais linhas mais e menos consomem dados em relação à franquia do plano, para ajustar planos e pacotes.

Sem acompanhamento, é difícil saber se os planos contratados combinam com o uso real. Algumas linhas estouram a franquia todo mês e outras mal usam os dados pelos quais a empresa paga.

Nesta receita, sua integração lista as linhas ativas, consulta o saldo de dados atualizado de cada uma e monta duas listas: as linhas que mais consumiram da franquia e as que menos consumiram. Tudo é somente leitura: nenhuma linha é alterada.

**Para quem é:** times de TI, compras ou gestão de telecom que revisam planos periodicamente e querem uma lista pronta toda semana em vez de conferir linha a linha no painel.

## O que você precisa

* Uma **chave de API de empresa** ou de **organização**. Como a receita só faz leituras, a chave de organização também serve e traz as linhas de todas as empresas da organização de uma vez. Veja [Chaves de API](/api-reference/v3/api-keys).

| Etapa | Endpoint |
| - | - |
| 1. Listar as linhas ativas | [`GET /api/v3/phone-accounts`](/api-reference/v3/phone-accounts/list) |
| 2. Consultar o saldo de cada linha | [`GET /api/v3/phone-accounts/{id}/balance`](/api-reference/v3/phone-accounts/balance) |
| 3. Calcular o consumo e montar o ranking | Na sua integração |

## Passo a passo

**1. Liste as linhas ativas**

Filtre as linhas pelo status `active`. Cada linha já vem com o plano, incluindo a franquia de dados em `plan.availableDataAmountGB`, o colaborador e o centro de custo.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/phone-accounts" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "status=active" \
  --data-urlencode "pageSize=200"
```

```json theme={null}
{
  "data": [
    {
      "id": "0198c2f1-3815-45b7-9e60-8e137cad845c",
      "phoneNumber": "+5541999887766",
      "name": "Maria - Vendas",
      "employee": { "id": "0197aa3e-3815-45b7-9e60-8e137cad845c", "fullName": "Maria de Souza" },
      "costCenter": { "id": "0198c2f1-3815-45b7-9e60-8e137cad845d", "name": "Comercial" },
      "plan": { "id": "0198c2f1-3815-45b7-9e60-8e137cad845e", "name": "Plano 20GB", "availableDataAmountGB": 20 }
    }
  ],
  "pagination": { "page": 1, "pageSize": 200, "totalCount": 1, "totalPages": 1 }
}
```

Se `pagination.totalPages` for maior que 1, busque as páginas seguintes com o parâmetro `page`. Descarte as linhas cujo plano não tem franquia de dados (`availableDataAmountGB` igual a 0, como planos só de WhatsApp): não dá para medir consumo contra uma franquia que não existe.

**2. Consulte o saldo atualizado de cada linha**

Para cada linha com franquia, consulte o saldo de dados.

```bash theme={null}
curl "https://api.salvy.com.br/api/v3/phone-accounts/0198c2f1-3815-45b7-9e60-8e137cad845c/balance" \
  -H "Authorization: Bearer $SALVY_API_KEY"
```

```json theme={null}
{ "dataBalanceGB": 4.5, "dataBalanceUpdatedAt": "2026-09-30T11:00:00Z" }
```

Quando a última medição já está antiga, a Salvy mede o saldo de novo antes de responder. Por isso esta chamada pode demorar mais que ler o campo `dataBalanceGB` da listagem, que traz a última medição disponível. Faça as consultas em lotes pequenos, e não todas de uma vez.

Se a consulta falhar para uma linha, por exemplo com `422` porque ela deixou de estar ativa, deixe essa linha fora do ranking. O mesmo vale para `dataBalanceGB` nulo, que indica que a linha não tem dado mensurável. Não estime um saldo.

**3. Calcule o consumo e monte o ranking**

O consumo de cada linha é a franquia do plano menos o saldo atual, nunca abaixo de zero:

```
usadoGB = max(0, franquiaGB - saldoGB)
usoPct  = usadoGB / franquiaGB × 100
```

Ordene pelo percentual de uso, do maior para o menor, e separe as primeiras e as últimas linhas. Se houver menos linhas que o dobro do tamanho das listas, não repita na lista de menor consumo uma linha que já está na de maior consumo.

## Sem código: workflow do n8n

Se você usa o [n8n](https://n8n.io), baixe o workflow pronto. Ele tem dois gatilhos: um manual, para testar, e uma agenda semanal, que roda toda segunda-feira às 8h.

Baixar workflow do n8n

`data-usage-ranking.json`: importe no n8n e siga as notas dentro do workflow.

1. No n8n, crie um workflow e importe o arquivo (menu **⋯ > Import from File**, ou cole o conteúdo do arquivo no editor).
2. Crie uma credencial **Bearer Auth** com a sua chave de API e selecione-a nos dois nós HTTP.
3. Execute o workflow. Ele gera um resumo para o gestor e um CSV com as linhas de maior e de menor consumo. Para mudar o tamanho das listas, ajuste `topN` (padrão 5) no nó **Configuração**.
4. Para receber o ranking toda semana, ative o workflow e conecte depois do nó **Resumo para o gestor** um nó de Slack, Teams ou e-mail.

## Como implementar

* **Gatilho:** uma rotina semanal, por exemplo toda segunda de manhã, com o resultado enviado ao gestor por Slack, Teams ou e-mail.
* **Consultas de saldo em lotes:** a consulta de saldo pode demorar; faça poucas chamadas em paralelo e ignore as linhas cujo saldo não puder ser lido.
* **Somente leitura:** a receita não altera nada na Salvy, então pode ser executada direto com uma chave de produção.

## Cuidados

> [accordion] Pacotes adicionais fazem o consumo parecer menor
>
> O consumo é calculado a partir do saldo. Quando uma linha recebe um pacote de dados adicional, o saldo aumenta, e o consumo calculado fica menor do que o real. Uma linha que já precisou de pacote pode aparecer no meio ou até na lista de menor consumo.

> [accordion] A consulta de saldo pode demorar
>
> Quando a medição está antiga, a Salvy mede o saldo de novo antes de responder. Com centenas de linhas, a execução leva alguns minutos. Mantenha os lotes pequenos e agende o ranking para um horário em que ninguém esteja esperando o resultado.

> [accordion] Linhas que ficam de fora
>
> Ficam fora do ranking as linhas sem franquia de dados no plano, as que deixaram de estar ativas entre a listagem e a consulta de saldo (a consulta retorna `422`) e qualquer linha cujo saldo não pôde ser lido. Nenhum saldo é estimado.

> [accordion] As ações sugeridas geram cobrança
>
> O ranking não altera nada, mas as ações que ele sugere, sim. Um pacote adicional ([Adicionar dados](/api-reference/v3/phone-accounts/top-up-data)) ou uma troca de plano geram cobrança. Confira com o gestor antes de automatizar qualquer uma delas.

## Variações

* **Por centro de custo.** Agrupe as linhas pelo `costCenter` da listagem e monte um ranking por área, para cada gestor ver só a sua equipe.
* **Alerta de estouro.** Em vez de um ranking semanal, rode todo dia e avise quando uma linha passar de 90% da franquia antes do fim do ciclo.
* **Linhas sem uso.** Separe as linhas com consumo próximo de zero por várias semanas seguidas: são candidatas a [cancelamento](/api-reference/v3/phone-accounts/cancel) ou a um plano menor.


# Visão geral
Source: https://docs.salvy.com.br/api-reference/v3/recipes/introduction

Guias passo a passo que resolvem problemas reais da sua operação combinando endpoints da API da Salvy.

A [referência da API](/api-reference/v3/introduction) explica o que cada endpoint faz. As receitas mostram como combiná-los para resolver um problema de ponta a ponta, como bloquear as linhas de quem saiu da empresa ou ratear a fatura por centro de custo.

Cada receita traz:

* **O problema** que ela resolve e para quem é útil.
* **O que você precisa** antes de começar: tipo de chave e endpoints usados.
* **O passo a passo**, com uma requisição por etapa e o motivo de cada uma.
* **Um workflow do n8n** pronto para baixar e testar, sem precisar escrever código.
* **Cuidados e variações**, como paginação, reexecução segura e testes no sandbox.

> [!TIP]
>
> Todas as receitas usam a **v3** da API. Comece com uma chave de sandbox
> (`salvy_test_`) e só troque para produção depois de validar o fluxo. Veja
> [Ambientes](/api-reference/v3/environments).

## Pessoas e RH

> [card] [Admissão → colaborador + linha](/api-reference/v3/recipes/admission-create-line)
>
> Quando o RH admite alguém, cadastre o colaborador e peça a linha dele no
> mesmo centro de custo.

> [card] [Desligamento → bloqueio de linhas](/api-reference/v3/recipes/offboarding-block-lines)
>
> Quando o RH desliga um colaborador, bloqueie automaticamente todas as linhas
> ativas dele.

## Financeiro

> [card] [Rateio de telecom por centro de custo](/api-reference/v3/recipes/cost-center-allocation)
>
> Divida a fatura de telecom do mês por centro de custo, pronta para o
> lançamento contábil.

> [card] [Fatura + NF-e para contas a pagar](/api-reference/v3/recipes/invoice-nfe-accounts-payable)
>
> Baixe todo mês a fatura com boleto e Pix e os arquivos da NF-e, sem entrar
> no painel.

## Gestão de linhas

> [card] [Consumo de dados: maiores e menores](/api-reference/v3/recipes/data-usage-ranking)
>
> Descubra quais linhas mais e menos consomem dados em relação à franquia do
> plano.


# Fatura + NF-e para contas a pagar
Source: https://docs.salvy.com.br/api-reference/v3/recipes/invoice-nfe-accounts-payable

Todo mês, baixe automaticamente o PDF de cada fatura da Salvy, com boleto e Pix, e a NF-e em PDF e XML para o seu contas a pagar.

Todo mês alguém do financeiro entra no painel da Salvy, baixa a fatura para pagar o boleto ou o Pix e depois volta para baixar a nota fiscal e lançar no ERP. Quando a empresa tem várias faturas, ou várias empresas, isso vira uma rotina manual que atrasa o fechamento.

Nesta receita, sua integração busca as faturas do mês de referência e baixa, para cada uma, o PDF da fatura e, quando emitida, a NF-e em PDF e XML, prontos para o e-mail do contas a pagar, um SFTP ou a importação do seu ERP.

**Para quem é:** times de financeiro e contas a pagar que querem receber os documentos da Salvy sem acessar o painel.

## O que você precisa

* Uma **chave de API de empresa** ou uma **chave de organização**. A receita só faz leituras, então a chave de organização funciona e traz as faturas de todas as empresas da organização de uma vez. Veja [Chaves de API](/api-reference/v3/api-keys).
* O **mês de referência** das faturas, no formato `AAAA-MM`.

| Etapa | Endpoint |
| - | - |
| 1. Listar as faturas do mês | [`GET /api/v3/invoices`](/api-reference/v3/invoices/list) |
| 2. Detalhar cada fatura | [`GET /api/v3/invoices/{id}`](/api-reference/v3/invoices/get) |
| 3. Baixar o PDF da fatura | [`GET /api/v3/invoices/{id}/pdf`](/api-reference/v3/invoices/pdf) |
| 4. Baixar a NF-e | [`GET /api/v3/invoices/{id}/nfe/pdf`](/api-reference/v3/invoices/nfe-pdf) e [`/nfe/xml`](/api-reference/v3/invoices/nfe-xml) |

> [!WARNING]
>
> No sandbox, o PDF da fatura não está disponível: `GET /invoices/{id}/pdf`
> sempre retorna 404. Para testar essa etapa, use uma chave de produção. Nenhuma
> etapa desta receita altera dados na Salvy.

## Passo a passo

**1. Liste as faturas do mês**

Filtre as faturas pelo mês de referência com `monthYear`.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/invoices" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "monthYear=2026-08" \
  --data-urlencode "pageSize=200"
```

```json theme={null}
{
  "data": [
    {
      "id": "0198c2f1-3815-45b7-9e60-8e137cad845c",
      "companyId": "0198c2f1-3815-45b7-9e60-8e137cad8450",
      "status": "pending",
      "isLate": false,
      "amountCents": 174108,
      "dueDate": "2026-09-10",
      "referenceMonth": "2026-08"
    }
  ],
  "pagination": { "page": 1, "pageSize": 200, "totalCount": 1, "totalPages": 1 }
}
```

Só três situações seguem para o contas a pagar. As outras são faturas encerradas, que não devem ser pagas:

| `status` | Significado | Enviar ao contas a pagar? |
| - | - | - |
| `pending` | Aberta, aguardando pagamento. | Sim |
| `failed` | A cobrança foi recusada e a fatura continua aberta. | Sim |
| `paid` | Já paga. Continua útil para a conciliação e para a nota fiscal. | Sim |
| `voided` | Cancelada. | Não |
| `refunded` | O pagamento foi estornado. | Não |
| `charged-back` | O pagamento com cartão foi contestado. | Não |

Uma fatura em atraso continua `pending` ou `failed`, com `isLate: true`.

A lista traz faturas de todos os produtos da Salvy. Para só telecom, adicione `product=telecom`. Com uma chave de organização, cada fatura traz o `companyId` da empresa a que pertence.

**2. Detalhe cada fatura**

O detalhe traz os itens cobrados e os dados da nota fiscal.

```bash theme={null}
curl "https://api.salvy.com.br/api/v3/invoices/0198c2f1-3815-45b7-9e60-8e137cad845c" \
  -H "Authorization: Bearer $SALVY_API_KEY"
```

```json theme={null}
{
  "id": "0198c2f1-3815-45b7-9e60-8e137cad845c",
  "status": "pending",
  "amountCents": 174108,
  "dueDate": "2026-09-10",
  "items": [
    { "product": "telecom", "description": "Plano Salvy de Telefonia Móvel", "quantity": 1, "unitAmountCents": 140178 },
    { "product": "telecom", "description": "Cobranças não recorrentes", "quantity": 1, "unitAmountCents": 33930 }
  ],
  "nfe": { "number": 12345, "amountCents": 174108 }
}
```

O campo `nfe` vem `null` enquanto a nota não foi emitida e quando ela foi cancelada. Nesses casos, pule a etapa 4 e avise o financeiro.

**3. Baixe o PDF da fatura**

O PDF da fatura traz os dados de pagamento da cobrança vigente: boleto e Pix. Ele **não** é a nota fiscal.

```bash theme={null}
curl "https://api.salvy.com.br/api/v3/invoices/0198c2f1-3815-45b7-9e60-8e137cad845c/pdf" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -o fatura.pdf
```

Trate a resposta 404 como "PDF indisponível" e siga para as próximas faturas, em vez de interromper o processo. No sandbox ela acontece sempre.

**4. Baixe a NF-e em PDF e XML**

Quando a fatura tem `nfe`, baixe o DANFE em PDF e o XML da nota.

```bash theme={null}
curl "https://api.salvy.com.br/api/v3/invoices/0198c2f1-3815-45b7-9e60-8e137cad845c/nfe/pdf" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -o nfe.pdf

curl "https://api.salvy.com.br/api/v3/invoices/0198c2f1-3815-45b7-9e60-8e137cad845c/nfe/xml" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -o nfe.xml
```

## Sem código: workflow do n8n

Se você usa o [n8n](https://n8n.io), baixe o workflow pronto com as quatro etapas. Ele tem dois gatilhos: um manual, para testar, e uma agenda mensal, para rodar sozinho.

Baixar workflow do n8n

`invoice-nfe-accounts-payable.json`: importe no n8n e siga as notas dentro do workflow.

1. No n8n, crie um workflow e importe o arquivo (menu **⋯ > Import from File**, ou cole o conteúdo do arquivo no editor).
2. Crie uma credencial **Bearer Auth** com a sua chave de API e selecione-a nos cinco nós HTTP.
3. Preencha o `mesReferencia` no nó **Dados de teste** e execute. Se deixar vazio, vale o mês anterior.
4. Conecte o destino dos arquivos depois dos nós finais: e-mail do contas a pagar, SFTP, Google Drive ou o seu ERP.
5. Para rodar todo mês, ative o workflow. As faturas são geradas no dia 1º de cada mês, e o nó **Agenda mensal** dispara no dia 5, às 8h, buscando o mês anterior. Os dias entre a geração e a agenda são uma margem para a fatura já estar disponível.

## Como implementar

* **Gatilho:** uma rotina mensal. As faturas são geradas no dia 1º de cada mês; rodar no dia 5 dá margem para a fatura já estar disponível. Também dá para chamar o fluxo a partir do seu ERP.
* **Destino dos arquivos:** e-mail do contas a pagar, SFTP, uma pasta compartilhada ou a importação do seu ERP.
* **Somente leitura:** a receita não altera nada na Salvy, então pode ser executada quantas vezes for preciso.

## Cuidados

> [accordion] Não pague faturas encerradas
>
> Faturas com `status` `voided`, `refunded` ou `charged-back` estão encerradas: não há nada a pagar. Filtre-as antes de enviar qualquer documento para o contas a pagar e registre-as à parte, como faz o workflow desta receita.

> [accordion] O PDF da fatura não é a nota fiscal
>
> `GET /invoices/{id}/pdf` traz o boleto e o Pix da cobrança vigente. A nota fiscal é o DANFE, em `GET /invoices/{id}/nfe/pdf`, com o XML em `GET /invoices/{id}/nfe/xml`. Envie os dois para o financeiro: um para pagar, outro para escriturar.

> [accordion] Nota ainda não emitida ou cancelada
>
> Enquanto a NF-e não é emitida, e quando ela é cancelada, o campo `nfe` da fatura vem `null`. Registre essas faturas para conferir depois, em vez de tratar a ausência da nota como erro.

> [accordion] Chave de organização com muitas empresas
>
> Com uma chave de organização, a lista traz as faturas de todas as empresas da organização. Use o `companyId` de cada fatura para separar os documentos por empresa e percorra todas as páginas da lista, como no código acima.

## Variações

* **Só telecom.** Adicione `product=telecom` na lista de faturas para ignorar as faturas de outros produtos da Salvy.
* **Cobrar o que está em atraso.** Filtre por `isLate: true` para montar um alerta de faturas vencidas e ainda abertas.
* **Rateio por centro de custo.** Para lançar o custo de telecom por centro de custo, use o detalhamento por linha da fatura em [`GET /api/v3/invoices/{id}/phone-accounts`](/api-reference/v3/invoices/phone-accounts).


# Desligamento → bloqueio de linhas
Source: https://docs.salvy.com.br/api-reference/v3/recipes/offboarding-block-lines

Quando o RH desliga um colaborador, encontre as linhas ativas dele e bloqueie todas automaticamente.

Quando alguém sai da empresa, as linhas que estavam com essa pessoa continuam funcionando até alguém lembrar de bloqueá-las no painel. Nesse intervalo, o chip pode continuar em uso fora da empresa.

Nesta receita, o próprio evento de desligamento do seu sistema de RH dispara o bloqueio: a partir do CPF do colaborador, sua integração encontra as linhas ativas dele, bloqueia cada uma e marca o colaborador como desligado na Salvy.

**Para quem é:** times de RH, TI ou de gestão de telecom que querem tirar o bloqueio de linhas do checklist manual de desligamento.

## O que você precisa

* Uma **chave de API de empresa**. Chaves de organização são somente leitura e não podem bloquear linhas. Veja [Chaves de API](/api-reference/v3/api-keys).
* O **CPF** do colaborador desligado e a **data do desligamento**, vindos do seu sistema de RH.
* Os colaboradores cadastrados na Salvy com CPF e as linhas associadas a eles.

| Etapa | Endpoint |
| - | - |
| 1. Encontrar o colaborador | [`GET /api/v3/employees`](/api-reference/v3/employees/list) |
| 2. Listar as linhas ativas | [`GET /api/v3/phone-accounts`](/api-reference/v3/phone-accounts/list) |
| 3. Bloquear cada linha | [`POST /api/v3/phone-accounts/{id}/block`](/api-reference/v3/phone-accounts/block) |
| 4. Marcar o colaborador como desligado | [`PATCH /api/v3/employees/{id}`](/api-reference/v3/employees/update) |

## Passo a passo

**1. Encontre o colaborador pelo CPF**

Filtre a lista de colaboradores pelo CPF. O filtro aceita o CPF com ou sem pontuação.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/employees" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "cpf=529.982.247-25" \
  --data-urlencode "status=active" \
  --data-urlencode "status=on-hold"
```

Filtre também por `status=active` e `status=on-hold`. O mesmo CPF pode ter mais de um cadastro, por exemplo quando a pessoa foi readmitida. Com esse filtro você ignora os cadastros que já foram desligados. A lista vem ordenada do cadastro mais recente para o mais antigo, então use o primeiro item de `data`.

```json theme={null}
{
  "data": [
    {
      "id": "0198c2f1-3815-45b7-9e60-8e137cad845c",
      "fullName": "João da Silva",
      "status": "active"
    }
  ],
  "pagination": { "page": 1, "pageSize": 50, "totalCount": 1, "totalPages": 1 }
}
```

Se `data` vier vazio, não há colaborador ativo com esse CPF e não há nada a bloquear.

**2. Liste as linhas ativas do colaborador**

Filtre as linhas pelo `employeeId` encontrado e pelo status `active`.

```bash theme={null}
curl -G "https://api.salvy.com.br/api/v3/phone-accounts" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  --data-urlencode "employeeId=0198c2f1-3815-45b7-9e60-8e137cad845c" \
  --data-urlencode "status=active" \
  --data-urlencode "pageSize=200"
```

Cada item de `data` é uma linha, com `id`, `phoneNumber` e `name`. Se `pagination.totalPages` for maior que 1, busque as páginas seguintes com o parâmetro `page` antes de continuar.

**3. Bloqueie cada linha**

Para cada linha, chame o endpoint de bloqueio com o motivo. Use `reason: "other"` e descreva o motivo em `otherReason`, para que o histórico da linha registre por que ela foi bloqueada.

```bash theme={null}
curl -X POST "https://api.salvy.com.br/api/v3/phone-accounts/0198c2f1-3815-45b7-9e60-8e137cad845d/block" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "other", "otherReason": "Colaborador desligado (integração RH)" }'
```

A resposta traz a linha com o estado atual. Bloquear uma linha que já está bloqueada não tem efeito, então repetir esta etapa é seguro.

**4. Marque o colaborador como desligado**

Depois que **todas** as linhas foram bloqueadas, atualize o colaborador com o status `terminated` e a data do desligamento.

```bash theme={null}
curl -X PATCH "https://api.salvy.com.br/api/v3/employees/0198c2f1-3815-45b7-9e60-8e137cad845c" \
  -H "Authorization: Bearer $SALVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "terminated", "terminatedAt": "2026-09-30" }'
```

Deixe esta etapa por último. A etapa 1 só encontra colaboradores ativos ou afastados: se você marcar o desligamento antes e algum bloqueio falhar, uma nova execução não encontra mais o colaborador e as linhas restantes ficam ativas.

## Sem código: workflow do n8n

Se você usa o [n8n](https://n8n.io), baixe o workflow pronto com as quatro etapas. Ele tem dois gatilhos: um manual, para testar, e um webhook, para o seu sistema de RH chamar a cada desligamento.

Baixar workflow do n8n

`offboarding-block-lines.json`: importe no n8n e siga as notas dentro do workflow.

1. No n8n, crie um workflow e importe o arquivo (menu **⋯ > Import from File**, ou cole o conteúdo do arquivo no editor).
2. Crie uma credencial **Bearer Auth** com a sua chave de API e selecione-a nos quatro nós HTTP.
3. Preencha o `cpf` no nó **Dados de teste** e execute. O workflow começa em modo simulação (`dryRun = true` no nó **Configuração**): ele mostra as linhas que seriam bloqueadas, sem bloquear nada.
4. Quando o resultado estiver certo, troque `dryRun` para `false`. Para rodar automaticamente, ative o workflow e faça o seu sistema de RH chamar a URL do nó **Webhook do RH** com `{ "cpf": "...", "terminatedAt": "AAAA-MM-DD" }`.

> [!WARNING]
>
> A URL de um webhook do n8n é pública. Antes de ativar o workflow, configure
> uma autenticação no nó **Webhook do RH** (por exemplo, Header Auth).

## Como implementar

* **Gatilho:** um webhook do sistema de RH a cada desligamento, uma rotina diária que busca os desligamentos do dia ou um botão no seu sistema interno.
* **Modo simulação primeiro.** Comece com uma versão que só consulta e mostra as linhas que seriam bloqueadas, sem fazer as chamadas de escrita. Confira o resultado e só depois ative as escritas.
* **Ordem das etapas:** marque o desligamento só depois de bloquear todas as linhas. Se algum bloqueio falhar, interrompa antes do `PATCH`, para que uma nova execução ainda encontre o colaborador.

## Cuidados

> [accordion] Teste no sandbox antes de usar em produção
>
> Bloquear uma linha em produção interrompe o serviço dela de verdade. Valide o fluxo com uma chave de sandbox (`salvy_test_`), com colaboradores e linhas de teste, antes de trocar para a chave de produção. Veja [Ambientes](/api-reference/v3/environments).

> [accordion] Reexecutar é seguro
>
> Se a execução parar no meio, rode de novo com o mesmo CPF. As linhas já bloqueadas não voltam na etapa 2 (elas deixam de ter status `active`) e bloquear de novo uma linha bloqueada não tem efeito. Como o desligamento só é marcado no final, o colaborador continua sendo encontrado até todas as linhas estarem bloqueadas.

> [accordion] Se você já integra seu RH com a Salvy
>
> O `PATCH` da etapa 4 conta como uma edição manual, e edições manuais têm prioridade sobre os dados que chegam de integrações. Se o seu sistema de RH já envia o status dos colaboradores para a Salvy, pule a etapa 4 e deixe a integração informar o desligamento. Caso contrário, uma readmissão futura enviada pela integração não substitui o status `terminated` que você gravou.

> [accordion] Linhas sem colaborador associado não são encontradas
>
> A etapa 2 só encontra as linhas associadas ao colaborador na Salvy. Se a sua empresa costuma deixar linhas sem colaborador, associe cada linha ao colaborador responsável, pelo painel ou por [`PATCH /api/v3/phone-accounts/{id}`](/api-reference/v3/phone-accounts/update), para que esta receita encontre todas.

## Variações

* **Avisar o gestor.** Ao final, envie para o Slack, Teams ou e-mail do gestor um resumo com o nome do colaborador e os números bloqueados.
* **Confirmar pelo webhook.** Assine o evento [`phone-account.blocked`](/api-reference/v3/webhooks/phone-account-blocked) para registrar no seu sistema cada linha bloqueada, inclusive as bloqueadas pelo painel.
* **Cancelar em vez de bloquear.** Se a linha não vai ser reaproveitada por outra pessoa, use [Cancelar linha](/api-reference/v3/phone-accounts/cancel) em vez do bloqueio. O bloqueio pode ser desfeito com [Desbloquear linha](/api-reference/v3/phone-accounts/unblock) e é a opção mais segura enquanto a linha aguarda um novo responsável.


# Detalhar tarefa
Source: https://docs.salvy.com.br/api-reference/v3/tasks/get

api-reference/v3/openapi.json GET /api/v3/tasks/{id}
Consulta o andamento de uma tarefa iniciada por uma chave de API da sua empresa, com as contagens de itens aplicados, com falha, pendentes e interrompidos. O resultado de cada item está em GET /tasks/{id}/results. Tarefas iniciadas pelo dashboard não são consultáveis por aqui e respondem 404.

**Escopo necessário:** `task:read`

# Introdução a tarefas
Source: https://docs.salvy.com.br/api-reference/v3/tasks/introduction

Como funcionam as operações em lote da API: a tarefa que acompanha a operação, os resultados de cada item e os webhooks de conclusão

Algumas operações agem sobre muitos itens de uma vez, como aplicar um centro de custo a várias linhas ou sincronizar a base de colaboradores. Elas não terminam durante a requisição: a API aceita o pedido, responde `202` com o ID de uma **tarefa** e processa os itens em segundo plano.

## Como funciona

**1. Envie a operação em lote**

A requisição é validada por inteiro antes de qualquer item ser processado. Se algum item for inválido, a resposta é `422`, aponta a posição dele na lista e nada é alterado.

**2. Guarde o ID da tarefa**

Se a validação passar, a resposta é `202` com o `taskId`. Repetir a requisição com o mesmo cabeçalho `idempotency-key` devolve a mesma tarefa, sem processar os itens de novo.

**3. Acompanhe a tarefa**

Consulte [Detalhar tarefa](/api-reference/v3/tasks/get) até o `status` deixar de ser `running`, ou receba os webhooks [Tarefa concluída](/api-reference/v3/webhooks/task-succeeded) e [Tarefa concluída com falhas](/api-reference/v3/webhooks/task-failed).

**4. Consulte o resultado de cada item**

Use [Listar resultados da tarefa](/api-reference/v3/tasks/results), paginado. Filtre por `status=failed` para ver só os itens que não foram aplicados, com o motivo de cada um.

## Falhas por item

Depois da validação, cada item é processado de forma independente: um item que falha não desfaz os que já foram aplicados. No resultado, um item com falha traz:

* `reason`: o motivo, em português, pronto para mostrar ao seu usuário;
* `retryable`: `true` quando a falha é temporária e vale tentar de novo; `false` quando o pedido precisa mudar.

Para tentar de novo, envie uma nova operação só com os itens que falharam.

## Limites

* Até 1.000 itens por requisição.
* O corpo da requisição é limitado a 1 MB.

## Quem pode ler uma tarefa

Uma tarefa pode ser lida por qualquer chave de API da empresa que a iniciou, então trocar a chave não faz você perder o acesso às tarefas em andamento. A leitura exige o escopo `task:read`.


# Listar resultados da tarefa
Source: https://docs.salvy.com.br/api-reference/v3/tasks/results

api-reference/v3/openapi.json GET /api/v3/tasks/{id}/results
Lista o resultado de cada item já processado de uma tarefa iniciada por uma chave de API da sua empresa, na ordem em que os itens foram incluídos, com paginação. Itens pendentes ou interrompidos aparecem apenas nas contagens de GET /tasks/{id}. O campo `type` indica a operação da tarefa e o formato de cada item em `data`. Tarefas iniciadas pelo dashboard não são consultáveis por aqui e respondem 404.

**Escopo necessário:** `task:read`

# Cadastrar endpoint de webhook
Source: https://docs.salvy.com.br/api-reference/v3/webhook-endpoints/create

api-reference/v3/openapi.json POST /api/v3/webhook-endpoints
Cadastra um endpoint de webhook que passa a receber os tipos de evento escolhidos. A resposta traz o segredo de assinatura (`secret`), retornado somente nesta chamada: guarde-o para verificar os eventos recebidos.

**Escopo necessário:** `webhook-endpoint:create`

# Excluir endpoint de webhook
Source: https://docs.salvy.com.br/api-reference/v3/webhook-endpoints/delete

api-reference/v3/openapi.json DELETE /api/v3/webhook-endpoints/{id}
Exclui um endpoint de webhook da empresa. Ele deixa de receber eventos imediatamente.

**Escopo necessário:** `webhook-endpoint:delete`

# Listar tipos de evento
Source: https://docs.salvy.com.br/api-reference/v3/webhook-endpoints/event-types

api-reference/v3/openapi.json GET /api/v3/webhook-event-types
Lista os tipos de evento que um endpoint de webhook pode receber, em ordem alfabética de nome. A lista é completa e não é paginada.

**Escopo necessário:** `webhook-endpoint:read`

# Detalhar endpoint de webhook
Source: https://docs.salvy.com.br/api-reference/v3/webhook-endpoints/get

api-reference/v3/openapi.json GET /api/v3/webhook-endpoints/{id}
Busca um endpoint de webhook da empresa pelo ID. O segredo de assinatura não é retornado.

**Escopo necessário:** `webhook-endpoint:read`

# Equipamento criado
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/asset-created

api-reference/v3/openapi.json webhook asset.created
Evento emitido quando um equipamento é criado

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando um equipamento é criado na sua empresa.

O payload traz apenas o `assetId`. Para ver os dados do equipamento, consulte [Detalhar equipamento](/api-reference/v3/assets/get).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `assetId` para buscar os dados atuais do equipamento em vez de inferi-los a partir da sequência de eventos recebidos.


# Equipamento excluído
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/asset-deleted

api-reference/v3/openapi.json webhook asset.deleted
Evento emitido quando um equipamento é excluído

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando um equipamento da sua empresa é excluído.

O payload traz apenas o `assetId` do equipamento excluído. Como ele não existe mais, [Detalhar equipamento](/api-reference/v3/assets/get) passa a responder `404` para esse ID: use o próprio evento para remover o equipamento do seu lado.

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Trate a exclusão como definitiva: um `asset.updated` do mesmo equipamento que chegue depois dela não significa que ele voltou a existir.


# Termo cancelado
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/asset-statement-canceled

api-reference/v3/openapi.json webhook asset-statement.canceled
Evento emitido quando um termo de equipamentos é cancelado

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando um termo de responsabilidade ou de devolução de equipamentos da sua empresa é cancelado.

O payload traz apenas o `assetStatementId`. Para saber o motivo, consulte `cancelReason` em [Detalhar termo](/api-reference/v3/asset-statements/get):

| `cancelReason` | Quando acontece | Tipos de termo |
| - | - | - |
| `replaced-by-new-document` | Um termo de responsabilidade mais novo foi enviado para algum dos mesmos equipamentos. `replacedById` traz o ID do termo novo. | Responsabilidade |
| `content-outdated` | Um equipamento do termo passou para outro colaborador antes da assinatura. | Responsabilidade |
| `client-request` | A empresa cancelou o termo. | Responsabilidade e devolução |
| `signer-refused` | O colaborador recusou a assinatura. | Responsabilidade e devolução |

Termos de devolução não são substituídos: enviar um novo termo de devolução não cancela o anterior.

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `assetStatementId` para buscar os dados atuais do termo em vez de inferi-los a partir da sequência de eventos recebidos.


# Termo assinado
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/asset-statement-signed

api-reference/v3/openapi.json webhook asset-statement.signed
Evento emitido quando um colaborador assina um termo de equipamentos

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando um colaborador da sua empresa assina um termo de responsabilidade ou de devolução de equipamentos.

O payload traz apenas o `assetStatementId`. Para ver os dados do termo, consulte [Detalhar termo](/api-reference/v3/asset-statements/get); para baixar o PDF assinado, [Baixar termo assinado](/api-reference/v3/asset-statements/signed-file).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `assetStatementId` para buscar os dados atuais do termo em vez de inferi-los a partir da sequência de eventos recebidos.


# Equipamento atualizado
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/asset-updated

api-reference/v3/openapi.json webhook asset.updated
Evento emitido quando os dados de um equipamento são atualizados

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando os dados de um equipamento da sua empresa são atualizados.

O payload traz apenas o `assetId`, sem indicar o que mudou. Para ver os dados atuais, consulte [Detalhar equipamento](/api-reference/v3/assets/get).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `assetId` para buscar os dados atuais do equipamento em vez de inferi-los a partir da sequência de eventos recebidos.


# Colaborador criado
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/employee-created

api-reference/v3/openapi.json webhook employee.created
Evento emitido quando um colaborador é criado

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando um colaborador é criado na sua empresa.

O payload traz apenas o `employeeId`. Para ver os dados do colaborador, consulte [Detalhar colaborador](/api-reference/v3/employees/get).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `employeeId` para buscar os dados atuais do colaborador em vez de inferi-los a partir da sequência de eventos recebidos.


# Colaborador excluído
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/employee-deleted

api-reference/v3/openapi.json webhook employee.deleted
Evento emitido quando um colaborador é excluído

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando um colaborador da sua empresa é excluído.

O payload traz apenas o `employeeId` do colaborador excluído. Como ele não existe mais, [Detalhar colaborador](/api-reference/v3/employees/get) passa a responder `404` para esse ID: use o próprio evento para remover o colaborador do seu lado.

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Trate a exclusão como definitiva: um `employee.updated` do mesmo colaborador que chegue depois dela não significa que ele voltou a existir.


# Colaborador atualizado
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/employee-updated

api-reference/v3/openapi.json webhook employee.updated
Evento emitido quando os dados de um colaborador são atualizados

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando os dados de um colaborador da sua empresa são atualizados.

O payload traz apenas o `employeeId`, sem indicar o que mudou. Para ver os dados atuais, consulte [Detalhar colaborador](/api-reference/v3/employees/get).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `employeeId` para buscar os dados atuais do colaborador em vez de inferi-los a partir da sequência de eventos recebidos.


# Introdução a Webhooks
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/introduction

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Os webhooks são uma forma de receber notificações em tempo real quando certos eventos ocorrem na plataforma Salvy. Em vez de solicitar constantemente atualizações à API (polling), os webhooks permitem que a Salvy envie informações diretamente para seu sistema assim que um evento acontece.

Para autenticar suas requisições à API, crie uma chave na página de [Chaves de API](/api-reference/v3/api-keys).

## Como funcionam os webhooks

A Salvy utiliza a plataforma [Svix](https://www.svix.com) para garantir uma entrega segura e confiável de webhooks.

A página de configurações de Webhooks está disponível no dashboard da Salvy, em Configurações > Funcionalidades > Webhooks.

Para mais detalhes de como a página de configurações funciona, e quais recursos estão disponíveis, consulte a [documentação da Svix](https://docs.svix.com/receiving/introduction).

1. Crie uma URL em seu sistema para receber as requisições de webhook
2. Acesse a página de [configurações de Webhooks](https://app.salvy.com.br/settings/webhooks), cadastre a sua URL e selecione os eventos desejados.
3. Quando um evento relevante ocorre (como o recebimento de um SMS), a Salvy envia uma requisição HTTP POST para sua URL
4. Seu sistema processa os dados recebidos e responde com um código de status HTTP 2xx para confirmar o recebimento. Se a resposta não for 2xx, a Salvy tenta reenviar o evento, veja [Entrega e novas tentativas](#entrega-e-novas-tentativas)
5. Para maior segurança, sugerimos que seu sistema também [verifique a integridade dos dados recebidos](/api-reference/v3/webhooks/verifying-payloads)

## Formato da requisição

Todas as requisições de webhook seguem o mesmo formato padrão:

```json theme={null}
{
  "type": "event.name",
  "timestamp": "2025-09-03T12:34:56Z",
  "data": {
    // Dados específicos do evento
  }
}
```

| Campo | Descrição |
| - | - |
| `type` | Identificador do tipo de evento (ex: `sms.received`) |
| `timestamp` | Data e hora em que o evento foi gerado, em formato ISO8601 |
| `data` | Objeto contendo os dados específicos do evento |

## Entrega e novas tentativas

Seu endpoint deve responder com um código de status HTTP **2xx** em até **15 segundos**. Qualquer outra resposta (4xx, 5xx, timeout ou erro de conexão) é tratada como falha, e o evento entra na fila de novas tentativas.

> [!TIP]
>
> Responda primeiro, processe depois. Se o seu sistema executar todo o
> processamento antes de responder, uma tarefa demorada pode estourar o tempo
> limite e fazer com que a Salvy reenvie um evento que você já processou.

### Cronograma de tentativas

Cada evento é tentado até **8 vezes**, ao longo de pouco mais de 27 horas. Cada intervalo começa após a falha da tentativa anterior; a última coluna mostra o tempo total decorrido desde o envio original:

| Tentativa | Momento do envio | Tempo acumulado total |
| - | - | - |
| 1ª | Imediatamente | 0 |
| 2ª | 5 segundos após a tentativa anterior | 5 segundos |
| 3ª | 5 minutos após a tentativa anterior | \~5 minutos |
| 4ª | 30 minutos após a tentativa anterior | \~35 minutos |
| 5ª | 2 horas após a tentativa anterior | \~2h35 |
| 6ª | 5 horas após a tentativa anterior | \~7h35 |
| 7ª | 10 horas após a tentativa anterior | \~17h35 |
| 8ª | 10 horas após a tentativa anterior | \~27h35 |

Como um mesmo evento pode ser entregue mais de uma vez (por exemplo, quando a sua resposta demora e a conexão cai antes de chegar até nós), trate o recebimento de forma **idempotente**. O header `svix-id` é único e estável por evento: use-o para identificar e descartar entregas repetidas.

### Quando as tentativas se esgotam

Se as 8 tentativas falharem, o evento é marcado como falho e **não é mais reenviado automaticamente**. Nesse momento, a Salvy avisa os administradores da empresa por e-mail ("Não foi possível entregar um evento"), identificando o endpoint afetado.

> [!WARNING]
>
> Esse aviso se refere a um único evento. Enquanto o endpoint estiver
> indisponível, outros eventos também vão falhar. Para não inundar a sua caixa
> de entrada, agrupamos os avisos: você recebe no máximo um e-mail por endpoint
> a cada 6 horas.

### Desativação automática do endpoint

Se **todas** as entregas para um endpoint falharem por cinco dias consecutivos, ele é **desativado automaticamente** e para de receber eventos. Os administradores recebem um e-mail de aviso ("Desativamos um endpoint da sua integração").

Um endpoint desativado não volta a funcionar sozinho. Depois de corrigir o problema, é preciso **reativá-lo manualmente** na página de [configurações de Webhooks](https://app.salvy.com.br/settings/webhooks).

### Como se recuperar de uma falha

**1. Verifique o endpoint**

Confirme que a URL está acessível publicamente e respondendo 2xx. O
histórico de tentativas, com o status HTTP e o corpo de cada resposta, fica
na página de [configurações de
Webhooks](https://app.salvy.com.br/settings/webhooks).

**2. Reative o endpoint, se ele tiver sido desativado**

Endpoints desativados precisam ser reativados manualmente na mesma página.

**3. Reenvie os eventos que ficaram para trás**

Use **Recover Failed** para reenviar os eventos que falharam a partir de uma
data, ou **Replay Missing** para reenviar os eventos que nunca chegaram a
ser tentados enquanto o endpoint esteve desativado. Eventos individuais
também podem ser reenviados pelo histórico.

Eventos novos voltam a ser entregues normalmente assim que o endpoint estiver saudável e ativo.

## Segurança

Para garantir a autenticidade das requisições de webhook, recomendamos:

1. Utilizar HTTPS para sua URL de webhook
2. Validar a origem da requisição verificando os cabeçalhos HTTP
3. Implementar um mecanismo de retry e timeout adequado para lidar com falhas temporárias

## Eventos disponíveis

Atualmente, a Salvy oferece os seguintes eventos via webhook:

* [SMS recebido](/api-reference/v3/webhooks/sms-received) (`sms.received`): quando um SMS é recebido pelo número virtual
* [Linha ativada](/api-reference/v3/webhooks/phone-account-activated) (`phone-account.activated`): quando uma linha é ativada
* [Linha bloqueada](/api-reference/v3/webhooks/phone-account-blocked) (`phone-account.blocked`): quando uma linha é bloqueada
* [Linha desbloqueada](/api-reference/v3/webhooks/phone-account-unblocked) (`phone-account.unblocked`): quando uma linha é desbloqueada
* [Linha cancelada](/api-reference/v3/webhooks/phone-account-canceled) (`phone-account.canceled`): quando uma linha é cancelada
* [Linha reativada](/api-reference/v3/webhooks/phone-account-reactivated) (`phone-account.reactivated`): quando uma linha é reativada
* [eSIM pronto para instalação](/api-reference/v3/webhooks/phone-account-esim-ready) (`phone-account.esim-ready`): quando o código de ativação do eSIM de uma linha fica disponível

Para mais detalhes sobre cada evento, consulte a documentação específica.

## Testes

Para realizar testes na sua integração de Webhooks, recomendamos o uso da seguinte ferramenta: [Standard Webhooks - Simulate Webhooks](https://www.standardwebhooks.com/simulate/svix)

## Gerenciar endpoints pela API

Além da página de configurações, você pode cadastrar e excluir endpoints pela API, o que é útil para integrações que configuram os próprios webhooks:

* [Listar tipos de evento](/api-reference/v3/webhook-endpoints/event-types): os eventos que um endpoint pode receber.
* [Cadastrar endpoint de webhook](/api-reference/v3/webhook-endpoints/create): a resposta traz o segredo de assinatura (`secret`), retornado somente nesta chamada. Guarde-o para [verificar os eventos](/api-reference/v3/webhooks/verifying-payloads).
* [Detalhar](/api-reference/v3/webhook-endpoints/get) e [excluir](/api-reference/v3/webhook-endpoints/delete) um endpoint.

Os endpoints cadastrados pela API aparecem na mesma página de configurações de Webhooks do dashboard.


# Linha ativada
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-activated

api-reference/v3/openapi.json webhook phone-account.activated
Evento emitido quando uma linha é ativada

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma linha da sua empresa é ativada e passa a poder ser usada.

O payload traz apenas o `phoneAccountId`. Para saber o estado atual da linha, consulte [Detalhar linha](/api-reference/v3/phone-accounts/get) (disponível na v3).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `phoneAccountId` para buscar o estado atual da linha em vez de inferi-lo a partir da sequência de eventos recebidos.


# Linha bloqueada
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-blocked

api-reference/v3/openapi.json webhook phone-account.blocked
Evento emitido quando uma linha é bloqueada

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma linha da sua empresa é bloqueada e deixa de funcionar até ser desbloqueada.

O payload traz apenas o `phoneAccountId`. Para saber o estado atual da linha, consulte [Detalhar linha](/api-reference/v3/phone-accounts/get) (disponível na v3).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `phoneAccountId` para buscar o estado atual da linha em vez de inferi-lo a partir da sequência de eventos recebidos.


# Linha cancelada
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-canceled

api-reference/v3/openapi.json webhook phone-account.canceled
Evento emitido quando uma linha é cancelada

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma linha da sua empresa é cancelada.

Uma linha cancelada ainda pode ser reativada. Nesse caso, você recebe [Linha reativada](/api-reference/v3/webhooks/phone-account-reactivated) (`phone-account.reactivated`).

O payload traz apenas o `phoneAccountId`. Para saber o estado atual da linha, consulte [Detalhar linha](/api-reference/v3/phone-accounts/get) (disponível na v3).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `phoneAccountId` para buscar o estado atual da linha em vez de inferi-lo a partir da sequência de eventos recebidos.


# Saldo de dados baixo
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-data-balance-low

api-reference/v3/openapi.json webhook phone-account.data-balance-low
Evento emitido quando o saldo de dados de uma linha cai para 20% ou para 0% do plano

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando o saldo de dados de uma linha da sua empresa cai para **20%** ou para **0%** dos dados do plano. O campo `threshold` diz qual nível foi atingido:

* `20`: a linha está perto de ficar sem dados;
* `0`: os dados do plano acabaram.

O payload traz o `phoneAccountId` e o `threshold`. Para ver o saldo da linha, consulte [Consultar saldo](/api-reference/v3/phone-accounts/balance); ele mostra a mesma leitura que disparou o evento.

* **Um evento por leitura de saldo.** Se o saldo cair de uma vez abaixo dos dois níveis, por exemplo de 30% para 0%, você recebe só o mais grave: `0`.
* **Os níveis se renovam.** Quando o saldo sobe, por uma recarga ou pela virada do ciclo, cada nível volta a disparar na próxima vez que for atingido.

> [!NOTE]
>
> O evento reflete o saldo da linha na última leitura feita junto à operadora, que pode levar algum tempo para acompanhar o consumo real.

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Trate o mesmo `phoneAccountId` e `threshold` recebidos em sequência como um único aviso.


# eSIM pronto para instalação
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-esim-ready

api-reference/v3/openapi.json webhook phone-account.esim-ready
Evento emitido quando o código de ativação do eSIM de uma linha fica disponível

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando o código de ativação do eSIM de uma linha fica disponível. O payload já traz o código — o QR code (`qrCodeBase64`), o código completo (`fullCode`) e as partes separadas (`code` e `smdpDomain`) —, então você pode enviar o eSIM para o colaborador sem precisar fazer outra requisição.

Se precisar do código de novo mais tarde, consulte [Obter eSIM da linha](/api-reference/v3/phone-accounts/esim) (disponível na v3).

> [!WARNING]
>
> O código de ativação permite instalar a linha em qualquer aparelho. Trate-o como uma credencial: não o registre em logs e envie-o apenas para quem vai instalar o eSIM.


# Linha reativada
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-reactivated

api-reference/v3/openapi.json webhook phone-account.reactivated
Evento emitido quando uma linha é reativada

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma linha **cancelada** da sua empresa volta a funcionar: é o inverso de [Linha cancelada](/api-reference/v3/webhooks/phone-account-canceled) (`phone-account.canceled`). O inverso de um bloqueio é [Linha desbloqueada](/api-reference/v3/webhooks/phone-account-unblocked) (`phone-account.unblocked`).

A reativação não é feita pela API. Ela acontece quando a Salvy reativa a linha ou quando uma portabilidade de saída da linha é revertida.

Depois da reativação, a linha pode ficar ativa na hora ou ainda precisar de uma etapa de ativação (chip físico ou eSIM). Confirme o estado atual antes de liberá-la para uso.

O payload traz apenas o `phoneAccountId`. Para saber o estado atual da linha, consulte [Detalhar linha](/api-reference/v3/phone-accounts/get) (disponível na v3).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `phoneAccountId` para buscar o estado atual da linha em vez de inferi-lo a partir da sequência de eventos recebidos.


# Linha desbloqueada
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/phone-account-unblocked

api-reference/v3/openapi.json webhook phone-account.unblocked
Evento emitido quando uma linha é desbloqueada

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma linha da sua empresa é desbloqueada.

Depois do desbloqueio, a linha pode voltar a ficar ativa imediatamente ou ainda depender de uma etapa de ativação — por isso, confirme o estado atual antes de liberá-la para uso.

O payload traz apenas o `phoneAccountId`. Para saber o estado atual da linha, consulte [Detalhar linha](/api-reference/v3/phone-accounts/get) (disponível na v3).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `phoneAccountId` para buscar o estado atual da linha em vez de inferi-lo a partir da sequência de eventos recebidos.


# SMS recebido
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/sms-received

api-reference/v3/openapi.json webhook sms.received
Evento emitido quando um SMS é recebido pelo número virtual

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Este evento é emitido para qualquer SMS recebido pelo número virtual móvel (`mobile-did`), mesmo que não contenha um código de verificação.

Fique atento, pois os números estão sujeitos a receber mensagens de spam.


# Tarefa concluída com falhas
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/task-failed

api-reference/v3/openapi.json webhook task.failed
Evento emitido quando uma tarefa termina com algum item não aplicado

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma tarefa iniciada por uma chave de API da sua empresa termina e ao menos um item não foi aplicado. Os itens que deram certo continuam aplicados.

O payload traz apenas o `taskId`. Para ver o resumo, consulte [Detalhar tarefa](/api-reference/v3/tasks/get); para o resultado de cada item, [Listar resultados da tarefa](/api-reference/v3/tasks/results).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `taskId` para buscar o estado atual da tarefa em vez de inferi-lo a partir da sequência de eventos recebidos.


# Tarefa concluída
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/task-succeeded

api-reference/v3/openapi.json webhook task.succeeded
Evento emitido quando uma tarefa termina com todos os itens aplicados

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

Emitido quando uma tarefa iniciada por uma chave de API da sua empresa termina com todos os itens aplicados.

O payload traz apenas o `taskId`. Para ver o resumo, consulte [Detalhar tarefa](/api-reference/v3/tasks/get); para o resultado de cada item, [Listar resultados da tarefa](/api-reference/v3/tasks/results).

> [!NOTE]
>
> Os eventos podem chegar fora de ordem ou mais de uma vez. Use o `taskId` para buscar o estado atual da tarefa em vez de inferi-lo a partir da sequência de eventos recebidos.


# Verificando Webhooks
Source: https://docs.salvy.com.br/api-reference/v3/webhooks/verifying-payloads

> [!WARNING]
>
> Para utilizar nossas APIs e Webhooks de linhas virtuais, é necessário aderir ao nosso [manual de branding](/api-reference/v3/branding)

## Introdução

A Salvy utiliza a plataforma [Svix](https://www.svix.com) para garantir uma entrega segura e confiável de webhooks. A verificação da autenticidade destes eventos é essencial para manter a segurança da sua aplicação.

Para realizar testes na sua integração de Webhooks, recomendamos o uso da seguinte ferramenta: [Standard Webhooks - Simulate Webhooks](https://www.standardwebhooks.com/simulate/svix)

## Verificação via SDK

A maneira recomendada para verificar a autenticidade dos eventos de webhook é utilizando o SDK da Svix disponível para diversas linguagens de programação:

```bash theme={null}
# Instalação para Node.js
npm install svix

# Instalação para Python
pip install svix

# Instalação para outras linguagens disponíveis na documentação da Svix
```

Para implementar a verificação via SDK, siga o passo a passo detalhado na [documentação oficial da Svix](https://docs.svix.com/receiving/verifying-payloads/how). Passe para a SDK o corpo da requisição e **todos** os headers recebidos: ela usa o `svix-id`, o `svix-timestamp` e o `svix-signature`.

> [!WARNING]
>
> Verifique a assinatura sobre o **corpo bruto** da requisição, exatamente como chegou. Se o seu framework já converteu o corpo em JSON, não o serialize de novo para verificar: qualquer diferença de espaços ou de ordem das chaves invalida a assinatura. Isso vale tanto para a SDK quanto para a verificação manual.

## Verificação manual

Alternativamente, é possível verificar a autenticidade dos eventos manualmente:

1. Pegue a chave de assinatura no painel de configurações de Webhooks, nos detalhes do endpoint. Ela começa com `whsec_`; remova esse prefixo e decodifique o restante de base64 para obter a chave.
2. Leia os headers `svix-id`, `svix-timestamp` e `svix-signature` da requisição.
3. Monte o conteúdo assinado juntando `svix-id`, `svix-timestamp` e o corpo bruto, separados por ponto: `{svix-id}.{svix-timestamp}.{corpo}`.
4. Calcule o HMAC-SHA256 desse conteúdo com a chave do passo 1 e codifique o resultado em base64.
5. Compare com as assinaturas do header `svix-signature`. Ele pode trazer mais de uma, separadas por espaço (por exemplo, durante a troca da chave), cada uma no formato `v1,<assinatura>`: a mensagem é válida se alguma delas for igual à calculada. Use uma comparação em tempo constante.
6. Rejeite a mensagem se o `svix-timestamp` estiver longe do horário atual. As SDKs da Svix aceitam até 5 minutos de diferença; isso impede que uma mensagem capturada seja reenviada depois.

Para mais detalhes, consulte a [documentação oficial da Svix](https://docs.svix.com/receiving/verifying-payloads/how-manual).


# Criar token WebRTC
Source: https://docs.salvy.com.br/api-reference/v3/webrtc/create-token

api-reference/v3/openapi.json POST /api/v3/webrtc/tokens
Emite uma credencial WebRTC de curta duração para uso pelo frontend do cliente.

**Escopo necessário:** `webrtc:issue-token`

# Comece a usar
Source: https://docs.salvy.com.br/mcp-guide/getting-started

Conecte seu agente de IA ao MCP da Salvy: autenticação por OAuth ou chave de API e a primeira chamada para validar a conexão.

## Antes de começar

Antes de conectar o MCP da Salvy, você precisa ter acesso à sua conta Salvy e utilizar um cliente de IA compatível com MCP. Isso inclui, por exemplo, Claude, ChatGPT, Codex, Cursor, Microsoft Copilot e ferramentas próprias da sua empresa.

A configuração e a forma de autenticação podem variar de acordo com o agente de IA que você utiliza.

Consulte a seção de [Integrações](/mcp-guide/integrations) para encontrar as instruções específicas para o seu cliente.

***

## Conectar ao MCP Salvy

Para conectar seu agente ao MCP da Salvy, adicione o MCP ao agente de IA que você deseja utilizar.

Para conexões feitas em nome de um usuário, você será direcionado para uma página de autorização da Salvy. Nela, poderá revisar o acesso solicitado e autorizar seu agente a utilizar a Salvy em seu nome.

Depois da autorização, a conexão será concluída e você poderá começar a utilizar as capacidades da Salvy pelo seu agente de IA.

A configuração pode variar de acordo com o agente que você utiliza. Consulte a seção de [Integrações](/mcp-guide/integrations) para ver o passo a passo específico para cada IA.

***

## Autenticação

Para utilizar o MCP da Salvy, é necessário autenticar o acesso antes que seu agente possa consultar informações ou realizar operações.

O MCP da Salvy oferece duas formas de autenticação:

**OAuth:** para conectar **um agente em nome de um usuário**. Esse é o fluxo utilizado quando você conecta seu agente à sua conta Salvy. Você será direcionado para uma página de autorização, onde poderá revisar o acesso solicitado e autorizar a conexão.

**API Key:** para conectar **um agente ou integração em nome de uma empresa**. A chave está associada a sua empresa e possui permissões específicas, chamadas de *scopes*, que determinam quais operações podem ser realizadas através daquela conexão.

### OAuth

Quando você utiliza OAuth, o MCP associa a conexão ao seu usuário da Salvy. As permissões disponíveis são determinadas pelos acessos que esse usuário possui na empresa que está sendo consultada ou gerenciada.

Por exemplo, se ele tiver acesso de Financeiro, poderá usar somente as ferramentas relacionadas ao financeiro da empresa, como consultas às faturas e rateio.

Isso significa que conectar seu agente ao MCP não cria um novo conjunto de permissões: o agente utiliza o contexto de acesso que já existe para você na Salvy. A autorização é verificada a cada chamada, considerando as permissões atuais do usuário.

Se sua organização tem mais de uma empresa cadastrada na Salvy, uma conexão OAuth pode operar em todas as empresas às quais você tem acesso, facilitando o trabalho de gestão.

### API Key

As API Keys representam o acesso de uma empresa, e não de um usuário individual. Cada chave possui um conjunto de *scopes* que são configurados na sua criação e definem quais capacidades podem ser utilizadas através dela.

Esse modelo é especialmente útil para integrações e agentes que precisam acessar a Salvy sem depender da sessão de um usuário específico.

**Cada API Key está associada a uma única empresa.** As operações realizadas através dela ficam limitadas à empresa e aos *scopes* configurados para aquela chave.

> [!WARNING]
>
> **Importante:** a API Key deve ser tratada como uma credencial sensível. Nunca compartilhe sua chave em conversas, código público ou ferramentas que não sejam confiáveis.

***

## Primeira chamada

Depois de conectar seu agente ao MCP da Salvy, faça uma pergunta simples ao seu agente de IA para verificar se a conexão está funcionando.

Você pode começar pedindo algo como:

> **Quais linhas estão ativas na minha empresa?**

Seu agente utilizará o MCP para consultar as linhas às quais você tem acesso e apresentar os resultados.

Se a resposta estiver correta, sua conexão está funcionando e você já pode começar a explorar as capacidades da Salvy.

A partir daí, você pode fazer outras perguntas, como:

> **Quais empresas eu gerencio pela Salvy?**

> **Quais linhas mais consumiram dados este mês?**

> **Quanto gastamos com telecom no mês passado?**

Para ver mais exemplos, consulte [O que você pode fazer](/mcp-guide/use-cases).


# Como funciona
Source: https://docs.salvy.com.br/mcp-guide/how-it-works

Como o MCP da Salvy expõe ferramentas ao seu agente de IA e como cada chamada respeita as permissões da sua conta.

## Contexto

O MCP da Salvy permite que seu agente acesse informações da sua operação conforme elas são necessárias para atender a uma solicitação.

Algumas informações já estão disponíveis para o agente, como as empresas às quais você tem acesso e as permissões que determinam quais operações podem ser realizadas.

Outras informações precisam ser consultadas pelo agente utilizando as ferramentas do MCP. Por exemplo, para encontrar uma linha específica, o agente pode primeiro consultar as linhas disponíveis e, a partir dos resultados, identificar a informação necessária para realizar uma operação.

Isso permite que o agente combine diferentes informações e ferramentas para atender a solicitações mais complexas.

Por exemplo, ao pedir:

> **Adicione até 5 GB às linhas que estão próximas de atingir o limite do plano.**

O agente pode precisar:

1. consultar as linhas às quais você tem acesso;
2. consultar o consumo dessas linhas;
3. identificar quais estão próximas do limite;
4. apresentar ou confirmar a operação, quando necessário;
5. executar a ação nas linhas selecionadas.

Em resumo: o agente utiliza o contexto disponível e consulta informações adicionais conforme precisa delas para realizar a tarefa.

***

## Descoberta de informações

Nem sempre você precisa informar todos os detalhes para fazer uma solicitação. Quando o agente precisa de uma informação que não está no seu pedido, ele pode consultá-la no MCP antes de continuar.

Por exemplo, se você pedir:

> **Quais linhas estão próximas de atingir o limite do plano?**

O agente pode primeiro consultar as linhas às quais você tem acesso e, depois, consultar o consumo de cada uma para identificar quais estão próximas do limite.

Você pode, portanto, fazer pedidos usando **o que você conhece da sua operação**, sem precisar conhecer IDs ou a estrutura interna da Salvy.

***

## Operações em lote

Algumas operações do MCP da Salvy permitem realizar uma mesma ação em várias linhas de uma só vez.

Você pode, por exemplo, pedir ao seu agente:

> **Bloqueie as linhas dos colaboradores que saíram da empresa.**

Quando a operação permitir, o agente poderá identificar as linhas que estão vinculadas a colaboradores desligados e realizar a ação em conjunto, em vez de executar uma chamada individual para cada linha.

Cada operação possui seus próprios limites e regras. Por isso, dependendo da quantidade de linhas e do tipo de ação, o agente pode precisar dividir a operação em diferentes etapas.

O resultado também depende do tipo de operação. Algumas ações são executadas de forma conjunta, enquanto outras podem retornar um resultado individual para cada linha processada. Por isso, uma falha em uma linha não significa necessariamente que as demais alterações serão desfeitas.

O agente apresentará o resultado da operação e informará eventuais linhas que não puderam ser processadas.

> [!NOTE]
>
> **Dica:** quando você estiver trabalhando com várias linhas, descreva claramente o que deseja selecionar. Você pode usar critérios como colaborador, empresa ou status.

***

## Confirmações

Algumas operações do MCP da Salvy, especialmente as que podem gerar uma cobrança, retornam ao agente as informações necessárias para que ele avalie a operação antes de executá-la.

Quando necessário, o agente pode apresentar os detalhes da operação e pedir sua confirmação antes de continuar. A Salvy recomenda que os agentes sejam conservadores ao decidir quando solicitar essa confirmação, mas essa decisão fica a cargo do agente que você está utilizando.

Por exemplo, ao pedir:

> **Adicione 5 GB às linhas da Ana e do João.**

O agente pode primeiro consultar as linhas, identificar quais serão afetadas e consultar o valor da operação. A partir dessas informações, ele pode apresentar os detalhes para você e solicitar sua confirmação antes de adicionar os dados.

Se o agente executar a operação sem solicitar uma confirmação, isso não significa que as permissões foram ignoradas. **A confirmação é uma etapa de interação com o agente, enquanto a autorização da operação continua sendo verificada pelo MCP.**

> [!WARNING]
>
> **Importante:** confirmar uma operação não substitui as permissões da sua conta. Mesmo que você confirme, a operação só poderá ser realizada se sua conexão estiver autorizada a executá-la.

***

## Resultados e estados

Depois de consultar informações ou realizar uma operação, o agente apresenta o resultado da solicitação e pode informar o estado da operação.

Algumas ações são concluídas imediatamente. Outras podem depender de etapas adicionais ou levar algum tempo para serem processadas.

Por exemplo, ao atribuir linhas a um centro de custo, o resultado pode indicar que as alterações foram **agendadas** para processamento. Nesse caso, o agente pode consultar novamente as linhas para verificar o resultado da operação.

Da mesma forma, algumas consultas podem retornar estados específicos que fazem parte do funcionamento da operação. Por exemplo, uma linha pode não ter um status de portabilidade disponível naquele momento, sem que isso represente necessariamente um erro.

**Se uma operação ainda estiver em processamento, não a considere concluída até que o resultado indique que ela foi finalizada.**

> [!NOTE]
>
> **Dica:** se você não tiver certeza se uma operação foi concluída, peça ao agente para verificar o estado atual antes de tentar realizá-la novamente.

***

## Limitações

O MCP da Salvy permite que seu agente consulte informações e realize operações na sua conta, mas nem tudo o que você faz pelo Dashboard está disponível pelo MCP.

**1. Nem todas as operações do Dashboard estão disponíveis**

O MCP disponibiliza um conjunto específico de capacidades relacionadas à telefonia da Salvy. Outras funcionalidades do Dashboard podem continuar disponíveis somente na plataforma.

**2. Cada operação possui seus próprios limites**

Operações em lote podem ter limites diferentes de quantidade de linhas e critérios de seleção. Dependendo da solicitação, o agente pode precisar dividir a operação em diferentes etapas ou informar que ela não pode ser realizada daquela forma.

**3. O MCP não substitui o contexto da sua empresa**

O agente tem acesso às informações e capacidades disponibilizadas pela Salvy, mas pode não ter acesso a informações que sua empresa mantém em outros sistemas, como RH, financeiro ou gestão de ativos.

Por isso, algumas decisões podem depender de informações que você precisa fornecer ao agente ou consultar em outras ferramentas.

**4. O acesso depende da sua conexão**

As informações e operações disponíveis dependem das permissões da conexão utilizada. Conectar um agente ao MCP não amplia os acessos que você já possui na Salvy.


# Integrações
Source: https://docs.salvy.com.br/mcp-guide/integrations

Conecte a Salvy ao Claude, ChatGPT, Codex, Microsoft Copilot, Cursor ou qualquer agente compatível com MCP, ou cadastre-a como conector na sua plataforma.

O MCP da Salvy é aberto a **qualquer agente de IA ou aplicação compatível com o protocolo MCP**, um protocolo aberto. Isso inclui ferramentas próprias da sua empresa, e não só produtos de mercado.

Abaixo, você encontra o passo a passo para **Claude**, **ChatGPT e Codex** e **Microsoft Copilot**, além de orientações para **Cursor** e outros agentes compatíveis. Esses são apenas exemplos documentados: se o seu agente oferece suporte a MCP, ele pode se conectar à Salvy.

## Claude

> [!NOTE]
>
> **Antes de começar**
>
> Verifique se você tem permissão para adicionar conectores na sua organização do Claude.
>
> Em algumas empresas, somente um administrador da organização no Claude pode habilitar um novo conector.

Conecte sua conta da Salvy ao Claude para consultar informações e realizar tarefas sem precisar navegar pelo Dashboard. A Salvy está no diretório de conectores do Claude.

[**Conectar ao Claude**](https://claude.ai/directory/salvy)

1. Abra a página da Salvy no diretório do Claude pelo link acima.
2. Clique em **Conectar**.
3. Entre com sua conta Salvy e autorize o acesso.

Cada colaborador conecta a Salvy com a própria conta Salvy, e o Claude só acessa o que essa conta já pode ver e fazer.

### Primeira chamada

Depois de conectar, experimente perguntar:

> **Quais linhas estão ativas na minha empresa?**

Se o Claude retornar suas linhas, a conexão está funcionando.

Para mais exemplos, consulte [O que você pode fazer](/mcp-guide/use-cases).

***

## ChatGPT e Codex

A Salvy tem um plugin oficial no ChatGPT.

[**Conectar ao ChatGPT**](https://chatgpt.com/plugins/plugin_asdk_app_6acfc8ae0b6c8191a5bf025272ebce02)

1. Abra a página da Salvy no ChatGPT pelo link acima.
2. Clique em **Instalar plugin**.
3. Entre com sua conta Salvy e autorize o acesso.

Como a conexão utiliza OAuth, cada usuário precisa autorizar sua própria conta Salvy antes de utilizar o plugin. O acesso concedido continua limitado às permissões que esse usuário já possui na Salvy.

> [!NOTE]
>
> Em workspaces ChatGPT Business e Enterprise, um administrador pode precisar liberar o plugin da Salvy antes que os colaboradores consigam conectá-lo.

### O que o plugin do ChatGPT não faz

Pelas regras da loja do ChatGPT, o plugin oficial não recebe CPF. Por isso, nele não é possível:

* cadastrar um colaborador com CPF ou buscar colaboradores pelo CPF;
* pedir a portabilidade de um número que está no nome de uma pessoa (CPF). Números no nome da empresa (CNPJ) podem ser portados normalmente.

Para esses casos, use o Dashboard da Salvy ou configure o MCP manualmente, como descrito abaixo.

### Configuração manual no ChatGPT

Se você precisa dos recursos acima, adicione o MCP da Salvy como um servidor MCP personalizado.

> [!NOTE]
>
> Servidores MCP personalizados funcionam no ChatGPT pela web, nos planos **Business** e **Enterprise/Edu**. No Business, só administradores e proprietários do workspace podem adicioná-los; no Enterprise/Edu, um administrador pode liberar outros membros. No plano Pro, o servidor só pode consultar informações, sem realizar ações.

1. Acesse [**Plugins**](https://chatgpt.com/plugins), clique em **+** e escolha **Adicionar servidor MCP personalizado** (Add custom MCP server).

2. Informe os dados do MCP da Salvy:

   * **Nome:** `Salvy`
   * **Conexão (URL do MCP):** `https://mcp.salvy.com.br/mcp`
   * **Autenticação:** `OAuth`
   * **Logo:** envie o ícone da Salvy.

   Baixar a logo Salvy
   PNG · 512×512 · 30 KB

3. Leia o aviso de risco e marque **Entendo e quero continuar** (I understand and want to continue).

4. Clique em **Criar como plugin** (Create as a plugin) e revise as ferramentas encontradas.

5. Instale o plugin e autorize o acesso com sua conta Salvy.

Para disponibilizar o plugin aos outros colaboradores, um administrador ou proprietário precisa publicá-lo no workspace. Consulte a [documentação da OpenAI](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt).

> [!NOTE]
>
> Depois de publicado, o ChatGPT guarda uma cópia fixa das ferramentas. Quando a Salvy adicionar ou mudar ferramentas, um administrador precisa atualizar a lista nas configurações do workspace.

No **Codex**, agente de programação da OpenAI, procure a Salvy com o comando `/plugins`. Se ela não aparecer, adicione o servidor MCP com a URL e a autenticação `OAuth` acima, seguindo a documentação do Codex.

### Primeira chamada

Depois de conectar, experimente perguntar:

> **Quais linhas estão ativas na minha empresa?**

Se o ChatGPT retornar suas linhas, a conexão está funcionando.

Para mais exemplos, consulte [O que você pode fazer](/mcp-guide/use-cases).

***

## Microsoft Copilot

> [!NOTE]
>
> **Antes de começar**
>
> Você precisa ter acesso ao **Microsoft Copilot Studio** e um agente criado.
>
> Depois de configurado e publicado, o agente pode ser disponibilizado para outros usuários da sua organização. Nesse caso, eles não precisam configurar o MCP novamente: basta utilizar o agente que foi disponibilizado e concluir a autenticação quando solicitada.

### Adicione o MCP da Salvy

1. Abra o agente que você deseja configurar no Copilot Studio.

2. Acesse **Tools**.

3. Selecione **Add a tool**.

4. Selecione **New tool**.

5. Escolha **Model Context Protocol**.

6. Preencha as informações do servidor:

   * **Server name:** `Salvy`
   * **Server description:** `Acesse e gerencie sua operação de telecom da Salvy.`
   * **Server URL:** `https://mcp.salvy.com.br/mcp`
   * **Logo:** envie o ícone da Salvy.

   Baixar a logo Salvy
   PNG · 512×512 · 30 KB

7. Em **Authentication**, selecione **OAuth 2.0**.

8. Em **OAuth 2.0 authentication type**, selecione **Dynamic discovery**.

9. Selecione **Create**.

O Copilot Studio encontrará automaticamente as informações necessárias para configurar a conexão.

### Crie a conexão

1. Depois de configurar o servidor, selecione **Next**.
2. Na tela **Add tool**, selecione **Create a new connection** para o MCP da Salvy.
3. Conclua o processo de autenticação quando solicitado.
4. Depois de criar a conexão, selecione **Add to agent**.

O MCP da Salvy será adicionado ao seu agente e suas ferramentas ficarão disponíveis no Copilot Studio.

### Compartilhe o agente

Depois de configurar o MCP da Salvy, você pode publicar e compartilhar o agente com os usuários da sua organização.

Os usuários que utilizarem o agente podem precisar autenticar sua própria conta Salvy. Nesse caso, cada pessoa acessará a Salvy de acordo com as permissões da sua própria conta.

### Primeira chamada

Depois de conectar, experimente perguntar ao seu agente:

> **Quais linhas estão ativas na minha empresa?**

Se o Copilot Studio retornar suas linhas, a conexão está funcionando.

Para mais exemplos, consulte [O que você pode fazer](/mcp-guide/use-cases).

***

## Cursor e outros agentes compatíveis com MCP

Você pode conectar o **Cursor** e qualquer outro agente, aplicação ou ferramenta própria que ofereça suporte a MCP. Como o fluxo de configuração varia de acordo com o cliente, use as configurações de MCP do seu agente (ou a documentação dele) e informe os dados do servidor da Salvy:

* **Nome:** `Salvy`
* **URL do MCP:** `https://mcp.salvy.com.br/mcp`
* **Transporte:** Streamable HTTP. O MCP da Salvy não utiliza `stdio` nem o transporte legado de `SSE`.
* **Autenticação:** `OAuth`, para conectar um agente em nome de um usuário, ou `API Key`, para conectar um agente ou integração em nome de uma empresa. Veja os detalhes em [Autenticação](/mcp-guide/getting-started#autenticação).
* **Logo:** se o seu agente permitir um ícone personalizado, envie o ícone da Salvy.

  Baixar a logo Salvy
  PNG · 512×512 · 30 KB

### Cadastrar a Salvy como conector na sua plataforma

Se a sua plataforma oferece conectores aos seus usuários, use os dados abaixo para cadastrar a Salvy no catálogo. Cada usuário conecta a própria conta Salvy por `OAuth` e acessa apenas o que suas permissões na Salvy permitem.

* **Título:** `Salvy`
* **Descrição curta:** `Acesse e gerencie suas linhas e equipamentos da Salvy.`
* **Categoria:** Comunicação, Produtividade
* **Site:** `https://salvy.com.br`
* **Documentação:** `https://docs.salvy.com.br/mcp-guide`
* **Política de privacidade:** `https://salvy.com.br/politica-de-privacidade`
* **Suporte:** `contato@salvy.com.br`
* **Logo:**

Baixar a logo Salvy
PNG · 512×512 · 30 KB

Baixar a logo Salvy
SVG · vetorial · 4 KB

**Descrição:**

```text theme={null}
A Salvy leva a gestão de telefonia corporativa para dentro dos fluxos de trabalho da sua empresa. Com o MCP, conecte seu agente de IA à operação da Salvy para investigar consumo, entender custos, consultar faturas e portabilidades e gerenciar linhas e equipamentos usando linguagem natural.

O que você pode fazer

Investigar sua operação. Consulte linhas, consumo de dados, colaboradores e centros de custo para entender o que está acontecendo com seu parque de telefonia.
Analisar custos. Consulte faturas e estimativas para acompanhar os gastos com telefonia e investigar o consumo da empresa.
Agir sobre suas linhas. Adicione dados, altere planos, bloqueie ou desbloqueie linhas e acompanhe portabilidades.
Organizar seu parque. Consulte e organize linhas por grupos, colaboradores e centros de custo.
Cuidar dos equipamentos. Veja quem está com cada notebook ou celular, acompanhe os termos de responsabilidade pendentes e cadastre, edite ou arquive equipamentos e suas categorias.

Disponível para empresas clientes da Salvy. As ações disponíveis seguem as permissões da conta Salvy de cada usuário.
```

Se você está desenvolvendo uma integração própria, consulte os [Requisitos técnicos](/mcp-guide/technical-requirements).

Depois de conectar, faça uma [primeira chamada](/mcp-guide/getting-started#primeira-chamada) para verificar se a conexão está funcionando.

***

## Conectar com ajuda de uma IA

Peça para uma IA compatível com MCP configurar a conexão com a Salvy para você.

Copie o prompt abaixo e cole no seu agente de IA.

```text theme={null}
Ajude-me a configurar o MCP da Salvy no meu cliente de IA.

Servidor MCP:
https://mcp.salvy.com.br/mcp

Use o transporte Streamable HTTP.

Se tiver dúvidas, consulte a documentação do MCP da Salvy: https://docs.salvy.com.br/mcp-guide

Identifique qual cliente de IA estou usando e me oriente sobre a forma correta de adicionar o MCP da Salvy. Se o cliente permitir configuração automática, faça a configuração para mim.

Depois de configurar, confirme se a conexão com o MCP da Salvy foi concluída.
```

***

## Problemas e soluções

> [accordion] Não consigo autorizar o MCP no Claude
>
> Se você não consegue concluir a autorização do MCP no Claude, verifique se está usando uma conta Salvy com acesso à empresa que deseja consultar ou gerenciar.
>
> O e-mail usado para entrar no Claude **não precisa ser o mesmo e-mail da sua conta Salvy**. Por exemplo, você pode estar conectado ao Claude com `joao@empresa.com.br` e autorizar o MCP na Salvy usando `joao@gmail.com`, desde que essa conta tenha as permissões necessárias.
>
> Durante a configuração, o Claude abrirá uma página da Salvy para autorizar o acesso. É nessa etapa que você deve entrar com a conta Salvy correta.
>
> **Para resolver:**
>
> 1. Na página de autorização, confirme qual conta está conectada à **Salvy**.
> 2. Certifique-se de que essa conta possui acesso à empresa que deseja utilizar.
> 3. Se necessário, saia da conta Salvy atual e entre com a conta correta.
> 4. Tente realizar a conexão novamente.
>
> Se você não conseguir conectar a Salvy, verifique também se tem permissão para adicionar conectores na sua organização do Claude. Em algumas organizações, essa configuração é restrita a administradores.

> [accordion] O MCP não aparece no meu agente de IA
>
> A forma de conectar o MCP pode variar de acordo com o agente de IA, o plano e as configurações da sua conta.
>
> **No ChatGPT,** conecte o [plugin da Salvy](https://chatgpt.com/plugins/plugin_asdk_app_6acfc8ae0b6c8191a5bf025272ebce02). Em workspaces Business e Enterprise, um administrador pode precisar liberá-lo antes.
>
> **No Claude,** conecte a Salvy pelo [diretório de conectores](https://claude.ai/directory/salvy). A possibilidade de adicionar um conector pode depender das permissões da organização.
>
> **No Microsoft Copilot Studio,** o MCP é adicionado como uma ferramenta de um agente no Copilot Studio.
>
> **No Codex e no Cursor,** o MCP é adicionado nas configurações de servidores MCP do próprio cliente. Consulte a [seção sobre outros agentes](#cursor-e-outros-agentes-compatíveis-com-mcp).
>
> Se você não encontrar uma opção para adicionar ou conectar um servidor MCP, verifique:
>
> 1. Se o seu agente de IA oferece suporte a MCP.
> 2. Se o recurso está disponível no seu plano ou conta.
> 3. Se você está utilizando uma versão compatível do cliente.
> 4. Se você tem permissão para adicionar um servidor ou aplicativo MCP.
> 5. Se a opção está habilitada nas configurações do cliente ou do workspace.
>
> Se o aplicativo ou conector já tiver sido disponibilizado pela sua organização, talvez você só precise selecioná-lo e autorizar sua própria conta Salvy, sem configurar o MCP novamente.

> [accordion] Não consigo concluir a autenticação
>
> Se a autenticação não for concluída, verifique se você está usando a conta Salvy correta e se ela possui acesso à empresa que deseja consultar ou gerenciar.
>
> Durante a autenticação, o MCP utiliza as permissões da sua conta Salvy para determinar quais informações e operações podem ser acessadas.
>
> **Para resolver:**
>
> 1. Verifique qual conta Salvy está sendo utilizada na autorização.
> 2. Confirme se essa conta possui acesso à empresa que você deseja consultar.
> 3. Se você tiver mais de uma conta Salvy, saia da conta atual e entre com a conta que possui as permissões necessárias.
> 4. Tente realizar a autenticação novamente.
>
> Se o problema persistir, verifique se o seu agente de IA já possui uma conexão com o MCP da Salvy usando outra conta. Nesse caso, pode ser necessário remover ou substituir a conexão existente antes de tentar novamente.

> [accordion] Meu agente não encontra as ferramentas da Salvy
>
> Depois de conectar o MCP da Salvy, seu agente deve conseguir acessar as ferramentas disponíveis no servidor.
>
> Se o agente não encontrar ou não conseguir utilizar as ferramentas da Salvy, verifique:
>
> 1. Confirme se a conexão com o MCP da Salvy foi concluída corretamente.
> 2. Verifique se o MCP da Salvy está habilitado no agente ou na conversa que você está utilizando.
> 3. Se o cliente oferecer uma opção para atualizar ou redescobrir as ferramentas, execute essa etapa.
> 4. Se necessário, atualize ou reinicie o cliente de IA e tente novamente.
> 5. Tente iniciar uma nova conversa e peça ao agente para consultar alguma informação da Salvy.
>
> **Se o agente encontrar as ferramentas, mas uma operação específica não puder ser realizada**, o problema pode estar relacionado às permissões da sua conta ou ao tipo de operação. Nesse caso, consulte a mensagem retornada pelo agente para entender o que precisa ser ajustado.

> [accordion] Meu agente não consegue realizar uma ação
>
> Algumas operações do MCP da Salvy dependem das permissões da sua conta e podem exigir uma confirmação antes de serem executadas.
>
> Se o agente não conseguir realizar uma ação:
>
> 1. **Confirme se sua conta possui permissão para realizar a operação.**\
>    No caso de conexões feitas com OAuth, o agente utiliza as permissões que você já possui na Salvy.
> 2. **Verifique o resultado da operação.**\
>    Algumas operações podem ser processadas por etapas ou retornar resultados diferentes para cada linha. Confira se a ação foi concluída antes de tentar executá-la novamente.
> 3. **Confira se todas as informações necessárias foram fornecidas.**\
>    Algumas operações precisam de informações específicas, como a empresa, as linhas ou outros identificadores. Seu agente pode consultar essas informações antes de realizar a ação.
> 4. **Confira a mensagem retornada pelo agente.**\
>    Ela pode indicar se a operação não está disponível para sua conta, se falta alguma informação ou se existe outra condição que impede a execução.
>
> O agente pode solicitar sua confirmação antes de executar uma operação, mas isso depende do comportamento do cliente de IA. A confirmação não substitui a autorização: a operação só pode ser realizada se a conexão tiver as permissões necessárias.
>
> Se a ação que você precisa realizar não estiver disponível no MCP, peça ao seu agente para utilizar `submit_mcp_feedback`. Assim, você pode enviar esse pedido diretamente para o time responsável pelo MCP.

> [accordion] Uma ferramenta retorna um erro
>
> Se uma ferramenta retornar um erro, leia a mensagem apresentada pelo agente. Em muitos casos, ela indica o que precisa ser corrigido antes de tentar novamente.
>
> Verifique:
>
> 1. **Se as informações fornecidas estão corretas.**\
>    Alguns campos precisam seguir formatos específicos ou corresponder a informações existentes na sua conta.
> 2. **Se a operação pode ser realizada no estado atual.**\
>    Algumas ações só podem ser executadas quando determinadas condições são atendidas. Por exemplo, uma linha precisa estar em um estado compatível para ser bloqueada.
> 3. **Se sua conta possui permissão para realizar a operação.**\
>    A autorização da sua conexão é verificada quando a operação é executada.
> 4. **Se a operação respeita os limites da ferramenta.**\
>    Algumas operações possuem limites de quantidade de linhas, valores ou frequência.
> 5. **Se a operação foi concluída ou ainda está em processamento.**\
>    Se o resultado indicar que a solicitação foi aceita, mas ainda não foi concluída, consulte o estado da operação antes de tentar novamente.
>
> Depois de corrigir o problema indicado na mensagem, peça ao agente para tentar a operação novamente.
>
> Se o erro persistir, entre em contato com o suporte da Salvy informando **a operação que você tentou realizar e a mensagem de erro apresentada pelo agente**.

> [accordion] Quero conectar a outro agente de IA
>
> O MCP é um protocolo aberto que pode ser utilizado por diferentes agentes de IA, incluindo Cursor, Codex e ferramentas próprias da sua empresa. A forma de configurar a conexão, porém, pode variar de acordo com o agente que você utiliza.
>
> Se o seu agente oferece suporte a MCP, você pode pedir para ele orientar a configuração ou consultar a documentação específica da IA.
>
> De forma geral, você precisará informar os dados do servidor da Salvy:
>
> 1. Abra as configurações de MCP do seu agente.
> 2. Adicione um novo servidor MCP com o nome `Salvy` e, se o agente permitir, envie a [logo da Salvy](/assets/salvy-app-icon.png).
> 3. Informe a URL do servidor: `https://mcp.salvy.com.br/mcp`.
> 4. Conclua a autenticação quando solicitado.
> 5. Depois da autenticação, as ferramentas da Salvy estarão disponíveis para uso no agente.
>
> A configuração pode exigir etapas adicionais de acordo com o cliente, o método de autenticação e as permissões da sua conta. Nem todo cliente compatível com MCP oferece o mesmo fluxo de conexão.
>
> Depois de conectar, faça uma [primeira chamada](/mcp-guide/getting-started#primeira-chamada) para verificar se a conexão está funcionando.

> [accordion] Ainda preciso de ajuda
>
> Se você seguiu as orientações acima e ainda não conseguiu utilizar o MCP da Salvy, entre em contato com o **suporte da Salvy**.
>
> Para agilizar o atendimento, envie:
>
> * o cliente de IA que você está utilizando;
> * a operação que estava tentando realizar;
> * a mensagem de erro apresentada pelo agente, se houver;
> * e, se possível, uma captura de tela do problema.
>
> Com essas informações, nossa equipe poderá investigar o que aconteceu e ajudar você a concluir a configuração ou realizar a operação.


# Entenda o MCP
Source: https://docs.salvy.com.br/mcp-guide/overview

Use seu agente de IA para consultar e gerenciar linhas, faturas, colaboradores e equipamentos da Salvy em linguagem natural.

> [!WARNING]
>
> **Antes de começar**
>
> Para usar o MCP da Salvy, você precisa ter uma conta ativa na Salvy e permissão para acessar a empresa que deseja consultar ou gerenciar.

## O que é o MCP da Salvy

O MCP da Salvy permite que você use a Salvy diretamente pelo seu agente de IA, no ambiente onde já trabalha.

Em vez de abrir o Dashboard da Salvy sempre que precisar consultar uma informação ou realizar uma operação, você pode conversar com seu agente e pedir que ele faça isso por você.

Assim, você pode levar a Salvy para diferentes fluxos de trabalho, como conversas, ferramentas internas e automações, sem precisar substituir as ferramentas que sua empresa já utiliza.

O MCP é um protocolo aberto, e o MCP da Salvy pode ser usado por **qualquer agente de IA ou aplicação compatível com MCP**: Claude, ChatGPT e Codex, Cursor, Microsoft Copilot ou uma ferramenta própria da sua empresa. Consulte as [Integrações](/mcp-guide/integrations) para ver como conectar.

***

## Como funciona na prática

Quando você faz um pedido ao seu agente de IA, ele entende o que você precisa e consulta o MCP da Salvy para encontrar as informações ou realizar a operação.

Por exemplo, se você pedir:

> **Quais linhas mais consumiram dados este mês?**

O agente pode consultar os dados da sua operação, analisar os resultados e mostrar para você o que merece atenção.

De forma simplificada:

> [!TIP]
>
> Você faz um pedido → o agente entende o que precisa → consulta ou realiza a operação na Salvy → apresenta o resultado


# Segurança & Governança
Source: https://docs.salvy.com.br/mcp-guide/security

Autenticação, autorização e controles que protegem o acesso do seu agente de IA à operação da Salvy.

## Autenticação e autorização

O acesso ao MCP da Salvy é protegido por autenticação e autorização. A autenticação identifica a conexão utilizada pelo agente, enquanto a autorização determina quais informações e operações essa conexão pode acessar.

O MCP utiliza as permissões associadas à conexão para verificar cada solicitação antes de permitir o acesso ou a execução de uma operação.

No caso de conexões feitas em nome de um usuário, as permissões são baseadas nos acessos que esse usuário possui na Salvy. Em conexões feitas com API Key, os *scopes* associados à chave determinam quais informações e operações podem ser utilizadas.

Isso significa que **conectar um agente ao MCP não amplia as permissões existentes**: o agente só pode acessar ou realizar aquilo que a conexão está autorizada a fazer.

Para saber como configurar cada forma de autenticação, consulte [Autenticação](/mcp-guide/getting-started#autenticação) na seção **Comece a usar**.

***

## Tipos de operação

As ferramentas do MCP da Salvy são classificadas de acordo com o tipo de operação que realizam. Essa classificação ajuda a entender o impacto de cada ação:

**Leitura:** operações que apenas consultam informações da sua conta, sem alterar os dados.

**Escrita:** operações que modificam informações ou configurações da sua operação, como organizar linhas ou alterar seu estado.

**Cobrança:** operações que podem gerar uma cobrança, como criar uma linha, adicionar dados ou alterar um plano.

**Destrutiva:** operações que podem causar uma alteração significativa ou difícil de reverter, como realizar uma portabilidade. Essas operações possuem regras e controles específicos para reduzir o risco de uma alteração indevida.

Essas classificações descrevem o impacto das operações, mas não determinam, por si só, se o agente solicitará uma confirmação antes de executá-las.

> [!WARNING]
>
> **Importante:** O agente pode apresentar os detalhes de uma operação e solicitar sua confirmação antes de continuar. Essa etapa depende do comportamento do agente utilizado e não substitui a autorização do MCP: mesmo após a confirmação, a operação só poderá ser executada se a conexão tiver as permissões necessárias.

***

## Auditoria e segurança

As operações realizadas através do MCP da Salvy são identificadas e registradas para que sua empresa tenha visibilidade sobre o uso do MCP e possa rastrear o que foi realizado por um agente.

As operações realizadas pelo MCP são diferenciadas das operações realizadas pelo Dashboard. Elas são registradas no histórico das linhas com o nome do usuário que realizou o pedido e a identificação do cliente de IA utilizado, como (via Claude) ou (via ChatGPT).

### Proteção das informações

As permissões da conexão são verificadas pelo MCP antes de permitir o acesso a informações ou a execução de operações

> [!WARNING]
>
> **Atenção ao tratamento de dados pelo seu agente de IA**
>
> As informações consultadas pelo MCP são disponibilizadas ao agente de IA que você está utilizando para atender à sua solicitação. Por isso, antes de conectar o MCP, avalie também a política de proteção, retenção e uso de dados do seu agente de IA e as configurações de privacidade da sua conta.
>
> A Salvy controla o acesso às informações dentro do MCP, mas o tratamento dessas informações pelo agente segue as políticas e configurações do serviço que você escolheu utilizar.

### Segurança das operações

O MCP valida as informações recebidas antes de executar uma operação e aplica controles adicionais às ações que podem gerar impacto financeiro ou operacional.

### Monitoramento

As operações realizadas através do MCP são registradas nos mecanismos de auditoria e monitoramento da Salvy.

Esses registros ajudam a investigar problemas, identificar a origem de uma operação e manter a rastreabilidade sobre o uso do MCP.


# Requisitos técnicos
Source: https://docs.salvy.com.br/mcp-guide/technical-requirements

Requisitos técnicos do MCP da Salvy, transporte, autenticação e o catálogo completo de ferramentas.

Se você quer conectar um agente, aplicação ou ferramenta própria ao MCP da Salvy, esta página reúne os requisitos técnicos e o catálogo das ferramentas disponíveis.

[A documentação principal](/mcp-guide/overview) explica o MCP de forma mais prática. Aqui você encontra os detalhes para quem precisa **configurar, desenvolver ou validar uma integração**.

## Antes de começar

Para usar o MCP da Salvy, você precisa de:

* uma conta ativa na Salvy;
* acesso às empresas que deseja consultar ou gerenciar;
* um cliente ou aplicação compatível com **MCP via Streamable HTTP**;
* uma forma de autenticação válida;
* permissões para realizar as operações desejadas.

O MCP da Salvy está disponível em:

```
https://mcp.salvy.com.br/mcp
```

O endpoint utiliza **Streamable HTTP** e aceita requisições `POST`.

***

## Compatibilidade

O MCP da Salvy utiliza o transporte **Streamable HTTP**, permitindo que clientes compatíveis com MCP se conectem diretamente ao servidor.

A implementação atual:

* utiliza `POST` para comunicação com o servidor;
* não utiliza `stdio`;
* não utiliza o transporte legado de `SSE`;
* não mantém uma sessão entre requisições;
* não exige `Mcp-Session-Id`.

A compatibilidade final também depende do cliente de IA ou aplicação utilizado para fazer a conexão.

***

## Descoberta de ferramentas

Depois de autenticar, o cliente pode consultar as ferramentas disponíveis no servidor usando `tools/list`.

As ferramentas são organizadas em dois grandes grupos:

* **Leitura:** consulta de informações da operação da Salvy;
* **Escrita:** ações que alteram dados ou podem gerar efeitos na conta.

O servidor informa as ferramentas disponíveis, seus parâmetros e suas descrições para que o cliente possa decidir qual utilizar.

### Importante

A disponibilidade de uma ferramenta na descoberta **não significa que qualquer usuário possa executá-la**.

Autenticação, permissões e regras da operação são verificadas quando a ferramenta é chamada.

***

## Catálogo de ferramentas

Se você quer saber exatamente o que o MCP da Salvy pode fazer, este é o lugar.

### Leitura

| Ferramenta | O que faz |
| - | - |
| `list_companies` | Lista as empresas às quais o usuário tem acesso. |
| `list_phone_accounts` | Lista linhas e permite filtrar o parque por diferentes critérios. |
| `get_phone_account` | Consulta os detalhes de uma linha específica. |
| `get_phone_account_timeline` | Consulta o histórico de eventos de uma linha. |
| `get_phone_account_usage` | Consulta o consumo das linhas, mês a mês ou dia a dia. |
| `list_sim_card_shipments` | Lista os envios de chip físico e mostra onde está cada chip. |
| `get_sim_card_shipment` | Consulta um envio de chip, com rastreio, endereço e as linhas do envio. |
| `list_phone_account_area_codes` | Lista os DDDs com número disponível para linha nova ou número virtual. |
| `list_phone_account_plans` | Lista os planos que a empresa pode contratar para suas linhas. |
| `get_phone_account_portability` | Consulta o status de uma portabilidade de entrada. |
| `list_employees` | Lista colaboradores e permite localizar linhas associadas a eles. |
| `list_cost_centers` | Lista os centros de custo disponíveis. |
| `list_invoices` | Lista faturas das empresas às quais o usuário tem acesso. |
| `get_invoice` | Consulta os detalhes de uma fatura. |
| `get_invoice_cost_by_cost_center` | Consulta a distribuição de custos por centro de custo. |
| `get_invoice_estimate` | Consulta uma estimativa dos custos do mês atual. |
| `list_assets` | Lista equipamentos e permite filtrar o parque por diferentes critérios. |
| `get_asset` | Consulta os detalhes de um equipamento, incluindo as informações técnicas do Salvy Link ou do Salvy MDM. |
| `get_asset_summary` | Resume o parque de equipamentos e aponta o que merece atenção. |
| `list_asset_statements` | Lista termos de responsabilidade e de devolução. |
| `list_asset_categories` | Lista as categorias de equipamentos. |
| `get_task` | Consulta o resultado de uma operação assíncrona. |

### Escrita

| Ferramenta | O que faz |
| - | - |
| `create_phone_accounts` | Cria novas linhas de telefonia. |
| `create_mobile_did_phone_accounts` | Cria números virtuais móveis para a API oficial da Meta e SMS, sem chip. |
| `replace_phone_account_sim_card` | Pede um chip físico novo para trocar o de uma linha, com envio pela Salvy. |
| `change_phone_account_sim_card` | Ativa um chip físico novo em uma linha, mantendo o número. |
| `change_phone_account_esim` | Gera um eSIM novo para uma linha com eSIM, mantendo o número. |
| `add_data_to_phone_accounts` | Adiciona dados às linhas selecionadas. |
| `change_phone_account_plan` | Altera o plano das linhas selecionadas. |
| `cancel_phone_accounts` | Cancela as linhas selecionadas. |
| `request_phone_account_portability` | Inicia uma portabilidade de entrada para uma linha. |
| `block_phone_accounts` | Bloqueia as linhas selecionadas. |
| `unblock_phone_accounts` | Desbloqueia linhas elegíveis. |
| `unschedule_phone_account_cancellations` | Desfaz agendamentos de cancelamento de linhas. |
| `update_phone_accounts` | Atualiza informações das linhas, como nome, colaborador, grupo, centro de custo e campos personalizados. |
| `create_phone_account_group` | Cria um grupo para organizar linhas. |
| `create_assets` | Cadastra novos equipamentos. |
| `update_assets` | Atualiza informações dos equipamentos, como situação, colaborador, local, categoria e campos personalizados, e arquiva ou desarquiva equipamentos. |
| `send_asset_statement` | Envia um termo de responsabilidade ou de devolução para assinatura do colaborador. |
| `create_asset_category` | Cria uma categoria de equipamentos. |
| `delete_asset_category` | Exclui uma categoria de equipamentos que não tenha equipamentos. |
| `submit_mcp_feedback` | Envia feedback sobre uma interação com o MCP. |

***

## Operações em lote

Algumas ferramentas do MCP da Salvy permitem realizar uma mesma operação em várias linhas ou equipamentos de uma só vez.

Os limites variam de acordo com a ferramenta:

#### Criação de linhas

* **Limite por chamada:** até 50 linhas.
* **Cota por empresa:** até 50 linhas em uma janela de 24 horas.
* **Disponibilidade:** a criação depende das condições de habilitação do MCP para a empresa.
* **Chip físico:** a linha pode usar um chip que já está com a empresa, informando o ICCID, ou pedir que a Salvy envie um chip novo.
* **Envio do chip:** o chip vai para o endereço cadastrado da empresa ou para o endereço informado no pedido. Linhas com o mesmo destinatário e endereço seguem no mesmo envio, e o envio não tem custo.
* **Ativação:** a linha com envio fica aguardando ativação até o chip chegar.
* **Disponibilidade do envio:** pedir o envio do chip pelo agente é liberado por empresa.

#### Criação de números virtuais móveis

* **Limite por chamada e cota:** os mesmos da criação de linhas, e as duas dividem a cota de 24 horas.
* **Estoque:** cada número sai do estoque da Salvy para o DDD pedido. Quando o DDD não tem números suficientes, o agente mostra os DDDs que têm.
* **Cobrança:** começa só quando o número recebe o primeiro SMS, de qualquer serviço (Meta, Instagram, Telegram, TikTok e outros).
* **Disponibilidade:** a mesma da criação de linhas.

#### Troca de chip

* **Limite por chamada:** uma linha.
* **Linhas:** só linha móvel ativa, ou eSIM ainda não instalado, como na troca de chip do painel. Uma linha bloqueada precisa ser desbloqueada antes.
* **Cobrança:** o chip novo tem a cobrança avulsa da tabela da empresa, mostrada no orçamento. O envio não tem custo.
* **Ativação:** a linha segue com o chip atual até o novo ser ativado, depois que ele chegar, pelo agente ou na troca de chip do painel.
* **Disponibilidade:** a mesma do envio de chip na criação de linhas.
* **Permissão:** pedir e ativar chip novo é só para administradores, como no painel.

#### Novo eSIM

* **Limite por chamada:** uma linha.
* **Linhas:** só linha com eSIM ativa, de operadora que emite eSIM, como no "Gerar novo eSIM" do painel. Enquanto o eSIM novo não for instalado, não dá para gerar outro.
* **Cobrança:** gerar um eSIM novo pelo agente não tem custo.
* **Instalação:** o eSIM anterior para de funcionar na hora. O novo é instalado pelo QR Code do "Instalar eSIM", na página da linha no painel, ou pelo e-mail que o agente pode enviar ao colaborador.
* **Permissão:** gerar eSIM novo é só para administradores, como no painel.

#### Atualização de linhas

* **Limite por chamada:** até 50 linhas.
* **Campos atualizáveis:** nome, centro de custo, colaborador, grupo e campos personalizados.
* **Nome da linha:** até 60 caracteres.
* **Atualização parcial:** somente os campos informados são alterados. O envio de `null` permite limpar um campo compatível com essa operação.

A ferramenta valida as linhas antes de iniciar as alterações. Depois dessa etapa, cada linha pode ter um resultado individual: aplicada, já estava no estado solicitado ou falhou.

#### Adição de dados

* **Limite por chamada:** até 25 linhas.
* **Limite de dados:** até 10 GB.

#### Alteração de plano

* **Limite por chamada:** até 25 linhas.

#### Cancelamento de linhas

* **Limite por chamada:** até 25 linhas.

#### Desagendamento de cancelamento

* **Limite por chamada:** até 25 linhas.

#### Bloqueio e desbloqueio

* **Bloqueio:** até 50 linhas por chamada.
* **Desbloqueio:** até 50 linhas por chamada.

#### Cadastro de equipamentos

* **Limite por chamada:** até 50 equipamentos.
* **Número de patrimônio:** obrigatório e único na empresa. A Salvy não gera um número: ele segue a numeração da própria empresa.
* **Tudo ou nada:** se algum equipamento for recusado, por exemplo por um número de patrimônio repetido ou um campo personalizado que a empresa não criou, nenhum é cadastrado.
* **Plano:** a empresa precisa ter um plano de gestão de equipamentos ativo.

#### Atualização de equipamentos

* **Limite por chamada:** até 50 equipamentos.
* **Campos atualizáveis:** situação, colaborador, local, categoria, dados de compra, garantia, campos personalizados e arquivamento.
* **Atualização parcial:** somente os campos informados são alterados. O envio de `null` limpa o campo.
* **Plano:** o mesmo exigido no cadastro.

A ferramenta valida os equipamentos antes de iniciar as alterações. Depois dessa etapa, cada equipamento pode ter um resultado individual: aplicado, já estava no estado solicitado ou falhou. O resultado também traz os valores anteriores de cada equipamento, que permitem desfazer a alteração.

#### Envio de termos

* **Limite por termo:** até 6 equipamentos, todos da mesma empresa.
* **Termo de responsabilidade:** todos os equipamentos precisam estar com o mesmo colaborador.
* **Novo envio:** cada chamada envia um novo e-mail ao colaborador.

### Como funciona o processamento

Cada ferramenta possui suas próprias regras de validação e processamento. Por isso, uma operação em lote pode ter resultados diferentes para cada linha ou equipamento.

Em algumas operações, todas as linhas são validadas antes de qualquer alteração ser aplicada. Depois dessa validação, porém, cada linha pode ser processada individualmente, e **uma falha em uma delas não significa necessariamente que as demais alterações serão desfeitas**.

O resultado pode indicar quais linhas foram atualizadas, quais já estavam no estado solicitado e quais não puderam ser processadas.

> [!WARNING]
>
> **Importante**
>
> Não considere uma operação concluída integralmente apenas porque a solicitação foi aceita. Confira o resultado retornado pelo agente e, quando necessário, consulte o estado final da operação.

***

## Resultados e estados

As ferramentas do MCP da Salvy podem retornar diferentes resultados, de acordo com o tipo de operação e o estado dos dados consultados.

Uma solicitação aceita não significa necessariamente que a operação foi concluída. Por exemplo, uma operação pode ter sido agendada ou continuar em processamento.

### Como interpretar os resultados

Entre os resultados possíveis, estão:

* **Operação aplicada:** a alteração foi realizada.
* **Operação já aplicada:** o estado solicitado já havia sido alcançado.
* **Operação agendada:** a execução foi programada para outro momento.
* **Resultado indisponível:** não há dados disponíveis para o período ou a consulta solicitada.
* **Falha na operação:** a ação não pôde ser concluída.

Os estados disponíveis variam conforme a ferramenta. Em operações realizadas sobre várias linhas, também pode haver resultados diferentes para cada linha processada.

### Consultar o resultado de uma operação

Algumas operações são assíncronas: a solicitação é aceita, mas o resultado final fica disponível posteriormente.

Ao consultar o resultado, verifique se a operação foi concluída e se houve linhas que não puderam ser processadas. Se necessário, utilize essas informações para decidir os próximos passos, evitando repetir uma ação que já tenha sido executada.

***

## Para desenvolvedores

Se você está construindo uma integração própria, recomendamos começar por:

1. conectar ao endpoint do MCP;
2. [configurar a autenticação](/mcp-guide/getting-started#autenticação);
3. executar `tools/list`;
4. selecionar uma ferramenta de leitura;
5. validar os parâmetros e o formato do resultado;
6. só depois habilitar operações de escrita.

Para uma primeira integração, prefira começar com ferramentas de consulta. Isso permite validar autenticação, descoberta e interpretação dos resultados antes de introduzir operações que alteram dados ou geram cobrança.

***

## Referência rápida

| Item | Valor |
| - | - |
| **Endpoint** | `https://mcp.salvy.com.br/mcp` |
| **Transporte** | Streamable HTTP |
| **Método** | `POST` |
| **Sessão** | Stateless |
| **Descoberta** | `tools/list` |
| **Autenticação** | OAuth ou API Key |
| **Capacidade MCP** | Tools |
| **Recursos MCP** | Não disponíveis atualmente |
| **Prompts MCP** | Não disponíveis atualmente |


# O que você pode fazer
Source: https://docs.salvy.com.br/mcp-guide/use-cases

Exemplos de perguntas e prompts prontos para usar o MCP da Salvy no dia a dia: consumo, custos, linhas, portabilidades e equipamentos.

## Peça para o seu agente…

### Entender o consumo de dados do meu parque de linhas

Você pode pedir ao seu agente para analisar o consumo de dados das linhas da sua empresa, identificar quais linhas mais consomem e destacar situações que merecem atenção.

Por exemplo:

> **Quais linhas estão consumindo mais dados este mês?**

O agente pode consultar o consumo das linhas, comparar os resultados e apresentar os principais destaques para você.

> [!NOTE]
>
> **Quer fazer uma análise mais específica?**
>
> Você pode combinar a pergunta com outros critérios da sua operação, como empresa, status ou centro de custo.
>
> Para entender em que dia o consumo disparou, peça o consumo dia a dia. Esse detalhamento vale para até 10 linhas por consulta e para os últimos 3 meses. Para um período maior, de até 12 meses, o agente consulta mês a mês.

#### Prompt

Copie o prompt abaixo e substitua os campos entre `[ ]`:

```text theme={null}
Analise o consumo de dados das minhas linhas.

**Empresa:** [NOME DA EMPRESA]

Mostre:

- quais linhas tiveram maior consumo;
- quais linhas estão próximas do limite do plano;
- quais padrões ou situações merecem minha atenção.

Organize os resultados por ordem de prioridade e explique brevemente por que cada item merece atenção. Quero um relatório enxuto e conciso com uma lista de melhorias.
```

***

### Entender os meus custos com telefonia

Você pode pedir ao seu agente para consultar os custos da sua operação de telefonia, comparar períodos e entender como os gastos estão distribuídos entre empresas ou centros de custo.

Por exemplo:

> **Quanto gastamos com telefonia nos últimos 6 meses?**

O agente pode consultar os custos da operação e organizar os resultados para ajudar você a entender como os gastos estão distribuídos e como eles evoluíram ao longo do tempo.

> [!WARNING]
>
> **Quer entender de onde vêm os seus gastos?**
>
> Para analisar os custos por centro de custo ou empresa, essas informações precisam estar configuradas corretamente na sua conta da Salvy.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Analise os meus custos com telefonia.

**Empresa:** [NOME DA EMPRESA]
**Período:** [PERÍODO]
**Agrupamento:** [EMPRESA OU CENTRO DE CUSTO]

Mostre:

- o custo total no período;
- como os custos estão distribuídos entre [CRITÉRIO];
- como os gastos evoluíram ao longo do período;
- quais áreas ou períodos merecem minha atenção.

Destaque as principais variações e explique brevemente o que os dados mostram.
```

***

### Organizar meu parque de linhas

Você pode pedir ao seu agente para analisar o seu parque de linhas e organizar linhas com perfis de uso semelhantes. Isso pode ajudar a estruturar a operação e facilitar consultas e ações em massa.

Por exemplo, você pode pedir ao agente para analisar o consumo das linhas, identificar padrões de uso e propor uma organização que faça sentido para sua operação.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero organizar meu parque de linhas.

**Empresa:** [NOME DA EMPRESA]

Analise o consumo de dados das minhas linhas e identifique perfis de uso semelhantes.

Com base nessa análise:

- proponha grupos que façam sentido para a minha operação;
- explique brevemente o perfil de cada grupo;
- associe cada linha ao grupo correspondente.

**Antes de fazer qualquer alteração, me mostre a organização proposta e peça minha confirmação.**
```

***

### Refletir uma mudança da empresa nas minhas linhas

Você pode pedir ao seu agente para atualizar sua operação de telefonia quando algo mudar na empresa, como a saída de um colaborador, uma mudança de área ou a entrada de uma nova pessoa.

Por exemplo:

> **O João saiu da empresa. Atualize a linha dele de acordo com essa mudança.**

O agente pode consultar as informações necessárias para identificar a linha relacionada ao colaborador e realizar as operações disponíveis para refletir a mudança na Salvy.

> [!WARNING]
>
> **O agente precisa ter acesso às informações da mudança.**
>
> O MCP da Salvy conhece as informações disponíveis na sua conta, mas não sabe automaticamente tudo o que acontece na sua empresa. Se a informação sobre a mudança estiver em outro sistema, o agente pode precisar receber esse contexto por meio de outra integração ou ferramenta.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Preciso atualizar minha operação de telefonia por causa de uma mudança na empresa.

**Empresa:** [NOME DA EMPRESA]
**Colaborador:** [NOME DO COLABORADOR]
**Mudança:** [DESCREVA O QUE ACONTECEU]

Consulte a operação da Salvy e identifique quais mudanças precisam ser feitas na linha desse colaborador para refletir essa alteração.

Antes de realizar qualquer operação, me mostre o que será alterado e peça minha confirmação.
```

***

### Criar uma nova linha

Você pode pedir ao seu agente para criar uma nova linha na Salvy quando precisar disponibilizar conexão para uma nova pessoa ou uma nova necessidade da empresa.

Por exemplo:

> **Crie uma nova linha para a Maria.**

O agente pode consultar as informações necessárias para realizar a criação e, antes de concluir a operação, apresentar os detalhes para sua confirmação.

Se a linha for de chip físico e a pessoa ainda não tiver o chip, o agente pode pedir que a Salvy envie um, sem custo, para o endereço da empresa ou para outro endereço que você informar. A linha fica aguardando ativação até o chip chegar.

> [!WARNING]
>
> **Para criar uma linha, você precisa ter permissão para realizar essa operação.**
>
> A disponibilidade e as condições da criação também dependem das informações e configurações da sua operação na Salvy.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero criar uma nova linha na Salvy.

**Empresa:** [NOME DA EMPRESA]

**Colaborador:** [NOME DO COLABORADOR]

**Produto/plano:** [PRODUTO OU PLANO, SE SOUBER]

**Tipo de chip:** [eSIM OU CHIP FÍSICO]

**Entrega do chip:** [ENDEREÇO DA EMPRESA, OUTRO ENDEREÇO OU NÃO PRECISA, SE FOR CHIP FÍSICO]

Verifique as informações necessárias para criar essa linha.

Se faltar alguma informação, me pergunte antes de prosseguir.

Quando estiver tudo pronto, me mostre os detalhes da linha que será criada e peça minha confirmação antes de realizar a operação.
```

***

### Criar um número virtual para a API da Meta

Você pode pedir ao seu agente para criar um número virtual móvel, sem chip, para usar na API oficial da Meta ou para receber SMS.

Por exemplo:

> **Crie um número virtual com DDD 11 para o suporte usar na API da Meta.**

O agente mostra o valor mensal antes de criar e, depois da sua confirmação, retorna o número reservado. A cobrança só começa quando o número recebe o primeiro SMS, de qualquer serviço. O agente também pode ler o código de verificação que o número receber por SMS.

> [!WARNING]
>
> **Para criar um número virtual, você precisa ter permissão para realizar essa operação.**
>
> Se o DDD pedido estiver sem números disponíveis, o agente mostra os DDDs que têm.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero criar um número virtual móvel na Salvy.

**Empresa:** [NOME DA EMPRESA]

**DDD:** [DDD DO NÚMERO]

**Para quem ou para quê:** [COLABORADOR OU USO DO NÚMERO, COMO SUPORTE OU VENDAS]

Verifique as informações necessárias para criar esse número.

Se faltar alguma informação, me pergunte antes de prosseguir.

Quando estiver tudo pronto, me mostre o valor mensal e peça minha confirmação antes de criar o número.
```

***

### Trocar o chip de uma linha

Você pode pedir ao seu agente um chip físico novo para uma linha, quando o chip foi perdido, quebrou ou quando a eSIM não pôde ser instalada no aparelho.

Por exemplo:

> **A Maria perdeu o chip. Peça um novo para a linha dela.**

O agente mostra o valor do chip novo e para onde ele vai antes de pedir. A linha continua com o número e com o chip atual até o novo ser ativado. Quando ele chegar, o agente acompanha o envio e ativa o chip novo com o ICCID impresso nele.

> [!WARNING]
>
> **Pedir e ativar chip novo é só para administradores da empresa, como no painel.**
>
> Só é possível pedir um chip novo quando a linha não tem outro envio em andamento.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero trocar o chip de uma linha da Salvy.

**Empresa:** [NOME DA EMPRESA]

**Linha ou colaborador:** [NÚMERO DA LINHA OU NOME DO COLABORADOR]

**Motivo:** [CHIP PERDIDO, CHIP COM DEFEITO OU ESIM QUE NÃO FUNCIONOU]

**Entrega do chip:** [ENDEREÇO DA EMPRESA OU OUTRO ENDEREÇO]

Verifique as informações necessárias para pedir o chip novo.

Quando estiver tudo pronto, me mostre o valor e o endereço de entrega e peça minha confirmação antes de realizar a operação.
```

***

### Gerar um novo eSIM

Você pode pedir ao seu agente um eSIM novo para uma linha, quando o colaborador trocou de aparelho, apagou o eSIM ou perdeu o celular.

Por exemplo:

> **O João trocou de celular. Gere um eSIM novo para a linha dele.**

O agente confirma antes de gerar, pois o eSIM anterior para de funcionar na hora. A linha continua com o mesmo número, e o eSIM novo pode ser instalado pelo QR Code do "Instalar eSIM", na página da linha no painel, ou pelo e-mail que o agente envia ao colaborador.

> [!WARNING]
>
> **Gerar eSIM novo é só para administradores da empresa, como no painel.**
>
> Enquanto o eSIM novo não for instalado, não é possível gerar outro.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero gerar um eSIM novo para uma linha da Salvy.

**Empresa:** [NOME DA EMPRESA]

**Linha ou colaborador:** [NÚMERO DA LINHA OU NOME DO COLABORADOR]

**Instalação:** [ENVIAR E-MAIL AO COLABORADOR OU INSTALAR PELO PAINEL]

Verifique se a linha pode receber um eSIM novo e peça minha confirmação antes de realizar a operação.
```

***

### Acompanhar o envio do chip

Você pode pedir ao seu agente para acompanhar os chips físicos que a Salvy está enviando para a sua empresa, ou o chip de uma linha específica.

Por exemplo:

> **Quais chips ainda estão a caminho?**

O agente pode mostrar onde está cada chip, a previsão de entrega e o link de rastreio da transportadora. Quando o chip está aguardando retirada, ele também indica o local e a rota.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero acompanhar o envio dos chips da Salvy.

**Empresa:** [NOME DA EMPRESA]

**Linha ou colaborador:** [NOME DA LINHA OU DO COLABORADOR, SE FOR UM ENVIO ESPECÍFICO]

Me mostre os envios que ainda não foram entregues, com a situação de cada um, a previsão de entrega e o link de rastreio.

Se algum envio estiver atrasado, aguardando retirada ou com falha na entrega, destaque isso para mim.
```

***

### Fazer um diagnóstico do parque de linhas

Você pode pedir ao seu agente para analisar o seu parque de linhas e identificar padrões, oportunidades e situações que merecem atenção.

Em vez de consultar uma informação específica, o agente pode combinar diferentes dados da sua operação, como consumo, planos, custos e status das linhas, para ajudar você a entender a situação do seu parque.

Por exemplo:

> **Faça um diagnóstico do meu parque de linhas e me diga o que merece minha atenção.**

O agente pode identificar linhas ou situações que se destacam, explicar os principais pontos encontrados e indicar o que vale investigar ou revisar.

> [!NOTE]
>
> **Um diagnóstico depende das informações disponíveis para o agente.**
>
> O MCP da Salvy fornece informações sobre a sua operação, mas algumas recomendações podem depender de contexto que não está na Salvy, como políticas internas, função do colaborador ou necessidades específicas de uma área.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Faça um diagnóstico do meu parque de linhas.

**Empresa:** [NOME DA EMPRESA]

Analise os dados disponíveis sobre minhas linhas, incluindo consumo, planos, custos e status.

Identifique:

- linhas ou situações que merecem atenção;
- padrões de consumo ou custo que se destacam;
- possíveis oportunidades de otimização;
- situações que valem ser investigadas.

Organize os resultados por prioridade e explique brevemente o motivo de cada recomendação.

Não faça nenhuma alteração na operação. Apenas apresente o diagnóstico e as recomendações.
```

***

### Gerenciar consumo

Você pode pedir ao seu agente para analisar o consumo de dados das linhas e, quando necessário, adicionar dados a uma ou várias linhas.

Por exemplo:

> **Adicione até 5 GB às linhas que estão próximas de atingir o limite do plano.**

O agente pode identificar as linhas correspondentes, consultar o consumo e preparar a operação. Como a adição de dados pode gerar uma cobrança, ele pode apresentar os detalhes e solicitar sua confirmação antes de executar a operação.

> [!WARNING]
>
> **Adicionar dados pode gerar uma cobrança.**
>
> A operação só é realizada se a conexão tiver permissão para executá-la. O agente pode solicitar sua confirmação antes de continuar e também pode precisar de informações adicionais para identificar corretamente as linhas que devem receber os dados.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero adicionar dados às minhas linhas.

**Empresa:** [NOME DA EMPRESA]

(opcional) **Linhas ou colaboradores:** [QUEM DEVE RECEBER OS DADOS]

**Quantidade de dados:** [QUANTIDADE DE GB POR LINHA]

Consulte o consumo atual dessas linhas e identifique quais estão próximas de atingir o limite do plano.

Para as linhas que atenderem a esse critério, prepare a adição de [QUANTIDADE DE GB].

Antes de realizar a operação, me mostre:

- quais linhas serão afetadas;
- quanto de dados será adicionado a cada uma;
- o valor da operação.

Peça minha confirmação antes de executar.
```

***

### Saber com quem está cada equipamento

Você pode pedir ao seu agente para consultar o parque de equipamentos da sua empresa: quem está com cada notebook ou celular, quais estão em estoque e onde cada um está guardado.

Por exemplo:

> **Quais equipamentos estão com a Maria?**

O agente pode buscar pelo número de patrimônio, pelo número de série, pelo modelo ou pelo nome de quem está com o equipamento, e apresentar os detalhes de cada um.

> [!NOTE]
>
> **Quer as informações técnicas de um equipamento?**
>
> Nos equipamentos com Salvy Link ou Salvy MDM, o agente também consulta as informações técnicas, como processador, memória, discos e sistema operacional.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero saber como está o parque de equipamentos da minha empresa.

**Empresa:** [NOME DA EMPRESA]

(opcional) **Filtro:** [CATEGORIA, MODELO OU COLABORADOR]

Mostre:

- quais equipamentos estão em uso e com quem;
- quais estão em estoque e onde estão guardados;
- quais estão em manutenção ou em outra situação que mereça atenção.

Organize o resultado por categoria.
```

***

### Recuperar os equipamentos de quem saiu da empresa

Você pode pedir ao seu agente para encontrar os equipamentos que ainda estão com colaboradores desligados e organizar a devolução.

Por exemplo:

> **Quais equipamentos ainda estão com pessoas que saíram da empresa?**

O agente pode identificar esses equipamentos e, se você pedir, enviar o termo de devolução para o colaborador assinar e atualizar a situação de cada equipamento quando ele voltar.

> [!WARNING]
>
> **Enviar um termo manda um e-mail para o colaborador.**
>
> O termo é enviado por e-mail para assinatura eletrônica, e cada envio manda um novo e-mail. Peça ao agente para confirmar com você antes de enviar.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero recuperar os equipamentos de quem saiu da empresa.

**Empresa:** [NOME DA EMPRESA]

Liste os equipamentos que ainda estão com colaboradores desligados, com o número de patrimônio, o modelo e quem está com cada um.

Depois, para cada colaborador, me pergunte se devo enviar o termo de devolução.

Não envie nenhum termo nem altere nenhum equipamento sem a minha confirmação.
```

***

### Fazer um diagnóstico do parque de equipamentos

Você pode pedir ao seu agente para analisar o parque de equipamentos e apontar o que merece atenção.

Por exemplo:

> **Faça um diagnóstico dos meus equipamentos e me diga o que merece atenção.**

O agente pode resumir os equipamentos por situação e categoria e destacar garantias vencidas ou perto de vencer, equipamentos sem colaborador, computadores com o Salvy Link sem reportar há mais de 30 dias e termos de responsabilidade que ainda não foram assinados.

> [!NOTE]
>
> **O diagnóstico usa as informações cadastradas.**
>
> Garantias, preços e datas de compra só entram na análise quando estão cadastrados nos equipamentos. As informações técnicas dependem do Salvy Link ou do Salvy MDM.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Faça um diagnóstico do meu parque de equipamentos.

**Empresa:** [NOME DA EMPRESA]

Identifique:

- garantias vencidas ou que vencem nos próximos 30 dias;
- equipamentos sem colaborador e equipamentos com colaboradores desligados;
- computadores com Salvy Link que não reportam há mais de 30 dias;
- termos de responsabilidade que ainda não foram assinados.

Organize os resultados por prioridade e explique brevemente por que cada item merece atenção.

Não faça nenhuma alteração. Apenas apresente o diagnóstico e as recomendações.
```

***

### Cadastrar e atualizar equipamentos

Você pode pedir ao seu agente para cadastrar equipamentos novos, por exemplo a partir de uma lista de compras, e para atualizar os que já existem: quem está com cada um, a situação, o local, a categoria ou os campos personalizados.

Por exemplo:

> **Cadastre estes 5 notebooks que chegaram hoje e entregue um para o João.**

O agente pode preparar o cadastro, pedir o que faltar e, depois de entregar um equipamento, enviar o termo de responsabilidade para o colaborador assinar. Cada equipamento precisa de um número de patrimônio, definido pela sua empresa.

> [!WARNING]
>
> **Para cadastrar e editar equipamentos, sua empresa precisa ter a gestão de equipamentos da Salvy.**
>
> Você também precisa ter permissão para gerenciar equipamentos na empresa.

#### Prompt

Preencha os campos entre `[ ]` antes de enviar o prompt ao seu agente.

```text theme={null}
Quero cadastrar novos equipamentos.

**Empresa:** [NOME DA EMPRESA]

**Equipamentos:** [LISTA COM MODELO, NÚMERO DE SÉRIE E NÚMERO DE PATRIMÔNIO]

(opcional) **Colaboradores:** [QUEM VAI RECEBER CADA EQUIPAMENTO]

Se faltar alguma informação, como o número de patrimônio ou a categoria, me pergunte antes de prosseguir.

Antes de cadastrar, me mostre a lista final e peça minha confirmação. Depois do cadastro, me pergunte se devo enviar o termo de responsabilidade para quem recebeu um equipamento.
```

***

## Usos criativos

### Help desk no Slack

Com o **Claude Tag no Slack**, sua empresa pode disponibilizar um Claude conectado às ferramentas definidas pela organização. Os colaboradores podem mencionar `@Claude` em um canal e fazer perguntas ou solicitar tarefas relacionadas à operação de telecom, sem precisar sair do Slack.

Por exemplo:

> **“Minha linha não está funcionando. Acabaram meus dados?”**

O Claude pode consultar as informações disponíveis no MCP da Salvy e ajudar o colaborador a entender o que está acontecendo.

Como o Claude Tag utiliza um acesso configurado pela organização, a empresa pode definir quais ferramentas e informações estarão disponíveis para ele e em quais canais ele poderá atuar.

Esse modelo pode ser especialmente útil para equipes que já utilizam o Slack como canal de comunicação e suporte interno.

**Saiba mais:** [Claude Tag no Slack →](https://code.claude.com/docs/en/claude-tag)

***

### Faça seus sistemas trabalharem juntos

Mudanças na empresa nem sempre acontecem na Salvy. Um colaborador pode ser desligado no sistema de RH, mudar de área ou ser contratado em outro sistema.

Você pode usar o MCP da Salvy em um *workflow* de automação para conectar esses eventos à sua operação de telecom e manter as informações atualizadas automaticamente.

Por exemplo:

> **Quando um colaborador for desligado, verifique se ele possui uma linha ativa na Salvy e bloqueie.**

Um *workflow* pode receber a informação do sistema de RH, consultar a Salvy para encontrar a linha correspondente e realizar a ação configurada.

### Como fazer

Você pode usar uma ferramenta de automação como o **n8n** para criar esse *workflow*.

O fluxo pode ser composto por:

1. **Detectar a mudança:** o n8n recebe uma atualização do seu sistema de RH.
2. **Identificar o colaborador:** o *workflow* obtém as informações necessárias para localizar a pessoa na Salvy.
3. **Consultar a Salvy:** o MCP da Salvy encontra a linha relacionada ao colaborador.
4. **Executar a ação:** o *workflow* utiliza o MCP para realizar a operação configurada.
5. **Registrar o resultado:** o n8n pode atualizar o sistema de origem ou enviar uma mensagem para o responsável.

> [!NOTE]
>
> **Dica:** você não precisa limitar esse *workflow* a desligamentos. O mesmo modelo pode ser usado para mudanças de área, atualização de centros de custo, *onboarding*, devolução de equipamentos e outras alterações que precisem ser refletidas na Salvy.

***

### Receba seus relatórios automaticamente

Algumas análises fazem parte da rotina da sua empresa e precisam ser acompanhadas com frequência. Em vez de repetir a mesma consulta toda semana ou todo mês, você pode transformar esse pedido em uma rotina no seu agente de IA.

Por exemplo:

> **Toda sexta-feira, analise o consumo de dados da minha operação e me envie um resumo com os principais pontos de atenção.**

A cada execução, o agente pode consultar os dados da Salvy através do MCP e gerar o relatório **do jeito que faz sentido para a sua operação**, combinando os dados disponíveis e os critérios que você definir.

Você pode, por exemplo, pedir para acompanhar:

* as linhas que mais consumiram dados;
* linhas próximas do limite do plano;
* consumo por empresa ou centro de custo;
* principais situações que merecem atenção;
* oportunidades de otimização identificadas a partir dos dados.

A cada execução, o agente pode reunir essas informações e apresentar o resultado no formato que você preferir, sem que você precise refazer a análise manualmente.

> [!TIP]
>
> **Exemplo**
>
> Toda segunda-feira, analise o consumo das minhas linhas. Separe por centro de custo, destaque as 10 linhas que mais consumiram dados e me avise se alguma estiver próxima do limite do plano. No final, faça um resumo com os três principais pontos que eu deveria acompanhar.

Você pode criar esse tipo de rotina usando os recursos de tarefas recorrentes disponíveis no seu agente de IA, como o [**Claude Routines**](https://code.claude.com/docs/en/routines).