Skip to main content

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 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.
{
  "idempotencyKey": "fatura-2026-05-1234",
  "externalCustomerId": "cliente-externo-1",
  "invoiceDate": "2026-05-31",
  "memo": "Serviços de implantação de maio/2026"
}

curl -X POST https://api.useaira.com/v1/invoices \
  -H "Authorization: Bearer $AIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json
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
{
  "idempotencyKey": "grupo-implantacao-1",
  "productId": "uuid-do-produto-implantacao",
  "name": "Serviços de Implantação",
  "startDate": "2026-05-01",
  "endDate": "2026-05-31"
}
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
{
  "idempotencyKey": "linha-onboarding-1",
  "productId": "uuid-do-produto-implantacao",
  "itemId": "uuid-do-item-onboarding",
  "lineItemGroupId": "{lineItemGroupId-do-passo-2}",
  "name": "Onboarding",
  "amount": 2500.00,
  "startDate": "2026-05-01",
  "endDate": "2026-05-15"
}
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:
{
  "idempotencyKey": "linha-mensagens-1",
  "productId": "uuid-do-produto-mensagens",
  "itemId": "uuid-do-item-envio",
  "name": "Mensagens enviadas",
  "amount": 1280.00,
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "subLineItems": [
    { "usage": 10000, "amount": 0.08 },
    { "usage": 4000, "amount": 0.12 }
  ]
}
Em cada sub-linha, usage é a quantidade consumida e amount é o valor unitário. O valor parcial da sub-linha é usage * amount, e a soma dos parciais deve bater exatamente com o amount da linha. No exemplo acima: (10000 * 0.08) + (4000 * 0.12) = 1280.00.
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

OperaçãoMétodoPath
Criar faturaPOST/v1/invoices
Atualizar faturaPUT/v1/invoices/{invoiceId}
Marcar como Em revisãoPOST/v1/invoices/{invoiceId}/in-review
Cancelar faturaPOST/v1/invoices/{invoiceId}/cancel
Criar grupoPOST/v1/invoices/{invoiceId}/line-item-groups
Atualizar grupoPUT/v1/invoices/{invoiceId}/line-item-groups/{lineItemGroupId}
Remover grupoDELETE/v1/invoices/{invoiceId}/line-item-groups/{lineItemGroupId}
Criar linhaPOST/v1/invoices/{invoiceId}/line-items
Atualizar linhaPUT/v1/invoices/{invoiceId}/line-items/{lineItemId}
Remover linhaDELETE/v1/invoices/{invoiceId}/line-items/{lineItemId}
Consulte a Referência da API para payloads completos, respostas e códigos de erro.

​
Próximos passos