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

# Desligamento → bloqueio de linhas

> 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

<Card title="Baixar workflow do n8n" icon="download" href="/api-reference/v3/recipes/workflows/offboarding-block-lines.json">
  `offboarding-block-lines.json`: importe no n8n e siga as notas dentro do
  workflow.
</Card>

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).
</Warning>

## 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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.