VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/Equipe de campo

Conta-corrente do representante

Lê o extrato e o saldo de crédito de um representante e faz lançamentos manuais de crédito ou de redução.

Cada representante comercial tem uma conta-corrente de crédito para desconto: é o saldo que ele pode gastar dando desconto aos clientes. A cada desconto concedido em um pedido, o valor é debitado; a empresa também pode creditar ou reduzir o saldo à mão. A comissão do representante entra no extrato, mas não altera o saldo.

GET devolve o extrato (os lançamentos, do mais novo para o mais antigo) e o saldo atual. POST faz um lançamento manual. Os dois exigem um usuário administrador.

Lançamento manual é permanente

Não existe rota para apagar ou estornar um lançamento. Para corrigir um erro, faça o lançamento contrário. Cada lançamento fica no extrato com a descrição manual.

GET/api/v1.0/manager_transactionsAdmin

Venddor 1.0: extrato e saldo de um representante

Identifique o representante por um dos três parâmetros. Se mais de um vier, vale a ordem manager_id, internal_code, user_id.

Parâmetros de consulta

manager_idstring
Id do representante (inteiro).
internal_codestring
Código interno do representante (por exemplo REP-001).
user_idstring
Id do usuário da loja que é o representante.
typestring
CD
C mostra só as comissões, D só os descontos concedidos em pedidos. Os lançamentos manuais não entram em nenhum dos dois filtros; sem type aparecem todos.
pageintegerpadrão: 1
Página.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 100. De 101 a 250 volta ao padrão de 20 (o campo search.items_per_page mostra o valor usado).
POST/api/v1.0/manager_transactionsAdmin

Venddor 1.0: lançar crédito ou redução na conta de um representante

Soma ou subtrai um valor do saldo de crédito. Identifique o representante no corpo, pelos mesmos três campos do extrato (mesma ordem de prioridade).

Corpo da requisição

amountnumberobrigatório
Valor em reais, como número (12.5). Não pode ser zero. Um valor negativo é tratado como positivo. Use no máximo duas casas decimais.
scopestringobrigatório
A soma ao saldo (aceita também a). Qualquer outro texto, como R, subtrai.
manager_idstring
Id do representante (inteiro, texto ou número).
internal_codestring
Código interno do representante.
user_idstring
Id do usuário da loja que é o representante.
GET/api/manager_transactionsAdmin

Extrato e saldo de um representante, forma sem versão

Igual a GET /api/v1.0/manager_transactions. Os parâmetros são os mesmos.

Parâmetros de consulta

manager_idstring
Id do representante.
internal_codestring
Código interno do representante.
user_idstring
Id do usuário do representante.
typestring
CD
Filtro de comissões (C) ou descontos (D).
pageintegerpadrão: 1
Página.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 100.
POST/api/manager_transactionsAdmin

Lançar crédito ou redução, forma sem versão

Igual a POST /api/v1.0/manager_transactions, com o mesmo corpo.

Corpo da requisição

amountnumberobrigatório
Valor em reais, como número.
scopestringobrigatório
A soma; qualquer outro texto subtrai.
manager_idstring
Id do representante.
internal_codestring
Código interno do representante.
user_idstring
Id do usuário do representante.

Exemplo de requisição

bash
# extrato
curl "$BASE_URL/api/v1.0/manager_transactions?manager_id=2&items_per_page=20" \
  -u "$ADMIN_EMAIL:$API_KEY"

# creditar R$ 50,00
curl -X POST "$BASE_URL/api/v1.0/manager_transactions" \
  -u "$ADMIN_EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":50,"scope":"A","manager_id":2}'

Resposta

200Extrato
json
{
  "success": true,
  "message": "",
  "balance": "150.00",
  "transactions": [
    {
      "transaction_id": "41",
      "manager_id": "2",
      "type": "C",
      "object_type": "O",
      "object_id": "",
      "amount": "50.00",
      "balance": "150.00",
      "timestamp": 1791749845,
      "description": "manual"
    }
  ],
  "search": { "page": 1, "items_per_page": 10, "total_items": 1 }
}
200Lançamento feito
json
{
  "success": true,
  "result": { "transaction_id": 41, "balance": "150.00", "timestamp": 1791749845 },
  "message": ""
}

Campos da resposta

successboolean
true quando a chamada foi processada. No lançamento, true não garante que houve lançamento: confira result.
messagestring
Vazio no sucesso. user not found quando o representante não foi encontrado.
balancestring
(Extrato) Saldo de crédito atual, em reais, string decimal. Não depende da página nem do filtro type.
transactions[].transaction_idstring
Id do lançamento.
transactions[].manager_idstring
Id do representante.
transactions[].typestring
CD
C quando o valor soma (crédito ou comissão), D quando subtrai (desconto ou redução manual).
transactions[].object_typestring
Sempre O.
transactions[].object_idstring
Id do pedido que originou o lançamento. Vazio nos lançamentos manuais.
transactions[].amountstring
Valor do lançamento, sempre positivo, em reais.
transactions[].balancestring
Saldo logo depois deste lançamento.
transactions[].timestampinteger
Momento do lançamento, Unix timestamp em segundos.
transactions[].descriptionstring
Descrição. manual nos lançamentos feitos por esta rota.
searchobject
Paginação: page, items_per_page e total_items.
resultobject
(Lançamento) transaction_id (número), balance (saldo depois do lançamento, em string decimal) e timestamp. É null quando o representante não foi encontrado.

Erros

StatusQuandoCorpo
200(extrato) manager_id que não é número, internal_code/user_id sem representante, ou nenhum identificador: lista vazia e saldo "0.00"{"success":true,"message":"","transactions":[],"balance":"0.00", ...}
200(lançamento) identificador que não é número, ou internal_code/user_id sem representante{"success":true,"result":null,"message":"user not found"}
400Corpo que não é JSON, ou amount enviado como texto{"message":"Invalid JSON body","status":400}
400amount ausente ou zero{"message":"amount is required","status":400}
400amount menor que 0,01 (vira 0 centavos){"message":"amount must be positive","status":400}
400scope ausente{"message":"scope is required (A=add, R=reduce)","status":400}
400Redução maior que o saldo{"message":"insufficient credit balance","status":400}
400(lançamento) manager_id numérico que não existe{"message":"trade rep not found","status":400}
401Sem credenciais, chave inválida ou token expirado{"message":"Invalid credentials","status":401}
403Usuário que não é administrador{"message":"Forbidden: admin scope required","status":403}
500(extrato) manager_id numérico que não existe{"message":"trade rep not found","status":500}
O mesmo erro de representante tem três respostas diferentes

Um representante que não existe responde de três jeitos, conforme o caso: lista vazia com HTTP 200 (id que não é número), 500 no extrato e 400 no lançamento (número que não existe), ou 200 com result: null (lançamento com id que não é número). Trate result: null, transactions vazio e saldo "0.00" com desconfiança antes de concluir que o representante não tem movimento.

Duas casas decimais, sempre

O valor é convertido para centavos multiplicando por 100 e descartando a fração. Valores como 4.35 podem ser gravados como 4.34 por causa da representação decimal em ponto flutuante. Para ter certeza, mande valores que terminem em .00, .25, .50 e .75, ou confira o balance devolvido.

Veja também

  • Nome alternativo da conta-corrente
  • Check-ins de visita
Anterior
Nomes alternativos dos check-ins
Próxima
Nome alternativo da conta-corrente
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também