Ir para o conteúdo

4.6. Totais da agenda

🔗 Endpoint

Método URL
GET /public/api/v1.1/cartao/agendas/{idAgenda}/totais

🧾 Descrição

Retorna os totais consolidados das URs de uma agenda: quanto existe, quanto está onerado, quanto está livre, quanto pode efetivamente ser alocado e quanto já está sendo utilizado pelo carrinho.

Aceita os mesmos filtros de 4.4. Listar URs da agenda. Isso permite dimensionar um recorte da agenda sem paginar a lista inteira: os totais correspondem exatamente ao conjunto de URs que a listagem devolveria com os mesmos parâmetros.

📤 Requisição

🧭 Parâmetros de rota

Parâmetro Tipo Obrigatório Descrição
idAgenda string Sim GUID da agenda, devolvido em 4.1. Solicitar agenda.

🔎 Query params

Parâmetro Tipo Obrigatório Descrição
dataLiquidacaoInicio string Não Considera URs com dataPrevistaLiquidacao maior ou igual à data informada (YYYY-MM-DD).
dataLiquidacaoFim string Não Considera URs com dataPrevistaLiquidacao menor ou igual à data informada (YYYY-MM-DD).
siglaArranjo string Não Sigla do arranjo de pagamento (ex.: MCC, VCC, ECC).
cnpjCredenciadora string Não CNPJ da credenciadora, somente dígitos.
possuiValorLivre boolean Não true considera apenas URs com valorLivre maior que zero; false apenas URs totalmente comprometidas.
possuiEfeitoTerceiros boolean Não true considera apenas URs com ao menos um ônus de terceiro (inclusive promessa de cessão); false apenas URs sem ônus de terceiro.

Regras e formatos

  • Datas no formato YYYY-MM-DD.
  • Sem filtros, o retorno cobre toda a agenda.
  • Este endpoint não é paginado — os parâmetros indicePagina, tamanhoDaPagina, ordem e direcaoOrdem não se aplicam.

🧪 Exemplo de cURL

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/totais?dataLiquidacaoInicio=2025-08-09&dataLiquidacaoFim=2025-08-31&siglaArranjo=MCC&possuiValorLivre=true" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

📥 Responses

✅ 200 OK

{
  "constituido": 480000.00,
  "comprometido": 96000.00,
  "livre": 384000.00,
  "disponivel": 268800.00,
  "garantido": 45000.00,
  "quantidadeUrs": 47,
  "prazoMedio": 22
}

🧾 Detalhamento dos Campos

Campo Tipo Descrição
constituido number Soma do valorConstituido das URs consideradas — o que as registradoras informam que existe.
comprometido number Soma do valorComprometido — a parte já onerada, por contratos próprios ou de terceiros.
livre number Soma do valorLivre — o que sobra para uso (constituido - comprometido).
disponivel number Soma do valorDisponivel — o livre já descontado o percentual máximo por UR configurado na operação. É o teto real de alocação no carrinho.
garantido number Soma do valorGarantido — quanto das URs já está sendo utilizado pelos itens do carrinho.
quantidadeUrs integer Quantidade de URs consideradas no recorte.
prazoMedio integer Prazo médio em dias, ponderado pelo valor, entre a data da consulta e as datas previstas de liquidação das URs consideradas.

Leia sempre disponivel como o número que importa para montar carrinho, e livre como o número que importa para entender a agenda. A diferença entre os dois é a trava de percentual máximo por UR da operação — não é ônus.

❌ 400 Bad Request

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'dataLiquidacaoFim' inválido. Formato esperado: YYYY-MM-DD.",
    "Campo 'cnpjCredenciadora' deve conter somente dígitos."
  ]
}

❌ 404 Not Found

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Não encontrado",
  "status": 404,
  "erros": [
    "Agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51' não encontrada."
  ]
}

🕒 Observações

  • Uma agenda cuja consulta ainda não terminou devolve totais zerados. A conclusão é notificada por webhook — ver 3.1. Listagem de URs.
  • garantido acompanha o carrinho em tempo real: adicionar ou remover item altera esse total sem alterar constituido, comprometido, livre ou disponivel. Para ver a composição por item, use 4.8. Consultar carrinho.
  • Os totais não trazem valores de deságio: valorNominal, valorDesconto e valorAquisicao existem apenas em antecipação (troca de titularidade). Contrato de garantia não tem deságio, portanto não tem taxa nem desconto a consolidar.
  • Depois da dataValidade da agenda os totais deixam de refletir a realidade das registradoras — refaça a consulta em 4.7. Refazer consulta.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.