--- title: 5.3. Detalhes do contrato url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/5.%20Contrato%20de%20receb%C3%ADveis/v1.1/5.3.%20Detalhes%20do%20contrato/ --- # 5.3. Detalhes do contrato ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | ---------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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](5.4.%20Listar%20URs%20do%20contrato.md), e uma UR específica em [5.5. Detalhes da UR do contrato](5.5.%20Detalhes%20da%20UR%20do%20contrato.md). 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 ```bash 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`) ```json { "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`) ```json { "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`) ```json { "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](5.5.%20Detalhes%20da%20UR%20do%20contrato.md). **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](5.4.%20Listar%20URs%20do%20contrato.md). | --- ### ❌ 404 Not Found Contrato inexistente, ou fora do grupo econômico informado no header `GrupoEconomico`. ```json { "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](5.4.%20Listar%20URs%20do%20contrato.md), e detalhadas em [5.5. Detalhes da UR do contrato](5.5.%20Detalhes%20da%20UR%20do%20contrato.md). 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](5.4.%20Listar%20URs%20do%20contrato.md) 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](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).