PostalForm MCP

Envie cartas reais de agentes: PDF → checkout → status.

Ver em postalform.comExperimente este MCPPatrocinado

Documentação

API de Correio e Servidor MCP Remoto para Agentes de IA

PostalForm é uma API de correio e servidor MCP remoto para transformar PDFs, cartas, formulários e saídas de agentes em correspondência postal física real. Desenvolvedores podem criar rascunhos de correio revisáveis, sessões de checkout hospedadas, pedidos de máquina diretos MPP/x402 e consultas de status de fulfillment sem construir infraestrutura de impressão, envelope, postagem ou entrega à transportadora.

Quando o agente não possui carteira de pagamento compatível

Pedidos de máquina comuns de PDF, carta, formulário, cartão postal e volume retornam um checkout_url, status_url, payment_options e next_action assinados junto com o desafio 402. As ferramentas de rascunho MPP também retornam checkout_url. O documento, ID do pedido, contagem de páginas e total permanecem os mesmos independentemente da opção de pagamento que o comprador escolher. O checkout hospedado é uma alternativa ao MPP/x402, não um tipo de credencial MPP. Essa alternativa não se aplica às APIs separadas de flores ou etiquetas de envio.

  1. Revise o preview_url (ou o campaign_url em volume), destinatários e total com o comprador. Preserve um documento enviado; não recrie seu conteúdo como uma carta para contornar um problema de upload.
  2. Se o runtime puder realmente obter uma credencial compatível aprovada, responda a um desafio de máquina. Uma conta Link conectada por si só não estabelece que o runtime pode emitir um SPT. O Link suporta integrações distintas de cartão virtual, SPT e Link Pay Token; use a capacidade que o runtime expõe.
  3. Caso contrário, apresente o checkout_url retornado. Abri-lo apenas revisa o pedido. Continuar abre o Checkout hospedado pela Stripe e reserva o pagamento hospedado para este pedido; chamadas de máquina subsequentes retornam a mesma opção de checkout. Nenhuma configuração de carteira ou instalação de CLI é necessária para o comprador.
  4. Consulte status_url ou postalform.get_order_status. payment_authorized significa que o cartão foi autorizado mesmo enquanto is_paid é falso. payment_processing e settled_pending_webhook também significam aguardar, não pagar novamente. payment_review_required precisa de reconciliação de suporte; closed não pode ser pago. Use os campos de fulfillment/rastreamento para distinguir impressão, envio e entrega.

Os links de checkout expiram após 24 horas; consulte o mesmo pedido para obter um link novo. Inícios simultâneos de checkout reutilizam uma sessão. Uma credencial rejeitada antes do pagamento (por exemplo, uma prova malformada ou desafio expirado) deixa o mesmo pedido pagável com uma credencial corrigida ou checkout hospedado. Após um pagamento de máquina interrompido, repita a mesma credencial e solicitação ou consulte: uma credencial ou caminho de pagamento diferente é bloqueado enquanto o resultado for incerto. Uma resposta 402 por si só não prova que uma tentativa anterior falhou; uma rejeição posterior não desbloqueia um pagamento incerto. Siga as opções de pagamento e status retornados. Um pagamento atrasado que chega fora do checkout selecionado é retido para reconciliação e não dispara outro envio.

Sem conexão MCP nativa? Use os endpoints HTTP de criação e status em OpenAPI. Não mude para upload via navegador apenas porque o runtime não pode anexar um servidor MCP remoto. Consulte a documentação de integração Link da Stripe para aprovação de propriedade do agente e recuperação de credenciais; a PostalForm não emite credenciais a partir da conta Link de um usuário.

Resposta rápida: desenvolvedores podem enviar correspondência postal por meio de uma API?

Sim. Use PostalForm Projects quando seu servidor precisar de chaves de API persistentes, um ambiente de teste gratuito, cotações de preço final, criação de pedidos idempotente e webhooks assinados. Use as ferramentas de rascunho do MCP remoto e checkout hospedado quando uma pessoa deve revisar o PDF, endereços, opções de envio e preço antes do pagamento. Use fluxos de pagamento de máquina diretos MPP ou x402 apenas para runtimes autônomos com aprovação explícita do proprietário, limites de gastos e IDs de solicitação idempotentes.

Intenção do desenvolvedorCaminho PostalFormMelhor padrão
Adicionar uma API de correio persistente a um aplicativoUse a API de correio para desenvolvedores PostalForm ProjectsComece no modo de teste gratuito com uma chave de API do projeto
Deixar um agente de IA preparar correspondência físicaConecte-se ao endpoint MCP remoto em https://postalform.com/mcpCrie um rascunho de checkout hospedado
Deixar ChatGPT, Claude, Gemini, Cursor ou Codex usar ferramentas de correioRegistre PostalForm como um servidor MCP HTTP remoto transmissívelExija aprovação para efeitos colaterais de correio
Deixar um runtime autônomo pagar por correioUse postalform.create_machine_order, MPP ou x402Limite de gastos aprovado pelo proprietário mais revisão de prévia
Listar PostalForm em um registro MCP ou de agentesUse o cartão do servidor MCP, manifesto de registro e esta página de desenvolvedorEnvie as URLs canônicas hospedadas pela PostalForm

Resumo pronto para diretório

Use esta tabela ao avaliar PostalForm para um registro MCP, diretório de agentes, catálogo de API, revisão de conectores ou listagem de ferramentas de desenvolvedor.

Campo do diretórioValor PostalForm
Tipo de produtoAPI de correio físico e servidor MCP remoto
Endpoint principalhttps://postalform.com/mcp
TransporteMCP HTTP transmissível
Padrão revisado por humanosAs ferramentas de rascunho de checkout hospedado criam um rascunho não pago e URL de checkout para revisão antes do pagamento
Caminho com capacidade de pagamentoTodo rascunho de PDF, carta e formulário pode selecionar MPP e usar postalform.pay_order após aprovação; postalform.create_machine_order também suporta x402
URLs de descoberta sem autenticação/openapi.json, /apis.json, /.well-known/mcp/server.json, /.well-known/mcp/server-card.json, /.well-known/mcp.json, /.well-known/agent-card.json, /.well-known/x402
Melhor destino de listagemhttps://postalform.com/developers para catálogos de API/MCP; https://postalform.com/agents para diretórios de agentes
Principais casos de usoEnviar PDFs, cartas, documentos gerados, formulários de fluxo de trabalho, pacotes de disputa, avisos de pagamento e verificações de status
Limite de efeitos colateraisA criação de rascunho não paga nem envia. O pagamento exige checkout hospedado, um token Stripe ou uma credencial MPP/x402
Política de aprovação recomendadaExija aprovação antes de compartilhar documentos, endereços, credenciais de pagamento ou enviar correio real

