Documentação para desenvolvedores

Documentação das APIs CepCerto.

Integre sua loja, ERP ou plataforma com endpoints documentados, limites claros, exemplos de resposta e uma coleção Postman pronta para uso.

Cadastre-se grátis Testar no Postman

Cadastro rápido e acesso pelo painel CepCerto

Teste primeiro em desenvolvimento. Gerar PIX cria uma cobrança; emitir postagem pode debitar saldo e contratar frete; cancelar postagem altera a operação e pode solicitar estorno.

Autenticação e ambientes

As três credenciais têm finalidades diferentes e não são intercambiáveis. Nunca publique tokens em código-fonte, exemplos ou repositórios.

Credencial	Finalidade	Envio
`postage_token`	Cotação operacional, saldo, PIX, postagem, cancelamento, rastreio, logradouro e comprovante.	JSON ou `Authorization: Bearer`, conforme o endpoint.
`consumption_key`	APIs pagas de CEP e frete Correios.	Último segmento das URLs `/ws/...`.
`widget_public_key`	Cotador instalado em sites.	Header `X-CepCerto-Public-Key` e JSON.

Desenvolvimentohttps://dev.cepcerto.com

Produçãohttps://cepcerto.com

Os tokens ficam disponíveis na Área Restrita, no módulo Integração. A chave pública é administrada em Frete no seu site.

API Cálculo de Frete — Correios, Jadlog e Loggi

Consulte preços e prazos com POST /api-cotacao-frete/, usando o token de postagem. A consulta consome a franquia diária de cotação.

Informe o peso em quilogramas e as dimensões em centímetros. Os exemplos abaixo detalham os limites para um ou vários volumes.

Assista ao tutorial de cálculo de frete

Ver todos os vídeos sobre cálculo de frete

Exemplos de cotação

POST01 - Cotar frete (volume único)

{{base_url}}/api-cotacao-frete/

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "cep_remetente": "{{cep_origem}}",
    "cep_destinatario": "{{cep_destino}}",
    "peso": "{{peso}}",
    "altura": "{{altura}}",
    "largura": "{{largura}}",
    "comprimento": "{{comprimento}}",
    "valor_encomenda": "{{valor_encomenda}}"
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "frete": {
        "valor_pac": "18,90",
        "valor_pac_balcao": "24,30",
        "prazo_pac": "até 6 dias",
        "valor_sedex": "29,70",
        "valor_sedex_balcao": "36,10",
        "prazo_sedex": "até 2 dias",
        "valor_jadlog_package": "17,50",
        "prazo_jadlog_package": "até 4 dias",
        "valor_loggi": "19,20",
        "prazo_loggi": "até 3 dias"
    }
}

POST02 - Cotar frete (múltiplos volumes)

{{base_url}}/api-cotacao-frete/

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Regras da encomenda: peso em kg, maior que 0 e até 30 kg; altura, largura e comprimento em cm, maiores que 0 e até 100 cm cada; a soma das três dimensões não pode ultrapassar 200 cm; valor declarado entre R$ 50,00 e R$ 35.000,00. CEPs devem conter 8 dígitos.

Múltiplos volumes: de 1 a 50 tipos de volume; quantidade de cada tipo entre 1 e 999. Cada volume obedece individualmente aos mesmos limites de peso e dimensões. Os valores são multiplicados pela quantidade e somados por serviço; o prazo final é o maior prazo encontrado para o serviço.

Cota Correios, Jadlog e Loggi e consome a franquia diária da API de cotação.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "cep_remetente": "{{cep_origem}}",
    "cep_destinatario": "{{cep_destino}}",
    "valor_encomenda": "150.00",
    "volumes": [
        {
            "peso": "0.5",
            "altura": "10",
            "largura": "15",
            "comprimento": "20",
            "quantidade": 2
        },
        {
            "peso": "1",
            "altura": "20",
            "largura": "20",
            "comprimento": "30",
            "quantidade": 1
        }
    ]
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "frete": {
        "valor_pac": "56,70",
        "prazo_pac": "até 6 dias",
        "valor_sedex": "89,10",
        "prazo_sedex": "até 2 dias"
    }
}

API de postagem e operação

Família autenticada pelo token de postagem. Peso é informado em quilogramas e dimensões em centímetros.

PesoMaior que 0 e até 30 kg

DimensõesCada lado maior que 0 e até 100 cm

SomaAltura + largura + comprimento até 200 cm

