Guia de Integração

Este guia apresenta o passo a passo para integrar o seu sistema à API de contratos 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

Ambientes

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

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/AuthenticateUserService para obter o token:

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

{
    "email": "service@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.

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`	ID do status do contrato

3. Monte a requisição

PUT /sap/contratos HTTP/1.1
Host: apim-xjur-qa.xjur.com.br/connect
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.

{
  "camposVisualizacaoPesquisa": null,
  "contratoId": 43754,
  "chavePrimariaId": 43754,
  "clienteId": 163,
  "pastaId": 37233,
  "pastaNome": " - ",
  "tipoContratoId": 913,
  "tipoContratoNome": null,
  "statusContratoId": 61,
  "statusContratoNome": null,
  "statusPastaNome": null,
  "numeroContrato": "37233.001",
  "objetoContrato": null,
  "dataInicioVigencia": "2026-04-23T18:14:45.405Z",
  "periodicidadeId": null,
  "periodicidadeNome": null,
  "dataFimVigencia": "2026-04-23T18:14:45.405Z",
  "observacoesContrato": "Demonstração",
  "departamentoId": null,
  "departamentoNome": null,
  "gestorId": null,
  "gestorNome": null,
  "urgente": false,
  "restrito": false,
  "moedaId": null,
  "moedaNome": null,
  "indiceId": 18,
  "indiceNome": null,
  "bancoId": null,
  "agencia": null,
  "conta": "BRUNO VICENTE DOS SANTOS",
  "valorTotal": 1500.00,
  "valorContrato": null,
  "valorCorrecao": 0.0,
  "valorJuros": 0.0,
  "valorAtualizado": 0.0,
  "dataBaseCorrecao": null,
  "dataFinalAtualizacao": null,
  "dataCadastro": "2025-07-17T09:49:12.5339504",
  "dataAprovacao": "2025-07-17T13:09:52.7",
  "dataAssinatura": null,
  "codigo": null,
  "usuarioIdCadastro": 18,
  "favoritoId": null,
  "estado": null,
  "uf": null,
  "cidade": null,
  "usuarioCadastroNome": null,
  "cabecalho": null,
  "ultimoAssinanteContrato": null,
  "proximoAssinanteContrato": null,
  "threadId": null,
  "openAIConfiguracaoId": 0,
  "numeroContratoSap": "4500001234",
  "valorSaldoAmortizacao": 299.22,
  "dataUltimoAtualValorAmortizacao": "2026-04-23T18:14:45.405Z",
  "dataFaturamento": "2026-04-23T18:14:45.405Z",
  "contratoParteContraria": [],
  "contratoEmpresas": [],
  "processoContratos": []
}

Erro: Trate conforme os Códigos de Erro.

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 /sap/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 /sap/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/connect/sap/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/connect");
    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("/sap/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/connect/sap/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}")