Manual de Integração do CIGA Diário - DOM/ES

Atenção

Agora Decretos (categoria 2) também recebem Metadados!
- Vide: Metadados para Leis e Decretos (categorias 1 e 2).
- Enfatizamos a importância da implementação desse envio pois futuramente esses dados passarão a ser exigidos obrigatoriamente também para o Cadastro de Atos para Publicação e não mais apenas para Item de Acervo Público, como é hoje.


Apresentação

Este é um documento técnico que apresenta o formato de troca de dados com o fim de permitir a aplicativos de terceiros o cadastro automatizado de documentos para publicação no Diário Oficial dos Municípios do Espírito Santo.

O cadastro automatizado de publicações pode ser útil para diversos sistemas de terceiros que armazenam ou geram documentos os quais precisam ser submetidos ao processo de publicidade oficial, como ferramentas de contabilidade e gestão de pessoal, ferramentas de controle legislativo, tributário e muitas outras.

Informações Gerais

A integração prevista neste documento é feita através de um web-service no modelo REST. Toda comunicação cliente/servidor ocorrerá via protocolo HTTPS (TLS 1.2), porta 443/TCP. São aceitos os métodos GET e POST, sendo seu uso discriminado neste documento. A autenticação utilizada é do tipo HTTP Basic Auth. O retorno é feito combinando os códigos HTTP padrão (200, 400, 401, 403 e 404) somados a um objeto JSON.

A autenticação do tipo HTTP Basic Auth, com usuário e senha, deve ser feita em todas as requisições. O controle de acesso é o mesmo empregado para o login de cadastro de atos no site. Todas as publicações são cadastradas no nome do usuário autenticado e o acompanhamento delas é de inteira responsabilidade do usuário que a cadastrou.

Todas as regras de publicação vigentes são aplicadas também aos documentos cadastrados por API.

Endereço base para as requisições: https://diariomunicipal.sc.gov.br/site/


Mensagens


Detalhes de Implementação dos Métodos

Modo de Autentificação

Para todos os métodos abaixo, Usuário e Senha devem ser informados via HTTP Basic Auth.

Codificação dos Textos dos Parâmetros

Todo argumento textual deverá ser passado com a codificação UTF-8.

<parâmetro>*

Todo parâmetro seguido de asterisco (*) é obrigatório.


Verifica Usuário e Senha e Retorna Parâmetros Iniciais

URL: ?r=remote/verify

Método: GET

Parâmetro na URL: Nenhum

Obs.: As categorias retornadas têm os códigos estáveis, logo não é necessário verificá-los sempre.

Retorno: Objeto JSON com o seguinte schema:


{
    "type":"object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "required":true,
    "properties":{
        "ok":{
            "type":"boolean",
            "description": "Indica se foi possível realizar a operação",
            "required":true
        },
            "proxima_edicao":{
            "type":"string",
            "description": "Data no formato dd/mm/yyyy da próxima edição",
            "required":true
        },
        "categorias":{
            "type":"array",
            "description": "Listagem das categorias válidas para cadastro",
            "required":true
        },
    }
}
            

Exemplo usando cURL:


 curl -u usuario:senha "https://diariomunicipal.sc.gov.br/site/?r=remote/verify"
            

Novos Cadastros

Existem duas formas de cadastrar documentos no DOM. A primeira e mais comum, que visa à publicação do ato em uma Edição de uma determinada data deve ser feita pelo "Cadastrar Ato para Publicação". Já na modalidade de item de acervo público, em que o ato não é publicado em uma determinada Edição do DOM, mas fica armazenado e disponível mediante o mesmo sistema de pesquisa. Esse cadastro de documentos, normalmente antigos, é feito pelo "Cadastrar Item de Acervo Público".

Ainda sobre esses dois tipos de cadastros disponíveis, ressaltam-se 4 pontos importantes em comum:

  1. Caso a categoria do Ato seja "1" ou "2", "Metadados para Leis e Decretos (categorias 1 e 2)" podem ser enviados. Aqui enfatizamos que hoje os Metadados são obrigatóros para Itens de Acervo Público, mas que também, futuramente, serão obrigatórios para Cadastros de Novas Publicações;
  2. Caso a categoria do Ato seja "6, 7 ou 28", "Metadados para Contratos, Convênios e Empenhos (categorias 6, 7 e 28)" podem ser enviados. Aqui enfatizamos que hoje os Metadados são obrigatóros para Itens de Acervo Público, mas que também, futuramente, serão obrigatórios para Cadastros de Novas Publicações;
  3. Basicamente a única diferença dos parâmetros desses cadastros é que para "Cadastrar Ato Para Publicação" deve-se fornecer o parâmetro "Ato[data_publicacao]". Por outro lado, para "Cadastrar Item de Acervo Público", fornece-se o parâmetro "Ato[data_documento]".
  4. Ambos os cadastros retormam Resposta Padrão para Novos Cadastros.

