Introdução

A Skymarine API é organizada em torno de REST. Nossa API têm previsibilidade e é fácil de usar, com recursos autodescritivos e URLs amigáveis. Nossos endpoints aceitam JSON como formato de corpo das requisições e retornam JSON como respostas.


Caso queira testar de maneira mais prática a API, você pode acessar o Swagger da API, onde poderá entender o fluxo de requisições e respostas da API em um ambiente mais amigável. Caso queira testar localmente, uma ótima opção é a plataforma do Postman.

API URL

Base URL

Tutorial Rápido

Para uma implementação rápida e uma visão geral, você pode seguir para o Quickstart.

Preferência de Código

Para os exemplos e snippets de código apresentados na documentação, você poderá escolher entre as seguintes opções:

Quickstart

Pré Requisitos

Para poder começar a utilizar a API, você precisa ter uma conta de e-mail cadastrada com os acessos de API habilitados. Se você já tiver uma conta, será necessário fazer login para a obtenção dos tokens necessários para a utilização da API.


Além das suas informações de login, será necessário ter em mãos a chave de API para poder realizar qualquer requisição, fornecida por nós no momento de cadastro na API.


Caso não tenha alguma dessas informações, vá até Contato e fale conosco através de um dos meios especificados.

Passo a passo

Com os pré-requisitos atendidos, você pode seguir o passo a passo a seguir para a configuração de chamadas na API:


  1. Configure a chave de API fornecida (API KEY) que será necessária para todas as requisições a serem feitas:

    Você deverá ter um cabeçalho (headers) com o nome de x-api-key e o valor será a chave de API fornecida.


  2. Configure o token de acesso (access_token) do seu login (não necessário para endpoints Auth):

    Você deverá ter um cabeçalho (headers) com o nome de Authorization e o valor será a token de acesso (access_token) obtido no login.


  3. Configure o corpo da requisição, em formato JSON, de acordo com a rota buscada:

    Para mais informações sobre as rotas disponíveis, consulte a seção de Autenticação ou a seção de endpoints de Tracking.


  4. Configure o tipo da requisição:

    O tipo da requisição deverá ser configurado de acordo com a rota, mas no geral, as requisições são do tipo POST.


  5. Resposta da requisição:

    Caso bem sucedida, a resposta da requisição será um JSON com as informações solicitadas, para mais informações sobre as respostas, consulte a seção de endpoints respectiva a rota buscada.

Autenticação

A API possui dois métodos de autenticação: Chave da API e Tokens para garantir que tanto a segurança quanto a integridade dos dados sejam mantida e as informações sejam acessadas apenas por usuários autorizados.

Chave da API

O primeiro passo para utilizar a API é obter uma chave de API através de uma solicitação de acesso, que pode ser feita junto ao gerente da sua conta ou entrando em Contato conosco.


Quando solicitado o acesso voce receberá duas informações: a chave da API e as suas informações de cadastrado (o qual será necessário atualizar a senha). Guarde essas informações com cuidado visto que elas garantem o acesso aos seus dados.


Para utilizar a chave da API, você deve incluí-la em todos as solicitações de API que você fizer. Voce deverá adicionar um cabeçalho (header) chamado X-API-KEY e com o valor da chave fornecida.

Nome do Header

Valor

X-Api-Key

Chave da API fornecida

Tokens

Para utilizar e obter os tokens, você deverá já ter feito o cadastro mencionado na etapa anterior de Chave da API. Caso já o tenha feito, você pode obter os tokens fazendo o login pelo navegador ou chamando a API diretamente.


Nessa seção o foco será em explicar e como utilizar os tokens. Para mais informações sobre como obter os tokens, confira os Endpoints de Autenticação.


A API trabalha com dois tipos de tokens:


  1. Token de Acesso (access_token):

    Utilizado nas chamadas onde o usuário precisa estar autenticado. Você irá utilizá-lo junto de um cabeçalho (header) Authorization com o valor Bearer seguido do token. Esse token possui uma duração de 1 dia.

    Nome do Header

    Valor

    Authorization

    Bearer + (token de acesso)


  2. Token de Atualização (refresh_token):

    Utilizado para renovar sessões de autenticação e obter novos tokens de acesso. Esse token expirará em 30 dias.

    Esse token será utilizado junto do Endpoint de /auth/refresh como parte do corpo da requisição. Para mais detalhes vá até a seção de Endpoints de Autenticação.

