---
title: "Cria uma nova fatura avulsa."
method: POST
path: "/v1/bills"
tags: ["bills"]
---

# Cria uma nova fatura avulsa.

`POST /v1/bills`

## Request

- Base URL: `//app.vindi.com.br/api` (relative, and the document’s source URL is not known)
- URL: `//app.vindi.com.br/api/v1/bills`
- Auth: HTTP basic

Faturas avulsas são independentes de assinaturas e podem ser usadas para cobrar qualquer tipo de valor não recorrente.

Todas as faturas seguirão as configurações de retentativa e notificações previamente configuradas na plataforma.

#### Exemplo

A maioria dos parâmetros deste método são opcionais. O exemplo abaixo efetua a emissão de uma fatura avulsa usando apenas os atributos obrigatórios:


```
{
  "customer_id": 28,
  "payment_method_code": "bank_slip",
  "bill_items": [
    {
      "product_id": 14,
      "amount": 100
    }
  ]
}
```

Recomendamos que você implemente apenas estes parâmetros obrigatórios e adicione os opcionais a medida que a necessidade sugir. Normalmente o comportamento padrão da plataforma é suficiente para a maioria dos casos de uso.

#### Lista de produtos

Sua fatura avulsa deve conter no mínimo um item na lista `bill_items`. Você deve referenciar o produto através do parâmetro `product_id` ou `product_code`.

Diferente das faturas geradas a partir de assinaturas, o valor dos itens das faturas avulsas pode ser informado através do parâmetro `amount` dentro da lista `bill_items`.

Apesar do `bill_item` suportar um esquema de precificação (`pricing_schema`) com quantidade (`quantity`), recomendamos utilizar apenas o parâmetro `amount` para evitar complexidade desnecessária no desenvolvimento. Se `pricing_schema`, `quantity` e `amount` forem informados ao mesmo tempo, garanta que todos sejam mutuamente válidos.

#### Método de pagamento

É obrigatório informar o código do método de pagamento para a geração da fatura. Caso o método escolhido seja cartão de crédito, por exemplo, a plataforma irá tentar efetuar a cobrança com o cartão já cadastrado para o respectivo cliente. Caso nenhum cartão esteja cadastrado, a plataforma enviará por padrão um e-mail automático solicitando os dados de pagamento.

Se preferir, você ainda poderá efetuar a captura dos dados de pagamento de duas outras formas diferentes:

- Capture os dados em uma página própria (obrigatoriamente com HTTPS) e informe-os para a Vindi através do método da API `POST payment_profiles` antes de criar a fatura;
- Ou então redirecione o cliente para o parâmetro `url` da fatura recém-criada, onde ele poderá imprimir o boleto ou inserir as informações de pagamento dentro do ambiente seguro da Vindi.

#### Condição de pagamento

Por padrão, a condição de pagamento configurada no método de pagamento será utilizada para emitir a cobrança da fatura avulsa.

Se desejar customizar a condição para uma fatura específica, informe o parâmetro `payment_condition`.

Caso você receba um erro no atributo `payment_condition` informando que o mesmo é inválido, verifique se os dados de data de vencimento `due_at`, data de agendamento `billing_at` e desconto por pontualidade `payment_condition.payment_condition_discounts.days_before_due` estão válidos. O valor da data do limite de desconto não pode ser retroativa, sendo assim, é possível que o parâmetro `payment_condition` fique inválido mesmo que não tenha sido informado, visto que as informações do método de pagamento escolhido serão utilizadas por padrão.

## Request body

