API de cartas escritas à mão: documentação e primeiros passos

A API de cartas escritas à mão da SuaCarta permite que qualquer sistema envie cartas manuscritas de forma programática. Se você é desenvolvedor e quer integrar o envio de cartas no seu produto, CRM ou automação interna, esta REST API carta manuscrita foi projetada para ser simples de implementar. Neste guia, cobrimos autenticação, endpoints principais, estrutura de payloads e primeiros passos para começar a enviar cartas via código.

Visão geral da arquitetura

A API da SuaCarta segue o padrão REST com JSON. Todas as chamadas usam HTTPS e autenticação via API key no header. O fluxo básico é: você cria um pedido de carta via POST, recebe um ID de rastreamento e acompanha o status via polling ou webhook. A carta é produzida com caligrafia robótica, envelopada e postada nos Correios em até 2 dias úteis.

A API aceita chamadas de qualquer linguagem ou plataforma que suporte HTTP. Não há SDK obrigatório — você pode integrar com curl, Python, Node.js, PHP, Ruby ou qualquer outra stack. O tempo de resposta médio do endpoint de criação é de 200 milissegundos.

Autenticação e setup inicial

Para acessar a API, você precisa de uma API key gerada no painel da SuaCarta. Cada plano empresarial inclui acesso à API — planos a partir do Profissional (R$799 por mês) já vêm com a chave habilitada.

A autenticação é feita via header Authorization com Bearer token. Todas as requisições devem incluir Content-Type application/json. A API retorna códigos HTTP padrão: 201 para criação bem-sucedida, 400 para payload inválido, 401 para autenticação falha e 429 para rate limit excedido.

O rate limit padrão é de 60 requisições por minuto, suficiente para a maioria dos cenários. Para volumes maiores, o plano Corporativo oferece limites expandidos e suporte técnico dedicado.

Endpoint principal: criar carta

O endpoint POST /v1/letters cria um novo pedido de carta. O payload mínimo inclui: nome do destinatário, endereço completo (rua, número, CEP, cidade, estado), mensagem da carta e estilo de caligrafia. Campos opcionais incluem: nome do remetente, endereço de retorno, cor da tinta, tipo de papel e dados de rastreamento customizados.

A mensagem suporta variáveis dinâmicas usando a sintaxe de chaves duplas. Por exemplo, se você envia o campo "primeiro_nome" como "Carlos" no payload, qualquer ocorrência de referência a esse campo no texto da mensagem será substituída automaticamente. Isso permite usar um template único para múltiplos destinatários.

O response retorna o ID da carta, status inicial "queued", data estimada de postagem e data estimada de entrega. Guarde o ID para consultas futuras de status.

Acompanhamento de status via webhook

A API oferece duas formas de acompanhar o status: polling no endpoint GET /v1/letters/{id} ou webhooks configurados no painel. Os status possíveis são: queued (na fila de produção), writing (sendo escrita pelo robô caligráfico), quality_check (em revisão de qualidade), posted (postada nos Correios), delivered (entregue) e returned (devolvida).

Para webhooks, você cadastra uma URL no painel e a SuaCarta envia um POST para essa URL a cada mudança de status. O payload inclui o ID da carta, o novo status, timestamp e metadados adicionais. Isso elimina a necessidade de polling e permite que o seu sistema reaja em tempo real a cada etapa.

Empresas que monitoram o status de entrega conseguem medir com precisão o impacto das cartas. Quando a carta é marcada como "delivered", você pode disparar o próximo passo da cadência — uma ligação de follow-up, por exemplo — sabendo que o destinatário já recebeu a carta.

Envio em lote: endpoint batch

Para envios em volume, o endpoint POST /v1/letters/batch aceita até 500 cartas por requisição. O payload é um array de objetos, cada um seguindo a mesma estrutura do endpoint unitário. O response retorna um batch_id e o status individual de cada carta.

O endpoint batch é ideal para campanhas sazonais (Natal, Dia das Mães), envios de aniversário do mês ou qualquer cenário em que você precisa disparar muitas cartas de uma vez. O processamento é assíncrono: a API confirma o recebimento imediatamente e as cartas entram na fila de produção.

Para acompanhar o batch, use GET /v1/batches/{batch_id}, que retorna o progresso geral e o status de cada carta individual. Webhooks de batch enviam notificações quando todas as cartas do lote são postadas.

Tratamento de erros e validação

A API valida o CEP e a estrutura do endereço antes de aceitar o pedido. Endereços incompletos ou com CEP inválido retornam 400 com uma mensagem descritiva do erro. Isso evita desperdício de produção com cartas que seriam devolvidas.

Para mensagens, há um limite de 500 caracteres por carta (frente) e 300 caracteres adicionais para o verso, quando habilitado. Mensagens que excedem o limite retornam 400 com o campo que precisa ser ajustado. Na prática, 500 caracteres equivalem a cerca de 80 a 100 palavras — o tamanho ideal para uma carta manuscrita eficaz.

Em caso de falha temporária (5xx), a recomendação é implementar retry com backoff exponencial. A API é projetada para disponibilidade de 99,9 por cento, mas falhas transitórias podem ocorrer em momentos de pico.

Integrações prontas vs. API direta

Se você usa plataformas como RD Station, Pipedrive, HubSpot, Shopify ou Nuvemshop, talvez não precise tocar na API diretamente. A SuaCarta oferece integrações nativas que conectam via interface visual, sem código. A API é indicada para sistemas proprietários, integrações customizadas ou cenários que as integrações nativas não cobrem.

Muitas empresas usam as duas abordagens: integrações nativas para os fluxos padrão do CRM e a API para automações específicas do sistema interno. Os dois caminhos compartilham o mesmo saldo de cartas do plano.

Primeiros passos práticos

Para começar a usar a API da SuaCarta hoje: contrate um plano empresarial no painel de preços, gere sua API key nas configurações da conta, faça uma chamada de teste para o endpoint de criação com um endereço real e acompanhe o status até a entrega.

A documentação técnica completa, com exemplos em múltiplas linguagens, está disponível no painel do desenvolvedor. E se precisar de suporte na integração, nossa equipe técnica ajuda — basta abrir um chamado via contato ou pelo chat do painel. De linha de código a carta na mesa do cliente em 3 dias úteis.