Ir para o conteúdo

4.2. Listar agendas

🔗 Endpoint

Método URL
GET /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, e as URs vinculadas em 4.4. Listar URs da agenda.

📤 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

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

{
  "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.
5 Agenda com falha A consulta falhou. O motivo é devolvido em motivoFalha em 4.3. Detalhes da agenda.

❌ 400 Bad Request

{
  "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. 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.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.