- PostV1Bills: Cria uma nova fatura avulsa.
  - `body` DataOnlyCreate
    - `color_depth` integer: Indica a profundidade de cor estimada da tela do usuário, em bits por pixel. É obtida no navegador do cliente por meio da propriedade window.screen.colorDepth.
    - `java_enabled` boolean: Indica se o navegador do usuário possui suporte para execução de applets Java. É obtida no navegador do cliente por meio da propriedade navigator.javaEnabled.
    - `language` string: Representa o idioma preferido do navegador, no formato IETF BCP 47 (por exemplo, en, pt-BR, fr-FR). Pode ser obtido através da propriedade navigator.language.
    - `screen_height` integer: Representa a altura total da tela do dispositivo do usuário, em pixels. O valor é obtido por meio da propriedade window.screen.height.
    - `screen_width` integer: Representa a largura total da tela do dispositivo do usuário, em pixels. O valor é obtido por meio da propriedade window.screen.width.
    - `time_zone_offset` integer: Diferença de horário, em horas, entre o UTC e a hora local do navegador do titular do cartão.
    - `user_agent` string: Identificador do browser utilizado pelo comprador no momento da compra.
    - `ip_address` string: Suporta informações somente em iPv4.
  - `customer_id` integer, required: ID do cliente
  - `code` string: Código externo para referência via API
  - `installments` integer: Número de parcelas. Se não informado, o valor '1' será utilizado
  - `payment_method_code` string, required: Código do método de pagamento
  - `billing_at` string: Data opcional de emissão da cobrança no formato ISO 8601. Se não informada, a cobrança será imediata
  - `due_at` string: Data opcional de vencimento da cobrança no formato ISO 8601. Se não informada, o vencimento padrão será utilizado
  - `brand_tid` string: Código identificador da transação na respectiva bandeira
  - `bill_items` BillItemParametersCreate[], required: Lista de itens da fatura
    - `product_id` number: ID do produto associado ao item da fatura
    - `product_code` string: Código do produto associado ao item da fatura
    - `amount` number, required: Valor do item da fatura
    - `description` string: Descrição opcional do item da fatura
    - `quantity` integer: Quantidade do item da fatura
    - `pricing_schema` PricingSchemaParameters
      - `price` number, required: Preço base
      - `minimum_price` number: Preço mínimo
      - `schema_type` 'flat' | 'per_unit' | 'step_usage' | 'volume_usage' | 'tier_usage', required: Tipo de cálculo da precificação
      - `pricing_ranges` PricingRangeParameters[]: Lista de faixas de precificação
        - `start_quantity` integer, required: Início da faixa
        - `end_quantity` integer: Término da faixa. Opcional apenas para a última
        - `price` number, required: Preço da unidade ou da faixa, dependendo do tipo escolhido
        - `overage_price` number: Preço unitário do excedente da faixa
  - `bill_affiliates` BillAffiliateParametersCreate[]: Lista de participantes da fatura. Este campo é exclusivo para transaçõesque contenham participantes ativos. Os participantes dividem o valorda fatura com a empresa
    - `affiliate_id` integer: ID do participante
    - `amount` number: Valor da fatura
    - `amount_type` integer: Tipo de valor da fatura
  - `metadata` 'array': Metadados da fatura
  - `payment_profile` PaymentProfileParametersFindOrCreate
    - `id` integer: ID do perfil de pagamento existente
    - `token` string
    - `holder_name` string: Nome do titular/portador do perfil de pagamento
    - `registry_code` string: CPF ou CNPJ do titular/portador
    - `bank_branch` string: Agência da conta bancária
    - `bank_account` string: Número da conta bancária
    - `card_expiration` string: Validade do cartão de crédito no formato MM/AA
    - `allow_as_fallback` string: Permite utilizar o perfil de pagamento em retentativas de cobranças não pagas.
    - `card_number` string: Número completo do cartão de crédito
    - `card_cvv` string: Código de segurança do cartão de crédito com 3 ou 4 dígitos
    - `card_token` string
    - `gateway_id` string
    - `payment_method_code` string: Código do método de pagamento
    - `payment_company_code` string: Código do banco ou bandeira
    - `gateway_token` string: Token externo
  - `payment_condition` PaymentConditionParametersCreate
    - `penalty_fee_value` number: Valor da multa
    - `penalty_fee_type` string: Tipo da multa
    - `daily_fee_value` number: Valor dos juros ao dia
    - `daily_fee_type` string: Tipo dos juros ao dia
    - `after_due_days` integer: Prazo para pagamento após vencimento
    - `payment_condition_discounts` PaymentConditionDiscountParametersCreate[]: Desconto de pontualidade
      - `value` number, required: Valor
      - `value_type` 'percentage' | 'amount', required: Tipo
      - `days_before_due` integer, required: Dias antes do vencimento

