Skip to main content

API - LOTE

Conceitos

Todos os robôs da Oystr que são utilizados através da API de lotes tem um nome e versão. Os robôs da Oystr trabalham e operam em execuções. Uma execução contém itens que fazem parte de uma fila. Cada item da fila é consumida por uma execução de robô. As execuções podem ter vários robôs trabalhando ao mesmo tempo. Após a execução é possível você ter acesso aos dados de relatório e saída do robô.

De maneira geral, para se criar uma execução e rodar um robô, temos que realizar as seguintes tarefas na ordem descrita:

Ordem Tipo Descrição
*0.1* **Opcional** *Validar as credenciais que serão utilizadas pelos robôs para acessar um sistema (tribunal, gestão jurídico, etc)*
*0.2* **Opcional** *Executar uma proto fila para obter itens*
1 **Obrigatório** Criar uma fila de itens
2 **Obrigatório** Anexar arquivos a fila de itens (apenas para os robôs que fazem upload de arquivos)
3 **Obrigatório** Iniciar a execução
4 **Obrigatório** Consultar o status da execução
5 **Obrigatório** Consultar o informações da execução
6 **Obrigatório** Validar as respostas/dados/journal da execução
7 **Obrigatório** Obter o relatório/resultado da execução

Respostas Assíncronas da API

Antes de continuar, é importante entender o conceito de que muitas das chamadas na API da Oystr retornam respostas de maneira assíncrona.

Isso quer dizer que a resposta da chamada não estará pronta de imediato e você receberá um id para consultar o resultado da chamada posteriormente.

O design da API leva em consideração o tempo que os robôs demoram para executar uma determinada tarefa. Lembre-se, algumas tarefas podem demorar horas para finalizar. Isso significa que seu código de integração precisa estar preparado para lidar com essas respostas assíncronas.

A seguir, veja um exemplo de chamada que recebe um id de consulta assíncrona.

http POST https://api4.oystr.com.br/v1/[método de retorno assíncrono] X-Oystr-Auth:[token]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "[id]"
}

O retorno de um método assíncrono é um json com um único campo: id. Precisamos fazer uma segunda chamada na API, usando o id retornado na chamada anterior para consultar se o resultado já está pronto. Considere uma chamada para validação de credencial no robô de testes “sample”, usando o usuário “zzz” e a senha “zzz”. Segue exemplo:

http POST https://api4.oystr.com.br/v1/credentials/validate/sample/v1.0 X-Oystr-Auth:[token] username=zzz password=zzz

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "zqwG3hcEGxYl457T8A1d6qS77PCky71HgWdBDj4Z1sTmV6mqlp5VCcCs1ZutIEue"
}

Após esta chamada, agora temos em mãos o id de consulta do resultado da nossa chamada assíncrona. O recomendado é que se consulte no mínimo a cada 10 segundos e no máximo a cada 120 segundos.

A partir de agora, precisamos consultar continuamente a API, até que tenhamos a confirmação de conclusão da execução.

Neste momento, podemos ter 3 tipos de código de resposta: 200, 404 ou 500. Abaixo, segue descrição de cada tipo de resposta.

Código Tipo Descrição
200 OK - Resultado pronto Com o payload da resposta, você receberá os dados relacionados ao seu resultado.
404 | 204 Resultado não disponível ainda Neste caso indica-se que os dados ainda não estão prontos.
500 Erro interno Neste caso entrar em contato conosco e informar o ID da chamada.

Segue um exemplo de consulta, com resposta:

http GET https://api4.oystr.com.br/v1/cached/[id] X-Oystr-Auth:[token]
HTTP/1.1 404 NOT FOUND // indica que o resultado não está pronto
// 3 segundos depois
http GET https://api4.oystr.com.br/v1/cached/[id] X-Oystr-Auth:[token]
HTTP/1.1 200 OK
Content-Type: application/json
{
    "Message"     : null,
    "notAllowed"  : null,
    "notAvailable": null,
    "Valid"       : true
}

Back to top