Skip to main content
A importação em lote permite criar ou substituir faturas a partir de uma planilha XLSX, seguindo um modelo padrão com colunas fixas. É indicada para carga inicial, migrações de sistemas anteriores e ajustes operacionais em grande volume.

​
Visão geral

  • Entidade importada: faturas.
  • Formato aceito: somente arquivos .xlsx.
  • Tamanho máximo: 50 MB por arquivo.
  • Resultado esperado: todas as faturas importadas entram com status Em revisão e origem Importação. Nenhuma fatura é emitida automaticamente pela importação.
  • Idempotência: cada fatura é identificada pela chaveIdempotencia. Reimportar com a mesma chave substitui a fatura anterior, desde que ela não esteja travada.
  • Múltiplas linhas por fatura: várias linhas da planilha com a mesma chaveIdempotencia formam uma única fatura, onde cada linha da planilha corresponde a uma linha de cobrança.
A importação não emite faturas para o cliente. Após a importação, as faturas ficam disponíveis na listagem com status Em revisão para conferência antes da emissão.

​
Como abrir a tela de importação

1

Acessar Faturas

No Dashboard, abra a listagem de Faturas.
2

Abrir o modal de importação

Clique em Ações → seção Importar → opção Importar faturas. Abre o modal “Importar faturas a partir de um arquivo”.
3

Baixar o modelo

Na descrição do modal, clique em modelo padrão para baixar o arquivo XLSX. O cabeçalho está na primeira linha e quatro linhas de exemplo já vêm preenchidas. Quando há um único modelo disponível, ele já vem pré-selecionado em “Selecione o modelo do arquivo”.
4

Preencher e enviar

Da segunda linha em diante, adicione uma linha por linha de cobrança. Use os nomes de coluna exatamente como estão no modelo — eles não podem ser renomeados ou reordenados. Faça upload do arquivo: assim que o upload é validado, o botão Enviar muda para Importar.
5

Acompanhar o resultado

Avisos não bloqueantes aparecem no bloco “Avisos no processamento”. Erros aparecem em “Erro ao processar a importação” ou “Arquivos que falharam no upload”.
Colunas extras não listadas no dicionário abaixo fazem o arquivo ser rejeitado — o schema não aceita propriedades adicionais.

​
Dicionário de colunas

A planilha tem 18 colunas na primeira linha (cabeçalho), nesta ordem e com estes nomes exatos:

​
chaveIdempotencia

  • Obrigatoriedade: obrigatória.
  • Tipo: texto, de 1 a 100 caracteres.
  • O que representa: identificador único da fatura.
  • Regra: múltiplas linhas com a mesma chaveIdempotencia formam uma única fatura — cada linha é uma linha de cobrança. Reimportar com a mesma chave substitui a fatura anterior, a menos que ela esteja travada.
  • Exemplo: fatura-exemplo-1.

​
idExternoCliente

  • Obrigatoriedade: obrigatória.
  • Tipo: texto, de 1 a 100 caracteres.
  • O que representa: ID externo do cliente já cadastrado na Aira.
  • Regra: o cliente precisa existir. Se não existir, a linha falha com Cliente não encontrado pelo customerExternalId.
  • Exemplo: cliente-externo-1.

​
dataEmissao

  • Obrigatoriedade: obrigatória.
  • Tipo: data no formato dd/mm/aaaa ou célula de data do Excel.
  • O que representa: data de emissão da fatura.
  • Regra: vazia ou inválida → Data da fatura inválida. Datas anteriores a 01/01/2000 são rejeitadas.
  • Exemplo: 01/05/2026.

​
dataVencimento

  • Obrigatoriedade: opcional.
  • Tipo: data no formato dd/mm/aaaa ou célula de data do Excel.
  • O que representa: data de vencimento da fatura.
  • Regra: se preenchida e inválida → Data de vencimento inválida. Só pode ser preenchida se o módulo de Pagamentos estiver habilitado — caso contrário → Data de vencimento não permitida: módulo de pagamentos desativado.
  • Exemplo: 10/05/2026.

​
memorando

  • Obrigatoriedade: opcional.
  • Tipo: texto até 1000 caracteres.
  • O que representa: observação livre da fatura, exibida na fatura.
  • Exemplo: Mensalidade de maio.

