# Visão geral

O sistema de RH da empresa envia uma **admissão**. O Motor confere tudo o que o
eSocial exige, cria o colaborador, gera a **matrícula**, monta e assina o
**S-2200** com o certificado A1 da empresa e o transmite. O resultado — o número do
recibo, o XML enviado e o XML do retorno — volta por **aviso** (webhook) e pela
**consulta**.

## Primeiros passos

1. Peça ao escritório de contabilidade que opera a empresa no Motor uma **chave de
   integração**. Para testar, peça uma chave de uma empresa ligada à Produção
   Restrita do eSocial (ver [Testar](https://developers.motorcontabil.com/testar)).
2. Liste as **jornadas** e os **sindicatos** da empresa
   (`GET /v1/catalogos/jornadas` e `GET /v1/catalogos/sindicatos`): a admissão os
   referencia por `id`.
3. Envie a admissão (`POST /v1/admissoes`) com uma `Idempotency-Key`.
4. Acompanhe pelo aviso no seu webhook ou pela consulta (`GET /v1/admissoes/{id}`).

## O que ela não faz

- Outros eventos (S-2206, S-2299, S-1200…), correção ou exclusão de admissão já
  enviada. Corrige-se pelo Motor, com o escritório.
- Readmissão de quem já tem cadastro na empresa, transferência entre empresas,
  empregado doméstico, temporário e intermitente.
- Ler colaboradores ou folha. A única leitura é a dos catálogos de jornada e de
  sindicato, que o pedido referencia.
- Documentos (contrato, ficha, foto).

## Endereço e formato

- Base: `https://api.motorcontabil.com`. Rotas em `/v1`.
- JSON em UTF-8. Datas `YYYY-MM-DD`. Valores em decimal com ponto (`2150.00`).
  CPF, CNPJ, CEP e códigos só com dígitos.
- **Pedido estrito:** campo que o contrato não define é recusado com
  `422 CAMPO_DESCONHECIDO`. Não há campo de empresa (é a da chave) nem de
  matrícula (é o Motor quem gera).
- O contrato completo, em OpenAPI 3.1, está em [openapi.yaml](https://developers.motorcontabil.com/openapi.yaml)
  (também em JSON, no mesmo endereço com `.json`) e é servido pela própria API em
  `https://api.motorcontabil.com/v1/openapi.json`.

## O fluxo

Ligar o **envio automático** é um ato separado de gerar a chave, feito pelo
administrador do escritório, por empresa. Ele nasce desligado.

| | envio automático **ligado** | envio automático **desligado** (padrão) |
|---|---|---|
| `POST` | `202`, estado `RECEBIDA` | `202`, estado `RECEBIDA` |
| depois | o Motor monta, aprova e transmite sem clique → `ENVIADA` | o Motor monta e põe na fila do escritório → `AGUARDANDO_ESCRITORIO`; uma pessoa aprova e transmite |
| fim | `PROCESSADA` ou `RECUSADA`, com aviso | `PROCESSADA` ou `RECUSADA`, com aviso; ou `DESCARTADA`, se o escritório descartar |

Com o **escritório suspenso**, a admissão **não** é recusada: ela é aceita
(`202`), o evento é montado e espera na fila do escritório, e sai o aviso
`admissao.aguardando_escritorio`.

## Os estados

| estado | significa |
|---|---|
| `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 eSocial processar |
| `PROCESSADA` | aceito; há número de recibo |
| `RECUSADA` | o eSocial recusou; veja `ocorrencias`. O Motor **nunca reenvia sozinho**, mas o escritório pode corrigir e reenviar, e a admissão pode voltar a `ENVIADA`. Não a trate como final |
| `DESCARTADA` | o escritório descartou o evento sem enviá-lo. O colaborador continua no Motor. Volta se o escritório restaurar o evento |

O escritório pode **corrigir** o evento antes de aprovar. Por isso o XML que a
consulta devolve é o que **foi enviado**, e pode diferir do pedido: trate-o como a
verdade.

## O cargo, a jornada e o sindicato

**O cargo é descrito; jornada e sindicato são referenciados.** O Motor procura o
cargo pelo nome no cadastro da empresa e o cria, com o CBO informado, se não
existir. Se existir, vale o CBO do cadastro e o informado é ignorado; quando os
dois diferem, a resposta traz o aviso `CBO_DO_CADASTRO`. Se o cargo existente
estiver **sem CBO**, a admissão é recusada com `CARGO_SEM_CBO` — quem corrige é
o escritório, no cadastro do cargo.

Jornada e sindicato vêm por `id`, dos catálogos. Quem os cadastra é o escritório.
Jornada com `pronta_para_esocial = false` ou sindicato sem CNPJ recusam a
admissão — peça ao escritório que os complete.