Pedir exportação de tarifas
Pede a geração de um arquivo CSV com as tarifas do requester, de todas as contas ou de uma conta só. O arquivo é gerado em segundo plano: a resposta traz a chave do pedido, e o webhook invoice_export avisa quando o arquivo fica pronto.
Endpoint
/billing/invoices/exportsAutenticação
Requer assinatura da requisição. Ver Autenticação. O requester é o da credencial que assina a requisição.
Corpo da requisição
Todos os campos são opcionais. Um corpo vazio ({}) exporta todas as tarifas do requester, sujeito à regra de tamanho abaixo.
| Campo | Tipo | Obrigatório | Descrição | Tamanho |
|---|---|---|---|---|
start_date | string | Não | Data inicial do período, no formato aaaa-mm-dd, inclusiva. | 10 |
end_date | string | Não | Data final do período, no formato aaaa-mm-dd, inclusiva. Não pode ser anterior a start_date. | 10 |
payment_method | string | Não | Método de pagamento da tarifa. Enumerador payment_method | — |
status | string | Não | Status da tarifa. Enumerador status | — |
billing_types | array | Não | Tipos de tarifa (billing_type) a incluir. Vazio inclui todos. | — |
owner_document_number | string | Não | CPF ou CNPJ do titular da conta, só números. Exporta as tarifas de todas as contas desse titular. | — |
account_number | string | Não | Número da conta, sem o dígito. | — |
owner_name | string | Não | Início do nome do titular. Serão exportadas as tarifas pertencentes às primeiras 50 contas retornadas pelo filtro de nome do titular. | — |
account_key | uuid | Não | Chave da conta, para exportar o extrato de tarifas de uma conta só. Não pode ser combinado com os três campos acima. | 36 |
Regra de tamanho
- Período de até 31 dias, contando as duas pontas: o pedido é sempre aceito.
- Período maior que 31 dias, ou sem
start_dateeend_date: o pedido é aceito se o requester (ou a conta, quando háaccount_key) tiver até 200.000 tarifas no período, contadas sem os demais filtros. Acima disso, a resposta é422 BLL000136e nenhum pedido é criado. Escolha um período menor.
Pedidos em andamento
- Um pedido com os mesmos filtros de outro ainda em andamento não cria um pedido novo: a resposta devolve o pedido existente, com
already_in_flight: true. - Cada requester pode ter até 20 pedidos em andamento (
pendingouprocessing). O 21º recebe422 BLL000134.
{
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"payment_method": "bank_slip",
"status": "open",
"billing_types": ["account_maintenance"],
"owner_document_number": "96969879003"
}
Resposta
| Campo | Tipo | Descrição |
|---|---|---|
invoice_export_key | uuid | Chave do pedido. Use-a para consultar o pedido. |
status | string | Status do pedido. Enumerador status do pedido |
filters | object | Filtros do pedido, normalizados: todos os campos do corpo, com null nos que não foram enviados. |
row_count | integer | Quantidade de tarifas já gravadas no arquivo. Só é definitiva em done. |
created_at | string | Data e hora do pedido. |
finished_at | string | Data e hora em que o arquivo ficou pronto. null até done. |
expires_at | string | Data e hora até a qual o arquivo pode ser baixado. null até done. |
file_name | string | Sempre null nesta resposta. |
download_url | string | Sempre null nesta resposta. O link é gerado na consulta do pedido. |
already_in_flight | boolean | true quando a resposta é um pedido em andamento com os mesmos filtros. |
{
"invoice_export_key": "7a9c0a5e-1b2f-4c3d-9e8f-0123456789ab",
"status": "pending",
"filters": {
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"payment_method": "bank_slip",
"status": "open",
"billing_types": ["account_maintenance"],
"owner_document_number": "96969879003",
"account_number": null,
"owner_name": null,
"account_key": null
},
"row_count": 0,
"created_at": "2026-10-15T14:03:11",
"finished_at": null,
"expires_at": null,
"file_name": null,
"download_url": null,
"already_in_flight": false
}
Erros
| Status | Código | Descrição |
|---|---|---|
| 400 | QIT000001 | Corpo fora do formato: campo desconhecido, tipo errado ou account_key sem 36 caracteres. |
| 400 | BLL000096 | Data fora do formato aaaa-mm-dd, ou end_date anterior a start_date. |
| 400 | BLL000043 | status fora do enumerador. |
| 400 | BLL000130 | payment_method fora do enumerador. |
| 400 | BLL000137 | account_key enviado junto de owner_document_number, account_number ou owner_name. |
| 404 | BLL000111 | Um dos billing_types não existe. |
| 404 | BLL000058 | account_key não é uma conta do requester. |
| 422 | BLL000134 | O requester já tem 20 pedidos em andamento. Aguarde um deles terminar. |
| 422 | BLL000136 | Período maior que 31 dias com mais de 200.000 tarifas. Escolha um período menor. |
O corpo de erro segue o formato padrão (title, description, translation, code). A tabela acima lista os códigos deste endpoint; os erros gerais da plataforma, como QIT000001, estão nos erros comuns do catálogo de erros do BaaS.
Enumeradores
Enumerador payment_method
| Valor | Descrição |
|---|---|
account_debit | Débito na conta do titular. |
centralizing_account_debit | Débito na conta centralizadora do requester. |
bank_slip | Cobrança por boleto. |
account_debit_and_bank_slip | Parte debitada em conta e o restante cobrado por boleto. |
Enumerador status
| Valor | Descrição |
|---|---|
open | Tarifa em aberto. |
pending | Aguardando pagamento. |
paid | Tarifa quitada. |
written_off | Tarifa baixada. |
Enumerador status do pedido
| Valor | Descrição |
|---|---|
pending | Pedido registrado, aguardando processamento. |
processing | Arquivo em geração. |
done | Arquivo pronto para download até expires_at. |
expired | Arquivo removido após o prazo de 7 dias. Faça um novo pedido. |
Webhooks relacionados
Quando o arquivo fica pronto, o requester recebe o webhook invoice_export.
Próximo passo
Consultar exportação de tarifas para obter o link de download.