Guia de Integração

Este guia apresenta o passo a passo para integrar o seu sistema à API de contratos e partes contrárias Xjur.

Pré-requisitos

• Credenciais de acesso (e-mail e senha) fornecidas pela equipe Xjur
• Subscription key (X-XJUR-SUBSCRIPTION-KEY) fornecida pela equipe Xjur
• URL base da API (produção ou homologação)
• Número SAP (numeroContratoSap) dos contratos que serão atualizados
• Número PNE (numeroPne) e documento contábil (docContabil) para cadastro de partes contrárias

Ambientes

Ambiente	URL Base
Produção	https://apim-xjur-prd.xjur.com.br/v2
Homologação	http://apim-xjur-qa.xjur.com.br/v2

Passo a passo

1. Obtenha o token JWT

As credenciais de acesso (e-mail e senha) são fornecidas pelo time da Xjur. Entre em contato com a equipe para solicitá-las antes de iniciar a integração.

Com as credenciais em mãos, chame o endpoint POST /Autenticacao/Authenticate para obter o token:

POST /Autenticacao/Authenticate HTTP/1.1
Host: apim-xjur-qa.xjur.com.br/v2
Authorization: Bearer <token>
X-XJUR-SUBSCRIPTION-KEY: <sua-chave>
Content-Type: application/json

{
    "email": "user@xjur.com.br",
    "senha": "sua-senha"
}

A resposta contém o campo token com o JWT a ser usado nas requisições seguintes. Consulte a Referência da API para detalhes completos do contrato deste endpoint.

Validade do token

O token tem prazo de expiração — implemente renovação automática no seu sistema para evitar erros 502 por token expirado.

2. Identifique os campos a atualizar

A API aceita atualizações parciais: envie apenas os campos que precisam ser alterados. Campos não informados são ignorados.

Campo	Tipo	Descrição
numeroContratoSap	string	Obrigatório. Identificador do contrato no SAP
valorSaldoAmortizacao	decimal	Valor do saldo de amortização
dataUltAtuVlrAmortizacao	datetime	Data da última atualização do valor de amortização
dataFaturamento	datetime	Data de faturamento
dataInicioVigencia	datetime	Início da vigência do contrato
dataFimVigencia	datetime	Fim da vigência do contrato
statusContrato	integer	Código do status do contrato conforme domínio Xjur

Datas

Todas as datas devem ser enviadas no formato ISO 8601: "2024-01-15T00:00:00Z"

3. Monte a requisição

PUT /contratos HTTP/1.1
Host: apim-xjur-qa.xjur.com.br/v2
Authorization: Bearer <token>
X-XJUR-SUBSCRIPTION-KEY: <sua-chave>
Content-Type: application/json

{
  "numeroContratoSap": "4500001234",
  "statusContrato": 2,
  "dataFimVigencia": "2025-12-31T23:59:59Z"
}

4. Trate a resposta

Sucesso (200): O contrato foi atualizado. O corpo contém o contrato completo retornado pelo Xjur APIM.

{
  "contratoId": 789,
  "numeroContratoSap": "4500001234",
  "statusContratoId": 2,
  "dataFimVigencia": "2025-12-31T23:59:59.000Z",
  "dataAtualizacao": "2024-07-01T14:32:00Z"
}

Erro: Trate conforme os Códigos de Erro.

Cadastro de partes contrárias

Use o endpoint POST /Contrato/AdicionarParteContraria para cadastrar representantes, garantidores ou cônjuges em contratos existentes.

1. Identifique o contrato

Para este fluxo, o contrato é localizado pela combinação:

Campo	Tipo	Descrição
numeroPne	string	Número PNE do contrato
docContabil	string	Documento contábil associado

2. Informe o tipo funcional da requisição

Valores aceitos para tipoRequisicao:

Valor	Descrição funcional
gmcprincgrid01	Representante legal
gmcprincgaran	Garantidor

Nota

Não dependa de configurações internas de classificação do Xjur. A integração deve usar apenas os valores funcionais descritos acima.

3. Monte a lista de pessoas

Cada pessoa deve conter nomeResponsavel, cpfCnpj e ehConjuge.

POST /Contrato/AdicionarParteContraria HTTP/1.1
Host: apim-xjur-qa.xjur.com.br/contratoadaptersap
Authorization: Bearer <token>
X-XJUR-SUBSCRIPTION-KEY: <sua-chave>
Content-Type: application/json