Valor declaradoR$ 50,00 a R$ 35.000,00

Método	Endpoint	Finalidade e efeito
POST	`/api-consulta-logradouro/`	Busca por UF, cidade e logradouro; bairro opcional; limite de 1 a 50 por página.
POST	`/api-saldo/`	Consulta somente leitura do saldo da carteira.
POST	`/api-credito/`	Cria PIX de R$ 5,00 a R$ 5.000,00. O saldo entra após confirmação do pagamento.
POST	`/api-postagem-frete/`	Emite etiqueta e pode debitar saldo. Tipos: PAC, SEDEX, Jadlog Package, Jadlog .COM e Loggi.
POST	`/api-cancela-postagem/`	Cancela objeto pertencente ao cliente quando o estado permite e solicita estorno aplicável.
POST	`/api-rastreio/`	Consulta somente leitura de objeto pertencente à conta.
POST	`/api-comprovante-correios/`	Comprovante de objeto Correios entregue; JSON/Base64 ou arquivo; limite de 30/minuto.

Múltiplos volumes

São aceitos de 1 a 50 tipos de volume e quantidade de 1 a 999 por tipo. Cada volume obedece aos limites acima. Valores são multiplicados e somados por serviço; o prazo final é o maior encontrado.

Emissão

Use request_id único para idempotência e não repita o envio. Logística reversa está disponível somente para PAC e SEDEX. A declaração exige produtos com descrição, quantidade e valor.

Novo exemplo completo

Emitir postagem com NF-e

O endpoint é o mesmo da emissão com declaração: POST /api-postagem-frete/. A diferença está no documento fiscal: use tipo_doc_fiscal: "danfe", retire produtos e envie a chave da NF-e com uma única fonte do documento.

Campo	Obrigatório	Regra
`tipo_doc_fiscal`	Sim	Use `danfe`.
`chave_danfe`	Sim	Chave de acesso com exatamente 44 dígitos e correspondente ao XML/PDF enviado.
`documento_fiscal_base64`	Uma das fontes	Conteúdo integral do XML ou PDF convertido em Base64. Limite decodificado de 10 MB.
`documento_fiscal_nome`	Com Base64	Nome com extensão, por exemplo `NFe_<chave>.xml`.
`documento_fiscal_url`	Uma das fontes	Alternativa ao Base64. URL HTTPS pública, porta 443, sem autenticação embutida.

Envie Base64 ou URL, nunca ambos. Para Jadlog, o documento precisa ser o XML autorizado; PDF DANFE não é aceito nessa transportadora.

JSON — documento XML em Base64

{
  "tipo_doc_fiscal": "danfe",
  "chave_danfe": "35260502745658000158550010000118891074417476",
  "documento_fiscal_nome": "NFe_35260502745658000158550010000118891074417476.xml",
  "documento_fiscal_base64": "PD94bWwgdmVyc2lvbj0iMS4wIi4uLg=="
}

Esses quatro campos entram junto com os demais dados de postagem exibidos na requisição completa logo abaixo. O valor Base64 acima está abreviado apenas para leitura.

PHP — ler o XML e montar os campos

function gerarXmlBase64(string $caminhoXml, string $chaveDanfe): array
{
    $chaveDanfe = preg_replace('/\D/', '', $chaveDanfe);
    if (strlen($chaveDanfe) !== 44) {
        throw new Exception('A chave DANFE deve possuir 44 dígitos.');
    }
    if (!is_file($caminhoXml)) {
        throw new Exception('Arquivo XML não encontrado: ' . $caminhoXml);
    }

    $xml = file_get_contents($caminhoXml);
    if ($xml === false || trim($xml) === '') {
        throw new Exception('Não foi possível ler o arquivo XML.');
    }

    return [
        'tipo_doc_fiscal' => 'danfe',
        'chave_danfe' => $chaveDanfe,
        'documento_fiscal_nome' => 'NFe_' . $chaveDanfe . '.xml',
        'documento_fiscal_base64' => base64_encode($xml),
    ];
}

Alternativa — documento por URL

{
  "tipo_doc_fiscal": "danfe",
  "chave_danfe": "35260502745658000158550010000118891074417476",
  "documento_fiscal_url": "https://seu-dominio.com/nfe/nota.xml"
}

A URL deve responder diretamente com um XML autorizado ou PDF DANFE válido. Não use endereço local, IP privado, porta diferente de 443, usuário ou senha na URL.

cURL — envio do JSON completo

