API Pública

orgaoservicepub

Gateway público de consulta de Comarcas e Órgãos do TJRJ.
Não requer autenticação por parte do consumidor. Todos os endpoints aceitam apenas requisições GET com parâmetros via query string.

Visão Geral

O orgaoservicepub é um gateway HTTP que expõe de forma pública dois endpoints de consulta ao cadastro de Comarcas e Órgãos do TJRJ. Ele atua como camada intermediária entre o consumidor e o serviço interno, sendo responsável por:

Autenticar automaticamente as requisições no serviço de origem — o consumidor não precisa enviar credenciais
Aplicar rate limiting para proteção do serviço de origem
Rotear corretamente as requisições ao backend

Consumidor ──GET──▶ orgaoservicepub Gateway ──▶ API Interna TJRJ (sem auth) (injeta Basic Auth)

Ambientes

Ambiente	URL Base
PRD Produção	`https://www3.tjrj.jus.br/orgaoservicepub/api`

Todos os exemplos nesta página utilizam a URL de Produção.

Health Check

Endpoint para verificar se o gateway está operacional. Útil para monitoramento e smoke tests pós-deploy.

HTTP

GET /api/health

Resposta esperada:

HTTP/1.1 200 OK text/plain healthy

Endpoints

1. Consultar Comarcas

Retorna a lista de Comarcas de acordo com os filtros informados. Todos os parâmetros são opcionais — se nenhum for enviado, retorna todas as comarcas.

HTTP

GET /api/ServicoPub/Comarca

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`CodComarca`	`integer`	Não	Código identificador único da comarca
`CodComarcaPrincipal`	`integer`	Não	Código da comarca principal (útil para buscar comarcas subordinadas)
`Nome`	`string`	Não	Nome ou parte do nome da comarca (busca parcial)
`CodNur`	`integer`	Não	Código da unidade regional (NUR) à qual a comarca pertence
`PageNumber`	`integer`	Não	Número da página quando `totalPages` > 1

Exemplos de requisição

HTTP — Buscar pelo nome

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Comarca?Nome=Niteroi

HTTP — Buscar por código

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Comarca?CodComarca=15

HTTP — Buscar comarcas de um NUR

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Comarca?CodNur=3

HTTP — Combinar filtros

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Comarca?CodNur=3&Nome=Campos

2. Consultar Órgãos

Retorna a lista de Órgãos de acordo com os filtros informados. Todos os parâmetros são opcionais.

HTTP

GET /api/ServicoPub/Orgao

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`CodOrg`	`integer`	Não	Código identificador único do órgão
`Nome`	`string`	Não	Nome ou parte do nome do órgão (busca parcial)
`CodNur`	`integer`	Não	Código da unidade regional (NUR) à qual o órgão pertence
`CodComarca`	`integer`	Não	Código da comarca à qual o órgão pertence
`IgnoreCache`	`boolean`	Não	Quando `true`, ignora o cache e busca diretamente na origem. Padrão: `false`
`PageNumber`	`integer`	Não	Número da página quando `totalPages` > 1

Exemplos de requisição

HTTP — Buscar pelo nome

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Orgao?Nome=Cartorio

HTTP — Buscar por código

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Orgao?CodOrg=42

HTTP — Buscar órgãos de uma comarca

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Orgao?CodComarca=15

HTTP — Ignorar cache

GET https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Orgao?CodNur=3&IgnoreCache=true

Exemplos Práticos

cURL

bash

# Consultar comarca pelo nome
curl -s "https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Comarca?Nome=Niteroi"

# Consultar órgãos de uma comarca
curl -s "https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Orgao?CodComarca=15"

# Forçar atualização do cache de órgãos
curl -s "https://www3.tjrj.jus.br/orgaoservicepub/api/ServicoPub/Orgao?CodComarca=15&IgnoreCache=true"

# Verificar saúde do gateway
curl -s "https://www3.tjrj.jus.br/orgaoservicepub/api/health"

C# (.NET — HttpClient)

csharp

using var client = new HttpClient
{
    BaseAddress = new Uri("https://www3.tjrj.jus.br/orgaoservicepub/api/")
};

// Consultar comarcas por nome
var response = await client.GetAsync("ServicoPub/Comarca?Nome=Niteroi");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

Usando IHttpClientFactory (recomendado em aplicações ASP.NET Core):

csharp

// Program.cs / Startup
builder.Services.AddHttpClient("orgaoservicepub", client =>
{
    client.BaseAddress = new Uri("https://www3.tjrj.jus.br/orgaoservicepub/api/");
});

// Uso no serviço
public class MinhaService(IHttpClientFactory factory)
{
    public async Task<string> GetComarcasAsync(string nome)
    {
        var client = factory.CreateClient("orgaoservicepub");
        var response = await client.GetAsync($"ServicoPub/Comarca?Nome={Uri.EscapeDataString(nome)}");
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsStringAsync();
    }
}

JavaScript / TypeScript (fetch)

