> ## 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.

# Criar faturas via API

> Crie faturas avulsas programaticamente em etapas: cabeçalho, grupos, linhas de cobrança e submissão para revisão.

> 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.

<Note>
  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.
</Note>

<br />

<h2 id="fluxo">
  Fluxo
</h2>

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.

<Steps>
  <Step title="Criar a fatura">
    `POST /v1/invoices` cria o cabeçalho da fatura em status `open`.

    ```json theme={null}
    {
      "idempotencyKey": "fatura-2026-05-1234",
      "externalCustomerId": "cliente-externo-1",
      "invoiceDate": "2026-05-31",
      "memo": "Serviços de implantação de maio/2026"
    }
    ```

    ```bash theme={null}
    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.
  </Step>

  <Step title="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`

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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`

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="(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:

    ```json theme={null}
    {
      "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`.
  </Step>

  <Step title="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-review`

    A partir daí, a revisão e a emissão para o cliente acontecem pelo Dashboard. Veja [Ciclo de vida da fatura](/faturas/ciclo-de-vida) para os próximos status.
  </Step>
</Steps>

<br />

<h2 id="linhas-sem-grupo">
  Linhas sem grupo
</h2>

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.

<br />

<h2 id="editar-e-cancelar">
  Editar e cancelar
</h2>

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.

<br />

<h2 id="referencia-rapida">
  Referência rápida
</h2>

| Operação               | Método   | Path                                                          |
| ---------------------- | -------- | ------------------------------------------------------------- |
| Criar fatura           | `POST`   | `/v1/invoices`                                                |
| Atualizar fatura       | `PUT`    | `/v1/invoices/{invoiceId}`                                    |
| Marcar como Em revisão | `POST`   | `/v1/invoices/{invoiceId}/in-review`                          |
| Cancelar fatura        | `POST`   | `/v1/invoices/{invoiceId}/cancel`                             |
| Criar grupo            | `POST`   | `/v1/invoices/{invoiceId}/line-item-groups`                   |
| Atualizar grupo        | `PUT`    | `/v1/invoices/{invoiceId}/line-item-groups/{lineItemGroupId}` |
| Remover grupo          | `DELETE` | `/v1/invoices/{invoiceId}/line-item-groups/{lineItemGroupId}` |
| Criar linha            | `POST`   | `/v1/invoices/{invoiceId}/line-items`                         |
| Atualizar linha        | `PUT`    | `/v1/invoices/{invoiceId}/line-items/{lineItemId}`            |
| Remover linha          | `DELETE` | `/v1/invoices/{invoiceId}/line-items/{lineItemId}`            |

Consulte a [Referência da API](/api-reference/introduction) para payloads completos, respostas e códigos de erro.

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Ciclo de vida da fatura](/faturas/ciclo-de-vida): entenda os status após `in_review`.
* [Documentos fiscais](/faturas/documentos-fiscais): emissão de NFSe e geração de PDFs após a aprovação.
* [Importação de faturas](/faturas/importacao): alternativa em planilha XLSX para carga em lote.