Ir para o conteúdo

4.1. Solicitar agenda

🔗 Endpoint

Método URL
POST /public/api/v1.1/cartao/agendas

🧾 Descrição

Recebe uma solicitação de consulta da agenda de recebíveis de cartão de um estabelecimento comercial (EC), com base nos filtros informados.

Ao receber a requisição, a plataforma VeFlow registra o OPT-IN do EC (quando aplicável) e inicia a consulta das agendas junto às registradoras. O processamento é assíncrono: a resposta confirma o recebimento e devolve o identificador da agenda, que deve ser usado nas consultas seguintes.

📤 Requisição

📋 Payload (JSON)

{
  "idOperacao": 0,
  "cnpj": "",
  "nome": "",
  "tags": [""],
  "arranjos": [""],
  "credenciadoras": [""],
  "dataInicial": "0000-00-00",
  "dataFinal": "0000-00-00",
  "taxa": 0.0000
}

🧾 Detalhamento dos Campos

Campo Tipo Obrigatório Descrição
idOperacao number Sim ID da operação atrelada (valor definido pelo time de implantação).
cnpj string Sim CNPJ do estabelecimento comercial (somente números, sem formatação).
nome string Não Nome do EC. Utilizado para conciliar os recebíveis quando o CNPJ do ponto de venda informado no arquivo do SLC não é o originário da UR.
tags string[] Não Lista de tags para rastreabilidade da agenda (p.ex. ["PA_01"]).
arranjos string[] Não Siglas dos arranjos de pagamento (ex.: "MCC", "VCC"). Se omitido, considera todos os arranjos.
credenciadoras string[] Não CNPJs das credenciadoras (somente números). Se omitido, busca em todas as credenciadoras habilitadas na operação.
dataInicial string Sim Data inicial da consulta, no formato YYYY-MM-DD. Deve ser no mínimo D+2 da data atual (recomendado D+5).
dataFinal string Sim Data final da consulta, no formato YYYY-MM-DD. Deve ser maior ou igual a dataInicial.
taxa number Não Deságio com até 4 casas decimais, usado apenas para projetar valorDesconto e valorAquisicao na listagem de URs.

Regras e formatos

  • Datas no formato YYYY-MM-DD.
  • cnpj e credenciadoras: somente dígitos (ex.: 12345678000199).
  • dataInicial >= D+2; dataFinal >= dataInicial.
  • taxa aqui é apenas projeção de vitrine. A taxa que vale para o contrato é a definida em cada item do carrinho — ver 4.10. Adicionar item. Não se aplica a contratos de garantia, que não têm deságio.

🧪 Exemplo de cURL

curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Idempotency-Key: 9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0" \
  -H "Content-Type: application/json" \
  -d '{
    "idOperacao": 1,
    "cnpj": "12345678000199",
    "nome": "LOJA EXEMPLO LTDA",
    "tags": ["PA_01"],
    "arranjos": ["MCC","VCC"],
    "credenciadoras": ["10293847560102"],
    "dataInicial": "2025-08-09",
    "dataFinal": "2025-08-15",
    "taxa": 1.9900
  }'

📥 Responses

✅ 202 Accepted

{
  "identificador": "534D8AAE-61E4-4264-9D15-715B9E1F1D51",
  "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666",
  "mensagem": "Solicitação de agenda recebida com sucesso!"
}
Campo Tipo Descrição
identificador string GUID da agenda criada. Use-o em todas as consultas da seção 4.
identificadorProcessamento string GUID do processamento assíncrono, para acompanhamento.
mensagem string Mensagem de confirmação.

✅ 202 Accepted — fora da janela de operação

{
  "identificador": "534D8AAE-61E4-4264-9D15-715B9E1F1D51",
  "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666",
  "dataAgendamento": "2025-08-11",
  "mensagem": "Solicitação recebida e agendada para processamento no próximo dia útil."
}

Retornado quando a requisição chega fora da janela operacional. O campo dataAgendamento informa o dia útil em que a consulta será processada.

❌ 400 Bad Request

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'cnpj' é obrigatório.",
    "Campo 'dataInicial' inválido. Formato esperado: YYYY-MM-DD.",
    "dataInicial deve ser no mínimo D+2."
  ]
}

🕒 Observações

  • Requisições são processadas apenas entre 09:00 e 18:00 em dias úteis (janela de operação). Fora dessa janela, a resposta é 202 com dataAgendamento para o próximo dia útil.
  • A agenda tem prazo de validade (dataValidade, devolvido em 4.3. Detalhes da agenda). Depois de vencida, os itens de carrinho montados sobre ela são invalidados e é necessário refazer a consulta — ver 4.7. Refazer consulta.
  • A conclusão da consulta é notificada por webhook — ver 3.1. Listagem de URs.
  • Consultar as URs retornadas: 4.4. Listar URs da agenda.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.