Descrição curta para diretório:

PostalForm is a remote MCP server and physical mail API for creating reviewable print-and-mail drafts from PDFs, letters, and forms, with hosted checkout, fulfillment status, and approved MPP/x402 machine-payment flows.

Qual superfície de integração você deve usar?

SuperfícieUse paraEvite quando
API REST PostalForm ProjectsAplicativos do lado do servidor que precisam de chaves de API do projeto, fulfillment simulado gratuito, cotações finais, créditos pré-pagos e webhooks assinadosUma pessoa deve aprovar cada documento e pagamento no checkout hospedado
Checkout hospedado via ferramentas de rascunho MCPAssistentes voltados ao usuário, clientes de chat web, ferramentas de suporte e fluxos de trabalho onde uma pessoa deve aprovar o pagamentoO agente já foi autorizado a pagar autonomamente
Sessão de checkout com token StripeClientes que podem obter um token de pagamento compartilhado Stripe aprovado pelo compradorO cliente não pode usar sessões de checkout ou tokens de pagamento compartilhados
API REST de pedido de máquina raizIntegrações MPP/x402 aprovadas que validam, pagam, repetem e consultam sem um espaço de trabalho ProjectsO usuário ainda precisa de uma etapa de aprovação visual antes do pagamento
Pagamento de máquina MPPRuntimes de agente que já suportam semântica de desafio/recibo MPP, Stripe Shared Payment Tokens ou credenciais de cartão-MPPFluxos simples voltados ao usuário onde o checkout hospedado é mais seguro
Pagamento de máquina x402Agentes e serviços nativos HTTP que podem responder a desafios 402 Payment RequiredFluxos de trabalho sem infraestrutura de carteira/pagamento ou controles de gastos
Endpoint MCP de checkout UCPPlataformas que integram especificamente a capacidade de checkout UCPRascunhos de endereço manual, texto de carta ou formulário de fluxo de trabalho que precisam das ferramentas MCP PostalForm

Etiquetas de envio de pacotes domésticos são um produto separado somente MPP. Use POST /api/machine/mpp/shipping-labels/validate para tarifas de transportadora ao vivo e depois POST /api/machine/mpp/shipping-labels para criar e pagar. A resposta paga e a página de conclusão expõem um download de PDF assinado; o e-mail de fulfillment inclui o anexo e o link do PDF. Consulte o guia de etiquetas de envio MPP.

Descoberta MCP remota

Use estas URLs canônicas ao listar PostalForm em diretórios MCP, catálogos de conectores ou registros de agentes:

O servidor MCP hospedado é melhor para clientes que podem se conectar a um endpoint MCP HTTP remoto transmissível. Use postalform.create_order_draft, postalform.create_letter_order_draft e postalform.create_form_order_draft para preparar um pedido para revisão do comprador, seguido por complete_checkout com um token de pagamento Stripe compatível ou pagamento pela URL de checkout hospedado. Para MPP, essas mesmas ferramentas de rascunho aceitam payment_protocol: "mpp" e buyer_email; use postalform.pay_order para pagar o pedido preparado após aprovação. postalform.create_machine_order também suporta MPP e x402.

Para o padrão de design por trás dessa divisão, consulte tornando o correio físico chamável por agentes de IA.

ChatGPT, Gemini e outros clientes MCP

O PostalForm está pronto para clientes que podem se conectar a servidores MCP remotos via HTTP streamable. O mesmo endpoint é usado por fluxos estilo conector personalizado do ChatGPT, ferramentas MCP da OpenAI Responses API, sessões MCP do Gemini SDK, Gemini CLI, Claude, Claude Code, Codex, Cursor, Windsurf, Cline, Replit, OpenClaw, Hermes, n8n, LangChain e clientes MCP similares.

Para integrações com ChatGPT ou OpenAI Responses API, configure o PostalForm como um servidor MCP remoto:

{
  "type": "mcp",
  "server_label": "postalform",
  "server_description": "Create real PostalForm mail drafts, hosted checkout sessions, machine-payment mail orders, and order status lookups.",
  "server_url": "https://postalform.com/mcp",
  "require_approval": "always"
}

Para o Gemini CLI, adicione o PostalForm como um servidor MCP HTTP:

gemini mcp add --transport http postalform https://postalform.com/mcp

Para os SDKs do Gemini, crie uma sessão de cliente MCP contra o endpoint do PostalForm e passe as ferramentas da sessão para a integração de chamada de ferramentas do Gemini. Deixe o usuário revisar o PDF, endereços, preço e opções de envio antes de pagar. Um cliente compatível pode então usar complete_checkout com um token Stripe aprovado pelo comprador; caso contrário, apresente o checkout hospedado.

UCP (Protocolo Universal de Comércio)

O PostalForm também suporta a capacidade de Checkout UCP para plataformas que integram via binding MCP do UCP.

As sessões de checkout UCP são precificadas dinamicamente com base na contagem de páginas do PDF e nas opções de impressão. O PostalForm espera os dados do PDF e endereço em metadata.postalform (o pdf pode ser { download_url, file_id }, { upload_token }, uma URL de dados ou uma URL HTTPS pública). As chamadas de ferramentas UCP devem incluir um perfil de plataforma em _meta.ucp.profile.

Nota: O UCP atualmente suporta checkouts baseados em PDF com IDs de Endereço Loqate (*_address_type="Address") apenas. Para endereços manuais, texto de carta e formulários de fluxo de trabalho, use as ferramentas MCP do PostalForm em /mcp.

Exemplo de create_checkout UCP:

{
  "name": "create_checkout",
  "arguments": {
    "_meta": {
      "ucp": {
        "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
      }
    },
    "currency": "USD",
    "line_items": [{ "item": { "id": "postalform_mail_pdf_bw_double" }, "quantity": 1 }],
    "payment": {},
    "metadata": {
      "postalform": {
        "pdf": {
          "download_url": "https://example.oaiusercontent.com/file.pdf",
          "file_id": "file_abc123"
        },
        "file_name": "letter.pdf",
        "sender_name": "Sender Example",
        "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
        "sender_address_type": "Address",
        "sender_address_text": "123 Sender St, Springfield, IL 62701",
        "recipient_name": "Recipient Example",
        "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
        "recipient_address_type": "Address",
        "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
        "double_sided": true,
        "color": false
      }
    }
  }
}

