> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Versionamento e estabilidade

> O que permanece estável dentro de /v1, quais mudanças o muveya considera incompatíveis, como escrever um cliente que tolera mudanças aditivas e onde as mudanças são anunciadas.

A versão da API faz parte do caminho. Tudo o que está documentado nesta aba fica sob `/v1`, e `/v1` é a única API pública: outras rotas usadas pelo console do muveya não são um contrato público, podem mudar a qualquer momento e não devem ser chamadas por integrações.

## O compromisso

* **Dentro de `/v1`, as mudanças são aditivas.** Uma operação, um campo ou um valor de que sua integração depende não é removido nem renomeado dentro de `/v1`.
* **Uma mudança incompatível exige uma nova versão.** Ela é publicada como uma nova versão principal no caminho (`/v2`), com um período de migração. A `/v1` não é quebrada no lugar.
* **O contrato é verificado a cada mudança.** O contrato OpenAPI por trás das páginas de **Endpoints** é gerado a partir do código do muveya, e cada mudança é comparada com a versão anterior por uma verificação automática de compatibilidade que rejeita as mudanças incompatíveis listadas abaixo.

A `version` que aparece dentro do documento OpenAPI é a revisão desse documento. A versão da API com que você se integra é o `/v1` do caminho.

## O que é considerado incompatível

O muveya considera incompatíveis estas mudanças na `/v1` e não as faz dentro de `/v1`:

| Mudança | Exemplo |
| - | - |
| Remover uma operação ou mudar seu `operationId` | Remover `GET /v1/orders` |
| Remover um status de resposta documentado de uma operação | Deixar de responder `404` onde estava documentado |
| Remover um parâmetro de consulta, de caminho ou de cabeçalho | Tirar `status` de `GET /v1/fulfillments` |
| Adicionar um novo parâmetro **obrigatório** | Tornar `limit` obrigatório |
| Remover um valor aceito de uma enumeração da requisição | Deixar de aceitar `weekly` como `period` |
| Tornar obrigatória uma propriedade do corpo da requisição | Exigir `period` em `POST /v1/analytics/exports` |
| Remover uma propriedade da resposta | Tirar `hasMore` das listas |
| Tornar opcional uma propriedade garantida da resposta | Tornar `status` opcional em `Order` |
| Remover um valor de uma enumeração da resposta | Deixar de retornar `in_transit` como status de caixa |
| Mudar o tipo de um campo | Transformar `onHand` de inteiro em texto |

## O que pode mudar dentro de `/v1`

Estas mudanças são aditivas e podem chegar a qualquer momento, anunciadas nas [novidades](/docs/pt/changelog):

* Novas operações e novos recursos.
* Novos parâmetros de consulta e cabeçalhos opcionais.
* Novos campos opcionais nas respostas.
* Novos valores em enumerações de resposta, por exemplo um novo status de pedido, um novo `type` de movimento de estoque ou uma nova chave de métrica de análise.
* Novos valores de `code` de erro.
* Novos escopos.
* Outra redação nos textos para pessoas: `title` e `detail` dos erros, `label` do resumo gerencial, descrições desta referência.
* Valores operacionais que a API informa em tempo de execução, como o orçamento de limite de uso nos cabeçalhos de resposta.

Um campo que aparece porque uma chave ganhou um escopo (por exemplo, os campos de custo com `catalog.cost:read`) não é uma mudança de contrato: ele sempre foi documentado como opcional.

## Escreva um cliente tolerante

<Steps>
  <Step title="Ignore campos que você não conhece">
    Interprete apenas os campos que você usa. Não falhe quando uma resposta trouxer um campo que não está no seu modelo.
  </Step>

  <Step title="Trate as enumerações como abertas">
    Dê a cada `switch` sobre um status, um tipo de movimento ou uma chave de métrica um ramo padrão. Um valor novo não deve derrubar sua integração; registre-o e trate-o como "outro".
  </Step>

  <Step title="Trate campos opcionais como opcionais">
    Um campo marcado como opcional pode estar ausente. Ele nunca é enviado como `null` no lugar (exceto três campos das análises, `value`, `averageHours` e `maxAgeHours`, descritos na referência). Verifique se ele existe antes de lê-lo.
  </Step>

  <Step title="Decida pelo código e use o status como alternativa">
    Trate os códigos de erro que você conhece e use o status HTTP para qualquer código que ainda não conheça. Veja [Erros](/docs/pt/api-reference/errors).
  </Step>

  <Step title="Nunca decida por textos para pessoas">
    `title`, `detail` e `label` mudam com o idioma e com a redação. Use chaves, códigos e ids.
  </Step>

  <Step title="Não dependa do formato do cursor nem da ordem das chaves">
    Os cursores são opacos e a ordem das chaves JSON não tem significado.
  </Step>
</Steps>

## Descontinuação

Hoje nenhuma operação ou campo da `/v1` está descontinuado, e nenhuma resposta traz cabeçalhos de descontinuação.

Quando existir uma `/v2`, a `/v1` terá um período de desativação anunciado. A desativação será publicada nas [novidades](/docs/pt/changelog) antes de entrar em vigor, e o muveya planeja sinalizá-la nas respostas com os cabeçalhos padrão `Deprecation` e `Sunset`.

## O que não está na `/v1` hoje

Recursos que não estão documentados nesta aba não estão disponíveis, por exemplo criar ou alterar pedidos pela API, ou [webhooks](/docs/pt/api-reference/webhooks). Se chegarem, chegarão como mudanças aditivas e serão anunciados nas novidades.

O único formato de chave de API emitido hoje é `mvy_test_` (veja [Autenticação](/docs/pt/api-reference/authentication)).

## Onde as mudanças são anunciadas

* As [novidades](/docs/pt/changelog) listam as mudanças visíveis para clientes, da mais recente para a mais antiga.
* As páginas de **Endpoints** são regeradas a partir do contrato sempre que ele muda, em inglês, espanhol e português.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.