# Envia uma admissão

`POST /v1/admissoes`

Confere o pedido inteiro **antes de gravar**: forma, referências
(jornada, sindicato, CBO, município) e tudo o que o S-2200 exige. Se algo
faltar ou estiver inválido, responde `422` e **nada é gravado**.

Passando, cria o colaborador e o vínculo numa transação só, gera a
matrícula e responde `202`. O envio ao eSocial segue em segundo plano.

O cabeçalho `Idempotency-Key` é obrigatório, e ela vale **por empresa**:
a mesma `Idempotency-Key` com o mesmo corpo devolve a mesma resposta e não
cria nada — **mesmo que o reenvio venha por outra chave de integração
ativa da mesma empresa** (quem troca de chave no meio e reenvia recebe a
resposta guardada); com outro corpo, `409 IDEMPOTENCIA_CONFLITO`; com o
primeiro pedido ainda em processamento, `409 IDEMPOTENCIA_EM_CURSO`. A
`Idempotency-Key` só fica presa a um pedido quando a resposta é `202` — uma
recusa `4xx` ou `503` não a consome.

A admissão entra na contagem de colaboradores ativos do escritório, como
a feita pela tela; não há cobrança própria por chamada.

Escritório suspenso **não** recusa a entrada: a admissão é aceita e o
evento montado, mas espera na fila do escritório, e o aviso
`admissao.aguardando_escritorio` diz isso.

## 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.
- `Idempotency-Key` (texto · obrigatório · de 8 a 100 caracteres · formato `^[A-Za-z0-9._:-]+$`) — Identificador único deste pedido, gerado pelo seu sistema (um UUID serve). Reenvie com a mesma chave quando não souber se o pedido anterior chegou.

## Corpo

Escopo da v1: empregado CLT (categoria 101) por prazo indeterminado, em
contrato de experiência ou por prazo determinado; aprendiz (103); com ou
sem deficiência e dependentes. Não há campo de matrícula nem de empresa:
a empresa é a da chave, e a matrícula é gerada pelo Motor.

- `trabalhador` (objeto · obrigatório)
  - `trabalhador.nome_completo` (texto · obrigatório · de 2 a 70 caracteres) — Uma linha só, com ao menos um caractere visível (`TS_nome` do XSD).
  - `trabalhador.cpf` (texto · obrigatório · 11 dígitos) — Só dígitos. Os dígitos verificadores são conferidos (`CPF_INVALIDO`).
  - `trabalhador.data_nascimento` (data (AAAA-MM-DD) · obrigatório)
  - `trabalhador.genero` (texto · obrigatório) — Sexo declarado ao eSocial (o leiaute só aceita M ou F).
    - `MASCULINO` — Masculino (M no eSocial)
    - `FEMININO` — Feminino (F no eSocial)
  - `trabalhador.raca_cor` (texto · obrigatório) — Por nome, não por código: a ordem do cadastro do Motor difere da tabela do eSocial, e o nome não deixa margem. "Não informado" não existe aqui — o eSocial o recusa para admissões desde 22/04/2024.
    - `INDIGENA` — Indígena (código 5 no eSocial)
    - `BRANCA` — Branca (código 1 no eSocial)
    - `PRETA` — Preta (código 2 no eSocial)
    - `AMARELA` — Amarela (código 4 no eSocial)
    - `PARDA` — Parda (código 3 no eSocial)
  - `trabalhador.grau_instrucao` (inteiro · obrigatório) — Código do grau de instrução do eSocial (01 a 12), sem o zero à esquerda.
    - `1` — Analfabeto, inclusive o que, embora tenha recebido instrução, não se alfabetizou
    - `2` — Até o 5º ano incompleto do ensino fundamental (antiga 4ª série) ou que se tenha alfabetizado sem ter frequentado escola regular
    - `3` — 5º ano completo do ensino fundamental
    - `4` — Do 6º ao 9º ano do ensino fundamental incompleto (antiga 5ª a 8ª série)
    - `5` — Ensino fundamental completo
    - `6` — Ensino médio incompleto
    - `7` — Ensino médio completo
    - `8` — Educação superior incompleta
    - `9` — Educação superior completa
    - `10` — Pós-graduação completa
    - `11` — Mestrado completo
    - `12` — Doutorado completo
  - `trabalhador.estado_civil` (texto · opcional) — Gravado no cadastro. Hoje o S-2200 do Motor não o declara.
    - `SOLTEIRO` — Solteiro(a)
    - `CASADO` — Casado(a)
    - `DIVORCIADO` — Divorciado(a)
    - `VIUVO` — Viúvo(a)
    - `SEPARADO` — Separado(a)
    - `UNIAO_ESTAVEL` — União estável
  - `trabalhador.nome_mae` (texto · opcional · de 2 a 70 caracteres)
  - `trabalhador.nome_pai` (texto · opcional · de 2 a 70 caracteres)
  - `trabalhador.email` (e-mail · opcional · de 6 a 60 caracteres · formato `^[^@\s]+@[^@\s]+\.[^@\s]+$`) — Fora deste formato é recusado com `422 DADOS_INVALIDOS` (`EMAIL_INVALIDO`) — nunca descartado em silêncio.
  - `trabalhador.celular` (texto · opcional · de 10 a 13 dígitos) — Com DDD, só dígitos.
