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:

  1. Criar nova Empresa-Filha, usando o token de um administrador da Empresa-mãe (chamada abaixo)
  2. 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
  3. Com o token do administrador da Empresa-Filha, criar as partes monitoradas Registrando partes para monitoramento, processos etc.
  4. 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.

_images/hierarquia_user_company.png

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:
 
Response Headers:
 
Status Codes:

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:
 
Response Headers:
 
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:
 
Response Headers:
 

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:

  1. Fazer login na empresa mãe;
  2. No menu à esquerda, ir em Configuracoes > Empresas;
  3. 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.;
  4. Fazer logout da conta na empresa mãe;
  5. Fazer login na empresa filha com o e-mail do novo administrador;
  6. Cadastrar as partes monitoradas em massa (menu à esquerda Partes > Monitorar em massa) ou cadastrar um a um em Partes > Partes monitoradas > Nova;
  7. 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:
 
Response Headers:
 
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:
 
Response Headers:
 
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:
 
Response Headers:
 
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