typescript

const BASE_URL = 'https://www3.tjrj.jus.br/orgaoservicepub/api';

// Consultar órgãos por comarca
async function getOrgaos(codComarca: number, ignoreCache = false): Promise<unknown> {
    const params = new URLSearchParams({
        CodComarca: String(codComarca),
        ...(ignoreCache && { IgnoreCache: 'true' }),
    });

    const response = await fetch(`${BASE_URL}/ServicoPub/Orgao?${params}`);

    if (!response.ok) {
        throw new Error(`Erro HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
}

// Consultar comarca pelo nome
async function getComarcas(nome: string): Promise<unknown> {
    const params = new URLSearchParams({ Nome: nome });
    const response = await fetch(`${BASE_URL}/ServicoPub/Comarca?${params}`);

    if (!response.ok) {
        throw new Error(`Erro HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
}

Python (requests)

python

import requests

BASE_URL = "https://www3.tjrj.jus.br/orgaoservicepub/api"

def get_comarcas(nome: str = None, cod_comarca: int = None, cod_nur: int = None):
    params = {}
    if nome:        params["Nome"] = nome
    if cod_comarca: params["CodComarca"] = cod_comarca
    if cod_nur:     params["CodNur"] = cod_nur

    response = requests.get(f"{BASE_URL}/ServicoPub/Comarca", params=params)
    response.raise_for_status()
    return response.json()

def get_orgaos(nome: str = None, cod_comarca: int = None, ignore_cache: bool = False):
    params = {}
    if nome:         params["Nome"] = nome
    if cod_comarca:  params["CodComarca"] = cod_comarca
    if ignore_cache: params["IgnoreCache"] = "true"

    response = requests.get(f"{BASE_URL}/ServicoPub/Orgao", params=params)
    response.raise_for_status()
    return response.json()

# Exemplos de uso
comarcas = get_comarcas(nome="Niteroi")
orgaos   = get_orgaos(cod_comarca=15, ignore_cache=True)

Rate Limiting

O gateway aplica um limite de taxa (rate limiting) por janela fixa para proteger o serviço de origem.

Requisições permitidas

1.000

por segundo

Fila de espera

Nenhuma

rejeição imediata

Política

Fixed Window

janela de 1 segundo

Quando o limite é atingido, o gateway responde imediatamente com:

HTTP/1.1 429 Too Many Requests Rate limit exceeded.

Dica: Se o seu sistema realiza consultas em lote, distribua as requisições no tempo ou implemente retry com exponential backoff.

Exemplo de retry com backoff em C# usando Polly:

csharp

// Usando Polly (Microsoft.Extensions.Http.Polly)
builder.Services.AddHttpClient("orgaoservicepub", client =>
    {
        client.BaseAddress = new Uri("https://www3.tjrj.jus.br/orgaoservicepub/api/");
    })
    .AddTransientHttpErrorPolicy(policy =>
        policy.OrResult(r => r.StatusCode == HttpStatusCode.TooManyRequests)
              .WaitAndRetryAsync(3, attempt => TimeSpan.FromMilliseconds(200 * attempt)));

Códigos de Resposta

Código	Status	Quando ocorre	O que fazer
200	OK	Requisição processada com êxito	Consumir o resultado normalmente
404	Not Found	O path informado não existe neste gateway	Verifique a URL — consulte a seção Endpoints
429	Too Many Requests	Limite de 1.000 req/s atingido	Aguarde e reenvie com exponential backoff
502	Bad Gateway	O serviço de origem está indisponível	Tente novamente mais tarde; acione o suporte se persistir
504	Gateway Timeout	O serviço de origem não respondeu em 60 segundos	Tente novamente; pode ser instabilidade pontual

FAQ

Preciso enviar um token ou credencial para consumir a API?

Não. O gateway injeta automaticamente as credenciais de acesso ao serviço interno. Consuma os endpoints diretamente, sem nenhum header de autenticação.

Posso combinar múltiplos filtros na mesma requisição?

Sim. Todos os parâmetros são cumulativos — quanto mais filtros informados, mais específico o resultado retornado.

O que acontece se eu não passar nenhum parâmetro?

O endpoint retorna todos os registros disponíveis. Use com cautela, pois o volume de dados pode ser expressivo.

O parâmetro IgnoreCache existe apenas no endpoint de Órgãos. Por quê?

O endpoint de Comarcas não utiliza cache no serviço de origem, portanto esse controle não se aplica a ele.

Como sei se o gateway está no ar antes de fazer chamadas?

Consulte o health check: GET /api/health. Retorno 200 healthy indica que o gateway está operacional.

Qual o timeout máximo de uma requisição?

O gateway aguarda até 60 segundos pela resposta do serviço de origem antes de retornar 504 Gateway Timeout.

Os endpoints suportam paginação?

A paginação, se existente, é controlada pelo serviço de origem. Consulte a equipe responsável pelo backend caso precise de controle sobre o volume de resultados retornados.