Estrutura da cobrança

Uma Cobrança (Payable) representa uma parcela individual de uma venda. Cada venda pode gerar N cobrânças (uma por parcela).

{
  "id": "698b8a825eaf8de7c5af246d",
  "code": "LP-P444M-LANGG-4",
  "saleId": "698b8a805eaf8de7c5af1cb9",
  "saleCode": "LP-P444M-LANGG",
  "saleKind": "order",
  "saleContext": {
    "entity": "698b8a805eaf8de7c5af1cb9"
  },
  "saleGroupId": "000000000000000000000001",
  "marketplaceId": null,
  "installment": 4,
  "totalInstallments": 5,
  "price": {
    "amount": 4000,
    "currency": "BRL"
  },
  "originalPrice": {
    "amount": 4000,
    "currency": "BRL"
  },
  "balance": null,
  "paid": false,
  "paidWith": "credit_card",
  "nsu": null,
  "status": "open",
  "statusChangedAt": "2026-02-10T19:44:03.149Z",
  "statusTransitions": {
    "open": "2026-02-10T19:44:03.149Z"
  },
  "dueAt": "2026-05-10T19:44:02.402Z",
  "originalDueAt": "2026-05-10T19:44:02.402Z",
  "currency": "BRL",
  "tags": ["open"],
  "attempts": 0,
  "hasManualUpdate": false,
  "community": "test",
  "createdAt": "2026-02-10T19:44:02.328Z",
  "updatedAt": "2026-02-12T20:46:11.133Z",
  "customer": {...},
  "items": [...],
  "recipients": [...],
  "integration": {...}
}

Campos principais

Campo	Tipo	Descrição
id	string	ID único da cobrança
code	string	Código único legível da cobrança. Ex: LP-P444M-LANGG-4
saleId	string	Identificador da venda associada
saleCode	string	Código da venda. Ex: LP-P444M-LANGG
saleKind	string	Tipo da venda. Valores possíveis: order, recurrence, subscription, commission
saleGroupId	string | null	ID do grupo de vendas (quando faz parte de um grupo)
marketplaceId	string | null	ID do marketplace de origem. Caso não aplicável, null
installment	integer	Número da parcela atual (ex: 1, 2, 3)
totalInstallments	integer	Número total de parcelas da venda
price	object	Preço atual da cobrança
originalPrice	object	Preço original antes de alterações
balance	object | null	Saldo restante. Caso não aplicável, null
paid	boolean	Indica se a cobrança foi paga
paidWith	string | null	Método de pagamento utilizado. Valores possíveis: bank_slip, credit_card, pix, multi_card, bolepix. Caso não pago, null
nsu	string | null	Código de autorização (NSU). Caso não aplicável, null
status	string	Status atual da cobrança. Valores possíveis: open, pending, paid, released, late, expired, failed, canceled, refunded, chargeback, in_protest
statusChangedAt	string (ISO 8601)	Data e hora da última mudança de status
dueAt	string (ISO 8601)	Data de vencimento atual
originalDueAt	string (ISO 8601)	Data de vencimento original (salva na criação)
currency	string	Moeda no formato ISO 4217. Ex: BRL
tags	array<string>	Tags descritivas (inclui todos os statuses pelos quais já passou)
attempts	integer	Número de tentativas de cobrança
hasManualUpdate	boolean	Indica se teve atualização manual (bloqueia cobranças automáticas)
community	string	Comunidade (tenant)
createdAt	string (ISO 8601)	Data e hora de criação
updatedAt	string (ISO 8601)	Data e hora da última atualização
saleContext	object	Contexto da venda (ver abaixo)

---

saleContext

Informações sobre o contexto da venda associada à cobrança.

"saleContext": {
  "kind": "order",
  "entity": "698b8a805eaf8de7c5af1cb9"
}

Campo	Tipo	Descrição
kind	string	Tipo do contexto da venda
entity	string	Referência ao channel/entidade da venda

---

customer

Dados do cliente associado à cobrança.

"customer": {
  "name": "Some name",
  "email": "test@tenda.digital",
  "phone": "(11) 91123-1233",
  "birth": "2026-02-10T19:44:01.217Z",
  "token": "3eef5671-a707-45ef-8c8a-d825e3ddd3d0",
  "document": {
    "kind": "cpf",
    "value": "545.537.435-40"
  },
  "address": {
    "address": null,
    "number": "875",
    "address2": null,
    "district": null,
    "city": null,
    "state": null,
    "country": "BR",
    "code": "09510112"
  }
}

Campo	Tipo	Descrição
name	string	Nome completo do cliente
email	string	Endereço de e-mail do cliente
phone	string | null	Número de telefone do cliente. Caso não informado, null
birth	string (ISO 8601) | null	Data de nascimento do cliente. Caso não informado, null
token	string | null	Token de pagamento. Caso não informado, null
document.kind	string	Tipo do documento. Valores possíveis: cpf, cnpj
document.value	string	Número do documento
address.address	string | null	Logradouro. Caso não informado, null
address.number	string | null	Número. Caso não informado, null
address.address2	string | null	Complemento. Caso não informado, null
address.district	string | null	Bairro. Caso não informado, null
address.city	string | null	Cidade. Caso não informado, null
address.state	string | null	Estado (UF). Caso não informado, null
address.country	string	País no formato ISO 3166-1 alpha-2. Ex: BR
address.code	string | null	CEP. Caso não informado, null

---

items