- `endereco` (objeto · obrigatório)
  - `endereco.cep` (texto · obrigatório · 8 dígitos)
  - `endereco.logradouro` (texto · obrigatório · de 1 a 100 caracteres) — O primeiro caractere não pode ser espaço (`TS_texto_100` do XSD).
  - `endereco.numero` (texto · opcional · de 1 a 10 caracteres) — Uma linha, com ao menos um caractere visível (`TS_nrLograd`). Ausente, o Motor declara "S/N".
  - `endereco.complemento` (texto · opcional · de 1 a 30 caracteres) — Uma linha, com ao menos um caractere visível (`TS_complemento`).
  - `endereco.bairro` (texto · obrigatório · de 1 a 90 caracteres) — Uma linha, com ao menos um caractere visível (`TS_bairro`).
  - `endereco.cod_municipio_ibge` (texto · obrigatório · 7 dígitos) — Código IBGE do município (7 dígitos). Precisa existir (`MUNICIPIO_INVALIDO`) e ser da `uf` informada (`MUNICIPIO_DIVERGE_DA_UF`).
  - `endereco.uf` (texto · obrigatório)
    - `AC` — Acre
    - `AL` — Alagoas
    - `AM` — Amazonas
    - `AP` — Amapá
    - `BA` — Bahia
    - `CE` — Ceará
    - `DF` — Distrito Federal
    - `ES` — Espírito Santo
    - `GO` — Goiás
    - `MA` — Maranhão
    - `MG` — Minas Gerais
    - `MS` — Mato Grosso do Sul
    - `MT` — Mato Grosso
    - `PA` — Pará
    - `PB` — Paraíba
    - `PE` — Pernambuco
    - `PI` — Piauí
    - `PR` — Paraná
    - `RJ` — Rio de Janeiro
    - `RN` — Rio Grande do Norte
    - `RO` — Rondônia
    - `RR` — Roraima
    - `RS` — Rio Grande do Sul
    - `SC` — Santa Catarina
    - `SE` — Sergipe
    - `SP` — São Paulo
    - `TO` — Tocantins
