Introdução API

    API Endpoint

    https://admin.fretebarato.com/{{plataforma}}/{{method}}/json/v1

Bem-vindo à documentação da API da Frete Barato.

A API do Frete Barato é utilizada por diversas plataformas de e-commerce. Com esta API viabilizamos a integração junto à Plataformas, Marketplaces, ERPs, Hubs, Transportadoras e empresas do ramo de transportes.

A integração com o Frete Barato é gratuita, não cobramos taxas ou mensalidades pela utilização da nossa API. Agimos dessa forma justamente para facilitar a vida de nossos usuários ao integrarem com nossos serviços, junto aos fluxos de seus sistemas.

Caso você seja um cliente Frete Barato e queira apenas utilizar os nossos serviços dentro do seu e-commerce, verifique primeiro se sua plataforma já possui integração com nosso sistema. Se ainda não possuir, entre em contato conosco para que possamos analisar a viabilidade de uma parceria para integração.

Autenticação API

                
    # Exemplo Curl
    curl 
    -X GET https://admin.fretebarato.com/{{plataforma}}/{{method}}/v1/json 
    -H "Authorization: Bearer xxxxxxxxxxxx" 
    curl \
                
                
    $url = "https://admin.fretebarato.com/{{plataforma}}/{{method}}/v1/json";

    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

    $headers = array(
    "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxx",
    );
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

O processo de autenticação é bastante simples

O cliente necessitará apenas de sua URL de autenticação fornecida pela equipe comercial da Frete Barato, contendo o “Customer Token” (token do cliente), como o exemplo abaixo:

https://admin.fretebarato.com/{{plataforma}}/{{method}}/v1/json/{customer_id}

É de suma importância que o campo de callback seja idêntico a URL de callback de retorno da sua aplicação. Caso este campo esteja diferente, nossa API irá retornar Client invalid impedindo a autorização do aplicativo.

Também disponibilizamos um fluxograma que poderá lhe auxiliar a visualizar este processo, assim como servir de base para que você adapte da melhor maneira ao fluxo de seu sistema.

Key	Value
Authorization	Bearer {{token}}
User-Agent	Aplicação (email para contato técnico)

Cotações

                
    # Exemplo Curl
    curl 
    -X GET https://admin.fretebarato.com/lojaintegrada/price/v1/json/{{customer_id}}
    -H "Authorization: Bearer xxxxxxxxxxxx" 
    curl \

    curl 
    -X POST https://admin.fretebarato.com/lojaintegrada/price/v1/json/{{customer_id}} 
    -H "Authorization: Bearer xxxxxxxxxxxx" 
    -H "Content-Type: application/json" 
    -d "{"zipcode":"06652030",
         "amount":125.82,
         "skus":[
                 {"id":149353786,
                  "product_id":21888010,
                  "sku":"OC928237",
                  "price":129.9,
                  "quantity":1,
                  "length":1,
                  "width":1,
                  "height":1,
                  "weight":0.1}]
        }"
                
    
    # Abaixo um exemplo (Payload):
    {
        "zipcode": "83324130",
        "amount": 543.23,
        "skus": [
            {
            "sku": "77214501",
            "price": 21.0382,
            "quantity": 10,
            "length": 8,
            "width": 3,
            "height": 2,
            "weight": 0.035
            },
            {
            "sku": "77214601",
            "price": 24.9374,
            "quantity": 10,
            "length": 9,
            "width": 6,
            "height": 3,
            "weight": 0.055
            }]
    }
                

                
    # Abaixo um exemplo (Response):
    {"quotes": [
        {"name": "Smart2C",
            "service": "Smart2C",
            "price": 42.02,
            "days": 6,
            "quote_id": 5,
            "time_payload": "17.84"
            }, {
            "name": "GFL",
            "service": "GFL",
            "price": 21.16,
            "days": 2,
            "quote_id": 3,
            "time_payload": "17.84"
            }
        ]
    }