Endpoints

post

- /auth


Utilizado para fazer o login de usuário e receber os tokens necessários para as demais operações da API. Necessita de headers e body. Retornará um JSON como resposta.

Headers

Nome

Tipo

Descrição

Content-Type

application/json

Tipo de conteúdo do corpo da requisição

X-Api-Key

string

Valor da chave da API recebida para acessar a API

Body

Nome

Tipo

Descrição

email

string

Email de cadastro

password

string

Senha de acesso

Response

Nome

Tipo

Descrição

AccessToken

string

Token de acesso aos seus dados

RefreshToken

string

Token de atualização do token de acesso

ExpiresIn

integer

Tempo em segundos para expiração do token de acesso

Example - POST - /auth

javascript

1const axios = require('axios'); 2 3const getTokens = async () => { 4 const url = "https://api.skymarine.com.br/auth"; 5 const headers = { 6 "Content-Type": "application/json", 7 "X-Api-Key": "<API_KEY>", 8 }; 9 const body = { 10 email: "<YOUR_EMAIL>", 11 password: "<YOUR_PASSWORD>", 12 }; 13 14 try { 15 const response = await axios.post(url, body, { headers }); 16 console.log(response.data); 17 } catch (error) { 18 if (error.response) { 19 console.error( 20 "Error " + 21 error.response.status + 22 " when making a request to " + 23 url + 24 " : " + 25 error.response.data, 26 error 27 ); 28 } else { 29 console.error("Error when making a request:", error.message); 30 } 31 } 32}; 33 34getTokens().then(() => { 35 console.log("API call completed."); 36}); 37

Resposta

JSON

{ "AccessToken": <ACCESS_TOKEN>, "RefreshToken": <REFRESH_TOKEN>, "ExpiresIn": 86400 }

post

- /auth/refresh-token


Utilizado para fazer o login de usuário e receber os tokens necessários para as demais operações da API. Necessita de headers e body. Retornará um JSON como resposta.

Headers

Nome

Tipo

Descrição

Content-Type

application/json

Tipo de conteúdo do corpo da requisição

X-Api-Key

string

Valor da chave da API recebida para acessar a API

Body

Nome

Tipo

Descrição

refreshToken

string

Token de Atualização recebido no momento do login

Response

Nome

Tipo

Descrição

AccessToken

string

Token de acesso aos seus dados

ExpiresIn

integer

Tempo em segundos para expiração do token de acesso

Example - POST - /auth/refresh-token

javascript

1const axios = require('axios'); 2 3const renewToken = async () => { 4 const url = "https://api.skymarine.com.br/auth/refresh-token"; 5 const headers = { 6 "Content-Type": "application/json", 7 "X-Api-Key": "<API_KEY>", 8 }; 9 const body = { 10 refreshToken: "<YOUR_REFRESH_TOKEN>", 11 }; 12 13 try { 14 const response = await axios.post(url, body, { headers }); 15 console.log(response.data); 16 } catch (error) { 17 if (error.response) { 18 console.error( 19 "Error " + 20 error.response.status + 21 " when making a request to " + 22 url + 23 " : " + 24 error.response.data, 25 error 26 ); 27 } else { 28 console.error("Error when making a request:", error.message); 29 } 30 } 31}; 32 33renewToken().then(() => { 34 console.log("API call completed."); 35}); 36

Resposta

JSON

{ "AccessToken": <ACCESS_TOKEN>, "ExpiresIn": 86400 }

Tracking API

Bem-vindo à seção da API de Tracking, uma ferramenta poderosa e eficiente projetada para fornecer informações sobre o status dos seus embarques. Nossa API permite que você acompanhe o seu embarque ao longo das etapas do processo de transporte, garantindo transparência e confiabilidade no gerenciamento de suas remessas.


Com a nossa API, você tem acesso ao:


  1. Rastreamento: Obtenha informações atualizadas sobre a localização e o status dos seus embarques.

  2. Histórico de Embarques: Acesse o histórico completo dos seus embarques com a Skymarine.

  3. Integração Fácil: Nossa API é projetada para ser facilmente integrada com seus sistemas existentes, permitindo uma implementação rápida e sem complicações.


