Ir para o conteúdo

5.1. Criar contratos

🔗 Endpoint

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

🧭 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 GUID 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:

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