Os fretes podem ser calculados informando uma lista de produtos e seus respectivos parâmetros, fazendo com que sejam montados pacotes de acordo com os limites de cada serviços das transportadoras.

Os dados dos produtos devem conter suas informações unitárias, sendo que as dimensões devem ser enviadas em centímetros (cm) e o peso em quilogramas (kg).

Para solicitar cotação é necessário fazer a chamada do endpoint Authorize e customer_ID (que identifica o cliente solicitante e seu respectivo CEP de origem)

Payload:

Parâmetros

Parâmetro	Tipo	Obrigatório	Observação
zipcode	Numérico	Sim	Deve conter exatamente 8 caracteres numéricos
amount	Numérico	Sim	Pode conter até 2 casas decimais
skus	Array	Sim	quantity, lenght, width, height, weight

Detalhe SKUS (Array)

Parâmetro	Tipo	Obrigatório	Observação
sku	String	Sim
quantity	Numérico	Sim	Pode conter apenas números naturais
lenght	Numérico	Sim	Pode conter apenas números naturais
width	Numérico	Sim	Pode conter apenas números naturais
height	Numérico	Sim	Pode conter apenas números naturais
weight	Numérico	Sim	Pode conter até 3 casas decimais

Response:

Parâmetros

Parâmetro	Tipo	Comportamento
name	Alfanumérico	Retorna o nome da transportadora.
service	Alfanumérico	Retorna o nome do serviço cadastrado para o cliente solicitante, dentro da transportadora (o cliente pode ter mais de um serviço cadastrado para a mesma transportadora).
price	Alfanumérico	Retorna o preço do serviço com até duas casas decimais.
days	Numérico	Retorna o prazo do frete em dias (apenas números naturais)..
quote_id	Numérico	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
time_payload	Numérico	Retorna o tempo de carregamento dos parâmetros na API. Campo numérico com até duas casas decimais..

Tabela de Erros:

Response	Tipo	Mensagem
400	bad request
401	unauthorized
403	forbidden
404
405	method not allowed
406	not acceptable

Ocorrências

    Tracking

    https://admin.fretebarato.com/{{plataforma}}/tracking/v1/json/{{customer_id}}

    
    # Abaixo um exemplo (Response):
    {
    "invoice": {
        "nota_fiscal_id": "99999999999999999999999999999999999999999999",
        "texto": "SOLICITACAO EM ROTA",
        "dataOcorrencia": "2024-02-28T07:12:00",
        "ocorrenciaCodigo": "02",
        "dataOcorrenciaPrev": "2024-02-29T00:00:00",
        "dataOcorrenciaEntrega": "2024-02-28T07:12:00",
        "trackCode": "ONT000000000",
        "timeline": [
        {
            "texto": "TRANSFERENCIA DE VOLUMES PARA ENTREGA",
            "data": "2024-02-27T21:37:00",
            "ocorrenciaCodigo": "32"
        }, 
        {
            "texto": "RECEBIMENTO DE TRANSFERENCIA ENTRE UNIDADES",
            "data": "2024-02-28T04:50:00",
            "ocorrenciaCodigo": "17"
        }, 
        {
            "texto": "SOLICITACAO EM ROTA",
            "data": "2024-02-28T07:12:00",
            "ocorrenciaCodigo": "02"
        }],
        "fiscal": {
            "nota_fiscal_id": "99999999999999999999999999999999999999999999",
            "numero": "30822",
            "pedido": "54874",
            "serie": "1",
            "data": "2024-02-26T17:07:27"
        },
        "transporte": {
            "cnpj": "23820639001352"
        },
        "destino": {
            "nome": "Bruno",
            "cpfcnpj": "00000000000",
            "email": "contato@fretebarato.com",
            "address": {
                "cep": "04202010",
                "uf": "sp",
                "cidade": "Sao Paulo"
            }
        },
        "emitente": {
            "cnpj": "31913883000154",
            "razao_social": "Frete Barato",
            "nome_fantasia": "Frete Barato"
        }
    }
}

