4.11. Adicionar itens em lote¶

🔗 Endpoint¶

Método	URL
	`/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 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.

📤 Requisição¶

📋 Payload (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¶

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¶

{
  "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¶

{
  "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¶

{
  "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¶

{
  "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.
Para conferir antes de criar o cronograma inteiro, calcule a composição de uma parcela em 4.9. Prévia do item.
O lote depende de uma agenda concluída — ver 4.1. Solicitar agenda e 4.3. Detalhes da agenda. Depois do prazo de validade da agenda, os itens são invalidados e é necessário refazer a consulta em 4.7. Refazer consulta.
Com o carrinho montado, o contrato é gerado em 5.1. Criar contratos.
Headers obrigatórios e convenções gerais estão descritos em 1.2. Convenções da API.