curl --request POST 'https://cepcerto.com/api-postagem-frete/' \
  --header 'Content-Type: application/json' \
  --data '{
    "token_cliente_postagem": "SEU_TOKEN",
    "request_id": "pedido-12345",
    "tipo_entrega": "jadlog-dotcom",
    "logistica_reversa": "N",
    "cep_remetente": "01527050",
    "cep_destinatario": "11440001",
    "peso": "1.0",
    "altura": "10",
    "largura": "15",
    "comprimento": "20",
    "valor_encomenda": "150.00",
    "nome_remetente": "Empresa remetente",
    "cpf_cnpj_remetente": "12345678000190",
    "whatsapp_remetente": "11999999999",
    "email_remetente": "remetente@empresa.com",
    "numero_endereco_remetente": "100",
    "nome_destinatario": "Cliente destinatário",
    "cpf_cnpj_destinatario": "12345678909",
    "whatsapp_destinatario": "11988888888",
    "email_destinatario": "cliente@email.com",
    "numero_endereco_destinatario": "200",
    "tipo_doc_fiscal": "danfe",
    "chave_danfe": "35260502745658000158550010000118891074417476",
    "documento_fiscal_nome": "NFe_35260502745658000158550010000118891074417476.xml",
    "documento_fiscal_base64": "BASE64_COMPLETO_DO_XML"
  }'

Requisições completas de postagem e operação

Abra uma requisição para ver a mesma explicação, endpoint, corpo e resposta de sucesso disponíveis na coleção oficial do Postman.

POST03 - Consultar logradouro

{{base_url}}/api-consulta-logradouro/

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

UF (2 letras), cidade e logradouro são obrigatórios. Bairro é opcional. Página começa em 1; limite de resultados por página: 1 a 50. A busca pode retornar correspondências parciais e consome o limite diário da API.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "uf": "SP",
    "cidade": "São Paulo",
    "logradouro": "Avenida Paulista",
    "bairro": "",
    "limite": 20,
    "pagina": 1
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "mensagem": "Endereços encontrados.",
    "consulta": {
        "uf": "SP",
        "cidade": "São Paulo",
        "logradouro": "Avenida Paulista",
        "bairro": ""
    },
    "paginacao": {
        "pagina": 1,
        "limite": 20,
        "total": 1,
        "total_paginas": 1
    },
    "resultados": [
        {
            "cep": "01310100",
            "logradouro": "Avenida Paulista",
            "bairro": "Bela Vista",
            "localidade": "São Paulo",
            "uf": "SP"
        }
    ]
}

POST04 - Consultar saldo

{{base_url}}/api-saldo/

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Consulta somente leitura do saldo atual da carteira. O token vem da variável postage_token do environment.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}"
}

Exemplo de sucesso · HTTP 200

{
    "nome_cliente": "CLIENTE EXEMPLO",
    "saldo_atual": "R$ 100,00",
    "data_requisicao": "31/07/2026 12:00:00"
}

POST05 - Gerar PIX para crédito

{{base_url}}/api-credito/

ATENÇÃO: esta operação cria uma cobrança PIX real em Produção. No Dev, a resposta é sempre fictícia. Valor mínimo R$ 5,00 e máximo R$ 5.000,00, com até 2 casas decimais. Gerar a cobrança não adiciona saldo; o crédito ocorre somente após confirmação do pagamento.

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "valor_credito": "10.00"
}

Exemplo de sucesso · HTTP 200

{
    "nome_cliente": "CLIENTE EXEMPLO",
    "data_requisicao": "31/07/2026 12:00:00",
    "valor": 10,
    "copia_cola": "000201...",
    "qrcode_url": "https://cepcerto.com/qrcode/EXEMPLO",
    "qrcode_img": "https://cepcerto.com/qrcode/EXEMPLO.png"
}

POST06 - Emitir postagem com declaração

{{base_url}}/api-postagem-frete/