Payload:

Header

Key	Value
Authorization	Bearer {{token}}
User-Agent	Aplicação (email para contato técnico)

Payload (Número do pedido)

Parâmetro	Tipo	Obrigatório	Observação
cnpj	Numérico	Sim	Deve conter exatamente 14 caracteres numéricos
numero_pedido	Numérico	Sim

Payload (Número Nota Fiscal)

Parâmetro	Tipo	Obrigatório	Observação
cnpj	Numérico	Sim	Deve conter exatamente 14 caracteres numéricos
numero_nota_fiscal	Numérico	Sim

Payload (Chave Nota Fiscal)

Parâmetro	Tipo	Obrigatório	Observação
nota_fiscal_id (Chave)	Numérico	Sim	Deve conter exatamente 44 caracteres numéricos
cnpj	Numérico	Não	Deve conter exatamente 14 caracteres numéricos

Nota Fiscal (Invoice)

    API Endpoint

    https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}

O endpoint de Invoice foi desenvolvido para receber e processar Notas Fiscais Eletrônicas (NF-e) em formato Base64.

Esta API permite que sistemas externos enviem documentos fiscais XML codificados em Base64, garantindo integridade, segurança e rastreabilidade no processo de recebimento.

O sistema realiza validações rigorosas em todas as etapas do processo, desde a estrutura do payload até a validação do conteúdo do documento decodificado.

Envio de Nota Fiscal (Push)

                
    # Exemplo Curl
    curl -X POST https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}} \
    -H "Authorization: Bearer xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
        "request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
        "created_at": "2025-10-29T15:12:34Z",
        "document_meta": {
            "type": "nf-e",
            "model": "55",
            "nota_fiscal_id": "35150000000000000000000000000000000061234567"
        },
        "document_encoding": {
            "format": "base64",
            "mimetype": "application/xml"
        },
        "document_payload": {
            "data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
        }
    }'
                

                
    # Exemplo PHP
    $url = "https://admin.fretebarato.com/invoice/push/v1/base64/{{customer_token}}";

    $payload = array(
        "request_id" => "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
        "created_at" => "2025-10-29T15:12:34Z",
        "document_meta" => array(
            "type" => "nf-e",
            "model" => "55",
            "nota_fiscal_id" => "35150000000000000000000000000000000061234567"
        ),
        "document_encoding" => array(
            "format" => "base64",
            "mimetype" => "application/xml"
        ),
        "document_payload" => array(
            "data" => base64_encode($xmlContent)
        )
    );

    $curl = curl_init($url);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

    $headers = array(
        "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type: application/json"
    );
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($payload));

    $response = curl_exec($curl);
    curl_close($curl);

Request Payload:

                
    # Estrutura Completa do Payload:
    {
        "request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
        "created_at": "2025-10-29T15:12:34Z",
        "document_meta": {
            "type": "nf-e",
            "model": "55",
            "nota_fiscal_id": "35150000000000000000000000000000000061234567"
        },
        "document_encoding": {
            "format": "base64",
            "mimetype": "application/xml"
        },
        "document_payload": {
            "data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4..."
        }
    }

Response de Sucesso:

                
    # Response HTTP 200:
    {
        "success": true,
        "message": "Invoice received successfully (Base64 format)",
        "data": {
            "request_id": "01HZQK3F2N8PYVJ9KQ6R4WXM5T",
            "document_meta": {
                "type": "nf-e",
                "model": "55",
                "nota_fiscal_id": "35150000000000000000000000000000000061234567"
            },
            "document_encoding": {
                "format": "base64",
                "mimetype": "application/xml"
            },
            "document_size": 15420,
            "customer_code": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4",
            "received_at": "2025-10-29 15:12:35",
            "processed_at": "2025-10-29 15:12:35"
        }
    }

Header de Autenticação:

