Coordenação Geral de Tecnologia da Informação - CGTI. Corporativo-Sistema de serviços corporativos Manual de Utilização dos Serviços

Transcrição

1 Corporativo-Sistema de serviços corporativos Manual de Utilização dos Serviços

2 Corporativo-Sistema de serviços corporativos Versão 1.3 Especificação dos Serviços Data: 03/12/2013 Histórico de Revisão Data Versão Descrição Autor 17/10/ Versão inicial. Gustavo Antunes 04/03/ Inclusão de serviços Gustavo Antunes 20/08/ Descrição dos serviços de inclusão de pessoa física e inclusão de pessoa jurídica Gustavo Antunes 03/12/ Adequação ao template 1.2 Thiago Pires MAPA/SE/SPOA/CGTI. Página 2 de 21 Versão do Template: 1.2

3 ÍNDICE 1. INFORMAÇÕES GERAIS GESTORES Gestor de Negócio Gestor Técnico ENDEREÇO DO WADL REQUISITOS E ORIENTAÇÕES PARA ACESSO Solicitação de acesso a serviço restrito REQUISIÇÃO AO SERVIÇO RESPOSTA DO SERVIÇO INFORMAÇÕES DETALHADAS CONSULTAR UNIDADES FEDERATIVAS Objetivo Pré-condições Endereço do Serviço s de Entrada Resposta CONSULTAR MUNICÍPIOS Objetivo Pré-condições Endereço do Serviço s de Entrada Resposta CONSULTAR UNIDADE MEDIDA Objetivo Pré-condições Endereço do Serviço s de Entrada Resposta CONSULTAR PAÍSES Objetivo Pré-condições Endereço do Serviço s de Entrada Resposta CONSULTAR PESSOA FÍSICA POR CPF Objetivo Pré-condições Endereço do Serviço s de Entrada Resposta CONSULTAR PESSOA JURÍDICA POR CNPJ Objetivo Pré-condições Endereço do Serviço s de Entrada MAPA/SE/SPOA/CGTI. Página 3 de 21

4 2.6.5 Resposta CONSULTAR PESSOA ESTRANGEIRA Objetivo Pré-condições Endereço do Serviço s de Entrada Resposta INCLUIR PESSOA ESTRANGEIRA Objetivo Pré-condições Endereço do Serviço s de Entrada Arquivo de Exemplo Resposta INCLUIR PESSOA FÍSICA Objetivo Pré-condições Endereço do Serviço s de Entrada Arquivo de Exemplo Resposta INCLUIR PESSOA JURÍDICA Objetivo Pré-condições Endereço do Serviço s de Entrada Arquivo de Exemplo Resposta LEGENDA QUADRO RESUMO MAPA/SE/SPOA/CGTI. Página 4 de 21

5 1. INFORMAÇÕES GERAIS Este documento tem como objetivo descrever os detalhes para utilização dos serviços fornecidos pelo sistema CORPORATIVO desenvolvidos no estilo de arquitetura de software REST. 1.1 GESTORES Gestor de Negócio Nome: Thiago Almeida Siqueira Telefone: (61) Área/Setor: Coordenação Geral de Tecnologia da Informação CGTI Gestor Técnico Nome: Thiago Almeida Siqueira Telefone: (61) Área/Setor: Coordenação Geral de Tecnologia da Informação CGTI 1.2 ENDEREÇO DO WADL Homologação: Produção: REQUISITOS E ORIENTAÇÕES PARA ACESSO O acesso aos serviços descritos neste documento é feito exclusivamente por programas autorizados sobre o protocolo de comunicação HTTP. O requisito para acesso aos serviços restritos é possuir usuário cadastrado no MAPA Ministério da Agricultura, Pecuária e Abastecimento com perfil associado ao(s) serviço(s) de interesse. Nas chamadas aos serviços, o cliente deve informar o usuário e senha (formato md5) fornecidos pelo MAPA. Estes dados devem ser informados a cada requisição HTTP no cabeçalho, utilizando-se o atributo Authorization (Exemplo: Authorization: Basic MDAwMDAwMDAwMDAxOTE6MTExMTExMTE=). Caso o serviço não seja restrito, não há necessidade de informar esses dados (usuário e senha) Solicitação de acesso a serviço restrito O acesso a um serviço restrito faz-se mediante a utilização de um usuário e senha e devem ser solicitados ao MAPA. Para tanto, deve-se entrar em contato com o gestor de negócio do sistema. 1.4 REQUISIÇÃO AO SERVIÇO Os parâmetros de entrada do serviço podem ser informados dentre 3 (três) tipos: MAPA/SE/SPOA/CGTI. Página 5 de 21

