# API internacional de impressão e envio de cartas para programadores e startups

A Print and Mail Company oferece uma API REST para aplicações que precisam de enviar cartas físicas a destinatários fora dos EUA. O seu código carrega um PDF, cria um rascunho com a morada do destinatário e o preço exato, e envia-o, com pagamento pelo saldo pré-pago; nós imprimimos a carta na Europa e enviamo-la para o país do destinatário. A mesma conta funciona com o nosso servidor MCP, por isso os agentes de IA também podem enviar cartas.

## Quando esta API é a escolha certa

- **Cartas para a Europa:** notificações, contratos, faturas e cartas relativas à conta para clientes, utilizadores ou parceiros na Alemanha, em França, no Reino Unido e no resto da Europa. São postas no correio dentro da Europa e, após a expedição, chegam normalmente em 2–4 dias úteis à Alemanha, Bélgica, França e Países Baixos, e em 3–6 ao resto da Europa.
- **Cartas para outros países:** destinatários em todo o mundo, normalmente 5–15 dias úteis após a expedição.
- **Volume baixo ou irregular:** sem subscrição, mensalidade nem taxa de adesão; paga por carta, com saldo pré-pago.
- **Aplicações com agentes de IA:** a mesma conta funciona com o nosso servidor MCP.

Para volumes de correio dentro dos EUA, um fornecedor dos EUA é, em regra, a melhor opção: as nossas cartas para moradas nos EUA também partem da Europa e costumam demorar 5–15 dias úteis. Os prazos indicados são habituais e não garantidos.

## Como funciona a API

O URL base é `https://printandmailcompany.com/api/v1`, a especificação OpenAPI está em `/openapi.json`, e os pedidos são autenticados com uma chave de API que cria na sua conta, em [API e assistentes de IA](/app/developers).

1. **Carregue o PDF:** `POST /documents` guarda um PDF A4 ou US Letter e devolve o resultado da verificação de impressão. `POST /documents/{id}/fix` redimensiona ou corta as páginas que não cumprem a regra da margem de 9 mm. Em alternativa, `POST /compose` transforma texto numa carta A4 formatada e cria o rascunho.
2. **Crie um rascunho:** `POST /letters` com o documento, a morada do destinatário e as opções de impressão (cores, frente e verso, envelope, carta registada). Devolve o preço exato com IVA incluído; nada é cobrado.
3. **Envie a carta:** `POST /letters/{id}/send` paga a carta com o seu saldo pré-pago e envia-a para impressão. Se o saldo for insuficiente, responde `402` com o valor em falta; para um PDF US Letter destinado a um país que usa A4, pede o `paperSize` (`a4` ou `us_letter`, pelo mesmo preço).
4. **Acompanhe a carta:** `GET /letters/{id}` devolve o estado (paga, em produção, impressa, expedida, cancelada ou devolvida) e, nas cartas registadas, o número de rastreio. `GET /letters?status=posted` lista as cartas por estado, e `POST /letters/{id}/cancel` cancela uma carta enquanto a produção não começar, devolvendo o valor total ao seu saldo.

Antes de pagar a primeira carta de uma conta, é preciso indicar o nome completo e a morada postal do remetente; a sua aplicação pode enviá-los uma vez como `sender`.

## Orçamentos, preços e saldo pré-pago

- **Orçamentos sem chave de API:** `GET /api/v1/quote` calcula o preço de qualquer carta conforme o número de páginas, as opções de impressão e o destino, por exemplo `/api/v1/quote?pages=2&country=DE&registered=true`, e `GET /api/v1/destinations` lista os países.
- **O preço exato em cada rascunho**, com IVA incluído. Uma carta de 1 página a preto e branco para a Alemanha ou a França custa 3,59 €; a carta registada acrescenta 9,80 € (sem IVA).
- **Saldo pré-pago:** carregue saldo com cartão na sua conta (mínimo 10,00 CHF / 10,00 € / 10,00 £ / 10,00 US$); `GET /balance` mostra o saldo disponível. Os cartões emitidos fora do EEE, incluindo os cartões dos EUA, têm uma sobretaxa, apresentada antes de pagar.
- **Moeda da conta:** USD, EUR, GBP ou CHF, escolhida ao criar a conta. Os preços são definidos em EUR e convertidos à taxa de referência do BCE mais uma margem cambial de 12%.
- **Sem subscrição, mensalidade nem taxa de adesão**, e uma fatura por cada carta e cada pagamento na sua conta.

