Guia de integração

O endpoint

POST /pne/contratos

Recebe uma proposta de negociação aprovada e devolve a pasta criada no Xjur.

Cabeçalho	Obrigatório	Descrição
Authorization	Sim	Bearer <jwt> de usuário de serviço, repassado ao Xjur
X-XJUR-SUBSCRIPTION-KEY	Sim	Chave de assinatura do APIM
Content-Type	Sim	application/json

Autenticação

Igual à integração de anexos da PNE, que já está em produção. São três passos, e o segundo é onde as integrações novas costumam tropeçar.

1. Obtenha o token. POST /Autenticacao/AuthenticateUserService com o e-mail e a senha da conta de integração devolve um JWT válido por 24 horas. O detalhe está em Obtendo o token.

2. A conta precisa ser de usuário de serviço. O Xjur recusa com 401 um token de usuário humano, mesmo válido e mesmo com todas as permissões. A marcação de usuário de serviço é uma propriedade da conta, feita no cadastro do Xjur.

3. Envie o token em toda chamada. O XJUR Connect repassa o cabeçalho Authorization recebido para o Xjur sem alterá-lo. Quem autoriza de fato é o Xjur, não o Connect: o Connect não valida o token nem decide permissão.

Como o token vale 24 horas, implemente renovação automática. Um 401 no meio do dia costuma ser token expirado, não credencial errada.

Estrutura do payload

O corpo tem a identificação da proposta na raiz e uma lista de negociações. Cada negociação carrega suas próprias listas.

{
  numeroPne, numeroVersaoPne, numeroElaboracaoVersaoPne,
  isNovaPasta, numeroPnePai,
  negociacoesList: [
    {
      ...dados da negociação,
      partesContrariasList: [...],
      Garantias: [...],
      ValoresLocacaoList: [...],
      encaixesList: [ { ...investimento, ObrasList: [...] } ],
      EquipamentosList: [...],
      compensacaoVolumetricaPartes: [...]
    }
  ]
}

O contrato completo, campo a campo, está na referência gerada a partir do OpenAPI. A fonte é a DME 12132.

Sobre os nomes dos campos

Os nomes seguem a DME, e a DME mistura convenções. Há campos em camelCase (numeroPne), em PascalCase (TipoValorLocacao, CPFCNPJParte) e alguns totalmente em maiúsculas (GNV). Envie exatamente como está na referência.

O que é validado no XJUR Connect

Só o que dá para afirmar sem consultar cadastro:

• Presença de numeroPne, numeroVersaoPne e numeroElaboracaoVersaoPne
• numeroPnePai presente quando isNovaPasta é 0
• Ao menos uma negociação em negociacoesList
• Em cada negociação: codigoTipoNegociacao, tipoNegociacao, docContabil, tipoContratoPNE
• Ao menos uma parte por negociação, cada uma com papelSignatarioId e CPFCNPJParte

Os domínios dos campos de lista (tipo de negociação, tipo de contrato, papel do signatário, tipo de garantia) são conferidos no Xjur, que é onde as listas estão cadastradas. Um valor fora do domínio retorna 422.

Idempotência

A chave da proposta é numeroPne + numeroVersaoPne + numeroElaboracaoVersaoPne.

Antes de criar, o XJUR Connect pergunta ao Xjur se já existe pasta ativa para essa combinação. Se existir, a resposta traz aquela pasta com a mensagem indicando que a proposta já havia sido recebida, e nenhuma pasta nova é criada.

Isso é o que torna a retentativa segura: depois de um 502 ou 504 você não sabe se a pasta foi criada, e reenviar resolve as duas situações.

Mudar a versão ou a versão de elaboração cria uma pasta nova, porque é outra proposta do ponto de vista do Jurídico.

Desdobramento de proposta

Quando a proposta deriva de outra, envie:

{
  "isNovaPasta": 0,
  "numeroPnePai": "1711454"
}

A pasta nova nasce vinculada à pasta de origem, para a rastreabilidade do ciclo da proposta. Omitir numeroPnePai nesse caso retorna 400.

Divergências em relação à DME 12132

Três pontos onde a implementação difere do documento e que precisam entrar na revisão formal da DME.

A rota. A DME desenha /Contrato/PNE/AdicionaContrato. A implementação usa POST /pne/contratos, seguindo a convenção das demais integrações do XJUR Connect.

O envelope da resposta. A DME desenha { "CODE": 201, "body": { ... } }, repetindo o status HTTP dentro do corpo. A implementação devolve o objeto direto, com o status no HTTP. O formato de erro também segue o padrão do XJUR Connect, descrito em Códigos de erro.

O nome da lista de compensação volumétrica. A DME usa compensacaoVolumetrica para a resposta Sim/Não da negociação e CompensacaoVolumetrica para a lista de postos intervenientes. Os dois diferem apenas na primeira letra, e o XJUR Connect não diferencia maiúsculas ao ler o JSON, o que torna os dois campos ambíguos e impede a requisição de ser processada. A lista passa a trafegar como compensacaoVolumetricaPartes. Essa não é uma preferência de estilo: manter os dois nomes originais inviabiliza o endpoint.

Limites conhecidos

O método de revisão/ajuste, que cancela a pasta quando a proposta volta para revisão, não tem contrato de dados definido na DME e não está implementado.

A sugestão automática de minutas é fase posterior.