Nosso objetivo é fornecer uma solução robusta e escalável que atenda às necessidades de monitoramento de embarques dos nossos clientes, melhorando a visibilidade e a eficiência operacional em toda a operação.

Endpoints

post

- /shipments


Utilizado para buscar os seus embarques, oferencendo alguns filtros como opção de busca. Retornará respostas paginadas no fomarto de JSON. Os embarques (shipments) sempre estarão em ordem descrecente de data de criação, do mais recente para o mais antigo.

Headers

Nome

Tipo

Descrição

Content-Type

application/json

Tipo de conteúdo do corpo da requisição

X-Api-Key

string

Valor da chave da API recebida para acessar a API

Authorization

string

Bearer + Valor do Token de Acesso recebido, para autenticação de usuário

Body

Nome

Tipo

Descrição

shipments

list of strings

IDs dos embarques a serem buscados, caso nenhum seja passado, retornará todos os embarques que se encaixar no filtro

with_descendants

boolean

Filtro para incluir os embarques de organizações filhas do cliente buscado

per_page

integer

Tamanho das páginas retornadas, padrão é 20 e máximo é 100

page

integer

Número da página buscada

Response

Nome

Tipo

Descrição

shipments

list of objects

Retorna os embarques que se encaixam nos filtros passados na requisição. (Veja Modelos par amais informações sobre a estrutura de cada objeto)

total_shipments

integer

Total de embarques encontrados na busca (diferente do total de embarques retornados)

per_page

integer

Tamanho real da página retornada

total_pages

integer

Número da página buscada

Example - POST - /shipments

javascript

1const axios = require('axios'); 2 3const getShipments = async () => { 4 const url = "https://api.skymarine.com.br/shipments"; 5 const headers = { 6 "Content-Type": "application/json", 7 "X-Api-Key": "<API_KEY>", 8 "Authorization": "Bearer <YOUR_ACCESS_TOKEN>", 9 }; 10 const body = { 11 shipments: [], 12 with_descendants: true, 13 per_page: 30, 14 page: 1 15 }; 16 17 try { 18 const response = await axios.post(url, body, { headers }); 19 console.log(response.data); 20 } catch (error) { 21 if (error.response) { 22 console.error( 23 "Error " + 24 error.response.status + 25 " when making a request to " + 26 url + 27 " : " + 28 error.response.data, 29 error 30 ); 31 } else { 32 console.error("Error when making a request:", error.message); 33 } 34 } 35}; 36 37getShipments().then(() => { 38 console.log("API call completed."); 39}); 40

Resposta

JSON

{ "shipments": [ { "id": "S00IS0000", "hbl": "AAAAA000000", "client_reference": null, "client": "Coporation Example A LTDA", "controlling_customer": null, "consignee": "Coporation Example A LTDA", "consignor": "Example Industry LIMITED", "origin": { "id": "CNSHA", "name": "Shanghai", "country": "China", "continent": "Asia", "sub_region": "Eastern Asia" }, "destination": { "id": "BRSSZ", "name": "Santos", "country": "Brazil", "continent": "Americas", "sub_region": "South America" }, "carrier": "Carrier Example A", "type": "SEA", "vessel_name": "Vessel Name", "voyage_number": "000S", "estimated_departure": "2024-01-01T22:00:00", "actual_departure": "2024-01-01T22:54:00", "estimated_arrival": "2024-03-12T20:00:00", "actual_arrival": null, "legs": [ { "order": 1, "mode": "FCL", "load_port": { "id": "CNSHA", "name": "Shanghai", "country": "China", "continent": "Asia", "sub_region": "Eastern Asia" }, "discharge_port": { "id": "MAPTM", "name": "Tanger Med", "country": "Morocco", "continent": "Africa", "sub_region": "Northern Africa" }, "estimated_departure": "2024-01-01T22:00:00", "actual_departure": "2024-01-01T22:54:00", "estimated_arrival": "2024-02-01T11:00:00", "actual_arrival": null, "carrier": "Carrier Example A", "aircraft_type": null, "vessel_imo": " ", "vessel_name": "Vessel name", "voyage_number": "000W" }, { "order": 2, "mode": "FCL", "load_port": { "id": "MAPTM", "name": "Tanger Med", "country": "Morocco", "continent": "Africa", "sub_region": "Northern Africa" }, "discharge_port": { "id": "BRSSZ", "name": "Santos", "country": "Brazil", "continent": "Americas", "sub_region": "South America" }, "estimated_departure": "2024-03-03T13:00:00", "actual_departure": null, "estimated_arrival": "2024-03-12T20:00:00", "actual_arrival": null, "carrier": "Carrier Example A", "aircraft_type": null, "vessel_imo": "0000000", "vessel_name": "Vessel Name", "voyage_number": "000S" } ], "container_count": 1, "container_mode": "FCL", "containers": [ { "number": "AAAA0000000", "type": "40HC ", "category": null, "iso_code": null, "mode": null, "demurrage_status": "Sem Demurrage", "pickup_gate_out": null, "return_gate_in": null, "demurrage_days": null } ], "goods_description": "Product description", "goods_value": 10.000.000,00, "goods_currency": BRL - Brazilian Real, "incoterm": "FOB", "quantity": 237, "quantity_unit": "PKG", "weight": 9.600, "weight_unit": "KG", "volume": 200, "volume_unit": "M3", "chargeable": 1, "free_time_destination": 7, "free_time_origin": null, "inspecao": null, "data_inspecao": null, "est_cargo_ready": null, "cargo_ready": null, "sales_staff": { "name": "Staff A", "email": "staff.a@skymarine.com.br" }, "operation_staff": { "name": "Staff B", "email": "staff.b@skymarine.com.br" } }, {...}, {...}, {...}, ... ], "total_shipments": 232, "per_page": 30, "total_pages": 8 }

