> ## Documentation Index > Fetch the complete documentation index at: https://docs.machine.global/llms.txt > Use this file to discover all available pages before exploring further. # Editar tarifa da categoria > Edita uma tarifa vigente da categoria, **mesclando** o payload sobre a tarifa atual: campo omitido mantém o valor gravado, `null` limpa um campo de valor, e `valores_tabelados` e `horarios`, quando enviados, substituem a lista inteira. Os campos, formatos e restrições de bandeira são os mesmos do POST (veja **Criar tarifa da categoria**). ### Versionamento e troca de id - **Valores mudaram** (qualquer campo além de `horarios`): nasce uma **nova versão** da tarifa com **id novo**, e a versão anterior é encerrada. A resposta traz `id` (o novo) e `id_anterior` (o id enviado na URL). Passe a usar o `id` devolvido: um PUT ou DELETE no id antigo responde **409**. - **Só `horarios` mudou**: a tarifa mantém o id, e `id_anterior` vem `null`. - **Nada mudou**: nada é gravado; responde 200 com a tarifa atual e `id_anterior: null`. ### Regras da edição - A tarifa padrão não aceita `horarios`, e a extra não aceita `horarios: null` (400): o PUT não transforma uma tarifa padrão em extra nem o contrário. - Trocar `metodo_calculo_tarifa` exige os obrigatórios do método novo. Os campos já gravados que não se aplicam ao método novo são limpos; campos **enviados** que não se aplicam respondem 400. - Uma tarifa tabelada (`T`) antiga com faixa `a_partir_de` a mantém na nova versão, mesmo sem ela no payload. ### Resposta Devolve a tarifa no mesmo formato da listagem, com `id_anterior` logo após o `id`. ### Status de erro | Status | Quando | |---|---| | 400 | Payload inválido (formato, campo obrigatório do método, campo não aplicável) ou configuração que a bandeira não pode usar | | 401 | Gestor não autenticado no header `Authorization` (Basic) | | 403 | Gestor sem a permissão de API de categoria (`api_integracao_categoria`) no cargo da bandeira | | 404 | Categoria ou tarifa inexistente, ou de outra bandeira | | 409 | Conflito com as tarifas vigentes da categoria, ou outra alteração de horários da mesma categoria em andamento (detalhes no exemplo de cada resposta) | 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. **O id da tarifa muda quando os valores são editados.** Cada alteração de valores cria uma nova versão da tarifa, com **id novo**, e encerra a versão anterior. A resposta traz `id` (o novo) e `id_anterior` (o id que foi alterado; `null` quando não nasceu versão nova). Passe a usar o `id` devolvido: um PUT ou DELETE no id antigo responde **409** (tarifa encerrada). Alterar só `horarios` mantém o id. ## OpenAPI ````yaml pages/v2/openapi-corridas.json PUT /configuracoes/categorias/{id}/tarifas/{tarifaId} openapi: 3.1.0 info: title: API de Integração description: API de Integração v2 - Corridas license: name: MIT version: 2.0.0 servers: - url: https://api-vendas.taximachine.com.br/api/v2/integracao - url: https://api.taximachine.com.br/api/v2/integracao security: - basicAuth: [] ApiKeyAuth: [] paths: /configuracoes/categorias/{id}/tarifas/{tarifaId}: put: summary: Editar tarifa da categoria description: >- Edita uma tarifa vigente da categoria, **mesclando** o payload sobre a tarifa atual: campo omitido mantém o valor gravado, `null` limpa um campo de valor, e `valores_tabelados` e `horarios`, quando enviados, substituem a lista inteira. Os campos, formatos e restrições de bandeira são os mesmos do POST (veja **Criar tarifa da categoria**). ### Versionamento e troca de id - **Valores mudaram** (qualquer campo além de `horarios`): nasce uma **nova versão** da tarifa com **id novo**, e a versão anterior é encerrada. A resposta traz `id` (o novo) e `id_anterior` (o id enviado na URL). Passe a usar o `id` devolvido: um PUT ou DELETE no id antigo responde **409**. - **Só `horarios` mudou**: a tarifa mantém o id, e `id_anterior` vem `null`. - **Nada mudou**: nada é gravado; responde 200 com a tarifa atual e `id_anterior: null`. ### Regras da edição - A tarifa padrão não aceita `horarios`, e a extra não aceita `horarios: null` (400): o PUT não transforma uma tarifa padrão em extra nem o contrário. - Trocar `metodo_calculo_tarifa` exige os obrigatórios do método novo. Os campos já gravados que não se aplicam ao método novo são limpos; campos **enviados** que não se aplicam respondem 400. - Uma tarifa tabelada (`T`) antiga com faixa `a_partir_de` a mantém na nova versão, mesmo sem ela no payload. ### Resposta Devolve a tarifa no mesmo formato da listagem, com `id_anterior` logo após o `id`. ### Status de erro | Status | Quando | |---|---| | 400 | Payload inválido (formato, campo obrigatório do método, campo não aplicável) ou configuração que a bandeira não pode usar | | 401 | Gestor não autenticado no header `Authorization` (Basic) | | 403 | Gestor sem a permissão de API de categoria (`api_integracao_categoria`) no cargo da bandeira | | 404 | Categoria ou tarifa inexistente, ou de outra bandeira | | 409 | Conflito com as tarifas vigentes da categoria, ou outra alteração de horários da mesma categoria em andamento (detalhes no exemplo de cada resposta) | 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. parameters: - name: id in: path required: true description: Id da categoria. Deve pertencer à central autenticada. schema: type: integer - name: tarifaId in: path required: true description: Id da tarifa. Deve ser uma tarifa vigente da categoria `id`. schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: nome: type: string minLength: 1 maxLength: 20 description: >- Nome da tarifa (1 a 20 caracteres, sem `<`, `>`, `"`, `'`, `&`, `\`, emoji e quebra de linha). Omitido, mantém o valor atual. metodo_calculo_tarifa: type: string enum: - D - P - T - V - B description: >- Método de cálculo: `D` duração, `P` hora parada, `T` tabelado, `V` km variável, `B` por bairro. Trocar o método exige os obrigatórios do método novo; os campos gravados que não se aplicam a ele são limpos. valor_bandeirada: type: - string - number - 'null' description: >- Bandeirada. Métodos `D`, `P` e `V` (obrigatório). Omitido, mantém o valor atual. example: '5.90' valor_km: type: - string - number - 'null' description: >- Valor por km. Métodos `D` e `P` (obrigatório). Omitido, mantém o valor atual. example: '5.90' valor_minuto: type: - string - number - 'null' description: >- Valor por minuto. Métodos `D` e `V` (obrigatório). Omitido, mantém o valor atual. example: '5.90' valor_hora_parada: type: - string - number - 'null' description: >- Valor da hora parada. Método `P` (obrigatório). Omitido, mantém o valor atual. example: '5.90' valor_minimo: type: - string - number - 'null' description: >- Valor mínimo da corrida. Métodos `D`, `P` e `V` (obrigatório). Omitido, mantém o valor atual. example: '5.90' valor_parada_adicional: type: - string - number - 'null' description: >- Valor por parada adicional. Métodos `D`, `P`, `V` e `T`. Omitido, mantém o valor atual. example: '5.90' valores_tabelados: type: array maxItems: 101 items: type: object required: - valor properties: distancia_km: type: - string - number - 'null' description: >- Distância da faixa em km (maior que zero). Não informar na faixa `a_partir_de`. example: '5.00' a_partir_de: type: boolean description: >- `true` na faixa que vale acima da maior distância (no máximo uma). Obrigatória em `V` e `B`; não aceita em `T`. valor: type: - string - number description: Valor da faixa (maior que zero). example: '15.00' description: >- Faixas de distância. Métodos `T`, `V` e `B` (obrigatório). Quando enviada, substitui a lista inteira. Omitido, mantém o valor atual. habilitar_limite_distancia: type: boolean description: >- Liga o limite de distância. Métodos `D` e `V`. `false` limpa `limite_distancia_maxima`. Omitido, mantém o valor atual. limite_distancia_maxima: type: - string - number - 'null' description: >- Distância máxima em km (maior que zero). Só com `habilitar_limite_distancia: true`; no `V`, maior que a maior faixa. Omitido, mantém o valor atual. example: '5.90' habilitar_taxa_deslocamento: type: boolean description: >- Liga o bônus de deslocamento. `false` limpa os três campos do bônus. Omitido, mantém o valor atual. taxa_deslocamento_valor_km: type: - string - number - 'null' description: >- Bônus: valor por km (maior que zero). Só com `habilitar_taxa_deslocamento: true`. Omitido, mantém o valor atual. example: '5.90' taxa_deslocamento_km_minimo: type: - string - number - 'null' description: >- Bônus: km mínimo (aceita zero). Só com `habilitar_taxa_deslocamento: true`. Omitido, mantém o valor atual. example: '5.90' taxa_deslocamento_valor_maximo: type: - string - number - 'null' description: >- Bônus: valor máximo (maior que zero). Só com `habilitar_taxa_deslocamento: true`. Omitido, mantém o valor atual. example: '5.90' tipo_cobranca_retorno: type: string enum: - T - 'N' - F - K - P description: >- Cobrança do retorno, só em bandeira que faz entregas: `T` pelo cálculo da tarifa, `N` não cobrar, `F` valor fixo, `K` por km percorrido, `P` porcentagem. Sem a funcionalidade de taxa de retorno, só `T`. Omitido, mantém o valor atual. valor_retorno_adicional: type: - string - number - 'null' description: >- Valor do retorno (maior que zero). Só com `tipo_cobranca_retorno` `F` ou `K`. Omitido, mantém o valor atual. example: '5.90' taxa_retorno_porcentagem: type: - string - number - 'null' description: >- Percentual do retorno (maior que zero, até `999.99`). Só com `tipo_cobranca_retorno` `P`. Omitido, mantém o valor atual. example: '5.90' calcular_individual_por_entrega: type: boolean description: >- Calcula o valor de cada entrega separadamente. Só em bandeira que faz entregas com o cálculo individual liberado, e método diferente de `B`. Omitido, mantém o valor atual. horarios: type: - array - 'null' items: type: object required: - dia_semana - hora_inicio - hora_fim properties: dia_semana: type: integer minimum: 1 maximum: 7 description: 1 (domingo) a 7 (sábado). hora_inicio: type: string description: '`HH:MM`, sem segundos (ex.: `18:00`).' example: '18:00' hora_fim: type: string description: >- `HH:MM`, sem segundos, maior que `hora_inicio`; aceita `24:00` para ir até o fim do dia. É o **fim do bloco**, como no calendário do painel: `18:00`–`22:00` vale das 18:00 até as 21:59:59, então um bloco seguinte pode começar em `22:00` no mesmo dia sem sobreposição. example: '24:00' description: >- Horários de atuação da tarifa extra. Quando enviada, substitui a lista inteira. A tarifa padrão não aceita horários, e a extra não aceita `null`. Omitido, mantém o valor atual. No máximo 36 horários quando a lista muda; reenviar a lista atual sem alteração é aceito mesmo acima disso (tarifa configurada no painel com mais blocos). maxItems: 36 examples: alterar_valores: summary: Alterar valores (gera nova versão com id novo) value: valor_km: '1.35' valor_minimo: '9.00' alterar_horarios: summary: Alterar só os horários da tarifa extra (mantém o id) value: horarios: - dia_semana: 6 hora_inicio: '19:00' hora_fim: '24:00' - dia_semana: 7 hora_inicio: '19:00' hora_fim: '24:00' trocar_metodo: summary: Trocar o método para hora parada value: metodo_calculo_tarifa: P valor_hora_parada: '18.00' desligar_bonus: summary: Desligar o bônus de deslocamento value: habilitar_taxa_deslocamento: false responses: '200': description: Tarifa editada (ou sem alteração) content: application/json: schema: type: object properties: success: type: boolean data: type: object description: >- Tarifa com só os campos que se aplicam ao método e à operação da bandeira. Valores em texto com 2 casas decimais. properties: id: type: integer description: >- Id atual da tarifa. Muda quando os valores são alterados: use este id daqui em diante. id_anterior: type: - integer - 'null' description: >- Id da versão encerrada por esta edição; `null` quando não nasceu versão nova. data_inicio: type: string description: >- Data e hora a partir da qual a tarifa vale, em ISO 8601 UTC (ex.: 2026-09-30T13:20:00Z). Definida pelo servidor no momento da gravação; não é aceita no corpo do POST/PUT. nome: type: string metodo_calculo_tarifa: type: string enum: - D - P - T - V - B valores_tabelados: type: array items: type: object properties: distancia_km: type: - string - 'null' a_partir_de: type: boolean valor: type: string horarios: type: array description: Lista vazia na tarifa padrão. items: type: object properties: dia_semana: type: integer hora_inicio: type: string example: '18:00' hora_fim: type: string example: '24:00' additionalProperties: true examples: nova_versao: summary: 'Valores alterados: id novo e id_anterior preenchido' value: success: true data: id: 4830 id_anterior: 4821 data_inicio: '2026-09-30T14:00:00Z' nome: Tarifa padrão metodo_calculo_tarifa: D valor_bandeirada: '5.90' valor_km: '1.35' valor_minuto: '0.15' valor_minimo: '9.00' valor_parada_adicional: '2.00' habilitar_limite_distancia: false habilitar_taxa_deslocamento: false horarios: [] mesma_versao: summary: 'Só horários alterados: mesmo id e id_anterior null' value: success: true data: id: 4822 id_anterior: null data_inicio: '2026-09-30T13:20:00Z' nome: Noite fim de semana metodo_calculo_tarifa: T valor_parada_adicional: '2.00' valores_tabelados: - distancia_km: '5.00' a_partir_de: false valor: '15.00' - distancia_km: '10.00' a_partir_de: false valor: '25.00' habilitar_taxa_deslocamento: false horarios: - dia_semana: 6 hora_inicio: '19:00' hora_fim: '24:00' - dia_semana: 7 hora_inicio: '19:00' hora_fim: '24:00' '400': description: Erro de validação content: application/json: schema: type: object examples: decimal_com_virgula: summary: Valor com vírgula value: success: false errors: - code: 0 message: >- 'valor_km': Deve ser um número não negativo, com até 2 casas decimais e ponto como separador. campo_nao_aplicavel: summary: Campo que não se aplica ao método value: success: false errors: - code: 0 message: >- 'valores_tabelados': Não se aplica ao método de cálculo da tarifa ou à operação da bandeira. horarios_na_padrao: summary: horarios na tarifa padrão value: success: false errors: - code: 0 message: >- 'horarios': A tarifa padrão vale o tempo todo e não aceita horários. horarios_null_na_extra: summary: horarios null na tarifa extra value: success: false errors: - code: 0 message: >- 'horarios': A tarifa extra precisa de horários de atuação. obrigatorio_metodo_novo: summary: Troca de método sem os obrigatórios do novo value: success: false errors: - code: 0 message: >- 'valor_km': Preenchimento obrigatório para o método de cálculo da tarifa. '401': description: Gestor não autenticado (Authorization Basic ausente ou inválido). content: application/json: schema: type: object example: success: false errors: - code: B5 message: Usuário e/ou senhas inválidos. '403': description: >- Gestor sem a permissão de API de categoria (api_integracao_categoria). content: application/json: schema: type: object example: success: false errors: - code: 68 message: >- O usuário informado não tem permissão para realizar essa operação. '404': description: Categoria ou tarifa não encontrada content: application/json: schema: type: object examples: categoria: summary: Categoria inexistente ou de outra bandeira value: success: false errors: - code: 0 message: Categoria informada não existe. tarifa: summary: Tarifa inexistente ou de outra categoria value: success: false errors: - code: 0 message: Tarifa não encontrada na categoria informada. '409': description: Conflito com as tarifas vigentes da categoria content: application/json: schema: type: object examples: tarifa_encerrada: summary: Id já encerrado (excluído ou substituído por nova versão) value: success: false errors: - code: 0 message: >- A tarifa foi encerrada ou substituída por uma nova versão. Consulte as tarifas vigentes da categoria. horario_sobreposto: summary: Horário sobreposto a outra tarifa vigente value: success: false errors: - code: 0 message: >- Existe sobreposição de horários no mesmo dia da semana. categoria_em_alteracao: summary: Outra criação ou troca de horários da categoria em andamento value: success: false errors: - code: 0 message: >- Outra alteração de tarifa desta categoria está em andamento. Tente novamente em instantes. '500': description: Erro interno content: application/json: schema: type: object example: success: false errors: - code: 0 message: Falha na operação components: securitySchemes: basicAuth: type: http scheme: basic ApiKeyAuth: type: apiKey in: header name: api-key description: Obrigatório. Sua chave API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.