Empresas na API¶

Esta API permite o cadastro de novas empresas usuárias do portal Digesto Operações.

Detalhes de uma empresa (`/api/user_company`)¶

Representa uma empresa usuária do Digesto Operações. Uma empresa é composta de usuários do sistema e por processos monitorados.

Diversas outras entidades na API também estão atreladas a uma user_company:

Inclusive uma user_company pode ser atrelada à user_company mãe dela.

Uma user_company é representada por um dicionário JSON com os seguintes campos:

Nome	Tipo	Descrição
$uri	string
api_name	string,null	Campo livre de até 150 caracteres. Quando fornecido, este texto é enviado em todas as chamadas web-hook desta empresa. Pode ser usado como forma de autenticação.
created_at	object,null
enabled_modules	array<string>
archived_at	datetime	Se foi excluido (nullable=True). Caso entidade tenha sido excluída, este campo tem o valor da datahora da última exclusão. Caso não esteja excluído, o valor é `null`. Campo somente-leitura.
admin_email	string,null
logo_url	string,null
trib_monitor_config	string,null	Dicionário JSON com regras de negócio para monitoramento em tribunais. Ver tabela abaixo. Quando não informado, copiamos o valor da empresa-mãe.
url_monitor_config	string,null	Dicionário JSON com regras de negócio para monitoramento de URLs. Ver tabela abaixo. Quando não informado, copiamos o valor da empresa-mãe.
protocolo_config	string,null	Dicionário JSON com regras de negócio para protocolização. Ver tabela abaixo. Quando não informado, copiamos o valor da empresa-mãe.
name [1]	string	Nome da empresa. Não pode se repetir.
user_company	object	Referência à empresa à qual o pedido pertence. (“UserCompany”). Campo somente-leitura, preenchido automaticamente na criação.
users	array	Lista de referencias aos usuários da empresa.

[1]	Obrigatório na criação de entidades.

trib_monitor_config¶

Dicionário JSON com regras de negócio para monitoramento de processos e partes.

Nome	Tipo	Descrição
create_cadastro_on_distrib	boolean	Cria cadastro agendado para cada nova distribuição
create_event_on_distrib	boolean	Cria evento para cada nova distribuição
create_event_on_movs	boolean	Cria evento para cada nova movimentação nos processos
create_event_on_publ	boolean	Cria evento para cada nova publicação nos processos
all_movs_on_first_day	boolean	Ao cadastrar um novo processo, o primeiro evento gerado possui todos os movimentos conhecidos do processo. No dia seguinte passamos a enviar só os novos movimentos. Default = false.

url_monitor_config¶

Dicionário JSON com regras de negócio para monitoramento de processos e partes.

Nome	Tipo	Descrição
send_emails	boolean	Envia email apos mudanças detectadas em URLs monitoradas
dest_emails	array	Lista de strings com endereços de emails
dest_emails_bcc	array	Lista de strings com endereços de emails (cópia oculta)

protocolo_config¶

Dicionário JSON com regras de negócio para monitoramento de processos e partes.

Nome	Tipo	Descrição
protocolo_publish_finished_to	array	Lista de e-mails avisados após cada protocolação
protocolo_publish_finished_bcc	array	Lista de e-mails avisados em BCC

users¶

É a lista de usuários associados a esta empresa.

Nome	Tipo	Descrição	Exemplo
$ref	string	URL relativa na API da entidade referenciada	/api/user/3

É possível listar as empresas filhas da empresa em que o usuário atualmente logado se encontra fazendo uma chamada API HTTP GET https://op.digesto.com.br/api/user_company.

Criando novas empresas (user_company)¶

Ao criar uma nova empresa dentro da API, ela será uma empresa filha da empresa à qual o usuário que fez a criação pertence.

Logo após criar a Empresa-Filha, você pode fazer uma chamada para Recuperar o token de API do usuário administrador de uma empresa. Nesse caso, as duas chamadas (para criar a empresa e para pegar o token do admin inicial da Empresa-Filha) são realizadas usando o token de API da Empresa-mãe.

As demais operações dessa nova Empresa-Filha devem ser feitas com este token de API recem-recuperado.

Um usuário só enxerga as entidades/recursos da empresa dele. Ele também só pode criar entidades que nascem associadas à empresa dele. O máximo que um usuário administrador pode fazer é criar uma nova empresa filha e recuperar um token de API para administrar os recursos dela.

O fluxo resumido para provisionamento de novos clientes seria então:

Criar nova Empresa-Filha, usando o token de um administrador da Empresa-mãe (chamada abaixo)
Com o token de um administrador da Empresa-mãe, fazer uma chamada para Recuperar o token de API do usuário administrador de uma empresa do administrador da Empresa-Filha recém-criada
Com o token do administrador da Empresa-Filha, criar as partes monitoradas Registrando partes para monitoramento, processos etc.
Caso a integração seja via webhooks (nossa API faz chamadas para o sistema do cliente com novos eventos), é necessário fazer login no Digesto Operações com o e-mail do administrador da nova Empresa-Filha, e ir em Configurações - Integração via API para configurar o endereço HTTP para onde enviaremos os eventos de monitoramento. Cada user_company tem seu endereço de webhook próprio.