Lista de produtos vinculados à cobrança. Nota, esse objeto items não é o mesmo objeto que obtemos de uma rota /items/{id}

"items": [
  {
    "lineItemId": "698b8a815eaf8de7c5af1f7b",
    "itemKind": "product",
    "name": "My at once product",
    "caption": "Branco | 1kg",
    "quantity": 2,
    "variantId": "0001",
    "price": {
      "amount": 10000,
      "currency": "BRL"
    },
    "subtotal": {
      "amount": 4000,
      "currency": "BRL"
    },
    "media": {
      "url": "https://cdn.layers.digital/uploads/.../bitmap@3x.png",
      "path": "/uploads/.../bitmap@3x.png",
      "mime": "image/png",
      "width": 456,
      "height": 783,
      "size": 379264,
      "name": "bitmap@3x.png",
      "orientation": null
    }
  }
]

Campo	Tipo	Descrição
lineItemId	string	Identificador do item de linha
itemKind	string	Tipo do item. Valores possíveis: product, service
name	string	Nome do item
caption	string	Descrição curta do item com atributos. Ex: Branco | 1kg
quantity	integer	Quantidade
variantId	string	Identificador da variante do produto
price.amount	integer	Valor unitário em centavos
price.currency	string	Moeda no formato ISO 4217
subtotal.amount	integer	Valor total do item em centavos (price × quantity)
subtotal.currency	string	Moeda no formato ISO 4217
media.url	string	URL pública da imagem do item
media.path	string	Caminho interno da imagem
media.mime	string	Tipo MIME da imagem. Ex: image/png, image/jpeg
media.width	integer	Largura da imagem em pixels
media.height	integer	Altura da imagem em pixels
media.size	integer	Tamanho do arquivo em bytes
media.name	string	Nome do arquivo da imagem
media.orientation	string | null	Orientação da imagem. Caso não informada, null

---

recipients

Lista de destinatários do split de pagamento da cobrança.

"recipients": [
  {
    "sourceId": "698b8a805eaf8de7c5af1ccd",
    "options": {
      "liable": true,
      "chargeProcessingFee": true,
      "chargeRemainder": true,
      "chargeLayersFee": false
    },
    "itemsInfo": [
      {
        "itemId": "5be99fd8dd405c6c7acfc0c4",
        "name": "My at once product",
        "splitValue": 100,
        "splitKind": "percent"
      }
    ],
    "items": {
      "amount": 4000,
      "currency": "BRL"
    },
    "discounts": {
      "amount": 0,
      "currency": "BRL"
    },
    "taxes": {
      "amount": 0,
      "currency": "BRL"
    },
    "shipping": {
      "amount": 0,
      "currency": "BRL"
    },
    "total": {
      "amount": 4000,
      "currency": "BRL"
    }
  }
]

Campo	Tipo	Descrição
sourceId	string	Identificador do recebedor
options.liable	boolean	Indica se é responsável pelos valores
options.chargeProcessingFee	boolean	Indica se será cobrada taxa de processamento
options.chargeRemainder	boolean	Indica se absorve o resto da divisão
options.chargeLayersFee	boolean	Indica se será cobrada taxa da Layers
itemsInfo	array	Informações de split por item
itemsInfo[].itemId	string	ID do item
itemsInfo[].name	string	Nome do item
itemsInfo[].splitValue	number	Valor ou percentual do split
itemsInfo[].splitKind	string	Tipo do split. Valores possíveis: flat, percent
items.amount	integer	Valor dos itens em centavos
items.currency	string	Moeda no formato ISO 4217
discounts.amount	integer	Valor de descontos em centavos
discounts.currency	string	Moeda no formato ISO 4217
taxes.amount	integer	Valor de impostos em centavos
taxes.currency	string	Moeda no formato ISO 4217
shipping.amount	integer	Valor de frete em centavos
shipping.currency	string	Moeda no formato ISO 4217
total.amount	integer	Valor total a receber em centavos
total.currency	string	Moeda no formato ISO 4217

---

integration

Status da integração da cobrança com sistemas contábeis externos.

"integration": {
  "status": "not_integrated",
  "statusChangedAt": "2026-02-10T19:44:03.149Z",
  "externalIdentifiers": [],
  "assignee": "DEFAULT_ASSIGNEE"
}

Campo	Tipo	Descrição
status	string	Status da integração. Valores possíveis: not_integrated, pending, integrated, approved, received, failed, ignored, invoiced
statusChangedAt	string (ISO 8601)	Data e hora da última alteração de status
externalIdentifiers	array<string>	Identificadores da cobrança em sistemas externos
assignee	string | null	Responsável pela integração

---

Statuses

Ordenados por prioridade (mais importante primeiro):

Valores possíveis: refunded, chargeback, in_protest, released, paid, pending, late, expired, failed, canceled, open

Status	Descrição
refunded	Reembolsado
chargeback	Chargeback (contestação)
in_protest	Em protesto
released	Valor liberado para saque
paid	Pago, aguardando liberação
pending	Aguardando pagamento
late	Vencido (atrasado)
expired	Expirado (janela de pagamento fechou)
failed	Falhou
canceled	Cancelado
open	Aberto (ainda não venceu, status inicial)

---

statusTransitions

Histórico de todas as transições de status da cobrança.

"statusTransitions": {
  "open": "2026-02-10T19:44:03.149Z"
}

Campo	Tipo	Descrição
[status]	string (ISO 8601)	Data e hora em que a cobrança atingiu cada status. A chave é o nome do status