O objetivo deste documento é explicar como se dará o acesso a API desenvolvida pela eProfessionalTI, para fazer a integração dos movimentos de entrada e saída dos contêineres dos terminais de vazios para o exportador, com o Portal da Maersk.
Durante as definições do projeto do Portal da Maersk, verificou-se a necessidade de os Terminais informarem alguns dados no momento da entrada e saída do contêiner. Hoje esses dados estão sendo informados manualmente direto no portal, a proposta deste projeto é a disponibilização de uma API, para que os parceiros da Maersk tenham a possibilidade de informar esses dados de forma automática e em tempo real.
A Web API que será disponibilizada, foi desenvolvida na plataforma Microsoft, usando a linguagem C# .Net, a camada de persistência utiliza o Entity Framework. Para este projeto foi adotada a arquitetura MVC (Model View Control). A mensageria prevista na integração, usará como padrão o formato JSON, formato este já consagrado e em uso em diversas corporações.
I - Requisição
O meio de autenticação escolhido para a API é o Digest, onde primeiramente o usuário obtém um Token, mediante ao
envio de Usuário e Senha. Caso o usuário e senha fornecidos sejam válidos, a API
retornará um Token, que deverá
ser usado no próximo acesso a API, para o método desejado. Vale lembrar que o Token terá validade de um minuto,
após este período um novo Token deverá ser obtido para a permissão de acesso.
Para obter o Token, o programa cliente deve acessar as seguintes URLs:
• Teste - "http://brmaerskdev.eprofessionalti.com/api/portal/integra/getaccess"
• Produção - "https://www.portalagendamentos.com.br/api/portal/integra/getaccess"
Os métodos em questão, são posts e o seguinte JSON deve ser enviado:
JSON para a requisição:
Onde:
DEPOT recebe o CNPJ em questão
LOGIN recebe o login fornecido pela Eprofessional
SENHA recebe a senha fornecida pela Eprofessional
II - Retorno
O retorno terá o atributo SUCCESS para retornar Verdadeiro ou Falso, caso o retorno seja Falso, o
Atributo
ERROR, trará a descrição do erro, caso contrário ele será vazio. Um terceiro atributo é o
OBJECT, este atributo
é um dado complexo, ou seja, um objeto que contém outros dois atributos o CNONCE que é uma string
que será usada
na autenticação Digest e o outro é o TOKEN, que será a chave usada para o acesso ao método desejado
da API.
I - Requisição
Caso a autenticação de usuário e senha tenha sido feita com sucesso, o sistema cliente deverá usar os dados
retornados (CNONCE e TOKEN) para acessar o método Gatein. O Acesso a este método dever
ser feito através das
seguintes URLs:
• Teste - "http://brmaerskdev.eprofessionalti.com/api/portal/integra/savegatein"
• Produção - "https://www.portalagendamentos.com.br/api/portal/integra/savegatein"
Aos métodos em questão, são posts e o seguinte JSON deve ser enviado:
JSON para a requisição:
Onde:
DEPOT - Recebe o CNPJ do Depot
TOKEN – Recebe o Token obtido no método getaccess
CNONCE – Recebe o CNONCE obtido no método getaccess
TICKETS – Um objeto que recebe os dados principais do agendamento feito no Portal da Maersk, ele
pode conter
um ou vários agendamentos conforme abaixo:
• DATA – Data do agendamento;
• MOTORISTA - Nome do Motorista;
• PLACA – Placa do caminhão;
• CPF – CPF do motorista.
II - Retorno
O retorno será um objeto (Dictionary(String,Object)), caso seja um retorno “TRUE”, o Atributo
NONCE, voltará
preenchido com uma string que deverá ser usada para consultar os status do agendamentos enviados.
Retorno do método savegatein:
I - Requisição
Caso a autenticação de usuário e senha tenha sido feita com sucesso, o sistema cliente deverá usar os dados
retornados (CNONCE e TOKEN) para acessar o método searchgatein.
O método savegatein é um método assíncrono, portanto, o retorno do processamento da requisição deve
ser obtido
em outro método usando o NONCE retornado, o método retornará um status para cada agendamento
enviado. Sendo
assim, para obter o status de cada agendamento/Ticket, o sistema cliente deverá acessar método searchgatein, que
estará disponível nos seguintes links:
• Teste - "http://brmaerskdev.eprofessionalti.com/api/portal/integra/searchgatein"
• Produção - “https://www.portalagendamentos.com.br/api/portal/integra/searchgatein”
Os métodos em questão, são posts e o seguinte JSON deve ser enviado:
JSON para a requisição do método searchgatein:
Onde:
DEPOT - Recebe o CNPJ do Depot
TOKEN – Recebe o Token obtido no método getaccess
CNONCE – Recebe o CNONCE obtido no método getaccess
NONCE – Recebe o NONCE obtido no método savegatein.
II - Retorno
O retorno será uma lista (Dictionary(String,Object)) e poderá conter um ou mais objetos com dados do agendamento
(Ticket). Notar que cada Ticket tem seu próprio status; Caso o atributo ERROR, seja diferente de
vazio, um erro
ocorreu para o agendamento em questão.
I - Requisição
Caso a autenticação de usuário e senha tenha sido feita com sucesso, o sistema cliente deverá usar os dados
retornados (CNONCE e TOKEN) para acessar o método Gateout. O Acesso a este método
dever ser feito através das
seguintes URLs:
• Teste - "http://brmaerskdev.eprofessionalti.com/api/portal/integra/savegateout"
• Produção - "https://www.portalagendamentos.com.br/api/portal/integra/savegateout"
Aos métodos em questão, são posts e o seguinte JSON deve ser enviado:
JSON para a requisição:
Onde:
DEPOT - Recebe o CNPJ do Depot
TOKEN – Recebe o Token obtido no método getaccess
TICKETS – Um objeto que recebe os dados principais do agendamento feito no Portal da Maersk, ele
pode conter
um ou vários agendamentos conforme abaixo:
• DATA – Data do agendamento;
• MOTORISTA - Nome do Motorista;
• PLACA – Placa do caminhão;
• CPF – CPF do motorista.
• CONTAINER – Número do container
• ISO – Uso do container
• TARA – Tara do container
• MGW – MGW do container
• LACRE – Lacre de exportação
II - Retorno
O retorno será um objeto (Dictionary(String,Object)), caso seja um retorno “TRUE”, o Atributo
NONCE, voltará
preenchido com uma string que deverá ser usada para consultar os status do agendamentos enviados.
Retorno do método savegateout::
I - Requisição
Caso a autenticação de usuário e senha tenha sido feita com sucesso, o sistema cliente deverá usar os dados
retornados (CNONCE e TOKEN) para acessar o método Gateout. O Acesso a este método
dever ser feito através das
seguintes URLs:
• Teste - "http://brmaerskdev.eprofessionalti.com/api/portal/integra/searchgateout "
• Produção - "https://www.portalagendamentos.com.br/api/portal/integra/searchgateout "
Aos métodos em questão, são posts e o seguinte JSON deve ser enviado:
JSON para a requisição:
Onde:
DEPOT - Recebe o CNPJ do Depot
TOKEN – Recebe o Token obtido no método getaccess
CNONCE – Recebe o CNONCE obtido no método getaccess
NONCE – Recebe o NONCE obtido no método savegateout.
II - Retorno
O retorno será uma lista (Dictionary(String,Object)) e poderá conter um ou mais objetos com dados do agendamento
(Ticket). Notar que cada Ticket tem seu próprio status; Caso o atributo ERROR, seja diferente de
vazio, um erro
ocorreu para o agendamento em questão.