Metadados para Leis e Decretos (categorias 1 e 2) Novo

Esses metadados servem tanto para o Cadastro de Novas Publicações como para Itens de Acervo Público, sendo momentaneamente obrigatórios para este último.

Futuramente esses parâmetros se tornão obrigatórios para ambos os cadastros!

Parâmetro Tipo Tamanho/Formato Descrição
Metadados[cod_subcategoria]** Numérico 1

Campo disponível e obrigatório apenas para Leis (categoria 1).
Valores possíveis:

  • 1 => Lei Orgânica
  • 2 => Emenda à Lei Orgânica
  • 3 => Lei Complementar
  • 4 => Lei Ordinária
  • 5 => Lei Delegada
  • 6 => Medida Provisória
  • 7 => Decreto Legislativo
  • 9 => Anexos
Metadados[status_lei] Numérico 1

Valores possíveis:

  • 1 => Vigente (Não consta revogação expressa)
  • 2 => Revogada
Obs.: Este atributo está em fase de homologação.
Metadados[numero]* Numérico 11 Número do ato normativo, sem pontos.
Metadados[ano]* Numérico 4 YYYY - Ano do ato normativo.
Metadados[epigrafe] Textual 100 Epígrafe do ato normativo, conforme art. 4º da LEI COMPLEMENTAR Nº 95, DE 26 DE FEVEREIRO DE 1998.
Metadados[ementa] Textual 500 Ementa do ato normativo, conforme art. 5º da LEI COMPLEMENTAR Nº 95, DE 26 DE FEVEREIRO DE 1998.
Metadados[tag_assunto] Textual [...,]

Valores possíveis (array com um ou mais):

  • Assistência Social
  • Criança e Adolescente
  • Educação
  • Meio Ambiente
  • Orçamento
  • Saúde
  • Segurança
  • Servidor Público
  • Transporte
  • Tributos
  • Trânsito
  • Turismo
  • Urbanística
  • Outros
Metadados[projeto_lei] Textual 100 Referência ao PL de origem.
Metadados[data_sancao]* Data dd/mm/yyyy Data da sanção.
Metadados[data_inicio_vigencia] Data dd/mm/yyyy Data do início da vigência.
Metadados[data_revogacao] Data dd/mm/yyyy Data da Revogação Total do ato se existir.
Obs.: Essa informação faz sentido no cadastro de Itens de Acervo Público de atos já revogados.
** Campo disponível e obrigatório apenas para Leis (categoria 1).

Metadados para Contratos, Convênios e Empenhos (categorias 6, 7 e 28) Novo

Esses metadados servem tanto para o Cadastro de Novas Publicações como para Itens de Acervo Público, sendo momentaneamente obrigatórios para este último.

Futuramente esses parâmetros se tornão obrigatórios para ambos os cadastros!

Parâmetro Tipo Tamanho/Formato Descrição
Metadados[legislacao]** Numérico 1

Valores possíveis:

  • 0 => Sem Legislação específica (padrão)
  • 1 => COVID-19 - LEI Nº 13.979, DE 6 DE FEVEREIRO DE 2020
Valor a ser passado caso seja um ato com fulcro em tal lei.
Metadados[numero]* Textual 255 O nome/número do Contrato, Convênio ou Empenho.
Metadados[numero_processo]** Textual 255 O nome/número do respectivo processo de contratação ou aquisição.
Metadados[url_processo] Textual 2000 URL pública do respectivo processo de contratação ou aquisição.
Metadados[objeto] Textual 65535 Objeto contratual.
Metadados[cnpj_cpf]* Textual 14 ou 11 Número da inscrição na RFB do contratado (CNPJ ou CPF). Aceita-se os documentos apenas com os números e também com o caracteres de separação. Ex: 09427503000112 ou 09.427.503/0001-12.
Metadados[nome_razao_social] Textual 255 Nome/Razão Social do contratado.
Metadados[data_assinatura] Data dd/mm/yyyy Data de Assinatura.
Metadados[data_vigencia_inicio]** Data dd/mm/yyyy Início da vigência (prazo contratual).
Metadados[data_vigencia_fim]** Data dd/mm/yyyy Fim da vigência (prazo contratual).
Metadados[valor]* Decimal ...0.000,00 Valor.
** Campos obrigatórios caso Metadados[legislacao] = 1, conforme Art. 4º, § 2º, da Lei n.º 13.979, de 6 de fevereiro de 2020.