Pagamentos de máquina (x402)

O PostalForm suporta pagamentos de máquina baseados em x402 para criação direta de pedidos via API. Os endpoints de pagamento de máquina são projetados para runtimes de agentes que podem não ter login ou chave de API do PostalForm: a chamada create não paga retorna um desafio de pagamento, e a nova tentativa paga autoriza o pedido. Payloads de carta podem ser texto puro, HTML, Markdown ou RTF e podem incluir assinaturas digitadas ou desenhadas; o PostalForm renderiza o PDF no servidor e pode retornar uma URL de pré-visualização assinada antes do pagamento.

Para uma visão geral amigável a crawlers do fluxo de correio físico x402, campos de diretório e padrões de segurança, veja API de correio físico x402.

  • Endpoint create/pay: POST https://postalform.com/api/machine/orders
  • Endpoint validate/quote (sem efeitos colaterais de pagamento): POST https://postalform.com/api/machine/orders/validate
  • Endpoint de status: GET https://postalform.com/api/machine/orders/:id
  • Fluxo: solicitação não paga retorna 402 + PAYMENT-REQUIRED, o cliente paga e tenta novamente com PAYMENT-SIGNATURE, o servidor retorna 202 + PAYMENT-RESPONSE; settled_pending_webhook significa que o Stripe ainda está verificando a liquidação, então consulte o endpoint de status em vez de pagar novamente
  • O corpo 402 repete o desafio decodificado como payment.payment_required. /api/machine/* permite solicitações de navegador de origem cruzada e expõe PAYMENT-REQUIRED, PAYMENT-RESPONSE e WWW-Authenticate. Apenas x402 v2 (PAYMENT-SIGNATURE) é aceito, não o cabeçalho v1 X-PAYMENT

Campos de solicitação obrigatórios para POST /api/machine/orders:

  • request_id (UUID)
  • buyer_name
  • buyer_email (obrigatório; definido no Stripe PaymentIntent como receipt_email)
  • exatamente uma fonte de documento:
    • pdf (formato canônico recomendado: { "upload_token": "..." }; também aceita { download_url, file_id }, URL de dados ou URL HTTPS pública)
    • letter (string bruta ou objeto com format definido como text, html, markdown ou rtf; signature opcional como string ou { mode: "typed" | "drawn", text?, dataUrl?, printDataUrl? }; o PostalForm renderiza o PDF no servidor)
    • form (payload de formulário de fluxo de trabalho de peça única descoberto através dos endpoints de esquema de formulários de máquina; campos de assinatura aceitam payloads de assinatura digitada ou desenhada quando presentes; fluxos de trabalho estatutários de múltiplos destinatários são excluídos e permanecem apenas na web)
  • nomes e endereços do remetente/destinatário (Loqate: *_address_type="Address" + *_address_id + *_address_text, ou Manual: *_address_type="Manual" + *_address_manual com { line1, line2?, city, state?, zip, countryCode? }; countryCode padrão é US; ambos os modos de endereço aceitam apenas os códigos de país suportados pelo checkout US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU e NL)

Opções comuns:

  • double_sided (padrão true)
  • color (padrão false)
  • mail_class (standard, priority, express)
  • certified (padrão false)
  • certified_return_receipt (padrão false; adiciona um aviso de recebimento para Correio Certificado dos EUA; ignorado para correio registrado PinGen)
  • return_receipt_format (electronic por padrão, ou physical para o cartão verde PS Form 3811 enviado; requer certified_return_receipt=true)
  • restricted_delivery (padrão false; solicita Entrega Restrita USPS somente ao destinatário e requer certified_return_receipt=true)
  • err_delivery (manual por padrão, ou email para que o PostalForm adquira e envie por e-mail o recibo eletrônico assinado)
  • err_email (substituição opcional para entrega automática; padrão buyer_email quando omitido)
  • signature_required (padrão false; solicita assinatura na entrega USPS; ignorado para cartões-postais ou quando mail_class="standard")
  • mailpiece_type (letter ou postcard; padrão letter)
  • postcard_size (4x6, 6x9, 11x6; obrigatório quando mailpiece_type="postcard")

Pedidos de máquina para cartões-postais usam os mesmos endpoints e fluxo de pagamento. Para cartões-postais, envie pdf como o PDF final do cartão-postal composto e defina mailpiece_type: "postcard" mais postcard_size.

Requisitos do PDF do cartão-postal:

  • Use um PDF de 2 páginas.
  • A página 1 é o lado da arte.
  • A página 2 é o lado do envio. Você pode colocar arte no verso ou uma mensagem sem endereço lá, mas não coloque nomes de remetente/destinatário, endereços de retorno ou entrega, indicia ou dados de código de barras no PDF. O PostalForm preenche o bloco de envio automaticamente.
  • Corresponda exatamente ao canvas de sangria para o tamanho selecionado. A especificação canônica e modelos estão em diretrizes de PDF para cartões-postais:
  • Cartões-postais internacionais roteados via Lob requerem postcard_size="4x6" e um endereço de remetente/retorno dos EUA. O PostalForm roteia cartões-postais internacionais maiores ou cartões-postais internacionais com endereços de retorno fora dos EUA para o PostGrid antes do envio ao provedor.

O PostalForm normaliza as opções de impressão de cartões-postais no servidor para correio padrão, cor total, frente e verso e sem complementos de certificado/assinatura.

Endpoint MCP

  • https://postalform.com/mcp
  • Métodos: POST/GET/DELETE com transporte HTTP streamable
  • Sessões: inicialize uma vez, depois inclua o cabeçalho mcp-session-id em todas as solicitações subsequentes
  • Autenticação: nenhuma autenticação é necessária hoje (entre em contato com support@postalform.com para allowlisting)
  • Transporte: payloads JSON-RPC via POST

Início rápido de integração

  1. Aponte seu cliente MCP para /mcp e inicialize uma sessão.
  2. Escolha endereços: use IDs Loqate via postalform.search_addresses, ou use endereços manuais com *_address_type="Manual" + *_address_manual (countryCode padrão é US).
  3. Crie um rascunho:
    • Texto de carta: postalform.create_letter_order_draft.
    • Formulários de fluxo de trabalho: postalform.list_forms -> postalform.get_form_schema -> postalform.create_form_order_draft.
    • Upload de PDF: postalform.create_order_draft (parâmetros de arquivo, upload_token, URL de dados ou URL HTTPS pública).
  4. Escolha o caminho de pagamento:
    • Clientes com token Stripe compatível: obtenha aprovação do comprador e chame complete_checkout com checkout_session.id, detalhes do comprador e o token. Caso contrário, envie o comprador para checkout_url.
    • Clientes com capacidade MPP: escolha payment_protocol: "mpp" e forneça buyer_email ao criar qualquer rascunho. Revise preview_url e price_usd, responda a um desafio MPP, então chame postalform.pay_order com apenas order_id e payment_authorization. create_machine_order permanece disponível para MPP e x402.
  5. Consulte o status do pedido conforme o cumprimento progride.
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(new URL('https://postalform.com/mcp'))
const client = new Client({ name: 'my-agent', version: '1.0.0' })

await client.connect(transport)
await client.listTools()

const draft = await client.callTool({
  name: 'postalform.create_letter_order_draft',
  arguments: {
    letter: {
      title: 'Demand for payment',
      body: 'Hello...\\n\\nThis is my letter body.\\n\\nSincerely,\\n',
      signature: 'Sender Example',
    },
    sender_name: 'Sender Example',
    sender_address_type: 'Manual',
    sender_address_manual: {
      line1: '123 Sender St',
      city: 'Springfield',
      state: 'IL',
      zip: '62701',
    },
    recipient_name: 'Recipient Example',
    recipient_address_type: 'Manual',
    recipient_address_manual: {
      line1: '456 Recipient Ave',
      city: 'Springfield',
      state: 'IL',
      zip: '62701',
    },
  },
})

console.log(draft.structuredContent?.checkout_url)

Pagamento e checkout

Checkout externo (qualquer cliente MCP)

  • Use checkout_url de postalform.create_order_draft para enviar clientes para a página de pagamento hospedada do PostalForm.
  • Melhor padrão para clientes MCP de chat em navegador ou qualquer fluxo onde uma pessoa deve revisar e pagar.
  • Abra a URL em um navegador (ou window.openai.openExternal dentro do ChatGPT).
  • Consulte postalform.get_order_status para confirmar pagamento e cumprimento.

Checkout com token Stripe (clientes agente compatíveis)

  • As ferramentas de rascunho retornam um checkout_session ACP contendo o ID do pedido preparado e o total.
  • Após o comprador aprovar o pedido e o total, chame complete_checkout com checkout_session_id, detalhes do comprador e um Token de Pagamento Compartilhado Stripe compatível (spt_..., provider=stripe). Nenhum reenvio de documento ou endereço é necessário.
  • O PostalForm confirma o PaymentIntent existente. Novas tentativas verificam seu estado atual e reutilizam o mesmo intent; confirmações usam uma chave de idempotência Stripe estável. Se nenhum intent existir, um intent não confirmado é salvo antes de qualquer tentativa de pagamento.
  • Repita uma chamada interrompida com o mesmo ID de checkout e token. Um resultado incerto é not_ready_for_payment com uma mensagem informativa, não uma recusa confirmada. Não crie outro pedido ou obtenha um token substituto enquanto o resultado estiver incerto.
  • completed significa que o checkout foi aceito, incluindo uma autorização aguardando captura. Siga postalform.get_order_status para pagamento e cumprimento; a conclusão do checkout não prova envio ou entrega. Pagamentos em processamento retornam not_ready_for_payment; autenticação adicional retorna requires_3ds; pagamentos cancelados retornam canceled. Uma recusa confirmada pode ser repetida com um token recém-autorizado no mesmo intent.
  • O suporte do cliente deve ser verificado: essas ferramentas não estabelecem que um assistente específico fornece o formato de token ou anexo necessário.
  • Widgets do ChatGPT podem usar window.openai.requestCheckout(checkout_session) quando disponível. Clientes sem checkout de token compatível devem apresentar checkout_url.

Pagamento direto de máquina (clientes MCP agênticos)

  • Para pagar um rascunho preparado via MPP, defina payment_protocol: "mpp" e buyer_email na criação e use postalform.pay_order após a aprovação. Use postalform.create_machine_order para a interface combinada de pedido de máquina MPP/x402.
  • Primeiro chame com payment_protocol="mpp" ou "x402" e sem credencial de pagamento.
  • Para MPP, pague um desafio WWW-Authenticate: Payment ... retornado com Link CLI, o servidor MCP Link, Tempo ou um cliente card-MPP como o mpp-card/client da Visa, então repita os mesmos argumentos de ferramenta com payment_authorization.
  • Para x402, pague o desafio PAYMENT-REQUIRED retornado com uma carteira/cliente compatível com x402, então repita os mesmos argumentos de ferramenta com payment_signature.
  • Reutilize o mesmo request_id e campos de pedido na nova tentativa.

Ferramentas

  • postalform.list_forms: Lista os fluxos de trabalho suportados para envio de peça única disponíveis para agentes. Fluxos de trabalho estatutários coordenados com múltiplos destinatários permanecem apenas na web.
  • postalform.get_form_schema: Busca o esquema de um fluxo de trabalho suportado para envio de peça única (campos, dependências, anexos). O esquema de máquina limita arquivos anexados inline e reporta attachments_max_total_size_mb (atualmente 12 MB combinados após decodificação base64). Pode incluir metadados checkout_flow (home ou forms_order) para roteamento web do PostalForm; clientes/agentes MCP podem tratar isso como informativo.
  • postalform.create_letter_order_draft: Cria um rascunho de pedido a partir de texto de carta (o servidor renderiza um PDF).
  • postalform.create_form_order_draft: Cria um rascunho de pedido a partir de uma submissão JSON de fluxo de trabalho suportado para envio de peça única; o servidor preenche um formulário, renderiza uma carta ou monta os documentos de pacote anexados necessários de acordo com o esquema descoberto. Anexos de fluxo de trabalho inline são limitados a 12 MB combinados após decodificação base64, mesmo quando o fluxo de upload do navegador permite arquivos maiores.
  • postalform.create_pdf_upload: Cria uma URL de upload de PDF de curta duração + upload_token para agentes que não podem passar parâmetros de arquivo. Faça upload do PDF e depois chame postalform.create_order_draft com pdf: { upload_token: "..." }.
  • postalform.search_addresses: Busca sugestões de endereços para correspondência. Entrada: query (mínimo de 3 caracteres), country_code opcional (padrão US), container opcional (para aprofundar em resultados do tipo Container), target opcional. Saída: sugestões de endereços com ids/texto/tipo/país. Se o tipo for Container, chame a busca novamente com container=id para obter resultados do tipo Address para rascunhos de pedido.
  • postalform.create_order_draft: Cria um rascunho de pedido e recebe uma URL de checkout. Entrada: pdf (objeto de arquivo { download_url, file_id }, ou { upload_token } de postalform.create_pdf_upload, ou uma URL data:application/pdf;base64,..., ou uma URL pública de download HTTPS), nomes de remetente/destinatário, e endereços Loqate (*_address_type="Address" + *_address_id) ou endereços manuais (*_address_type="Manual" + *_address_manual, com countryCode opcional). Saída: order_id, price_usd, checkout_url, checkout_session.
  • postalform.create_machine_order: Cria e paga um único PDF, carta, formulário de fluxo de trabalho ou campanha de cartas em massa usando MPP direto ou x402. Para envio em massa, envie exatamente um de bulk.csv_content ou bulk.recipients (objetos de endereço JSON com merge_fields opcional), bulk.content_mode (pdf, text ou html), e o correspondente pdf ou bulk.template_text/bulk.template_html de nível superior compartilhado; omita campos de destinatário de nível superior, letter, form e opções de cartão postal. Saída: detalhes do desafio payment_required na primeira chamada, depois detalhes pagos/liquidados após repetir com payment_authorization (MPP) ou payment_signature (x402). O envio em massa também retorna campaign_url, bulk.recipient_count, bulk.content_mode e price_usd combinado para revisão do comprador. Uma nova tentativa paga em cripto pode retornar brevemente settled_pending_webhook; consulte o status e não pague novamente. Veja o exemplo de destinatário JSON.
  • postalform.pay_order: Busca um desafio ou paga um rascunho MPP existente de peça única ou campanha em massa comum por order_id. Nenhum reenvio de documento ou CSV é necessário. Ao alternar de create_machine_order, omita payment_authorization primeiro para buscar o desafio deste endpoint e depois responda com a credencial aprovada. Revise a pré-visualização do PDF único ou o painel da campanha em massa e o preço total antes do pagamento.
  • complete_checkout: Paga uma sessão de checkout preparada com um token de pagamento Stripe aprovado pelo comprador. Entrada: checkout_session_id (order*id), buyer (first_name, last_name opcional, email), payment_data.token (token de pagamento compartilhado Stripe, spt*...), provider=stripe. Saída: resposta da sessão de checkout com status e link permanente do pedido.
  • postalform.get_order_status: Busca os detalhes mais recentes do status do pedido. Entrada: order_id. Saída: found, is_paid, current_step, error, além do status público de envio armazenado, evidências de rastreamento da transportadora e disponibilidade de recibo eletrônico de retorno (veja o exemplo de status abaixo). Pedidos em massa também retornam campaign_url e bulk com ID da campanha, contagem de destinatários, modo de conteúdo, status da campanha e contagens por status em bulk.status_counts. Use o painel para destinatários individuais; o estado agregado do pagamento não prova a entrega.
  • postalform.ping: Verificação de saúde do servidor MCP. Entrada: nenhuma. Saída: payload de ping para verificações de conectividade.

Exemplos de payloads de ferramentas

postalform.list_forms

Requisição:

{
  "name": "postalform.list_forms",
  "arguments": { "q": "IRS", "limit": 10 }
}

postalform.get_form_schema

Requisição:

{
  "name": "postalform.get_form_schema",
  "arguments": { "slug": "1099-nec" }
}

Nota: a resposta pode incluir checkout_flow. Isso são metadados de fluxo de trabalho para roteamento de checkout web do PostalForm e não altera a sequência de chamadas de ferramentas MCP.

postalform.search_addresses

Requisição:

{
  "name": "postalform.search_addresses",
  "arguments": {
    "target": "recipient",
    "query": "123 Main St"
  }
}

Resposta:

{
  "structuredContent": {
    "view": "address_suggestions",
    "target": "recipient",
    "query": "123 Main St",
    "suggestions": [
      {
        "id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
        "text": "123 Main St, Springfield, IL 62701",
        "type": "Address",
        "description": ""
      }
    ]
  }
}

postalform.create_letter_order_draft

Requisição:

{
  "name": "postalform.create_letter_order_draft",
  "arguments": {
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "letter": {
      "title": "Payment demand letter",
      "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n",
      "signature": "Sender Example"
    },
    "sender_name": "Sender Example",
    "sender_address_type": "Manual",
    "sender_address_manual": {
      "line1": "123 Sender St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    },
    "recipient_name": "Recipient Example",
    "recipient_address_type": "Manual",
    "recipient_address_manual": {
      "line1": "456 Recipient Ave",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  }
}

postalform.create_form_order_draft

Requisição:

{
  "name": "postalform.create_form_order_draft",
  "arguments": {
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "slug": "1099-nec",
    "fields": {
      "calendar_year": "2025",
      "payer_name": "Sender Example LLC",
      "payer_street_address": "123 Sender St",
      "payer_city_state_zip_phone": "Springfield, IL 62701, 217-555-0100",
      "payer_tin": "12-3456789",
      "recipient_tin": "123-45-6789",
      "recipient_name": "Contractor Example",
      "recipient_street_address": "456 Recipient Ave",
      "recipient_city_state_zip": "Springfield, IL 62701",
      "box_1_nonemployee_compensation": "1250.00"
    },
    "sender_name": "Sender Example",
    "sender_address_type": "Address",
    "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
    "sender_address_text": "123 Sender St, Springfield, IL 62701",
    "recipient_name": "Contractor Example",
    "recipient_address_type": "Manual",
    "recipient_address_manual": {
      "line1": "456 Recipient Ave",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  }
}

postalform.create_pdf_upload

Requisição:

{
  "name": "postalform.create_pdf_upload",
  "arguments": {
    "file_name": "letter.pdf",
    "content_type": "application/pdf",
    "content_length": 1234567
  }
}

Resposta:

{
  "structuredContent": {
    "upload_url": "https://postalform.com/api/mcp/pdf-uploads/pfu_...",
    "upload_token": "pfu_...",
    "expires_at": "2026-01-17T12:00:00Z",
    "max_bytes": 104857600,
    "required_headers": {}
  }
}

Faça upload do PDF com multipart/form-data usando o campo file (aliases pdf e pdfFile também são aceitos) e depois passe upload_token para postalform.create_order_draft ou postalform.create_machine_order. Deixe o codificador multipart do cliente HTTP gerar o cabeçalho Content-Type, incluindo seu boundary; não defina um cabeçalho Content-Type: multipart/form-data simples ao usar FormData ou curl -F.

postalform.create_order_draft

Nota: pdf aceita um objeto de arquivo, um upload_token ou uma URL de dados base64 (data:application/pdf;base64,...). Uma URL de download pode usar qualquer host HTTPS público, incluindo URLs de anexos assinados do Muse ou outros clientes; ela deve funcionar sem cabeçalhos de autenticação adicionais. Cada redirecionamento também deve usar HTTPS e resolver para endereços públicos. Endereços privados/internos são bloqueados; downloads são limitados a 100 MB, cinco redirecionamentos e 20 segundos. Requisição:

{
  "name": "postalform.create_order_draft",
  "arguments": {
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "pdf": { "upload_token": "pfu_..." },
    "file_name": "letter.pdf",
    "sender_name": "Sender Example",
    "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
    "sender_address_type": "Address",
    "sender_address_text": "123 Sender St, Springfield, IL 62701",
    "recipient_name": "Recipient Example",
    "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
    "recipient_address_type": "Address",
    "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
    "double_sided": true,
    "color": false
  }
}

Resposta:

{
  "structuredContent": {
    "view": "order_draft",
    "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "page_count": 2,
    "price_usd": 2.99,
    "checkout_url": "https://postalform.com/payment?orderId=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "sender_name": "Sender Example",
    "sender_address_text": "123 Sender St, Springfield, IL 62701",
    "recipient_name": "Recipient Example",
    "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
    "checkout_session": {
      "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
      "payment_provider": {
        "provider": "stripe",
        "merchant_id": "profile_123",
        "supported_payment_methods": ["card", "apple_pay", "google_pay"]
      },
      "status": "ready_for_payment",
      "currency": "usd",
      "line_items": [
        {
          "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
          "item": { "id": "postalform_mail_pdf", "quantity": 1 },
          "base_amount": 299,
          "discount": 0,
          "subtotal": 299,
          "tax": 0,
          "total": 299
        }
      ],
      "totals": [
        { "type": "items_base_amount", "display_text": "Items", "amount": 299 },
        { "type": "subtotal", "display_text": "Subtotal", "amount": 299 },
        { "type": "tax", "display_text": "Tax", "amount": 0 },
        { "type": "total", "display_text": "Total", "amount": 299 }
      ],
      "links": [
        { "type": "terms_of_use", "value": "https://postalform.com/terms" },
        { "type": "privacy_policy", "value": "https://postalform.com/privacy" }
      ],
      "payment_mode": "test"
    }
  }
}

MPP para qualquer rascunho

postalform.create_order_draft, postalform.create_letter_order_draft e postalform.create_form_order_draft aceitam:

{
  "payment_protocol": "mpp",
  "buyer_email": "buyer@example.com",
  "buyer_name": "Buyer Example"
}

Inclua esses campos junto com os argumentos normais de PDF, carta ou formulário e um request_id estável. buyer_email é obrigatório para MPP; buyer_name usa como padrão o remetente. A resposta tem payment_protocol: "mpp", um fallback checkout_url do mesmo pedido, preview_url, price_usd e payment contendo o status do pedido, endpoint de pagamento e desafios MPP (payment.payment.www_authenticate). Nenhum pagamento é enviado pela criação do rascunho. Omitir payment_protocol preserva o checkout hospedado e complete_checkout.

Após revisão e aprovação do comprador, responda a um desafio retornado e pague o mesmo pedido preparado:

{
  "name": "postalform.pay_order",
  "arguments": {
    "order_id": "11111111-1111-4111-8111-111111111111",
    "payment_authorization": "Payment <credential>"
  }
}

Omita payment_authorization para atualizar o desafio. O Link CLI ou outro cliente HTTP MPP pode enviar POST {} para https://postalform.com/api/machine/mpp/orders/{order_id}/pay. Uma chamada não paga retorna HTTP 402 com WWW-Authenticate; repita essa mesma URL e corpo com Authorization: Payment .... O pagamento bem-sucedido retorna o status do pedido e Payment-Receipt. Reutilize o mesmo ID de pedido e credencial após uma resposta interrompida. Novas tentativas paid e settled_pending_webhook não enviam outro pagamento; consulte o status. O documento e os endereços nunca são reenviados. O protocolo da requisição original permanece parte do contrato de idempotência. Pedidos MPP/x402 podem selecionar o checkout hospedado retornado antes de enviar uma credencial de pagamento; um rascunho existente apenas hospedado não pode ser convertido em MPP chamando pay_order.

postalform.create_machine_order

Primeira chamada para um desafio de pagamento MPP/Link:

{
  "name": "postalform.create_machine_order",
  "arguments": {
    "payment_protocol": "mpp",
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "buyer_name": "Agent Owner",
    "buyer_email": "owner@example.com",
    "letter": {
      "title": "Payment demand letter",
      "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n"
    },
    "sender_name": "Sender Example",
    "sender_address_type": "Manual",
    "sender_address_manual": {
      "line1": "123 Sender St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    },
    "recipient_name": "Recipient Example",
    "recipient_address_type": "Manual",
    "recipient_address_manual": {
      "line1": "456 Recipient Ave",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  }
}

Formato da resposta:

{
  "structuredContent": {
    "view": "machine_order",
    "protocol": "mpp",
    "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "status": "payment_required",
    "payment": {
      "www_authenticate": ["Payment ..."],
      "retry_header": "Authorization",
      "retry_header_value": "Payment ..."
    }
  }
}

Depois que o Link CLI ou Link MCP retornar a credencial MPP paga, repita os mesmos argumentos com:

{
  "payment_authorization": "Payment ..."
}

Para x402, defina payment_protocol como x402; a primeira resposta contém payment.payment_required_header e a nova tentativa usa payment_signature.

complete_checkout

Requisição:

{
  "name": "complete_checkout",
  "arguments": {
    "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "buyer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    },
    "payment_data": {
      "token": "spt_test_123",
      "provider": "stripe"
    }
  }
}

Resposta:

{
  "structuredContent": {
    "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "buyer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    },
    "status": "completed",
    "currency": "usd",
    "line_items": [
      {
        "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
        "item": { "id": "postalform_mail_pdf", "quantity": 1 },
        "base_amount": 299,
        "discount": 0,
        "subtotal": 299,
        "tax": 0,
        "total": 299
      }
    ],
    "fulfillment_options": [
      {
        "type": "shipping",
        "id": "postalform_standard",
        "title": "First Class mail",
        "subtitle": "Mailed via postal carrier",
        "carrier": "Postal carrier",
        "carrier_info": "PostalForm print-and-mail provider",
        "earliest_delivery_time": "2026-07-01T00:00:00.000Z",
        "latest_delivery_time": "2026-07-06T00:00:00.000Z",
        "subtotal": 0,
        "tax": 0,
        "total": 0
      }
    ],
    "fulfillment_option_id": "postalform_standard",
    "totals": [
      { "type": "items_base_amount", "display_text": "Items", "amount": 299 },
      { "type": "subtotal", "display_text": "Subtotal", "amount": 299 },
      { "type": "tax", "display_text": "Tax", "amount": 0 },
      { "type": "total", "display_text": "Total", "amount": 299 }
    ],
    "order": {
      "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
      "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
      "permalink_url": "https://postalform.com/order/complete?order_id=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b"
    },
    "messages": [],
    "links": [
      { "type": "terms_of_use", "value": "https://postalform.com/terms" },
      { "type": "privacy_policy", "value": "https://postalform.com/privacy" }
    ]
  }
}

postalform.get_order_status

Resposta:

{
  "structuredContent": {
    "view": "order_status",
    "found": true,
    "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "is_paid": true,
    "current_step": "letter_created",
    "mailing_status": "processed",
    "mailing_status_normalized": "processed_for_delivery",
    "tracking_number": "9400000000000000000000",
    "carrier": "USPS",
    "delivery_status": "delivered",
    "delivery_status_detail": "Delivered to authorized agent",
    "signed_by": "Authorized agent",
    "tracking_events": [],
    "estimated_delivery_at": null,
    "tracking_updated_at": "2026-09-05T12:00:00Z",
    "electronic_return_receipt": {
      "requested": true,
      "status": "manual",
      "document_available": false,
      "emailed_at": null
    }
  }
}

As leituras de status usam as mesmas evidências públicas de envio armazenadas da página de conclusão do pedido. mailing_status / mailing_status_normalized descrevem o cumprimento; delivery_status e tracking_events relatam evidências disponíveis da transportadora. Uma etapa interna como letter_created, ou um número de rastreamento sozinho, não prova aceitação ou entrega pela transportadora. Campos ausentes são null, eventos ausentes são [] e pedidos desconhecidos retornam found=false sem campos de envio. Esses campos também suportam transportadoras fora dos EUA; não presuma que todo número de rastreamento pertence ao USPS.

tracking_events contém no máximo os 50 eventos armazenados mais recentes, com status, statusNormalized, statusDetail, message, occurredAt e location (postalCode, city, state, label). Os eventos são sanitizados como na página de conclusão. tracking_updated_at é o timestamp do último webhook do provedor registrado, não uma garantia de uma consulta recente à transportadora. As estimativas podem mudar.

electronic_return_receipt.requested significa que um recibo eletrônico foi selecionado. Seu status é manual, pending, sent ou failed (ou null quando não solicitado); sent e emailed_at referem-se ao PostalForm enviando o recibo por email. document_available significa que o PostalForm tem um documento de recibo armazenado. Um valor falso não prova que o USPS não emitiu um recibo, especialmente com recuperação manual. Recibos físicos de retorno não contam como recibos eletrônicos. Esta ferramenta não baixa/adquire recibos nem expõe seus caminhos de armazenamento, e a consulta nunca cobra, paga ou inicia o envio.

Exemplo de resposta de erro

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "recipient_address_manual is required when recipient_address_type is Manual."
    }
  ]
}

Notas de integração

  • Idempotência: use request_id nas ferramentas de criação de rascunho (postalform.create_order_draft, postalform.create_letter_order_draft, postalform.create_form_order_draft) e em postalform.create_machine_order. Reutilize o mesmo valor e os mesmos campos de pedido nas novas tentativas. O servidor retornará o rascunho/pedido existente.
  • Erros: chamadas de ferramentas que falham na validação retornam isError=true com uma mensagem legível por humanos. Para checkout por token, complete_checkout também pode retornar mensagens ACP com códigos de erro como payment_declined ou requires_3ds.
  • Fallback de checkout instantâneo: se window.openai.requestCheckout estiver indisponível ou checkout_session.payment_provider não tiver merchant_id, use checkout_url.
  • Etapas de status do pedido: payment_received, receiver_address_verified, sender_address_verified, pdf_normalized, letter_created, email_sent, canceled, refunded, abandoned.

Limites e requisitos

  • Todos os pedidos são impressos a partir de PDFs. Para postalform.create_order_draft você fornece o PDF. Para postalform.create_letter_order_draft e postalform.create_form_order_draft o PostalForm gera o PDF no servidor. Os PDFs são sanitizados antes da impressão.
  • Anexos form.attachments inline são JSON em base64 e podem totalizar no máximo 12 MB após a decodificação. Siga os valores de allowed_types, max_files e max_size_mb (limitados por máquina) de cada anexo conforme o schema do workflow.
  • Para um workflow com recipient.mode="user", o nome/endereço do destinatário de nível superior controla o envelope. Mantenha-o alinhado com os campos de papel de endereço do destinatário em form.fields; esses campos não substituem o endereço de ordem de máquina de nível superior.
  • Máximo de 199 páginas e 100 MB por arquivo.
  • download_url aceita qualquer host HTTPS público e parâmetros de consulta assinados, sem lista de permissões do fornecedor. A URL e cada redirecionamento devem resolver para endereços públicos e funcionar sem cabeçalhos de autenticação extras. Se o cliente não puder expor uma URL para download, use postalform.create_pdf_upload para uma URL de upload_token ou data:application/pdf;base64,.... Para cartas geradas, passe o texto diretamente para postalform.create_letter_order_draft; nenhum upload é necessário.
  • Os países de endereço padrão são US quando omitidos. Use IDs de endereço Loqate retornados por postalform.search_addresses (o prefixo do ID contém o país) ou use entrada manual de endereço com *_address_type="Manual" e *_address_manual.countryCode. Pedidos de máquina aplicam a mesma lista de países do seletor de endereço do checkout: US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU e NL; códigos não suportados ou inválidos são rejeitados. CSVs em lote aceitam a mesma lista por meio de country, country_code ou countrycode.
  • As sugestões de endereço podem incluir type="Container" (edifícios/complexos). Chame postalform.search_addresses novamente com container=<id> e uma consulta refinada (suite, unidade, caixa postal) para obter resultados type="Address". Apenas type="Address" (não Container) é válido para rascunhos de pedidos baseados em Loqate.

Segurança, permissões e limites de taxa do MCP

Trate o PostalForm como uma ferramenta de ação no mundo real, pois ele pode criar rascunhos de correspondência e, em fluxos de pagamento por máquina, colocar pedidos de correspondência pagos após um desafio de pagamento aprovado pelo proprietário. Em clientes de chat, configure o servidor com require_approval: "always" e exija revisão humana antes de enviar documentos, endereços ou credenciais de pagamento do usuário.

Ferramenta ou fluxoEscopoEfeitos colaterais e limites
postalform.list_forms e postalform.get_form_schemaLê o catálogo de formulários publicado e os metadados do schemaNenhum pedido, upload de arquivo, pagamento ou efeito colateral de correspondência
postalform.search_addressesBusca sugestões de endereço para campos de remetente ou destinatárioChama o provedor de busca de endereços e tem limite de taxa por IP. Os padrões são 120 buscas por minuto e 3.000 por dia. Não cria pedido ou pagamento
postalform.create_pdf_uploadCria uma URL de upload de curta duração para um PDFSomente token de upload. O arquivo ainda precisa ser anexado a uma chamada de rascunho posterior. Os uploads são limitados pelos limites documentados de páginas e tamanho de arquivo
postalform.create_order_draftCria um rascunho em PDF para checkout hospedado ou MPPCria um rascunho não pago, retornando checkout hospedado ou um desafio MPP. Nenhuma impressão ou envio ocorre antes do pagamento
postalform.create_letter_order_draftRenderiza texto de carta em um rascunho para checkout hospedado ou MPPCria um rascunho não pago, retornando checkout hospedado ou um desafio MPP. Nenhuma impressão ou envio ocorre antes do pagamento
postalform.create_form_order_draftPreenche um formulário de workflow para checkout hospedado ou MPPCria um rascunho não pago, retornando checkout hospedado ou um desafio MPP. Nenhuma impressão ou envio ocorre antes do pagamento
postalform.pay_orderRetorna um desafio MPP ou paga um pedido MPP preparadoPasse apenas order_id e o payment_authorization aprovado pelo comprador; reutilize esse ID em novas tentativas.
postalform.create_machine_orderCria ou paga um pedido de máquina direto MPP/x402Use apenas em runtimes autônomos autorizados com controles de gastos. A chamada não paga retorna um desafio de pagamento; a nova tentativa paga deve incluir a autorização MPP ou a assinatura de pagamento x402
complete_checkoutPaga um checkout preparado com um token Stripe compatívelUse apenas após o comprador confirmar o checkout com um token de pagamento compartilhado Stripe
postalform.get_order_status e postalform.pingLê o status do pedido ou o estado de saúdeNenhum efeito colateral de criação de pedido, pagamento ou envio

Ferramentas que criam rascunhos e ferramentas de pedido de máquina direto também são limitadas pela limitação de pedidos não pagos. O limite padrão de criação de pedidos não pagos é de 10 tentativas por hora por IP do cliente. Em limites de taxa, as ferramentas MCP retornam uma resposta de erro e chamadas de wrapper HTTP podem retornar 429.

Os scanners de segurança devem tratar o checkout hospedado como o caminho seguro padrão: a ferramenta pode criar um rascunho, mas o cliente ainda revisa o PDF, endereços, preço e opções de envio antes do pagamento. O pagamento direto por máquina deve permanecer atrás de aprovação explícita do proprietário, limites de gastos, valores de request_id idempotentes e uma etapa de revisão de pré-visualização quando preview_url estiver presente.

Fontes de protocolo e plataforma

Perguntas frequentes

  • O PostalForm é uma API de correspondência? Sim. O PostalForm expõe endpoints REST de pedidos de máquina, um catálogo OpenAPI e um servidor MCP remoto para criar rascunhos de correspondência física, cotações, pedidos com pagamento por máquina e consultas de status de atendimento.
  • Um servidor MCP pode enviar correspondência postal real? Sim, mas o PostalForm separa a criação de rascunhos do envio pago. As ferramentas de rascunho preparam pedidos não pagos para checkout hospedado ou pagamento MPP opcional por ID do pedido. Os pagamentos exigem aprovação do comprador e a credencial apropriada.
  • Qual é o padrão mais seguro para ChatGPT, Claude, Gemini, Cursor ou Codex? Use o endpoint MCP remoto em https://postalform.com/mcp,, configure a aprovação para efeitos colaterais de correspondência, crie um rascunho de checkout hospedado e deixe o usuário revisar o PDF, endereços, preço e opções antes do pagamento.
  • Um agente pode pagar por correspondência com x402 ou MPP? Sim. O PostalForm suporta fluxos de pagamento direto por máquina para runtimes autônomos autorizados. A chamada não paga retorna um desafio de pagamento, e a nova tentativa paga deve incluir a assinatura de pagamento x402 ou a autorização MPP.
  • Preciso de uma chave de API do PostalForm? Não para o endpoint MCP público atual ou fluxo de pagamento por máquina. Algumas implantações de alto volume, sensíveis a abuso ou com lista de permissões podem exigir coordenação com support@postalform.com.
  • Posso enviar PDFs pela API ou MCP? Sim. Use a ferramenta de upload de PDF para criar um token de upload de curta duração, passe uma URL pública de download HTTPS, use uma URL de anexo do ChatGPT ou forneça uma URL de dados onde suportado.
  • Como mantenho os efeitos colaterais de correspondência seguros? Trate a correspondência física como uma ação no mundo real. Use checkout hospedado por padrão, exija aprovação humana, defina limites de gastos, reutilize IDs de solicitação de idempotência e revise URLs de pré-visualização antes do pagamento quando presentes.