6 Path; ou s; ou Arquivo (XML ou JSON) Para envio de arquivo, deverá ser informado no cabeçalho da requisição o tipo de arquivo através do atributo Content-Type (Exemplo: Content-Type: application/xml). Exemplos dos arquivos estão descritos no detalhamento do serviço. 1.5 RESPOSTA DO SERVIÇO O formato da resposta do serviço pode ser escolhida dentre os dois tipos abaixo, sendo que a opção desejada deve ser enviada no cabeçalho da requisição pelo atributo Accept (Exemplo: Accept: application/json). XML: extensible Markup Language JSON: JavaScript Object Notation MAPA/SE/SPOA/CGTI. Página 6 de 21

7 2 INFORMAÇÕES DETALHADAS Abaixo são listados os detalhes dos serviços disponibilizados pelo sistema CORPORATIVO: 2.1 CONSULTAR UNIDADES FEDERATIVAS Objetivo Tem como finalidade realizar a consulta das unidades federativas do Brasil. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Não se aplica Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU Lista de registros chave Sigla da UF 2 AL N/A valor Nome da UF 50 AL N/A MAPA/SE/SPOA/CGTI. Página 7 de 21

8 2.2 CONSULTAR MUNICÍPIOS Objetivo Tem como finalidade realizar a consulta dos municípios de determinada Unidade Fedetativa do Brasil. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Descrição do Conteúdo Obrigatório Máscara sguf Sigla da Unidade Federativa Sim N/A 2 AL Vide Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/hora de execução - DT N/A status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU Lista de registros chave Código do município 10 NU N/A valor Descrição município 50 AN N/A MAPA/SE/SPOA/CGTI. Página 8 de 21

9 2.3 CONSULTAR UNIDADE MEDIDA Objetivo Tem como finalidade realizar a consulta das unidades de medida utilizadas pelos sistemas MAPA. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Não se aplica Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU Lista de registros identificador Identificador da unidade de medida 5 NU N/A sigla Sigla da unidade de medida 5 AN N/A descricao Descrição da unidade de medida 30 AN N/A MAPA/SE/SPOA/CGTI. Página 9 de 21

10 2.4 CONSULTAR PAÍSES Objetivo Tem como finalidade realizar a consulta dos países utilizados nos projetos MAPA. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Não se aplica Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora da execução - DT N/A status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU Lista de registros chave Sigla do país 3 AL N/A valor país 50 AN N/A MAPA/SE/SPOA/CGTI. Página 10 de 21

11 2.5 CONSULTAR PESSOA FÍSICA POR CPF Objetivo Tem como finalidade realizar a consulta de informações de pessoa física a partir do CPF. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Descrição do Conteúdo Obrigatório Máscara CPF CPF da pessoa a ser consultada Sim N/A 11 AL N/A Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A identificador Identificador da pessoa 10 NU N/A nome Nome da pessoa 100 AN N/A cpf CPF da pessoa 11 AN N/A rg RG da pessoa 15 AN N/A dataexpedicaorg Data de expedição do RG N/A DT N/A orgaoexpedidorrg Órgão expedidor do RG 2 AL N/A M Masculino sexo Sexo 1 AL F Feminino N Não informado datanascimento Data de nascimento N/A DT N/A nomepai pai 100 AN N/A nomemae Nome da mãe 100 AN N/A dataobito Data de óbito N/A DT N/A MAPA/SE/SPOA/CGTI. Página 11 de 21