Key	Value	Observação
Authorization	Bearer {{token}}	Token de autenticação fornecido pela equipe Frete Barato
Content-Type	application/json	Obrigatório para envio de payload JSON
User-Agent	Aplicação (email para contato técnico)	Opcional, mas recomendado para identificação

Parâmetros do Payload:

Campos de Primeiro Nível

Parâmetro	Tipo	Obrigatório	Observação
request_id	String	Sim	Identificador único da requisição (UUID ou ULID). Deve ter entre 20 e 36 caracteres
created_at	String	Sim	Data/hora de criação no formato ISO 8601 (ex: 2025-10-29T15:12:34Z)
document_meta	Object	Sim	Objeto contendo metadados do documento fiscal
document_encoding	Object	Sim	Objeto contendo informações de codificação do documento
document_payload	Object	Sim	Objeto contendo o documento codificado em Base64

Campos do Objeto "document_meta"

Parâmetro	Tipo	Obrigatório	Observação
type	String	Sim	Tipo do documento fiscal. Valores aceitos: "nf-e" (Nota Fiscal Eletrônica)
model	String	Sim	Modelo do documento fiscal (ex: "55" para NF-e)
nota_fiscal_id	String	Sim	Chave de acesso da NF-e. Deve conter exatamente 44 caracteres numéricos

Campos do Objeto "document_encoding"

Parâmetro	Tipo	Obrigatório	Observação
format	String	Sim	Formato de codificação. Atualmente aceito apenas: "base64"
mimetype	String	Sim	Tipo MIME do documento original. Valores aceitos: "application/xml", "text/xml"

Campos do Objeto "document_payload"

Parâmetro	Tipo	Obrigatório	Observação
data	String	Sim	Documento fiscal codificado em Base64. Após decodificação, deve ter no mínimo 100 bytes

Parâmetros do Response:

Parâmetro	Tipo	Comportamento
success	Boolean	Indica se a requisição foi processada com sucesso (true/false)
message	String	Mensagem descritiva sobre o resultado do processamento
data	Object	Objeto contendo detalhes do documento processado (presente apenas em caso de sucesso)
data.request_id	String	Retorna o identificador único da requisição enviada
data.document_meta	Object	Retorna os metadados do documento processado
data.document_encoding	Object	Retorna as informações de codificação do documento
data.document_size	Numeric	Retorna o tamanho do documento decodificado em bytes
data.customer_code	String	Retorna o código identificador do cliente solicitante
data.received_at	String	Data/hora de recebimento do documento no formato Y-m-d H:i:s
data.processed_at	String	Data/hora de processamento do documento no formato Y-m-d H:i:s

Validações Realizadas:

A API realiza validações rigorosas em múltiplas camadas:

Tipo de Validação	Descrição	Erro Retornado
Autenticação	Valida Bearer Token no header Authorization	401 - Authentication failure
Dispatcher	Valida versão da API (v1) e formato (base64)	401 - Authentication failure / Only base64 format is supported
Token Cliente	Valida se o token do cliente possui 32 caracteres	401 - Authentication failure
Cliente Existente	Verifica se o cliente existe na base de dados	404 - Customer not found
Estrutura JSON	Valida se todos os campos obrigatórios estão presentes	400 - Field [campo] is required
Request ID	Valida se é um UUID/ULID válido (20-36 caracteres)	400 - Field [request_id] must be a valid UUID or ULID
Data ISO 8601	Valida formato de data created_at	400 - Field [created_at] must be a valid ISO 8601 datetime
Tipo Documento	Valida se o tipo é "nf-e"	400 - Field [document_meta.type] must be one of: nf-e
Formato Encoding	Valida se o formato é "base64"	400 - Field [document_encoding.format] must be "base64"
Mimetype	Valida se é application/xml ou text/xml	400 - Field [document_encoding.mimetype] must be one of: ...
Chave NF-e	Valida se possui exatamente 44 caracteres numéricos	400 - Field [document_meta.nota_fiscal_id] must be exactly 44 characters
Base64 Válido	Valida se o Base64 pode ser decodificado	400 - Invalid base64 document format
Documento Vazio	Valida se documento decodificado não está vazio	400 - Decoded document is empty
Tamanho Mínimo	Valida se documento decodificado possui mínimo 100 bytes	400 - Decoded document is too small (minimum 100 bytes)
Conteúdo vs Mimetype	Valida se conteúdo corresponde ao mimetype declarado	400 - Document content does not match declared mimetype

