Autores

Sobre este Documento

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.

Breve descrição do projeto

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.

Características Técnicas

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.

Autenticação na API

    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.

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

SEARCHGATEIN

    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.

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/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::

SEARCHGATEOUT

    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.