ATENÇÃO: esta operação pode debitar saldo e emitir etiqueta real. Use um request_id único para idempotência e não repita o Send. Tipos: pac, sedex, jadlog-package, jadlog-dotcom ou loggi. Logística reversa é aceita somente para PAC e SEDEX. Declaração exige ao menos um produto com descrição, quantidade e valor.

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Regras da encomenda: peso em kg, maior que 0 e até 30 kg; altura, largura e comprimento em cm, maiores que 0 e até 100 cm cada; a soma das três dimensões não pode ultrapassar 200 cm; valor declarado entre R$ 50,00 e R$ 35.000,00. CEPs devem conter 8 dígitos.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "request_id": "postman-{{$timestamp}}",
    "tipo_entrega": "pac",
    "logistica_reversa": "N",
    "cep_remetente": "{{cep_origem}}",
    "cep_destinatario": "{{cep_destino}}",
    "peso": "{{peso}}",
    "altura": "{{altura}}",
    "largura": "{{largura}}",
    "comprimento": "{{comprimento}}",
    "valor_encomenda": "{{valor_encomenda}}",
    "nome_remetente": "{{remetente_nome}}",
    "cpf_cnpj_remetente": "{{remetente_documento}}",
    "whatsapp_remetente": "{{remetente_telefone}}",
    "email_remetente": "{{remetente_email}}",
    "numero_endereco_remetente": "{{remetente_numero}}",
    "complemento_remetente": "",
    "nome_destinatario": "{{destinatario_nome}}",
    "cpf_cnpj_destinatario": "{{destinatario_documento}}",
    "whatsapp_destinatario": "{{destinatario_telefone}}",
    "email_destinatario": "{{destinatario_email}}",
    "numero_endereco_destinatario": "{{destinatario_numero}}",
    "complemento_destinatario": "",
    "tipo_doc_fiscal": "declaracao",
    "produtos": [
        {
            "descricao": "Produto de exemplo",
            "valor": "50.00",
            "quantidade": 1
        }
    ]
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "sucesso": true,
    "mensagem": "Frete Correios confirmado com sucesso.",
    "frete": {
        "freteTipo": "correios_pac",
        "servico": "pac",
        "valor": 18.9,
        "prazo": "até 6 dias",
        "codigoObjeto": "AP000000000BR",
        "pdfUrlEtiqueta": "https://cepcerto.com/postagem/etiqueta/download/EXEMPLO",
        "pdfUrlDCE": "https://cepcerto.com/postagem/etiqueta/documento?id=EXEMPLO"
    }
}

POST07 - Emitir postagem com NF-e (XML Base64)

{{base_url}}/api-postagem-frete/

ATENÇÃO: esta operação pode debitar saldo e emitir etiqueta real. Use um request_id único e não repita o Send.

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Regras da encomenda: peso em kg, maior que 0 e até 30 kg; altura, largura e comprimento em cm, maiores que 0 e até 100 cm cada; a soma das três dimensões não pode ultrapassar 200 cm; valor declarado entre R$ 50,00 e R$ 35.000,00. CEPs devem conter 8 dígitos.

Emissão com NF-e: use `tipo_doc_fiscal: "danfe"`, informe `chave_danfe` com os 44 dígitos da chave de acesso e envie exatamente uma fonte do documento fiscal autorizado: `documento_fiscal_base64` ou `documento_fiscal_url`. No exemplo desta requisição, o XML completo é convertido para Base64 e enviado em `documento_fiscal_base64`; `documento_fiscal_nome` identifica o arquivo, por exemplo `NFe_...xml`. Não envie o prefixo `data:...;base64,` (ele é aceito, mas o Base64 puro é preferível). O documento decodificado pode ter até 10 MB. Para Jadlog, envie obrigatoriamente o XML autorizado; PDF DANFE não é aceito. A chave informada deve corresponder à chave presente no XML.

Exemplo PHP a partir de um arquivo:

```php
$chave = preg_replace('/\D/', '', $chaveDanfe);
if (strlen($chave) !== 44) {
throw new Exception('A chave DANFE deve possuir 44 dígitos.');
}
$xml = file_get_contents('/caminho/nota.xml');
if ($xml === false || trim($xml) === '') {
throw new Exception('Não foi possível ler o arquivo XML.');
}
$dadosNfe = [
'tipo_doc_fiscal' => 'danfe',
'chave_danfe' => $chave,
'documento_fiscal_nome' => 'NFe_' . $chave . '.xml',
'documento_fiscal_base64' => base64_encode($xml),
];
```

