Skip to main content

API 1:1

CREDENCIALConceitos

Todos os robôs da Oystr que são utilizados através da API 1:1 possuem um nome e versão. Diferente do modelo em lote, onde existe o conceito de filas e execuções com múltiplos itens, na API 1:1 cada requisição representa a execução de um único item de forma isolada.

Cada chamada realizada na API 1:1 dispara uma execução individual de robô, responsável por processar os dados enviados e retornar um resultado específico para aquele item. Essas execuções são independentes entre si e não compartilham estado ou fila.

De maneira geral, para executar um robô utilizando a API 1:1, temos o seguinte fluxo:

OrdemTipoDescrição
*0.1***Opcional***Validar as credenciais que serão utilizadas pelos robôs para acessar um sistema (tribunal, gestão jurídico, etc)*
1**Obrigatório**Criar execução do item e receber o identificador da execução (id assíncrono)
2**Obrigatório**Consultar o retorno/status da execução
3**Obrigatório**Obter o resultado final da execução

0.1 - Validar Credenciais

POST: https://api4.oystr.com.br/credentials/validate/:botId/v3.0.0-dev

USUÁRIOUsuário/Senha E- SENHA (UP)UP

objeto “credentials”“credentials”, com par usuáusuário e senha, seráserá utilizado pelo robôrobô para conseguir acesso ao sistema no qual ele iráirá executar as tarefas. Por exemplo, em um robôrobô de tribunal onde a tarefa éé obter a úúltima movimentaçãmovimentação processual, esse usuáusuário/senha seráserá utilizado para entrar no sistema do tribunal.

Quando informado na requisiçãrequisição (via arquivo payload ou especificado no body da requisiçãrequisição), éé necessánecessário seguir o formato abaixo:

{
   "username": "...",
   "password": "...",
   "credentialsOption": "..."
}
ParâParâmetros
ParâParâmetro Tipo DescriçãDescrição
username String (obrigatóobrigatório) UsuáUsuário utilizado para acessar o sistema em que o robôrobô iráirá executar a tarefa.
password String (obrigatóobrigatório) Senha correspondente ao usuáusuário informado.
credentialsOption String (opcional) Valor opcional que seráserá informado indicando particularidades das opçõopções informadas. Quando necessánecessário, a documentaçãdocumentação do robôrobô iráirá apontar.

CERTIFICADOCertificado Digital A1 (CP)- CP

O objeto “credentials”“credentials” com certificado A1 seráserá utilizado pelo robôrobô para conseguir acesso ao sistema no qual ele iráirá executar as tarefas. Por exemplo, em um robôrobô unificado intimaçõintimações onde a tarefa éé obter a todas as intimaçõintimações disponídisponíveis para o advogado em diversos tribunais do Brasil, esse certificado A1 seráserá utilizado para entrar no sistema de cada tribunal especificado.

Quando informado na requisiçãrequisição (via arquivo payload ou especificado no body da requisiçãrequisição), éé necessánecessário seguir o formato abaixo:

{
   "username": "...",
   "base64Cert": "...",
   "pin": "...",
   "credentialsOption": "..."
}
ParâParâmetros
ParâParâmetro Tipo DescriçãDescrição
username String (obrigatóobrigatório) UsuáUsuário utilizado para acessar o sistema em que o robôrobô iráirá executar a tarefa.
base64Cert String (obrigatóobrigatório) ConteúConteúdo do certificado A1 codificado em Base64
pin String (obrigatóobrigatório) PIN ou senha utilizada para utilizar o certificado.
pin String (opcional) Valor opcional que seráserá informado indicando particularidades das opçõopções informadas. Quando necessánecessário, a documentaçãdocumentação do robôrobô iráirá apontar.

1

Criaçã- Criar Execução dado ExecuçãoItem 1:1

POST: https://api4.oystr.com.br/v1/execute/single

CóCódigo de retorno

Retorno DescriçãDescrição
202 inicia a execuçãexecução de um íítem. Retona o id para
consulta futur
5xx ou 4xx Falha ao iniciar a execuçãexecução do íítem. Nestes
casos éé necessánecessário utilizar (manualmente via
suporte) o header X-Oystr-TraceId retornado
para verificar se o íítem foi recebido pela API e
estáestá em execuçãexecução ou nãnão.

Formato da RequisiçãRequisição (via HTTP)

{
    "dry": false,
    "bot": "",
    "version": "",
    "cid": "",
    "timeout": "",
    "deadline": "",
    "credentials": {
        "username": "",
        "password": ""
    },
    "data": {},
    "files": [{
        "bound": true,
        "property": "",
        "description": "",
        "name": "",
        "data": ""
    }]
}
CAMPOCampo ObrigatóObrigatório Formato Default DescriçãDescrição
dry NãNão Boolean false Indica se éé uma execuçãexecução de teste
bot Sim String   Id do robôrobô
version Sim String   VersãVersão do robôrobô
cid NãNão String vazio Identificador úúnico da requisição¹requisição¹
force NãNão Boolean vazio Indica se um item úúnico, discriminado pelo cid deve ser reexecutado ou nãnão
timeout NãNão Duration 5 minutos Tempo mámáximo aguardando o retorno de um item desde o iníinício da execução²execução². Exemplo: 30s
deadline NãNão ZonedDateTime vazio Data mámáxima para o iníinício da execuçãexecução do item³item³ no formato ISO 8601. Exemplo 2022-01-01T00:00:00.0-03:00
credentials RobôRobô json   Credenciais usadas na requisiçãrequisição
data Sim json   Dados passados diretamente para o robôrobô. Cada robôrobô possuípossuí um formato especíespecífico.
file RobôRobô json   Arquivos passados para o robôrobô
  1. ID usado para evitar requisiçõrequisições duplicadas. Caso o cid nãnão seja úúnico a resposta seráserá do tipo Duplicate . Caso o cid seja inváinválido a requisiçãrequisição seráserá rejeitada
  2. . ApóApós este períperíodo a resposta seráserá do tipo Timeout
  3. Caso a execuçãexecução do íítem nãnão tenha iniciado atéaté esta data a resposta seráserá do tipo Overdue.

2

Retorno- Consultar o retorno da chamadaexecução - (assíassíncrono)

GET: https://api.oystr.com.br/v1/execute/single/:bot/:cached?format=latest

CóCódigo de retorno

Retorno DescriçãDescrição
404 id inváinválido ou íítem rejeitado. Nunca haveráhaverá uma resposta para este item.
202 Reposta indisponíindisponível, aguarde
200 Resposta disponídisponível

Resultados3 - Interpretar e obter o resultado final da execução

Após uma resposta 200, teremos como payload da resposta o resultado final da execução. Os resultados ficam disponídisponíveis no endereçmodelo do endereço /execute/single/[bot-id]/[id]?format=[legacy|latest]abaixo de acordo com o header X-Oystr-ReturnPath.ReturnPath:

GET: https://api.oystr.com.br/v1/execute/single/:bot/:cached?format=latest

O payload recebido depende do valor da variávariável formaforma:

Formato Legado QueryString:- format=legacy

GET: https://api.oystr.com.br/v1/execute/single/:bot/:cached?format=latest
{
    "type": "",
    "payload": {}
}

Formato Recomendado QueryString:- format=latest

O payload em json obtido quando a resposta estáestá disponídisponível segue o seguinte modelo:

{
    "account": 0,
    "user": 0,
    "bot": "",
    "version": "",
    "cid": "",
    "request": "",
    "started": "",
    "ended": "",
    "taskTime": "",
    "timeout": "",
    "finishedAs": "",
    "retry": "",
    "dry": false,
    "result": {}
}

Descrição dos campos:

Campo Formato DescriçãDescrição
account Long Conta que realizou a requisiçãrequisição
user Long UsuáUsuário que realizou a requisiçãrequisição
bot String RobôRobô
version String VersãVersão do robôrobô
cid String id de integraçãintegração
request String Id da requisiçãrequisição
started ZonedDateTime Data de iníinício da execuçãexecução do item no formato ISO-8601
ended ZonedDateTime Data de iníinício da execuçãexecução do item no formato ISO-8601
taskTime Duration Tempo de execuçãexecução do item
timeout Duration Timeout efetivamente usado
retry Enum indica se éé possípossível re-executar o item
dry Json Indica se éé uma execuçãexecução DE TESTE
finishedAs Enum Tipo de resultado (tabela abaixo)
result Json Payload com o resultado

Tipos de retorno

Os tipos de resultados possípossíveis:

Resposta PermiteReexecução ReexecuçãoRecomendada? Origem DescriçãDescrição
Response  Não Bot Resposta váválida
PartialResponse  Não  Bot  
NotAllowed  Sim Bot NãNão éé permitida a execuçãexecução do item
NotFound  Não Bot Item nãnão encontrado
NotConsistent  Não Bot Dados inconsistentes
NotAvailable  Sim Bot Item nãnão disponivel
ProxyError Sim Bot Erro de proxy
CaptchaError Sim Bot Erro de captcha
Forbidden  Sim Bot ExecuçãExecução do item nãnão éé permitida
BotError  Sim Bot Erro no robôrobô
Other NãNão Bot Outros
RequestHasViolations NãNão InfraAPI Pedido contécontém informaçõinformações inváinválidas. O item nãnão foi executado.
NotAndApiRequest NãNão InfraAPI Formato inváinválido de requisiçãrequisição. O item nãnão foi executado
NotAccepted NãNão InfraAPI ExecuçãExecução do item nõnõa foi aceita. O item pode ou nãnão ter sido executado
Timeout NãNão InfraAPI Timeout durante a execuçãexecução do item. O item pode ou nãnão ter sido executado
Overdue NãNão InfraAPI ExecuçãExecução do item ocorreria apíapís o deadline. Item nãnão foi executado
Duplicate NãNão InfraAPI Item duplicado baseado no cid. Item nãnão foi executado
UnexpectedError NãNão InfraAPI Erro inesperado. O item pode ou nãnão ter sido executado
Unknown NãNão InfraAPI Desconhecido. O item pode ou nãonõa ter sido executado

RequisiçõRequisições Duplicadas

A Oystr nãnão testa os dados enviados para a execuçãexecução com a exceçãexceção dos atributos cid e force . Caso o cid esteja presente na requisiçãrequisição, a Oystr faráfará a verificaçãverificação se este cid foi executado nos úúltimos 15 dias para esta conta e robôrobô. Caso o cid seja "duplicado", o íítem seráserá executado apenas se o parâparâmetro force estiver presente com o valor true , caso contrácontrário a resposta do íítem seráserá do tipo Duplicate .

A Oystr emprega uma estratéestratégia estatíestatística para verifica ser o íítem jájá foi executado. Esta estratéestratégia permite falsos positivos, ou seja:

  1. íítem nãnão foi executado (com certeza) para esta conta e robôrobô nos úúltimos 15 dias, ou2
  2. . íítem possivelmente jájá foi executado antes (false positivo)

Um cid , se presente, deve ter entre 1 e 50 carateres alphanuméalphanuméricos ou '-' de acordo com a seguinte expressãexpressão regular: [0-9a-zA-Z\\-]{1,50} . Caso o cid seja inváinválido o íítem nãnão seráserá executado, a requisiçãrequisição seráserá ignorada e ficaráficará sem resposta, retornando 404 em consultas futuras.

ReexecuçãReexecução

Em alguns casos éé possípossível que um íítem seja reexecutado em caso de erro, mesmo que um cid tenha sido utilizado. Os critécritérios que definem se um íítem pode ou nãnão ser reexecutado ficam a cargo do cliente da API que deve observar os seguintes critécritérios:

  1. Se houve uma execuçãexecução anterior "do mesmo" ííten, esta deve ter retornado como insucesso, com o parâparâmetro retry = SAFE . Caso contrácontrário nãnão éé seguro reexecutar o íítem.
  2. . Caso um cid seja utilizado, ele deve ser úúnico ou o parâparâmetro force = true deve ser utilziado para ignorar o teste de duplicidade.

A Oystr nãnão verifica se a requisiçãrequisição anterior retornou com retry = SAFE durante a nova execuçãexecução, mesmo que o cid seja o mesmo. Esta verificaçãverificação fica a cargo do cliente/usuáusuário da api.

Back to top