5.1. Criar contratos¶

🔗 Endpoint¶

Método	URL
	`/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. A operação é de uma modalidade só (antecipação ou garantia), e por isso todos os itens do carrinho têm o mesmo tipoContrato — ver 2.1. Conceitos. O efeito na registradora depende da modalidade da operação: tipoContrato 1 registra troca de titularidade da UR; 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.

🧭 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.

📤 Requisição¶

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

🧬 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¶

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:

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¶

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

🔹 ursRejeitadas¶

Campo	Tipo	Descrição
idUr	string	Identificador da UR recusada.
motivo	string	Motivo da recusa, devolvido pela registradora ou pela validação.

❌ 400 Bad Request¶

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

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

A UR volta em ursRejeitadas, com o motivo da recusa.
O contrato é criado apenas com as URs aceitas.
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 e a notificação em 3.2. Atualizações do contrato.

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.

🔄 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.