API de integração: envie as vendas do seu programa ao TicketBAI e ao Vectura
O seu software —um POS de outra marca, um quiosque, uma loja online, um ERP ou o programa de um hotel— envia cada venda ao Vectura com uma chamada JSON. O Vectura emite o talão ou a fatura, assina-a com TicketBAI ou Veri*Factu, envia-a à administração fiscal e devolve-lhe o QR para imprimir. Sem bibliotecas, sem instalar nada e com uma chave por programa.
Conta de demonstração
Dados fictícios, sem envios à Autoridade Tributária nem por e-mail. Reposta todas as noites.
{
"seriefactura": "KIOSKO1",
"numfactura": "105",
"fechaexpedicionfactura": "2026-11-06",
"importetotalfactura": "3,50",
"baseimponible": "2,89",
"tipoimpositivo": "21",
"cuotaimpuesto": "0,61"
}
{
"error": "0",
"leyenda": "TicketBAI",
"fiscal_estado": "aceptado",
"qr_url": "https://batuz.eus/QRTBAI/?id=…"
}
Integrar é assim tão simples
Gere uma chave
Na sua área de utilizador, em Configuração → API e integrações, cria uma chave para cada programa. Pode ser eliminada a qualquer momento.
Envie a venda
O seu programa faz um POST com o JSON da venda. Sem NIF sai um talão simplificado; com NIF, uma fatura completa.
Imprima o QR
O Vectura assina e envia à administração fiscal, e responde com o QR e a legenda para imprimir no talão.
O que inclui
Uma chamada por venda
O seu programa envia um JSON com o NIF (opcional), o montante e o IVA. Sem NIF emite-se um talão simplificado; com NIF, uma fatura completa a esse cliente.
Assinatura e envio à administração fiscal
O Vectura assina com o seu certificado e envia à «Hacienda Foral» (TicketBAI em Biscaia, Guipúscoa e Álava) ou à Agência Tributária espanhola (Veri*Factu no resto de Espanha).
O QR, pronto a imprimir
A resposta traz o endereço do QR e a sua legenda (TicketBAI ou VERI*FACTU), e pode pedir ao Vectura a imagem do QR.
Repetições seguras e a sua numeração
Respeitamos a série e o número do seu programa. Se repetir uma venda com a mesma série e o mesmo número, o Vectura devolve a original sem criar outra: uma falha de rede nunca duplica uma fatura.
Anular, consultar e retificar
Anule um talão, consulte o estado fiscal de uma venda ou corrija uma fatura com uma fatura retificativa, tudo pela mesma API.
Faturas completas, cobranças e orçamentos
Com linhas, vários tipos de IVA, cliente, cobrança e envio do PDF por e-mail; faturas pendentes de cobrança, orçamentos e consulta de documentos.
Para programas que só deixam ficheiros
Se o seu software não sabe fazer chamadas web, um script do PowerShell envia sozinho os ficheiros JSON de uma pasta e escreve a resposta com o QR. Sem programar.
Manual e chaves na sua área de utilizador
Gere uma chave por programa e consulte o manual da API, com exemplos em curl, PHP, C#, JavaScript e Python e a lista de erros.
Perguntas frequentes
De que preciso para começar?
Uma conta do Vectura Suite e os dados fiscais da sua empresa. Para assinar a sério é preciso o seu certificado eletrónico (e, com TicketBAI, a licença de software, que o nosso suporte configura). Enquanto testa, a empresa está em modo de teste.
Funciona com TicketBAI e Veri*Factu?
Sim. Consoante o regime da sua empresa, o Vectura assina com TicketBAI (Biscaia, Guipúscoa e Álava) ou gera o registo Veri*Factu; o programa que chama não precisa de os distinguir.
Posso testar sem enviar nada à administração fiscal?
Sim. Enquanto a empresa está em modo de teste, tudo é assinado e enviado para o ambiente de teste da administração fiscal e os QR não têm validade legal. Quando tudo funciona, passa-se a real.
O que acontece se a ligação se cortar a meio de uma venda?
Tenta de novo com a mesma série e o mesmo número (ou a mesma referência): o Vectura devolve a venda original sem a duplicar.
Há um limite de chamadas?
Sim: 120 pedidos por minuto, mais do que suficiente para uma loja. Se exceder, a API responde 429 e tenta de novo passado um momento.
Onde está a documentação?
Dentro do Vectura Suite, na sua área de utilizador: Ajuda → Manual da API. Inclui um guia de início, cada ponto da API com exemplos em curl, PHP, C#, JavaScript e Python, e a lista de erros. Pode consultá-lo com o teste gratuito.
Quem vê a minha chave?
Ninguém: é mostrada uma única vez ao criá-la e o Vectura só guarda uma impressão digital. Se a perder, elimine-a e crie outra; eliminar uma chave não afeta as outras.
Posso ligar o programa de um hotel?
Sim: além das vendas, há pontos da API para quartos ocupados e cobranças ao quarto, que o programa do hotel consulta e liquida.
Vamos testá-lo com o seu negócio?
Crie a sua conta e experimente com os seus próprios dados, sem cartão e sem compromisso.