Unofficial Carris API Documentation

API privada da Carris, descrita de acordo com as normas OpenAPI 3.0.0 e Swagger.

Esta API está protegida com autorização do tipo bearer JWT. Os tokens expiram a cada 15 minutos e devem ser atualizados com refresh.

Documentação Swagger/OpenAPI

---

A CARRIS também disponibiliza dados publicamente nos formatos GTFS e GTFS-RT através do seu portal do programador (https://gateway.carris.pt/apiui/#!/)

---

Índice de Conteúdos

Clique para expandir

• Autenticação Inicial
  • Pedido
  • Resposta
• Endpoints
  • Pedido
  • Resposta
• Refresh/Atualização
  • Pedido
  • Resposta

---

..::Autenticação Inicial::..

Obter um authorizationToken inicial

Fazer um POST request para o endpoint de autorização.

Pedido

{
	"token": "string",    //o valor desta chave é token de app fornecido pela carris
	"type": "string"    //o valor desta chave deverá ser "apikey" no primeiro request
}

Resposta

{
  "authorizationToken": "string",    // guardar token JWT a usar em todas os outros pedidos
  "refreshToken": "string",    // guardar token para atualizar o token expirado
  "expires": int    // data de expiração do token em segundos desde a Era Unix/Unix Epoch
}

Pode descodificar o token JWT "authorizationToken" e saber mais sobre a norma JWT em JWT.io

..::Endpoints::..

Obter dados provenientes da Carris

Fazer GET requests para os endpoints de dados.

Pedido

Deverá incluir um cabeçalho de autenticação do tipo Bearer, que contenha o o valor da chave JSON obtido em Autenticação Inicial:

Authorization: Bearer { authorizationToken }

Resposta

Deverá recebr uma respota em troca do seu pedido.

A resposta depende do endpoint que escolher. 
Será dada no formato JSON.

..::Refresh/Atualização::..

Trocar o seu authenticationToken inválido por um válido

Após aproximadamente 15 minutos (se preferir, calcule a hora de criação do token com a hora de expiração do mesmo para obter o tempo de vida do token), o seu authorizationToken irá expirar. Recolha o refreshToken que obteu em Autenticação Inicial e inclua-o no corpo do seu pedido. Ser-lhe-á atribuído um novo authorizationToken válido.

Repita este processo ao longo do tempo de vida da sua aplicação (faça um novo pedido de Autenticação Inicial se o tempo de vida da app for reiniciado). A cada 15 minutos, revogue o authorizationToken atual e atualize-o - e assim sucessivamente.

Pedido

Agora, deverá recolher o refreshToken obtido em Autenticação Inicial e faça dele o valor da chave "token". Indique que o token é de atualização, mudando o valor da chave "type" para "refresh".

{
	"token": "string",    // token de refresh
	"type": "string"    // o valor desta chave deve ser "refresh" aquando da atualização do seu token
}

Resposta

Esta resposta será igual à obtida em Autenticação Inicial. Recolha os valores da chave e use-os nos seus próximos pedidos, de forma a manter um flow de tokens contínuo. Aquando do término de mais um período de 15 minutos, volte a atualizar o seu authorizationToken e assim sucessivamente!

{
  "authorizationToken": "string",    // guardar token a usar em todas os outros pedidos
  "refreshToken": "string",    // guardar token para atualizar o token expirado
  "expires": int    // data de expiração do token em segundos desde a Era Unix/Unix Epoch
}

---

Divirta-se e partilhe os seus projetos connosco!

Não hesite em contactar para mais informações!

Os Pull Requests e Issues são bem-vindos :)