Os usuários da user_company-mãe não enxergam as entidades (partes monitoradas, processos monitorados, usuários etc) da user_company filha.

Toda chamada feita com um API token de um usuário se refere à empresa deste usuário. Ex.: entidades criadas com o token de um usuário da empresa filha, ficarão na empresa filha. Esta hierarquia é ilustrada na figura abaixo.

Hierarquia entre empresas e suas entidades.

POST https://op.digesto.com.br/api/user_company¶

Cria nova empresa na API.

Exemplo de chamada:

POST https://op.digesto.com.br/api/user_company HTTP/1.1
Content-Type: application/json

{
  "name": "Nova empresa"
}

Exemplo de resposta:

Note que na resposta abaixo, 7 é o id da user_company filha recem-criada e 1 da user_company mãe.

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

{
    "$uri": "/api/user_company/7",
    "api_name": null,
    "created_at": {
        "$date": 1463940701000
    },
    "enabled_modules": "[]",
    "is_archived": false,
    "logo_url": null,
    "name": "Nova empresa",
    "trib_monitor_config": "{}",
    "user_company": {
        "$ref": "/api/user_company/1"
    },
    "users": []
}

Request Headers:
	Authorization – token da API. Ver Autenticação. Content-Type – `application/json`
Response Headers:
	Content-Type – `application/json`
Status Codes:	200 OK – Recurso criado

Recuperar o token de API do usuário administrador de uma empresa¶

GET https://op.digesto.com.br/api/user_company/(int: id)/admin_api_token¶

Exemplo de chamada:

Retorna o token de API do administrador da empresa identificada via ID na URL. Caso não exista um usuário administrador definido para essa empresa, um novo aleatório será criado.

Esta chamada deve ser feita autenticado como um usuário da empresa-mãe.

GET https://op.digesto.com.br/api/user_company/1/admin_api_token HTTP/1.1

Exemplo de resposta:

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

{
    "api_key": "21357b41-f22d-4a09-8bc1-71042936b624",
    "status": "OK"
}

Request Headers:
	Authorization – token da API. Ver Autenticação.
Response Headers:
	Content-Type – `application/json`
Parameters:	id – identificador numérico do recurso user_company

Modificar o endereço webhook de uma empresa¶

O endereço de retornos via webhook para uma empresa-filha criada pode ser configurado via API também. Para configurar via interface web, basta ir em Configurações - Integração via API.

Na chamada abaixo, use o token de API do usuário admin da empresa filha.

POST https://op.digesto.com.br/api/user_company/current_webhook_config¶

Exemplo de chamada:

POST https://op.digesto.com.br/api/user_company/current_webhook_config?api_key=<chave> HTTP/1.1
Content-Type: application/json

{
    "url": "https://meu-endereco.com/webhook"
}

Exemplo de resposta:

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

{
    "is_global_active": true,
    "url": "https://meu-endereco.com/webhook"
}

Request Headers:
	Authorization – token da API. Ver Autenticação.
Response Headers:
	Content-Type – `application/json`

Criando manualmente nova empresa¶

Todas as operações abaixo estão disponíveis via API (seções anteriores), para execução autônoma pelo software cliente e o servidor de API Digesto.

No entanto, para facilitar a criação de novas empresas (user_company ) e cadastrar as partes monitoradas (monitored_person ) associadas a esta empresa, disponibilizamos uma interface web. Veja os passos:

Fazer login na empresa mãe;
No menu à esquerda, ir em Configuracoes > Empresas;
Criar a nova empresa (filha), escolhendo um novo e-mail para o campo E-mail de um novo administrador. Este e-mail deve ser diferente de qualquer outro usuário do sistema.;
Fazer logout da conta na empresa mãe;
Fazer login na empresa filha com o e-mail do novo administrador;
Cadastrar as partes monitoradas em massa (menu à esquerda Partes > Monitorar em massa) ou cadastrar um a um em Partes > Partes monitoradas > Nova;
Obter o token de integração na API, indo em Configurações > Integração via API. O token fica na caixa Autenticação (enviar dados para API). Este token é usado para autenticar o software cliente que faz as chamadas para a API. Usando este token, a API saberá que se trata de dados e alertas da nova empresa-filha.

Estatísticas de uso¶

As chamadas a seguir permitem consultar o volume de uso das operações da API.

Totais de entidades¶

GET https://op.digesto.com.br/api/user_company/entities_totals¶

Retorna o total de entidades cadastradas e associadas à user_company passada, bem como total de chamadas feitas no mês.

Exemplo de chamada:

GET https://op.digesto.com.br/api/user_company/entities_totals HTTP/1.1

Exemplo de resposta:

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

{
  "total_active_monitored_person": 12,
  "total_active_monitored_url": 0,
  "total_active_proc": 120,
  "total_active_user": 14,
  "total_active_user_company": 14
}

Request Headers:
	Authorization – token da API. Ver Autenticação.
Response Headers:
	Content-Type – `application/json`
Query Parameters:
	user_company_id (int) – identificador numérico do recurso user_company (empresa) na API only_trial (boolean) – retornar apenas uso das pessoas e processos monitorados em trial. Default = false. include_children (boolean) – incluir no somatório os totais das user_company filhas. Default = true.

Totais de consultas¶

GET https://op.digesto.com.br/api/user_company/queries_totals¶

Retorna o total de consultas realizadas pela user_company passada, no mês indicado.

Request Headers:
	Authorization – token da API. Ver Autenticação.
Response Headers:
	Content-Type – `application/json`
Query Parameters:
	user_company_id (int) – identificador numérico do recurso user_company (empresa) na API year (int) – ano desejado. Default = ano atual. month (int) – mês desejado Default = mês atual. only_trial (boolean) – retornar apenas uso das pessoas e processos monitorados em trial. Default = false. include_children (boolean) – incluir no somatório os totais das user_company filhas. Default = true.
Response JSON Object:
	total_tribproc_view (int) – total de consultas à base judicial sem anexos bem sucedidas total_tribproc_view_anexo (int) – total de consultas à base judicial com anexos bem sucedidas

Exemplo de chamada:

GET https://op.digesto.com.br/api/user_company/queries_totals HTTP/1.1

Exemplo de resposta:

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

{
  "total_tribproc_view": 14,
  "total_tribproc_view_anexo": 14,
  "total_report_cnjs": 3,
  "total_report_partes": 3,
  "total_search_proc_partes": 3,
}

Eventos de monitoramento¶

POST https://op.digesto.com.br/api/user_company/usage_events¶

Retorna o total de eventos de monitoramento gerados para a user_company passada.

Exemplo de chamada:

POST https://op.digesto.com.br/api/user_company/usage_events HTTP/1.1

Exemplo de resposta:

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

{
  "total_MOV" :1,
  "total_PUBL_PROC" :2,
  "total_PUBL_STR" :3,
  "total_DISTRIB" :4,
  "total_CIP_PROCON" :14,
  "total_CADASTRO" :5,
  "total_PROTOCOLO_PROC" :6,
  "total_DIFF_PROC" :7,
}

Request Headers:
	Authorization – token da API. Ver Autenticação.
Response Headers:
	Content-Type – `application/json`
Query Parameters:
	user_company_id (int) – identificador numérico do recurso user_company (empresa) na API year (int) – ano desejado. Default = ano atual. month (int) – mês desejado Default = mês atual. only_trial (boolean) – retornar apenas uso das pessoas e processos monitorados em trial. Default = false. include_children (boolean) – incluir no somatório os totais das user_company filhas. Default = true.

Reportando erros via API¶

Erros podem ser reportados direto à equipe Digesto de forma automatizada.

Valores válidos para o campo error_type:

distrib.parte: distribuição de processo incorreta (parte não relevante)
distrib.ausente: processo citado, cuja distribuição não foi informada pela API
distrib.dados: distribuição de processo incorreta (dados de cadastro do processo incorretos)

Um identificador único em formato string é retornado nesta chamada. O mesmo pode ser usado futuramente para referenciar o report feito.

POST https://op.digesto.com.br/api/user_company/report_error_comment¶

O erro é na distribuição de um processo, cujo CNJ é informado no campo object.

Exemplo de chamada:

POST https://op.digesto.com.br/api/user_company/report_error_comment HTTP/1.1
Content-Type: application/json

{
  "error_type": "distrib.parte",
  "object": "111221.23213.2016-02223-2312",
  "error_comment": "essa parte nao nos interessa, tem que ser processos da CBD sem LTDA no final"
}

Exemplo de resposta:

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

"2e0f63a4-ba83-4855-a590-06c8476bb675"

Query Parameters:
	error_type (string) – Tipo do erro reportado. Valores válidos: `distrib.parte`, `distrib.ausente`, `distrib.dados`. object (string) – número CNJ do processo. error_comment (string) – comentário sobre o erro reportado.
Status Codes:	200 OK – Report recebido com sucesso.

Criando novos usuários em empresas filhas

Empresas na API¶

Detalhes de uma empresa (/api/user_company)¶

trib_monitor_config¶

url_monitor_config¶

protocolo_config¶

users¶

Criando novas empresas (user_company)¶

Recuperar o token de API do usuário administrador de uma empresa¶

Modificar o endereço webhook de uma empresa¶

Criando manualmente nova empresa¶

Estatísticas de uso¶

Totais de entidades¶

Totais de consultas¶

Eventos de monitoramento¶

Reportando erros via API¶

Detalhes de uma empresa (`/api/user_company`)¶