Documentação da API

1. Começando

A API Tudo Envio permite que você integre cotação de frete, emissão de etiquetas dos Correios, rastreamento de objetos e gestão de clientes diretamente no seu sistema. Todas as respostas são em JSON e o servidor utiliza HTTPS obrigatório.

1.1. Autenticação

Todas as chamadas exigem o cabeçalho Authorization com seu token:

http

Authorization: Bearer seu_token_aqui

1.2. Passo a passo para começar

1
Solicite acesso à API
Acesse Integrações → API no painel e clique em Solicitar acesso. Informe nome da empresa e documento (CNPJ ou CPF).
2
Aguarde aprovação do administrador
Você receberá um e-mail assim que sua solicitação for aprovada (em geral em até 1 dia útil).
3
Gere seu token de acesso
Após aprovado, volte a Integrações → API e clique em Gerar novo token. Copie e guarde em local seguro — o token completo só é mostrado uma vez.
4
Teste sua primeira chamada
Use o exemplo abaixo para validar o token consultando /me:
5
Integre nos seus fluxos
Use os endpoints da seção 2 para cotar frete, emitir etiquetas e rastrear pedidos.

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/me" \
  -H "Authorization: Bearer seu_token_aqui"

1.3. Rate limit

O limite padrão é de 60 requisições por minuto por token. Ao atingir o limite, o servidor responde

429 RATE_LIMITED

e os cabeçalhosX-RateLimit-Remaining eX-RateLimit-Reset indicam quando reativar.

2. Endpoints

2.1. Dados do usuário

GET/me

Retorna informações do usuário autenticado pelo token.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/me" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "user": {
    "id": "uuid-do-usuario",
    "name": "João da Silva",
    "email": "joao@empresa.com.br"
  }
}

2.2. Consultar saldo

GET/saldo

Retorna o saldo disponível em reais (BRL) para emissão de etiquetas.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/saldo" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "saldo": 152.40,
  "currency": "BRL"
}

2.3. Cotar frete

POST/frete/cotacao

Calcula o valor e prazo para todos os serviços Correios disponíveis (PAC, SEDEX, etc).

Parâmetros

Nome	Tipo	Obrigatório	Descrição
cep_origem	string	Sim	CEP de origem (8 dígitos).
cep_destino	string	Sim	CEP de destino (8 dígitos).
peso	number	Sim	Peso em kg (máx. 30).
comprimento	number	Não	Comprimento em cm.
largura	number	Não	Largura em cm.
altura	number	Não	Altura em cm.
valor_declarado	number	Não	Valor declarado em reais.

Exemplo de requisição

json

{
  "cep_origem": "01310100",
  "cep_destino: "20040020",
  "peso": 1.5,
  "comprimento": 20,
  "largura": 15,
  "altura": 10
}

Exemplo com cURL

curl

curl -X POST "https://tudoenvio.com.br/api/public/v1/frete/cotacao" \
  -H "Authorization: Bearer seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "cep_origem": "01310100", "cep_destino: "20040020", "peso": 1.5, "comprimento": 20, "largura": 15, "altura": 10 }'

Resposta

json

{
  "cotacoes": [
    { "servico": "PAC", "codigo_servico": "03298", "valor": 18.50, "prazo": 7, "erro": null },
    { "servico": "SEDEX", "codigo_servico": "03220", "valor": 32.90, "prazo": 2, "erro": null }
  ]
}

2.4. Emitir etiqueta

POST/etiquetas

Cria uma nova etiqueta de postagem. O valor é debitado do saldo do usuário.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
servico	string	Sim	Código do serviço (ex: 03220 para SEDEX).
remetente	object	Sim	Dados do remetente (nome, documento, endereço completo).
destinatario	object	Sim	Dados do destinatário (nome, documento, endereço completo).
peso	number	Sim	Peso em kg.
dimensoes	object	Sim	Objeto com altura, largura e comprimento em cm.
valor_declarado	number	Não	Valor declarado em reais.

Exemplo de requisição

json

{
  "servico": "03220",
  "remetente": {
    "nome": "Loja XYZ",
    "documento": "12345678000190",
    "cep": "01310100",
    "logradouro": "Av. Paulista",
    "numero": "1000",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "uf": "SP"
  },
  "destinatario": {
    "nome": "Maria Souza",
    "documento": "12345678900",
    "cep": "20040020",
    "logradouro": "Rua da Quitanda",
    "numero": "50",
    "bairro": "Centro",
    "cidade": "Rio de Janeiro",
    "uf": "RJ"
  },
  "peso": 1.5,
  "dimensoes": { "altura": 10, "largura": 15, "comprimento": 20 }
}