Alternativa por URL: remova `documento_fiscal_nome` e `documento_fiscal_base64` e envie `"documento_fiscal_url": "https://seu-dominio.com/nfe/nota.xml"`. A URL deve usar HTTPS público, porta 443, sem usuário/senha e responder com XML autorizado ou PDF DANFE válido.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "request_id": "postman-{{$timestamp}}",
    "tipo_entrega": "pac",
    "logistica_reversa": "N",
    "cep_remetente": "{{cep_origem}}",
    "cep_destinatario": "{{cep_destino}}",
    "peso": "{{peso}}",
    "altura": "{{altura}}",
    "largura": "{{largura}}",
    "comprimento": "{{comprimento}}",
    "valor_encomenda": "{{valor_encomenda}}",
    "nome_remetente": "{{remetente_nome}}",
    "cpf_cnpj_remetente": "{{remetente_documento}}",
    "whatsapp_remetente": "{{remetente_telefone}}",
    "email_remetente": "{{remetente_email}}",
    "numero_endereco_remetente": "{{remetente_numero}}",
    "complemento_remetente": "",
    "nome_destinatario": "{{destinatario_nome}}",
    "cpf_cnpj_destinatario": "{{destinatario_documento}}",
    "whatsapp_destinatario": "{{destinatario_telefone}}",
    "email_destinatario": "{{destinatario_email}}",
    "numero_endereco_destinatario": "{{destinatario_numero}}",
    "complemento_destinatario": "",
    "tipo_doc_fiscal": "danfe",
    "chave_danfe": "{{nfe_key}}",
    "documento_fiscal_nome": "{{nfe_xml_name}}",
    "documento_fiscal_base64": "{{nfe_xml_base64}}"
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "sucesso": true,
    "mensagem": "Frete Jadlog confirmado com sucesso.",
    "frete": {
        "freteTipo": "jadlog_dotcom",
        "servico": "jadlog-dotcom",
        "valor": 18.9,
        "prazo": "até 4 dias",
        "codigoObjeto": "10000000000000",
        "pdfUrlEtiqueta": "https://cepcerto.com/postagem/etiqueta/download/EXEMPLO",
        "pdfUrlDCE": null
    }
}

POST08 - Emitir postagem com múltiplos volumes

{{base_url}}/api-postagem-frete/

ATENÇÃO: esta operação pode debitar saldo e emitir múltiplas etiquetas reais. Use um request_id único e não repita o Send.

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Regras da encomenda: peso em kg, maior que 0 e até 30 kg; altura, largura e comprimento em cm, maiores que 0 e até 100 cm cada; a soma das três dimensões não pode ultrapassar 200 cm; valor declarado entre R$ 50,00 e R$ 35.000,00. CEPs devem conter 8 dígitos.

Múltiplos volumes: de 1 a 50 tipos de volume; quantidade de cada tipo entre 1 e 999. Cada volume obedece individualmente aos mesmos limites de peso e dimensões. Os valores são multiplicados pela quantidade e somados por serviço; o prazo final é o maior prazo encontrado para o serviço.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "request_id": "postman-{{$timestamp}}",
    "tipo_entrega": "pac",
    "logistica_reversa": "N",
    "cep_remetente": "{{cep_origem}}",
    "cep_destinatario": "{{cep_destino}}",
    "valor_encomenda": "{{valor_encomenda}}",
    "nome_remetente": "{{remetente_nome}}",
    "cpf_cnpj_remetente": "{{remetente_documento}}",
    "whatsapp_remetente": "{{remetente_telefone}}",
    "email_remetente": "{{remetente_email}}",
    "numero_endereco_remetente": "{{remetente_numero}}",
    "complemento_remetente": "",
    "nome_destinatario": "{{destinatario_nome}}",
    "cpf_cnpj_destinatario": "{{destinatario_documento}}",
    "whatsapp_destinatario": "{{destinatario_telefone}}",
    "email_destinatario": "{{destinatario_email}}",
    "numero_endereco_destinatario": "{{destinatario_numero}}",
    "complemento_destinatario": "",
    "tipo_doc_fiscal": "declaracao",
    "produtos": [
        {
            "descricao": "Produto de exemplo",
            "valor": "50.00",
            "quantidade": 1
        }
    ],
    "volumes": [
        {
            "peso": "0.5",
            "altura": "10",
            "largura": "15",
            "comprimento": "20",
            "quantidade": 2
        },
        {
            "peso": "1",
            "altura": "20",
            "largura": "20",
            "comprimento": "30",
            "quantidade": 1
        }
    ]
}

Exemplo de sucesso · HTTP 200

{
    "status": "pendente",
    "sucesso": false,
    "mensagem": "Postagem recebida, aguardando conclusão da etiqueta.",
    "frete": {
        "freteTipo": "correios_pac",
        "servico": "pac",
        "codigoObjeto": "",
        "pdfUrlEtiqueta": null
    }
}