Modelos

Abaixo estão os modelos que compõem o objeto de retorno dos embarques afim de esclarecer a estrutura e o que representa cada informação retornada.

Localização

Nome

Tipo

Exemplo

Descrição

id

string

BRSSZ

UNLOCODE da localização

name

string

Santos

Nome da cidade da localização

country

string

Brazil

País da localização

continent

string

Americas

Continente da localização

sub_region

string

South America

Sub-região da localização

Pessoas

Nome

Tipo

Exemplo

Descrição

name

string

Nome Sobrenome

Nome da pessoa

email

string

nome.sobrenome@skymarine.com.br

Email de contato

Containers

Nome

Tipo

Exemplo

Descrição

number

string

AAAA0000000

número do container

type

string

40HC

Tipo de container

category

string

DRY - Dry Storage

Categoria do container

iso_code

string

42R0

Código ISO do container

mode

string

FCL - Full Container Load

Modo de contratação

demurrage_status

string

Sem Demurrage

Status de demurrage do container

pickup_gate_out

date

2023-09-22T00:00:00

Data que o container foi retirado

return_gate_in

date

2023-09-22T00:00:00

Data de retorno do container

demurrage_days

integer

5

Dias contabilizados de demurrage

Pernas do Embarque

Nome

Tipo

Exemplo

Descrição

order

integer

1

Ordem da perna no trajeto completo

mode

string

SEA

Tipo do transporte

load_port

relationship

Tabela Localização

Porto de carregamento/origem

discharge_port

relationship

Tabela Localização

Porto de descarregamento/destino

estimated_departure

date

2023-09-22T00:00:00

Data estimada de saída

actual_departure

date

2023-09-22T00:00:00

Data real de saída

estimated_arrival

date

2023-09-22T00:00:00

Data estimada de chegada

actual_arrival

date

2023-09-22T00:00:00

Data real de chegada

carrier

string

MSK

Código do carrier da perna

aircraft_type

string

AAAA

Tipo da aeronave (único para tipo AIR)

vessel_imo

string

XXX0000

Código da embarcação que realizou o trajeto

vessel_name

string

Ship Name

Nome da embarcação

voyage_number

string

444W

Código da viagem da embarcação

Embarque

Nome

Tipo

Exemplo

Descrição

id

string

S00IS0000

ID identificadora da Skymarine

hbl

string

AAAAA000000

Código House Bill of Landing do embarque

client_reference

string

XXXXXX

Referência do cliente vinculada no nosso sistema

client

string

Industry A - South LTDA

Client do embarque

controlling_customer

string

Industry A LTDA

Organização pai do embarque

consignee

string

Industry A - South LTDA

Importador da carga

consignor

string

B Corporation Co

Exportador da carga

origin

relationship

Tabela Localização

