Skip to main content
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.
  • Os centros de custo cadastrados na Salvy, de preferência com código, e as linhas associadas a eles.

​
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.
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.
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, 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

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

​
Variações

  • Vários meses de uma vez. Troque monthYear por fromMonthYear e toMonthYear em Listar faturas 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.