​
cnpjCpf

  • Obrigatoriedade: opcional.
  • Tipo: texto até 30 caracteres.
  • O que representa: CNPJ ou CPF usado para escolher a conta de pagamento entre o cliente e suas subsidiárias. A comparação ignora pontuação.
  • Regra: quando vazia, usa a primeira conta de pagamento do próprio cliente. Quando preenchida, procura match exato (após remover não-numéricos) entre as contas do cliente e das suas subsidiárias.
  • Exemplo: 12.345.678/0001-90.

​
unidadePeriodo

  • Obrigatoriedade: opcional.
  • Tipo: texto, um dos valores semanal, mensal ou anual.
  • O que representa: unidade de período de faturamento da linha.
  • Regra: maiúsculas/minúsculas indiferentes. Vazia é aceita (a fatura fica sem unidade de período). Qualquer outro valor → Unidade de período inválida (semanal, mensal, anual).
  • Exemplo: mensal.

​
chaveIdempotenciaGrupo

  • Obrigatoriedade: opcional.
  • Tipo: texto até 100 caracteres.
  • O que representa: identificador de um grupo de linhas de cobrança dentro da fatura.
  • Regra: linhas com a mesma chaveIdempotenciaGrupo dentro da mesma chaveIdempotencia formam um grupo. Quando preenchida, exige dataInicioGrupo e dataFimGrupo válidas e referência consistente ao mesmo produto entre todas as linhas do grupo.
  • Exemplo: grupo-implantacao-1.

​
dataInicioGrupo

  • Obrigatoriedade: condicional — obrigatória quando chaveIdempotenciaGrupo estiver preenchida.
  • Tipo: data no formato dd/mm/aaaa ou célula de data do Excel.
  • O que representa: início do período coberto pelo grupo.
  • Regra: em branco ou inválida, com chaveIdempotenciaGrupo preenchida → Data de início do grupo inválida.
  • Exemplo: 01/05/2026.

​
dataFimGrupo

  • Obrigatoriedade: condicional — obrigatória quando chaveIdempotenciaGrupo estiver preenchida.
  • Tipo: data no formato dd/mm/aaaa ou célula de data do Excel.
  • O que representa: fim do período coberto pelo grupo.
  • Regra: em branco ou inválida, com chaveIdempotenciaGrupo preenchida → Data de término do grupo inválida.
  • Exemplo: 31/05/2026.

​
idProduto

  • Obrigatoriedade: condicional — obrigatória apenas se nomeProduto estiver vazio.
  • Tipo: texto até 100 caracteres.
  • O que representa: ID do produto na Aira ao qual a linha de cobrança está vinculada.
  • Regra: pelo menos uma das colunas idProduto ou nomeProduto precisa estar preenchida. Quando ambas estão preenchidas, o idProduto tem prioridade. Se o ID não existir → Produto não encontrado. Se ambas estiverem vazias → Informe o idProduto ou o nomeProduto.
  • Exemplo: uuid-do-produto-assinatura.

​
nomeProduto

  • Obrigatoriedade: condicional — obrigatória apenas se idProduto estiver vazio.
  • Tipo: texto até 200 caracteres.
  • O que representa: nome do produto na Aira ao qual a linha de cobrança está vinculada.
  • Regra: usada quando idProduto está vazio. A busca ignora maiúsculas/minúsculas, acentos e espaços extras nas pontas. Se nenhum produto bate → Produto não encontrado.
  • Exemplo: Serviço de Implantação.

​
idItem

  • Obrigatoriedade: condicional — obrigatória apenas se nomeItem estiver vazio.
  • Tipo: texto até 100 caracteres.
  • O que representa: ID de um item do catálogo ao qual a linha de cobrança está vinculada.
  • Regra: pelo menos uma das colunas idItem ou nomeItem precisa estar preenchida. Quando ambas estão preenchidas, o idItem tem prioridade. Se o ID não existir → Item não encontrado. Se ambas estiverem vazias → Informe o idItem ou o nomeItem.
  • Exemplo: uuid-do-item-onboarding.

