# Integração Nexos ↔ Exent Space

> Documentação centralizada da integração entre o **Nexos** (este sistema) e o **Exent Space** —
> aplicativo externo onde os colaboradores consultam e atualizam o próprio perfil, enviam reembolsos
> e notas fiscais.
>
> Última atualização: 2026-06-23

---

## 1. O que é o Exent Space

O **Exent Space** é um app externo voltado ao colaborador. Por ele, o colaborador:

- Visualiza e **atualiza os próprios dados** de perfil (dados pessoais, documentos, conta bancária).
- Envia **reembolsos** com comprovante.
- Envia **notas fiscais** (recorrência mensal e prêmio semestral).

O Nexos é a fonte de verdade do RH/Financeiro. A integração mantém os dois lados sincronizados em
**duas direções**.

---

## 2. As duas direções da integração

```
┌──────────────────────────┐                          ┌──────────────────────────┐
│       EXENT SPACE        │                          │          NEXOS           │
│  (app do colaborador)    │                          │   (core / RH / finance)  │
└──────────────────────────┘                          └──────────────────────────┘
            │                                                       │
            │  INBOUND  (Space → Nexos)                             │
            │  routes/api.php  prefixos  integration/  e  finance/  │
            │ ────────────────────────────────────────────────────▶ │
            │   pair, sync de perfil, reembolsos, notas fiscais     │
            │                                                       │
            │  OUTBOUND  (Nexos → Space)                            │
            │  POST {exent_space_url_api}/nexos/profile-sync        │
            │  POST {exent_space_url_api}/nexos/user-status         │
            │◀────────────────────────────────────────────────────  │
            │   disparado quando alguém MEXE NO CORE                │
            │   (edita/aprova/rejeita/ativa colaborador)            │
            │                                                       │
```

- **Inbound (Space → Nexos):** o Space chama a API do Nexos. Ver [02-rotas-inbound.md](02-rotas-inbound.md).
- **Outbound (Nexos → Space):** o Nexos empurra mudanças para o Space sempre que um operador altera dados
  no core. Ver [03-sync-outbound.md](03-sync-outbound.md).

---

## 3. Resumo de todos os endpoints

### Inbound — Space chama o Nexos

| Método | Rota | Direção | Controller | Auth |
|--------|------|---------|-----------|------|
| `GET`  | `/api/integration/collaborators` | Space → Nexos | `CollabController@index` | `integration.token` + `tenancy.header` |
| `PUT`  | `/api/integration/collaborators/pair` | Space → Nexos | `CollabController@pair` | `integration.token` + `tenancy.header` |
| `POST` | `/api/integration/collaborators/sync` | Space → Nexos | `CollabController@sync` | `integration.token` + `tenancy.header` |
| `POST` | `/api/integration/refunds/add` | Space → Nexos | `CollabController@addRefund` | `integration.token` + `tenancy.header` |
| `POST` | `/api/integration/refunds/get` | Space → Nexos | `CollabController@getRefund` | `integration.token` + `tenancy.header` |
| `POST` | `/api/integration/refunds/cancel` | Space → Nexos | `CollabController@cancelRefund` | `integration.token` + `tenancy.header` |
| `POST` | `/api/integration/invoices/add` | Space → Nexos | `CollabController@addInvoice` | `integration.token` + `tenancy.header` |
| `POST` | `/api/integration/invoices/get` | Space → Nexos | `CollabController@getInvoice` | `integration.token` + `tenancy.header` |
| `POST` | `/api/finance/refunds/add` | Space → Nexos | `FinanceWebhookController@addRefund` | `google.domain` + `tenancy.header` |
| `POST` | `/api/finance/refunds/get` | Space → Nexos | `FinanceWebhookController@getRefund` | `google.domain` + `tenancy.header` |
| `POST` | `/api/finance/refunds/cancel` | Space → Nexos | `FinanceWebhookController@cancelRefund` | `google.domain` + `tenancy.header` |
| `POST` | `/api/finance/invoices/add` | Space → Nexos | `FinanceWebhookController@addInvoice` | `google.domain` + `tenancy.header` |
| `POST` | `/api/finance/invoices/get` | Space → Nexos | `FinanceWebhookController@getInvoice` | `google.domain` + `tenancy.header` |

> Os grupos `integration/` e `finance/` expõem **a mesma lógica** de reembolso/NF, diferindo apenas na
> autenticação (token de integração vs. e-mail do domínio Google). Ver [02-rotas-inbound.md](02-rotas-inbound.md).

### Outbound — Nexos chama o Space

| Método | Endpoint no Space | Disparado por | Quando |
|--------|-------------------|---------------|--------|
| `POST` | `{exent_space_url_api}/nexos/profile-sync` | `CollaboratorController@syncProfileToSpace` | Aprovar/rejeitar alteração pendente; sync auto-aprovado |
| `POST` | `{exent_space_url_api}/nexos/user-status` | `CollaboratorController@syncStatusToSpace` | Ativar/desativar colaborador |

Detalhes e tabela completa de gatilhos em [03-sync-outbound.md](03-sync-outbound.md).

---

## 4. Índice desta pasta

| Arquivo | Conteúdo |
|---------|----------|
| [01-configuracao-e-autenticacao.md](01-configuracao-e-autenticacao.md) | Credenciais (`exent_space`), middlewares, headers obrigatórios, cliente HTTP outbound |
| [02-rotas-inbound.md](02-rotas-inbound.md) | Space → Nexos: cada rota, body, validação e **exemplos de retorno JSON** |
| [03-sync-outbound.md](03-sync-outbound.md) | Nexos → Space: gatilhos no core, payloads de `profile-sync` e `user-status` |
| [04-fluxo-alteracoes-colaborador.md](04-fluxo-alteracoes-colaborador.md) | Ciclo completo de `CoreCollabPendingChange` (pendente/aprovado/rejeitado) |

---

## 5. Arquivos-fonte críticos

| Componente | Caminho |
|-----------|---------|
| Rotas de API | [routes/api.php](../../routes/api.php) |
| Controller inbound (integration) | [CollabController.php](../../app/Http/Controllers/Integrations/CollabController.php) |
| Controller inbound (finance) | [FinanceWebhookController.php](../../app/Http/Controllers/Finance/Api/Webhook/FinanceWebhookController.php) |
| Controller do core + sync outbound | [CollaboratorController.php](../../app/Http/Controllers/Core/CollaboratorController.php) |
| Credenciais do Space | [IntegrationCredentialService.php](../../app/Services/IntegrationCredentialService.php) |
| Cliente HTTP | [GuzzleService.php](../../app/Services/GuzzleService.php) |
| Middleware de auth inbound | [IntegrationApiTokenMiddleware.php](../../app/Http/Middleware/IntegrationApiTokenMiddleware.php) |
| Registro de middlewares | [bootstrap/app.php](../../bootstrap/app.php) |
| Model de alterações | [CoreCollabPendingChange.php](../../app/Models/Core/CoreCollabPendingChange.php) |
| Model do colaborador | [CoreCollaborator.php](../../app/Models/Core/CoreCollaborator.php) |