Ir para o conteúdo

4.5. Detalhes da UR

🔗 Endpoint

Método URL
GET /public/api/v1.1/cartao/agendas/{idAgenda}/urs/{idUr}

🧾 Descrição

Retorna os detalhes de uma UR (Unidade de Recebível) dentro do contexto de uma agenda: os mesmos valores da listagem, mais o array efeitos — a relação dos ônus registrados sobre aquela UR.

O array efeitos responde à pergunta que a listagem não responde: quem comprometeu esta UR, por qual contrato, com que ônus e até quando. É também onde a promessa de cessão aparece, sempre como ônus de terceiro.

Use esta consulta antes de alocar uma UR grande em um item de carrinho: valorComprometido diz quanto está onerado, efeitos diz por que.

📤 Requisição

🧭 Parâmetros de rota

Parâmetro Tipo Obrigatório Descrição
idAgenda string Sim GUID da agenda, devolvido em 4.1. Solicitar agenda.
idUr string Sim GUID da UR, obtido em 4.4. Listar URs da agenda.

🧪 Exemplo de cURL

curl -X GET https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/urs/7D121577-3C5A-494D-B052-291D9E100D0D \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

📥 Responses

✅ 200 OK

{
  "id": "7D121577-3C5A-494D-B052-291D9E100D0D",
  "credenciadora": {
    "cnpj": "10293847560102",
    "nome": "CREDENCIADORA EXEMPLO S.A."
  },
  "arranjo": {
    "sigla": "MCC",
    "nome": "Mastercard Cartão de Crédito"
  },
  "dataPrevistaLiquidacao": "2025-08-14",
  "valorConstituido": 10000.00,
  "valorComprometido": 2500.00,
  "valorLivre": 7500.00,
  "valorDisponivel": 5000.00,
  "valorGarantido": 1200.00,
  "possuiPromessaCessao": true,
  "efeitos": [
    {
      "tipoEfeito": 2,
      "tipoOnus": 1,
      "dataVencimentoEfeito": "2025-12-30",
      "idEfeitoContrato": "A7F1C2B4-9D30-4A11-8F55-6B2E7C1D0A93",
      "documentoTitular": "12345678000199",
      "titularEhVoce": true,
      "valorComprometido": 1500.00
    },
    {
      "tipoEfeito": 3,
      "tipoOnus": 2,
      "dataVencimentoEfeito": "2026-01-15",
      "idEfeitoContrato": "5C90E1AA-33B7-42D8-9E64-1F8C7A2B4D06",
      "documentoTitular": "***456780***",
      "titularEhVoce": false,
      "valorComprometido": 1000.00
    }
  ]
}

🧾 Detalhamento dos Campos

🔹 Nível raiz

Campo Tipo Descrição
id string GUID da UR.
credenciadora.cnpj string CNPJ da credenciadora responsável pela UR.
credenciadora.nome string Nome da credenciadora.
arranjo.sigla string Sigla do arranjo de pagamento (ex.: MCC).
arranjo.nome string Nome do arranjo (ex.: Mastercard Cartão de Crédito).
dataPrevistaLiquidacao string Data prevista de liquidação da UR (YYYY-MM-DD).
valorConstituido number Valor que a registradora informa existir na UR.
valorComprometido number Parte da UR já onerada, por contrato próprio ou de terceiro. Igual à soma de efeitos[].valorComprometido.
valorLivre number Parte da UR disponível para uso (valorConstituido - valorComprometido).
valorDisponivel number Valor livre já descontado o percentual máximo por UR configurado na operação.
valorGarantido number Quanto desta UR está sendo utilizado pelos itens do carrinho.
possuiPromessaCessao boolean true quando há promessa de cessão entre os efeitos — sempre ônus de terceiro.
efeitos array Ônus registrados sobre a UR. Array vazio ([]) significa UR livre de ônus.

🔹 efeitos

Campo Tipo Descrição
tipoEfeito integer Natureza do efeito registrado sobre a UR (ver tabela abaixo).
tipoOnus integer Origem do ônus: 1 = próprio (contrato seu), 2 = terceiro (contrato de outra instituição).
dataVencimentoEfeito string Até quando o efeito onera a UR (YYYY-MM-DD). Depois dessa data o valor volta a compor o valorLivre, se o efeito não for renovado.
idEfeitoContrato string ID de efeito de contrato — identificador que permite às registradoras reconhecerem o mesmo contrato no ambiente de interoperabilidade.
documentoTitular string Documento (CNPJ/CPF) do titular do efeito. Vem mascarado quando titularEhVoce é false.
titularEhVoce boolean true quando o efeito é de um contrato do seu grupo econômico; false quando pertence a terceiro.
valorComprometido number Quanto este efeito onera a UR. A soma dos efeitos é o valorComprometido da UR.

🔢 tipoEfeito

Código Significado
1 Troca de titularidade — a UR foi cedida; o titular do recebível passou a ser o cessionário.
2 Garantia — a UR está travada em favor do credor, sem cessão definitiva.
3 Promessa de cessão — compromisso de cessão futura registrado sobre a UR. Somente leitura.
4 Penhor — efeito legado, mantido apenas para leitura de registros antigos.

⚠️ Como interpretar os efeitos

  • Array vazio ("efeitos": []) significa UR livre de ônus: todo o valorConstituido está livre, limitado apenas pelo percentual máximo por UR da operação (valorDisponivel).
  • tipoOnus = 1 (próprio): o efeito vem de um contrato do seu grupo econômico. O idEfeitoContrato permite localizar o contrato correspondente em 5. Contrato de recebíveis.
  • tipoOnus = 2 (terceiro): outra instituição já onerou parte da UR. Você não tem acesso ao contrato dela — por isso documentoTitular vem mascarado.
  • Promessa de cessão (tipoEfeito = 3) aparece apenas em leitura e sempre como ônus de terceiro (tipoOnus = 2). Ela nunca pode ser criada pela API: não existe endpoint que registre promessa de cessão. Quando presente, possuiPromessaCessao vem true na UR e na listagem de 4.4. Listar URs da agenda.
  • Penhor (tipoEfeito = 4) é legado. Pode aparecer em URs com histórico antigo e não é gerado por nenhuma operação atual da plataforma VeFlow.
  • Para varrer a agenda inteira em busca de URs oneradas por terceiros, use o filtro possuiEfeitoTerceiros=true em 4.4. Listar URs da agenda.

❌ 404 Not Found

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "titulo": "Não encontrado",
  "status": 404,
  "erros": [
    "UR '7D121577-3C5A-494D-B052-291D9E100D0D' não encontrada na agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51'."
  ]
}

Retornado tanto quando a agenda não existe quanto quando a UR informada não pertence àquela agenda.

🕒 Observações

  • Os efeitos refletem o estado informado pelas registradoras no momento da consulta da agenda. Uma agenda vencida pode trazer ônus desatualizados — refaça a consulta em 4.7. Refazer consulta.
  • Alterações de ônus e de valores da UR também são notificadas por webhook — ver 3.3. Atualizações da UR.
  • valorComprometido (ônus registrado) e valorGarantido (uso no carrinho) são grandezas diferentes: a primeira já está registrada nas registradoras; a segunda é a alocação em montagem na plataforma, que só se torna ônus quando o item vira contrato.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.