​
nomeItem

  • Obrigatoriedade: condicional — obrigatória apenas se idItem estiver vazio.
  • Tipo: texto até 200 caracteres.
  • O que representa: nome do item do catálogo ao qual a linha de cobrança está vinculada.
  • Regra: usada quando idItem está vazio. A busca ignora maiúsculas/minúsculas, acentos e espaços extras nas pontas. Se nenhum item bate → Item não encontrado. Esta coluna não é um nome de exibição livre — o nome exibido da linha de cobrança vem sempre do item resolvido.
  • Exemplo: Onboarding.
Os valores de idProduto e idItem correspondem aos identificadores internos dos produtos e itens do catálogo na Aira. Antes de rodar a importação, entre em contato com o time da Aira para receber o mapeamento correto dos IDs a utilizar — os valores variam conforme o caso de uso e o cadastro da sua conta. Como alternativa, use nomeProduto e nomeItem para resolver pelo nome.

​
dataInicioItem

  • Obrigatoriedade: obrigatória em toda linha.
  • Tipo: data no formato dd/mm/aaaa ou célula de data do Excel.
  • O que representa: início do período coberto pela linha de cobrança.
  • Regra: em branco ou inválida → Data de início do item inválida.
  • Exemplo: 01/05/2026.

​
dataFimItem

  • Obrigatoriedade: obrigatória em toda linha.
  • Tipo: data no formato dd/mm/aaaa ou célula de data do Excel.
  • O que representa: fim do período coberto pela linha de cobrança.
  • Regra: em branco ou inválida → Data de término do item inválida.
  • Exemplo: 31/05/2026.

​
quantidade

  • Obrigatoriedade: obrigatória.
  • Tipo: número decimal (aceita . ou , como separador). Sem separador de milhar.
  • O que representa: quantidade cobrada na linha.
  • Regra: maior ou igual a zero. Vazia, não numérica ou negativa → Quantidade inválida.
  • Exemplo: 8.

​
valorUnitario

  • Obrigatoriedade: obrigatória.
  • Tipo: número decimal em reais (não em centavos). Aceita . ou , como separador. Sem separador de milhar.
  • O que representa: valor unitário da linha em reais.
  • Regra: maior ou igual a zero. Vazio, não numérico ou negativo → Valor unitário inválido. O total da linha é quantidade × valorUnitario.
  • Exemplo: 499,00.

​
Regras de agrupamento e idempotência

​
Uma fatura por chaveIdempotencia

Linhas que compartilham a mesma chaveIdempotencia formam uma única fatura. Para isso, os campos de cabeçalho abaixo precisam ser idênticos em todas as linhas da fatura — se algum diferir, a segunda linha (e as seguintes) é rejeitada com Campos da fatura inconsistentes entre linhas do mesmo idempotencyKey:
  • idExternoCliente
  • dataEmissao
  • dataVencimento
  • memorando
  • cnpjCpf
  • unidadePeriodo

​
Grupos de linhas de cobrança

Um grupo é um agrupador de linhas de cobrança dentro da mesma fatura, sob um mesmo produto. Use quando um produto é faturado em várias linhas — por exemplo, as etapas de uma implantação (Onboarding + Treinamento) — e você quer exibi-las agrupadas na fatura, com um período único para o conjunto. Linhas com a mesma chaveIdempotenciaGrupo, dentro da mesma chaveIdempotencia, formam um grupo. Dentro de um grupo:
  • Todas as linhas devem apontar para o mesmo produto — senão Todas as linhas de um grupo devem ter o mesmo productId. Linhas que usam idProduto e linhas que usam nomeProduto apontando para o mesmo produto resolvido são compatíveis; referências literais diferentes contam como diferença.
  • Os campos dataInicioGrupo e dataFimGrupo devem ser idênticos entre as linhas — senão Campos do grupo inconsistentes entre linhas do mesmo groupIdempotencyKey.
  • dataInicioGrupo e dataFimGrupo são obrigatórias quando chaveIdempotenciaGrupo estiver preenchida.
O nome exibido do grupo na fatura vem sempre do nome do produto resolvido. O chaveIdempotenciaGrupo é opcional: fatura com linhas soltas (sem grupo) também é válida. Uma mesma fatura pode misturar linhas agrupadas e linhas soltas.

​
Substituição por reimportação

Reimportar um arquivo com uma chaveIdempotencia já existente substitui a fatura anterior. Se a fatura existente estiver travada (já emitida, paga, cancelada ou sincronizada), a linha falha com Fatura alvo está travada e não pode ser substituída e nada é alterado.