Origem do embarque

destination

relationship

Tabela Localização

Destino final do embarque

carrier

string

MAESRK

Nome do armador responsável pelo transporte

type

string

SEA

Formato da viagem

vessel_name

string

Ship Name

Nome do navio principal da viagem

voyage_number

string

444W

Número da viagem do navio principal da viagem

estimated_departure

date

2023-09-22T00:00:00

Data de saída estimada do local de origem

actual_departure

date

2023-09-22T00:00:00

Data real de saída do local de origem

estimated_arrival

date

2023-09-22T00:00:00

Data de chegada estimada no destino final

actual_arrival

date

2023-09-22T00:00:00

Data real de chegada no destino final

legs

list of legs

Tabela Perna do Trajeto

Lista ordenada das pernas do trajeto

container_count

integer

6

Quantidade de containers vinculados ao embarque

container_mode

string

FCL - Full Container Load

Tipo de contratação dos containers

containers

list of containers

Tabela Containers

Containers vinculados ao embarque

goods_description

string

Produto A

Descrição da carga

goods_value

number

10.000,00

Valor da carga

goods_currency

string

FOB

Moeda do valor da carga

incoterm

string

1

Código das condições de negociação internacional

quantity

number

111

Quantidade de itens da carga

quantity_unit

string

PKG

Unidade referente a quantidade de itens da carga

weight

number

10.000

Peso da carga

weight_unit

string

KG

Unidade de medida do peso da carga

volume

number

200

Volume da carga

volume_unit

string

M3

Unidade de medida do volume da carga

chargeable

number

200

Volume sujeito a cobrança

free_time_destination

integer

1

Diárias de free time no local de destino

free_time_origin

integer

4

Dias de free time no local de origem

inspecao

string

Conferido

Caso aplicável, status da inspeção

data_inspecao

date

2023-09-22T00:00:00

Caso aplicável, data de realização da inspeção

est_cargo_ready

date

2023-09-22T00:00:00

Data estimada de prontidão da carga

cargo_ready

date

2023-09-22T00:00:00

Data real de prontidão da carga

sales_staff

realtiosnship

Tabela Pessoas

Pessoa responsável pela venda

operation_staff

realtionship

Tabela Pessoas

Pessoa responsável pela operação

Erros

Para garantir uma integração suave e eficiente, nossa API de Acompanhamento de Embarques fornece mensagens de erro detalhadas e padronizadas. Estas mensagens ajudam os desenvolvedores a identificar, diagnosticar e resolver problemas rapidamente. A seguir, descrevemos os tipos de erros que podem ocorrer e como interpretá-los.

Estrutura de Resposta de Erro

Quando ocorre um erro, a API retorna uma resposta JSON com a seguinte estrutura:

Error

JSON

{ "message": "string", "resourcePath": "string", "details": "string" }
  1. Message: mensagem de erro;
  2. Resource Path: a rota na qual ocorreu o erro;
  3. Details: mensagem um pouco mais diretiva a respeito do erro;

Abaixo segue algumas instruções a respeito dos erros mais comuns que podem ser encontrados e junto de algumas soluções a ser utilizadas:

Error 400 - Bad Request

Esse erro pode ser encontrado devido a uma má formação do requisição. Confira as informações solicitados se estão de acordo com os requisitos de cada rota, principalmente se o Corpo da requisição e possíveis parâmetros estão preenchidos corretamente e ainda é válido.

Error 401 - Unauthorized

Esse erro pode ser encontrado devido a alguns fatores e se deve a alguma falha de acesso ao recurso requisitado. Confira as suas informações de acesso, principalmente se o cabeçalho referente a Token de Acesso está preenchido corretamente e ainda é válido.

Error 403 - Forbidden

Esse erro pode ser encontrado devido a alguns fatores e se deve a alguma falha na autenticação. Confira as suas informações de acesso, principalmente se o cabeçalho referente a Chave de API está preenchido corretamente.

Error 429 - Too Many Requests

Esse erro se dá devido a um excesso de solicitações dentro de um intervalo de tempo. Aguarde um pouco e tente novamente. Caso esse erro não seja condizente com o seu uso, você pode entrar em contato conosco para buscar alguma outra solução.

Informações Adicionais

Limites de Uso e Cotas

