Pedidos
Status
Atualize o status de um pedido cadastrado na API Frete Barato.
O endpoint de status atualiza o status de um pedido criado pelo cadastro. O pedido é identificado pelo order_code retornado no cadastro.
Endpoint
https://admin.fretebarato.com/order/status/v1/json/{{customer_id}}
Atualize o status de um pedido
curl -X POST "https://admin.fretebarato.com/order/status/v1/json/{{customer_id}}" \
-H "Authorization: Bearer xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "User-Agent: MinhaAplicacao ([email protected])" \
-d '{
"order_code": 987654,
"status": "pago",
"emitente_cnpj": "12345678000199"
}'
$url = "https://admin.fretebarato.com/order/status/v1/json/{{customer_id}}";
$payload = array(
"order_code" => 987654,
"status" => "pago",
"emitente_cnpj" => "12345678000199"
);
$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);
{
"order_code": 987654,
"status": "pago",
"emitente_cnpj": "12345678000199"
}
{
"success": true,
"code": 200,
"message": "Status atualizado.",
"data": {
"changed": true,
"order_code": 987654,
"status": "pago",
"status_code": 14
}
}
Enquanto o pedido não tem NF-e, os status aceitos são aberto, pago, pendente e cancelado, sem ordem obrigatória entre eles. Depois de cancelado, o pedido não muda mais. O vínculo da NF-e aceita o pedido em aberto, pago ou pendente. cancelado não vincula.
Depois do envio da nota fiscal com o order_code, o pedido fica faturado e o único status aceito por esta API é expedicao.
Com a expedição gravada e o CNPJ, o volume, o peso e o nome da transportadora preenchidos, a rotina de rastreio avança sozinha por emitido, transporte e entregue. Esses status não são enviados por esta API. A partir daí o pedido não muda mais por este endpoint. Se a transportadora mudar depois do cadastro, use a edição da nota fiscal.
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 |
|---|---|---|---|
order_code | Numérico | Sim | Número inteiro retornado no cadastro. Aceita número (987654) ou texto só com dígitos ("987654"), sem zeros à esquerda |
status | String | Sim | Antes da NF-e: aberto, pago, pendente ou cancelado. Depois do envio da NF-e: apenas expedicao. Envie o valor exatamente assim: minúsculas, sem acento e com underline. O número (status_code) não é aceito no lugar do texto. cancelado é definitivo |
emitente_cnpj | String | Sim | CNPJ do emitente gravado no pedido, com 14 dígitos (aceita pontuação). Precisa ser um CNPJ cadastrado na conta |
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 Status atualizado. ou, quando o pedido já estava no status enviado e esse status ainda permite alteração, Status já aplicado. |
data.changed | Boolean | true quando o status foi gravado nesta chamada e false quando o pedido já estava nele e ainda podia ser alterado |
data.order_code | Numérico | Identificador do pedido alterado |
data.status | String | Status gravado |
data.status_code | Numérico | Código do status gravado: 11 (aberto), 14 (pago), 17 (pendente), 12 (cancelado) ou 5 (expedicao) |
Trate os erros
| Response | Tipo | Mensagem | Descrição |
|---|---|---|---|
400 | Bad Request | order_code inválido. | order_code ausente, zero, negativo, decimal, com zeros à esquerda ou com caracteres que não sejam dígitos |
400 | Bad Request | Status não permitido (status). | Valor fora da tabela, com maiúsculas ou numérico. Também vale para faturado, emitido, em_transporte, entregue e para as etapas de romanêio do painel (emissão, aberto, fechado e conferência) |
400 | Bad Request | CNPJ do emitente é obrigatório. | emitente_cnpj ausente ou sem 14 dígitos |
400 | Bad Request | Nota fiscal inconsistente (emitente_cnpj). | emitente_cnpj diferente do gravado no pedido |
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 | Pedido não encontrado. | order_code inexistente nesta conta ou que não pertence a esta API, sem indicar se ele existe. Também ocorre quando a NF-e desse order_code foi importada depois pela caixa de e-mail do Frete Barato: o registro passa para o canal de e-mail |
406 | Not Acceptable | Invalid Params (JSON) | Estrutura JSON inválida ou malformada |
409 | Conflict | Pedido já possui NF-e (status). | Status comercial (aberto, pago, pendente ou cancelado) em um pedido que já tem NF-e. O status não muda |
409 | Conflict | Status de expedição exige NF-e vinculada (status). | expedicao antes do vínculo |
409 | Conflict | Pedido neste status não pode ser alterado (status). | O pedido já está cancelado, numa etapa de romanêio do painel, em transferência, emitido, transporte, entregue, atraso ou finalizado. O status só muda enquanto o pedido está em aberto, pago, pendente, faturado ou em expedição |
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": "order_code inválido.",
"data": null
}
{
"success": false,
"code": 400,
"message": "Status não permitido (status).",
"data": null
}
{
"success": false,
"code": 404,
"message": "Pedido não encontrado.",
"data": null
}
{
"success": false,
"code": 409,
"message": "Pedido já possui NF-e (status).",
"data": null
}
{
"success": false,
"code": 409,
"message": "Status de expedição exige NF-e vinculada (status).",
"data": null
}