Crédito e pagamento

Consulte limite de crédito, títulos vencidos, prazo e promoções de um cliente B2B, e entenda a regra de formas de pagamento que a sincronização por CNPJ grava.

Em vendas B2B, o cliente não é só alguém que paga no ato: ele tem um limite de crédito, um prazo e, muitas vezes, uma lista própria de formas de pagamento liberadas ou bloqueadas. Esta página reúne o que a API oferece sobre isso.

Há duas partes bem diferentes:

Consultas financeiras (/api/v1.0/customers/{id}/...): quatro leituras que um ERP ou o app do vendedor usam. Duas delas (overdue-titles e payment-term) são valores fixos, ainda sem dados reais; as outras duas (credit-limit e promotions) são reais.
Formas de pagamento por cliente: a regra "este cliente só pode pagar por tal forma" ou "este cliente não pode usar tal forma". O checkout aplica a regra, e você a grava pela Sincronização por CNPJ.

As consultas financeiras mostram dados financeiros: exigem um administrador (promotions também aceita o próprio cliente consultando o próprio id). Valores em dinheiro são strings decimais ("1500.00").

GET/api/v1.0/customers/{id}/credit-limitAdmin

Limite de crédito de um cliente

Soma os limites de crédito do cliente e mostra o quanto já foi usado e o quanto resta, no total e por seller. O limite é definido por cliente e por seller (o limite de um seller não vale para outro). Cliente sem limite devolve tudo "0.00" e vendors vazio. Também responde em /api/customers/{id}/credit-limit.

Parâmetros de caminho

idstringobrigatório

Id do cliente (UUID; na rota sem versão, o id decimal).

200Limite do cliente

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "credit_limit": "5000.00",
  "available": "3200.00",
  "used": "1800.00",
  "currency": "BRL",
  "vendors": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "limit": "5000.00", "available": "3200.00", "used": "1800.00" }
  ]
}

Campos da resposta

credit_limitstring

Soma dos limites, string decimal.

availablestring

Soma do que ainda pode ser usado.

usedstring

credit_limit menos available.

currencystring

Sempre BRL.

vendorsarray

Um item por seller com limite: vendor_id (UUID do seller; vazio para um limite geral da loja), limit, available e used.

GET/api/v1.0/customers/{id}/overdue-titlesAdmin

Títulos vencidos de um cliente (provisória)

Os títulos (boletos, duplicatas) vencidos e não pagos do cliente. Ainda não há contas a receber na plataforma: a resposta é sempre uma lista vazia e total zero. A rota existe para que o cliente da API 1.0 receba um formato estável; trate a lista vazia como "sem informação", não como "sem dívidas". Também responde em /api/customers/{id}/overdue-titles.

Parâmetros de caminho

idstringobrigatório

Id do cliente.

200Sem títulos

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "overdue_titles": [],
  "total_overdue": "0.00",
  "count": 0
}

GET/api/v1.0/customers/{id}/payment-termAdmin

Prazo de pagamento de um cliente (provisória)

O prazo de pagamento do cliente. Ainda não há prazo por cliente: todo cliente recebe o padrão "À vista". Não use a resposta para decidir faturamento a prazo. Também responde em /api/customers/{id}/payment-term.

Parâmetros de caminho

idstringobrigatório

Id do cliente.

200Prazo padrão

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "payment_term_id": null,
  "payment_term_name": "À vista",
  "days": 0,
  "installments": 1,
  "is_default": true
}

GET/api/v1.0/customers/{id}/promotionsAdmin

Promoções ativas vistas por um cliente

Lista as promoções ativas da loja. Não é filtrada por cliente: todos os clientes recebem a mesma lista. Pode ser chamada por um administrador ou pelo próprio cliente (com o próprio id); só o administrador vê o campo code (cupom). Também responde em /api/customers/{id}/promotions.

Parâmetros de caminho

idstringobrigatório

Id do cliente.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

200Promoções ativas

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "promotions": [
    {
      "id": "45646519-bcd1-4b6d-b341-2f94da1cbe2e",
      "name": "Recuperação de carrinho",
      "type": "percentage",
      "discount_bps": 2400,
      "min_cart": "",
      "code": "VOLTE-24",
      "valid_until": "2026-10-12T18:01:41Z"
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 76 }
}

Campos da resposta

promotions[].typestring

Tipo da promoção (percentage, fixed, free_shipping, buy_x_get_y).

promotions[].discount_bpsinteger

Desconto. Em promoção percentage, em pontos-base (2400 = 24%); em fixed, em centavos.

promotions[].min_cartstring

Sempre vazio. O valor mínimo do carrinho não é exposto aqui.

promotions[].codestring

Código do cupom, quando existe. Só para administrador.

promotions[].valid_untilstring

Fim da validade (RFC 3339), quando existe.

paramsobject

Paginação: page, items_per_page, total_items.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/customers/3dc023ca-3746-4b6e-8afd-686a4a9af99f/credit-limit"

Formas de pagamento por cliente

Cada cliente pode ter uma regra própria sobre as formas de pagamento da loja. A regra é uma lista de pares (forma de pagamento, A ou D), gravada pelo campo payments da Sincronização por CNPJ:

Regra gravada	Modo	Efeito no checkout
Nenhuma	`none`	O cliente vê todas as formas que a loja oferece.
Só linhas `D`	`blacklist`	Vê todas, menos as marcadas `D`.
Ao menos uma linha `A`	`whitelist`	Vê somente as marcadas `A`. As demais ficam bloqueadas.

Atenção ao segundo caso: basta uma linha A para o cliente passar a ver só aquela forma. As formas são as da loja e as dos sellers.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador (consultas financeiras)	`{"message":"Forbidden: financial data requires admin scope","status":403}`

Veja também

Crédito e pagamento

Consulte limite de crédito, títulos vencidos, prazo e promoções de um cliente B2B, e entenda a regra de formas de pagamento que a sincronização por CNPJ grava.

Há duas partes bem diferentes:

Consultas financeiras (/api/v1.0/customers/{id}/...): quatro leituras que um ERP ou o app do vendedor usam. Duas delas (overdue-titles e payment-term) são valores fixos, ainda sem dados reais; as outras duas (credit-limit e promotions) são reais.
Formas de pagamento por cliente: a regra "este cliente só pode pagar por tal forma" ou "este cliente não pode usar tal forma". O checkout aplica a regra, e você a grava pela Sincronização por CNPJ.

GET/api/v1.0/customers/{id}/credit-limitAdmin

Limite de crédito de um cliente

Parâmetros de caminho

idstringobrigatório

Id do cliente (UUID; na rota sem versão, o id decimal).

200Limite do cliente

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "credit_limit": "5000.00",
  "available": "3200.00",
  "used": "1800.00",
  "currency": "BRL",
  "vendors": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "limit": "5000.00", "available": "3200.00", "used": "1800.00" }
  ]
}

Campos da resposta

credit_limitstring

Soma dos limites, string decimal.

availablestring

Soma do que ainda pode ser usado.

usedstring

credit_limit menos available.

currencystring

Sempre BRL.

vendorsarray

Um item por seller com limite: vendor_id (UUID do seller; vazio para um limite geral da loja), limit, available e used.

GET/api/v1.0/customers/{id}/overdue-titlesAdmin

Títulos vencidos de um cliente (provisória)

Parâmetros de caminho

idstringobrigatório

Id do cliente.

200Sem títulos

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "overdue_titles": [],
  "total_overdue": "0.00",
  "count": 0
}

GET/api/v1.0/customers/{id}/payment-termAdmin

Prazo de pagamento de um cliente (provisória)

Parâmetros de caminho

idstringobrigatório

Id do cliente.

200Prazo padrão

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "payment_term_id": null,
  "payment_term_name": "À vista",
  "days": 0,
  "installments": 1,
  "is_default": true
}

GET/api/v1.0/customers/{id}/promotionsAdmin

Promoções ativas vistas por um cliente

Parâmetros de caminho

idstringobrigatório

Id do cliente.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250.

200Promoções ativas

json

{
  "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
  "promotions": [
    {
      "id": "45646519-bcd1-4b6d-b341-2f94da1cbe2e",
      "name": "Recuperação de carrinho",
      "type": "percentage",
      "discount_bps": 2400,
      "min_cart": "",
      "code": "VOLTE-24",
      "valid_until": "2026-10-12T18:01:41Z"
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 76 }
}

Campos da resposta

promotions[].typestring

Tipo da promoção (percentage, fixed, free_shipping, buy_x_get_y).

promotions[].discount_bpsinteger

Desconto. Em promoção percentage, em pontos-base (2400 = 24%); em fixed, em centavos.

promotions[].min_cartstring

Sempre vazio. O valor mínimo do carrinho não é exposto aqui.

promotions[].codestring

Código do cupom, quando existe. Só para administrador.

promotions[].valid_untilstring

Fim da validade (RFC 3339), quando existe.

paramsobject

Paginação: page, items_per_page, total_items.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/customers/3dc023ca-3746-4b6e-8afd-686a4a9af99f/credit-limit"

Formas de pagamento por cliente

Regra gravada	Modo	Efeito no checkout
Nenhuma	`none`	O cliente vê todas as formas que a loja oferece.
Só linhas `D`	`blacklist`	Vê todas, menos as marcadas `D`.
Ao menos uma linha `A`	`whitelist`	Vê somente as marcadas `A`. As demais ficam bloqueadas.

Atenção ao segundo caso: basta uma linha A para o cliente passar a ver só aquela forma. As formas são as da loja e as dos sellers.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave inválida ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador (consultas financeiras)	`{"message":"Forbidden: financial data requires admin scope","status":403}`