Exemplo com cURL

curl

curl -X POST "https://tudoenvio.com.br/api/public/v1/etiquetas" \
  -H "Authorization: Bearer seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "servico": "03220", "remetente": { "nome": "Loja XYZ", "documento": "12345678000190", "cep": "01310100", "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cidade": "São Paulo", "uf": "SP" }, "destinatario": { "nome": "Maria Souza", "documento": "12345678900", "cep": "20040020", "logradouro": "Rua da Quitanda", "numero": "50", "bairro": "Centro", "cidade": "Rio de Janeiro", "uf": "RJ" }, "peso": 1.5, "dimensoes": { "altura": 10, "largura": 15, "comprimento": 20 } }'

Resposta

json

{
  "etiqueta": {
    "id": "uuid-da-etiqueta",
    "codigo_rastreamento": "BR123456789BR",
    "servico": "SEDEX",
    "status": "emitida",
    "valor": 32.90,
    "url_pdf": "https://..."
  }
}

2.5. Consultar etiqueta

GET/etiquetas/{id}

Retorna os dados de uma etiqueta já emitida.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/etiquetas/{id}" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "etiqueta": {
    "id": "uuid-da-etiqueta",
    "codigo_rastreamento": "BR123456789BR",
    "servico": "SEDEX",
    "status": "emitida",
    "valor": 32.90,
    "created_at": "2026-06-11T02:00:00Z"
  }
}

2.6. Rastrear objeto

GET/rastreamento/{codigo}

Consulta os eventos de rastreio de um código dos Correios.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/rastreamento/{codigo}" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "codigo": "BR123456789BR",
  "eventos": [
    { "data": "2026-06-11T08:30:00Z", "local": "São Paulo / SP", "descricao": "Objeto postado" },
    { "data": "2026-06-12T14:00:00Z", "local": "Rio de Janeiro / RJ", "descricao": "Objeto entregue" }
  ]
}

2.7. Listar clientes

GET/clientes

Retorna a lista de clientes cadastrados pelo usuário.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/clientes" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "clientes": [
    { "id": "uuid", "nome": "Maria Souza", "documento": "12345678900", "email": "maria@email.com" }
  ]
}

2.8. Criar cliente

POST/clientes

Cadastra um novo cliente no catálogo.

Exemplo de requisição

json

{
  "nome": "Maria Souza",
  "documento": "12345678900",
  "email": "maria@email.com",
  "telefone": "11999999999",
  "cep": "20040020",
  "logradouro": "Rua da Quitanda",
  "numero": "50",
  "bairro": "Centro",
  "cidade": "Rio de Janeiro",
  "uf": "RJ"
}

Exemplo com cURL

curl

curl -X POST "https://tudoenvio.com.br/api/public/v1/clientes" \
  -H "Authorization: Bearer seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "nome": "Maria Souza", "documento": "12345678900", "email": "maria@email.com", "telefone": "11999999999", "cep": "20040020", "logradouro": "Rua da Quitanda", "numero": "50", "bairro": "Centro", "cidade": "Rio de Janeiro", "uf": "RJ" }'

Resposta

json

{ "cliente": { "id": "uuid", "nome": "Maria Souza" } }

2.9. Emitir etiqueta com pagamento POS (maquininha)

POST/pos/etiquetas

Fluxo específico para app Android integrado a maquininha de cartão (Cielo/Stone/PagSeguro etc.). Aceita o envio completo + os dados da transação já autorizada pelo SDK nativo — sem exigir saldo prévio. Envie o header `Idempotency-Key` (ou reutilize o NSU) para evitar duplicação em caso de retry.

Exemplo de requisição

json

{
  "envio": { /* mesmo formato de POST /etiquetas */ },
  "pagamento_externo": {
    "nsu": "000123456",
    "tid": "1234567890ABCDEF",
    "bandeira": "Visa",
    "parcelas": 1,
    "valor": 27.90,
    "autorizacao": "A1B2C3"
  }
}

Exemplo com cURL

curl

curl -X POST "https://tudoenvio.com.br/api/public/v1/pos/etiquetas" \
  -H "Authorization: Bearer seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "envio": { /* mesmo formato de POST /etiquetas */ }, "pagamento_externo": { "nsu": "000123456", "tid": "1234567890ABCDEF", "bandeira": "Visa", "parcelas": 1, "valor": 27.90, "autorizacao": "A1B2C3" } }'

Resposta

json

