Dados financeiros e auditoria

Consulta a auditoria de crédito, o histórico de pagamentos, o rateio entre sellers e o custo e lucro de um pedido.

Além do pedido em si, a plataforma guarda informações auxiliares que o financeiro, a auditoria e o atendimento consultam: como o limite de crédito do cliente foi usado, como o pagamento foi repartido entre os sellers, quanto custou e quanto lucrou. São rotas de leitura.

Duas delas pertencem a recursos opcionais da loja e respondem 403 module_disabled quando o recurso está desligado: o rateio de pagamento (payment-splits, recurso de pagamentos diretos) e o custo e lucro (custo-lucro). As demais valem para toda loja.

GET/api/v1/admin/orders/{id}/credit-auditAdmin

Auditoria do limite de crédito de um pedido

Mostra como o limite de crédito (compra a prazo, boleto faturado) do cliente foi consultado e abatido por este pedido: limite, usado e disponível antes e depois, a decisão e as tentativas de pagamento. Para pedidos antigos, o documento é reconstruído a partir do histórico do limite (reconstructed: true). Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{id}/payment-statisticsAdmin

Histórico de pagamentos do cliente em um pedido

Resume o histórico do comprador (identificado pelo cliente ou pelo e-mail do pedido): quantos pedidos válidos fez nos últimos 4 meses e nos últimos 5 anos. Só entram na contagem os pedidos que contam como receita. Atenção: late_payments hoje vem sempre 0, porque a plataforma ainda não apura atraso de pagamento; só orders_placed é calculado.

Path parameters

iduuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{orderID}/payment-splitsAdmin

Divisão do pagamento de um pedido entre sellers

Mostra como o valor pago foi repartido: a parte de cada seller e a comissão da loja (marketplace). Só existe quando a loja usa pagamentos diretos (split); sem o recurso responde 403.

Path parameters

orderIDuuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{id}/custo-lucroAdmin

Custo, lucro e margem de um pedido

Custo congelado no momento da venda, lucro e margem, por linha e para o pedido. Exige o recurso "Custo e Lucro" da loja.

Path parameters

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/credit-audit" -H "Authorization: Bearer $TOKEN"
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/payment-statistics" -H "Authorization: Bearer $TOKEN"
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/payment-splits" -H "Authorization: Bearer $TOKEN"

Resposta

200credit-audit

json

{
  "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
  "reconstructed": true,
  "payment_attempts": [],
  "credit_audit": {
    "version": 1,
    "source": "local_order_limits",
    "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
    "order_amount_cents": 12500,
    "payment_method": "boleto-faturado",
    "before": { "limit_cents": 50000, "used_cents": 10000, "available_cents": 40000 },
    "after": { "limit_cents": 50000, "used_cents": 22500, "available_cents": 27500 },
    "deducted_cents": 12500,
    "decision_allow": true,
    "decision_reason": "ok",
    "hash": "208f317f92130823065d55d7eed70a4558c61cc6fb4debe36cfb976223a4a79d"
  }
}

200payment-statistics

json

{
  "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
  "last_4_months": { "orders_placed": 3, "late_payments": 0 },
  "last_5_years": { "orders_placed": 11, "late_payments": 0 }
}

200payment-splits

json

{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "count": 1,
  "splits": [
    {
      "id": "6d1b0a2e-8f3b-4b9c-b3b6-0c2f9b1e7a55",
      "order_id": "0932405c-a8c1-49b3-a7db-61aab4c4d666",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "recipient_type": "vendor",
      "amount": 23241,
      "commission_amount": 2324,
      "status": "completed",
      "payment_method": "pix",
      "processed_at": "2026-10-11T21:00:00Z",
      "created_at": "2026-10-11T20:14:40Z"
    }
  ]
}

200custo-lucro

json

{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "revenue_cents": 190895,
  "cost_total_cents": 120000,
  "profit_cents": 70895,
  "margin_bps": 3713,
  "cost_known": true,
  "cost_partial": false,
  "lines_total": 2,
  "lines_costed": 2,
  "lines_missing_cost": 0,
  "lines_zero_cost": 0,
  "revenue_uncosted_cents": 0,
  "lines": [
    {
      "order_item_id": "04b62cb6-7421-41ed-9e27-4eb3c11343c4",
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "product_name": "Notebook Vintage Vermelho",
      "sku": "SD-004018-C",
      "quantity": 1,
      "unit_price_cents": 167895,
      "revenue_cents": 167895,
      "unit_cost_cents": 100000,
      "cogs_total_cents": 100000,
      "cost_known": true,
      "profit_cents": 67895,
      "margin_bps": 4044
    }
  ]
}

