Desenvolvedores

API RESTful para desenvolvedores

Integre o envio de cartas escritas à mão diretamente no seu sistema. API simples, previsível e bem documentada.

Comece rápido

Autenticação

Use sua API key no header de autorização de todas as requisições.

Authorization: Bearer sk_live_sua_api_key

Base URL

Todas as requisições usam HTTPS. Ambiente de sandbox disponível para testes.

https://api.suacarta.com.br/v1

Rate Limits

Limites generosos que escalam com seu plano. Headers indicam uso restante.

Starter: 100 req/min
Pro: 500 req/min
Enterprise: ilimitado

Endpoints

POST/api/v1/cards

Enviar uma carta

Request

{
  "to": {
    "name": "Maria Silva",
    "address": "Rua das Flores, 123",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01234-567"
  },
  "message": "Obrigado por ser nosso cliente...",
  "style": "elegant",
  "template": "agradecimento"
}

Response

{
  "id": "card_abc123",
  "status": "processing",
  "estimated_delivery": "2024-03-20",
  "tracking_url": "https://suacarta.com.br/track/abc123",
  "created_at": "2024-03-15T10:30:00Z"
}

GET/api/v1/cards/:id

Status de uma carta

Request

GET /api/v1/cards/card_abc123
Authorization: Bearer sk_live_sua_api_key

Response

{
  "id": "card_abc123",
  "status": "shipped",
  "tracking_code": "BR123456789",
  "events": [
    { "type": "created", "at": "2024-03-15T10:30:00Z" },
    { "type": "written", "at": "2024-03-15T14:00:00Z" },
    { "type": "shipped", "at": "2024-03-16T08:00:00Z" }
  ]
}

GET/api/v1/styles

Listar estilos de caligrafia

Request

GET /api/v1/styles
Authorization: Bearer sk_live_sua_api_key

Response

{
  "styles": [
    {
      "id": "elegant",
      "name": "Elegante",
      "description": "Caligrafia cursiva clássica"
    },
    {
      "id": "modern",
      "name": "Moderna",
      "description": "Estilo contemporâneo e limpo"
    },
    {
      "id": "casual",
      "name": "Casual",
      "description": "Escrita descontraída e pessoal"
    }
  ]
}

GET/api/v1/templates

Listar templates

Request

GET /api/v1/templates
Authorization: Bearer sk_live_sua_api_key

Response

{
  "templates": [
    {
      "id": "agradecimento",
      "name": "Agradecimento",
      "variables": ["nome", "produto", "data_compra"]
    },
    {
      "id": "boas-vindas",
      "name": "Boas-vindas",
      "variables": ["nome", "plano", "empresa"]
    }
  ]
}

POST/api/v1/bulk

Envio em massa

Request

{
  "cards": [
    {
      "to": { "name": "Cliente 1", "address": "..." },
      "message": "Mensagem personalizada 1",
      "style": "elegant"
    },
    {
      "to": { "name": "Cliente 2", "address": "..." },
      "message": "Mensagem personalizada 2",
      "style": "modern"
    }
  ],
  "schedule": "2024-03-20T09:00:00Z"
}

Response

{
  "batch_id": "batch_xyz789",
  "total_cards": 2,
  "status": "queued",
  "estimated_completion": "2024-03-20T12:00:00Z"
}

SDKs oficiais

Node.js

Disponível

npm install @suacarta/sdk

Python

Disponível

pip install suacarta

Ruby

Em breve

gem install suacarta

Webhooks

Receba notificações em tempo real sobre o status de cada carta. Configure uma URL de callback e enviaremos eventos automaticamente.

card.created

Carta criada e na fila de produção

card.written

Carta escrita à mão e pronta para envio

card.shipped

Carta postada nos Correios com código de rastreamento

card.delivered

Carta entregue no endereço do destinatário

card.returned

Carta devolvida por endereço inválido ou ausência

Exemplo de payload do webhook

{
  "event": "card.shipped",
  "data": {
    "card_id": "card_abc123",
    "tracking_code": "BR123456789",
    "shipped_at": "2024-03-16T08:00:00Z",
    "estimated_delivery": "2024-03-20"
  },
  "webhook_id": "wh_def456",
  "created_at": "2024-03-16T08:00:05Z"
}

Comece a integrar

Solicite sua API key e comece a enviar cartas de forma programática em minutos. Nossa equipe está pronta para ajudar na integração.

Solicitar API Key