API atual/Referência completa/Pagamentos

Taxas de gateway

Quanto cada forma de pagamento custa à loja, usado para calcular o lucro real dos pedidos.

O gateway cobra uma taxa de cada transação (por exemplo, 2,5% mais R$ 1,50 no boleto). Cadastrar essas taxas faz o relatório de lucro mostrar o resultado depois do custo de pagamento. As taxas não são cobradas do cliente nem alteram o preço: servem só para análise.

Consultar taxas

Devolve a taxa que cada forma de pagamento custa à loja. Esses números alimentam o relatório de lucro real, que desconta a taxa do gateway da receita de cada pedido.

GET/api/v1/admin/payment-feesAdmin

Lista as taxas de gateway configuradas

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_reports. Requer o módulo analytics ativo.

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/payment-fees" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Taxas devolvidas

json

[
  {
    "payment_method": "boleto",
    "percent_bps": 250,
    "fixed_cents": 150
  }
]

A resposta é uma lista JSON (não um objeto), ordenada por payment_method. Vazia: [].

Campos da resposta

[].payment_methodstring

Código da forma de pagamento, como cadastrado na loja (por exemplo pix, boleto, credit_card).

[].percent_bpsinteger

Parte percentual da taxa, em pontos-base (250 = 2,5%).

[].fixed_centsinteger

Parte fixa da taxa por transação, em centavos.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"analytics"}` / `{"error":"insufficient privileges","required":"view_reports"}`
500	Falha na consulta	`{"error":"failed to list payment fees","detail":"..."}`

Substituir taxas

Grava as taxas e substitui o conjunto inteiro: formas de pagamento que não estiverem no corpo têm a taxa apagada.

PUT/api/v1/admin/payment-feesAdmin

Define as taxas de gateway

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_reports. Requer o módulo analytics ativo.

Corpo da requisição

[]arrayobrigatório

Lista de taxas. O corpo é uma lista JSON, não um objeto. Linhas com payment_method vazio são ignoradas.

[].payment_methodstringobrigatório

Código da forma de pagamento.

[].percent_bpsintegerpadrão: 0

Percentual em pontos-base.

[].fixed_centsintegerpadrão: 0

Parte fixa em centavos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/payment-fees" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "payment_method": "pix",
      "percent_bps": 99,
      "fixed_cents": 0
    },
    {
      "payment_method": "boleto",
      "percent_bps": 250,
      "fixed_cents": 150
    }
  ]'

Resposta

200Taxas gravadas

json

{
  "ok": true
}

Campos da resposta

okboolean

true quando gravou.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"analytics"}` / `{"error":"insufficient privileges","required":"view_reports"}`
400	Corpo que não é uma lista JSON válida	`{"error":"invalid body","detail":"..."}`
500	Falha ao gravar	`{"error":"failed to save payment fees","detail":"..."}`

Veja também

Transações e estornos

API atual/Referência completa/Pagamentos

Taxas de gateway

Quanto cada forma de pagamento custa à loja, usado para calcular o lucro real dos pedidos.

Consultar taxas

Devolve a taxa que cada forma de pagamento custa à loja. Esses números alimentam o relatório de lucro real, que desconta a taxa do gateway da receita de cada pedido.

GET/api/v1/admin/payment-feesAdmin

Lista as taxas de gateway configuradas

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_reports. Requer o módulo analytics ativo.

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/payment-fees" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Taxas devolvidas

json

[
  {
    "payment_method": "boleto",
    "percent_bps": 250,
    "fixed_cents": 150
  }
]

A resposta é uma lista JSON (não um objeto), ordenada por payment_method. Vazia: [].

Campos da resposta

[].payment_methodstring

Código da forma de pagamento, como cadastrado na loja (por exemplo pix, boleto, credit_card).

[].percent_bpsinteger

Parte percentual da taxa, em pontos-base (250 = 2,5%).

[].fixed_centsinteger

Parte fixa da taxa por transação, em centavos.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"analytics"}` / `{"error":"insufficient privileges","required":"view_reports"}`
500	Falha na consulta	`{"error":"failed to list payment fees","detail":"..."}`

Substituir taxas

Grava as taxas e substitui o conjunto inteiro: formas de pagamento que não estiverem no corpo têm a taxa apagada.

PUT/api/v1/admin/payment-feesAdmin

Define as taxas de gateway

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_reports. Requer o módulo analytics ativo.

Corpo da requisição

[]arrayobrigatório

Lista de taxas. O corpo é uma lista JSON, não um objeto. Linhas com payment_method vazio são ignoradas.

[].payment_methodstringobrigatório

Código da forma de pagamento.

[].percent_bpsintegerpadrão: 0

Percentual em pontos-base.

[].fixed_centsintegerpadrão: 0

Parte fixa em centavos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/payment-fees" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "payment_method": "pix",
      "percent_bps": 99,
      "fixed_cents": 0
    },
    {
      "payment_method": "boleto",
      "percent_bps": 250,
      "fixed_cents": 150
    }
  ]'

Resposta

200Taxas gravadas

json

{
  "ok": true
}

Campos da resposta

okboolean

true quando gravou.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"analytics"}` / `{"error":"insufficient privileges","required":"view_reports"}`
400	Corpo que não é uma lista JSON válida	`{"error":"invalid body","detail":"..."}`
500	Falha ao gravar	`{"error":"failed to save payment fees","detail":"..."}`

Veja também

Transações e estornos