Campos da resposta

credit_auditobject

Documento da auditoria. Pode ser null quando o pedido não passou por controle de crédito (por exemplo, pagamento com cartão); nesse caso payment_attempts ainda traz as tentativas de pagamento.

credit_audit.beforeobject

Estado do limite antes do pedido: limit_cents, used_cents, available_cents, tudo em centavos.

credit_audit.afterobject

Estado do limite depois do pedido, com os mesmos campos.

credit_audit.deducted_centsinteger

Quanto do limite este pedido consumiu.

credit_audit.decision_allowboolean

Se o pedido foi liberado pelo controle de crédito.

credit_audit.decision_reasonstring

Motivo da decisão (ok quando liberado).

payment_attemptsarray

Tentativas de pagamento do pedido, da mais nova para a mais antiga: id, payment_method, provider, status, amount_cents, details, created_at, updated_at.

reconstructedboolean

true quando o documento foi remontado a partir do histórico do limite, e não gravado no momento do pedido.

last_4_monthsobject

orders_placed (pedidos válidos do comprador nos últimos 4 meses) e late_payments (sempre 0 por ora).

last_5_yearsobject

orders_placed (últimos 5 anos) e late_payments (sempre 0 por ora).

late_sourcestring

Texto de diagnóstico sobre a origem do cálculo. Não depende dele: o conteúdo muda e não faz parte do contrato.

splitsarray

Partes do pagamento. recipient_type é vendor ou marketplace; amount é o valor bruto e commission_amount a comissão da loja, ambos em centavos; status é pending, processing, completed, failed ou refunded.

revenue_centsinteger

(custo-lucro) Receita do pedido em centavos.

cost_total_centsinteger

(custo-lucro) Custo total das linhas com custo conhecido.

profit_centsinteger

(custo-lucro) Lucro em centavos. null quando nenhuma linha tem custo.

margin_bpsinteger

(custo-lucro) Margem em pontos-base (3713 = 37,13%). null sem custo.

cost_partialboolean

(custo-lucro) true quando só parte das linhas tem custo; o lucro, nesse caso, é parcial.

linesarray

(custo-lucro) Por linha: receita, custo unitário, custo total (cogs_total_cents), lucro e margem.

Erros

Status	Quando	Corpo
401	Sem token ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `view_orders`/`manage_orders`; ou o recurso opcional está desligado	`{"error":"insufficient privileges", ...}` ou `{"error":"module_disabled","module":"custo-e-lucro"}` (ou `direct-payments`)
404	Pedido inexistente (em `payment-splits`, um id inexistente devolve 200 com `count: 0`)	`{"error":"order not found"}`
500	Falha interna	`{"error":"failed to ..."}`

Veja também

Dados financeiros e auditoria

Consulta a auditoria de crédito, o histórico de pagamentos, o rateio entre sellers e o custo e lucro de um pedido.

GET/api/v1/admin/orders/{id}/credit-auditAdmin

Auditoria do limite de crédito de um pedido

Path parameters

iduuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{id}/payment-statisticsAdmin

Histórico de pagamentos do cliente em um pedido

Path parameters

iduuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{orderID}/payment-splitsAdmin

Divisão do pagamento de um pedido entre sellers

Mostra como o valor pago foi repartido: a parte de cada seller e a comissão da loja (marketplace). Só existe quando a loja usa pagamentos diretos (split); sem o recurso responde 403.

Path parameters

orderIDuuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{id}/custo-lucroAdmin

Custo, lucro e margem de um pedido

Custo congelado no momento da venda, lucro e margem, por linha e para o pedido. Exige o recurso "Custo e Lucro" da loja.

Path parameters

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/credit-audit" -H "Authorization: Bearer $TOKEN"
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/payment-statistics" -H "Authorization: Bearer $TOKEN"
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/payment-splits" -H "Authorization: Bearer $TOKEN"

Resposta

200credit-audit

json

{
  "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
  "reconstructed": true,
  "payment_attempts": [],
  "credit_audit": {
    "version": 1,
    "source": "local_order_limits",
    "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
    "order_amount_cents": 12500,
    "payment_method": "boleto-faturado",
    "before": { "limit_cents": 50000, "used_cents": 10000, "available_cents": 40000 },
    "after": { "limit_cents": 50000, "used_cents": 22500, "available_cents": 27500 },
    "deducted_cents": 12500,
    "decision_allow": true,
    "decision_reason": "ok",
    "hash": "208f317f92130823065d55d7eed70a4558c61cc6fb4debe36cfb976223a4a79d"
  }
}

