8.2. Enumerações homônimas entre produtos¶

Mesmo nome, mesmo número, significado diferente

statusAgenda e statusContrato existem com o mesmo nome e no mesmo espaço numérico no Cartão de crédito e na Duplicata Escritural, mas com significados diferentes.

Um mapeamento de enum reaproveitado entre os dois produtos traduz o código para o estado errado sem gerar nenhum erro: o payload é válido, o número existe nas duas tabelas e a integração segue adiante com a informação trocada.

Esta página é para quem integra mais de um produto da Vertrau. A referência completa das enumerações do cartão está em 8.1. Enumerações.

🔢 statusAgenda¶

No Cartão de crédito vai de 1 a 5; na Duplicata Escritural, de 1 a 4.

Código	Cartão de crédito	Duplicata Escritural
1	Agenda disponível	Agenda disponível
2	Agenda vazia	Agenda vazia
3	Agenda com promessa de cessão	Agenda ultrapassou tempo de publicação
4	Agenda ultrapassou tempo de publicação	Agenda com falha
5	Agenda com falha	— (não existe)

O conflito está no código 3: no cartão ele indica promessa de cessão registrada sobre as URs — ônus de terceiro, apenas em leitura, que reduz o valorLivre e não é falha. Na duplicata, o mesmo 3 indica que a agenda ultrapassou o tempo de publicação, que é um caso de exceção operacional.

Consequência prática: quem reaproveita o mapeamento da duplicata no cartão trata uma agenda utilizável como agenda estourada; no sentido inverso, trata uma agenda estourada como agenda com ônus de terceiro.

🔢 statusContrato¶

No Cartão de crédito vai de 1 a 12, cobrindo o ciclo completo de registro, liquidação e cancelamento. Na Duplicata Escritural vai de 1 a 4, com estados consolidados.

Código	Cartão de crédito	Duplicata Escritural
1	Aguardando registro	Ativo
2	Registrando	Erro
3	Falha no registro	Em Processamento
4	Aguardando liquidação	Baixado
5	Cancelado	— (não existe)
6	Em liquidação	— (não existe)
7	Liquidado	— (não existe)
8	Em cancelamento	— (não existe)
9	Falha no cancelamento	— (não existe)
10	Incluindo UR	— (não existe)
11	Substituindo URs	— (não existe)
12	Processando contrato	— (não existe)

Aqui nenhum dos quatro primeiros códigos coincide em significado. O caso mais perigoso é o 2: no cartão é Registrando, um estado transitório saudável; na duplicata é Erro. Um contrato de cartão em andamento normal seria lido como contrato com falha, e um contrato de duplicata com falha seria lido como processamento em curso.

✅ Orientação prática¶

Nunca reaproveite o mesmo mapeamento de enum entre produtos. Mantenha uma tabela de tradução por produto, mesmo quando o nome do campo é idêntico.
Resolva o enum pelo produto de origem da notificação ou da consulta: a rota chamada (/public/api/v1.1/cartao/..., no caso do cartão) e o webhook que recebeu o payload já identificam o produto. Use essa origem como chave do mapeamento, não o nome do campo.
Não deduza o produto pelo intervalo de valores. Os intervalos se sobrepõem: 1 a 4 é válido nos dois produtos, para os dois enums.
Trate código desconhecido como valor futuro — registre a ocorrência e mantenha o recurso em estado neutro, em vez de rejeitar o payload.

🕒 Observações¶

Enumerações do cartão de crédito: 8.1. Enumerações.
statusAgenda da duplicata: 2.4. Consultar Simulação e 7.1. Atualização Solicitação Agenda, na documentação da Duplicata Escritural.
statusContrato da duplicata: 3.3. Consultar Contrato, na documentação da Duplicata Escritural.
Headers obrigatórios e convenções gerais do cartão: 1.1. Primeiros Passos.
Dúvidas de mapeamento entre produtos: contato@vertrau.capital.