Documentação para desenvolvedores

Emita etiquetas e acompanhe sua operação por API.

Automatize a emissão de etiquetas com declaração ou NF-e e consulte os recursos que acompanham cada postagem.

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.

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"
}

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

Como evito duplicar uma postagem?

Envie um request_id único para cada operação e confira o resultado antes de repetir uma solicitação. A emissão pode debitar saldo e contratar frete.

Posso emitir com nota fiscal?

Sim. Use tipo_doc_fiscal danfe, a chave correspondente e o documento em Base64 ou por URL HTTPS. Para Jadlog, envie o XML autorizado.

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