Ziptax Sales Tax API

Para Markdown limpo de qualquer página, acrescente .md ao final da URL da página. Para um índice completo da documentação, consulte https://docs.zip.tax/llms.txt. Para integração com clientes de IA (Claude Code, Cursor, etc.), conecte-se ao servidor MCP em https://docs.zip.tax/_mcp/server.

Servidor MCP

O Servidor MCP da Ziptax dá a agentes de IA e aplicações baseadas em LLM acesso direto a dados de imposto sobre vendas em tempo real dos EUA e do Canadá. MCP é um padrão aberto que permite que aplicações de IA se conectem com segurança a ferramentas externas e fontes de dados. Uma vez conectado, seu agente pode:

• Consultar alíquotas de imposto sobre vendas e uso por código postal, endereço ou coordenadas geográficas.
• Recuperar detalhamentos de impostos por jurisdição (estadual, municipal, distrital).
• Consultar métricas de uso da conta e informações de cota.

Info

Você precisará de uma chave de API Ziptax válida. Crie uma conta gratuita em platform.zip.tax.

Detalhes da conexão

URL base	https://mcp.zip-tax.com/
Método	POST
Transporte	HTTP Streamable (a maioria dos clientes chama isso de HTTP)

Autenticação

Toda solicitação deve incluir uma chave de API válida enviada como cabeçalho HTTP. Dois métodos de cabeçalho são suportados.

Cabeçalho X-API-KEY (recomendado)

X-API-KEY: your-api-key

Cabeçalho Authorization

Authorization: Bearer your-api-key

Aviso

Se ambos estiverem presentes, o cabeçalho X-API-KEY tem prioridade. Não passe sua chave de API como parâmetro de URL; chaves em URLs podem acabar em logs.

Ferramentas

O servidor expõe duas ferramentas.

lookup_tax_rate

Consulte alíquotas de imposto sobre vendas e uso para um local nos EUA ou no Canadá. Forneça um endereço completo para precisão ao nível da porta, ou um par lat/lng para uma consulta por ponto geográfico. Retorna alíquotas detalhadas por jurisdição (estadual, municipal, distrital).

Parâmetros

Forneça address para uma consulta ao nível da porta, ou lat e lng para uma consulta por ponto geográfico. O esquema de entrada declara esse requisito como uma restrição anyOf.

Exemplo de resposta

A resposta da ferramenta espelha a resposta da REST API por Endereço da Ziptax:

{
  "metadata": {
    "version": "v60",
    "response": {
      "code": 100,
      "name": "RESPONSE_CODE_SUCCESS",
      "message": "Successful API Request.",
      "definition": "http://api.zip-tax.com/request/v60/schema"
    }
  },
  "baseRates": [
    {
      "rate": 0.0725,
      "jurType": "US_STATE_SALES_TAX",
      "jurName": "CA",
      "jurDescription": "US State Sales Tax",
      "jurTaxCode": "06"
    },
    {
      "rate": 0.005,
      "jurType": "US_COUNTY_SALES_TAX",
      "jurName": "ORANGE",
      "jurDescription": "US County Sales Tax",
      "jurTaxCode": "30"
    }
  ],
  "taxSummaries": [
    {
      "rate": 0.0775,
      "taxType": "SALES_TAX",
      "summaryName": "Total Base Sales Tax",
      "displayRates": [
        { "name": "Total Rate", "rate": 0.0775 }
      ]
    }
  ],
  "addressDetail": {
    "normalizedAddress": "200 Spectrum Center Dr, Irvine, CA 92618-5003, United States",
    "incorporated": "true",
    "geoLat": 33.65253,
    "geoLng": -117.74794
  }
}

get_account_metrics

Recupere métricas de uso da conta e informações de cota para sua conta Ziptax. Retorna contagens atuais de solicitações, limites e direitos. Não aceita parâmetros.

Exemplos de casos de uso

Uma vez conectado, pergunte ao seu agente coisas como:

• "Qual é a alíquota de imposto sobre vendas para o código postal 90210?"
• "Qual é a alíquota combinada de imposto sobre vendas em 200 Spectrum Center Dr, Irvine, CA?"
• "Qual é a alíquota de imposto sobre vendas para o código postal canadense M5V 2T6 em Toronto, Ontário?"
• "Qual foi a alíquota de imposto sobre vendas em Nashville, TN (37203) em janeiro deste ano?"
• "Quantas solicitações de API restam no meu plano Ziptax este mês?"

Configuração do cliente

Abaixo estão exemplos de configuração para conectar clientes MCP populares ao Servidor MCP da Ziptax. Substitua your_api_key pela sua chave de API Ziptax de platform.zip.tax.

Claude Desktop

Adicione este bloco ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "ziptax": {
      "type": "http",
      "url": "https://mcp.zip-tax.com/",
      "headers": {
        "X-API-KEY": "your_api_key"
      }
    }
  }
}

Cursor

Navegue até Configurações → MCP e adicione um novo servidor com:

• Nome: Servidor MCP da Ziptax
• Tipo: HTTP
• URL: https://mcp.zip-tax.com/
• Cabeçalhos: X-API-KEY: your_api_key

Devin

No Devin, adicione a integração MCP da Ziptax no MCP Marketplace, ou configure-a manualmente em Configurações → MCP Marketplace → Adicionar o Seu:

{
  "mcpServers": {
    "ziptax-sales-tax-api": {
      "transport": "shttp",
      "url": "https://mcp.zip-tax.com/",
      "headers": {
        "X-API-KEY": "$ZIPTAX_API_KEY"
      }
    }
  }
}

Armazene sua chave de API como um segredo chamado ZIPTAX_API_KEY no Gerenciador de Segredos do Devin.

Cliente MCP genérico

Qualquer cliente MCP que suporte transporte HTTP Streamable pode se conectar:

• Nome: Servidor MCP da Ziptax
• Tipo: HTTP
• URL: https://mcp.zip-tax.com/
• Cabeçalhos: X-API-KEY: your_api_key

Tratamento de erros

Quando uma solicitação falha, o Servidor MCP retorna uma mensagem de erro no resultado da ferramenta. Para a lista completa de códigos de resposta da API, consulte a referência de Códigos de Resposta.