> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upag.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência

> Crie e gerencie faturas dos seus clientes

Uma fatura representa uma cobrança emitida para um cliente. Faturas podem ser criadas manualmente ou geradas automaticamente por assinaturas.

## <Icon icon="folder-tree" type="solid" /> Estrutura

Uma fatura é representada em nossa API pela seguinte estrutura:

```json theme={null}
{
  "id": "inv_abc123xyz",
  "customerId": "cus_ahwDXrgYvur89iPs",
  "paymentMethodId": "pm_abc123xyz",
  "currency": "BRL",
  "status": "open",
  "livemode": false,
  "number": "INV-001",
  "description": null,
  "dueDate": "2024-12-15T00:00:00.000Z",
  "paidAt": null,
  "amountDue": 9900,
  "amountPaid": 0,
  "attemptCount": 0,
  "subscriptionId": null,
  "items": [
    {
      "id": "ii_abc123xyz",
      "priceId": "price_def456ghi",
      "quantity": 1,
      "amount": 9900
    }
  ],
  "payments": [],
  "createdAt": "2024-11-15T10:00:00.000Z",
  "updatedAt": "2024-11-15T10:00:00.000Z"
}
```

## Atributos:

<AccordionGroup>
  <Accordion title="id:">
    ```json {2} theme={null}
    {
      "id": "inv_abc123xyz",
    }
    ```

    `id` : <u> string. </u> <br />
    Identificador único da fatura, começando com `inv_`
  </Accordion>

  <Accordion title="livemode:">
    ```json {2} theme={null}
    {
      "livemode": false,
    }
    ```

    `livemode` : <u> boolean. </u> <br />
    Indica se a fatura está em modo de produção (`true`) ou teste (`false`)
  </Accordion>

  <Accordion title="customerId:">
    ```json {2} theme={null}
    {
      "customerId": "cus_ahwDXrgYvur89iPs",
    }
    ```

    `customerId` : <u> string. </u> <br />
    ID do cliente associado à fatura. Veja a referência completa <a href="../customers/reference">aqui</a>
  </Accordion>

  <Accordion title="paymentMethodId:">
    ```json {2} theme={null}
    {
      "paymentMethodId": "pm_abc123xyz",
    }
    ```

    `paymentMethodId` : <u> string | null. </u> <br />
    ID do método de pagamento utilizado. Veja a referência completa <a href="../payment-methods/reference">aqui</a>
  </Accordion>

  <Accordion title="status:">
    ```json {2} theme={null}
    {
      "status": "open",
    }
    ```

    `status` : <u> string. </u> <br />
    Status atual da fatura

    <Info>
      | Status          | Descrição                                    |
      | --------------- | -------------------------------------------- |
      | `draft`         | **A fatura está em rascunho**                |
      | `open`          | **A fatura foi emitida e aguarda pagamento** |
      | `paid`          | **A fatura foi paga**                        |
      | `uncollectible` | **A fatura não pode ser cobrada**            |
      | `void`          | **A fatura foi cancelada**                   |
    </Info>
  </Accordion>

  <Accordion title="currency:">
    ```json {2} theme={null}
    {
      "currency": "BRL",
    }
    ```

    `currency` : <u> string. </u> <br />
    Código da moeda (ex.: `BRL`)
  </Accordion>

  <Accordion title="number:">
    ```json {2} theme={null}
    {
      "number": "INV-001",
    }
    ```

    `number` : <u> string | null. </u> <br />
    Número sequencial da fatura gerado automaticamente ao ser emitida
  </Accordion>

  <Accordion title="description:">
    ```json {2} theme={null}
    {
      "description": null,
    }
    ```

    `description` : <u> string | null. </u> <br />
    Descrição interna da fatura
  </Accordion>

  <Accordion title="dueDate:">
    ```json {2} theme={null}
    {
      "dueDate": "2024-12-15T00:00:00.000Z",
    }
    ```

    `dueDate` : <u> string | null. </u> <br />
    Data de vencimento da fatura em formato ISO 8601
  </Accordion>

  <Accordion title="paidAt:">
    ```json {2} theme={null}
    {
      "paidAt": null,
    }
    ```

    `paidAt` : <u> string | null. </u> <br />
    Data em que a fatura foi paga. `null` se ainda não paga
  </Accordion>

  <Accordion title="amountDue:">
    ```json {2} theme={null}
    {
      "amountDue": 9900,
    }
    ```

    `amountDue` : <u> number. </u> <br />
    Valor total a ser cobrado em centavos
  </Accordion>

  <Accordion title="amountPaid:">
    ```json {2} theme={null}
    {
      "amountPaid": 0,
    }
    ```

    `amountPaid` : <u> number. </u> <br />
    Valor já pago em centavos
  </Accordion>

  <Accordion title="attemptCount:">
    ```json {2} theme={null}
    {
      "attemptCount": 0,
    }
    ```

    `attemptCount` : <u> number. </u> <br />
    Número de tentativas de cobrança realizadas
  </Accordion>

  <Accordion title="subscriptionId:">
    ```json {2} theme={null}
    {
      "subscriptionId": null,
    }
    ```

    `subscriptionId` : <u> string | null. </u> <br />
    ID da assinatura que gerou esta fatura. `null` para faturas criadas manualmente
  </Accordion>

  <Accordion title="items:">
    ```json {2-7} theme={null}
    {
      "items": [
        {
          "id": "ii_abc123xyz",
          "priceId": "price_def456ghi",
          "quantity": 1,
          "amount": 9900
        }
      ]
    }
    ```

    `items` : <u> array. </u> <br />
    Lista de itens da fatura. Cada item contém `id`, `priceId`, `quantity` e `amount` (em centavos)
  </Accordion>

  <Accordion title="payments:">
    ```json {2} theme={null}
    {
      "payments": [],
    }
    ```

    `payments` : <u> array. </u> <br />
    Lista de pagamentos associados a esta fatura
  </Accordion>

  <Accordion title="createdAt:">
    ```json {2} theme={null}
    {
      "createdAt": "2024-11-15T10:00:00.000Z",
    }
    ```

    `createdAt` : <u> string. </u> <br />
    Data de criação da fatura em formato ISO 8601
  </Accordion>

  <Accordion title="updatedAt:">
    ```json {2} theme={null}
    {
      "updatedAt": "2024-11-15T10:00:00.000Z",
    }
    ```

    `updatedAt` : <u> string. </u> <br />
    Data da última atualização da fatura em formato ISO 8601
  </Accordion>
</AccordionGroup>