4.3. Detalhes da agenda¶

🔗 Endpoint¶

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

🧾 Descrição¶

Retorna os detalhes de uma agenda de recebíveis específica: os filtros usados na solicitação, o estado atual do processamento, os totais consolidados por fase de valor e um resumo do que já foi alocado no carrinho.

É o endpoint usado para acompanhar o resultado da consulta iniciada em 4.1. Solicitar agenda e para decidir se a agenda ainda pode ser usada. As URs não vêm neste retorno: elas são consultadas de forma paginada em 4.4. Listar URs da agenda.

📋 Parâmetros de rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idAgenda	string	Sim	GUID da agenda, devolvido como `identificador` em 4.1 e 4.2.

🧪 Exemplo de cURL¶

curl -X GET https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

📥 Responses¶

✅ 200 OK¶

{
  "identificador": "534D8AAE-61E4-4264-9D15-715B9E1F1D51",
  "agenda": {
    "cnpj": "12345678000199",
    "nome": "LOJA EXEMPLO LTDA",
    "tags": ["PA_01"],
    "arranjos": ["MCC", "VCC"],
    "credenciadoras": ["10293847560102"],
    "dataInicial": "2025-08-09",
    "dataFinal": "2025-08-15",
    "statusAgenda": 1,
    "motivoFalha": null,
    "dataValidade": "2025-08-08T18:00:00"
  },
  "totais": {
    "constituido": 1250000.00,
    "comprometido": 300000.00,
    "livre": 950000.00,
    "disponivel": 780000.00,
    "garantido": 170000.00
  },
  "carrinho": {
    "quantidadeItens": 3,
    "totalAlocado": 170000.00
  },
  "quantidadeUrs": 1240
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Descrição
identificador	string	GUID da agenda consultada.
quantidadeUrs	number	Quantidade total de URs vinculadas à agenda.

🔹 agenda¶

Campo	Tipo	Descrição
cnpj	string	CNPJ do estabelecimento comercial utilizado na solicitação da agenda.
nome	string	Nome do EC informado na solicitação, usado para conciliar os recebíveis.
tags	string[]	Tags associadas à solicitação original, para rastreabilidade.
arranjos	string[]	Siglas dos arranjos de pagamento filtrados na solicitação (ex.: `MCC`, `VCC`).
credenciadoras	string[]	CNPJs das credenciadoras consultadas.
dataInicial	string	Data inicial do intervalo consultado (`YYYY-MM-DD`).
dataFinal	string	Data final do intervalo consultado (`YYYY-MM-DD`).
statusAgenda	number	Status atual da agenda. Ver tabela Status da Agenda.
motivoFalha	string-null	Descrição do erro devolvido pela registradora. Preenchido apenas quando `statusAgenda` é `5` (Agenda com falha).
dataValidade	string	Data e hora até quando a agenda é considerada válida.

🔹 totais¶

Consolidado dos valores das URs da agenda. Os quatro primeiros campos pertencem à fase de agenda; garantido reflete o que já foi comprometido na fase de carrinho/contrato.

Campo	Tipo	Descrição
constituido	number	Soma do `valorConstituido` das URs, conforme registro na registradora.
comprometido	number	Soma do `valorComprometido` das URs — parcela já onerada por terceiros ou por contratos anteriores.
livre	number	Soma do `valorLivre` das URs, isto é, o constituído menos o comprometido.
disponivel	number	Soma do `valorDisponivel` das URs — o que sobra do valor livre depois de descontar o que está no carrinho.
garantido	number	Soma do `valorGarantido`, ou seja, o total das URs desta agenda já alocado em itens de carrinho ou contratos.

🔹 carrinho¶

Campo	Tipo	Descrição
quantidadeItens	number	Quantidade de itens de carrinho montados sobre esta agenda.
totalAlocado	number	Valor total das URs desta agenda alocado nesses itens de carrinho.

🔢 Status da Agenda¶

Código	Significado
1	Agenda disponível
2	Agenda vazia
3	Agenda com promessa de cessão
4	Agenda ultrapassou tempo de publicação
5	Agenda com falha

A promessa de cessão (statusAgenda igual a 3) é um ônus de terceiro que incide sobre a UR. Ela aparece apenas em leitura, para que você saiba que aquele valor não está livre — nunca é criada pela API.

❌ 404 Not Found¶

Retornado quando o idAgenda informado não existe no grupo econômico.

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Atenção",
  "status": 404,
  "erros": [
    "Agenda não encontrada."
  ]
}

⏳ Validade da agenda¶

A agenda é uma fotografia dos recebíveis devolvida pelas registradoras no momento da consulta. Por isso ela tem prazo: o campo dataValidade informa até quando essa fotografia é aceita pela plataforma.

Passada a validade, a agenda está velha:

o statusAgenda passa a 4 (Agenda ultrapassou tempo de publicação);
os itens de carrinho montados sobre ela são invalidados, porque não há garantia de que as URs continuem com os mesmos valores livres;
é necessário refazer a consulta para obter uma agenda atualizada — ver 4.7. Refazer consulta — e montar o carrinho novamente.

Sempre confira dataValidade antes de adicionar itens ao carrinho ou de fechar o contrato.

🔄 Mudanças nesta versão¶

O que mudou	Detalhe
O objeto raiz passou a se chamar `agenda`	Antes era `simulacao`. O conteúdo é o mesmo conjunto de filtros e status da consulta.
Voltou o bloco `totais`	Traz o consolidado de `constituido`, `comprometido`, `livre`, `disponivel` e `garantido` sem precisar somar UR por UR.
Entraram `dataValidade` e `carrinho`	`dataValidade` diz até quando a agenda vale; `carrinho` mostra quantos itens já foram montados sobre ela e quanto está alocado.
O array `titulos` deixou de vir embutido	As URs agora são consultadas de forma paginada em 4.4. Listar URs da agenda, porque uma agenda de 30 dias passa de 10 mil URs e o retorno embutido era inviável.

🕒 Observações¶

A agenda só pode ser consultada depois da solicitação inicial em 4.1. Solicitar agenda, que é assíncrona e responde 202 Accepted.
Em caso de falha na consulta, motivoFalha é preenchido com a descrição do erro retornado pela registradora.
A conclusão da consulta é notificada por webhook — ver 3.1. Listagem de URs.
Para localizar o identificador de uma agenda, use 4.2. Listar agendas.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.