Pular para o conteúdo principal

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​

ENDPOINT
/billing/invoices/exports
MÉTODO
POST
STATUS
201

Autenticaçã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.

CampoTipoObrigatórioDescriçãoTamanho
start_datestringNãoData inicial do período, no formato aaaa-mm-dd, inclusiva.10
end_datestringNãoData final do período, no formato aaaa-mm-dd, inclusiva. Não pode ser anterior a start_date.10
payment_methodstringNãoMétodo de pagamento da tarifa. Enumerador payment_method—
statusstringNãoStatus da tarifa. Enumerador status—
billing_typesarrayNãoTipos de tarifa (billing_type) a incluir. Vazio inclui todos.—
owner_document_numberstringNãoCPF ou CNPJ do titular da conta, só números. Exporta as tarifas de todas as contas desse titular.—
account_numberstringNãoNúmero da conta, sem o dígito.—
owner_namestringNãoInício do nome do titular. Serão exportadas as tarifas pertencentes às primeiras 50 contas retornadas pelo filtro de nome do titular.—
account_keyuuidNãoChave 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_date e end_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 BLL000136 e 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 (pending ou processing). O 21º recebe 422 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​

CampoTipoDescrição
invoice_export_keyuuidChave do pedido. Use-a para consultar o pedido.
statusstringStatus do pedido. Enumerador status do pedido
filtersobjectFiltros do pedido, normalizados: todos os campos do corpo, com null nos que não foram enviados.
row_countintegerQuantidade de tarifas já gravadas no arquivo. Só é definitiva em done.
created_atstringData e hora do pedido.
finished_atstringData e hora em que o arquivo ficou pronto. null até done.
expires_atstringData e hora até a qual o arquivo pode ser baixado. null até done.
file_namestringSempre null nesta resposta.
download_urlstringSempre null nesta resposta. O link é gerado na consulta do pedido.
already_in_flightbooleantrue 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​

StatusCódigoDescrição
400QIT000001Corpo fora do formato: campo desconhecido, tipo errado ou account_key sem 36 caracteres.
400BLL000096Data fora do formato aaaa-mm-dd, ou end_date anterior a start_date.
400BLL000043status fora do enumerador.
400BLL000130payment_method fora do enumerador.
400BLL000137account_key enviado junto de owner_document_number, account_number ou owner_name.
404BLL000111Um dos billing_types não existe.
404BLL000058account_key não é uma conta do requester.
422BLL000134O requester já tem 20 pedidos em andamento. Aguarde um deles terminar.
422BLL000136Perí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​

ValorDescrição
account_debitDébito na conta do titular.
centralizing_account_debitDébito na conta centralizadora do requester.
bank_slipCobrança por boleto.
account_debit_and_bank_slipParte debitada em conta e o restante cobrado por boleto.

Enumerador status​

ValorDescrição
openTarifa em aberto.
pendingAguardando pagamento.
paidTarifa quitada.
written_offTarifa baixada.

Enumerador status do pedido​

ValorDescrição
pendingPedido registrado, aguardando processamento.
processingArquivo em geração.
doneArquivo pronto para download até expires_at.
expiredArquivo 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.