12 status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU 2.6 CONSULTAR PESSOA JURÍDICA POR CNPJ Objetivo Tem como finalidade realizar a consulta de informações de pessoa jurídica a partir do CNPJ. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Descrição do Conteúdo Obrigatório Máscara CNPJ CNPJ da pessoa a ser consultada Sim N/A 14 AL N/A Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A identificador nmrazaosocial Identificador da pessoa jurídica Razão Social da pessoa jurídica 10 NU N/A 100 AN N/A MAPA/SE/SPOA/CGTI. Página 12 de 21

13 nmfantasia Nome fantasia da pessoa jurídica 100 AN N/A nrcnpj CNPJ da pessoa jurídica 14 AN N/A nrinscricaoestadu al Número da inscrição estadual 20 AN N/A status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU 2.7 CONSULTAR PESSOA ESTRANGEIRA Objetivo Tem como finalidade realizar a consulta de informações de pessoa a partir do País de origem. O sistema deve validar as informações e retornar os registros que atentem a consulta Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: ento=&nome= s de Entrada Descrição do Conteúdo Obrigatório Máscara sgpais Sigla do país de origem da pessoa Sim N/A 3 AL Vide 2.4 nrdocumento Número do documento da pessoa física Não N/A N/A AN N/A MAPA/SE/SPOA/CGTI. Página 13 de 21

14 Descrição do Conteúdo Obrigatório Máscara nome Nome da pessoa Sim N/A Ao menos 3 caracteres AN N/A Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A status Status da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU Lista de Registros identificador nome Identificador da pessoa Nome da pessoa 10 NU N/A 300 AN N/A nrdocumento Número do documento 10 AN N/A tipodocumento documento 100 AN N/A telefone endereco sgpais da pessoa Telefone da pessoa Endereço da pessoa País de origem da pessoa 100 AN N/A 20 AN N/A 200 AN N/A 3 AL N/A MAPA/SE/SPOA/CGTI. Página 14 de 21

15 2.8 INCLUIR PESSOA ESTRANGEIRA Objetivo Tem como finalidade incluir informações de pessoa. O sistema deve validar as informações e retornar o identificador do registro incluído Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Descrição do Conteúdo Obrigatório Máscara nome nrdocumento tipodocumento telefone endereco sgpais Nome da pessoa Número do documento Tipo do documento da pessoa Telefone da pessoa Endereço da pessoa País de origem da pessoa Sim N/A 300 AN N/A Não N/A 10 AN N/A Não N/A 100 AN N/A Não N/A 100 AN N/A Não N/A 20 AN N/A Não N/A 200 AN N/A Sim N/A 3 AN Vide Arquivo de Exemplo <pessoaestrangeira> <nome></nome> <nrdocumento></nrdocumento> <tipodocumento></tipodocumento> < ></ > MAPA/SE/SPOA/CGTI. Página 15 de 21

16 <telefone></telefone> <endereco></endereco> <sgpais></sgpais> </pessoaestrangeira> Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A identificador Identificador gerado para o registro 10 NU N/A status Situação da operação 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU 2.9 INCLUIR PESSOA FÍSICA Objetivo Tem como finalidade incluir informações de pessoa física. O sistema deve validar as informações e retornar o identificador do registro incluído Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Descrição do Conteúdo Obrigatório Máscara nome Nome da pessoa física Sim N/A 100 AN N/A MAPA/SE/SPOA/CGTI. Página 16 de 21

