Cadastro

Cadastre pedidos na API Frete Barato antes da emissão da NF-e.

O endpoint de create cadastra o pedido na Frete Barato antes de a NF-e existir. O pedido aparece no painel desde o cadastro, com o ícone do Frete Barato que identifica os pedidos criados por esta API.

O destino pode ir no cadastro. Sem esses campos, o pedido nasce sem endereço e a NF-e preenche o destino no envio da nota fiscal com o order_code. A transportadora também pode ir neste cadastro. Sem os campos de transporte, o pedido nasce sem esses dados; o preenchimento ou a mudança posterior é a edição da nota fiscal.

A resposta retorna o order_code, identificador do pedido na Frete Barato. Guarde esse valor: ele é usado na atualização de status e no envio da nota fiscal.

Endpoint

https://admin.fretebarato.com/order/create/v1/json/{{customer_id}}

Cadastre um pedido

curl -X POST "https://admin.fretebarato.com/order/create/v1/json/{{customer_id}}" \
  -H "Authorization: Bearer xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaAplicacao ([email protected])" \
  -d '{
    "status": "aberto",
    "numero_pedido": "PED-1001",
    "emitente_cnpj": "12.345.678/0001-99",
    "destino_nome": "Maria Silva",
    "destino_cpf": "123.456.789-09",
    "destino_endereco_telefone": "(11) 98765-4321",
    "destino_endereco_cep": "01310-100",
    "destino_endereco_uf": "SP",
    "destino_endereco_logradouro": "Avenida Paulista",
    "destino_endereco_numero": "1000",
    "destino_endereco_bairro": "Bela Vista",
    "destino_endereco_complemento": "Sala 12",
    "transporte_cnpj": "12.345.678/0001-99",
    "transporte_volume_quantidade": 2,
    "transporte_volume_peso_bruto": 1.25,
    "transporte_volume_peso_liquido": 1.1,
    "transporte_nome": "Transportadora Exemplo",
    "transporte_nome_alias": "Exemplo"
  }'

$url = "https://admin.fretebarato.com/order/create/v1/json/{{customer_id}}";

$payload = array(
  "status" => "aberto",
  "numero_pedido" => "PED-1001",
  "emitente_cnpj" => "12.345.678/0001-99",
  "destino_nome" => "Maria Silva",
  "destino_cpf" => "123.456.789-09",
  "destino_endereco_telefone" => "(11) 98765-4321",
  "destino_endereco_cep" => "01310-100",
  "destino_endereco_uf" => "SP",
  "destino_endereco_logradouro" => "Avenida Paulista",
  "destino_endereco_numero" => "1000",
  "destino_endereco_bairro" => "Bela Vista",
  "destino_endereco_complemento" => "Sala 12",
  "transporte_cnpj" => "12.345.678/0001-99",
  "transporte_volume_quantidade" => 2,
  "transporte_volume_peso_bruto" => 1.25,
  "transporte_volume_peso_liquido" => 1.1,
  "transporte_nome" => "Transportadora Exemplo",
  "transporte_nome_alias" => "Exemplo"
);

$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",
  "User-Agent: MinhaAplicacao ([email protected])"
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($payload));

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

{
  "status": "aberto",
  "numero_pedido": "PED-1001",
  "emitente_cnpj": "12.345.678/0001-99",
  "destino_nome": "Maria Silva",
  "destino_cpf": "123.456.789-09",
  "destino_endereco_telefone": "(11) 98765-4321",
  "destino_endereco_cep": "01310-100",
  "destino_endereco_uf": "SP",
  "destino_endereco_logradouro": "Avenida Paulista",
  "destino_endereco_numero": "1000",
  "destino_endereco_bairro": "Bela Vista",
  "destino_endereco_complemento": "Sala 12",
  "transporte_cnpj": "12.345.678/0001-99",
  "transporte_volume_quantidade": 2,
  "transporte_volume_peso_bruto": 1.25,
  "transporte_volume_peso_liquido": 1.1,
  "transporte_nome": "Transportadora Exemplo",
  "transporte_nome_alias": "Exemplo"
}

{
  "success": true,
  "code": 200,
  "message": "Pedido cadastrado.",
  "data": {
    "created": true,
    "order_code": 987654,
    "numero_pedido": "PED-1001",
    "status": "aberto"
  }
}

Headers

Key	Value
`Authorization`	`Bearer {{token}}`
`Content-Type`	`application/json`
`User-Agent`	Aplicação (e-mail para contato técnico)

Parâmetros do payload

