# Consulta o andamento de uma admissão

`GET /v1/admissoes/{id}`

Alcança as admissões da **empresa da chave**, com qualquer chave ativa
dela — inclusive a admissão enviada por uma chave já revogada, para que a
troca de chave não deixe nenhuma sem consulta. Admissão de outra empresa e
admissão inexistente respondem igual: `404 NAO_ENCONTRADA`.

`xml_evento` é o XML **que foi enviado** ao eSocial — pode diferir do
pedido, porque o escritório pode corrigir o evento antes de aprovar. Trate
o XML devolvido como a verdade.

## Cabeçalhos e parâmetros

- `Authorization` (`Bearer <chave>` · obrigatório) — `Authorization: Bearer <chave>`. A chave é gerada pelo escritório na ficha da empresa, com um nome, aparece uma vez (o Motor guarda só o resumo SHA-256 dela), e alcança uma empresa e só a admissão. Vale enquanto não for revogada e o escritório que a gerou atender a empresa. A empresa pode ter **até duas chaves ativas** ao mesmo tempo, para trocar sem parar; o endereço do webhook e o segredo dele são da integração da empresa, não de cada chave — o webhook é opcional, e trocar o endereço gera um segredo novo na hora. Sessão de usuário e token OAuth são recusados nestas rotas.
- `id` (uuid · obrigatório)

## Respostas

### 200

Andamento atual.

Corpo:

- `id` (uuid · obrigatório)
- `estado` (texto · obrigatório) — Onde a admissão está.
  - `RECEBIDA` — Colaborador criado; o evento está sendo montado.
  - `AGUARDANDO_ESCRITORIO` — O evento está na fila do escritório, esperando uma pessoa aprovar.
  - `ENVIADA` — Transmitido; aguardando o processamento do eSocial.
  - `PROCESSADA` — Aceito pelo eSocial; há `nr_recibo`.
  - `RECUSADA` — Recusado pelo eSocial; veja `ocorrencias`. Se o escritório corrigir e reenviar, pode voltar a ENVIADA; não a trate como final.
  - `DESCARTADA` — O escritório descartou o evento sem enviá-lo. Pode voltar se ele o restaurar.
- `matricula` (texto · obrigatório · até 30 caracteres)
- `ambiente` (texto · obrigatório) — Ambiente do eSocial da empresa.
  - `PRODUCAO` — Produção (com valor legal).
  - `RESTRITA` — Produção Restrita (teste, sem valor legal).
- `prazo_legal` (data (AAAA-MM-DD) · obrigatório)
- `fora_do_prazo` (true / false · obrigatório)
- `recebida_em` (data e hora (ISO 8601) · obrigatório)
- `atualizada_em` (data e hora (ISO 8601) · obrigatório)
- `nr_recibo` (texto ou null · obrigatório · formato `^1\.\d\.\d{19}$`) — Número do recibo do eSocial. Só em PROCESSADA.
- `ocorrencias` (lista de objeto · obrigatório)
  - `ocorrencias.N.codigo` (texto ou null · obrigatório)
  - `ocorrencias.N.descricao` (texto ou null · obrigatório)
  - `ocorrencias.N.tipo` (texto ou null · obrigatório) — Tipo da ocorrência no retorno do eSocial (erro ou advertência).
  - `ocorrencias.N.localizacao` (texto ou null · obrigatório)
- `xml_evento` (texto ou null · obrigatório) — XML do S-2200 assinado, exatamente como foi enviado. Nulo antes de ENVIADA.
- `xml_retorno` (texto ou null · obrigatório) — XML do retorno do eSocial para ESTE evento (recortado do lote). Só em PROCESSADA ou RECUSADA.

### 401

`CHAVE_INVALIDA` — ausente, malformada, desconhecida, credencial que não
é chave de integração, ou chave de uma empresa que deixou de ser
atendida pelo escritório que a gerou. `CHAVE_REVOGADA` — a chave foi revogada pelo
escritório; vale a partir da chamada seguinte à revogação. Admissão
enviada por ela e ainda não transmitida vai para a fila do escritório
(aviso `admissao.aguardando_escritorio`).

Corpo:

