Criar fatura

POST 
/v1/invoices

Cria uma nova fatura.

Request

Query Parameters

expand string
Expande as referências.
Pode ser um valor único ou uma lista separada por vírgula (csv) de referências retornadas neste endpoint.
Example: data.loan
fields string

Permite especificar quais campos devem ser incluídos ou excluídos na resposta. Utilize o nome do campo para incluí-lo, ou prefixe o nome com um sinal de menos (-) para excluí-lo. Pode ser um valor único ou uma lista separada por vírgula(csv). Funciona para campos expandidos.

Esteja ciente de que especificar um campo para inclusão, terá o efeito que nenhum dos campos padrão seja retornado na resposta, a menos que seja explicitamente especificado.

Importante: Não é permitido combinar inclusões e exclusões na mesma requisição. Uma tentativa de fazê-lo resultará em um erro.

Examples:

inclusao

Retorna apenas os campos `id` e `createdAt`.

Example: id,createdAt

exclusao

Retorna todos os campos, exceto `id`.

Example: -id

Header Parameters

Idempotency-Key string
Chave única de idempotência para evitar duplicação de requisições.
Example: 5f92f01728e009f403d8502e
base39-external-client-id string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição.

application/json

Body

payer stringrequired

Responsável pelo pagamento. Pode ser um customer ou company.

beneficiary stringrequired

Fundo que vai receber o pagamento.

dueDate date

A data de vencimento da fatura.

type stringrequired
Tipo da fatura
Possible values: [pay_off, customer_recurring, company_recurring]
Example: pay_off
purpose string
Propósito da fatura
Possible values: [cancellation, customer_refinance, employment_terminated, external_collector, no_funds, regular, requested_by_company, requested_by_customer, requested_by_insurance]
Example: regular
description string

Uma string anexada ao objeto. Muitas vezes útil para exibição aos usuários.

items

object[]

Array [

installment string

Identificador que faz referência a uma parcela.

Example: inst_631a1f531a40784a5b1df6ed

amount double

Valor da parcela que será considerado como pago. Pode ser menor (para realizar pagamento parcial da parcela) ou igual ao valor original da parcela.

discount double

Valor do desconto que será dado na fatura referente a parcela informada

fine double

Valor da multa

interest double

Valor do juros

description string

Descrição do item.

purposeKey string

Chave de propósito do item da fatura.

metadata object

Conjunto de pares de valores-chave que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado.

]

autoFinalize boolean

Quando definido como true, executa o processo para finalizar a fatura no ato de criação, alterando o status para open ao final do processo. Se não informado ou definido como false, a fatura permanecerá com o status draft.

updateInvoiceItemOnInsert boolean
Sobrescrever configuração de desconto e multa no momento da criação dos itens da fatura. Este campo determina se, no momento da criação dos itens da fatura, descontos ou multas serão aplicados automaticamente aos itens de fatura enviados na requisição. Quando este campo é informado, o valor nele especificado substituirá o valor contido em settings.invoices[type].updateInvoiceItemOnInsert. É importante destacar que essa configuração apenas se aplica à requisição atual e não afetará as configurações existentes. Esse recurso foi desenvolvido com o propósito de substituir o parâmetro settings.invoices[type].updateInvoiceItemOnInsert pelo valor enviado na requisição.
Example: true
deductFineInterestFromAmount boolean
Quando definido como verdadeiro (true), caso a parcela esteja atrasada e o valor (amount) fornecido seja menor do que o valor restante (amountRemaining), os valores de multa (fine) e juros (interest) do item serão recalculados proporcionalmente ao valor pago (amount) e, então, deduzidos do valor do item, substituindo os três respectivos campos fornecidos na requisição pelos valores proporcionais calculados.
Example: true
paidAt date

Data de pagamento da fatura.

metadata object

Conjunto de pares de valores-chave que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado.

Responses

201

Retorna o objeto Invoice se a criação for bem-sucedida; caso contrário, um erro.

application/json

Schema

Schema

id string
Identificador exclusivo para o objeto.
Example: inv_5f92f01728e009f403d8502e
status string
Status da fatura
Possible values: [draft, open, paid, void, uncollectible, refunded]
Example: draft
payer string

Responsável pelo pagamento. Pode ser um customer ou company.

beneficiary string

Fundo que vai receber o pagamento.

dueDate date

A data de vencimento da fatura.

amountDue double
Valor devido.
Example: 200000
amountPaid double
Valor pago.
Example: 150050
amountRemaining double
Valor restante.
Example: 95000
type string
Tipo da fatura
Possible values: [pay_off, customer_recurring, company_recurring]
Example: pay_off
purpose string
Propósito da fatura
Possible values: [cancellation, customer_refinance, employment_terminated, external_collector, no_funds, regular, requested_by_company, requested_by_customer, requested_by_insurance]
Example: regular

invoiceItems

object

Contém grupos de parcelas na fatura tanto para o pagamento, como para antecipação.

url string

hasMore boolean

data

object[]

Uma lista de itens de invoice

Array [

id string

Identificador exclusivo para o objeto.

Example: item_5f92f01728e009f403d8502e

installment string

Identificador que faz referência a uma parcela.

Example: inst_631a1f531a40784a5b1df6ed

invoice string

Identificador que faz referência a uma fatura.

Example: inv_631a1f531a40784a4b0df5ed

amount double

Valor da parcela que será considerado como pago. Pode ser menor (para realizar pagamento parcial da parcela) ou igual ao valor original da parcela.

discount double

Valor do desconto que será dado na fatura referente a parcela informada

fine double

Valor da multa

interest double

Valor do juros

description string

Descrição do item.

purposeKey string

Chave de propósito do item da fatura.

metadata object

Conjunto de pares de valores-chave que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado.

createdAt date-time

Data de criação do objeto

Example: 2023-08-25T22:38:41.134Z

updatedAt date-time

Data de alteração do objeto

Example: 2023-08-25T22:38:41.134Z

deleted boolean

Identifica se o objeto foi excluído. Se verdadeiro, o objeto foi excluído.

Default value: false

Example: false

createdBy

object

clientId string

Identificador do cliente que criou a assinatura.

Example: client_identifier

externalClientId string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição. Populado pelo campo enviado no header base39-external-client-id.

app string

Nome da aplicação que criou a assinatura.

Example: backoffice

updatedBy

object

clientId string

Identificador do cliente que criou a assinatura.

Example: client_identifier

externalClientId string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição. Populado pelo campo enviado no header base39-external-client-id.

app string

Nome da aplicação que criou a assinatura.

Example: backoffice

]

paymentIntents

object

Representa um conjunto de intenções de pagamento.

hasMore boolean

data

object[]

Uma lista de inteções de pagamento

Array [

id string

Identificador exclusivo para o objeto.

Example: pi_5f92f01728e009f403d8502e

invoice string

Identificador que faz referência a uma fatura.

Example: inv_631a1f531a40784a4b0df5ed

status string

Possible values: [paid, void, open]

Default value: open

amount double

Valor da que deverá ser pago.

paymentDetails

object

paidAt date

amountPaid double

metadata object

expireAt date

method string

Possible values: [pix, boleto, offline, payment_method, loan]

Example: boleto

methodData

object

anyOf

boleto

externalId string

type stringrequired

Default value: boleto

provider string

Provedor utilizado para os boletos

Possible values: [kobana, default, test_only]

Example: kobana

description string

typeableLine string

url string

barcode string

ourNumber string

ourNumberRaw string

customer string

Example: cust_631a2a321a40784a4b0df641

events object[]

offline

type stringrequired

Default value: offline

description string

paymentMethod

type stringrequired

Default value: paymentMethod

paymentMethod stringrequired

Example: pm_631a2a321a40784a4b0df641

description string

loan

loan stringrequired

Example: loan_645122117022fa52620deb01

type stringrequired

Default value: loan

description string

metadata object

Conjunto de pares de valores-chave que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado.

createdAt date-time

Data de criação do objeto

Example: 2023-08-25T22:38:41.134Z

updatedAt date-time

Data de alteração do objeto

Example: 2023-08-25T22:38:41.134Z

createdBy

object

clientId string

Identificador do cliente que criou a assinatura.

Example: client_identifier

externalClientId string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição. Populado pelo campo enviado no header base39-external-client-id.

app string

Nome da aplicação que criou a assinatura.

Example: backoffice

updatedBy

object

clientId string

Identificador do cliente que criou a assinatura.

Example: client_identifier

externalClientId string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição. Populado pelo campo enviado no header base39-external-client-id.

app string

Nome da aplicação que criou a assinatura.

Example: backoffice

]

description string

Uma string anexada ao objeto. Muitas vezes útil para exibição aos usuários.

history

object[]

Array [

description string

createdAt date-time

status string

Status da fatura

Possible values: [draft, open, paid, void, uncollectible, refunded]

Example: draft

metadata object

Conjunto de pares de valores-chave que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado.

]

paidAt date

Data de pagamento da fatura.

metadata object

Conjunto de pares de valores-chave que podem ser anexados a um objeto. Isso pode ser útil para armazenar informações adicionais sobre o objeto em um formato estruturado.

createdAt date-time
Data de criação do objeto
Example: 2023-08-25T22:38:41.134Z
updatedAt date-time
Data de alteração do objeto
Example: 2023-08-25T22:38:41.134Z
deleted boolean
Identifica se o objeto foi excluído. Se verdadeiro, o objeto foi excluído.
Default value: false
Example: false

createdBy

object

clientId string

Identificador do cliente que criou a assinatura.

Example: client_identifier

externalClientId string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição. Populado pelo campo enviado no header base39-external-client-id.

app string

Nome da aplicação que criou a assinatura.

Example: backoffice

updatedBy

object

clientId string

Identificador do cliente que criou a assinatura.

Example: client_identifier

externalClientId string

Chave de identificação do cliente externo. Utilizada para identificar o cliente que está realizando a requisição. Populado pelo campo enviado no header base39-external-client-id.

app string

Nome da aplicação que criou a assinatura.

Example: backoffice

Example (from schema)

{
  "id": "inv_5f92f01728e009f403d8502e",
  "status": "draft",
  "payer": "string",
  "beneficiary": "string",
  "dueDate": "2024-07-29",
  "amountDue": 200000,
  "amountPaid": 150050,
  "amountRemaining": 95000,
  "type": "pay_off",
  "purpose": "regular",
  "invoiceItems": {
    "url": "string",
    "hasMore": true,
    "data": [
      {
        "id": "item_5f92f01728e009f403d8502e",
        "installment": "inst_631a1f531a40784a5b1df6ed",
        "invoice": "inv_631a1f531a40784a4b0df5ed",
        "amount": 0,
        "discount": 0,
        "fine": 0,
        "interest": 0,
        "description": "string",
        "purposeKey": "string",
        "metadata": {},
        "createdAt": "2023-08-25T22:38:41.134Z",
        "updatedAt": "2023-08-25T22:38:41.134Z",
        "deleted": false,
        "createdBy": {
          "clientId": "client_identifier",
          "externalClientId": "string",
          "app": "backoffice"
        },
        "updatedBy": {
          "clientId": "client_identifier",
          "externalClientId": "string",
          "app": "backoffice"
        }
      }
    ]
  },
  "paymentIntents": {
    "hasMore": true,
    "data": [
      {
        "id": "pi_5f92f01728e009f403d8502e",
        "invoice": "inv_631a1f531a40784a4b0df5ed",
        "status": "open",
        "amount": 0,
        "paymentDetails": {
          "paidAt": "2024-07-29",
          "amountPaid": 0,
          "metadata": {}
        },
        "expireAt": "2024-07-29",
        "method": "boleto",
        "metadata": {},
        "createdAt": "2023-08-25T22:38:41.134Z",
        "updatedAt": "2023-08-25T22:38:41.134Z",
        "createdBy": {
          "clientId": "client_identifier",
          "externalClientId": "string",
          "app": "backoffice"
        },
        "updatedBy": {
          "clientId": "client_identifier",
          "externalClientId": "string",
          "app": "backoffice"
        }
      }
    ]
  },
  "description": "string",
  "history": [
    {
      "description": "string",
      "createdAt": "2024-07-29T15:51:28.071Z",
      "status": "draft",
      "metadata": {}
    }
  ],
  "paidAt": "2024-07-29",
  "metadata": {},
  "createdAt": "2023-08-25T22:38:41.134Z",
  "updatedAt": "2023-08-25T22:38:41.134Z",
  "deleted": false,
  "createdBy": {
    "clientId": "client_identifier",
    "externalClientId": "string",
    "app": "backoffice"
  },
  "updatedBy": {
    "clientId": "client_identifier",
    "externalClientId": "string",
    "app": "backoffice"
  }
}

Loading...