Oystr API Documentation

Histórico de Versões

Versão	Descrição
20220704.1	Primeira versão pública
20220719.1	Documentação sobre o header X-Oystr-TraceId
20220919.1	Documentação a reexecução de ítens usando force e retry
20230104.1	Documentando o tamanho máximo da requisição
20230425.1	Removendo documentação sobre a execução direta. Remoção do modo legacy
20230508.1	Alterando documentação de markdown/pdf para html

Considerações Gerais

A API da Oystr está disponível no endereço https://api.oystr.com.br/v1.
Todos os endpoints documentados abaixo são relativos à esta url
Todas as requisições feitas à API devem ter o header X-Oystr-Auth com o token de autenticação válido.
A API da Oystr funciona sempre de forma assíncrona, ou seja, a execução das requisições da API nunca é feita de forma direta. A Oystr sempre retorna um ID para consulta posterior do resultado.

Endpoints

Método	Path	Retorno	Descrição
POST	/execute/single	202	Inicia a execução de um ítem. Retona o id para consulta futura
POST	/execute/single	5XX ou 4XX	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.
GET	/execute/single/[bot-id]/[id]	404	id inválido ou ítem rejeitado. Nunca haverá uma resposta para este item
		202	Resposta indisponível, aguarde
		200	Resposta disponível

Aviso:

O tamanho máximo das requisições http é 50Mb
O tamanho máximo das respostas às requisições http é 100Mb

Formato da Requisição HTTP

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

Descrição dos Campos

Campo	Obrigatório	Formato	Default	Descrição
dry	não	Boolean	false	Indica se é uma execução de teste
bot	sim	String		Id do robô
version	sim	String		Versão do robô
cid	não	String		Identificador único da requisição¹
force	não	Boolean		Indica se um ítem único, discrimidado pelo `cid` deve ser reexecutado ou não
timeout	não	Duration	5 minutos	Tempo máximo aguardando o retorno de um ítem desde o início da execução². Exemplo: 30s
deadline	não	ZonedDateTime		Data máxima para o início da execução do ítem³ no formato ISO 8601. Exemplo: 2022-01-01T00:00:00.0-03:00
credentials	Ver robô	Json		Credenciais a serem usadas na requisição
data	sim	Json		Dados passados diretamente para o robô
files	Ver robô	Json		Arquivos passados para o robô

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
Após este período a resposta será do tipo Timeout
Caso a execução do ítem não tenha iniciado até esta data a resposta será do tipo Overdue

Resultados

Os resultados ficam disponíveis no endereço /execute/single/[bot-id]/[id]?format=latest. O payload em json obtido quando a resposta está disponível segue o seguinte modelo:

{
  "account"    : 0,
  "user"       : 0,
  "bot"        : "",
  "version"    : "",
  "cid"        : "",
  "request"    : "",
  "started"    : "",
  "ended"      : "",
  "taskTime"   : "",
  "timeout"    : "",
  "finishedAs" : "",
  "retry"      : "",
  "dry"        : false,
  "result"     : {},
  "node"       : "",
  "worker"     : "",
  "evt"        : "",
  "origin"     : "",
  "context"    : "",
  "wrapper"    : ""
}

Descrição dos Campos

Campo	Uso	Formato	Descrição
account	Público	Long	Conta que realizou a requisição
user	Público	Long	Usuário que realizou a requisição
bot	Público	String	ID do robô
version	Público	String	Versão do robô
cid	Público	String	Id de integração ([mais detalhes](#markdown-header-requisicoes-duplicadas))
request	Público	String	Id da requisição
started	Público	ZonedDateTime	Data de início da execução do ítem no formato ISO-8601
ended	Público	ZonedDateTime	Data de término da execução do ítem no formato ISO-8601
taskTime	Público	Duration	Tempo de execução do ítem
timeout	Público	Duration	Timeout efetivamente usado
retry	Público	Enum	Indica se possível re-executar o ítem.
dry	Público	Boolean	Indica se é uma execução de teste
finishedAs	Público	Enum	Tipo de resultado (veja os tipos na tabela abaixo)
result	Público	Json	Payload com o resultado
node	Interno	String	BS que executou o ítem
worker	Interno	String	Worker que executou o ítem
evt	Interno	String	Tipo do evento
origin	Interno	String	Nó que emitiu o evento
context	Interno	String	Nome do diretório com o context
wrapper	Interno	String	Versão do wrapper utilizada para executar a requisição

Dados específicos do Robô

Tipos de Resultados

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

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:

ítem não foi executado (com certeza) para esta conta e robô nos últimos 15 dias, ou
ítem possivelmente já foi executado antes (falso 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\\-]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:

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.
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.

Credenciais

É recomendado que as credenciais utilizadas nas chamadas da API sejam salvas no Vault, o cofre de senhas seguro da Oystr.
Neste caso, o campo credentials deve ter no seguinte formato:

{ "hash" : "HASH_DA_CREDENCIAL" }

A documentação da api do vault está disponível aqui.