--- title: 4.2. Listar agendas 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.2.%20Listar%20agendas/ --- # 4.2. Listar agendas ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | --------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/public/api/v1.1/cartao/agendas` | --- ## 🧾 Descrição Retorna a **lista paginada das agendas de recebíveis** já solicitadas no grupo econômico, com os filtros informados na query string. Use este endpoint para localizar o `identificador` de uma agenda, acompanhar em que estado ela está (`statusAgenda`) e verificar se ela ainda está dentro do prazo de validade (`dataValidade`) antes de montar o carrinho. O detalhamento completo de uma agenda específica está em [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md), e as URs vinculadas em [4.4. Listar URs da agenda](4.4.%20Listar%20URs%20da%20agenda.md). --- ## 📤 Requisição ### 🔍 Filtros (query string) | Parâmetro | Tipo | Obrigatório | Descrição | | ----------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | cnpj | string | Não | CNPJ do estabelecimento comercial (somente números, sem formatação). | | idOperacao | number | Não | ID da operação atrelada à agenda (valor definido pelo time de implantação). | | status | number | Não | Filtra pelo status da agenda. Ver tabela **Status da Agenda**. | | dataInicial | string | Não | Considera agendas cujo intervalo consultado inicia a partir desta data, no formato `YYYY-MM-DD`. | | dataFinal | string | Não | Considera agendas cujo intervalo consultado termina até esta data, no formato `YYYY-MM-DD`. | | tags | string[] | Não | Lista de tags de rastreabilidade. Repita o parâmetro para informar mais de uma (ex.: `tags=PA_01&tags=PA_02`). | ### 📄 Paginação e ordenação | Parâmetro | Tipo | Obrigatório | Padrão | Descrição | | ---------------- | ------ | ----------- | ------ | -------------------------------------------------------------------------------------- | | indicePagina | number | Não | `1` | Página desejada do resultado. | | tamanhoDaPagina | number | Não | `20` | Quantidade de registros por página. | | ordem | string | Não | — | Campo usado para ordenar o resultado (ex.: `dataInicial`, `statusAgenda`). | | direcaoOrdem | string | Não | — | Direção da ordenação: `asc` ou `desc`. | **Regras e formatos** * Datas no formato `YYYY-MM-DD`. * `cnpj`: somente dígitos (ex.: `12345678000199`). * Filtros são combinados entre si (E lógico). Quando nenhum filtro é informado, retorna todas as agendas do grupo econômico, da mais recente para a mais antiga. --- ## 🧪 Exemplo de cURL ```bash curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/agendas?cnpj=12345678000199&status=1&dataInicial=2025-08-01&dataFinal=2025-08-31&tags=PA_01&indicePagina=1&tamanhoDaPagina=20&ordem=dataInicial&direcaoOrdem=desc" \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Content-Type: application/json" ``` --- ## 📥 Responses ### ✅ 200 OK ```json { "registros": [ { "identificador": "534D8AAE-61E4-4264-9D15-715B9E1F1D51", "cnpj": "12345678000199", "nome": "LOJA EXEMPLO LTDA", "dataInicial": "2025-08-09", "dataFinal": "2025-08-15", "statusAgenda": 1, "dataValidade": "2025-08-08T18:00:00", "quantidadeUrs": 1240, "tags": ["PA_01"] } ], "paginacao": { "paginaAtual": 1, "paginaTotal": 3, "paginaQuantidadeRegistro": 20, "quantidadeRegistros": 47, "temPaginaAnterior": false, "temProximaPagina": true }, "mensagem": "Agendas listadas com sucesso!" } ``` ### 🧾 Detalhamento dos Campos #### 🔹 registros | Campo | Tipo | Descrição | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | identificador | string | GUID da agenda. Use-o nos demais endpoints da seção 4. | | cnpj | string | CNPJ do estabelecimento comercial consultado. | | nome | string | Nome do EC informado na solicitação da agenda. | | 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**. | | dataValidade | string | Data e hora até quando a agenda é considerada válida. Depois disso é necessário refazer a consulta. | | quantidadeUrs | number | Quantidade de URs retornadas na agenda. As URs são consultadas de forma paginada em **4.4. Listar URs da agenda**. | | tags | string[] | Tags de rastreabilidade informadas na solicitação. | #### 🔹 paginacao | Campo | Tipo | Descrição | | ------------------------ | ------- | ------------------------------------------------------------ | | paginaAtual | number | Página retornada nesta resposta. | | paginaTotal | number | Total de páginas disponíveis com os filtros informados. | | paginaQuantidadeRegistro | number | Quantidade de registros nesta página. | | quantidadeRegistros | number | Total de registros que atendem aos filtros. | | temPaginaAnterior | boolean | Indica se existe página anterior. | | temProximaPagina | boolean | Indica se existe próxima página. | --- ### 🔢 Status da Agenda | Código | Significado | O que fazer | | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------- | | 1 | Agenda disponível | Agenda pronta para uso. Consulte as URs e monte o carrinho. | | 2 | Agenda vazia | A consulta foi concluída, mas a registradora não devolveu URs no intervalo informado. | | 3 | Agenda com promessa de cessão | Existe ônus de terceiro sobre as URs. A promessa de cessão aparece apenas em leitura, nunca é criada aqui. | | 4 | Agenda ultrapassou tempo de publicação | A agenda passou da `dataValidade`. Refaça a consulta — ver [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). | | 5 | Agenda com falha | A consulta falhou. O motivo é devolvido em `motivoFalha` em [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md). | --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'dataInicial' inválido. Formato esperado: YYYY-MM-DD.", "Campo 'status' inválido. Valores aceitos: 1, 2, 3, 4 ou 5." ] } ``` --- ## 🕒 Observações * A agenda só aparece nesta listagem depois de solicitada em [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md). Enquanto o processamento assíncrono não termina, ela é listada com o status resultante da consulta às registradoras. * Requisições de consulta de agenda são processadas **apenas entre 09:00 e 18:00 em dias úteis** (janela de operação). Isso afeta a criação da agenda, não esta listagem. * Agendas com `statusAgenda` igual a `4` estão vencidas: os itens de carrinho montados sobre elas foram invalidados e é preciso refazer a consulta — ver [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).