Ir para o conteúdo

4.3. Criar Parcelas da Garantia

🔗 Endpoint

Método URL
POST /api/v1.1/cartao/agenda/{identificador}/parcela-garantia

🧾 Descrição

Cria as parcelas contratuais que servirão como vínculo de garantia para a operação. Após o cadastro, um processo assíncrono será disparado para vincular automaticamente URs a cada parcela, buscando as melhores URs disponíveis conforme regras de prioridade e prazo.

Não é permitido cadastrar mais de um conjunto de parcelas com o mesmo contratoErp para o mesmo contexto (retornará erro de conflito).

📤 Requisição

📋 Payload (JSON)

{
  "contratoErp": "",
  "valorContrato": 0.00,
  "parcelasTotal": 1,
  "parcelas": [
    {
      "numero": 1,
      "data": "2025-01-01",
      "valor": 1.00
    }
  ]
}

🧾 Detalhamento dos Campos

Campo Tipo Obrigatório Descrição
contratoErp string Sim Identificador do contrato no ERP do cliente (único). Não pode haver outro cadastro com o mesmo valor para o mesmo contexto.
valorContrato number Sim Valor total do contrato (numérico ≥ 0). Esse valor é esperado ser a soma das parcelas; será replicado no contexto do contrato.
parcelasTotal integer Sim Quantidade total de parcelas (inteiro ≥ 1). Deve corresponder ao tamanho do array parcelas.
parcelas array Sim Lista de objetos contendo as parcelas. Deve conter pelo menos 1 item.
→ numero integer Sim Número da parcela (inteiro ≥ 1). Deve ser único dentro do contratoErp.
→ data string Sim Data alvo de liquidação da parcela, em formato ISO YYYY-MM-DD.
→ valor number Sim Valor da parcela (numérico > 0).

Regras de validação

  • contratoErp é obrigatório e único: tentativas de criar outro cadastro com mesmo contratoErp devem retornar 409 Conflict.
  • valorContrato ≥ 0; preferencialmente igual à soma dos valor das parcelas (server pode validar e emitir warning se divergente).
  • parcelasTotal ≥ 1 e deve ser igual a parcelas.length.
  • Cada numero de parcela deve ser único dentro do mesmo contratoErp.
  • data deve ser uma data válida no formato YYYY-MM-DD.
  • valor deve ser maior que zero.

🧪 Exemplo de cURL

curl -X POST https://api.veflow.com/api/v1.1/cartao/agenda/534D8AAE-61E4-4264-9D15-715B9E1F1D51/parcela-garantia \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contratoErp": "CTR-2025-0001",
    "valorContrato": 10000.00,
    "parcelasTotal": 2,
    "parcelas": [
      { "numero": 1, "data": "2025-09-30", "valor": 5000.00 },
      { "numero": 2, "data": "2025-10-30", "valor": 5000.00 }
    ]
  }'

📥 Responses

✅ 200 OK

{
  "mensagem": "Parcelas cadastradas e vínculo automático agendado."
}

Indica que as parcelas foram validadas e registradas. O processo de vinculação automática de URs foi agendado e executado de forma assíncrona.

❌ 400 Bad Request

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Campo 'contratoErp' é obrigatório.",
    "parcelasTotal deve ser igual ao número de itens em 'parcelas'.",
    "valor da parcela 2 é inválido: deve ser > 0."
  ]
}

❌ 409 Conflict

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Conflito",
  "status": 409,
  "erros": [
    "Já existe um cadastro de parcelas para o contratoErp 'CTR-2025-0001'."
  ]
}

🕒 Observações

  • Após o cadastro, a plataforma iniciará um processo que vinculará automaticamente URs às parcelas para compor a garantia da melhor forma possível conforme regras de prioridade (menor prazo, maior valor livre, ordenação configurada, etc.).
  • Por padrão, a alocação automática de URs considerará URs com data de liquidação a partir de 5 (cinco) dias úteis antes da data de vencimento da parcela (ou seja, janela de busca iniciando 5 dias úteis antes da data informada). Ajustes nesta regra podem ser parametrizados em configurações do cliente.
  • Não é permitido criar múltiplos cadastros com o mesmo contratoErp no mesmo contexto (o endpoint retornará 409 Conflict).
  • O sistema valida unicidade dos campos numero por contratoErp no momento do cadastro.
  • A validação da consistência entre valorContrato e a soma das parcelas.valor pode bloqueará o cadastro por padrão.
  • Autenticação obrigatória via Authorization: Bearer {token}.