- `codigo` (texto · obrigatório) — Código estável. Conhecidos: IDEMPOTENCY_KEY_INVALIDA, CHAVE_INVALIDA, CHAVE_REVOGADA, CHAVE_SEM_ESCOPO, EMPRESA_NAO_HABILITADA, CERTIFICADO_INDISPONIVEL, NAO_ENCONTRADA, METODO_NAO_PERMITIDO, TRABALHADOR_JA_ADMITIDO, IDEMPOTENCIA_CONFLITO, IDEMPOTENCIA_EM_CURSO, CORPO_GRANDE_DEMAIS, CAMPO_DESCONHECIDO, DADOS_INVALIDOS, DADOS_FALTANDO, LIMITE_EXCEDIDO, INDISPONIVEL (a lista, com o que fazer em cada um, está em `x-motor-codigos.recusas`). Trate código desconhecido como erro que exige olhar humano.
- `mensagem` (texto · obrigatório) — Texto em português para pessoas. Não o use para decidir — use `codigo`.
- `campos` (lista de objeto · obrigatório) — Problemas campo a campo. Vazio quando o erro não é de um campo.
  - `campos.N.campo` (texto · obrigatório) — Caminho no corpo, com ponto e índice — `trabalhador.cpf`, `dependentes.0.cpf`. `(corpo)` quando o JSON não pôde ser lido.
  - `campos.N.codigo` (texto · obrigatório) — Código do campo; a lista completa, com quem corrige cada um, está em `x-motor-codigos.campos`. Quem corrige depende do código: os de jornada e sindicato são do cadastro do escritório, não do pedido.
  - `campos.N.mensagem` (texto · obrigatório)

### 404

`NAO_ENCONTRADA` — não existe, ou não é da empresa desta chave.

Corpo:

- `codigo` (texto · obrigatório) — Código estável. Conhecidos: IDEMPOTENCY_KEY_INVALIDA, CHAVE_INVALIDA, CHAVE_REVOGADA, CHAVE_SEM_ESCOPO, EMPRESA_NAO_HABILITADA, CERTIFICADO_INDISPONIVEL, NAO_ENCONTRADA, METODO_NAO_PERMITIDO, TRABALHADOR_JA_ADMITIDO, IDEMPOTENCIA_CONFLITO, IDEMPOTENCIA_EM_CURSO, CORPO_GRANDE_DEMAIS, CAMPO_DESCONHECIDO, DADOS_INVALIDOS, DADOS_FALTANDO, LIMITE_EXCEDIDO, INDISPONIVEL (a lista, com o que fazer em cada um, está em `x-motor-codigos.recusas`). Trate código desconhecido como erro que exige olhar humano.
- `mensagem` (texto · obrigatório) — Texto em português para pessoas. Não o use para decidir — use `codigo`.
- `campos` (lista de objeto · obrigatório) — Problemas campo a campo. Vazio quando o erro não é de um campo.
  - `campos.N.campo` (texto · obrigatório) — Caminho no corpo, com ponto e índice — `trabalhador.cpf`, `dependentes.0.cpf`. `(corpo)` quando o JSON não pôde ser lido.
  - `campos.N.codigo` (texto · obrigatório) — Código do campo; a lista completa, com quem corrige cada um, está em `x-motor-codigos.campos`. Quem corrige depende do código: os de jornada e sindicato são do cadastro do escritório, não do pedido.
  - `campos.N.mensagem` (texto · obrigatório)

### 429

`LIMITE_EXCEDIDO` — mais de 60 chamadas por minuto com esta chave. Só
isso: a admissão pela API não tem limite próprio no plano do escritório
(conta como colaborador ativo, como a da tela). Espere o `Retry-After`
(em segundos).

Cabeçalhos:

- `Retry-After` — Segundos a esperar antes de repetir.

Corpo:

- `codigo` (texto · obrigatório) — Código estável. Conhecidos: IDEMPOTENCY_KEY_INVALIDA, CHAVE_INVALIDA, CHAVE_REVOGADA, CHAVE_SEM_ESCOPO, EMPRESA_NAO_HABILITADA, CERTIFICADO_INDISPONIVEL, NAO_ENCONTRADA, METODO_NAO_PERMITIDO, TRABALHADOR_JA_ADMITIDO, IDEMPOTENCIA_CONFLITO, IDEMPOTENCIA_EM_CURSO, CORPO_GRANDE_DEMAIS, CAMPO_DESCONHECIDO, DADOS_INVALIDOS, DADOS_FALTANDO, LIMITE_EXCEDIDO, INDISPONIVEL (a lista, com o que fazer em cada um, está em `x-motor-codigos.recusas`). Trate código desconhecido como erro que exige olhar humano.
- `mensagem` (texto · obrigatório) — Texto em português para pessoas. Não o use para decidir — use `codigo`.
- `campos` (lista de objeto · obrigatório) — Problemas campo a campo. Vazio quando o erro não é de um campo.
  - `campos.N.campo` (texto · obrigatório) — Caminho no corpo, com ponto e índice — `trabalhador.cpf`, `dependentes.0.cpf`. `(corpo)` quando o JSON não pôde ser lido.
  - `campos.N.codigo` (texto · obrigatório) — Código do campo; a lista completa, com quem corrige cada um, está em `x-motor-codigos.campos`. Quem corrige depende do código: os de jornada e sindicato são do cadastro do escritório, não do pedido.
  - `campos.N.mensagem` (texto · obrigatório)

### 503

`INDISPONIVEL` — falha nossa, não do pedido nem da chave. No `POST`,
repita com a MESMA `Idempotency-Key`, respeitando `Retry-After` quando
vier: não haverá duplicata — se a admissão tiver sido criada, a
repetição devolve o `202` dela.

Cabeçalhos:

- `Retry-After` — Segundos a esperar antes de repetir, quando vier.

Corpo:

- `codigo` (texto · obrigatório) — Código estável. Conhecidos: IDEMPOTENCY_KEY_INVALIDA, CHAVE_INVALIDA, CHAVE_REVOGADA, CHAVE_SEM_ESCOPO, EMPRESA_NAO_HABILITADA, CERTIFICADO_INDISPONIVEL, NAO_ENCONTRADA, METODO_NAO_PERMITIDO, TRABALHADOR_JA_ADMITIDO, IDEMPOTENCIA_CONFLITO, IDEMPOTENCIA_EM_CURSO, CORPO_GRANDE_DEMAIS, CAMPO_DESCONHECIDO, DADOS_INVALIDOS, DADOS_FALTANDO, LIMITE_EXCEDIDO, INDISPONIVEL (a lista, com o que fazer em cada um, está em `x-motor-codigos.recusas`). Trate código desconhecido como erro que exige olhar humano.
- `mensagem` (texto · obrigatório) — Texto em português para pessoas. Não o use para decidir — use `codigo`.
- `campos` (lista de objeto · obrigatório) — Problemas campo a campo. Vazio quando o erro não é de um campo.
  - `campos.N.campo` (texto · obrigatório) — Caminho no corpo, com ponto e índice — `trabalhador.cpf`, `dependentes.0.cpf`. `(corpo)` quando o JSON não pôde ser lido.
  - `campos.N.codigo` (texto · obrigatório) — Código do campo; a lista completa, com quem corrige cada um, está em `x-motor-codigos.campos`. Quem corrige depende do código: os de jornada e sindicato são do cadastro do escritório, não do pedido.
  - `campos.N.mensagem` (texto · obrigatório)

## Exemplos

curl:

```bash
curl https://api.motorcontabil.com/v1/admissoes/9a3f0c55-7d7e-4a52-b8c1-5d9f3c2e1a10 \
  -H "Authorization: Bearer $CHAVE_MOTOR"
```

Node:

```js
// Node 18 ou mais novo (fetch nativo), em módulo ES.
const resposta = await fetch('https://api.motorcontabil.com/v1/admissoes/9a3f0c55-7d7e-4a52-b8c1-5d9f3c2e1a10', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CHAVE_MOTOR}`,
  },
});
const dados = await resposta.json();
```

C#:

```csharp
using System.Net.Http.Headers;
using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("https://api.motorcontabil.com") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", chaveMotor);

var pedido = new HttpRequestMessage(HttpMethod.Get, "/v1/admissoes/9a3f0c55-7d7e-4a52-b8c1-5d9f3c2e1a10");

var resposta = await http.SendAsync(pedido);
var corpo = await resposta.Content.ReadAsStringAsync();
```