17 Descrição do Conteúdo Obrigatório Máscara cpf rg dataexpedicaorg orgaoexpedidorrg Número do CPF Número do RG Data de expedição do RG Órgão expedidor do RG Sim N/A 11 AN N/A Não N/A 15 AN N/A Não N/A - DT N/A Não N/A 20 AN N/A sexo Sexo Não N/A 1 AL M Masculino F - Feminino datanascimento Data de nascimento Não N/A - DT N/A nomepai pai Não N/A 100 AN N/A nomemae Nome da mãe Não N/A 100 AN N/A dataobito Data de óbito Não N/A - DT N/A Arquivo de Exemplo <pessoafisica> <nome></nome> <cpf></cpf> <rg></rg> <dataexpedicaorg></dataexpedicaorg> <orgaoexpedidorrg></orgaoexpedidorrg> <sexo></sexo> <datanascimento></datanascimento> <nomepai></nomepai> <nomemae></nomemae> <dataobito></dataobito> </pessoafisica> MAPA/SE/SPOA/CGTI. Página 17 de 21

18 2.9.6 Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A identificador Identificador gerado para o registro 10 NU N/A status Código do tipo de solo 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU 2.10 INCLUIR PESSOA JURÍDICA Objetivo Tem como finalidade incluir informações de pessoa jurídica. O sistema deve validar as informações e retornar o identificador do registro incluído Pré-condições Usuário deve ter sido previamente cadastrado; Usuário deve autenticar-se com sucesso Endereço do Serviço URI: s de Entrada Descrição do Conteúdo Obrigatório Máscara nmrazaosocial nmfantasia nrcnpj Nome da pessoa jurídica Nome Fantasia Número do CNPJ Sim N/A 100 AN N/A Sim N/A 100 AN N/A Sim N/A 14 AN N/A MAPA/SE/SPOA/CGTI. Página 18 de 21

19 Descrição do Conteúdo Obrigatório Máscara nrinscricaoestadual Número da Inscrição estaudla Não N/A 20 AN N/A Arquivo de Exemplo <pessoajuridica> <nmrazaosocial></nmrazaosocial> <nmfantasia></nmfantasia> <nrcnpj></nrcnpj> <nrinscricaoestadual></nrinscricaoestadual> </pessoajuridica> Resposta Id Identificador da operação 10 NU N/A datahoraexecuca o Data/Hora de execução - DT N/A identificador Identificador gerado para o registro 10 NU N/A status Código do tipo de solo 1 NU Lista de mensagens codigo Código da mensagem 10 NU N/A descricao Texto da mensagem 4000 NU N/A A Alerta tipo Tipo da mensagem 1 NU MAPA/SE/SPOA/CGTI. Página 19 de 21

20 3 LEGENDA AL = Alfa AN = Alfanumérico AS = Alfanumérico sem caracteres especiais NU = Numérico DT = Data e/ou Hora CH = Char BI = bit BL = boleano N/A = Não se Aplica. MAPA/SE/SPOA/CGTI. Página 20 de 21

21 Corporativo-Sistema de serviços corporativos Versão QUADRO RESUMO Serviço Contexto Envio URI Método Acesso Restrito? Consultar unidade federativa corporativo Path /servicos/uf GET Sim Consultar municípios corporativo Path /servicos/município/{sguf} GET Sim Consultar unidade medida corporativo Path /servicos/unidademedida GET Sim Consultar países corporativo Path /servicos/pais GET Sim Consultar pessoa física por CPF Consultar pessoa jurídica por CNPJ corporativo Path /servicos/pessoafisica/{cpf} GET Sim corporativo Path /servicos/pessoajuridica/{cnpj} GET Sim Consultar pessoa corporativo Path /servicos/pessoa/{sgpais}?nrdocumento =&nome= Incluir pessoa corporativo Arquivo /servicos/pessoa POST Sim Incluir pessoa física corporativo Arquivo /servicos/pessoafisica POST Sim Incluir pessoa jurídica corporativo Arquivo /servicos/pessoajuridica POST Sim GET Sim MAPA/SE/SPOA/CGTI. Página 21 de 21