5.3. Detalhes do contrato¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1.1/cartao/contratos/{idContrato}`

🧾 Descrição¶

Retorna o cabeçalho de um contrato de recebíveis de cartão: identificação, tipo, modalidade, status no regime de interoperabilidade, configuração da operação (parcelas ou fumaça), registradora responsável e os totais financeiros consolidados.

As URs vinculadas não vêm embutidas neste retorno. Como um contrato pode ter milhares de URs, elas são consultadas de forma paginada em 5.4. Listar URs do contrato, e uma UR específica em 5.5. Detalhes da UR do contrato. O campo quantidadeUrs informa quantas URs existem no contrato.

O conteúdo de totais depende do tipoContrato. Essa é a regra central desta página — ver a seção totais, mais abaixo.

📤 Requisição¶

📋 Parâmetros de rota¶

Parâmetro	Tipo	Obrigatório	Descrição
idContrato	string	Sim	GUID do contrato, devolvido na criação do contrato.

🧪 Exemplo de cURL¶

curl -X GET https://api.veflow.com/public/api/v1.1/cartao/contratos/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6 \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

📥 Responses¶

✅ 200 OK — contrato de troca de titularidade (`tipoContrato = 1`)¶

{
  "contrato": {
    "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6",
    "identificadorInteroperabilidade": ["0DC43268-E05F-478E-931C-A43B8B3DD79B"],
    "cnpj": "12345678000199",
    "modalidade": 1,
    "tipoContrato": 1,
    "status": 4,
    "dataAssinatura": "2025-08-08",
    "dataVencimento": "2025-09-30",
    "parcela": null,
    "fumaca": null,
    "registradora": {
      "id": 2,
      "nome": "CERC"
    }
  },
  "totais": {
    "constituido": 120000.00,
    "livre": 20000.00,
    "garantido": 100000.00,
    "disponivel": 18000.00,
    "nominal": 100000.00,
    "desconto": 1990.00,
    "aquisicao": 98010.00,
    "taxa": 1.9900
  },
  "quantidadeUrs": 42
}

✅ 200 OK — contrato de garantia (`tipoContrato = 2`)¶

{
  "contrato": {
    "identificador": "A7E90C41-2B33-4F0E-9E52-6C7B1D0A94F2",
    "identificadorInteroperabilidade": ["B1C2D3E4-5F60-4718-92A3-0D4E5F6A7B8C"],
    "cnpj": "12345678000199",
    "modalidade": 2,
    "tipoContrato": 2,
    "status": 4,
    "dataAssinatura": "2025-08-08",
    "dataVencimento": "2026-06-08",
    "parcela": {
      "numero": 1,
      "total": 10,
      "valor": 25000.00,
      "data": "2025-09-08"
    },
    "fumaca": null,
    "registradora": {
      "id": 2,
      "nome": "CERC"
    }
  },
  "totais": {
    "constituido": 320000.00,
    "livre": 70000.00,
    "garantido": 250000.00,
    "disponivel": 61000.00
  },
  "quantidadeUrs": 118
}

Repare que o contrato de garantia não traz nominal, desconto, aquisicao nem taxa. Isso não é omissão de exemplo: esses campos não existem nesse tipo de contrato.

🔸 Recorte do bloco `fumaca` (garantia fumaça, `modalidade = 3`)¶

{
  "contrato": {
    "modalidade": 3,
    "tipoContrato": 2,
    "parcela": null,
    "fumaca": {
      "prazoEstendidoDias": 30,
      "tipoValor": 1,
      "valor": 50000.00,
      "percentualRetencaoUr": 100.00
    }
  }
}

🧾 Detalhamento dos campos¶

🔹 contrato¶

Campo	Tipo	Descrição
identificador	string	GUID do contrato na plataforma VeFlow.
identificadorInteroperabilidade	string[]	Identificadores do contrato no regime de interoperabilidade. É um array porque o mesmo contrato pode ter identificador em mais de uma registradora. Vem vazio (`[]`) enquanto o registro não é confirmado.
cnpj	string	CNPJ do estabelecimento comercial (EC), somente dígitos.
modalidade	integer	Como o contrato foi montado dentro do tipo (integral, parcelado ou fumaça). Ver a tabela Modalidade.
tipoContrato	integer	`1` = Troca de titularidade, `2` = Garantia. Ver a tabela Tipo de contrato.
status	integer	Código do status atual do contrato. Ver a tabela Status do contrato.
dataAssinatura	string	Data de assinatura do contrato (`YYYY-MM-DD`).
dataVencimento	string	Data de vencimento final do contrato (`YYYY-MM-DD`). Em contrato parcelado, é o vencimento da última parcela.
parcela	object/null	Dados da parcela vinculada. Preenchido em garantia parcelada; `null` nos demais casos.
fumaca	object/null	Configuração da garantia fumaça. Preenchido em garantia fumaça; `null` nos demais casos.
registradora	object/null	Registradora responsável pelo contrato. Vem `null` enquanto a registradora não é definida.

🔢 Tipo de contrato¶

Código	Significado	Aplicação
1	Troca de titularidade	Antecipação: as URs são cedidas ao fundo/securitizadora, que passa a ser o titular do recebível.
2	Garantia	As URs permanecem com o EC, mas ficam comprometidas como garantia da operação. Não há cessão e não há deságio.

Fumaça não é um tipo de contrato. É uma configuração da garantia (tipoContrato = 2): prazo estendido, uso apenas de URs performadas e regra de retenção sobre cada UR. A v1 documentava 3 = Fumaça como tipo de contrato — isso está corrigido nesta versão.

Promessa de cessão nunca pode ser criada pela plataforma. Ela aparece somente em leitura, como ônus de terceiro sobre a UR — ver o array efeitos em 5.5. Detalhes da UR do contrato. Penhor é legado e também só aparece em leitura.

🔢 Modalidade¶

Código	Significado	Aplicação
1	Integral	Operação em uma única liquidação, sem parcelamento. É a modalidade típica da troca de titularidade. `parcela` e `fumaca` vêm `null`.
2	Parcelada	Garantia distribuída em parcelas contratuais. O bloco `parcela` é preenchido.
3	Fumaça	Garantia com prazo estendido e retenção sobre as URs performadas. O bloco `fumaca` é preenchido.

🔢 Status do contrato¶

Código	Significado	Aplicação
1	Aguardando registro	Contrato recebido na plataforma e será encaminhado para a registradora.
2	Registrando	Contrato oficializado na registradora, aguardando retorno do registro.
3	Falha no registro	Contrato obteve erro na formalização no regime de interoperabilidade.
4	Aguardando liquidação	Contrato registrado; entrou no fluxo de apenas aguardar as liquidações.
5	Cancelado	Contrato oficialmente cancelado no regime de interoperabilidade.
6	Em liquidação	Contrato obteve a primeira liquidação de uma UR vinculada.
7	Liquidado	Contrato obteve liquidação de todas as suas URs vinculadas.
8	Em cancelamento	Solicitação de cancelamento recebida na plataforma e será encaminhada para a registradora.
9	Falha no cancelamento	Não foi possível cancelar o contrato no regime de interoperabilidade.
10	Em extensão	Solicitação de extensão do prazo do contrato encaminhada à registradora (usual em garantia fumaça).
11	Falha na extensão	Não foi possível estender o prazo do contrato no regime de interoperabilidade.
12	Vencido	O contrato alcançou a `dataVencimento` sem liquidação total das URs vinculadas.

Os códigos 10, 11 e 12 são novos na v1.1. A v1 documentava apenas 1 a 9.

🔸 parcela — garantia parcelada (`modalidade = 2`)¶

Campo	Tipo	Descrição
numero	integer	Número da parcela vinculada a este contrato.
total	integer	Total de parcelas da operação.
valor	number	Valor da parcela.
data	string	Data de vencimento da parcela (`YYYY-MM-DD`).

🔸 fumaca — garantia fumaça (`modalidade = 3`)¶

Campo	Tipo	Descrição
prazoEstendidoDias	integer	Dias de prazo estendido: quanto tempo além do vencimento a garantia continua capturando URs performadas.
tipoValor	integer	Como o `valor` deve ser lido: `1` = valor fixo, `2` = percentual.
valor	number	Valor desejado na operação (montante fixo ou percentual, conforme `tipoValor`).
percentualRetencaoUr	number	Percentual do valor livre de cada UR retido para compor a garantia (ex.: `100.00` retém todo o valor livre da UR).

A fumaça combina três decisões: prazo estendido, somente URs performadas e regra de retenção por UR. Ela continua sendo um contrato de garantia (tipoContrato = 2) e, portanto, também não tem deságio.

🔸 registradora¶

Campo	Tipo	Descrição
id	integer	Identificador da registradora na plataforma.
nome	string	Nome da registradora (ex.: `CERC`, `TAG`, `CRDC`, `NUCLEA`).

O objeto inteiro vem null enquanto a registradora do contrato ainda não foi definida — situação normal em status = 1 (Aguardando registro).

🔹 totais¶

Esta é a regra central da página: o conteúdo de totais é condicional ao tipoContrato.

Campo	`tipoContrato = 1` (Troca de titularidade)	`tipoContrato = 2` (Garantia)
constituido	✅ Presente	✅ Presente
livre	✅ Presente	✅ Presente
garantido	✅ Presente	✅ Presente
disponivel	✅ Presente	✅ Presente
nominal	✅ Presente	❌ Não existe
desconto	✅ Presente	❌ Não existe
aquisicao	✅ Presente	❌ Não existe
taxa	✅ Presente	❌ Não existe

Campos comuns aos dois tipos¶

Campo	Tipo	Descrição
constituido	number	Soma do valor constituído das URs vinculadas, conforme registro na registradora. É o tamanho bruto da agenda que sustenta o contrato.
livre	number	Soma do valor das URs que a registradora informa como não comprometido por nenhum efeito, seu ou de terceiro.
garantido	number	Soma do valor efetivamente comprometido pelas URs neste contrato. É o número que o contrato de fato sustenta.
disponivel	number	Quanto do valor livre a plataforma considera utilizável para este contrato após aplicar as regras da operação (arranjos e credenciadoras habilitados, exigência de UR performada, percentual de retenção). É o teto para reforço de garantia ou extensão de prazo.

livre é o que a registradora enxerga; disponivel é o que a operação consegue usar. A diferença entre os dois costuma vir de URs fora dos arranjos ou das credenciadoras habilitados, ou ainda não performadas.

Campos exclusivos da troca de titularidade¶

Campo	Tipo	Descrição
nominal	number	Valor das URs cedido ao fundo. É a base da operação de antecipação, antes do deságio.
desconto	number	Soma dos deságios aplicados sobre o valor nominal.
aquisicao	number	Valor nominal deságiado (`nominal - desconto`): o que o fundo ou a securitizadora paga hoje para receber o recebível no futuro.
taxa	number	Deságio aplicado na operação, com até 4 casas decimais.

Por que esses quatro campos não aparecem em garantia? Porque nominal, desconto e aquisicao só existem onde houve cessão ao fundo. Na troca de titularidade a UR muda de titular: alguém compra o recebível com deságio, então faz sentido falar de valor nominal, deságio e valor de aquisição. Em um contrato de garantia não há cessão nem deságio — a UR continua sendo do EC, apenas comprometida. Sem cessão, não há preço de compra; sem deságio, não há taxa. Documentar esses campos em garantia seria descrever números que a API não devolve.

🔹 quantidadeUrs¶

Campo	Tipo	Descrição
quantidadeUrs	integer	Quantidade de URs vinculadas ao contrato. Use-o para dimensionar a paginação em 5.4. Listar URs do contrato.

❌ 404 Not Found¶

Contrato inexistente, ou fora do grupo econômico informado no header GrupoEconomico.

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

🔄 Mudanças em relação à v1¶

Mudança	Detalhe
Rota corrigida	A rota estava documentada com a versão errada (`/api/v1/cartao/contrato/{identificador}`). Agora é `/public/api/v1.1/cartao/contratos/{idContrato}`.
`totais.aquisicao` voltou	A v1.1 havia removido o campo; ele volta, exclusivo de `tipoContrato = 1`.
`totais.CET` saiu	O campo estava documentado, mas nunca existiu no retorno da API. Foi removido da documentação.
`totais.disponivel` entrou	Novo campo, presente nos dois tipos de contrato.
Bloco `fumaca` voltou	Agora com `prazoEstendidoDias`, `tipoValor`, `valor` e `percentualRetencaoUr`, e vinculado a `tipoContrato = 2` (não mais a um "tipo 3").
`status` é `integer`	A tabela da v1 declarava `string`, incorretamente. O campo sempre foi numérico.
Status do contrato de 1–9 para 1–12	Entraram `10` Em extensão, `11` Falha na extensão e `12` Vencido.
`titulos` deixou de vir embutido	As URs agora são paginadas em 5.4. Listar URs do contrato, e detalhadas em 5.5. Detalhes da UR do contrato. O contrato passa a devolver apenas `quantidadeUrs`.
`tipoContrato = 3` não existe	Fumaça é configuração da garantia, sinalizada por `modalidade = 3`.

🕒 Observações¶

Os valores em totais refletem sempre o estado mais recente do contrato e mudam conforme liquidações parciais, chargebacks e conciliação bancária.
Após liquidação total (status = 7), as URs do contrato são consideradas encerradas e não podem ser reatribuídas.
URs canceladas, rejeitadas ou liquidadas permanecem listadas em 5.4. Listar URs do contrato para fins de auditoria.
Esta consulta é de leitura e não está sujeita à janela de operação. As operações de escrita do contrato (criação, cancelamento e remoção de UR) são processadas apenas entre 09:00 e 18:00 em dias úteis.
O cancelamento do contrato exige que a próxima UR performada esteja ao menos 3 dias úteis à frente da data atual — ver Cancelar contrato.
Mudanças de status do contrato são notificadas por webhook — ver 3.2. Atualizações do contrato.
Headers obrigatórios e convenções gerais: 1.2. Convenções da API.