POST09 - Cancelar postagem

{{base_url}}/api-cancela-postagem/

ATENÇÃO: operação destrutiva. O código deve pertencer ao cliente autenticado. Cancela quando o estado da postagem e a transportadora permitem e solicita o estorno aplicável; repetir o cancelamento pode retornar erro de regra de negócio.

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "codigo_objeto": "{{tracking_code}}"
}

Exemplo de sucesso · HTTP 200

{
    "sucesso": true,
    "nome_cliente": "CLIENTE EXEMPLO",
    "saldo_anterior": "R$ 81,10",
    "valor_creditado": "R$ 18,90",
    "saldo_atual": "R$ 100,00",
    "mensagem": "Objeto AP000000000BR cancelado com sucesso!"
}

POST10 - Rastrear objeto

{{base_url}}/api-rastreio/

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Consulta somente leitura. O código deve pertencer ao cliente autenticado. Transportadora é opcional; quando omitida, o sistema tenta identificar pelo código e pelos dados internos.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "codigo_objeto": "{{tracking_code}}",
    "transportadora": ""
}

Exemplo de sucesso · HTTP 200

{
    "sucesso": true,
    "mensagem": "OK",
    "objeto": "AP000000000BR",
    "transportadora": "Correios",
    "dt_prevista": {
        "texto": "05/08/2026",
        "iso_inicio": "2026-08-05T23:59:59-03:00",
        "iso_fim": "2026-08-05T23:59:59-03:00"
    },
    "eventos": [
        {
            "data_br": "31/07/26 10:00",
            "descricao": "Objeto postado",
            "detalhe": "",
            "unidade": {
                "nome": "Agência",
                "cidade": "São Paulo",
                "uf": "SP",
                "tipo": "AGÊNCIA"
            },
            "entregue": false
        }
    ]
}

POST11 - Comprovante Correios em JSON/Base64

{{base_url}}/api-comprovante-correios/

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Somente para objeto Correios entregue e pertencente ao cliente autenticado. Código no padrão de rastreio Correios. Formato json retorna nome, MIME type e imagem em Base64. Limite de 30 consultas por minuto; pode retornar 503 quando os Correios estiverem indisponíveis.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "codigo_rastreio": "{{tracking_code}}",
    "formato": "json"
}

Exemplo de sucesso · HTTP 200

{
    "sucesso": true,
    "mensagem": "OK",
    "objeto": "AP000000000BR",
    "nome_arquivo": "comprovante-entrega-AP000000000BR.jpg",
    "content_type": "image/jpeg",
    "comprovante_base64": "/9j/4AAQSkZJRgABAQ..."
}

POST12 - Baixar comprovante Correios

{{base_url}}/api-comprovante-correios/

Usa o token de postagem do cliente, diferente da chave dos planos de consumo. Nunca publique o token.

Mesmas regras do comprovante JSON: objeto Correios entregue, pertencente ao cliente e limite de 30/minuto. Retorna JPG ou PNG binário; use Send and Download para não corromper o arquivo.

Headers

Nome	Valor
`Content-Type`	`application/json`

Corpo JSON

{
    "token_cliente_postagem": "{{postage_token}}",
    "codigo_rastreio": "{{tracking_code}}",
    "formato": "arquivo"
}

API Cálculo de Frete — Balcão e Desconto CepCerto

Preço de balcão é o preço oficial cobrado diretamente pelos Correios. Na mesma resposta, a API apresenta o preço CepCerto com desconto e a economia disponível para PAC e SEDEX. Quando elegível, apresenta também Mini Envios, disponível somente pelo CepCerto.

Ver a página exclusiva desta API

Endpoint JSON

https://cepcerto.com/ws/json-frete/cep_origem/cep_destino/peso_gramas/altura_cm/largura_cm/comprimento_cm/sua_chave

Endpoint XML

https://cepcerto.com/ws/xml-frete/cep_origem/cep_destino/peso_gramas/altura_cm/largura_cm/comprimento_cm/sua_chave

Parâmetro	Como enviar
`cep_origem`	CEP com 8 dígitos. O hífen é aceito e removido automaticamente.
`cep_destino`	CEP com 8 dígitos. O hífen é aceito e removido automaticamente.
`peso_gramas`	Peso maior que zero e no máximo 30.000 gramas. Exemplo: envie `1000` para 1 kg.
`altura_cm`	Altura maior que zero e no máximo 100 cm.
`largura_cm`	Largura maior que zero e no máximo 100 cm.
`comprimento_cm`	Comprimento maior que zero e no máximo 100 cm.
Soma das dimensões	`altura_cm + largura_cm + comprimento_cm` não pode ultrapassar 200 cm.
`sua_chave`	Chave de consumo disponível na Área Restrita.

Compatibilidade: integrações antigas que enviam peso sem unidade entre 0,1 e 30 continuam sendo interpretadas em quilogramas. Para novas integrações, envie sempre o peso em gramas.

Exemplo JSON

GET https://cepcerto.com/ws/json-frete/01527050/11440001/300/4/16/24/SUA_CHAVE

Retorno JSON

{
  "ceporigem": "01527050",
  "cepdestino": "11440001",
  "peso_gramas": 300,
  "altura_cm": 4,
  "largura_cm": 16,
  "comprimento_cm": 24,
  "valorpac": "25,80",
  "valorpac_desconto_cepcerto": "21,34",
  "economiapac_cepcerto": "4,46",
  "prazopac": "6",
  "valorsedex": "27,60",
  "valorsedex_desconto_cepcerto": "25,80",
  "economiasedex_cepcerto": "1,80",
  "prazosedex": "2",
  "valorminienvios_cepcerto": "14,90",
  "prazominienvios_cepcerto": "7 dias"
}

Regras do Mini Envios

Mini Envios é oferecido somente pelo CepCerto e não possui preço de balcão. Seus campos de valor e prazo aparecem apenas quando estiver disponível para a rota e o pacote tiver até 300 g, altura até 4 cm, largura até 16 cm, comprimento até 24 cm, valor declarado até R$ 100,00, sem AR, sem Mão Própria e com destino em outra cidade.

Exemplo XML

GET https://cepcerto.com/ws/xml-frete/01527050/11440001/300/4/16/24/SUA_CHAVE

Retorno XML

<xml>
  <ceporigem>01527050</ceporigem>
  <cepdestino>11440001</cepdestino>
  <peso_gramas>300</peso_gramas>
  <altura_cm>4</altura_cm>
  <largura_cm>16</largura_cm>
  <comprimento_cm>24</comprimento_cm>
  <valorpac>25,80</valorpac>
  <valorpac_desconto_cepcerto>21,34</valorpac_desconto_cepcerto>
  <economiapac_cepcerto>4,46</economiapac_cepcerto>
  <prazopac>6</prazopac>
  <valorsedex>27,60</valorsedex>
  <valorsedex_desconto_cepcerto>25,80</valorsedex_desconto_cepcerto>
  <economiasedex_cepcerto>1,80</economiasedex_cepcerto>
  <prazosedex>2</prazosedex>
  <valorminienvios_cepcerto>14,90</valorminienvios_cepcerto>
  <prazominienvios_cepcerto>7 dias</prazominienvios_cepcerto>
</xml>

Frete no seu site (Widget)

O SDK incorpora o cotador em páginas HTML, lojas virtuais e sistemas. A chave pública deve estar ativa e o domínio ou IPv4 de origem precisa estar autorizado no painel.

<script src="https://cepcerto.com/widget_frete/"
  data-public-key="SUA_CHAVE_PUBLICA"></script>

Método	Endpoint	Finalidade
POST	`/widget_frete/api/acesso`	Valida chave, origem, configuração e consumo.
POST	`/widget_frete/api/cotacao`	Calcula as opções configuradas na conta.
GET	`/widget_frete/`	Carrega o SDK JavaScript.
GET	`/widget_frete/estilo.css`	Carrega os estilos oficiais.

As regras de pacote são as mesmas da cotação operacional: até 30 kg, lados até 100 cm, soma até 200 cm e valor declarado de R$ 50,00 a R$ 35.000,00. Contas premium podem autorizar até 10 domínios ou IPs.

Requisições completas do widget

POST01 - Validar acesso e carregar configuração

{{base_url}}/widget_frete/api/acesso

Endpoint utilizado pelo SDK. A chave pública vem de widget_public_key no environment. A chave deve estar ativa e o host de Origin deve estar cadastrado no painel.

Headers

Nome	Valor
`X-CepCerto-Public-Key`	`{{widget_public_key}}`
`Origin`	`{{widget_origin}}`
`Content-Type`	`application/json`

Corpo JSON

