#GoFile API Connect

O que é a API Connect?

Um portal de conformidade para a declaração de impostos no Reino Unido: seu software se conecta a um ponto de contato com o cliente e seus dados, e # GoFile cuida de tudo entre essa conexão e o recebimento pela HMRC .

A implementação do Making Tax Digital não é uma API simples de se chamar uma vez. É uma API complexa de se implementar continuamente. terReconhecimento, concessões OAuth que expiram após 18 meses, cabeçalhos de prevenção de fraudes que devem descrever o dispositivo de origem real, correspondência de obrigações, chaves de período que você nunca deve inventar, idempotência de envio e uma trilha de auditoria que permanece válida por anos — esse é o trabalho, e ele nunca termina.

A API Connect realiza esse trabalho, sendo executada e mantida por trás de uma pequena interface REST. A versão 1 abrange CUBAVerificar se um cliente está autorizado, analisar sua situação completa em relação ao IVA, preencher a declaração e acompanhar todo o processo até a emissão do recibo.

Para quem é?

A API foi projetada para um modelo de agente: sua empresa parceira conecta seu HMRC Receita e Alfândega do Reino Unido). conta de serviços de agente uma única autorização abrange todos os clientes para os quais a empresa está autorizada a atuar.

Como funciona

Cada requisição é uma chamada REST assinada. Tudo que legalmente exige intervenção humana acontece em uma página que hospedamos.

GET /api/v1/vat/193054661/status

{
  "vat_number": "193054661",
  "mode": "live",
  "obligations": {
    "open": [
      { "period": { "start": "2026-04-01",
                    "end":   "2026-06-30" },
        "due": "2026-08-07",
        "overdue": false }
    ],
    "fulfilled": [ /* filed periods + figures */ ]
  }
}

{
  "external_client_id": "CLIENT-91827",
  "client_name": "Acme Trading Ltd",
  "vat_number": "193054661",
  "return": {
    "vat_due_sales": "12500.00",
    "total_vat_due": "12500.00",
    "net_vat_due":   "8300.00"
    /* ...nine boxes in total */
  }
}

{
  "id": "vfs_...",
  "status": "submitted",
  "receipt": {
    "gofile_reference": "GF-VAT-123",
    "form_bundle": "258868935084"
  }
}

A aprovação hospedada — e por que ela é importante

HMRC não quer apenas uma declaração; ela quer saber se a declaração foi feita por uma pessoa real em um dispositivo real e se um ser humano assumiu a responsabilidade pela declaração. É para isso que servem os cabeçalhos de prevenção de fraudes, e erros neles representam um problema de conformidade, não um bug.

Portanto, a API Connect nunca pede ao seu software para falsificá-los. Quando você publica um documento, retornamos um URL para uma página. nós hospedamosNessa página, a pessoa autorizada faz login com autenticação de dois fatores, seu dispositivo real é capturado, a declaração é exibida na íntegra e ela confirma a declaração. Só então entramos em contato com HMRC — com cabeçalhos gerados a partir desse dispositivo específico, capturados junto com a declaração como comprovante.

A página também orienta o seu cliente durante a conexão única HMRC . Quando uma empresa faz a declaração pela primeira vez, ela autoriza a sua conta de serviços de agente nessa página e retorna diretamente para o processo de declaração.

O que você não precisa construir

Você nunca será solicitado a fornecer uma chave de ponto final ou um finalised sinalizador — a API os rejeita completamente, porque cabe a nós determiná-los, e errar neles é o que causa problemas nos registros.

Sandbox e ao vivo

Os modos são escolhidos pela chave que você usa para assinar, portanto, não há nenhuma opção global para ativar nem nada para esquecer durante a implantação:

• gfk_sandbox_… Arquivo de chaves para o ambiente de teste da HMRC . Gratuito, ilimitado e seguro para executar em CI.
• gfk_live_… As chaves arquivam retornos reais.

Ambos funcionam simultaneamente. Seu conjunto de testes pode ser executado no ambiente de sandbox enquanto os arquivos de produção estão ativos, e a troca entre eles depende da credencial utilizada para login. O uso, os registros de requisições e os limites diários são monitorados separadamente para cada modo.

Segurança e provas

A rotação não exige tempo de inatividade: várias chaves podem estar ativas simultaneamente, então você emite o novo par, o implementa e revoga o antigo assim que nada for assinado com ele.

Webhooks, registros e o portal do desenvolvedor

O processo de envio de documentos é assíncrono por natureza — um humano precisa aprovar e HMRC precisa responder. Em vez de fazer você consultar o sistema repetidamente, enviamos eventos assinados para o seu endpoint à medida que o processo avança: aguardando aprovação, enviado, reprovado e outros. Cada entrega é assinada pelo HMAC com a sua chave secreta do webhook, para que você possa verificar se ela foi enviada por nós.

O portal de parceiros em api.gofile.co.uk oferece à sua equipe:

• Chaves de API — emitir pares de sandbox e produção, ver o último uso, rotacionar e revogar.
• Registros de solicitações — cada requisição assinada com seu status, código de erro, modo, duração e ID da requisição. Falhas de assinatura também aparecem, que é exatamente o que você precisa quando está errando o HMAC às 2 da manhã.
• Entregas via Webhook — status, código de resposta e cronograma de novas tentativas por evento.
• Uso — solicitações e registros organizados por dia e divididos por modalidade.
• Cobrança — faturas, métodos de pagamento e seu plano.

Preços

Os preços não incluem IVA. As taxas de declaração serão adicionadas à sua próxima fatura mensal. Sem taxas por cliente, sem volume mínimo e sem custos para declaração em ambiente de teste — você só paga quando uma declaração real chegar à HMRC .

O que vem a seguir?

A versão 1 refere-se ao IVA, pois é onde MTD é obrigatório e o volume é mais elevado. O mesmo modelo — uma chamada simples, uma aprovação online e um recibo — foi concebido para ser estendido ao restante das obrigações fiscais no Reino Unido.

MTD para Imposto de Renda é a próxima etapa natural, e é onde o valor de uma API simplificada é maior: a própria interface ITSA da HMRC abrange um grande número de endpoints e formatos, e pretendemos condensar tudo isso na mesma interface racional que o Connect oferece para o IVA. Se o seu planejamento depende de um imposto ou cronograma específico, conte-nos — A demanda do parceiro determina a ordem.

Comece agora