> ## 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.
# Fatura + NF-e para contas a pagar
> 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) |
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
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.
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.
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.
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.
`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
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.
`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.
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.
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).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.