- `vinculo` (objeto · obrigatório)
  - `vinculo.data_admissao` (data (AAAA-MM-DD) · obrigatório) — O prazo do S-2200 é a véspera. Data de hoje ou passada é aceita e enviada; a resposta diz `fora_do_prazo: true`.
  - `vinculo.categoria` (inteiro · obrigatório) — Categoria do trabalhador (Tabela 01 do eSocial).
    - `101` — Empregado - Geral, inclusive o empregado público da administração direta ou indireta contratado pela CLT
    - `103` — Empregado - Aprendiz
  - `vinculo.salario_base` (número · obrigatório · maior que 0) — Salário mensal, em reais, com no máximo duas casas decimais. Mais que isso é recusado pelo servidor com `422 DADOS_INVALIDOS` (`SALARIO_INVALIDO`). A regra não está no schema porque `multipleOf: 0.01` reprova valores válidos por arredondamento binário (1234.56).
  - `vinculo.horas_mensais` (inteiro · opcional · de 1 a 220) — Divisor do salário-hora na folha (220 = 44 h semanais). Não é a jornada: o que o S-2200 declara sai da jornada do catálogo. Ausente, o Motor o deriva da jornada escolhida (horas semanais × 5, até 220); sem jornada (`tp_reg_jor` 2, 3 ou 4), 220. Fora de 1 a 220: `HORAS_MENSAIS_INVALIDAS`.
  - `vinculo.tp_reg_jor` (inteiro · obrigatório) — Regime de jornada do eSocial. O 1 exige `jornada_id`.
    - `1` — Submetido a horário de trabalho (Capítulo II do Título II da CLT)
    - `2` — Atividade externa especificada no inciso I do art. 62 da CLT
    - `3` — Função especificada no inciso II do art. 62 da CLT
    - `4` — Teletrabalho, previsto no inciso III do art. 62 da CLT
  - `vinculo.cargo` (objeto · obrigatório) — Descrito, não referenciado. O Motor procura um cargo com o mesmo nome (sem diferenciar maiúsculas) no cadastro da empresa e o cria, com o CBO informado, se não houver. Se o cargo **já existir**, vale o CBO do cadastro e o informado é ignorado — cargo é cadastro da empresa, e trocar o CBO dele mudaria o de todos os colaboradores daquele cargo. O aviso `CBO_DO_CADASTRO` sai **só quando o CBO informado difere do cadastro**. Se o cargo existente estiver **sem CBO**, a admissão é recusada com `CARGO_SEM_CBO`, e quem corrige é o **escritório**, no cadastro do cargo — o CBO informado não o preenche.
    - `vinculo.cargo.nome` (texto · obrigatório · de 1 a 100 caracteres)
    - `vinculo.cargo.cbo` (texto · obrigatório · 6 dígitos) — Código da CBO. Precisa existir na classificação (`CBO_FORA_DO_CATALOGO`).
  - `vinculo.jornada_id` (uuid · opcional) — Id de `GET /v1/catalogos/jornadas`. Obrigatório quando `tp_reg_jor` = 1.
  - `vinculo.sindicato_id` (uuid · obrigatório) — Id de `GET /v1/catalogos/sindicatos`.
- `contrato` (uma das formas abaixo · obrigatório)
  - quando `tipo = "INDETERMINADO"`:
    - `contrato.tipo` ("INDETERMINADO" · obrigatório)
  - quando `tipo = "EXPERIENCIA"` — Contrato de experiência é prazo determinado para o eSocial: o S-2200 declara o término do 1º período (o dia da admissão conta como dia 1). A prorrogação para o 2º período é ato do escritório no Motor (S-2206) e não passa por esta API. A soma dos dois períodos não passa de 90 dias (`EXPERIENCIA_ACIMA_DE_90_DIAS`).:
    - `contrato.tipo` ("EXPERIENCIA" · obrigatório)
    - `contrato.dias_primeiro_periodo` (inteiro · obrigatório · de 1 a 90)
    - `contrato.dias_segundo_periodo` (inteiro ou null · opcional · de 1 a 89) — Planejado, não declarado. Nulo ou ausente = ainda não decidido.
    - `contrato.clausula_assecuratoria` (true / false · obrigatório) — Cláusula assecuratória do direito recíproco de rescisão antecipada (art. 481 da CLT).
  - quando `tipo = "PRAZO_DETERMINADO"` — Contrato por prazo determinado, para a categoria 101 ou 103, com a data de término obrigatória. Obrigatório para o aprendiz (categoria 103) — sem ele, `APRENDIZ_DADOS_OBRIGATORIOS`.:
    - `contrato.tipo` ("PRAZO_DETERMINADO" · obrigatório)
    - `contrato.data_termino` (data (AAAA-MM-DD) · obrigatório) — Igual ou posterior à `data_admissao` (`DATA_TERMINO_INVALIDA`).
    - `contrato.clausula_assecuratoria` (true / false · obrigatório)
