SERVIÇO CONTRATO. Especificação das operações de Serviço MANUAL DO USUÁRIO CONSULTAR CONTRATO. Projeto: Plataforma de Integração.

Transcrição

1 SERVIÇO Especificação das operações de Serviço /07/ de 14

2 Data 01/07/ Versão Descrição Histórico de Revisões - Elaboração Inicial da especificação da operação de serviço ListarContrato 08/07/ Revisão do documento. - Revisão da obrigatoriedade sobre as datas inicial e final, as mesmas deverão ser 14/07/ obrigatórias. - Substituída as siglas do agente no Response pelo código do agente. 01/08/ Versão Disponibilizada /07/ de 14

3 Índice 1. INTRODUÇÃO LOCALIZAÇÃO ESTRUTURA GERAL DOS ELEMENTOS MESSAGEHEADER SECURITY PARÂMETROS DE ENTRADA LISTAR PERIODO PARÂMETROS DE SAÍDA LISTARRESPONSE PENDÊNCIA VIGÊNCIA OPERAÇÕES DISPONÍVEIS LISTAR PARÂMETROS DE ENTRADA PARÂMETROS DE SAÍDA EXEMPLO DE XML DE ENTRADA EXEMPLO DE XML DE SAÍDA DESCRIÇÃO DE ALERTA E EXCEÇÕES ABREVIAÇÕES, SIGLAS E ACRÔNIMOS REFERÊNCIAS /07/ de 14

4 1. Introdução Plataforma de Integração A Plataforma de integração consiste numa solução que visa integrar aplicações para acesso à informações no ambiente da CCEE Câmara de Comercialização de Energia Elétrica. Por meio dele, qualquer sistema, escrito em qualquer linguagem, pode conectar-se para consulta ou inserção de dados. A CCEE estabeleceu por meio dessa plataforma um padrão de interconexão entre sistemas heterogêneos, que usa a web e a XML como linguagem para troca de informações (dados e metadados). Esse serviço destina-se num canal oferecido para interação entre os sistemas dos Agentes e a CCEE. Módulo de Contratos (Consulta de Contratos) Este serviço possibilitará a consulta de contratos através de uma chamada Web Service. Consideramos um tipo de operações: Listar contratos Este método será responsável por retornar uma lista de contratos para informações específicas. A operação estará disponível através da mesma operação (Soap Action), cabendo a determinados elementos dentro da mensagem de entrada definir qual consulta está sendo feita. 2. Localização A tabela abaixo lista os ambientes e as correspondentes URLs da Web Service: Tipo de URL Produção Piloto Endereço A consulta do documento WSDL pode ser feita via navegador Web, ou através de softwares e bibliotecas especializadas em Web Service. 3. Estrutura geral dos elementos As seções a seguir descrevem cada parâmetro de entrada e saída, com seus respectivos tipos de dados e descrição. As operações contendo os campos do tipo Enumeration são consideradas case sensitive, e em alguns casos com valores restritos. Os valores deverão ser exatamente iguais aos valores definidos no documento WSDL e seus arquivos XSD importados /07/ de 14

5 3.1. messageheader Tanto a mensagem de entrada (request) quanto a mensagem de resposta (response) deverão conter a seção messageheader como parte do Header, sendo constituída dos seguintes elementos: Nome Descrição Tipo Condição codigoperfilagente Código do perfil agente utilizados nos sistemas da CCEE transactionid Contém o identificador da mensagem. Será preenchido pela CCEE e incluído na mensagem de resposta listacodigoperfilagente Para uso interno da CCEE. Não precisa ser enviado no request e não será enviado na resposta Estrutura Uso interno 3.2. Security A mensagem de entrada deverá conter, dentro do Header, a estrutura Security listada abaixo, que deverá conter o usuário e senha utilizados para autenticação. Esta estrutura é uma especialização do UsernameToken da especificação WS-Security, contendo apenas os seguintes elementos: Nome Descrição Tipo Condição Username Código do perfil agente utilizados nos sistemas da CCEE Password Senha fornecida para utilização da plataforma 3.3. Parâmetros de entrada Os seguintes elementos fazem parte da mensagem de entrada da operação listarcontrato: listarcontrato /07/ de 14

6 Tipo de contrato Identificador dos tipos de contrato existentes no ambiente sistêmico da CCEE. CCEAL CCEAR_D CCEAR_Q LEILAO_AJUSTE PROINFA Vendedor Comprador Identifica o código externo do agente associado Identifica o código externo do agente associado ITAIPU CCEN CCGF Alfanumér ico 3538 Alfanumér ico periodo inicio fim Início do período a ser consultado. Não considera horário de verão Fim do período a ser consultado. Não considera horário de verão DateTime DateTime 01/01/ /01/ Parâmetros de saída Os seguintes elementos fazem parte da mensagem de resposta da operação listarcontrato: listarcontratoresponse contrato Lista com os contratos encontradas durante a consulta. Lista Min: 0 Max: Unbounded contrato /07/ de 14