## Response `201`

Fatura avulsa criada com sucesso.

- Bill: Utilize este método para listar as faturas associadas à sua conta na Vindi. Leia a documentação sobre [paginação](http://atendimento.vindi.com.br/hc/pt-br/articles/203020644#pagination) e [filtros de busca](http://atendimento.vindi.com.br/hc/pt-br/articles/204163150). #### Atributos para busca <code>id</code>, <code>code</code>, <code>installments</code>, <code>period_id</code>, <code>subscription_id</code>, <code>customer_id</code>, <code>amount</code>, <code>status</code>, <code>payment_method_id</code>, <code>seen_at</code>, <code>due_at</code>, <code>billing_at</code>, <code>created_at</code> e <code>updated_at</code>. #### Itens da fatura Uma fatura é composta de vários itens representados no array `bill_items`. Este endpoint lista apenas os 25 primeiros itens de cada fatura. Caso queira listar mais itens de uma fatura, utilize o método da API `GET /bills/{id}/bill_items`.
  - `id` integer, required: ID da fatura
  - `code` string: Código externo para referência via API
  - `amount` number, required: Valor da fatura
  - `installments` integer, required: Número de parcelas
  - `status` 'review' | 'pending' | 'paid' | 'canceled' | 'scheduled', required: Status da fatura
  - `seen_at` string, required: Última visualização da fatura
  - `billing_at` string: Data opcional de emissão da cobrança
  - `due_at` string: Data de vencimento da fatura
  - `url` string, required: URL para pagamento da fatura
  - `created_at` string, required: Data e hora da geração da fatura
  - `updated_at` string, required: Data e hora da última atualização da fatura
  - `bill_items` BillItem[]: Itens da fatura. Este atributo exibe os primeiros 25 itens. Para os demais, consulte o método `GET /bills/:id/bill_items`
    - `id` integer, required: ID do item da fatura
    - `amount` number, required: Valor do item da fatura
    - `quantity` integer: Quantidade do item da fatura
    - `pricing_range_id` integer: ID da faixa de precificação usada no cálculo do preço, se aplicável
    - `description` string: Descrição opcional do item da fatura
    - `pricing_schema` PricingSchema
      - `id` string, required: ID do esquema de precificação
      - `short_format` string, required: Descrição da precificação gerada automaticamente
      - `price` number, required: Preço base
      - `minimum_price` number: Preço mínimo
      - `schema_type` 'flat' | 'per_unit' | 'step_usage' | 'volume_usage' | 'tier_usage', required: Tipo de cálculo da precificação
      - `pricing_ranges` PricingRange[]: Lista de faixas de precificação
        - `id` string, required: ID do faixa de precificação
        - `start_quantity` integer, required: Início da faixa
        - `end_quantity` integer: Término da faixa. Opcional apenas para a última
        - `price` number, required: Preço da unidade ou da faixa, dependendo do tipo escolhido
        - `overage_price` number: Preço unitário do excedente da faixa
      - `created_at` string, required: Data e hora do cadastro do esquema de precificação
    - `product` ProductSummary, required
      - `id` integer, required: ID do produto
      - `name` string, required: Nome do produto
      - `code` string: Código externo do produto
    - `product_item` ProductItemSummary
      - `id` integer, required: ID do item
      - `product` ProductSummary, required
        - `id` integer, required: ID do produto
        - `name` string, required: Nome do produto
        - `code` string: Código externo do produto
    - `discount` DiscountSummary
      - `id` integer, required: ID do desconto
      - `discount_type` 'percentage' | 'amount' | 'quantity', required: Tipo do desconto
      - `percentage` number: Valor numérico para porcentagem de 0.01 até 100
      - `amount` number: Valor para desconto fixo
      - `quantity` integer: Número para desconto por quantidade
      - `cycles` integer: Número de ciclos de recorrência onde o desconto será aplicado a partir do momento de sua criação. Nulo significa desconto por tempo indefinido
  - `charges` BillCharge[]: Cobranças da fatura
    - `id` integer, required: ID da cobrança
    - `amount` number, required: Valor da cobrança
    - `status` 'pending' | 'paid' | 'canceled' | 'processing' | 'fraud_review', required: Status da cobrança
    - `due_at` string, required: Data do vencimento da cobrança
    - `paid_at` string: Data do pagamento da cobrança, apenas se a cobrança já foi paga
    - `installments` integer, required: Número de parcelas da cobrança. Valores acima de 1 são usados apenas para parcelamento através da administradora do cartão de crédito
    - `attempt_count` integer: Número de tentativas automáticas de cobrança já realizadas
    - `next_attempt` integer: Data da próxima tentativa automática de cobrança
    - `print_url` string: URL para impressão da cobrança. Usado apenas para boletos
    - `created_at` string, required: Data e hora da geração da cobrança
    - `updated_at` string, required: Data e hora da última atualização da cobrança
    - `last_transaction` TransactionSummary, required
      - `id` integer, required: ID da transação
      - `transaction_type` 'charge' | 'refund' | 'authorization' | 'capture' | 'verify' | 'register' | 'void' | 'renew_payment_profile' | 'pre_authorization' | 'update', required: Tipo da transação
      - `status` 'processing' | 'success' | 'rejected' | 'failure' | 'timeout' | 'waiting' | 'canceled' | 'fraud_review', required: Status da transação
      - `amount` number, required: Valor da transação
      - `installments` integer, required: Número de parcelas
      - `gateway_message` string, required: Mensagem de resposta do gateway
      - `gateway_response_code` string, required: Código de resposta do gateway
      - `gateway_authorization` string, required: Código da autorização usado no estorno ou captura. Varia de acordo com o adquirente
      - `gateway_transaction_id` string, required: Código externo de referência do gateway. Para boletos, representa o "nosso número"
      - `gateway_response_fields` string: Atributos de resposta específicos do gateway
      - `fraud_detector_score` number: Pontuação da análise antifraude entre 0.00 e 1.00. Quanto maior a pontuação, maior o risco de fraude
      - `fraud_detector_status` 'automatic_success' | 'manual_success' | 'automatic_rejected' | 'manual_rejected' | 'review' | 'failure': Status da análise antifraude
      - `fraud_detector_id` string: ID da análise antifraude
      - `created_at` string, required: Data e hora da transação
      - `gateway` GatewaySummary, required
        - `id` integer, required: ID do gateway
        - `connector` string, required: Conector utilizado no gateway
      - `payment_profile` PaymentProfileSummary, required
        - `id` integer, required: ID do perfil de pagamento
        - `holder_name` string: Nome do titular/portador do perfil de pagamento
        - `registry_code` string: CPF ou CNPJ do titular/portador
        - `bank_branch` string: Agência da conta bancária
        - `bank_account` string: Número da conta bancária
        - `card_expiration` string: Validade do cartão de crédito no formato MM/AA
        - `allow_as_fallback` string: Permite utilizar o perfil de pagamento em retentativas de cobranças não pagas.
        - `card_number_first_six` string: Primeiros 6 dígitos do cartão de crédito (BIN/IIN)
        - `card_number_last_four` string: Últimos 4 dígitos do cartão de crédito
        - `renewed_card` object
          - `card_number_last_four` string: Últimos quatro dígitos do cartão de crédito renovado
          - `card_expiration` string: Nova validade do cartão de crédito renovado
        - `card_renewed_at` string: Data da renovação do cartão de crédito renovado
        - `token` string, required: Token interno para referência do perfil de pagamento
        - `created_at` string, required: Data e hora do cadastro do perfil de pagamento
        - `payment_company` PaymentCompany, required
          - `id` integer, required: ID da bandeira ou banco
          - `name` string, required: Nome da bandeira ou banco
          - `code` string, required: Código para referência via API
    - `payment_method` PaymentMethodSummary, required
      - `id` integer, required: ID do método de pagamento
      - `public_name` string, required: Nome público do método de pagamento
      - `name` string, required: Nome interno do método de pagamento
      - `code` string, required: Código externo para referência via API
      - `type` string, required: Tipo do método de pagamento
  - `bill_affiliates` BillAffiliateResponseFull[]: Lista de participantes da fatura. Este campo é exclusivo para transaçõesque contenham participantes ativos. Os participantes dividem o valorda fatura com a empresa
    - `affiliate_id` integer: ID do participante
    - `amount` number: Valor da fatura
    - `amount_type` integer: Tipo de valor da fatura
  - `customer` CustomerSummary
    - `id` integer, required: ID do cliente
    - `name` string, required: Nome do cliente
    - `email` string: E-mail do cliente
    - `code` string: Código opcional para referência via API
  - `period` PeriodSummary
    - `id` integer, required: ID do período
    - `billing_at` string: Data para geração automática da cobrança do período
    - `cycle` integer, required: Ciclo do período
    - `start_at` string, required: Data e hora do início do período
    - `end_at` string, required: Data e hora do término do período
    - `duration` integer, required: Duração do período em número de segundos
  - `subscription` SubscriptionSummary
    - `id` integer, required: ID da assinatura
    - `code` string: Código externo para referência via API
    - `plan` PlanSummary, required
      - `id` integer, required: ID do plano
      - `name` string, required: Nome do plano
      - `code` string: Código externo do plano
    - `customer` CustomerSummary, required
      - `id` integer, required: ID do cliente
      - `name` string, required: Nome do cliente
      - `email` string: E-mail do cliente
      - `code` string: Código opcional para referência via API
  - `metadata` object: Metadados da fatura
  - `payment_profile` PaymentProfileSummary
    - `id` integer, required: ID do perfil de pagamento
    - `holder_name` string: Nome do titular/portador do perfil de pagamento
    - `registry_code` string: CPF ou CNPJ do titular/portador
    - `bank_branch` string: Agência da conta bancária
    - `bank_account` string: Número da conta bancária
    - `card_expiration` string: Validade do cartão de crédito no formato MM/AA
    - `allow_as_fallback` string: Permite utilizar o perfil de pagamento em retentativas de cobranças não pagas.
    - `card_number_first_six` string: Primeiros 6 dígitos do cartão de crédito (BIN/IIN)
    - `card_number_last_four` string: Últimos 4 dígitos do cartão de crédito
    - `renewed_card` object
      - `card_number_last_four` string: Últimos quatro dígitos do cartão de crédito renovado
      - `card_expiration` string: Nova validade do cartão de crédito renovado
    - `card_renewed_at` string: Data da renovação do cartão de crédito renovado
    - `token` string, required: Token interno para referência do perfil de pagamento
    - `created_at` string, required: Data e hora do cadastro do perfil de pagamento
    - `payment_company` PaymentCompany, required
      - `id` integer, required: ID da bandeira ou banco
      - `name` string, required: Nome da bandeira ou banco
      - `code` string, required: Código para referência via API
  - `payment_condition` PaymentCondition
    - `penalty_fee_value` number, required: Valor da multa
    - `penalty_fee_type` string, required: Tipo da multa
    - `daily_fee_value` number, required: Valor dos juros ao dia
    - `daily_fee_type` string, required: Tipo dos juros ao dia
    - `after_due_days` integer, required: Prazo para pagamento após vencimento
    - `payment_condition_discounts` PaymentConditionDiscount[], required: Desconto de pontualidade
      - `value` number, required: Valor
      - `value_type` 'percentage' | 'amount', required: Tipo
      - `days_before_due` integer, required: Dias antes do vencimento

## Other responses

- `400`: Erro de sintaxe JSON no corpo do request.
- `422`: Parâmetros inválidos. Verificar erro na resposta.

---

[API](https://skmtc.dev/vindi/apis/api-vindi.md) - [All operations](https://skmtc.dev/vindi/apis/api-vindi/llms.txt) - [OpenAPI document](https://skmtc.dev/vindi/apis/api-vindi/revisions/3e857e1cdd03?raw)