Fatura dentro, QR de pagamento fora — via API

Pronto em três passos

1. 1

   Cria uma chave API

   Inicia sessão na app e cria uma chave em «API e integrações». Começa por gsk_live_ e é mostrada exatamente uma vez — guarda-a em segurança. 10 tokens grátis já estão na conta.

2. 2

   Escolhe uma porta

   REST para o teu sistema, MCP para o teu agente de IA, email para fluxos de envio existentes — ou simplesmente a aplicação web. A chave é a mesma em todo o lado.

3. 3

   Envia faturas

   Documento dentro, resposta com os dados de pagamento e o GiroCode fora — para PDF, também o PDF carimbado. Cada resposta indica os tokens cobrados e restantes.

A API REST e o servidor MCP autenticam-se com a mesma chave API do GiroSnap como bearer token. Não existe uma «chave MCP» separada — a chave gsk_live_ da app é a única chave:

Authorization: Bearer gsk_live_...

As chaves criam-se e revogam-se apenas na app (sessão iniciada) — uma chave divulgada nunca pode gerar novas chaves. O texto em claro nunca mais pode ser recuperado depois da criação.

JSON ou multipart, máx. 12 MB por documento (JPG, PNG, WEBP, PDF). O arranque mais rápido é o endpoint tudo-em-um:

curl -X POST https://www.girosnap.eu/api/v1/invoices \
  -H "Authorization: Bearer gsk_live_..." \
  -F "file=@rechnung.pdf"

• POST/api/v1/invoicesTudo em um: dados de pagamento + QR, para PDF também o PDF carimbado.
• POST/api/v1/extractExtrair apenas os dados de pagamento (sem QR, sem carimbo).
• POST/api/v1/qrSó QR — a partir de dados de pagamento (sem extração) ou de um documento.
• POST/api/v1/stampCarimbar o GiroCode num PDF.
• GET/api/v1/balanceConsultar saldo de tokens, limiar de aviso e pacotes (grátis).
• POST/api/v1/checkoutCriar um link Stripe diretamente pagável para um pacote de tokens.

Todos os parâmetros, formatos de resposta e códigos de erro — com «try it out» diretamente no browser: Abrir a referência interativa da API

MCP (Model Context Protocol) é o padrão aberto com que os agentes de IA (p. ex., Claude) usam ferramentas externas. O nosso servidor MCP entrega o GiroSnap ao teu agente como caixa de ferramentas: fotografa uma fatura, chama uma ferramenta e recebe o GiroCode ou o PDF carimbado diretamente no seu fluxo.

O caminho mais fácil — Claude (web e desktop): Definições → Conectores → «Adicionar conector personalizado», chama-lhe «GiroSnap» e cola este URL com a tua chave. Deixa os campos OAuth vazios:

https://www.girosnap.eu/api/mcp?key=GIROSNAP_API_KEY

Este URL contém a tua chave API — trata-o como uma palavra-passe e não o partilhes.

Ligação: indica o URL do servidor e passa a tua chave API no cabeçalho Authorization — a mesma configuração funciona no Claude, em agentes de IDE e nos teus próprios agentes SDK:

{
  "mcpServers": {
    "girosnap": {
      "type": "http",
      "url": "https://www.girosnap.eu/api/mcp",
      "headers": {
        "Authorization": "Bearer gsk_live_..."
      }
    }
  }
}

GIROSNAP_API_KEY é a tua chave gsk_live_ normal da app — não há uma chave MCP separada.

As ferramentas em detalhe

• extract_invoice1 token/página

  Lê beneficiário, IBAN, BIC, montante (em cêntimos) e referência a partir de uma foto de fatura ou de um PDF. Só é preciso se o teu agente não puder ou não dever ler a fatura sozinho.

• create_payment_qr1 token/página

  Gera o EPC/GiroCode lível por scan — como imagem, SVG e payload em bruto. Aceita dados de pagamento prontos (caminho mais rápido, sem extração) ou um documento.

• stamp_invoice_pdf1 token/página

  Carimba o GiroCode na fatura PDF — em espaço livre ou numa página acrescentada; PDF assinados e e-faturas ficam intactos e recebem uma folha de acompanhamento.

• get_token_balancegrátis

  Saldo de tokens atual, indicador de limiar, lista de pacotes e link de carregamento.

• buy_tokensgrátis

  Cria um link Stripe Checkout diretamente pagável para um pacote de tokens — os tokens são creditados automaticamente após o pagamento.

Truque: se o teu agente já conhece os dados de pagamento (afinal, viu a fatura), passa-os simplesmente como payment a create_payment_qr ou stamp_invoice_pdf — do nosso lado não corre nenhuma extração e a resposta é a mais rápida.

Envia faturas simplesmente por email — sem qualquer código. A fotos respondemos com o GiroCode no corpo; os PDF voltam carimbados em anexo, mesmo vários por email.

1. Regista o teu endereço de remetente na app em «API e integrações».
2. Clica no link de confirmação no email — feito.
3. Envia faturas (PDF, JPG, PNG, WEBP) para o endereço de processamento e aguarda a resposta.

Até 10 anexos por email, 12 MB cada. A resposta indica sempre os tokens cobrados e restantes; quando o saldo fica curto, o link de carregamento vai incluído.

A própria app é a quarta porta: carregar, rever, carimbar — diretamente no browser. E seja qual for a porta por onde uma fatura entra: tudo fica registado no teu histórico, com QR, PDF e custos consultáveis a qualquer momento.

Uma regra, em todo o lado: 1 token por página (um QR a partir de dados prontos conta como uma página). Contas novas começam com 10 tokens grátis; carrega-se via Stripe — na app, via POST /api/v1/checkout ou com a ferramenta buy_tokens.

Quando o saldo fica curto, avisamos por email; a 0 o processamento pausa em todas as portas (nenhum serviço de IA é chamado) e cada resposta traz o link de carregamento.

Cobrança justa: se o processamento falhar do nosso lado, o token é devolvido. Se o modelo correu mas não conseguiu ler a fatura, fica gasto.

Todos os erros usam o mesmo envelope — um code legível por máquina, uma message compreensível e, com tokens insuficientes (HTTP 402), o link de carregamento diretamente na resposta:

{
  "error": {
    "code": "insufficient_tokens",
    "message": "Not enough tokens for this operation.",
    "needed": 3,
    "balance": 1,
    "checkoutUrl": "https://www.girosnap.eu/app?screen=tokens"
  }
}

Códigos importantes: insufficient_tokens (402), unreadable (422, o modelo correu — token gasto), extraction_failed (502, devolvido), unsupported_media (415), file_too_large (413). Catálogo completo na referência interativa.