7 codigoorigem Identifica o código do contrato proveniente do sistema externo proprietário do Agente Exemplo: 1150 codigo Identificador único que corresponde a um número sequencial de um determinado contrato Alfanumérico Exemplo: tipo Identificador dos tipos de contrato existentes no ambiente sistêmico da CCEE. CCEAL CCEAR_D CCEAR_Q LEILAO_AJUSTE PROINFA ITAIPU CCEN subtipo Identifica os tipos de energia para o Contrato CCEEAL. Exemplo: Energia Firme, Geração de energia Flexível por percentual de consumo ou percentual de geração. CCGF FIRME FLEXIVEL_CONSUM O FLEXIVEL_GERACA O Periodo Estrutura tipoenergia ENERGIA_CONVEN Informa os tipos de geração CIONAL possíveis. ENERGIA_INCENTI VADA_ESPECIAL ENERGIA_CONVEN CIONAL_ESPECIAL ENERGIA_INCENTI VADA_COGERACA O_QUALIFICADA /07/ de 14

8 subtipocontrato Informa os sub-tipos de geração possíveis. LEN Leilão de Energia Nova; LER Leilão de Energia de Reserva; LAJ Leilão de Ajuste; LFA Leilão de fontes alternativas; LEE Leilão de Energia existente. LEN LER LAJ LFA LEE pendência pendenciacontrato Identifica o tipo de pendência associada ao contrato, independente do tipo de contrato. ADITIVO_NAO_VALID ADO ANUAL_NAO_VALIDA DO CANCELAMENTO_NA O_VALIDADO FINALIZACAO_NAO_ VALIDADA MENSAL_NAO_VALID ADA MENSAL_NULO MONTANTE_MEDIO_ NAO_VALIDADO RASCUNHO REGISTRO_NAO_VALI DADO SAZONIZACAO_NAO_ VALIDADA TIPO_MODULACAO_ NAO_INFORMADA TIPO_MODULACAO_ NAO_VALIDADA vigência periodo/inicio DD/MM/YYYY HH24:MI:SS Data 01/01/2 013 Obrigatóri o /07/ de 14

9 periodo/fim DD/MM/YYYY HH24:MI:SS Data 31/12/2 013 Obrigatóri o comprador Identifica o código externo do Agente associado à CCEE. Alfanum érico 3538 vendedor Identifica o código externo do Agente associado à CCEE. Alfanum érico 1150 quantidadecontratu alanual Informa o valor total (Anual) sobre o montante de energia contratado em medida de unidade (MWh). Alfanum érico , Operações disponíveis O serviço ListarContratoBSv1 possuirá apenas uma operação, listarcontrato. A seção Estrutura dos Elementos irá descrever os tipos de valores para cada elemento. Aqui apenas quais elementos devem ser enviados para cada tipo de consulta serão listados. IMPORTANTE: Em todas as consultas o valor do codigoperfilagente (no messageheader) deverá ser enviado Listar Contrato Este método será responsável por retornar uma lista de contratos Parâmetros de entrada Os parâmetros abaixo devem ser enviados para a consulta de contratos: codigoperfilagente Código do perfil agente utilizados nos sistemas da CCEE Alfanumér ico Username Usuário fornecido para utilização da plataforma Alfanumér ico Password Senha fornecida para utilização da plataforma Alfanumér ico vendedor Identifica o código externo do agente associado Alfanumér ico /07/ de 14

10 comprador Identifica o código externo do agente associado Alfanumér ico 1150 periodo/inicio Inicio do horário da vigência. Formato DD/MM/YYYY HH24:MI:SS Data 01/01/2013 periodo/fim Fim do horário da vigência. Formato DD/MM/YYYY HH24:MI:SS Data 31/01/ Parâmetros de saída Os parâmetros abaixo serão retornados na consulta de dados faltantes: codigoorigem Identifica o código do contrato proveniente do sistema externo proprietário do Agente codigo Identificador único que corresponde a um número sequencial de um determinado contrato tipo subtipo periodo/inicio periodo/fim Identificador dos tipos de contrato existentes no ambiente sistêmico da CCEE. Identifica os tipos de energia para o Contrato CCEEAL. Exemplo: Energia Firme, Geração de energia Flexível por percentual de consumo ou percentual de geração. Inicio do horário da vigência. Formato DD/MM/YYYY HH24:MI:SS Fim do horário da vigência. Formato DD/MM/YYYY HH24:MI:SS 1150 Alfanumérico Data Data CCEAL, CCEAR- D, CCEAR-Q, CCEN, CCGF, Itaipu, Leilão de Ajuste, PROINFA FIRME FLEXIVEL_CONS UMO FLEXIVEL_GERA CAO 01/01/ /01/2013 Obrigatóri o Obrigatóri o /07/ de 14

11 tipoenergia Informa os tipos de geração possíveis. ENERGIA_CONV ENCIONAL ENERGIA_INCE NTIVADA_ESPE CIAL ENERGIA_CONV ENCIONAL_ESP ECIAL subtipocontrato LEN Leilão de Energia Nova; LER Leilão de Energia de Reserva; ENERGIA_INCE NTIVADA_COGE RACAO_QUALIF ICADA LEN LER LAJ Leilão de Ajuste; LAJ LFA Leilão de fontes alternativas; LEE Leilão de Energia existente. LFA LEE pendencia Identifica o tipo de pendência associada ao contrato, independente do tipo de contrato. Alfanumérico Exemplo de XML de entrada <soapenv:envelope xmlns:soapenv=" xmlns:v1=" xmlns:oas=" wss-wssecurity-secext-1.0.xsd" xmlns:v11=" xmlns:v12=" <soapenv:header> <v1:messageheader> <v1:codigoperfilagente>66</v1:codigoperfilagente> <v1:transactionid></v1:transactionid> <v1:listacodigoperfilagente> <v1:codigoperfilagente></v1:codigoperfilagente> </v1:listacodigoperfilagente> </v1:messageheader> <oas:security> <oas:usernametoken> <oas:username>ag10</oas:username> <oas:password>senha123</oas:password> </oas:usernametoken> </oas:security> /07/ de 14

12 </soapenv:header> <soapenv:body> <v11:listarcontrato> <v11:contrato> <v12:tipo>ccear_d</v12:tipo> <v12:vigencias> <v12:vigencia> <v12:periodo> <v12:inicio> t</v12:inicio> <v12:fim> t</v12:fim> </v12:periodo> <v12:comprador> <v12:código>99</v12:codigo> </v12:comprador> <v12:vendedor> <v12:codigo>9999</v12:codigo> </v12:vendedor> </v12:vigencia> </v12:vigencias> </v11:contrato> </v11:listarcontrato> </soapenv:body> </soapenv:envelope> Exemplo de XML de saída <soapenv:envelope xmlns:soapenv=" xmlns:bm=" xmlns:bo=" xmlns:fm=" xmlns:mh=" <soapenv:header> <mh:messageheader> <mh:codigoperfilagente>66</mh:codigoperfilagente> <mh:transactionid>eb62b a-4be5-ae81-35aff13c7dea</mh:transactionid> </mh:messageheader> </soapenv:header> <soapenv:body> <bm:listarcontratoresponse> <bm:contrato> <bm:contrato> <bo:codigoorigem>5388</bo:codigoorigem> <bo:codigo>27658</bo:codigo> <bo:tipo>ccear_d</bo:tipo> <bo:subtipo>lfa</bo:subtipo> <bo:tipoenergia>incentivada_especial</bo:tipoenergia> <bo:vigencias> <bo:vigencia> <bo:periodo> <bo:inicio> t-02:00</bo:inicio> <bo:fim> t23:00:00-02:00</bo:fim> </bo:periodo> <bo:comprador> <bo:codigo>66</bo:codigo> /07/ de 14

13 </bo:comprador> <bo:vendedor> <bo:codigo>4012</bo:codigo> </bo:vendedor> <bo:quantidadecontratadaanual> <bo:valor> </bo:valor> </bo:quantidadecontratadaanual> </bo:vigencia> </bo:vigencias> </bm:contrato> </bm:contrato> </bm:listarcontratoresponse> </soapenv:body> </soapenv:envelope> 5. Descrição de alerta e Exceções A seguir, descreveremos as descrições das mensagens de alerta e exceção, classificando-as em categorias de código de erro: Código de Erro Mensagens de ambiente Um erro aconteceu O Serviço está indisponível Acesso Negado XML Inválido. Código Mensagens de Alerta referentes ao negócio A Operação <nome da operação> foi processada com sucesso! Dados não encontrados A Data inicial não pode ser maior que a Data final. 6. Abreviações, siglas e acrônimos Sigla XML SOAP WSDL XSD CCEE HTTPS Definição extensible Markup Language Simple Object Access Protocol Web Service Description Language Xml Schema Definition Câmara de Comercialização de Energia Elétrica HyperText Transfer Protocol Secure /07/ de 14

14 SSL URL WSS Secure Sockets Layer Uniform Resource Locator Web Service Security 7. Referências Sigla Apache Axis 1.x, 2.x HTTP SOAP 1.1 WSDL 1.1 Definição Web Services Security XML 1.1 XML Schema 1.1 XML Schema Definition SSL HTTPS /07/ de 14