- `deficiencia` (objeto · opcional) — Envie só para pessoa com deficiência ou reabilitada: pelo menos um dos seis indicadores tem de ser `true` (`PCD_TIPO_OBRIGATORIO`). Ausente, o grupo não é declarado. Os indicadores são só `true`, `false` ou ausentes (texto como "sim" é recusado, nunca convertido). Recusas, em `campos[]`: `PCD_TIPO_OBRIGATORIO` (nenhum indicador verdadeiro); `PCD_COTA_INCOERENTE` (`conta_na_cota` sem deficiência nem reabilitação, ou faltando com elas); `PCD_COTA_APRENDIZ` (aprendiz — categoria 103 — com `conta_na_cota: true`: o aprendiz com deficiência não conta na cota, MOS §23.6); `PCD_TIPO_SEM_DEFICIENCIA` (tipo de deficiência ou observação sem a deficiência).
  - `deficiencia.fisica` (true / false · opcional · padrão `false`)
  - `deficiencia.visual` (true / false · opcional · padrão `false`)
  - `deficiencia.auditiva` (true / false · opcional · padrão `false`)
  - `deficiencia.mental` (true / false · opcional · padrão `false`)
  - `deficiencia.intelectual` (true / false · opcional · padrão `false`)
  - `deficiencia.reabilitado` (true / false · opcional · padrão `false`) — Beneficiário reabilitado ou readaptado.
  - `deficiencia.conta_na_cota` (true / false · obrigatório) — Conta na cota de pessoas com deficiência (Lei 8.213/1991)? Pode ser `false` com deficiência — a pessoa pode recusar a ação afirmativa. Tem de ser `false` para o aprendiz (`PCD_COTA_APRENDIZ`).
  - `deficiencia.observacao` (texto · opcional · de 1 a 255 caracteres) — O primeiro caractere não pode ser espaço (`TS_texto_255` do XSD).
- `aprendiz` (objeto · opcional) — Obrigatório, e só aceito, quando `vinculo.categoria` = 103: fora dela, `APRENDIZ_FORA_DA_CATEGORIA`; na 103 sem a modalidade, ou sem contrato `PRAZO_DETERMINADO`, `APRENDIZ_DADOS_OBRIGATORIOS` (o grupo do aprendiz é obrigatório no S-2200 desde 22/01/2024). Recusas, em `campos[]`, com o código do servidor: `APRENDIZ_MODALIDADE_AUSENTE` · `APRENDIZ_INVALIDO` (forma) · `APRENDIZ_ENTIDADE_AUSENTE` (DIRETA sem a entidade qualificadora) · `APRENDIZ_ESTABELECIMENTO_AUSENTE` (INDIRETA sem o estabelecimento) · `APRENDIZ_INCOERENTE` (campo da outra modalidade) · `APRENDIZ_CNPJ_INVALIDO` (entidade qualificadora ou prática) · `APRENDIZ_INSCRICAO_INVALIDA` (estabelecimento da cota) · `APRENDIZ_INSCRICAO_DA_PROPRIA_EMPRESA` · `APRENDIZ_CPF_NAO_SUPORTADO`.
  - `aprendiz.modalidade` (texto · obrigatório) — Como o aprendiz é contratado.
    - `DIRETA` — A própria empresa da chave cumpre a cota e contrata o aprendiz (exige `cnpj_entidade_qualificadora`).
    - `INDIRETA` — A empresa da chave é a entidade sem fins lucrativos ou de prática desportiva que contrata o aprendiz para outro estabelecimento cumprir a cota (exige `estabelecimento_da_cota`).
  - `aprendiz.cnpj_entidade_qualificadora` (texto · opcional · 14 dígitos) — CNPJ da entidade qualificadora, na contratação direta. Os dígitos verificadores são conferidos pelo servidor (`APRENDIZ_CNPJ_INVALIDO`).
  - `aprendiz.estabelecimento_da_cota` (objeto · opcional) — Só na contratação INDIRETA: o estabelecimento **para o qual** a contratação foi efetivada — quem cumpre a cota com este aprendiz. **Não é a empresa da chave**: a raiz do CNPJ (8 primeiros dígitos) tem de ser diferente da do empregador (`APRENDIZ_INSCRICAO_DA_PROPRIA_EMPRESA`). Os dígitos verificadores são conferidos pelo servidor (`APRENDIZ_INSCRICAO_INVALIDA`). **Só CNPJ.** O leiaute admite CPF, mas a biblioteca do eSocial não o aceita nas alterações contratuais (S-2206) deste aprendiz: com CPF, todo reajuste futuro ficaria travado. CPF é recusado com `APRENDIZ_CPF_NAO_SUPORTADO` até a biblioteca aceitá-lo.
    - `aprendiz.estabelecimento_da_cota.tipo_inscricao` ("CNPJ" · obrigatório)
    - `aprendiz.estabelecimento_da_cota.numero` (texto · obrigatório · 14 dígitos)
  - `aprendiz.cnpj_pratica` (texto · opcional · 14 dígitos) — Estabelecimento onde acontecem as atividades práticas, quando for outro. Os dígitos verificadores são conferidos pelo servidor (`APRENDIZ_CNPJ_INVALIDO`).
