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:
- 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.
- 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.
- 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.
- 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
. - 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
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:
- 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 valorBearer
seguido do token. Esse token possui uma duração de 1 dia.Nome do Header
Valor
- 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
Body
Nome
Tipo
Descrição
Response
Nome
Tipo
Descrição
Example - POST - /auth
javascript
Resposta
JSON
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
Body
Nome
Tipo
Descrição
Response
Nome
Tipo
Descrição
Example - POST - /auth/refresh-token
javascript
Resposta
JSON
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:
- Rastreamento: Obtenha informações atualizadas sobre a localização e o status dos seus embarques.
- Histórico de Embarques: Acesse o histórico completo dos seus embarques com a Skymarine.
- 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
Body
Nome
Tipo
Descrição
Response
Nome
Tipo
Descrição
Example - POST - /shipments
javascript
Resposta
JSON
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
Pessoas
Nome
Tipo
Exemplo
Descrição
Containers
Nome
Tipo
Exemplo
Descrição
Pernas do Embarque
Nome
Tipo
Exemplo
Descrição
Embarque
Nome
Tipo
Exemplo
Descriçã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: mensagem de erro;
- Resource Path: a rota na qual ocorreu o erro;
- 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
- 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.
- 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.
- 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:
- 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.
- 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.
- 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.
- 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
- 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:
- MAJOR: Mudanças significativas que podem incluir alterações incompatíveis com versões anteriores.
- MINOR: Novas funcionalidades que são compatíveis com versões anteriores.
- 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
- v1.2.0: Introdução de novos endpoints para rastreamento de embarques.
- v1.1.5: Correção de um bug que afetava a autenticação de usuários.
- 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: