Como Consumir a API de Calendários

Publicado em 2012-05-29 21:49 por JP Negri

A calculadora de prazos além de acessível via tela também pode ser acessada através de uma API REST permitindo o consumo da funcionalidade por outros sites (via JSONP) e sistemas. Nesse post documentamos a API e mostramos como consumi-la usando jQuery

Esse post é direcionado a programadores com alguma experiência em JavaScript, especialmente usando-se jQuery. Outro artigo explica a calculadora em termos de funcionalidade para os não versados em finanças.

Material Necessário

  • Alguma ferramenta que permita invocar APIs REST com algum grau de controle melhor do que apenas um Browser. Recomendo o excelente plugin do Firefox RESTClient ou o bastante bom Advanced REST client Application para o Chrome.
  • Um editor HTML/JavaScript decente. Aqui usamos o Visual Studio 2012, mas qualquer um em que você seja proficiente vai funcionar.

Show me the code!

Nada como ver funcionando para aprender. Por isso baixe uma cópia da aplicação de exemplo no GitHub e experimente. O restante do post detalhara formalmente os métodos, mas é no exemplo que se vê, em ação, jQuery, JSONP e nossa API.

A url base da API está sempre em http://elekto.com.br/api/.

Os métodos da API

Todos os métodos da API são GET, podendo ou não ter alguns parâmetros. A resposta bem sucedida sempre tem status 200. O erro mais comun é Bad Request (400), em geral devido a algum parâmetro mal formatado; ou Not Found (404) ao tentar-se usar um calendário não disponível nesse serviço.

A resposta dos métodos pode ser JSON, JSONP ou XML. O padrão é JSON, mas se o header da chamada conter accept: application/xml então XML será retornado; ou se conter accept: application/javascript JSONP é retornado. Existe um método que é exceção e sempre responde com texto plano, conforme documentados mais abaixo.

A opção de XML é mais interessante ao consumir-se a API num aplicativo, ao invés de numa página.

JSONP é necessário para invocar esse serviço caso o faça a partir de uma página em outro site, o que é um dos cenários mais comuns de utilização. Ainda assim os exemplos abaixo mostrarão a resposta JSON, posto que o consumo de JSONP via jquery é (quase) transparente. No caso de JSONP deve-se, alem do header adequado, informar na chamada o nome da função de callback no parâmetro, opcional, muito convenientemente chamado de callback.

Calendars

Retorna os calendários disponíveis para utilização. Nenhum parâmetro é necessário

URL exemplo: http://elekto.com.br/api/Calendars

Exemplo de Retorno

[
  {
    "BusinessCalendarCode":"br-BC",
    "Description":"Brasil - Banco Central",
    "MaxDate":"2055-01-01T00:00:00",
    "MinDate":"1950-02-20T00:00:00"
  },
  {
    "BusinessCalendarCode":"br-SP",
    "Description":"Brasil - São Paulo",
    "MaxDate":"2079-01-01T00:00:00",
    "MinDate":"2001-01-01T00:00:00"
  }
]
Campos Retornados
CampoDescrição
BusinessCalendarCodeO código do calendário. Será o recurso a ser usado nas demais chamadas
DescriptionUm nome amigável para o calendário.
MaxDateA maior data até onde cálculos com o calendário são precisos.
MinDateA menor data até onde cálculos com o calendário são precisos.

Calendars/:businessCalendarCode

Retorna os feriados do local identificado.

URL exemplo: http://elekto.com.br/api/Calendars/br-SP

Parâmetros
ParâmetroObrigatório?Descrição
businessCalendarCodeSimO código do calendário.

Exemplo de Retorno

[
  "1950-02-20T00:00:00",
  "1950-02-21T00:00:00",
  "1950-04-06T00:00:00",
  "1950-04-07T00:00:00"
]

É apenas um vetor contendo as datas que são feriados no calendário.

Além dos parâmetros descritos o resultado pode ser consumido ainda com queries OData padrão.

Calendars/:businessCalendarCode/Text

Na verdade não é um método JSON. É apenas um modo conveniente de baixar um arquivo texto com os feriados do calendário selecionado. As datas estão em ISO-8601.

URL exemplo: http://elekto.com.br/api/Calendars/br-SP/Text

Parâmetros
ParâmetroObrigatório?Descrição
businessCalendarCodeSimO código do calendário.

Calendars/:businessCalendarCode/Delta

Permite o cálculo dos prazos (em dias úteis e corridos) entre duas datas.

URL exemplo: http://elekto.com.br/api/Calendars/br-BC/Delta?initialDate=2012-05-29&finalDate=2012-07-22&type=financial

Parâmetros
ParâmetroObrigatório?Descrição
businessCalendarCodeSimO código do calendário.
initialDateSimA data inicial do prazo a ser computado. No formato AAAA-MM-DD.
finalDateSimA data final do prazo a ser computado. No formato AAAA-MM-DD.
typeOpcional. O default é "financial"O tipo de prazo a ser computado. "financial" retorna prazos financeiros (excluindo o último dia), "whole" retorna os prazos cheios, incluindo a data final.

Exemplo de Retorno

{
"ActualDays": 54,
"WorkDays": 38
}

Calendars/:businessCalendarCode/Add

A partir de uma data inicial e de um prazo (em dias úteis ou corridos) retorna a data final.

URL exemplo: http://elekto.com.br/api/Calendars/br-BC/Add?initialDate=2012-05-25&days=8&type=actual&finalAdjust=modifiedFollowing

Parâmetros
ParâmetroObrigatório?Descrição
businessCalendarCodeSimO código do calendário.
initialDateSimA data inicial do prazo a ser computado. No formato AAAA-MM-DD.
daysSimO prazo em dias.
typeOpcional. O default é "work"O tipo de prazo informado. "work" para prazos em dias úteis, "actual" para prazos em dias corridos.
finalAdjustOpcional. O default é "none"O tipo de ajuste a ser aplicado na data final. "none" não faz ajuste algum, "following" ajusta para o dia útil seguinte, e "modifiedFollowing" ajusta para o útil seguinte desde que não mude o mês. Para mais detalhes sobre esse parâmetro veja o manual da calculadora.

Exemplo de Retorno

"2012-06-04T00:00:00"

Nota Final

O uso da API é livre. Não esqueça de verificar os Termos de Serviço, que são bastante justos. Se tiver dúvidas quanto ao uso dela deixe um comentário abaixo, ou entre em contato conosco.

Atualização

Este artigo foi atualizado em 2013-08-29 para refletir mudanças na serialização das datas, que passou a ser no formato ISO-8601, ou seja, o amigável yyyy-MM-dd. Também passamos a hospedar o código de exemplo no GitHub.

Share