- `dependentes` (lista de objeto · opcional · até 99 itens) — Até 99 (`DEPENDENTE_LIMITE`). Não pode haver dois com o mesmo CPF (`DEPENDENTE_CPF_REPETIDO`), nem dois com o mesmo `tipo` + `nome` + `data_nascimento` (`DEPENDENTE_REPETIDO`). Os dependentes marcados `dependente_irrf` são a contagem que o Motor usa na dedução do IRRF — não há campo de "número de dependentes".
  - `dependentes.N.tipo` (texto · obrigatório) — Código da Tabela 07 do eSocial (tipo de dependente), **obrigatório para todo dependente** — a biblioteca do eSocial o exige sempre, embora o XSD só o peça com IRRF (`DEPENDENTE_TIPO_OBRIGATORIO`). Só os vigentes: 04 e 07 foram encerrados em 25/04/2023, e 05 e 08 não existem (`DEPENDENTE_TIPO_INVALIDO`).
    - `01` — Cônjuge
    - `02` — Companheiro(a) com o(a) qual tenha filho ou viva há mais de 5 (cinco) anos ou possua declaração de união estável
    - `03` — Filho(a) ou enteado(a)
    - `06` — Irmão(ã), neto(a) ou bisneto(a) sem arrimo dos pais, do(a) qual detenha a guarda judicial
    - `09` — Pais, avós e bisavós
    - `10` — Menor pobre do qual detenha a guarda judicial
    - `11` — A pessoa absolutamente incapaz, da qual seja tutor ou curador
    - `12` — Ex-cônjuge
    - `99` — Agregado/Outros (exige `descricao`)
  - `dependentes.N.nome` (texto · obrigatório · de 2 a 70 caracteres) — Uma linha só, de 2 a 70 caracteres (`TS_nmDep`).
  - `dependentes.N.data_nascimento` (data (AAAA-MM-DD) · obrigatório) — Não pode ser futura nem anterior a 1890 (`DEPENDENTE_NASCIMENTO_INVALIDO`).
  - `dependentes.N.cpf` (texto · opcional · 11 dígitos) — Obrigatório quando `dependente_irrf` = true (`DEPENDENTE_CPF_OBRIGATORIO`). Dígitos conferidos (`DEPENDENTE_CPF_INVALIDO`); não pode ser o do próprio trabalhador (`DEPENDENTE_CPF_DO_TRABALHADOR`) nem repetir o de outro dependente (`DEPENDENTE_CPF_REPETIDO`).
  - `dependentes.N.dependente_irrf` (true / false · opcional · padrão `false`) — Dependente para dedução do Imposto de Renda. Os marcados são a contagem que a folha usa.
  - `dependentes.N.dependente_salario_familia` (true / false · opcional · padrão `false`)
  - `dependentes.N.incapaz_para_trabalho` (true / false · opcional · padrão `false`) — Tem incapacidade física ou mental para o trabalho.
  - `dependentes.N.descricao` (texto · opcional · de 1 a 100 caracteres) — Obrigatória quando `tipo` = "99" (`DEPENDENTE_DESCRICAO_OBRIGATORIA`), e só aceita nesse caso (`DEPENDENTE_DESCRICAO_INDEVIDA`). O primeiro caractere não pode ser espaço (`TS_descrDep` = `TS_texto_100`).

## Respostas

### 202

Admissão aceita. O colaborador já existe no Motor e a matrícula é
definitiva — guarde-a. Repetida pela mesma `Idempotency-Key` com o
mesmo corpo, volta exatamente esta resposta, com o cabeçalho
`X-Motor-Repetido: true`.

