Quick start

Este guia leva você do zero ao seu primeiro request autenticado em cerca de 5 minutos: obter um token, fazer um GET real, ler a resposta, paginar e entender os erros.

Antes de começar

Você precisa de um usuário de API da Rently (com permissões para usar a API) e da URL da sua instância. Na Rently cada cliente (tenant) vive em seu próprio host, por exemplo https://sua-empresa.rently.com.ar. O host identifica o tenant, então sempre use o host da sua instância em cada chamada.

Neste guia usamos https://{tenant}.rently.com.ar como exemplo. Substitua pelo host do seu tenant.

1. Obter um token

A API se autentica com um token Bearer OAuth2. Para obtê-lo, faça um POST em /auth/token com suas credenciais usando o grant client_credentials. Seu usuário de API é o client_id e sua chave é o client_secret.

curl -X POST https://{tenant}.rently.com.ar/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_USERNAME" \
  -d "client_secret=YOUR_PASSWORD"

A resposta é um JSON com o token:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...",
  "token_type": "bearer",
  "expires_in": 86399
}

Campo	Descrição
`access_token`	O token que você envia em cada request posterior.
`token_type`	Sempre `bearer`. Define o esquema do header `Authorization`.
`expires_in`	Validade do token em segundos (≈ 1 dia).

Reutilize o token

O token vale cerca de um dia (expires_in ≈ 86399 segundos). Guarde-o e reutilize-o em vez de pedir um novo a cada request. Quando expirar, peça outro.

O token está vinculado ao tenant

O token só é válido contra o mesmo host com o qual você o solicitou. Se usar um token contra o host de outro tenant, a API responde 403. Solicite sempre o token e faça as chamadas contra o mesmo host.

2. Seu primeiro request autenticado

Com o access_token, adicione o header Authorization: Bearer {token} a qualquer endpoint da API. Vamos começar por um GET simples e sem parâmetros: listar as filiais da sua instância com GET /api/branchoffices.

curl https://{tenant}.rently.com.ar/api/branchoffices \
  -H "Authorization: Bearer YOUR_TOKEN"

Resposta (array de filiais):

[
  {
    "Id": 1,
    "BusinessName": "Rently LAX Airport",
    "Name": "LAX Branch",
    "Street": "123 Airport Road",
    "Number": "Terminal 1",
    "City": "Los Angeles",
    "Country": "United States",
    "PostalCode": "90045",
    "Latitude": 33.9416,
    "Longitude": -118.4085,
    "Telephone": "+1-213-555-0123",
    "Email": "lax@rently.com",
    "IATACode": "LAX",
    "IsFranchise": false,
    "PublicWebSite": "https://rently.com/locations/lax"
  }
]

Idioma da resposta

Alguns endpoints aceitam um parâmetro Language para definir o idioma dos textos da resposta; por exemplo, GET /api/search o suporta. O valor aceita o nome de cultura completo (es-AR, en-US, pt) ou o código ISO de duas letras (es, en). Se você omitir, usa-se o idioma padrão da sua instância. Consulte a referência da API para ver quais endpoints o aceitam.

Pronto: esse é o seu primeiro chamado autenticado. Cada vez que receber um 200, você já está operando contra a API.

3. Um GET com paginação

As listagens grandes vêm paginadas. Vejamos GET /api/bookings/list, que devolve reservas em blocos. Aceita estes parâmetros de query:

Parâmetro	Default	Descrição
`offset`	`0`	Cursor de paginação. Na primeira chamada, `0`.
`limit`	`30`	Quantidade de elementos por página.
`status`	—	Filtro opcional por status da reserva.
`sortDirectionAsc`	`true`	Direção de ordenação.

curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=0&limit=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

A resposta envolve os resultados em uma estrutura paginada:

{
  "Offset": 0,
  "Limit": 30,
  "Total": 1,
  "Results": [
    {
      "Id": 1,
      "IsQuotation": false,
      "Balance": 0.0,
      "TotalPayed": 0.0
    }
  ],
  "NextOffset": 0
}

Campo	Descrição
`Offset` / `Limit`	O offset e o limite aplicados a esta página.
`Total`	Quantidade total de registros disponíveis.
`Results`	O array de elementos desta página (pode vir `null` se não houver resultados).
`NextOffset`	O `offset` a enviar na próxima chamada para trazer a página seguinte.

Como iterar as páginas

Para percorrer todas as páginas, pegue o NextOffset de cada resposta e passe-o como offset na seguinte. A iteração termina quando Results traz menos elementos que Limit.

# Página seguinte: use o NextOffset que a resposta anterior devolveu
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=NEXT_OFFSET&limit=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Tratamento de erros

Diante de um erro, a API responde com um código de status HTTP e, nos erros de negócio, um corpo JSON com o formato WebApiErrorResponse:

{
  "ErrorMessage": "The requested resource was not found",
  "ErrorCode": 1,
  "Id": "0HMV9A1B2C3D4-00000001"
}

Campo	Descrição
`ErrorMessage`	Descrição legível do erro.
`ErrorCode`	Código numérico do erro (por exemplo, `1` = cliente não encontrado, `4` = o preço não coincide, `22` = reserva não encontrada). É serializado como inteiro.
`Id`	GUID de correlação. Útil para reportar o problema ao suporte.

Códigos de status mais comuns:

Status	Significado	Corpo
`200`	Sucesso.	Resultado do endpoint.
`400`	Erro de negócio ou de validação.	`WebApiErrorResponse` com `ErrorCode`.
`403`	Não autenticado ou sem permissões.	—
`404`	Recurso não encontrado.	—

A autenticação falha retorna 403

Se o token estiver ausente, vencido, ou não corresponder ao tenant do host, a API responde 403 (não 401). Se receber 403, verifique se o header Authorization está presente, se o token não expirou e se você está usando o host correto do tenant.

Guarde o Id do erro

Quando algo falha com um 400, o campo Id do corpo é o identificador de correlação. Inclua-o ao abrir um ticket de suporte: ele permite rastrear exatamente o que aconteceu do lado do servidor.

Próximos passos

Você já tem o essencial: token, request autenticado, paginação e erros. A partir daqui você pode explorar o resto da API:

Busque disponibilidade e cote com GET /api/search e GET /api/booking/price.
Crie uma reserva com POST /api/booking/book e registre o pagamento com POST /api/booking/pay.
Consulte os catálogos mestres: GET /api/places, GET /api/categories, GET /api/currencies.

O detalhe completo de cada endpoint, com seus parâmetros e schemas, está na referência da API.

1. Obter um token​

2. Seu primeiro request autenticado​

3. Um GET com paginação​

Como iterar as páginas​

4. Tratamento de erros​

Próximos passos​