Resposta Padrão para Novos Cadastros

Ambas as operações de inserção (cadastros) retornam a mesma estrutura.

Retorno: Objeto JSON com o seguinte schema:


{
    "type":"object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "required":true,
    "properties":{
        "ok":{
            "type":"boolean",
            "description": "Indica se foi possível realizar a operação",
            "required":true
        },
        "codigo":{
            "type":"integer",
            "description": "Código do Ato Cadastrado",
            "required":true
        },
    }
}
                

Cadastrar Ato para Publicação

URL: ?r=remote/create

Método: POST

Parâmetro na URL: Nenhum

Parâmetros para serem enviados como itens de formulário no corpo do POST:

Parâmetro Tipo Tamanho/Formato Descrição
Ato[titulo]* Textual 200 Título da publicação
Ato[cod_categoria]* Numérico 1 Código da categoria, conforme remote/verify.
Ato[data_publicacao]* Data dd/mm/yyyy Data de publicação (no mínimo a mesma retornada pelo remote/verify).
Ato[anexo]* Documento Arquivo para publicação, no formato DOC, DOCX ou RTF (PDF para tabelas da contabilidade), respeitando as normas de publicação no DOM.
Ato[url_origem_api] Textual 2000 URL pública para o ato (publicação) no sistema de origem desse cadastro

Exemplo usando cURL:


curl -u usuario:senha \
    -F "Ato[titulo]=Resolução 123" \
    -F "Ato[cod_categoria]=3" \
    -F "Ato[data_publicacao]=03/12/2020" \
    -F "Ato[anexo][email protected]" \
    -F "Ato[url_origem_api]=http://www.dominio.terceiro.com/.../..." \
    "https://diariomunicipal.sc.gov.br/site/?r=remote/create"
                

Exemplo de Lei com Metadados usando cURL::


curl -u usuario:senha \
    -F "Ato[titulo]=Lei Complementar N.º 1.234, de 01 de Dezembro de 2019" \
    -F "Ato[cod_categoria]=1" \
    -F "Ato[data_publicacao]=03/12/2019" \
    -F "Ato[anexo][email protected]_complementar_1234_2019.docx" \
    -F "Ato[url_origem_api]=www.dominio.terceiro.com/.../..." \
        -F "Metadados[cod_subcategoria]=3" \
        -F "Metadados[status_lei]=2" \
        -F "Metadados[numero]=1234" \
        -F "Metadados[ano]=2019" \
        -F "Metadados[epigrafe]=Lei Complementar N.º 1.234, de 01 de Dezembro de 2019" \
        -F "Metadados[ementa]=Dispõe sobre ...." \
        -F "Metadados[tag_assunto][]=Saúde,Educação" \
        -F "Metadados[projeto_lei]=Projeto de Lei N.º 670/2018" \
        -F "Metadados[data_sancao]=01/12/2019" \
        -F "Metadados[data_inicio_vigencia]=03/12/2019" \
    "https://diariomunicipal.sc.gov.br/site/?r=remote/create"
                

Cadastrar Item de Acervo Público Novo

URL: ?r=remote/acervoCreate

Método: POST

Parâmetro na URL: Nenhum

Parâmetros para serem enviados como itens de formulário no corpo do POST:

Parâmetro Tipo Tamanho/Formato Descrição
Ato[titulo]* Textual 200 Título da publicação
Ato[cod_categoria]* Numérico 1 Código da categoria, conforme remote/verify.
Ato[data_documento]* Data dd/mm/yyyy Data do Documento, ou seja, a data de sua criação e/ou de entrada em vigor/publicação.
Ato[anexo]* Documento Arquivo para publicação, no formato DOC, DOCX ou RTF (PDF para tabelas da contabilidade), respeitando as normas de publicação no DOM.
Ato[url_origem_api] Textual 2000 URL pública para o ato (publicação) no sistema de origem desse cadastro

Exemplo usando cURL:


curl -u usuario:senha \
    -F "Ato[titulo]=Lei Complementar N.º 1.234, de 01 de Dezembro de 1999" \
    -F "Ato[cod_categoria]=1" \
    -F "Ato[data_documento]=01/12/1999" \
    -F "Ato[anexo][email protected]_complementar_1234_1999.docx" \
    -F "Ato[url_origem_api]=www.dominio.terceiro.com/.../..." \
        -F "Metadados[cod_subcategoria]=3" \
        -F "Metadados[status_lei]=2" \
        -F "Metadados[numero]=1234" \
        -F "Metadados[ano]=1999" \
        -F "Metadados[epigrafe]=Lei Complementar N.º 1.234, de 01 de Dezembro de 1999" \
        -F "Metadados[ementa]=Dispõe sobre ...." \
        -F "Metadados[tag_assunto][]=Saúde,Educação" \
        -F "Metadados[projeto_lei]=Projeto de Lei N.º 670/1998" \
        -F "Metadados[data_sancao]=01/12/1999" \
        -F "Metadados[data_inicio_vigencia]=03/12/1999" \
        -F "Metadados[data_revogacao]=11/11/2019" \
    "https://diariomunicipal.sc.gov.br/site/?r=remote/acervoCreate"
                

Excluir Publicação Programada

URL: ?r=remote/delete

Método: POST

Parâmetro na URL: id = código do documento cadastrado

Retorno: Objeto JSON com o seguinte schema:


{
    "type":"object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "required":true,
    "properties":{
        "ok":{
            "type":"boolean",
            "description": "Indica se foi possível realizar a operação",
            "required":true
        },
        "codigo":{
            "type":"integer",
            "description": "Código do Ato",
            "required":true
        },
    }
}
            

Exemplo usando cURL:


curl -X POST -u usuario:senha "https://diariomunicipal.sc.gov.br/site/?r=remote/delete&id=<código_ato>"
            

Verificar Status da Publicação

URL: ?r=remote/status

Método: GET

Parâmetro na URL: codigo = código do documento cadastrado

Retorno: Objeto JSON com o seguinte schema:


{
    "type":"object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "required":true,
    "properties":{
        "ok":{
            "type":"boolean",
            "description": "Indica se foi possível realizar a operação",
            "required":true
        },
        "status":{
            "type":"string",
            "description": "Novo|Em diagramação|Publicado|Cancelado|Publicado Equivocadamente|Acervo Público|Acervo Removido",
            "required":true
        },
        "data_publicacao":{
            "type":"string",
            "description":  "Data no formato dd/mm/yyyy",
            "required":true
        },
        "edicao":{
            "type":"integer",
            "description": "N.º da Edição em que foi publicado",
            "required":true
        },
        "pagina":{
            "type":"integer",
            "description": "Pág. do ato na Edição",
            "required":true
        },
        "url":{
            "type":"string",
            "description": "URL para a publicação oficial (PDF)",
            "required":true
        },
    }
}
            

Exemplo usando cURL:


curl -u usuario:senha "https://diariomunicipal.sc.gov.br/site/?r=remote/status&codigo=<código_ato>"
            

Listar Publicações

URL: ?r=remote/list

Método: GET

Parâmetro na URL: page (número da página atual), count (quantidade de itens por página)

Retorno: Objeto JSON com o seguinte schema:


{
    "type":"object",
    "$schema": "http://json-schema.org/draft-03/schema",
    "required":true,
    "properties":{
        "ok":{
            "type":"boolean",
            "description": "Indicativo de validade semântica da requisição.",
            "required":true
        },
        "result":{
            "type":"array",
            "description": "Lista das publicações",
            "required":false,
            "items":{
                "type":"object",
                "required":false,
                "properties":{
                    "codigo":{
                        "type":"integer",
                        "required":true
                    },
                    "titulo":{
                        "type":"string",
                        "required":true
                    },
                    "categoria":{
                        "type":"string",
                        "required":true
                    },
                    "data_publicacao":{
                        "type":"string",
                        "description": "Formato dd/mm/yyyy",
                        "required":true
                    },
                    "data_cadastro":{
                        "type":"string",
                        "description": "Formato dd/mm/yyyy h:i:s",
                        "required":true
                    },
                    "url_origem_api":{
                        "type":"string",
                        "required":true
                    },
                    "status":{
                        "type":"string",
                        "required":true
                    }
                }
            }
        }
    }
}
            

Exemplo usando cURL:


curl -u usuario:senha "https://diariomunicipal.sc.gov.br/site/?r=remote/list&page=1&count=50"