URL base
https://freebillgen.com/api/v1Autenticação
Cada pedido usa um token Bearer. Crie um em Definições → Chaves de API, atribua os âmbitos de leitura e escrita necessários por recurso, defina uma validade opcional e envie-o em cada pedido:
Authorization: Bearer <a sua-chave-de-api>Os pedidos são autenticados na conta que criou a chave e verificados segundo os âmbitos atribuídos. Mantenha o token em sigilo e revogue-o se for exposto ou deixar de ser necessário.
O que pode fazer
- Ler faturas, clientes, empresas, pagamentos e agendamentos recorrentes
- Criá-los e atualizá-los (API de escrita - Pro)
- Obter relatórios de IVA e de antiguidade de saldos em JSON
- Ler a mesma fila limitada de Próximas ações usada pelo painel
- Ler ficheiros de faturas eletrónicas de fornecedores que enviou manualmente à Caixa de entrada (não é um endpoint de receção por Peppol ou e-mail)
- Descarregar mapeamentos genéricos OASIS UBL e UN/CEFACT CII para análise (sem validação de perfil)
- Registar endpoints de webhook para eventos de fatura e pagamento (Pro)
- Idempotency-Key nas operações de escrita compatíveis. Dados de pedido alterados sob a mesma chave devolvem 409
- Paginação por cursor via links.next, ajustável com per_page (máx. 100)
- Permitir que agentes de IA leiam qualquer fatura partilhada - JSON-LD schema.org/Invoice, além de Accept: application/json ou text/markdown em cada link de partilha assinado
- Servidor MCP apenas leitura e sem autenticação em https://freebillgen.com/api/mcp (get_invoice, verify_invoice) para agentes de IA
Convenções
- Idempotência
- Nas chamadas de criação e ação compatíveis, envie uma Idempotency-Key exclusiva. Repetir dados idênticos devolve o sucesso original. Dados alterados devolvem 409.
- Paginação
- As listas de recursos persistidos usam paginação por cursor. Siga links.next (ou envie ?cursor=...) e ajuste ?per_page= (máx. 100). O fluxo limitado de ações indica o respetivo limite e se foi truncado.
- Valores monetários
- Os valores monetários são cadeias de carateres JSON exatas, formatadas segundo a escala ISO 4217 da moeda, como "121.00" para EUR ou "500" para JPY. Os preços unitários podem conservar a precisão adicional com que são introduzidos.
- IDs
- Cada recurso é identificado por um ID opaco, nunca por um número sequencial.
Exemplo: liste as suas faturas
curl https://freebillgen.com/api/v1/invoices \
-H "Authorization: Bearer $FREEBILLGEN_API_KEY"Abrir a referência completa e interativa da API →
Perguntas sobre a API de fatura
A API de fatura é gratuita?
Sim. A API de leitura está incluída gratuitamente. A API de escrita e os webhooks de saída fazem parte do Lifetime Pro por € 49, com impostos incluídos: um único pagamento, sem mensalidade nem renovação anual.
Como faço a autenticação?
Crie um token Bearer em Definições -> Chaves de API, atribua-lhe âmbitos de leitura e escrita por recurso e envie-o como um cabeçalho Authorization: Bearer em cada pedido. As chaves têm âmbito limitado à sua própria conta e podem ser revogadas ou expiradas.
Posso criar faturas programaticamente?
Sim, através da API de escrita, que faz parte do complemento Pro. Produz as mesmas faturas profissionais que a aplicação Web, com numeração sequencial e tratamento configurável do IVA aplicado no servidor. A API não certifica a conformidade com a legislação local.
Como evito criar faturas duplicadas em caso de reenvio?
Envie uma Idempotency-Key exclusiva na chamada de criação. Repetir dados idênticos com essa chave devolve o resultado original. Reutilizá-la com dados alterados devolve 409, em vez de repetir silenciosamente uma fatura diferente.
Posso ler as faturas que recebi?
Sim, gratuitamente. GET /api/v1/inbox lista os ficheiros UBL/CII compatíveis de fornecedores que enviou manualmente e que o FreeBillGen interpretou, mantendo o original para auditoria. GET /api/v1/inbox/{id} devolve um deles. O reconhecimento da sintaxe não valida perfis, e esses endpoints não transformam o FreeBillGen num canal de receção Peppol, de rede governamental ou por e-mail.
Um agente de IA pode ler uma fatura sem uma conta?
Sim. Cada fatura partilhada por um link público assinado pode ser lida por agentes na mesma URL. A página incorpora JSON-LD schema.org/Invoice. O cabeçalho Accept: application/json devolve uma fatura estruturada (partes, itens, totais, saldo devido e opções de pagamento), enquanto Accept: text/markdown devolve uma versão limpa e económica em tokens. Também há um servidor Model Context Protocol (MCP) apenas de leitura e sem autenticação em https://freebillgen.com/api/mcp, com as ferramentas get_invoice e verify_invoice. A assinatura do link é o token de acesso. Trate a URL completa como segredo, pois qualquer pessoa que a receber poderá abrir a fatura.