200payment-statistics

json

{
  "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
  "last_4_months": { "orders_placed": 3, "late_payments": 0 },
  "last_5_years": { "orders_placed": 11, "late_payments": 0 }
}

200payment-splits

json

{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "count": 1,
  "splits": [
    {
      "id": "6d1b0a2e-8f3b-4b9c-b3b6-0c2f9b1e7a55",
      "order_id": "0932405c-a8c1-49b3-a7db-61aab4c4d666",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "recipient_type": "vendor",
      "amount": 23241,
      "commission_amount": 2324,
      "status": "completed",
      "payment_method": "pix",
      "processed_at": "2026-10-11T21:00:00Z",
      "created_at": "2026-10-11T20:14:40Z"
    }
  ]
}

200custo-lucro

json

{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "revenue_cents": 190895,
  "cost_total_cents": 120000,
  "profit_cents": 70895,
  "margin_bps": 3713,
  "cost_known": true,
  "cost_partial": false,
  "lines_total": 2,
  "lines_costed": 2,
  "lines_missing_cost": 0,
  "lines_zero_cost": 0,
  "revenue_uncosted_cents": 0,
  "lines": [
    {
      "order_item_id": "04b62cb6-7421-41ed-9e27-4eb3c11343c4",
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "product_name": "Notebook Vintage Vermelho",
      "sku": "SD-004018-C",
      "quantity": 1,
      "unit_price_cents": 167895,
      "revenue_cents": 167895,
      "unit_cost_cents": 100000,
      "cogs_total_cents": 100000,
      "cost_known": true,
      "profit_cents": 67895,
      "margin_bps": 4044
    }
  ]
}

Campos da resposta

credit_auditobject

Documento da auditoria. Pode ser null quando o pedido não passou por controle de crédito (por exemplo, pagamento com cartão); nesse caso payment_attempts ainda traz as tentativas de pagamento.

credit_audit.beforeobject

Estado do limite antes do pedido: limit_cents, used_cents, available_cents, tudo em centavos.

credit_audit.afterobject

Estado do limite depois do pedido, com os mesmos campos.

credit_audit.deducted_centsinteger

Quanto do limite este pedido consumiu.

credit_audit.decision_allowboolean

Se o pedido foi liberado pelo controle de crédito.

credit_audit.decision_reasonstring

Motivo da decisão (ok quando liberado).

payment_attemptsarray

Tentativas de pagamento do pedido, da mais nova para a mais antiga: id, payment_method, provider, status, amount_cents, details, created_at, updated_at.

reconstructedboolean

true quando o documento foi remontado a partir do histórico do limite, e não gravado no momento do pedido.

last_4_monthsobject

orders_placed (pedidos válidos do comprador nos últimos 4 meses) e late_payments (sempre 0 por ora).

last_5_yearsobject

orders_placed (últimos 5 anos) e late_payments (sempre 0 por ora).

late_sourcestring

Texto de diagnóstico sobre a origem do cálculo. Não depende dele: o conteúdo muda e não faz parte do contrato.

splitsarray

revenue_centsinteger

(custo-lucro) Receita do pedido em centavos.

cost_total_centsinteger

(custo-lucro) Custo total das linhas com custo conhecido.

profit_centsinteger

(custo-lucro) Lucro em centavos. null quando nenhuma linha tem custo.

margin_bpsinteger

(custo-lucro) Margem em pontos-base (3713 = 37,13%). null sem custo.

cost_partialboolean

(custo-lucro) true quando só parte das linhas tem custo; o lucro, nesse caso, é parcial.

linesarray

(custo-lucro) Por linha: receita, custo unitário, custo total (cogs_total_cents), lucro e margem.

Erros

Status	Quando	Corpo
401	Sem token ou token expirado	`{"error":"invalid or expired token"}`
403	Sem `view_orders`/`manage_orders`; ou o recurso opcional está desligado	`{"error":"insufficient privileges", ...}` ou `{"error":"module_disabled","module":"custo-e-lucro"}` (ou `direct-payments`)
404	Pedido inexistente (em `payment-splits`, um id inexistente devolve 200 com `count: 0`)	`{"error":"order not found"}`
500	Falha interna	`{"error":"failed to ..."}`