Parceiro API - Introdução

A API de Parceiro permite criar, configurar e gerir subscrições dos seus clientes através de uma integração própria, sem necessidade de aceder manualmente ao Facturalusa. Estes endpoints foram pensados para plataformas, aplicações e integradores que pretendem disponibilizar facturação aos seus próprios clientes, mantendo o processo operacional dentro do seu software.

Para chamar os endpoints reservados a parceiros é obrigatório enviar o header x-partner-key. Este header identifica o parceiro e permite validar que a operação pode ser executada dentro da rede de subscrições associadas ao parceiro.

Além do x-partner-key, deve continuar a ser utilizada a API key da subscrição através do mecanismo normal de autenticação da API. A x-partner-key identifica o parceiro; a API key identifica a subscrição sobre a qual está a ser executado o pedido.

O fluxo habitual passa por consultar os planos disponíveis, criar uma subscrição em ambiente de produção ou teste, guardar a API key devolvida e, a partir daí, utilizar essa API key para configurar a entidade, impressão, autoridade tributária, callbacks, entre outros.

Os endpoints de parceiro dividem-se em dois grupos: /partner/*, para operações globais do parceiro, e /subscription/*, para operações sobre a subscrição autenticada. Ambos exigem autenticação válida e acesso de parceiro.

Os endpoints /partner/* apenas podem ser chamados através de uma API key de uma subscrição de produção. Uma API key de teste não pode executar operações globais de parceiro, como consultar o estado do parceiro, consultar planos disponíveis, gerar API keys ou criar novas subscrições.

As API keys de teste podem, no entanto, ser utilizadas nos endpoints /subscription/*, permitindo configurar e testar a subscrição de teste autenticada.