Criar tarifa da categoria

Cria a tarifa padrão ou uma tarifa extra da categoria. A tarifa começa a valer na hora.

Tarifa padrão × tarifa extra

• A primeira tarifa da categoria é a padrão: é criada sem horarios e vale o tempo todo.
• Com a padrão já criada, toda tarifa nova é extra e exige horarios.
• A categoria aceita no máximo 8 tarifas vigentes: a padrão e mais 7 extras.

Método de cálculo (metodo_calculo_tarifa)

Os obrigatórios são os mesmos que o painel exige ao salvar: só o campo vazio é recusado, e zero é aceito. Os demais valores podem ficar vazios. Em todos os métodos também valem nome, horarios e habilitar_taxa_deslocamento.

Restrições de bandeira (400 quando não atendidas):

• V exige o app de motorista da bandeira (ou da bandeira agrupadora) na versão 14.4 ou superior;
• B só em bandeira que faz somente entregas;
• P não é aceito em bandeira com cálculo de corrida pré-fixado.

Uma tarifa que já usa V, B ou P pode continuar com o mesmo método mesmo sem atender à restrição.

Campos condicionais

• limite_distancia_maxima (maior que zero): só com habilitar_limite_distancia: true (métodos D e V). No V, precisa ser maior que a maior faixa de valores_tabelados.
• Bônus de deslocamento: habilitar_taxa_deslocamento: true exige taxa_deslocamento_valor_km (maior que zero), taxa_deslocamento_km_minimo (aceita zero) e taxa_deslocamento_valor_maximo (maior que zero). Com false, os três são limpos e não são aceitos.
• Retorno (tipo_cobranca_retorno): só em bandeira que faz entregas. T pelo cálculo da tarifa, N não cobrar, F valor fixo e K por km percorrido (ambos exigem valor_retorno_adicional maior que zero), P porcentagem (exige taxa_retorno_porcentagem maior que zero, até 999.99). Sem a funcionalidade de taxa de retorno na bandeira, só T é aceito.
• calcular_individual_por_entrega: só em bandeira que faz entregas, com o cálculo individual por entrega liberado, e em método diferente de B. Com true, a parada adicional não é cobrada (valor_parada_adicional fica vazio).

Campo enviado que não se aplica ao método ou à operação da bandeira responde 400 com a mensagem '<campo>': Não se aplica ao método de cálculo da tarifa ou à operação da bandeira. Campos que não fazem parte do contrato (como id, categoria_id ou data_inicio) são ignorados.

Formatos

• Valores: número JSON ou texto, não negativo, com ponto como separador e até 2 casas decimais ("5.90" ou 5.9), nos mesmos limites do painel: até 8 dígitos inteiros nos valores da tarifa, 5 na taxa de deslocamento, 7 em limite_distancia_maxima e 11 no valor das faixas. "5,90" e "5.999" respondem 400. Na resposta, os valores vêm sempre como texto ("5.90"). null limpa o campo (e a obrigatoriedade do método continua valendo).
• Booleanos (habilitar_*, calcular_individual_por_entrega): true ou false.
• nome: texto de 1 a 20 caracteres, sem <, >, ", ', &, \, emoji, quebra de linha e outros caracteres de controle (400). Omitido, vale “Tarifa padrão” ou “Tarifa extra N”, como no painel.
• horarios: lista de até 36 horários {dia_semana, hora_inicio, hora_fim} por tarifa, com dia_semana de 1 (domingo) a 7 (sábado) e horas em HH:MM, sem segundos (18:00:00 responde 400), hora_fim maior que hora_inicio e 24:00 para ir até o fim do dia. hora_fim é o fim do bloco, como no calendário do painel: 08:00–12:00 e 12:00–18:00 no mesmo dia não se sobrepõem. Na resposta, os horários vêm no mesmo formato. Sobreposição dentro do próprio payload responde 400; com outra tarifa vigente da categoria, 409.
• valores_tabelados: lista de faixas {distancia_km, valor} (ambos maiores que zero, sem repetir distância) e no máximo uma faixa {a_partir_de: true, valor}, sem distancia_km, que vale acima da maior distância. Até 100 faixas de distância. A ordem é definida pelo servidor (distância crescente, a_partir_de por último).

Alterações simultâneas

A criação de tarifa e a troca de horários de uma tarifa (PUT) travam a categoria enquanto gravam. Uma segunda chamada desse tipo para a mesma categoria, feita ao mesmo tempo, responde 409 com Outra alteração de tarifa desta categoria está em andamento. Tente novamente em instantes. e não grava nada: aguarde a anterior terminar e repita a chamada.

Resposta

Devolve a tarifa criada no mesmo formato da listagem (só os campos aplicáveis).

Status de erro

Requer Api-Key (bandeira) + autenticação HTTP Basic de um gestor ativo da bandeira com a permissão de API de categoria (api_integracao_categoria) no cargo; sem ela, responde 403.