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

# Migração do legado

> Como sair das rotas sem versão (/api/...) para a v1 (/api/v1/...). Payloads e respostas são os mesmos nas duas versões.

As rotas sem versão continuam funcionando. Para integrações novas, use a v1; para as existentes,
a troca é de path.

## Passo a passo

**1. Troque o prefixo**

`/api/` vira `/api/v1/` nas rotas de calculadoras, consultas e JusScore. Health continua em
`/api/health`.

**2. Troque o nome da correção simples**

`correction_simple` vira `correcao-simples`.

**3. Consultas assíncronas**

O `statusUrl` do `202` aponta para a versão em que a consulta foi criada, e o `GET` do
protocolo funciona nas duas versões. O webhook não muda: mesmo corpo, mesma assinatura.

**4. JusScore**

Na v1, acompanhe a consulta pelo `GET /api/v1/jus-score/{id_consulta}`; `url_retorno` responde
`400` por enquanto. Quando o webhook assinado chegar à v1, ele virá só com a assinatura HMAC,
**sem** a `x-api-key`, e esta página trará a verificação. Se depende do webhook hoje, continue
no legado até lá.

| Legado | v1 |
| - | - |
| `POST /api/calculadoras/trabalhista` | `POST /api/v1/calculadoras/trabalhista` |
| `POST /api/calculadoras/correction_simple` | `POST /api/v1/calculadoras/correcao-simples` |
| `POST /api/consultas/cnh` | `POST /api/v1/consultas/cnh` |
| `POST /api/jus-score` | `POST /api/v1/jus-score` |
| `GET /api/health` | `GET /api/health` (sem versão) |

Algumas rotas existem só na v1: `GET /api/v1/consumo` e o relatório PDF da calculadora completa.

## Como saber que o legado foi depreciado

Quando o legado for depreciado, toda resposta dele passa a trazer:

| Header | Valor |
| - | - |
| `Deprecation` | A data da depreciação, em segundos (`@1788220800`). |
| `Sunset` | A data de desligamento, quando houver. |
| `Link` | Este guia, com `rel="deprecation"`. |

A data entra no [changelog](https://docs.jusfy.com.br/changelog.md) antes de valer.

## Política de versionamento

A versão vai no path (`/api/v1/...`). A versão do contrato segue semver: MAJOR é a versão do path,
MINOR é mudança compatível e PATCH é só documentação.

**Mudanças compatíveis** entram na versão atual, sem aviso prévio. Sua integração deve tolerá-las:

* campo novo na resposta;
* campo opcional novo no request;
* rota nova;
* valor novo de enum **na resposta**, quando o campo estiver documentado como extensível;
* código de erro novo para uma condição que antes não era tratada.

**Mudanças incompatíveis** só entram numa versão nova de path:

* remover ou renomear path, campo ou valor de enum;
* tornar obrigatório um campo opcional;
* mudar o tipo ou o formato de um campo;
* mudar o significado de um status code;
* mudar o formato do envelope ou do erro;
* mudar a assinatura ou o corpo de um webhook.

Quando uma versão é depreciada, você recebe três sinais: os headers acima, as operações marcadas
como `deprecated` na referência da versão e comunicação direta aos clientes que ainda a chamam.

Uma versão só é desligada quando o prazo de aviso venceu **e** todo cliente que ainda a chama foi
contatado. Desligada, as rotas dela respondem **`410 Gone`**, no formato de erro padrão, com a
`message` apontando para este guia.


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