Cabeçalhos:

- `X-Motor-Repetido` — `true` quando a resposta é a repetição de um pedido já aceito.

Corpo:

- `id` (uuid · obrigatório) — Número de acompanhamento.
- `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) — Gerada pelo Motor pelo modelo de matrícula da empresa. Definitiva: o eSocial a fixa no primeiro envio. Guarde-a junto do CPF.
- `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) — Último dia para enviar o S-2200 (a véspera da admissão).
- `fora_do_prazo` (true / false · obrigatório) — `true` quando a `data_admissao` é o dia do pedido ou anterior (horário de Brasília) — o prazo é a véspera, então nesse caso ele já passou. Não bloqueia o envio.
- `recebida_em` (data e hora (ISO 8601) · obrigatório)
- `avisos` (lista de objeto · obrigatório) — Observações que não impediram a admissão, como `CBO_DO_CADASTRO` (cargo já existente com CBO diferente do informado — ver `Cargo`).
  - `avisos.N.codigo` (texto · obrigatório)
  - `avisos.N.mensagem` (texto · obrigatório)

```json
{
  "id": "9a3f0c55-7d7e-4a52-b8c1-5d9f3c2e1a10",
  "estado": "RECEBIDA",
  "matricula": "MOT-000042",
  "ambiente": "PRODUCAO",
  "prazo_legal": "2026-11-02",
  "fora_do_prazo": false,
  "recebida_em": "2026-10-28T13:05:12-03:00",
  "avisos": []
}
```

### 400

`IDEMPOTENCY_KEY_INVALIDA` — o cabeçalho `Idempotency-Key` falta ou está
fora da forma (8 a 100 caracteres: letras, dígitos e `. _ : -`). Nada foi
gravado nem consumido.

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)

### 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)

### 403

A chave é válida, mas a empresa não pode admitir pela API agora.
`EMPRESA_NAO_HABILITADA` — a empresa não está habilitada no eSocial pelo Motor.
`CERTIFICADO_INDISPONIVEL` — sem certificado A1 válido no cofre (ausente ou vencido).
`CHAVE_SEM_ESCOPO` — a chave não alcança a admissão.
Nada foi gravado. Quem resolve é o escritório.

Escritório suspenso **não** é recusa de entrada: com o escritório suspenso a admissão é aceita (`202`), o
evento é montado e espera na fila do escritório, e sai o 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)

### 409

`TRABALHADOR_JA_ADMITIDO` — já existe colaborador com este CPF nesta
empresa (inclusive desligado; readmissão está fora da v1).
`IDEMPOTENCIA_CONFLITO` — a `Idempotency-Key` já foi usada nesta empresa
com outro corpo.
`IDEMPOTENCIA_EM_CURSO` — um pedido com a mesma `Idempotency-Key` ainda
está sendo processado nesta empresa; repita em alguns segundos.

Cabeçalhos:

- `Retry-After` — Só em `IDEMPOTENCIA_EM_CURSO`, em segundos.

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)

### 413

`CORPO_GRANDE_DEMAIS` — o corpo passa de 256 KB. Nada foi gravado.

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)

### 422

Nada foi gravado. `campos[]` diz o que corrigir, campo a campo.
`CAMPO_DESCONHECIDO` — o corpo tem campo que este contrato não define
(inclusive `matricula`, que é gerada pelo Motor).
`DADOS_INVALIDOS` — campo com forma ou valor inválido, ou referência que
não existe (jornada, sindicato, CBO, município).
`DADOS_FALTANDO` — falta o que o S-2200 exige.
Quando há problemas de mais de um tipo, o código é o primeiro desta
ordem: CAMPO_DESCONHECIDO, DADOS_INVALIDOS, DADOS_FALTANDO.

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)

```json
{
  "codigo": "DADOS_FALTANDO",
  "mensagem": "O S-2200 não pode ser montado com estes dados.",
  "campos": [
    {
      "campo": "vinculo.jornada_id",
      "codigo": "JORNADA_AUSENTE",
      "mensagem": "Informe a jornada (obrigatória quando tp_reg_jor = 1)."
    },
    {
      "campo": "trabalhador.grau_instrucao",
      "codigo": "GRAU_INSTRUCAO_AUSENTE",
      "mensagem": "Informe o grau de instrução."
    }
  ]
}
```

### 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 -X POST https://api.motorcontabil.com/v1/admissoes \
  -H "Authorization: Bearer $CHAVE_MOTOR" \
  -H "Idempotency-Key: 7f9c2b4e-5a0d-4c1e-9b7a-3e2d1c0b9a88" \
  -H "Content-Type: application/json" \
  -d @admissao.json
```

Node:

```js
// Node 18 ou mais novo (fetch nativo), em módulo ES.
import { randomUUID } from 'node:crypto';

// Gere uma Idempotency-Key por admissão e guarde-a: o reenvio usa a mesma.
const idempotencyKey = randomUUID();

const resposta = await fetch('https://api.motorcontabil.com/v1/admissoes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHAVE_MOTOR}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(admissao),
});
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.Post, "/v1/admissoes");
// Uma Idempotency-Key por admissão; o reenvio usa a mesma.
pedido.Headers.Add("Idempotency-Key", idempotencyKey);
pedido.Content = new StringContent(admissaoJson, Encoding.UTF8, "application/json");

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

Corpo — Contrato de experiência de 45 dias, sem deficiência nem dependentes:

```json
{
  "trabalhador": {
    "nome_completo": "Maria Aparecida Souza",
    "cpf": "52998224725",
    "data_nascimento": "1998-03-14",
    "genero": "FEMININO",
    "raca_cor": "PARDA",
    "grau_instrucao": 7,
    "estado_civil": "SOLTEIRO",
    "email": "maria.souza@example.com",
    "celular": "62991234567"
  },
  "endereco": {
    "cep": "74000000",
    "logradouro": "Rua 3",
    "numero": "120",
    "bairro": "Setor Central",
    "cod_municipio_ibge": "5208707",
    "uf": "GO"
  },
  "vinculo": {
    "data_admissao": "2026-11-03",
    "categoria": 101,
    "salario_base": 2150,
    "tp_reg_jor": 1,
    "cargo": {
      "nome": "Auxiliar administrativo",
      "cbo": "411005"
    },
    "jornada_id": "6f1c2a1e-1111-4c4c-9a9a-000000000001",
    "sindicato_id": "0b7e9d2c-2222-4d4d-8b8b-000000000002"
  },
  "contrato": {
    "tipo": "EXPERIENCIA",
    "dias_primeiro_periodo": 45,
    "dias_segundo_periodo": 45,
    "clausula_assecuratoria": false
  }
}
```

Corpo — Aprendiz (categoria 103), contratação direta, com um dependente:

```json
{
  "trabalhador": {
    "nome_completo": "João Pedro Lima",
    "cpf": "11144477735",
    "data_nascimento": "2009-07-02",
    "genero": "MASCULINO",
    "raca_cor": "BRANCA",
    "grau_instrucao": 6
  },
  "endereco": {
    "cep": "74000000",
    "logradouro": "Avenida Goiás",
    "bairro": "Setor Central",
    "cod_municipio_ibge": "5208707",
    "uf": "GO"
  },
  "vinculo": {
    "data_admissao": "2026-11-03",
    "categoria": 103,
    "salario_base": 1100,
    "tp_reg_jor": 1,
    "cargo": {
      "nome": "Aprendiz de auxiliar administrativo",
      "cbo": "411005"
    },
    "jornada_id": "6f1c2a1e-1111-4c4c-9a9a-000000000003",
    "sindicato_id": "0b7e9d2c-2222-4d4d-8b8b-000000000002"
  },
  "contrato": {
    "tipo": "PRAZO_DETERMINADO",
    "data_termino": "2028-11-02",
    "clausula_assecuratoria": false
  },
  "aprendiz": {
    "modalidade": "DIRETA",
    "cnpj_entidade_qualificadora": "33641358000152"
  },
  "dependentes": [
    {
      "tipo": "03",
      "nome": "Ana Lima",
      "data_nascimento": "2026-01-20",
      "cpf": "39053344705",
      "dependente_irrf": true,
      "dependente_salario_familia": true
    }
  ]
}
```