Parâmetro	Tipo	Obrigatório	Observação
`status`	String	Sim	Status inicial do pedido: `aberto`, `pago` ou `pendente`. `cancelado` não é aceito no cadastro; aplique-o depois, pelo status do pedido
`numero_pedido`	String	Sim	Número do pedido no seu sistema, de 1 a 60 caracteres. Envie como texto. Um número JSON, como `1001`, responde `400 Campo [numero_pedido] inválido.`
`emitente_cnpj`	String	Sim	14 dígitos de um CNPJ da conta (aceita pontuação). É o emitente gravado no pedido. Razão social e nome fantasia vêm do cadastro da conta, o mesmo critério da consulta e da edição
`destino_nome`	String	Não	Nome do destinatário, de 3 a 100 caracteres
`destino_cpf`	String	Não	CPF do destinatário com 11 dígitos (aceita pontuação)
`destino_cnpj`	String	Não	CNPJ do destinatário com 14 dígitos (aceita pontuação)
`destino_endereco_telefone`	String	Não	Telefone com DDD, de 10 ou 11 dígitos (aceita pontuação)
`destino_endereco_cep`	String	Não	CEP com 8 dígitos (aceita `01310-100`)
`destino_endereco_uf`	String	Não	UF com 2 letras
`destino_endereco_logradouro`	String	Não	Logradouro, de 3 a 200 caracteres
`destino_endereco_numero`	String	Não	Número do endereço, de 1 a 11 caracteres. `S/N` é aceito
`destino_endereco_bairro`	String	Não	Bairro, de 2 a 100 caracteres
`destino_endereco_complemento`	String	Não	Complemento, até 200 caracteres
`transporte_cnpj`	String	Condicional	CNPJ da transportadora com 14 dígitos (aceita pontuação)
`transporte_volume_quantidade`	Numérico	Condicional	Quantidade de volumes. Número inteiro a partir de 1
`transporte_volume_peso_bruto`	Numérico	Condicional	Peso bruto maior que zero, com ponto decimal (ex: `1.25`)
`transporte_volume_peso_liquido`	Numérico	Não	Peso líquido. Se enviado, deve ser maior que zero
`transporte_nome`	String	Condicional	Nome da transportadora, de 3 a 200 caracteres
`transporte_nome_alias`	String	Não	Nome alternativo da transportadora, até 200 caracteres

Um campo opcional pode ser omitido, enviado como null ou como "". Os três casos têm o mesmo efeito. Nome, logradouro, bairro e complemento são gravados com iniciais maiúsculas, a UF em maiúsculas, e CEP, telefone, CPF e CNPJ só com os dígitos.

Se vier qualquer campo de transporte preenchido, transporte_cnpj, transporte_volume_quantidade, transporte_volume_peso_bruto e transporte_nome são obrigatórios juntos. Peso líquido e alias seguem opcionais. Para cadastrar sem transportadora, omita esses campos.

Parâmetros do response

Parâmetro	Tipo	Comportamento
`success`	Boolean	Indica se a requisição foi processada com sucesso (`true`/`false`)
`code`	Numérico	Retorna o código HTTP da resposta
`message`	String	Retorna `Pedido cadastrado.`
`data.created`	Boolean	`true` quando o pedido foi criado nesta chamada
`data.order_code`	Numérico	Identificador do pedido na Frete Barato, número inteiro. Guarde-o para o status e para o envio da NF-e. Não muda depois do vínculo
`data.numero_pedido`	String	Número do pedido enviado
`data.status`	String	Alias gravado: `aberto`, `pago` ou `pendente`

O cadastro não é idempotente. Repetir o mesmo numero_pedido responde 409 com a mensagem numero_pedido ambíguo, não altera o pedido que já existe e não aplica o transporte deste body. Guarde o order_code da primeira resposta.

Trate os erros

Response	Tipo	Mensagem	Descrição
`400`	Bad Request	Campo status inválido.	Campo ausente, vazio, fora do tamanho ou enviado como número
`400`	Bad Request	Status inválido (status).	`status` diferente de `aberto`, `pago` e `pendente`, inclusive `cancelado`
`400`	Bad Request	Campo numero_pedido inválido.	`numero_pedido` ausente, vazio, fora do tamanho ou enviado como número
`400`	Bad Request	Campo destino_nome inválido.	Campo de destino que não é texto ou está fora da regra. A mesma mensagem existe para os demais campos de destino
`400`	Bad Request	Endereço do destino inválido (destino_endereco_cep).	CEP sem 8 dígitos
`400`	Bad Request	Endereço do destino inválido (destino_endereco_uf).	UF com 2 caracteres que não são letras
`400`	Bad Request	Campo transporte_cnpj inválido.	Campo obrigatório do grupo de transporte ausente ou fora da regra. A mesma mensagem existe para os demais campos de transporte
`400`	Bad Request	CNPJ do emitente é obrigatório.	`emitente_cnpj` ausente ou sem 14 dígitos
`400`	Bad Request	Payload inválido (JSON).	JSON válido que não é um objeto (uma lista, por exemplo)
`401`	Unauthorized	Authentication failure	Falha na autenticação: token inválido, Customer ID incorreto ou versão incorreta da API
`403`	Forbidden	Você não tem permissão para acessar este recurso.	O CNPJ do emitente não pertence à conta
`404`	Not Found	Customer not found	Customer ID sem conta associada
`404`	Not Found	Cliente não encontrado.	Cadastro da conta não localizado. Fale com o suporte
`406`	Not Acceptable	Invalid Params (JSON)	Estrutura JSON inválida ou malformada
`409`	Conflict	numero_pedido ambíguo	Já existe um pedido desta API na conta com o mesmo `numero_pedido`. Use outro número. O pedido existente não é alterado
`500`	Internal Server Error	Mensagem variável	Erro interno do servidor. A requisição pode ser reenviada

Exemplos de erro

{
  "success": false,
  "code": 400,
  "message": "Campo [numero_pedido] inválido.",
  "data": null
}

{
  "success": false,
  "code": 400,
  "message": "Status inválido (status).",
  "data": null
}

{
  "success": false,
  "code": 401,
  "message": "Authentication failure",
  "data": null
}

{
  "success": false,
  "code": 403,
  "message": "Você não tem permissão para acessar este recurso.",
  "data": null
}

{
  "success": false,
  "code": 409,
  "message": "numero_pedido ambíguo",
  "data": null
}

Etiquetas

Consulte e obtenha a etiqueta de transporte de um pedido na API Frete Barato.

Status

Atualize o status de um pedido cadastrado na API Frete Barato.