Utilização

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. 

© 2021 Moloni

Software de faturação online

Certificado pela Autoridade Tributária N.º 2860