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

# Admissão → colaborador + linha

> 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).
* 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

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

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

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

  <Step title="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).
  </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 admissão.

<Card title="Baixar workflow do n8n" icon="download" href="/api-reference/v3/recipes/workflows/admission-create-line.json">
  `admission-create-line.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 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).
</Warning>

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

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

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

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

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

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


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