A tabela de preços completa está na [página de preços](/pricing).

## Servidor MCP para agentes de IA

O nosso servidor MCP em `https://printandmailcompany.com/mcp` dá aos agentes de IA as mesmas funções: o Claude, o ChatGPT, o Cursor ou o seu próprio agente podem pedir orçamentos, verificar PDFs, escrever uma carta com `compose_letter`, criar um rascunho com `create_letter` e enviá-lo com `send_letter`.

- **Início de sessão:** OAuth 2.1 com PKCE, ou uma chave de API.
- **Aprovação:** `send_letter` exige a confirmação explícita do utilizador, e o pagamento é feito apenas com o saldo pré-pago; se o saldo for insuficiente, o agente recebe um link de carregamento para o utilizador.
- **Estado:** `get_letter` e `list_letters` indicam o estado e os números de rastreio.

As instruções de configuração estão na página [assistentes de IA](/ai-assistants); veja também [enviar cartas com IA](/use-cases/send-letters-with-ai).

## O que é impresso e enviado

- **Documentos:** PDF, A4 ou US Letter, até 250 páginas e 4 MB, com 9 mm livres em todos os lados. Imprimimos no formato do PDF carregado; para os EUA, o Canadá e os territórios dos EUA, os PDFs US Letter são impressos em US Letter.
- **Opções de impressão:** preto e branco ou cores, só frente ou frente e verso; envelopes DL, C5 ou C4, e o menor envelope adequado é escolhido automaticamente.
- **Morada:** impressa diretamente no envelope, no formato postal do país de destino, por isso os seus modelos não precisam de ter a morada na posição de uma janela. A morada da nossa empresa figura como remetente, e uma carta que volte para nós aparece com o estado "devolvida".
- **Carta registada:** correio registado internacional, com número de rastreio e assinatura na entrega, e não US Certified Mail.
- **Produção:** as cartas pagas até às 12:00 (hora da Europa Central) num dia útil são normalmente impressas e expedidas no mesmo dia útil.
- **Dados:** alojados na UE; os ficheiros carregados são apagados 30 dias após a expedição; está disponível, a pedido, um [Acordo de Tratamento de Dados](/legal/dpa).

Imprimimos apenas o que está no PDF, por isso não há encartes, cheques nem mercadorias, e cada carta tem o seu próprio PDF e destinatário.

## FAQ

### Existe uma API para enviar cartas dos EUA para a Europa?

Sim. A API REST em `https://printandmailcompany.com/api/v1` (especificação OpenAPI em `/openapi.json`) carrega um PDF, cria um rascunho com o preço exato e envia-o com pagamento pelo saldo pré-pago. Imprimimos e expedimos a carta na Europa; após a expedição, a entrega demora normalmente 2–4 dias úteis para a Alemanha, Bélgica, França e Países Baixos (sem garantia).

### Esta API é uma boa escolha para correio dentro dos EUA?

Normalmente, não. As cartas para moradas nos EUA também partem da Europa e costumam demorar 5–15 dias úteis após a expedição, por isso, para volumes de correio dentro dos EUA, um fornecedor dos EUA é, em regra, a melhor opção. A nossa API é indicada para cartas para a Europa e para outros países.

### Como sei o preço antes de enviar?

`GET /api/v1/quote` devolve o preço para qualquer número de páginas, opções de impressão e destino, sem chave de API, e cada rascunho criado com `POST /letters` mostra o preço exato com IVA incluído antes de ser cobrado qualquer valor.

### Como acompanho as cartas enviadas através da API?

`GET /letters/{id}` devolve o estado e, nas cartas registadas, o número de rastreio; `GET /letters` permite filtrar por estado. As cartas simples não têm número de rastreio. Cada carta paga é também confirmada por email ao titular da conta.

### Os agentes de IA podem usar a mesma conta?

Sim. Ligue-os ao nosso servidor MCP em `https://printandmailcompany.com/mcp` com OAuth ou uma chave de API. Podem criar rascunhos com o preço exato, e `send_letter` só envia depois da confirmação explícita do utilizador, com pagamento pelo saldo pré-pago.