Para trabalhar com a API, é fundamental estar familiarizado com pedidos POST e autenticação Oauth2.
Todos os pedidos para API deverão ser enviados através do método POST e os dados podem ser enviados em formato x-www-urlencoded ou em Json.
Na query string do pedido devem estar incluídos os seguintes parâmetros:
Access token (access_token)
Parâmetro obrigatório que deve estar sempre em todos os pedidos.
Json (json)
A API por defeito aceita apenas dados em formato x-www-urlencoded.
Para enviar os dados em formato Json deverá acrescentar na query string do pedido o parâmetro "json=true"
Human errors (human_errors)
Existe ainda outro parâmetro opcional: Human errors.
Ao enviar este parâmetro, quando a API devolver algum erro, como por exemplo, inserir um documento ou inserir um artigo, juntamente com o erro, vem uma mensagem verbosa do mesmo.
Por exemplo, na falta da indicação de uma série de documento é retornado o erro "2 document_set_id".
Body
Os restantes dados são enviados no body do POST, podendo estes ser enviados, tal como referido acima, em formato x-www-urlencoded ou Json.
Por exemplo, "company_id=5" em x-www-urlencoded ou "{company_id:5}" em json.
Renovação da Access Token
As access tokens têm uma validade de uma hora conforme descrito na documentação e é importante que a mesma seja usada praticamente na sua totalidade.
Depois de passar pelo processo de autenticação, deverá guardar as duas tokens do seu lado e usar essa mesma access token até que ela expire (ou esteja prestes a expirar).
Sempre que for fazer um pedido à API ou começar um processo que envolva vários pedidos à API, deverá analisar primeiro se a access token ainda é válida.
Caso não seja válida deverá usar o endpoint de renovação para obter duas novas tokens, e passar a usar essas.