Para garantir um serviço de alta qualidade e disponibilidade para todos os nossos usuários, implementamos limites de uso e cotas na nossa API. Esta seção detalha os limites aplicáveis, como monitorá-los e o que fazer se precisar de mais capacidade.

Limites Gerais

  1. Requisições por segundo:

    Cada chave de API tem um limite de 10 requisições por segundo. Esse limite ajuda a garantir que a API permaneça responsiva para todos os usuários.

  2. Requisições simutâneas:

    Cada chave de API tem um limite de 10 requisições simultâneas. Esse limite ajuda a garantir que a API permaneça responsiva para todos os usuários.

  3. Cota mensal:

    Cada chave de API tem um limite de 10.000 solicitações por mês. Esse limite ajuda a garantir que a API permaneça responsiva para todos os usuários.

Caso queira solicitar um aumento de cota, entre em Contato com a equipe de suporte.

Segurança e Boas Práticas

Garantir a segurança dos dados e a integridade das transações é uma prioridade fundamental para Skymarine API. Esta seção fornece diretrizes e práticas recomendadas para ajudar você a proteger sua aplicação e seus usuários.

Boas Práticas

Para garantir a segurança das suas interações com a API, siga estas práticas recomendadas:

  1. Armazenamento de Credenciais:

    A fim de garantir a segurança tanto da API, mas principalmente dos seus dados, armazene de forma cuidadosa a Chave de API e os tokens que você obtiver. Não compartilhe e nem salve em lugares públicos.

  2. Gestão de Uso:

    Como mencionado antertiomente, a API possui limites de uso. Certifique-se que sua aplicação não ultrapasse esses limites, para evitar bloqueios e suspensões.

Revogação de Credenciais

Para garantir a segurança da aplicação, periodicamente as credenciais são revogadas.

  1. Chave da API:

    Tem validade de 6 meses, após esse período será revogada. Será renovado e reenviado pela Skymarine, apenas para clientes que ainda estiverem ativos no último período.

  2. Token de Renovação:

    Tem validade de 1 mês, após esse período será invalido. Você poderá renovar esse token através da própria API

  3. Token de Acesso:

    Tem validade de 1 hora, após esse período será invalidado. Você poderá renovar esse token através da própria API

Atualizações e Versões

Para garantir que você esteja sempre utilizando a versão mais recente e segura de nossa API, implementamos um sistema de versionamento claro e fornecemos atualizações regulares. Esta seção detalha como tratamos as atualizações e o versionamento, além de fornecer orientações sobre como manter sua integração sempre atualizada.

Nossa API é continuamente melhorada e atualizada. Para garantir a compatibilidade e aproveitar as novas funcionalidades, recomendamos acompanhar as notas de versão e migrar para as versões mais recentes quando necessário. Você pode conferir também o Swagger da API para verificar o estado da versão mais recente.

Versão Atual

Política de Versionamento

Utilizamos o versionamento semântico para todas as versões da nossa API. Cada versão é identificada por um número de versão MAJOR.MINOR.PATCH:

  1. MAJOR: Mudanças significativas que podem incluir alterações incompatíveis com versões anteriores.
  2. MINOR: Novas funcionalidades que são compatíveis com versões anteriores.
  3. PATCH: Correções de bugs e melhorias menores que não afetam a compatibilidade com versões anteriores.

Notas de Versão

Publicamos notas de versão detalhadas para cada atualização, descrevendo as novas funcionalidades, correções de bugs e quaisquer mudanças que possam afetar a compatibilidade. As notas de versão estarão disponíveis nesse site quando houver e também podem ser enviadas por e-mail para as contas cadastradas caso seja optado por isso.

Exemplos de Versionamento

  1. v1.2.0: Introdução de novos endpoints para rastreamento de embarques.
  2. v1.1.5: Correção de um bug que afetava a autenticação de usuários.
  3. v2.0.0: Reformulação completa do sistema de autenticação, resultando em mudanças incompatíveis com a versão 1.x.x.

Planejamento de Atualizações

Para ajudar você a planejar as atualizações, fornecemos um cronograma de lançamento antecipado para as próximas major versões. Este cronograma estará disponível junto das notas de atualizações.

Contato

Se você tiver dúvidas, precisar de suporte ou desejar fornecer feedback, estamos aqui para ajudar. Existem várias maneiras de entrar em contato conosco: