--- title: 4.3. Detalhes da agenda url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/4.%20Agenda%20de%20receb%C3%ADveis/v1.1/4.3.%20Detalhes%20da%20agenda/ --- # 4.3. Detalhes da agenda ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | -------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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](4.1.%20Solicitar%20agenda.md) 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](4.4.%20Listar%20URs%20da%20agenda.md). ### 📋 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 ```bash 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 ```json { "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. ```json { "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](4.7.%20Refazer%20consulta.md) — 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](4.4.%20Listar%20URs%20da%20agenda.md), 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](4.1.%20Solicitar%20agenda.md), 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](../../3.%20Notificações%20-%20WebHook/3.1.%20Listagem%20de%20URs.md). * Para localizar o `identificador` de uma agenda, use [4.2. Listar agendas](4.2.%20Listar%20agendas.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).