API de Depósitos e Garantia (V2)

A API de Depósitos e Garantias do Themis (versão 2) permite consultar, somente para leitura, os depósitos e garantias cadastrados no sistema, com paginação e filtros.
​

Por meio dela, é possível listar depósitos ou garantias filtrando pela situação do processo, pelo status da garantia, pela área e pelo processo vinculado, além de detalhar cada registro com índice econômico, juros e código de operação.

Ela foi pensada para integrações periódicas, como a alimentação de dashboards de BI. Em relação à V1 (/api/v1/garantias), a V2 traz as seguintes mudanças:
​

Toda chamada precisa do token de um usuário API do Themis, enviado no header X-Aurum-Auth. É o mesmo token já utilizado nas demais APIs do Themis. Saiba mais em Como autenticar requisições na API do Themis.
​

Também é aceito o parâmetro ?token=<seu-token> na URL, mas recomendamos o uso do header, pois URLs costumam ficar gravadas em logs e históricos.
​

Sem token, ou com token inválido, a API responde 417 Expectation Failed com a mensagem "Falha na autenticação."
​

O endereço base é o mesmo utilizado pelas demais APIs do seu Themis:
​

O limite de requisições se renova continuamente ao longo do minuto, e não de uma vez na virada do minuto. Ao receber 429, aguarde os segundos indicados em Retry-After antes de tentar novamente:
​

Path: /api/v2/garantias

Método: GET
​

Retorna uma página de depósitos ou garantias. Os parâmetros categoria e statusProcesso são obrigatórios; sem eles, a resposta é 400 Bad Request. Os demais filtros são opcionais e se somam (todos precisam ser atendidos).
​

Parâmetros a serem repassados na URL como Query Param:

Exemplos:
​

​Exemplo combinando filtros (garantias de processos ativos das áreas 5 e 7, não levantadas, com ou sem reforço, 50 por página, maior saldo primeiro):
​

​Requisição (exemplo):
​

​JSON retornado (exemplo):
​

Os campos de paginação indicam o total de itens (totalElements), o total de páginas (totalPages), a página atual (number) e se ela é a última (last). A resposta traz ainda outros metadados de paginação, que podem ser ignorados.
​

Path: /api/v2/garantias/:id

Método: GET
​

Retorna os mesmos campos da listagem e mais os dados de correção financeira. Não há filtros nem paginação. Se o ID não existir, a resposta é 404 Not Found, sem corpo.
​

Exemplo:
​

​Requisição (exemplo):
​

​JSON retornado (exemplo):
​

Utilize estes códigos nos filtros e para interpretar as respostas.
​

Quando há mais de um erro de validação, todos vêm na mesma resposta:

Como trazer todos os registros para o BI?

Percorra as páginas até last ser true, com size=100 para fazer menos chamadas. Faça uma rodada para cada combinação de filtros obrigatórios de que você precisa:

Mantenha a ordenação padrão (id) durante toda a rodada, para que nenhum item pule de página entre uma chamada e outra.

Com que frequência posso consultar?

Para dashboards, uma ou duas cargas por dia costumam bastar. Dentro de uma carga, espace as chamadas para ficar abaixo de 60 por minuto e, se receber 429, aguarde o tempo indicado em Retry-After antes de continuar.

Preciso chamar a API de Processos para saber o número do processo?

Não. Cada item já traz processo.numero. Use processo.id se precisar cruzar as informações com outras APIs do Themis.

Ficou com alguma dúvida? Entre em contato com nosso time de suporte pelo e-mail [email protected] ou, se preferir, utilize o ícone de chat disponível diretamente no Themis. Estamos à disposição para ajudar.

Estes artigos podem interessar a você: