# API 1:1

### **CREDENCIAL**

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

#### **USUÁRIO E SENHA (UP)**

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

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

```json
{
   "username": "...",
   "password": "...",
   "credentialsOption": "..."
}
```

##### **Parâmetros**

<table border="1" id="bkmrk-par%C3%A2metro-tipo-descr" style="width: 100%; border-collapse: collapse; border-style: solid;"><thead><tr><th style="width: 19.4045%;">Parâmetro</th><th style="width: 20.0183%;">Tipo</th><th style="width: 60.566%;">Descrição</th></tr></thead><tbody><tr><td style="width: 19.4045%;">**username**</td><td style="width: 20.0183%;">*String (obrigatório)*</td><td style="width: 60.566%;">Usuário utilizado para acessar o sistema em que o robô irá executar a tarefa.</td></tr><tr><td style="width: 19.4045%;">**password**</td><td style="width: 20.0183%;">*String (obrigatório)*</td><td style="width: 60.566%;">Senha correspondente ao usuário informado.</td></tr><tr><td style="width: 19.4045%;">**credentialsOption**</td><td style="width: 20.0183%;">*String (opcional)*</td><td style="width: 60.566%;">Valor opcional que será informado indicando particularidades das opções informadas. Quando necessário, a documentação do robô irá apontar.</td></tr></tbody></table>

#### **CERTIFICADO A1 (CP)**

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

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

```
{
   "username": "...",
   "base64Cert": "...",
   "pin": "...",
   "credentialsOption": "..."
}
```

##### **Parâmetros**

<table border="1" id="bkmrk-par%C3%A2metro-tipo-descr-1" style="width: 100%; border-collapse: collapse; border-style: solid;"><thead><tr><th style="width: 12.7303%;">Parâmetro</th><th style="width: 20.1461%;">Tipo</th><th style="width: 67.1124%;">Descrição</th></tr></thead><tbody><tr><td style="width: 12.7303%;">**username**</td><td style="width: 20.1461%;">*String (obrigatório)*</td><td style="width: 67.1124%;">Usuário utilizado para acessar o sistema em que o robô irá executar a tarefa.</td></tr><tr><td style="width: 12.7303%;">**base64Cert**</td><td style="width: 20.1461%;">*String (obrigatório)*</td><td style="width: 67.1124%;">Conteúdo do certificado A1 codificado em [Base64](https://pt.wikipedia.org/wiki/Base64)</td></tr><tr><td style="width: 12.7303%;">**pin**</td><td style="width: 20.1461%;">*String (obrigatório)*</td><td style="width: 67.1124%;">PIN ou senha utilizada para utilizar o certificado.</td></tr><tr><td style="width: 12.7303%;">**pin**</td><td style="width: 20.1461%;">*String (opcional)*</td><td style="width: 67.1124%;">Valor opcional que será informado indicando particularidades das opções informadas. Quando necessário, a documentação do robô irá apontar.</td></tr></tbody></table>

### **Criação da Execução 1:1**

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

**Código de retorno**

<table border="1" id="bkmrk-retorno-descri%C3%A7%C3%A3o-20" style="width: 99.6296%; height: 173.125px; border-collapse: collapse; border-style: solid;"><thead><tr style="height: 29.7017px;"><th style="width: 21.6788%; height: 29.7017px;">**Retorno**</th><th style="width: 78.5538%; height: 29.7017px;">**Descrição**</th></tr></thead><tbody><tr style="height: 46.5057px;"><td style="width: 21.6788%; height: 46.5057px;">202</td><td style="width: 78.5538%; height: 46.5057px;">inicia a execução de um ítem. Retona o id para   
consulta futur</td></tr><tr style="height: 96.9176px;"><td style="width: 21.6788%; height: 96.9176px;">5xx ou 4xx</td><td style="width: 78.5538%; height: 96.9176px;">Falha ao iniciar a execução do ítem. Nestes   
casos é necessário utilizar (manualmente via   
suporte) o header X-Oystr-TraceId retornado   
para verificar se o ítem foi recebido pela API e   
está em execução ou não.</td></tr></tbody></table>

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

```json
{
    "dry": false,
    "bot": "",
    "version": "",
    "cid": "",
    "timeout": "",
    "deadline": "",
    "credentials": {
        "username": "",
        "password": ""
    },
    "data": {},
    "files": [{
        "bound": true,
        "property": "",
        "description": "",
        "name": "",
        "data": ""
    }]
}
```

<table border="1" id="bkmrk-campo-obrigat%C3%B3rio-fo" style="width: 100%; border-collapse: collapse; border-style: solid;"><thead><tr><th style="width: 13.4719%;">**CAMPO**</th><th style="width: 13.1011%;">**Obrigatório**</th><th style="width: 16.0638%;">**Formato**</th><th style="width: 13.4755%;">**Default**</th><th style="width: 43.8764%;">**Descrição**</th></tr></thead><tbody><tr><td style="width: 13.4719%;">dry</td><td style="width: 13.1011%;">Não</td><td style="width: 16.0638%;">Boolean</td><td style="width: 13.4755%;">false</td><td style="width: 43.8764%;">Indica se é uma execução de teste</td></tr><tr><td style="width: 13.4719%;">bot</td><td style="width: 13.1011%;">Sim</td><td style="width: 16.0638%;">String</td><td style="width: 13.4755%;"> </td><td style="width: 43.8764%;">Id do robô</td></tr><tr><td style="width: 13.4719%;">version</td><td style="width: 13.1011%;">Sim</td><td style="width: 16.0638%;">String</td><td style="width: 13.4755%;"> </td><td style="width: 43.8764%;">Versão do robô</td></tr><tr><td style="width: 13.4719%;">cid</td><td style="width: 13.1011%;">Não</td><td style="width: 16.0638%;">String</td><td style="width: 13.4755%;">vazio</td><td style="width: 43.8764%;">Identificador único da requisição¹</td></tr><tr><td style="width: 13.4719%;">force</td><td style="width: 13.1011%;">Não</td><td style="width: 16.0638%;">Boolean</td><td style="width: 13.4755%;">vazio</td><td style="width: 43.8764%;">Indica se um item único, discriminado pelo cid deve ser reexecutado ou não</td></tr><tr><td style="width: 13.4719%;">timeout</td><td style="width: 13.1011%;">Não</td><td style="width: 16.0638%;">Duration</td><td style="width: 13.4755%;">5 minutos</td><td style="width: 43.8764%;">Tempo máximo aguardando o retorno de um item desde o início da execução². Exemplo: 30s</td></tr><tr><td style="width: 13.4719%;">deadline</td><td style="width: 13.1011%;">Não</td><td style="width: 16.0638%;">ZonedDateTime</td><td style="width: 13.4755%;">vazio</td><td style="width: 43.8764%;">Data máxima para o início da execução do item³ no formato ISO 8601. Exemplo 2022-01-01T00:00:00.0-03:00</td></tr><tr><td style="width: 13.4719%;">credentials</td><td style="width: 13.1011%;">Robô</td><td style="width: 16.0638%;">json</td><td style="width: 13.4755%;"> </td><td style="width: 43.8764%;">Credenciais usadas na requisição</td></tr><tr><td style="width: 13.4719%;">data</td><td style="width: 13.1011%;">Sim</td><td style="width: 16.0638%;">json</td><td style="width: 13.4755%;"> </td><td style="width: 43.8764%;">Dados passados diretamente para o robô. Cada robô possuí um formato específico.</td></tr><tr><td style="width: 13.4719%;">file</td><td style="width: 13.1011%;">Robô</td><td style="width: 16.0638%;">json</td><td style="width: 13.4755%;"> </td><td style="width: 43.8764%;">Arquivos passados para o robô</td></tr></tbody></table>

1. ID usado para evitar requisições duplicadas. Caso o cid não seja único a resposta será do tipo Duplicate . Caso o cid seja inválido a requisição será rejeitada
2. . Após este período a resposta será do tipo Timeout
3. Caso a execução do ítem não tenha iniciado até esta data a resposta será do tipo Overdue.

### **Retorno da chamada (assíncrono)**

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

**Código de retorno**

<table id="bkmrk-retorno-descri%C3%A7%C3%A3o-40"><thead><tr><th>**Retorno**</th><th>**Descrição**</th></tr></thead><tbody><tr><td>404</td><td>id inválido ou ítem rejeitado. Nunca haverá uma resposta para este item.</td></tr><tr><td>202</td><td>Reposta indisponível, aguarde</td></tr><tr><td>200</td><td>Resposta disponível</td></tr></tbody></table>

**Resultados**

Os resultados ficam disponíveis no endereço /execute/single/\[bot-id\]/\[id\]?format=\[legacy|latest\] de acordo com o header X-Oystr-ReturnPath.

O payload recebido depende do valor da variável forma

**Formato Legado** QueryString: format=legacy

```json
{
    "type": "",
    "payload": {}
}
```

**Formato Recomendado** QueryString: format=latest

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

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

<table border="1" id="bkmrk-campo-formato-descri" style="width: 99.3827%; height: 445.526px; border-collapse: collapse; border-style: solid;"><thead><tr style="height: 29.7017px;"><th style="width: 21.0768%; height: 29.7017px;">**Campo**</th><th style="width: 26.1283%; height: 29.7017px;">**Formato**</th><th style="width: 52.7791%; height: 29.7017px;">**Descrição**</th></tr></thead><tbody><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">account</td><td style="width: 26.1283%; height: 29.7017px;">Long</td><td style="width: 52.7791%; height: 29.7017px;">Conta que realizou a requisição</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">user</td><td style="width: 26.1283%; height: 29.7017px;">Long</td><td style="width: 52.7791%; height: 29.7017px;">Usuário que realizou a requisição</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">bot</td><td style="width: 26.1283%; height: 29.7017px;">String</td><td style="width: 52.7791%; height: 29.7017px;">Robô</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">version</td><td style="width: 26.1283%; height: 29.7017px;">String</td><td style="width: 52.7791%; height: 29.7017px;">Versão do robô</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">cid</td><td style="width: 26.1283%; height: 29.7017px;">String</td><td style="width: 52.7791%; height: 29.7017px;">id de integração</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">request</td><td style="width: 26.1283%; height: 29.7017px;">String</td><td style="width: 52.7791%; height: 29.7017px;">Id da requisição</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">started</td><td style="width: 26.1283%; height: 29.7017px;">ZonedDateTime</td><td style="width: 52.7791%; height: 29.7017px;">Data de início da execução do item no formato ISO-8601</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">ended</td><td style="width: 26.1283%; height: 29.7017px;">ZonedDateTime</td><td style="width: 52.7791%; height: 29.7017px;">Data de início da execução do item no formato ISO-8601</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">taskTime</td><td style="width: 26.1283%; height: 29.7017px;">Duration</td><td style="width: 52.7791%; height: 29.7017px;">Tempo de execução do item</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">timeout</td><td style="width: 26.1283%; height: 29.7017px;">Duration</td><td style="width: 52.7791%; height: 29.7017px;">Timeout efetivamente usado</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">retry</td><td style="width: 26.1283%; height: 29.7017px;">Enum</td><td style="width: 52.7791%; height: 29.7017px;">indica se é possível re-executar o item</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">dry</td><td style="width: 26.1283%; height: 29.7017px;">Json</td><td style="width: 52.7791%; height: 29.7017px;">Indica se é uma execução DE TESTE</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">finishedAs</td><td style="width: 26.1283%; height: 29.7017px;">Enum</td><td style="width: 52.7791%; height: 29.7017px;">Tipo de resultado (tabela abaixo)</td></tr><tr style="height: 29.7017px;"><td style="width: 21.0768%; height: 29.7017px;">result</td><td style="width: 26.1283%; height: 29.7017px;">Json</td><td style="width: 52.7791%; height: 29.7017px;">Payload com o resultado</td></tr></tbody></table>

#### **Tipos de retorno**

Os tipos de resultados possíveis:

<table border="1" id="bkmrk-resposta-permite-ree" style="width: 100%; border-collapse: collapse; border-style: solid;"><thead><tr><th style="width: 22%;">**Resposta**</th><th style="width: 19.2809%;">**Permite Reexecução**</th><th style="width: 12.2393%;">**Origem**</th><th style="width: 46.4686%;">**Descrição**</th></tr></thead><tbody><tr><td style="width: 22%;">Response</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Resposta válida</td></tr><tr><td style="width: 22%;">PartialResponse</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;"> </td><td style="width: 46.4686%;"> </td></tr><tr><td style="width: 22%;">NotAllowed</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Não é permitida a execução do item</td></tr><tr><td style="width: 22%;">NotFound</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Item não encontrado</td></tr><tr><td style="width: 22%;">NotConsistent</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Dados inconsistentes</td></tr><tr><td style="width: 22%;">NotAvailable</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Item não disponivel</td></tr><tr><td style="width: 22%;">ProxyError</td><td style="width: 19.2809%;">Sim</td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Erro de proxy</td></tr><tr><td style="width: 22%;">CaptchaError</td><td style="width: 19.2809%;">Sim</td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Erro de captcha</td></tr><tr><td style="width: 22%;">Forbidden</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Execução do item não é permitida</td></tr><tr><td style="width: 22%;">BotError</td><td style="width: 19.2809%;"> </td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Erro no robô</td></tr><tr><td style="width: 22%;">Other</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Bot</td><td style="width: 46.4686%;">Outros</td></tr><tr><td style="width: 22%;">RequestHasViolations</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Pedido contém informações inválidas. O item não foi executado.</td></tr><tr><td style="width: 22%;">NotAndApiRequest</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Formato inválido de requisição. O item não foi executado</td></tr><tr><td style="width: 22%;">NotAccepted</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Execução do item nõa foi aceita. O item pode ou não ter sido executado</td></tr><tr><td style="width: 22%;">Timeout</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Timeout durante a execução do item. O item pode ou não ter sido executado</td></tr><tr><td style="width: 22%;">Overdue</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Execução do item ocorreria apís o deadline. Item não foi executado</td></tr><tr><td style="width: 22%;">Duplicate</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Item duplicado baseado no cid. Item não foi executado</td></tr><tr><td style="width: 22%;">UnexpectedError</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Erro inesperado. O item pode ou não ter sido executado</td></tr><tr><td style="width: 22%;">Unknown</td><td style="width: 19.2809%;">Não</td><td style="width: 12.2393%;">Infra</td><td style="width: 46.4686%;">Desconhecido. O item pode ou nõa ter sido executado</td></tr></tbody></table>

#### **Requisições Duplicadas**

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

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

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

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

#### **Reexecução**

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

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

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