--- title: 4.11. Adicionar itens em lote url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/4.%20Agenda%20de%20receb%C3%ADveis/v1.1/4.11.%20Adicionar%20itens%20em%20lote/ --- # 4.11. Adicionar itens em lote ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | ------------------------------------------------------------------- | | ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1.1/cartao/agendas/{idAgenda}/carrinho/itens/lote` | --- ## 🧾 Descrição Cria **N itens de carrinho de uma só vez — um item por parcela** de um contrato de garantia parcelada, e dispara a **alocação automática de URs** para cada parcela. É o caminho para a garantia parcelada: em vez de chamar [4.10. Adicionar item](4.10.%20Adicionar%20item.md) uma vez por parcela, você envia o contrato inteiro (identificação no ERP, valor total e o cronograma de parcelas) e a plataforma **VeFlow** monta os itens correspondentes. Cada item criado nasce com `tipoContrato` = `2` (Garantia) e `estrategia` = `4` (Alocação automática por parcela). O processamento é **assíncrono**: a resposta confirma a criação dos itens, devolve o `idItem` de cada parcela e o `identificadorProcessamento` para acompanhar a alocação das URs. > ⚠️ **A alocação automática não reserva a UR.** Como em qualquer item de carrinho, não existe trava de exclusividade antes do registro do contrato na registradora — ver a nota em [4.10. Adicionar item](4.10.%20Adicionar%20item.md). --- ## 📤 Requisição ### 📋 Payload (JSON) ```json { "tipoContrato": 2, "contratoErp": "", "valorContrato": 0.00, "parcelas": [ { "numero": 1, "data": "0000-00-00", "valor": 0.00 } ], "alocacaoAutomatica": { "janelaDiasUteis": 5, "ordem": "ASC", "somenteUrPerformada": false } } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | | ------------------------ | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tipoContrato | integer | Sim | Natureza do contrato dos itens criados. Use `2` = Garantia: o cadastro em lote existe para a garantia parcelada. | | contratoErp | string | Sim | Identificador do contrato no ERP do cliente. **Único por contexto**: não pode haver outro cadastro com o mesmo valor. | | valorContrato | number | Sim | Valor total do contrato (numérico ≥ 0). Deve ser igual à soma dos `valor` das parcelas. | | parcelas | array | Sim | Cronograma de parcelas do contrato. Deve conter ao menos 1 item. Cada parcela vira um item de carrinho. | | → numero | integer | Sim | Número da parcela (inteiro ≥ 1). Deve ser único dentro do mesmo `contratoErp`. | | → data | string | Sim | Data de vencimento da parcela, no formato `YYYY-MM-DD`. É a data que baliza a janela de busca de URs. | | → valor | number | Sim | Valor da parcela (numérico > 0). | | **alocacaoAutomatica** | object | Não | Parâmetros da alocação automática de URs. Quando omitido, valem os padrões descritos abaixo. | | → janelaDiasUteis | integer | Não | Quantos dias úteis **antes** do vencimento da parcela a busca de URs começa. Padrão `5`. | | → ordem | string | Não | `ASC` ou `DESC` (case-insensitive). Define a ordem em que as URs candidatas são varridas dentro da janela. Padrão `ASC`. | | → somenteUrPerformada | boolean | Não | Quando `true`, aloca apenas URs já performadas. Padrão `false`. | **Regras de validação** * `contratoErp` é obrigatório e único: se já existir cadastro com o mesmo `contratoErp` no contexto, a requisição é recusada com **409 Conflict**. * `valorContrato` ≥ 0 e **igual à soma dos `valor` das parcelas**. Divergência **bloqueia** o cadastro com **400 Bad Request** — não é aviso. * `parcelas` deve conter ao menos 1 item. * Cada `numero` de parcela deve ser único dentro do mesmo `contratoErp`. * `data` deve ser uma data válida no formato `YYYY-MM-DD`. * `valor` de cada parcela deve ser maior que zero. * `alocacaoAutomatica.janelaDiasUteis` deve ser um inteiro ≥ 0. * Não há campo `taxa` neste endpoint: contrato de garantia não tem deságio. --- ## 🧪 Exemplo de cURL ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/agendas/534D8AAE-61E4-4264-9D15-715B9E1F1D51/carrinho/itens/lote \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: 0b3f7a91-6c52-4e18-93a7-5d8c1f0b2e43" \ -H "Content-Type: application/json" \ -d '{ "tipoContrato": 2, "contratoErp": "CTR-2025-0001", "valorContrato": 10000.00, "parcelas": [ { "numero": 1, "data": "2025-09-30", "valor": 5000.00 }, { "numero": 2, "data": "2025-10-30", "valor": 5000.00 } ], "alocacaoAutomatica": { "janelaDiasUteis": 5, "ordem": "ASC", "somenteUrPerformada": false } }' ``` --- ## 📥 Responses ### ✅ 202 Accepted ```json { "identificadorProcessamento": "A1B2C3D4-1111-2222-3333-444455556666", "itens": [ { "numeroParcela": 1, "idItem": "7C2C4D03-80BB-43E9-885C-F6A1C2660A68" }, { "numeroParcela": 2, "idItem": "A6B1E4C7-2F0D-4B88-9E51-3C7A2D9F6B04" } ], "mensagem": "Itens do carrinho criados. Alocação automática de URs agendada." } ``` | Campo | Tipo | Descrição | | -------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | identificadorProcessamento | string | GUID do processamento assíncrono da alocação automática, para acompanhamento. | | itens | array | Itens de carrinho criados, um por parcela. | | → numeroParcela | number | Número da parcela que o item garante, conforme informado em `parcelas.numero`. | | → idItem | string | GUID do item criado no carrinho. | | mensagem | string | Mensagem de confirmação. | Os itens já existem no carrinho quando a resposta chega; o que roda de forma assíncrona é a **alocação das URs** em cada um deles. Consulte os itens depois para ver as URs alocadas e o `valorGarantido` de cada parcela. --- ### ❌ 400 Bad Request ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "titulo": "Atenção", "status": 400, "erros": [ "Campo 'contratoErp' é obrigatório.", "Campo 'parcelas' deve conter ao menos um item.", "valorContrato (10.000,00) diverge da soma das parcelas (9.500,00).", "Número da parcela 2 está duplicado no contratoErp 'CTR-2025-0001'.", "valor da parcela 2 é inválido: deve ser > 0." ] } ``` --- ### ❌ 404 Not Found ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "titulo": "Não encontrado", "status": 404, "erros": [ "Agenda '534D8AAE-61E4-4264-9D15-715B9E1F1D51' não encontrada." ] } ``` --- ### ❌ 409 Conflict — `contratoErp` já cadastrado ```json { "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.10", "titulo": "Conflito", "status": 409, "erros": [ "Já existe cadastro de itens para o contratoErp 'CTR-2025-0001'." ] } ``` --- ## 🔄 Mudanças nesta versão * A rota `parcela-garantia` passou a ser `carrinho/itens/lote`. Parcela de garantia **é** um conjunto de N itens de carrinho, e um recurso separado duplicava o conceito: quem consultava o carrinho não encontrava as parcelas, e quem consultava as parcelas não via as URs alocadas. * Saiu o campo `parcelasTotal`, redundante com o tamanho do array `parcelas`. O total é o próprio `parcelas.length`. * O retorno passou de `200 OK` para **`202 Accepted`** com `identificadorProcessamento`: a alocação automática de URs é assíncrona, e o `200` sugeria trabalho concluído. * A janela de busca de URs, antes fixa em 5 dias úteis e ajustável só por configuração do cliente, passou a ser parametrizável na requisição via `alocacaoAutomatica.janelaDiasUteis`. * A divergência entre `valorContrato` e a soma das parcelas passou a **bloquear** o cadastro com `400`. Antes a documentação deixava o comportamento em aberto. --- ## 🕒 Observações * A alocação automática busca, para cada parcela, as melhores URs disponíveis por **prioridade de menor prazo e maior valor livre**, respeitando a janela e a ordenação configuradas. * Por padrão, a busca considera URs com data prevista de liquidação **a partir de 5 dias úteis antes da `data` da parcela**. Esse padrão pode ser alterado por requisição em `alocacaoAutomatica.janelaDiasUteis`. * Cada item criado nasce com `tipoContrato` = `2` (Garantia) e `estrategia` = `4` (Alocação automática por parcela). * Contrato de garantia não tem deságio: os itens deste lote não trazem valor nominal, desconto, aquisição nem taxa. O que se acompanha por parcela é o `valorGarantido`. * Cada item continua sendo administrável individualmente depois do lote: é possível conferir a composição de uma parcela, ajustá-la ou acrescentar um item avulso com [4.10. Adicionar item](4.10.%20Adicionar%20item.md). * Para conferir antes de criar o cronograma inteiro, calcule a composição de uma parcela em [4.9. Prévia do item](4.9.%20Prévia%20do%20item.md). * O lote depende de uma agenda concluída — ver [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md) e [4.3. Detalhes da agenda](4.3.%20Detalhes%20da%20agenda.md). Depois do prazo de validade da agenda, os itens são invalidados e é necessário refazer a consulta em [4.7. Refazer consulta](4.7.%20Refazer%20consulta.md). * Com o carrinho montado, o contrato é gerado em [5.1. Criar contratos](../../5.%20Contrato%20de%20recebíveis/v1.1/5.1.%20Criar%20contratos.md). * Headers obrigatórios e convenções gerais estão descritos em **1.2. Convenções da API**.