{
  "numeroPne": "PNE123456",
  "docContabil": "4500001234",
  "tipoRequisicao": "gmcprincgrid01",
  "pessoasList": [
    {
      "nomeResponsavel": "Maria Silva",
      "telefone": "11999999999",
      "email": "maria.silva@email.com",
      "cpfCnpj": "529.982.247-25",
      "ehConjuge": false
    }
  ]
}

4. Trate os possíveis resultados

HTTP	Resultado	Como tratar
200	Todos os registros foram processados com sucesso	Prosseguir com o fluxo do cliente
207	Resultados mistos	Avaliar cada item de registros
400	Payload inválido	Corrigir campos obrigatórios, duplicidades ou tipo não suportado
404	PNE não encontrada	Validar numeroPne e docContabil
409	Todos os registros são duplicados	Considerar que não houve nova inclusão

Consulte Partes Contrárias para exemplos completos de request, response e validações.

Idempotência

A API implementa idempotência baseada em hash do payload:

• Se você enviar exatamente o mesmo payload para o mesmo contrato dentro de 24 horas, a resposta anterior será retornada sem nova chamada ao backend.
• Isso previne atualizações duplicadas em caso de retry.
• Se qualquer campo do payload mudar, a atualização será reprocessada normalmente.

sequenceDiagram
  participant C as Cliente
  participant API as XJUR Connect
  participant APIM as Xjur

  C->>API: PUT /contratos (1ª chamada)
  API->>APIM: GET busca contratoId
  APIM-->>API: contratoId = 789
  API->>APIM: PATCH atualiza contrato
  APIM-->>API: contrato atualizado
  API-->>C: 200 OK (resultado salvo em cache)

  C->>API: PUT /contratos (2ª chamada, mesmo payload)
  API-->>C: 200 OK (retorna do cache, sem chamar APIM)

Exemplos de código

cURL

curl -X PUT https://apim-xjur-prd.xjur.com.br/v2/contratos \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-XJUR-SUBSCRIPTION-KEY: $SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numeroContratoSap": "4500001234",
    "valorSaldoAmortizacao": 150000.50,
    "dataFaturamento": "2024-07-01T00:00:00Z",
    "statusContrato": 1
  }'

C# (.NET)

public async Task AtualizarContrato(string token, string numeroContratoSap)
{
    var client = new HttpClient();
    client.BaseAddress = new Uri("https://apim-xjur-prd.xjur.com.br/v2");
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", token);
    client.DefaultRequestHeaders.Add("X-XJUR-SUBSCRIPTION-KEY", subscriptionKey);

    var payload = new
    {
        numeroContratoSap,
        statusContrato = 2,
        dataFimVigencia = new DateTime(2025, 12, 31, 23, 59, 59, DateTimeKind.Utc)
    };

    var response = await client.PutAsJsonAsync("/contratos", payload);

    if (response.IsSuccessStatusCode)
    {
        var resultado = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Sucesso: {resultado}");
    }
    else
    {
        var erro = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Erro {(int)response.StatusCode}: {erro}");
    }
}

Python

import requests

def atualizar_contrato(token: str, numero_contrato_sap: str) -> dict:
    url = "https://apim-xjur-prd.xjur.com.br/v2/contratos"
    headers = {
        "Authorization": f"Bearer {token}",
        "X-XJUR-SUBSCRIPTION-KEY": subscription_key,
        "Content-Type": "application/json",
    }
    payload = {
        "numeroContratoSap": numero_contrato_sap,
        "statusContrato": 2,
        "dataFimVigencia": "2025-12-31T23:59:59Z",
    }

    response = requests.put(url, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()

Tratamento de erros recomendado

try:
    resultado = atualizar_contrato(token, "4500001234")
    print("Atualizado:", resultado)
except requests.HTTPError as e:
    status = e.response.status_code
    body = e.response.json()
    codigo = body.get("codigo")

    if status == 404 and codigo == "CONTRATO_NAO_ENCONTRADO":
        print("Contrato não existe no sistema.")
    elif status == 504 and codigo == "TIMEOUT_SERVICO_EXTERNO":
        print("Serviço indisponível — tente novamente em instantes.")
    elif status == 502:
        print("Erro no serviço externo — contate o suporte.")
    else:
        print(f"Erro inesperado [{status}]: {body}")