--- title: 5.1. Criar contratos 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.1.%20Criar%20contratos/ --- # 5.1. Criar contratos ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | ------------------------------------------------------ | | ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1.1/cartao/agendas/{idAgenda}/contratos` | --- ## 🧾 Descrição Transforma o **carrinho montado sobre a agenda** em **1..N contratos** e os envia para registro na registradora. É neste ponto que a intenção de operação deixa de ser simulação e passa a produzir efeito na registradora. Cada item do carrinho gera **um contrato**. Como itens de tipos diferentes podem conviver no mesmo carrinho, uma única requisição pode produzir contratos com **efeitos distintos na registradora**: item com `tipoContrato` `1` registra **troca de titularidade** da UR; item com `tipoContrato` `2` registra **ônus de cessão fiduciária** sobre a UR. O processamento é **assíncrono**: a resposta confirma o recebimento, devolve o `identificadorProcessamento` para acompanhamento e a lista de contratos criados, cada um com o seu `identificador`. A conclusão do registro é notificada por webhook — ver [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md). ### 🧭 Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------- | | idAgenda | string | Sim | GUID da agenda cujo carrinho será contratado, devolvido em [4.1. Solicitar agenda](../../4.%20Agenda%20de%20recebíveis/v1.1/4.1.%20Solicitar%20agenda.md). | --- ## 📤 Requisição ### 📋 Payload (JSON) ```json { "idsItens": [""], "contaCorrente": { "banco": "", "agencia": "", "conta": "" } } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | | --------------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | idsItens | string[] | Não | GUIDs dos itens do carrinho que devem ser contratados. **Se omitido, contrata todos os itens do carrinho da agenda.** | | contaCorrente | object | Sim | Conta corrente de domicílio informada no registro do contrato. | | contaCorrente.banco | string | Sim | Código do banco (COMPE), somente números (ex.: `"237"`). | | contaCorrente.agencia | string | Sim | Número da agência, somente números, sem dígito verificador. | | contaCorrente.conta | string | Sim | Número da conta com dígito verificador, somente números. | **Regras e formatos** * `idsItens` aceita apenas itens pertencentes ao carrinho da agenda informada em `{idAgenda}`. Item de outra agenda é recusado com `400`. * Omitir `idsItens` contrata **todos** os itens do carrinho. Informar a lista permite contratar o carrinho em partes. * Cada item informado gera **um contrato próprio**, com o `tipoContrato` que foi definido no item — ver [4.10. Adicionar item](../../4.%20Agenda%20de%20recebíveis/v1.1/4.10.%20Adicionar%20item.md). * `banco`, `agencia` e `conta`: somente dígitos, sem máscara. * A agenda precisa estar dentro da `dataValidade`. Agenda vencida invalida os itens do carrinho e exige refazer a consulta — ver [4.7. Refazer consulta](../../4.%20Agenda%20de%20recebíveis/v1.1/4.7.%20Refazer%20consulta.md). --- ## 🧬 Efeito de cada tipo de contrato na registradora | tipoContrato | Significado | O que é registrado | | ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Troca de titularidade | Registra a **troca de titularidade** da UR: o recebível passa a ter o fundo como titular. É a única modalidade com cessão ao fundo e, por isso, a única com deságio (`valorNominal`, `valorDesconto` e `valorAquisicao`). | | 2 | Garantia | Registra **ônus de cessão fiduciária** sobre a UR. A titularidade permanece com o estabelecimento comercial; a UR fica comprometida como garantia do contrato. | **Pontos de atenção** * **Fumaça não é tipo de contrato.** É uma **configuração da garantia** (`tipoContrato` `2`): prazo estendido, uso de **somente URs performadas** e regra de retenção. O contrato continua sendo do tipo `2`. * **Promessa de cessão nunca é criada por este endpoint.** Ela aparece apenas em leitura, como **ônus de terceiro** sobre a UR. * Contrato de **garantia não tem deságio**: não traz `valorNominal`, `valorDesconto`, `valorAquisicao` nem `taxa`. O valor relevante é o `valorGarantido` do contrato. * **Penhor é legado** e não é utilizado nesta versão. --- ## 🧪 Exemplo de cURL ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/contratos \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: 3b8f7c02-9a41-4d6e-8f77-1c2d3e4f5a6b" \ -H "Content-Type: application/json" \ -d '{ "idsItens": [ "B27F1A55-9C3D-4E71-A0B8-6D5C4E3F2A19", "C41E2B66-8D4E-4F82-B1C9-7E6D5F4A3B2C" ], "contaCorrente": { "banco": "237", "agencia": "1234", "conta": "567890" } }' ``` Para contratar **todos** os itens do carrinho, envie apenas a conta corrente: ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/contratos \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: 7d1a4e93-2b58-4c17-9e60-8f3a1b2c4d5e" \ -H "Content-Type: application/json" \ -d '{ "contaCorrente": { "banco": "237", "agencia": "1234", "conta": "567890" } }' ``` --- ## 📥 Responses ### ✅ 202 Accepted ```json { "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666", "contratos": [ { "idItem": "B27F1A55-9C3D-4E71-A0B8-6D5C4E3F2A19", "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6", "tipoContrato": 1, "status": 1 }, { "idItem": "C41E2B66-8D4E-4F82-B1C9-7E6D5F4A3B2C", "identificador": "9E3C7A21-4B58-4D93-8A6F-2C1D0E9B8A77", "tipoContrato": 2, "status": 1 } ], "ursRejeitadas": [ { "idUr": "7D121577-3C5A-494D-B052-291D9E100D0D", "motivo": "UR comprometida por terceiro após a montagem do carrinho." } ], "mensagem": "Contratos recebidos e enviados para registro na registradora!" } ``` ### 🧾 Detalhamento dos Campos #### 🔹 Nível raiz | Campo | Tipo | Descrição | | -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- | | identificadorProcessamento | string | GUID do processamento assíncrono desta requisição, para acompanhamento. | | contratos | array | Contratos criados — um por item contratado. | | ursRejeitadas | array | URs que não puderam ser incluídas nos contratos. Vazio quando todas as URs do carrinho foram aceitas. | | mensagem | string | Mensagem de confirmação. | #### 🔹 contratos | Campo | Tipo | Descrição | | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | idItem | string | GUID do item do carrinho que originou o contrato. | | identificador | string | GUID do contrato criado. Use-o nas demais consultas da seção 5. | | tipoContrato | number | Tipo do contrato: `1` = Troca de titularidade, `2` = Garantia. | | status | number | Status inicial do contrato — normalmente `1` (Aguardando registro). Ver tabela **Status do contrato** em [5.2. Listar contratos](5.2.%20Listar%20contratos.md). | #### 🔹 ursRejeitadas | Campo | Tipo | Descrição | | ------ | ------ | ---------------------------------------------------------------- | | idUr | string | GUID da UR recusada. | | motivo | string | Motivo da recusa, devolvido pela registradora ou pela validação. | --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'contaCorrente.banco' é obrigatório.", "Item 'C41E2B66-8D4E-4F82-B1C9-7E6D5F4A3B2C' não pertence ao carrinho desta agenda.", "Requisição fora da janela de operação (09:00 às 18:00 em dias úteis)." ] } ``` --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Atenção", "status": 404, "erros": [ "Agenda não encontrada." ] } ``` --- ## ⚙️ Modo de falha: atômico ou parcial Quando um dos itens não pode ser contratado, a operação pode se comportar de duas formas: | Modo | Comportamento | | ------- | ------------------------------------------------------------------------------------------------- | | Atômico | Se um item falha, **nenhum contrato é criado**. A resposta devolve `contratos` vazio e o motivo. | | Parcial | Os itens válidos geram contrato e os que falharam são reportados na resposta. | O modo é **configuração da operação**, definida com o time de implantação. **Não é parâmetro da requisição** e não muda de chamada para chamada. Confirme com a implantação qual modo está ativo na sua operação antes de tratar a resposta. --- ## 🔒 URs rejeitadas e ausência de trava de recebível Não existe **trava de recebível** antes do registro na registradora. Entre montar o carrinho e criar o contrato, a mesma UR pode ter sido **comprometida por terceiro** — outra cessão, outra garantia ou uma promessa de cessão registrada nesse intervalo. Nesses casos: 1. A UR volta em `ursRejeitadas`, com o `motivo` da recusa. 2. O contrato é criado apenas com as URs aceitas. 3. Se, descontadas as rejeições, o **valor solicitado no item não for atingido**, o contrato pode ser **cancelado**. Acompanhe o `status` em [5.2. Listar contratos](5.2.%20Listar%20contratos.md) e a notificação em [3.2. Atualizações do contrato](../../3.%20Notificações%20-%20WebHook/3.2.%20Atualizações%20do%20contrato.md). Quanto menor o intervalo entre montar o carrinho e criar o contrato, menor o risco de rejeição. --- ## 🕒 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 criação de contratos é recusada, porque o registro depende da registradora. * O `202 Accepted` confirma o **recebimento**, não o registro. O contrato nasce com `status` `1` (Aguardando registro) e só produz efeito depois do retorno da registradora. * Envie sempre o header `Idempotency-Key`: em caso de reenvio da mesma requisição, evita a criação de contratos duplicados. * Um item já contratado não é contratado novamente. Para operar o restante do carrinho, informe em `idsItens` apenas os itens ainda não contratados. * Contratos de garantia não têm deságio; portanto não há `taxa` nem valores de nominal, desconto e aquisição em nenhuma etapa desses contratos. * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). --- ## 🔄 Mudanças em relação à documentação anterior | Antes | Agora | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `POST /api/v1/cartao/agenda/{id}/contrato` — rota na **versão errada** (`v1` dentro da pasta `v1.1`), com recursos no **singular** e sem o prefixo `/public`. | `POST /public/api/v1.1/cartao/agendas/{idAgenda}/contratos` — versão correta e recursos no plural. | | Corpo vazio (`{}`), que não dizia **o que** contratar quando o carrinho tem N itens. | Corpo com `idsItens` (omitir contrata todos os itens) e `contaCorrente`. | | Retorno com **um único** `identificador`, incompatível com um carrinho que gera N contratos. | Retorno com `identificadorProcessamento`, array `contratos` (um por item) e array `ursRejeitadas`. | | `200 OK`. | `202 Accepted`, coerente com o processamento assíncrono e com o registro pendente na registradora. | | Exemplo de cURL malformado (chaves no meio da URL e `contrato` colado ao identificador). | Exemplos de cURL válidos, com URL completa e headers obrigatórios. |