> ## 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.
# Rateio de telecom por centro de custo
> 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
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.
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`.
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.
`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
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.
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`.
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.
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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.