Tabela de Códigos de Resposta:

Response	Tipo	Mensagem	Descrição
200	success	Invoice received successfully (Base64 format)	Nota fiscal recebida e processada com sucesso
400	bad request	Field [campo] is required / Invalid params	Parâmetros ausentes, inválidos ou fora do padrão esperado
401	unauthorized	Authentication failure	Falha na autenticação: token inválido ou versão incorreta da API
403	forbidden	Access denied	Acesso negado ao recurso solicitado
404	not found	Customer not found	Cliente não encontrado na base de dados
406	not acceptable	Invalid Params (JSON)	Estrutura JSON inválida ou malformada
500	internal server error	Internal error	Erro interno do servidor durante o processamento

Exemplos de Erros:

                
    # Erro 400 - Campo obrigatório ausente:
    {
        "message": "Field [request_id] is required",
        "code": 400
    }

    # Erro 400 - Chave NF-e inválida:
    {
        "message": "Field [document_meta.nota_fiscal_id] must be exactly 44 characters",
        "code": 400
    }

    # Erro 401 - Falha na autenticação:
    {
        "message": "Authentication failure",
        "code": 401
    }

    # Erro 404 - Cliente não encontrado:
    {
        "message": "Customer not found",
        "code": 404
    }

    # Erro 400 - Base64 inválido:
    {
        "message": "Invalid base64 document format in [document_payload.data]",
        "code": 400
    }

    # Erro 400 - Conteúdo não corresponde ao mimetype:
    {
        "message": "Document content does not match declared mimetype (XML expected)",
        "code": 400
    }

Boas Práticas:

Request ID Único: Sempre gere um identificador único (UUID v4 ou ULID) para cada requisição. Isso facilita rastreamento e debug.
Timestamp Preciso: Utilize formato ISO 8601 com timezone (ex: 2025-10-29T15:12:34Z) para garantir precisão temporal.
Validação Prévia: Valide a estrutura do XML antes de codificar em Base64 para evitar erros desnecessários.
Chave de Acesso: Certifique-se de que a chave de 44 caracteres corresponde exatamente à chave presente no XML da NF-e.
Mimetype Correto: Declare o mimetype correto (application/xml ou text/xml).
Tratamento de Erros: Implemente retry logic para erros temporários (500) e tratamento adequado para erros de validação (400).
Logs e Auditoria: Mantenha logs detalhados das requisições usando o request_id como chave de rastreamento.
Segurança: Nunca exponha o Bearer Token em logs ou sistemas de monitoramento.

Fluxo de Processamento:

O sistema segue um fluxo estruturado de processamento:

Recepção: API recebe o payload JSON com documento em Base64
Autenticação: Valida Bearer Token e credenciais do cliente
Validação Estrutural: Verifica todos os campos obrigatórios e seus formatos
Decodificação: Decodifica o documento Base64 para formato original
Validação de Conteúdo: Verifica se o conteúdo corresponde ao mimetype declarado
Processamento: Executa regras de negócio e persistência dos dados
Resposta: Retorna JSON com resultado do processamento

Endpoint de Informações da API:

                
    # Consultar informações sobre a API Invoice
    curl -X GET https://admin.fretebarato.com/invoice/ \
    -H "Authorization: Bearer xxxxxxxxxxxx"

Este endpoint retorna informações detalhadas sobre a API, incluindo versão, endpoints disponíveis, estrutura de payload e códigos de resposta.