Nota Fiscal
Edição
Altere os dados de transporte, destino e totais de uma nota fiscal na API Frete Barato.
O endpoint de edit altera destino, totais, volumes, pesos e transportadora de uma nota fiscal.
CNPJ, volume, peso e nome da transportadora podem entrar no cadastro do pedido. Quando esses dados mudarem depois, use este endpoint.
A edição grava os 16 campos de uma vez. Os campos obrigatórios precisam vir no payload e um campo opcional omitido é gravado vazio. Por isso, consulte a nota, altere o que precisar e reenvie todos os campos.
Endpoint
https://admin.fretebarato.com/invoice/edit/v1/json/{{customer_id}}
Edite uma nota fiscal
curl -X PATCH "https://admin.fretebarato.com/invoice/edit/v1/json/{{customer_id}}" \
-H "Authorization: Bearer xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "User-Agent: MinhaAplicacao ([email protected])" \
-d '{
"id_fatura_nota_fiscal": 987654,
"emitente_cnpj": "12345678000199",
"info": {
"total_nf": 150.5,
"total_frete": 10,
"transporte_volume_quantidade": 3,
"transporte_volume_peso_bruto": 2.5,
"transporte_volume_peso_liquido": 2.2,
"transporte_cnpj": "11222333000181",
"transporte_nome": "Transportadora Exemplo Ltda",
"transporte_nome_alias": "Exemplo",
"destino_endereco_cep": "01310100",
"destino_endereco_uf": "SP",
"destino_endereco_bairro": "Bela Vista",
"destino_endereco_logradouro": "Avenida Paulista",
"destino_endereco_numero": "1000",
"destino_endereco_complemento": "Sala 12",
"destino_nome": "Maria Silva",
"destino_endereco_telefone": "(11) 98765-4321"
}
}'
$url = "https://admin.fretebarato.com/invoice/edit/v1/json/{{customer_id}}";
$payload = array(
"id_fatura_nota_fiscal" => 987654,
"emitente_cnpj" => "12345678000199",
"info" => array(
"total_nf" => 150.5,
"total_frete" => 10,
"transporte_volume_quantidade" => 3,
"transporte_volume_peso_bruto" => 2.5,
"transporte_volume_peso_liquido" => 2.2,
"transporte_cnpj" => "11222333000181",
"transporte_nome" => "Transportadora Exemplo Ltda",
"transporte_nome_alias" => "Exemplo",
"destino_endereco_cep" => "01310100",
"destino_endereco_uf" => "SP",
"destino_endereco_bairro" => "Bela Vista",
"destino_endereco_logradouro" => "Avenida Paulista",
"destino_endereco_numero" => "1000",
"destino_endereco_complemento" => "Sala 12",
"destino_nome" => "Maria Silva",
"destino_endereco_telefone" => "(11) 98765-4321"
)
);
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PATCH");
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);
{
"id_fatura_nota_fiscal": 987654,
"emitente_cnpj": "12345678000199",
"info": {
"total_nf": 150.5,
"total_frete": 10,
"transporte_volume_quantidade": 3,
"transporte_volume_peso_bruto": 2.5,
"transporte_volume_peso_liquido": 2.2,
"transporte_cnpj": "11222333000181",
"transporte_nome": "Transportadora Exemplo Ltda",
"transporte_nome_alias": "Exemplo",
"destino_endereco_cep": "01310100",
"destino_endereco_uf": "SP",
"destino_endereco_bairro": "Bela Vista",
"destino_endereco_logradouro": "Avenida Paulista",
"destino_endereco_numero": "1000",
"destino_endereco_complemento": "Sala 12",
"destino_nome": "Maria Silva",
"destino_endereco_telefone": "(11) 98765-4321"
}
}
{
"success": true,
"code": 200,
"message": "Ação efetuada com sucesso.",
"data": {
"changed": [
{ "field": "transporte_volume_quantidade", "from": "2", "to": "3" },
{ "field": "transporte_volume_peso_bruto", "from": "1.25", "to": "2.5" },
{ "field": "transporte_volume_peso_liquido", "from": "1.1", "to": "2.2" },
{ "field": "destino_endereco_uf", "from": "sp", "to": "SP" }
]
}
}
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 |
|---|---|---|---|
id_fatura_nota_fiscal | Numérico | Sim | Identificador da nota |
emitente_cnpj | String | Sim | CNPJ do emitente da nota, com 14 dígitos (aceita pontuação). Precisa ser um CNPJ cadastrado na conta |
id_cliente | Numérico | Não | Se enviado, precisa ser o da conta autenticada |
info | Object | Recomendado | Objeto com os 16 campos da nota. Sem info, os campos são lidos da raiz do payload |
Detalhe do objeto info
| Parâmetro | Tipo | Obrigatório | Observação |
|---|---|---|---|
total_nf | Numérico | Sim | Valor total da nota, maior ou igual a zero |
total_frete | Numérico | Sim | Valor do frete, maior ou igual a zero |
transporte_volume_quantidade | Numérico | Sim | Quantidade de volumes. Número inteiro a partir de 1 |
transporte_volume_peso_bruto | Float | Sim | Peso bruto a partir de 0.001 |
transporte_volume_peso_liquido | Float | Não | Peso líquido a partir de 0.001. Omitido, null ou "" grava 0. O valor 0 é rejeitado |
transporte_cnpj | String | Sim | CNPJ da transportadora com exatamente 14 dígitos, sem pontuação |
transporte_nome | String | Sim | Nome da transportadora, de 3 a 200 caracteres |
transporte_nome_alias | String | Não | Nome alternativo da transportadora, até 200 caracteres. Vazio grava sem alias |
destino_endereco_cep | String | Sim | CEP com exatamente 8 dígitos, sem hífen |
destino_endereco_uf | String | Sim | UF com 2 caracteres. Gravada em maiúsculas |
destino_endereco_bairro | String | Sim | Bairro, de 2 a 100 caracteres |
destino_endereco_logradouro | String | Sim | Logradouro, de 3 a 200 caracteres |
destino_endereco_numero | String | Sim | Número do endereço, de 1 a 11 caracteres |
destino_endereco_complemento | String | Não | Complemento, até 200 caracteres |
destino_nome | String | Sim | Nome do destinatário, de 3 a 100 caracteres |
destino_endereco_telefone | String | Não | Telefone com 10 ou 11 dígitos. Espaços, hífens e parênteses são removidos |
A troca de CNPJ com o pedido em Transporte ou Entregue responde
400Não é permitido alterar o CNPJ da transportadora com o pedido em Transporte ou Entregue. Se a troca de CNPJ remover volumes já gerados, o pedido volta para faturado. A consulta indica esses casos em can_update_order e can_delete_volumes.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 | Mensagem descritiva sobre o resultado da edição |
data.changed | Array | Lista dos campos alterados, com field (campo), from (valor anterior) e to (valor novo), sempre como texto. Um reenvio sem mudanças retorna [] |
Trate os erros
Os erros de validação dos campos de info retornam juntos na mesma resposta, no formato campo: mensagem. e separados por espaço (ex: transporte_cnpj: CNPJ deve ter 14 dígitos.).
| Response | Tipo | Mensagem | Descrição |
|---|---|---|---|
400 | Bad Request | ID da nota fiscal é obrigatório. | id_fatura_nota_fiscal ausente, zero ou inválido |
400 | Bad Request | CNPJ do emitente é obrigatório. | emitente_cnpj ausente ou sem 14 dígitos |
400 | Bad Request | Nota fiscal inconsistente (emitente_cnpj). | O emitente da nota é diferente do emitente_cnpj enviado |
400 | Bad Request | campo: mensagem. | Um ou mais campos de info ausentes ou fora da regra (veja as mensagens abaixo) |
400 | Bad Request | Não é permitido alterar o CNPJ da transportadora com o pedido em Transporte ou Entregue. | Troca do CNPJ da transportadora com o pedido em transporte ou entregue |
401 | Unauthorized | Authentication failure | Falha na autenticação: token inválido, Customer ID incorreto ou versão incorreta da API |
403 | Forbidden | Cliente inconsistente (id_cliente). | id_cliente enviado diferente da conta autenticada |
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 |
404 | Not Found | Nota fiscal não encontrada. | Não existe nota com esse identificador |
406 | Not Acceptable | Invalid Params (JSON) | Payload ausente ou estrutura JSON inválida |
Mensagens de validação do objeto info
| Parâmetro | Mensagens |
|---|---|
total_nf | O campo Valor Total é obrigatório / O campo Valor Total não pode ser negativo. |
total_frete | O campo Valor Frete é obrigatório / O campo Valor Frete não pode ser negativo. |
transporte_volume_quantidade | O campo Quantidade de Volumes é obrigatório / Quantidade de Volumes deve ser um número inteiro. / O campo Quantidade de Volumes não pode ser 0. |
transporte_volume_peso_bruto | O campo Peso Bruto é obrigatório / O campo Peso Bruto não pode ser 0. |
transporte_volume_peso_liquido | O campo Peso Líquido não pode ser 0. |
transporte_cnpj | O campo CNPJ é obrigatório / CNPJ deve ter 14 dígitos. |
transporte_nome | O campo Nome da Transportadora é obrigatório / Nome da Transportadora deve ter no mínimo 3 caracteres. / Nome da Transportadora deve ter no máximo 200 caracteres. |
transporte_nome_alias | Nome Alias deve ter no máximo 200 caracteres. |
destino_endereco_cep | O campo CEP é obrigatório / CEP deve ter 8 dígitos. |
destino_endereco_uf | O campo UF é obrigatório / UF deve ter 2 caracteres. |
destino_endereco_bairro | O campo Bairro é obrigatório / Bairro deve ter no mínimo 2 caracteres. / Bairro deve ter no máximo 100 caracteres. |
destino_endereco_logradouro | O campo Rua é obrigatório / Rua deve ter no mínimo 3 caracteres. / Rua deve ter no máximo 200 caracteres. |
destino_endereco_numero | O campo Número é obrigatório / Número deve ter no mínimo 1 caractere. / Número deve ter no máximo 11 caracteres. |
destino_endereco_complemento | Complemento deve ter no máximo 200 caracteres. |
destino_nome | O campo Nome é obrigatório / Nome deve ter no mínimo 3 caracteres. / Nome deve ter no máximo 100 caracteres. |
destino_endereco_telefone | Telefone deve ter no mínimo 10 dígitos. / Telefone deve ter no máximo 11 dígitos. |
Exemplos de erro
{
"success": false,
"code": 400,
"message": "destino_endereco_uf: O campo UF é obrigatório. destino_endereco_bairro: O campo Bairro é obrigatório. destino_endereco_logradouro: O campo Rua é obrigatório. destino_endereco_numero: O campo Número é obrigatório. destino_nome: O campo Nome é obrigatório.",
"data": null
}
{
"success": false,
"code": 400,
"message": "transporte_volume_peso_liquido: O campo Peso Líquido não pode ser 0.",
"data": null
}
{
"success": false,
"code": 400,
"message": "Não é permitido alterar o CNPJ da transportadora com o pedido em Transporte ou Entregue.",
"data": null
}
{
"success": false,
"code": 404,
"message": "Nota fiscal não encontrada.",
"data": null
}

