# Criar usuário

`POST /v1/usuarios`

Convida uma pessoa para o portal da Conta com um papel: `administrador`, `operador` ou `financeiro`. A senha provisória aparece uma vez na resposta; o autenticador é cadastrado no primeiro login. Só administrador.

## Corpo (`application/json`)

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `email` | texto | sim | E-mail do usuário |
| `nome` | texto | sim | Nome completo (pelo menos 2 caracteres) |
| `papel` | `administrador` \| `operador` \| `financeiro` | sim | `administrador`, `operador` ou `financeiro` |
| `so_sso` | booleano | não | Se `true`, a pessoa só entra pelo login único da empresa (padrão `false`) |

## Respostas

| HTTP | Significa |
|---|---|
| 201 | Criado |
| 422 | Corpo ou parâmetros com formato inválido (`detail` lista os campos) |

### Exemplo de resposta

```json
{
  "id": "7d6c5b4a-3928-4f1e-9d0c-b1a2f3e4d5c6",
  "conta_id": "0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b",
  "email": "fulano@escritorio.com.br",
  "nome": "Fulano de Tal",
  "papel": "operador",
  "senha_provisoria": "q3X9-p0aZ7mK"
}
```

## Erros

Recusas vêm como `{"detail": {"erro": "<código>", "mensagem": "…"}}`.

| HTTP | `erro` | Significa |
|---|---|---|
| 401 | — | Chave ausente ou inválida |
| 409 | `email_ja_cadastrado` | Este e-mail já tem usuário |

## Exemplos de requisição

### Bash

```bash
curl -X POST 'https://sync.lops.com.br/v1/usuarios' \
  -H "Authorization: Bearer $SYNC_CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{"email":"fulano@escritorio.com.br","nome":"Fulano de Tal","papel":"operador"}'
```

### JavaScript

```javascript
const resposta = await fetch("https://sync.lops.com.br/v1/usuarios", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNC_CHAVE}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "email": "fulano@escritorio.com.br",
    "nome": "Fulano de Tal",
    "papel": "operador"
  }),
});
console.log(resposta.status, await resposta.json());
```

### Python

```python
import os

import requests

resposta = requests.post(
    "https://sync.lops.com.br/v1/usuarios",
    headers={"Authorization": f"Bearer {os.environ['SYNC_CHAVE']}"},
    json={
        "email": "fulano@escritorio.com.br",
        "nome": "Fulano de Tal",
        "papel": "operador",
    },
)
print(resposta.status_code, resposta.json())
```

### PHP

```php
<?php
$ch = curl_init('https://sync.lops.com.br/v1/usuarios');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNC_CHAVE'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => 'fulano@escritorio.com.br',
        'nome' => 'Fulano de Tal',
        'papel' => 'operador',
    ]),
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
var_dump($status, json_decode($corpo, true));
```