7.4. Divergências¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/liquidacoes/divergencias`

🧾 Descrição¶

Retorna, de forma paginada, a fila de exceções operacionais da conciliação: todos os casos em que o que a agenda anunciou e o que entrou em conta não fecharam.

Enquanto 7.1. Posição do contrato mostra o número consolidado (totais.divergencia), esta página mostra cada ocorrência, com UR, contrato, valores e tipo de divergência. É a lista de trabalho da operação: cada registro precisa de uma decisão — cobrar a credenciadora, reprocessar o crédito, desempatar uma atribuição ambígua ou aceitar a redução de posição.

Vale para os dois tipos de contrato (1 = Troca de titularidade e 2 = Garantia). Na antecipação a liquidação vem da baixa da UR cedida ao fundo; na garantia, da conciliação da movimentação bancária com a agenda. A divergência é apurada da mesma forma nos dois casos.

📤 Requisição¶

🔎 Query Params¶

Parâmetro	Tipo	Obrigatório	Descrição
idContrato	string	Não	GUID do contrato. Filtra as divergências de um contrato específico.
cnpj	string	Não	CNPJ do estabelecimento comercial (somente números, sem formatação).
tipoDivergencia	integer	Não	Filtra por tipo de divergência (ver tabela abaixo).
dataInicio	string	Não	Início do intervalo de apuração (inclusivo), no formato `YYYY-MM-DD`. Se omitido, considera os últimos 30 dias.
dataFim	string	Não	Fim do intervalo de apuração (inclusivo), no formato `YYYY-MM-DD`. Se omitido, considera a data atual.
indicePagina	integer	Não	Página desejada (base 1). Padrão `1`.
tamanhoDaPagina	integer	Não	Quantidade de registros por página. Padrão `20`.
ordem	string	Não	Campo de ordenação. Valores aceitos: `dataApuracao`, `dataPrevistaLiquidacao`, `valorDivergencia`. Padrão `dataApuracao`.
direcaoOrdem	string	Não	Direção da ordenação: `asc` ou `desc`. Padrão `desc` (apuração mais recente primeiro).

Regras e formatos

Datas no formato YYYY-MM-DD; dataFim >= dataInicio.
dataInicio e dataFim filtram por dataApuracao (quando a plataforma apurou a divergência), não pela data prevista da UR.
O intervalo não pode ultrapassar 366 dias.
cnpj e idContrato podem ser combinados com tipoDivergencia para montar filas de trabalho por time.

🧪 Exemplo de cURL¶

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/liquidacoes/divergencias?idContrato=19710560-04CD-4E48-881D-D38350B39079&tipoDivergencia=1&dataInicio=2025-09-01&dataFim=2025-09-30&indicePagina=1&tamanhoDaPagina=20" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Responses¶

✅ 200 OK¶

{
  "registros": [
    {
      "identificadorUr": "7D121577-3C5A-494D-B052-291D9E100D0D",
      "idContrato": "19710560-04CD-4E48-881D-D38350B39079",
      "dataPrevistaLiquidacao": "2025-09-10",
      "tipoDivergencia": 3,
      "valorEsperado": 1000.00,
      "valorLiquidado": 950.00,
      "valorDivergencia": -50.00,
      "dataApuracao": "2025-09-10"
    },
    {
      "identificadorUr": "A93F1D08-2C77-4B6E-9E15-6F2B84C0D311",
      "idContrato": "19710560-04CD-4E48-881D-D38350B39079",
      "dataPrevistaLiquidacao": "2025-09-11",
      "tipoDivergencia": 1,
      "valorEsperado": 2500.00,
      "valorLiquidado": 0.00,
      "valorDivergencia": -2500.00,
      "dataApuracao": "2025-09-11"
    },
    {
      "identificadorUr": null,
      "idContrato": null,
      "dataPrevistaLiquidacao": null,
      "tipoDivergencia": 2,
      "valorEsperado": 0.00,
      "valorLiquidado": 480.00,
      "valorDivergencia": 480.00,
      "dataApuracao": "2025-09-12"
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 3,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}

🧾 Detalhamento dos Campos¶

🔹 registros¶

Campo	Tipo	Descrição
identificadorUr	string/null	GUID da UR envolvida. `null` quando o crédito chegou sem linha de agenda correspondente (`tipoDivergencia` = `2`).
idContrato	string/null	GUID do contrato afetado. `null` quando a divergência não pôde ser atribuída a nenhum contrato.
dataPrevistaLiquidacao	string/null	Data prevista de liquidação da UR (`YYYY-MM-DD`). `null` quando não há UR identificada.
tipoDivergencia	integer	Tipo da divergência apurada (ver tabela abaixo).
valorEsperado	number	Valor que a agenda anunciou. `0.00` quando não havia linha de agenda.
valorLiquidado	number	Valor efetivamente creditado e atribuído. `0.00` quando nenhum crédito chegou.
valorDivergencia	number	`valorLiquidado - valorEsperado`. Negativo quando entrou menos do que o anunciado; positivo quando entrou mais.
dataApuracao	string	Data em que a plataforma apurou a divergência (`YYYY-MM-DD`).

🔹 paginacao¶

Campo	Tipo	Descrição
paginaAtual	integer	Página atual do retorno (base 1).
paginaTotal	integer	Total de páginas disponíveis.
paginaQuantidadeRegistro	integer	Quantidade de registros por página.
quantidadeRegistros	integer	Total de registros encontrados.
temPaginaAnterior	boolean	Indica se existe página anterior.
temProximaPagina	boolean	Indica se existe próxima página.

🔹 mensagem¶

Campo	Tipo	Descrição
mensagem	string/null	Mensagem informativa opcional do retorno (`null` nos casos de sucesso simples).

🔢 Tipos de divergência¶

Código	Significado	Aplicação
1	Agenda sem crédito	A agenda anunciou a UR e o crédito não chegou. Apurada somente na última rodada de conciliação do dia (19:00).
2	Crédito sem agenda	Chegou crédito em conta sem linha de agenda correspondente. `identificadorUr` e `idContrato` vêm `null`.
3	Valor abaixo do esperado	O crédito chegou, mas em valor menor que o anunciado pela agenda. `valorDivergencia` negativo.
4	Valor acima do esperado	O crédito chegou em valor maior que o anunciado pela agenda. `valorDivergencia` positivo.
5	Redução de posição da agenda	A registradora reduziu o valor comprometido da UR depois do registro do contrato, por chargeback da venda ou ajuste da credenciadora.
6	Atribuição ambígua	Mais de uma UR compatível com o mesmo crédito (mesma data, arranjo, credenciadora e valor). A conciliação fica suspensa até o desempate.
7	Data fora do esperado	O crédito chegou em data diferente da anunciada pela agenda. O valor fecha, a data não.

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'cnpj' inválido. Informe somente números.",
    "Campo 'tipoDivergencia' inválido. Valores aceitos: 1, 2, 3, 4, 5, 6, 7.",
    "O intervalo entre 'dataInicio' e 'dataFim' não pode ultrapassar 366 dias."
  ]
}

❌ 404 Not Found¶

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

Retornado quando o idContrato informado no filtro não existe. Filtros válidos que simplesmente não encontram divergências devolvem 200 OK com registros vazio.

🕒 Observações¶

Divergências do tipo 1 (Agenda sem crédito) só aparecem após a última rodada de conciliação do dia, às 19:00. Antes disso, a UR vencida ainda é tratada como em aberto, porque o crédito pode chegar durante o dia.
Os créditos em conta chegam pela integração de liquidações — ver 6.1. Envio dos créditos em conta — e devem ser enviados após as 10:05, por causa do processamento batch das agendas às 10:00. Envios antes desse horário podem gerar divergências temporárias do tipo 2 (Crédito sem agenda), que se resolvem na rodada seguinte.
Divergências do tipo 6 (Atribuição ambígua) bloqueiam a conciliação daquele crédito: nada é atribuído até o desempate, para não liquidar a UR errada. Enquanto isso, o valor permanece em emAberto na posição do contrato.
Divergências do tipo 5 (Redução de posição da agenda) alimentam o campo totais.chargeback em 7.1. Posição do contrato e não representam falha de crédito: o recebível deixou de existir na agenda.
Para auditar uma divergência linha a linha — o que a agenda anunciou, quais créditos chegaram e quais ônus existiam sobre a UR — use 7.3. Extrato de conciliação da UR.
Mudanças de posição da UR apuradas na conciliação também são notificadas por webhook — ver 3.3. Atualizações da UR.
Contrato de garantia não tem deságio: a divergência é sempre comparação entre esperado e liquidado, nunca envolve valor nominal, desconto, aquisição ou taxa.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.