Como verificar programaticamente uma empresa polonesa (VAT, Lista Branca, KRS) — REST, Python, MCP

A verificação de um parceiro comercial na Polônia não é um capricho, mas sim um elemento de devida diligência — o status do VAT e a conformidade da conta com a Lista Branca impactam diretamente se você poderá contabilizar o custo e deduzir o VAT. O problema é que as fontes oficiais (Ministério das Finanças, Ministério da Justiça, GUS, Comissão Europeia) possuem APIs dispersas e diferentes entre si. Abaixo, mostro como reduzir isso a algumas chamadas HTTP que retornam JSON puro — a partir do curl, Python e um agente de IA que fala o protocolo MCP.

Todos os exemplos utilizam skanfirmy.pl — um conjunto de ferramentas para verificação de empresas por NIP/KRS/REGON e VAT europeu (VIES). Os dados vêm diretamente dos registros oficiais, os endpoints são gratuitos e sem registro (sem chave API), e a camada web funciona do lado do cliente, sem rastreamento.

Camada REST: um GET, um JSON

O caso mais simples — verificação do NIP. O endpoint é público, o método é GET, e a resposta é JSON:

curl https://skanfirmy.pl/nip/5260250995

Na resposta, você receberá, entre outras informações, o status do VAT (ativo/isento/não registrado), dados da entidade do Registro VAT e contas listadas na Lista Branca. Caminhos disponíveis:

• GET /nip/{nip} — status do VAT e dados da Lista Branca para um único NIP
• GET /nips/{lista} — vários NIPs de uma vez (lista separada por vírgulas)
• GET /regon/{nip} — dados do registro REGON (GUS)
• GET /vies/{country}/{number} — validação do número VAT europeu (por exemplo, /vies/DE/811128135)

Como é um simples GET retornando JSON, ele se integra sem cerimônia em qualquer pipeline — cron, função serverless, hook em CI, qualquer coisa que consiga fazer uma requisição HTTP.

Python: verificação no código

Com a biblioteca requests, tudo se resume a algumas linhas. Abaixo, uma função mínima que verifica o status do VAT e sinaliza uma exceção quando a entidade não é um contribuinte ativo:

import requests

def verifica_vat(nip: str) -> dict:
    r = requests.get(f"https://skanfirmy.pl/nip/{nip}", timeout=10)
    r.raise_for_status()
    dados = r.json()
    status = dados.get("vatStatus") or dados.get("status")
    if status != "Ativo":
        raise ValueError(f"NIP {nip}: status VAT = {status!r}")
    return dados

resultado = verifica_vat("5260250995")
print("Contas na Lista Branca:", resultado.get("accountNumbers", []))

Uma observação sobre boas práticas: trate os literais retornados pelos registros MF ("Ativo", "Isento") como valores canônicos — compare-se ao original e deixe qualquer tradução apenas para a camada de apresentação. Isso garante que a lógica não se desvie com a mudança do idioma da interface.

Tem muitos NIPs para processar em massa? Para um batch único com exportação CSV/JSON, existe a versão web /bulk, e programaticamente você alcançará o mesmo efeito através de GET /nips/{lista}.

MCP: o mesmo para o agente de IA

Aqui a coisa fica interessante. O diferencial chave do skanfirmy.pl é a total disponibilidade para agentes: em https://skanfirmy.pl/mcp está um servidor Model Context Protocol com 9 ferramentas — também sem chave API. Um agente (por exemplo, um assistente contábil) pode chamar a verificação do NIP da mesma forma que um humano clica no formulário.

O MCP fala JSON-RPC 2.0 através de POST. A chamada de uma ferramenta específica é feita pelo método tools/call:

curl -X POST https://skanfirmy.pl/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "verifica_nip",
      "arguments": { "nip": "5260250995" }
    }
  }'

A lista de ferramentas com seus esquemas de entrada será retornada por tools/list (o mesmo envelope, outro method). Para agentes que preferem REST puro, ainda existe https://skanfirmy.pl/llms.txt — um mapa de endpoints e formas de uso em um formato legível para modelos. Se você quiser ir além dos registros poloneses, dê uma olhada no serviço irmão otwarteapi.pl — um catálogo de APIs públicas (polonesas e mundiais) voltadas para agentes de IA.

Além da verificação única: monitoramento e webhook

O status do VAT de um parceiro ou sua conta na Lista Branca pode mudar de um dia para o outro — e uma verificação única não capturará isso. Portanto, existe /monitoring: alertas diários sobre mudanças no status do VAT ou na conta, com notificação push através de webhook assinado com HMAC. Na prática, você conecta um endpoint em seu sistema, verifica a assinatura do cabeçalho e reage — sem consultar os registros em um loop.

Versão EN

Todo o serviço é bilíngue. As versões em inglês correspondem aos textos em polonês.