URL base
https://freebillgen.com/api/v1Autenticação
Toda requisição usa um token Bearer. Crie um em Configurações → Chaves de API, atribua os escopos de leitura e gravação necessários por recurso, defina uma validade opcional e envie-o em cada requisição:
Authorization: Bearer <sua-chave-de-api>As requisições são autenticadas na conta que criou a chave e conferidas segundo os escopos atribuídos. Mantenha o token em sigilo e revogue-o se for exposto ou deixar de ser necessário.
O que você pode fazer
- Ler faturas, clientes, empresas, pagamentos e agendamentos recorrentes
- Criá-los e atualizá-los (API de escrita - Pro)
- Obter relatórios de impostos e vencimentos em JSON
- Ler a mesma fila limitada de Próximas ações usada pelo painel
- Ler arquivos de faturas eletrônicas de fornecedores que você enviou manualmente à Caixa de entrada (não é um endpoint de recebimento por Peppol ou e-mail)
- Baixar mapeamentos genéricos OASIS UBL e UN/CEFACT CII para análise (sem validação de perfil)
- Registrar endpoints de webhook para eventos de fatura e pagamento (Pro)
- Idempotency-Key nas gravações compatíveis. Dados de solicitação alterados sob a mesma chave retornam 409
- Paginação por cursor via links.next, ajustável com per_page (máx. 100)
- Permitir que agentes de IA leiam qualquer fatura compartilhada - JSON-LD schema.org/Invoice, além de Accept: application/json ou text/markdown em cada link de compartilhamento assinado
- Servidor MCP somente 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 retorna o sucesso original. Dados alterados retornam 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). A fila limitada de ações informa seu limite e se foi truncada.
- Valores monetários
- Os valores monetários são strings JSON exatas, formatadas na escala ISO 4217 da moeda, como "121.00" para EUR ou "500" para JPY. Os preços unitários podem manter uma precisão adicional informada.
- IDs
- Cada recurso é endereçado por um id opaco, nunca por um número sequencial.
Exemplo: liste 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 gravação e os webhooks de saída fazem parte do Lifetime Pro por € 49, com tributos incluídos: um único pagamento, sem mensalidade nem renovação anual.
Como faço a autenticação?
Crie um token Bearer em Configurações -> Chaves de API, atribua a ele escopos de leitura/escrita por recurso, e envie-o como um cabeçalho Authorization: Bearer em cada requisição. As chaves têm escopo limitado à sua própria conta e podem ser revogadas ou expiradas.
Posso criar faturas programaticamente?
Sim, pela API de gravação, que faz parte do complemento Pro. Ela produz as mesmas faturas profissionais que o aplicativo web, com numeração sequencial e tratamento configurável de impostos aplicado no servidor. A API não certifica 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 retorna o resultado original. Reutilizá-la com dados alterados retorna 409, em vez de repetir silenciosamente uma fatura diferente.
Posso ler as faturas que recebi?
Sim, gratuitamente. GET /api/v1/inbox lista os arquivos UBL/CII compatíveis de fornecedores que você enviou manualmente e que o FreeBillGen interpretou, mantendo o original para auditoria. GET /api/v1/inbox/{id} retorna um deles. O reconhecimento da sintaxe não valida perfis, e esses endpoints não transformam o FreeBillGen em um canal de recebimento Peppol, de rede governamental ou por e-mail.
Um agente de IA pode ler uma fatura sem uma conta?
Sim. Cada fatura compartilhada 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 retorna uma fatura estruturada, e Accept: text/markdown retorna uma versão limpa e econômica em tokens. Também há um servidor Model Context Protocol (MCP) somente 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.