Importação de faturas

Documentation Index

Fetch the complete documentation index at: https://docs.useaira.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​

Como abrir a tela de importação

​

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.

​

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

​

Resolução automática no processamento

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

​

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

• Ciclo de vida da fatura — entenda as transições a partir de Em revisão.
• Descontos e alocações — ajuste valores e distribua cobranças após a importação.
• Documentos fiscais — emissão de NFSe e geração de PDFs.