Skip to main content
A API pública permite criar faturas avulsas em etapas: criar o cabeçalho, montar grupos e linhas de cobrança, ajustar valores e submeter para revisão. Útil para cobranças pontuais, ajustes ou integrações que precisam montar a fatura programaticamente.
A edição via API só vale para faturas avulsas. Faturas geradas por ciclos de cobrança contratuais não podem ser modificadas dessa forma.

​
Fluxo

O fluxo é multi-etapa: cada passo retorna o id da entidade criada, que você usa no passo seguinte. Tudo continua editável até a fatura ser emitida manualmente no Dashboard ou cancelada.
1

Criar a fatura

POST /v1/invoices cria o cabeçalho da fatura em status open.
A resposta contém o id da fatura. Guarde esse valor como invoiceId para usar nos próximos passos.Campos importantes:
  • customerId ou externalCustomerId: informe exatamente um.
  • paymentAccountId: opcional. Quando omitido, a Aira escolhe automaticamente uma conta de pagamento do cliente.
  • invoiceDate: data de fechamento da fatura (fim do período coberto).
  • idempotencyKey: chave única. Reusar a mesma chave retorna a fatura já existente.
2

Criar um grupo de linhas

Grupos agrupam linhas relacionadas ao mesmo produto. São úteis quando um produto é faturado em várias linhas, por exemplo Onboarding + Treinamento dentro de Serviços de Implantação.POST /v1/invoices/{invoiceId}/line-item-groups
Guarde o id retornado como lineItemGroupId. O campo name é opcional. Quando omitido, o nome do produto é usado.
3

Adicionar linhas ao grupo

Cada linha vincula um item do catálogo a um valor e um período. Faça uma chamada por linha.POST /v1/invoices/{invoiceId}/line-items
Repita para cada linha. Por exemplo, uma segunda chamada com itemId e idempotencyKey diferentes para Treinamento.Sobre os IDs:
  • productId deve ser o mesmo do grupo.
  • itemId deve ser um item válido do catálogo.
  • name é opcional. Quando omitido, usa o nome do item.
4

(Opcional) Detalhar consumo com sub-linhas

Para detalhar a composição do amount da linha (por exemplo, consumo por faixa de preço), inclua subLineItems no payload do passo anterior:
Em cada sub-linha, usage é a quantidade consumida e price é o preço unitário em unidades monetárias, enviado como string decimal. A Aira arredonda usage * price para centavos em cada sub-linha; a soma precisa ser igual ao amount da linha, que é um número inteiro em centavos. No exemplo acima: (10000 * 0.08) + (4000 * 0.12) = R$ 1.280,00, portanto amount é 128000.
5

Marcar como Em revisão

Com a fatura montada, marque como Em revisão para que ela apareça na fila de aprovação interna no Dashboard.POST /v1/invoices/{invoiceId}/in-reviewA partir daí, a revisão e a emissão para o cliente acontecem pelo Dashboard. Veja Ciclo de vida da fatura para os próximos status.

​
Linhas sem grupo

Linhas podem existir fora de grupos. O campo lineItemGroupId é opcional no POST /line-items. Use quando não faz sentido agrupar, por exemplo uma única linha avulsa ou linhas heterogêneas que não compartilham produto.

​
Editar e cancelar

Faturas avulsas continuam editáveis via API mesmo após in_review. Ações suportadas:
  • Atualizar data e memorando da fatura: PUT /v1/invoices/{invoiceId} (aceita apenas invoiceDate e memo).
  • Atualizar ou remover grupo: PUT ou DELETE em /v1/invoices/{invoiceId}/line-item-groups/{lineItemGroupId}.
  • Atualizar ou remover linha: PUT ou DELETE em /v1/invoices/{invoiceId}/line-items/{lineItemId}.
  • Cancelar a fatura: POST /v1/invoices/{invoiceId}/cancel. Funciona em qualquer estado da fatura avulsa.

​
Referência rápida

Consulte a Referência da API para payloads completos, respostas e códigos de erro.

​
Próximos passos