{
  "success": true,
  "etiqueta": {
    "id": "uuid",
    "codigo_rastreamento": "BR123456789BR",
    "servico": "SEDEX",
    "valor": 27.90,
    "etiqueta_pdf_url": "https://...",
    "declaracao_pdf_url": "https://...",
    "recibo_json_url": "/api/public/v1/etiquetas/uuid/recibo-json"
  },
  "idempotente": false
}

2.10. Recibo estruturado (JSON) para impressão local

GET/etiquetas/{id}/recibo-json

Retorna o payload `tudoenvio.recibo/v1` — QR Code, código de rastreio, remetente/destinatário e itens — pronto para a lib de impressão nativa Android (Sunmi, Gertec, PAX).

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/etiquetas/{id}/recibo-json" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "success": true,
  "recibo": {
    "schema": "tudoenvio.recibo/v1",
    "codigo_objeto": "BR123456789BR",
    "qr_code_url": "https://tudoenvio.com.br/rastreio?codigo=BR123456789BR",
    "remetente": { "...": "..." },
    "destinatario": { "...": "..." },
    "itens": [ { "descricao": "Livro", "quantidade": 1, "valor": 50.00 } ],
    "total": 27.90
  }
}

2.11. URLs assinadas dos PDFs da etiqueta

GET/etiquetas/{id}/pdf

Retorna URLs assinadas (válidas por curto período) da etiqueta oficial, declaração de conteúdo e recibo em PDF — útil para reimpressão.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/etiquetas/{id}/pdf" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "success": true,
  "etiqueta_pdf_url": "https://...",
  "declaracao_pdf_url": "https://...",
  "etiqueta_ar_pdf_url": "https://...",
  "recibo_pdf_url": "https://..."
}

2.12. Criar recarga PIX

POST/saldo/recarga

Gera um QR Code PIX para recarga de saldo. Uso opcional — recomendado apenas quando o lojista prefere operar por saldo em vez de cobrar cartão a cada emissão.

Exemplo de requisição

json

{ "valor": 100.00 }

Exemplo com cURL

curl

curl -X POST "https://tudoenvio.com.br/api/public/v1/saldo/recarga" \
  -H "Authorization: Bearer seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "valor": 100.00 }'

Resposta

json

{
  "success": true,
  "recarga_id": "uuid",
  "valor": 100.00,
  "qr_code": "00020126580014BR.GOV.BCB.PIX...",
  "qr_code_base64": "iVBORw0KGgo...",
  "expira_em": "2026-07-28T15:30:00Z"
}

2.13. Consultar status de recarga

GET/saldo/recarga/{id}

Consulta o status atual de uma recarga PIX criada via API.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/saldo/recarga/{id}" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{ "success": true, "recarga": { "id": "uuid", "status": "pago", "valor": 100.00 } }

2.14. Catálogo de embalagens

GET/config/embalagens

Lista embalagens ativas com estoque, para o POS montar o seletor.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/config/embalagens" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{ "success": true, "embalagens": [ { "id": "uuid", "nome": "Caixa P", "preco": 3.50, "estoque": 42 } ] }

2.15. Serviços adicionais (seguro/AR/mão-própria)

GET/config/adicionais

Retorna habilitação e valores dos serviços adicionais para o POS calcular extras.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/config/adicionais" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{
  "success": true,
  "seguro": { "habilitado": true, "percentual": 1.5, "minimo": 0 },
  "mao_propria": { "habilitado": false, "valor": 8.50 },
  "aviso_recebimento": { "habilitado": true, "valor": 8.50 }
}

2.16. Plano de markup do lojista

GET/config/plano

Plano vigente aplicado sobre a cotação para o lojista autenticado.

Exemplo com cURL

curl

curl -X GET "https://tudoenvio.com.br/api/public/v1/config/plano" \
  -H "Authorization: Bearer seu_token_aqui"

Resposta

json

{ "success": true, "plano": { "nome": "Prata", "tipo": "percentual", "valor": 35, "servicos": ["03298","03220"] } }

3. Códigos de erro

Toda resposta de erro segue o formato padrão abaixo:

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Descrição amigável do problema."
  }
}

Código	HTTP	Descrição
UNAUTHORIZED	401	Token ausente, inválido ou revogado.
FORBIDDEN	403	Acesso não autorizado a este recurso.
VALIDATION_ERROR	400	Dados de entrada inválidos.
CLIENT_NOT_FOUND	404	Recurso não encontrado.
INSUFFICIENT_BALANCE	402	Saldo insuficiente para emitir a etiqueta.
RATE_LIMITED	429	Limite de chamadas excedido.
INTERNAL_ERROR	500	Erro interno do servidor.

4. Suporte

Dúvidas ou problemas? Entre em contato em contato@tudoenvio.com.br ou pela página Ajuda.