API REST v1

API de Envio de Telegramas

Automatize o envio de telegramas dos Correios diretamente do seu sistema. Ideal para cobranças, notificações jurídicas, comunicados oficiais e envios em alto volume.

Solicitar Token Ver Documentação

# Criar telegrama

POST /api/v1/telegrama
Authorization: Bearer <token>

{
  "destinatario": { ... },
  "texto": "Conteúdo...",
  "simular": false
}

Pensado para quem envia em alto volume

Três formas de enviar: manualmente pelo painel, em massa via CSV ou integrado via API.

Envio por Volume

Dispare milhares de telegramas por mês com tarifas corporativas e faturamento mensal. Cota-se por volume, com NFS-e emitida automaticamente.

Envio em Massa via CSV

Importe uma planilha com centenas de destinatários, aplique um template com variáveis e envie tudo em poucos cliques. Sem precisar integrar código.

Integração via API REST

Endpoints JSON com autenticação por Bearer Token. Crie telegramas, consulte status, rastreio em tempo real e saldo direto do seu backend.

Simulação antes de Enviar

O endpoint aceita simular: true para calcular preço, páginas e verificar saldo sem criar o telegrama. Ideal para orçamentos e previews.

Rastreio em Tempo Real

Consulte o status dos Correios em tempo real via API. Cada chamada traz a lista completa de eventos do objeto, sem precisar cadastrar webhook.

Seguro e Auditável

Tokens individuais por integração, rate limiting por usuário e histórico completo no painel (plataforma = API). Os envios são realizados pelos Correios.

Casos de uso comuns

Empresas que enviam documentos de forma recorrente ganham tempo e reduzem custo ao integrar o fluxo direto no sistema interno.

Cobrança — disparo automático após X dias de atraso.
Escritórios de advocacia — notificações extrajudiciais em lote.
Sindicatos e associações — comunicados aos associados.
RH e compliance — convocações e avisos formais.
SaaS — telegrama como canal embutido no produto do cliente.

Como começar

Solicite um contrato corporativo informando o volume estimado.
Nossa equipe gera o token de API e envia para você em segurança.
Use o token no header Authorization: Bearer em todas as chamadas.
Rode em modo simulação (simular: true) até validar o payload.
Desative a simulação e comece a enviar em produção.

Documentação da API

API REST, JSON, base:

Autenticação

Todas as requisições exigem um Bearer Token enviado no header Authorization. Tokens não expiram, mas podem ser revogados pela nossa equipe. Solicite seu token pelo fluxo corporativo.

Authorization: Bearer SEU_TOKEN_AQUI
Accept: application/json
Content-Type: application/json

Rate Limiting

Escopo	Limite
Geral (todos os endpoints)	60 req/min por usuário
Criação (`POST /telegrama`)	10 req/min por usuário

Ao exceder, a API responde 429 Too Many Requests. Para volumes maiores, fale com o comercial.

Endpoints

Criar ou Simular Telegrama

O remetente é puxado automaticamente do cadastro do usuário autenticado. Tickets criados via API ficam marcados com plataforma = "API".

Request (cURL)

curl -X POST BASE_URL/api/v1/telegrama \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "destinatario": {
      "nome": "João da Silva",
      "cep": "01001-000",
      "endereco_rua": "Praça da Sé",
      "endereco_numero": "100",
      "endereco_complemento": "Sala 1",
      "endereco_bairro": "Sé",
      "endereco_cidade": "São Paulo",
      "endereco_estado": "SP"
    },
    "texto": "Conteúdo do telegrama...",
    "adicionais": {
      "copia": false,
      "confirmacao": false
    },
    "agendamento": null,
    "simular": false
  }'

Body — campos

Campo	Tipo	Obrigatório	Descrição
`destinatario.nome`	string	sim	Nome completo do destinatário.
`destinatario.cep`	string	sim	CEP com ou sem máscara.
`destinatario.endereco_rua`	string	sim	Logradouro.
`destinatario.endereco_numero`	string	sim	Número do imóvel.
`destinatario.endereco_complemento`	string	não	Apto, sala, bloco etc.
`destinatario.endereco_bairro`	string	sim	Bairro.
`destinatario.endereco_cidade`	string	sim	Cidade.
`destinatario.endereco_estado`	string(2)	sim	UF, ex: `SP`.
`texto`	string	sim	Conteúdo do telegrama.
`adicionais.copia`	boolean	não	Cópia do telegrama.
`adicionais.confirmacao`	boolean	não	Confirmação de entrega (AR).
`agendamento`	string\|null	não	Data/hora futura ISO 8601 ou `null`.
`simular`	boolean	não	Se `true`, apenas calcula preço sem criar o telegrama.

Response — `simular: false`

{
  "success": true,
  "simulacao": false,
  "uuid_ticket": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PROCESSANDO",
  "preco": 15.90,
  "saldo_atual": 484.10,
  "mensagem": "Telegrama criado com sucesso. Acompanhe pelo uuid_ticket."
}

Response — `simular: true`

{
  "success": true,
  "simulacao": true,
  "preco_base": 12.90,
  "preco_adicionais": 3.00,
  "preco_total": 15.90,
  "adicionais": [
    { "slug": "copia", "descricao": "Cópia do telegrama", "preco": 3.00 }
  ],
  "paginas_estimadas": 1,
  "caracteres": 350,
  "saldo_disponivel": 500.00,
  "saldo_suficiente": true
}

Códigos de erro

HTTP	Código	Quando
400	`CADASTRO_INCOMPLETO`	Usuário sem endereço completo no cadastro.
400	`SALDO_INSUFICIENTE`	Saldo + limite de crédito insuficiente.
422	validação	Campos obrigatórios faltando ou inválidos.
423	`blocked`	Conta suspensa (inadimplência, etc.).
429	—	Rate limit excedido.

Pronto para integrar?

Fale com nosso time comercial para contratar o plano corporativo e receber seu token de API.

Solicitar Acesso Corporativo Falar com o Comercial