​
Formatos aceitos

Aceitamos dois formatos:
  • Texto no formato dd/mm/aaaa.
  • Células de data do Excel — o formato nativo quando você digita a data diretamente na célula formatada como data.
O formato ISO aaaa-mm-dd não é aceito. Datas anteriores a 01/01/2000 são rejeitadas como inválidas.

​
Resolução automática no processamento

Para cada linha, a Aira faz as seguintes buscas e associações:
1

Cliente

Busca o cliente pelo idExternoCliente. Se não existir → Cliente não encontrado pelo customerExternalId.
2

Conta de pagamento

  • Se cnpjCpf estiver vazio: usa a primeira conta de pagamento do cliente. Se o cliente não tiver nenhuma → Cliente não possui conta de pagamento.
  • Se cnpjCpf estiver preenchido: normaliza removendo caracteres não numéricos e procura match exato entre as contas de pagamento do cliente e das suas subsidiárias. Sem match → taxId não encontrado entre o cliente e suas subsidiárias.
3

Produto

  • Se idProduto estiver preenchido, busca o produto por ID.
  • Senão, busca pelo nomeProduto (ignorando maiúsculas/minúsculas, acentos e espaços extras).
  • Se nada bate → Produto não encontrado. Se ambas estiverem vazias → Informe o idProduto ou o nomeProduto.
4

Item

  • Se idItem estiver preenchido, busca o item por ID.
  • Senão, busca pelo nomeItem (mesma comparação acima).
  • Se nada bate → Item não encontrado. Se ambas estiverem vazias → Informe o idItem ou o nomeItem.
5

Fatura existente

Verifica se já existe fatura com a mesma chaveIdempotencia. Se existir e estiver travada (já emitida, paga, cancelada ou sincronizada) → Fatura alvo está travada e não pode ser substituída. Caso contrário, a fatura anterior é substituída.

​
Comportamento após importar

Toda fatura criada pela importação entra com estado fixo, não configurável pela planilha:
  • Status: Em revisão.
  • Origem: Importação.
  • Alocação: a fatura é alocada inteiramente ao cliente do cabeçalho.
  • Nome exibido do grupo: vem sempre do nome do produto resolvido.
  • Nome exibido da linha de cobrança: vem sempre do nome do item resolvido.
A fatura não é emitida automaticamente pela importação. O usuário precisa abrir a fatura em “Em revisão”, conferir e emitir.

​
Mensagens de erro


​
Exemplos do modelo

O modelo baixável já vem preenchido com quatro linhas de exemplo, cobrindo os cenários mais comuns: fatura simples resolvida por ID, fatura com grupo resolvida por nome, e fatura sem dataVencimento misturando ID e nome.

​
Linha 1 — Fatura simples, produto e item por ID

Uma fatura avulsa com uma única linha de cobrança (mensalidade). Resolve produto e item pelo ID.

​
Linha 2 — Fatura com grupo, primeira linha (Onboarding)

Primeira linha de uma fatura com grupo de implantação. O cnpjCpf é usado para escolher a conta de pagamento entre o cliente e suas subsidiárias. Produto e item resolvidos pelo nome.

​
Linha 3 — Mesma fatura, segunda linha do grupo (Treinamento)

Segunda linha da fatura fatura-exemplo-2, dentro do mesmo grupo grupo-implantacao-1. Todos os campos de cabeçalho (idExternoCliente, dataEmissao, dataVencimento, memorando, cnpjCpf, unidadePeriodo) e os campos de grupo (dataInicioGrupo, dataFimGrupo, referência ao produto) coincidem com a Linha 2.

​
Linha 4 — Fatura sem dataVencimento, produto por ID e item por nome

Fatura avulsa, sem grupo, com dataVencimento em branco e unidadePeriodo em branco. Mistura: produto pelo ID e item pelo nome.

​
Limitações conhecidas

  • Somente arquivos .xlsx são aceitos — outros formatos (.csv, .xls, .ods) não são suportados.
  • O tamanho máximo por arquivo é 50 MB.
  • Os nomes das colunas em português (camelCase) são fixos — não podem ser renomeados ou reordenados.
  • Colunas extras não previstas pelo schema fazem o arquivo ser rejeitado.

​
Próximos passos