{
    "public_key": "{{widget_public_key}}"
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "cliente": {
        "id_clie": 123,
        "nome_cliente": "CLIENTE EXEMPLO"
    },
    "modo": "conta",
    "configuracao": {
        "titulo": "Calcule seu frete",
        "servicos": "pac-desconto,sedex-desconto,loggi"
    },
    "consumo": {
        "restante": 499
    }
}

POST02 - Cotar pelo widget

{{base_url}}/widget_frete/api/cotacao

Os parâmetros vêm do environment selecionado. Cota conforme os serviços e campos configurados na conta. O domínio/IP precisa estar autorizado. Regras da encomenda: peso em kg, maior que 0 e até 30 kg; altura, largura e comprimento em cm, maiores que 0 e até 100 cm cada; a soma das três dimensões não pode ultrapassar 200 cm; valor declarado entre R$ 50,00 e R$ 35.000,00. CEPs devem conter 8 dígitos.

Headers

Nome	Valor
`X-CepCerto-Public-Key`	`{{widget_public_key}}`
`Origin`	`{{widget_origin}}`
`Content-Type`	`application/json`

Corpo JSON

{
    "public_key": "{{widget_public_key}}",
    "cep_remetente": "{{cep_origem}}",
    "cep_destinatario": "{{cep_destino}}",
    "peso": "{{peso}}",
    "altura": "{{altura}}",
    "largura": "{{largura}}",
    "comprimento": "{{comprimento}}",
    "valor_encomenda": "{{valor_encomenda}}"
}

Exemplo de sucesso · HTTP 200

{
    "status": "sucesso",
    "modo": "conta",
    "cliente": {
        "id_clie": 123,
        "nome_cliente": "CLIENTE EXEMPLO"
    },
    "enderecos": {
        "origem": {
            "cep": "01527050",
            "localidade": "São Paulo",
            "uf": "SP"
        },
        "destino": {
            "cep": "11440001",
            "localidade": "Guarujá",
            "uf": "SP"
        }
    },
    "cotacoes": [
        {
            "transportadora": "Correios",
            "servico": "PAC CepCerto com desconto",
            "valor": "18,90",
            "prazo": "até 6 dias"
        }
    ],
    "consumo": {
        "restante": 498
    }
}

GET03 - SDK JavaScript

{{base_url}}/widget_frete/

Retorna o SDK JavaScript. Instalação: <script src="https://cepcerto.com/widget_frete/" data-public-key="SUA_CHAVE"></script>.

GET04 - CSS do widget

{{base_url}}/widget_frete/estilo.css

Folha de estilos carregada automaticamente pelo SDK.

Respostas, erros e boas práticas

HTTP	Significado
`200`	Operação aceita ou concluída.
`400`	JSON ou requisição inválida.
`401`	Credencial, domínio ou origem não autorizada.
`404`	Recurso não encontrado.
`405`	Método HTTP não permitido.
`422`	Campo ou regra de negócio inválida.
`429`	Limite ou franquia excedida.
`500/503`	Indisponibilidade interna ou do fornecedor.

Use HTTPS e mantenha tokens somente no servidor.
Implemente timeout, registro de erros e repetição controlada.
Não repita emissão ou PIX sem conferir o resultado anterior.
Valide HTTP e o corpo JSON/XML; resposta documentada não significa sucesso funcional.

Regras por endpoint

Unidades, limites, campos obrigatórios, autenticação, consumo e códigos HTTP.

Teste antes de publicar

Use o ambiente de desenvolvimento e valide respostas antes de operar em produção.

Coleção Postman

Importe requisições, exemplos e environments oficiais para começar rapidamente.

Dúvidas frequentes

Tudo o que você precisa saber

Qual credencial devo usar?

Use o token de postagem para cotação operacional, saldo, PIX, emissão, cancelamento, rastreio e comprovantes; use a chave de consulta nas APIs /ws; e use a chave pública apenas no widget de frete.

Existe ambiente de desenvolvimento?

Sim. Valide URLs e formatos em dev.cepcerto.com antes de usar produção. PIX, emissão e cancelamento podem alterar dados e devem ser executados apenas com autorização.

Onde encontro os tokens?

Entre na Área Restrita e abra Integração. A chave pública do widget fica no módulo Frete no seu site.

A documentação também está no Postman?

Sim. A coleção oficial inclui requisições, exemplos de sucesso, ambientes e testes para validar sua integração.

Comece agora

Economize tempo e organize seus envios com o CepCerto.

Compare fretes, gere etiquetas e acompanhe suas encomendas em uma única plataforma.

Criar minha conta grátis