> ## Documentation Index
> Fetch the complete documentation index at: https://docs.piposaude.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Como fazer uma inclusão
> Incluir novos membros, grupos familiares ou benefícios em membros existentes.
Uma inclusão registra um novo membro (titular e/ou dependentes) ou adiciona um benefício a um membro que
já existe. As inclusões são **assíncronas**: a API responde com um `request-id` e o processamento continua
em segundo plano — acompanhe o resultado pela [consulta de requisição](#acompanhando-o-resultado) ou por
[webhooks](/docs/guias/webhooks).
Antes de começar, revise [Convenções](/docs/comecar/convencoes) — valores em centavos,
datas ISO 8601, campos em kebab-case. Toda chamada exige o header `Authorization: Bearer `
(ver [Autenticação](/docs/comecar/autenticacao)).
## Escolhendo o endpoint
| Cenário | Endpoint |
| --------------------------------------------------- | ----------------------------------------------- |
| Incluir novos membros / grupos familiares (em lote) | `POST /v1/enrollment/inclusion` |
| Incluir um benefício em um membro já existente | `POST /v1/enrollment/inclusion/{member-tax-id}` |
## Inclusão em lote
Informe `company-tax-id` e a lista `members`. Cada membro traz seus dados de perfil e o mapa
`products` (tipo de produto → entradas com `start-option` e `name` ou `product-id`).
`POST /v1/enrollment/inclusion` com o corpo JSON.
A resposta `200` traz `{ "request-id": "..." }`. Use-o para acompanhar o processamento.
```json theme={null}
{
"company-tax-id": "12345678000190",
"members": [
{
"beneficiary-type": "primary",
"name": "João Silva",
"tax-id": "12345678900",
"mothers-name": "Maria Silva",
"date-of-birth": "1985-05-15",
"gender": "male",
"marital-status": "married",
"admission-date": "2024-01-01",
"work-contract-type": "brazil-labor-law",
"job-title": "Desenvolvedor Senior",
"employee-id": "EMP001",
"salary": 800000,
"email-corporate": "joao.silva@acme.com",
"email-private": "joao.silva@email.com",
"phone": "11987654321",
"products": {
"health-insurance": [
{ "name": "Plano Saúde Premium", "start-option": "on-inclusion-date" }
]
}
}
]
}
```
O titular e seus dependentes vão no mesmo array `members`. O dependente é vinculado pelo
`primary-tax-id`. Documentos previamente enviados (ver
[envio de documentos](/docs/comecar/convencoes#envio-de-documentos-em-uma-movimenta%C3%A7%C3%A3o))
são referenciados pelo `document-id`.
```json theme={null}
{
"company-tax-id": "12345678000190",
"members": [
{
"beneficiary-type": "primary",
"name": "Mariazinha da Silva",
"tax-id": "12345678900",
"mothers-name": "Mãe Maria Silva",
"date-of-birth": "1985-05-15",
"gender": "female",
"marital-status": "married",
"admission-date": "2024-01-01",
"work-contract-type": "brazil-labor-law",
"job-title": "Desenvolvedora Senior",
"employee-id": "EMP001",
"salary": 800000,
"email-corporate": "maria.silva@acme.com",
"email-private": "maria.silva@email.com",
"phone": "11987654321",
"documents": [
{ "document-id": "cd56c772-e8d9-4ce9-82c7-7bb155de40cc", "document-type": "identification-document-with-tax-id" },
{ "document-id": "957ef952-8515-4dd6-b356-c1434a8e9f33", "document-type": "enrollment-request" }
],
"products": {
"health-insurance": [
{ "product-id": "4de3d975-a4ed-47ab-aab9-d4a190fea06f", "start-option": "on-inclusion-date" }
],
"dental-insurance": [
{ "product-id": "6b9616e3-f76b-414f-b5d5-75ebc90d5895", "start-option": "on-inclusion-date" }
]
}
},
{
"beneficiary-type": "dependent",
"name": "Filho da Mariazinha",
"tax-id": "41165181070",
"primary-tax-id": "12345678900",
"mothers-name": "Mariazinha da Silva",
"date-of-birth": "2020-03-01",
"gender": "male",
"marital-status": "single",
"dependent-relationship-type": "child",
"dependent-relationship-start-date": "2020-03-01",
"phone": "11911234456",
"email-private": "filho.mariazinha@example.com",
"weight": 7000,
"height": 18000,
"handicapped": "no",
"documents": [
{ "document-id": "e079e1ad-bdff-49e9-85f7-fbd228ca15fd", "document-type": "document-proving-relationship" }
],
"products": {
"health-insurance": [
{ "product-id": "4de3d975-a4ed-47ab-aab9-d4a190fea06f", "start-option": "on-inclusion-date" }
]
}
}
]
}
```
### Respostas de erro
```json theme={null}
{ "error": "Not entitled to access this company" }
```
A resposta devolve o lote com as `offenses` de cada membro. Ver
[Quando a movimentação não é aceita (422)](#quando-a-movimentação-não-é-aceita-422).
## Inclusão de benefício em membro existente
Use `POST /v1/enrollment/inclusion/{member-tax-id}` com o CPF do membro no caminho. O corpo traz
`company-tax-id` e `member-benefits`.
```json theme={null}
{
"company-tax-id": "12345678000190",
"member-benefits": {
"beneficiary-type": "primary",
"products": {
"health-insurance": [
{ "name": "Plano Saúde Premium", "start-option": "on-inclusion-date" }
]
}
}
}
```
A resposta de sucesso (`200`) traz o `request-id`:
```json theme={null}
{ "request-id": "bbb22222-e89b-12d3-a456-426614174007" }
```
### Respostas de erro
```json theme={null}
{ "error": "Member is not primary with the specified company" }
```
```json theme={null}
{ "error": "Not entitled to modify this member" }
```
Além dos dados do membro, a resposta inclui as `offenses` que indicam quais validações falharam.
```json theme={null}
{
"result": {
"beneficiary-type": "primary",
"company-tax-id": "12345678000190",
"products": {
"health-insurance": [
{ "name": "Plano Saúde Premium", "start-option": "on-inclusion-date" }
]
},
"offenses": ["product-health-insurance-0-already-exists"]
}
}
```
## Acompanhando o resultado
A inclusão retorna um `request-id`:
```json theme={null}
{ "request-id": "aaa11111-e89b-12d3-a456-426614174006" }
```
Consulte o status com `GET /v1/request/{request-id}`, que retorna o andamento por CPF e por produto.
## Quando a movimentação não é aceita (422)
Se houver violações de validação, a resposta é `422` com o payload devolvido e uma lista de `offenses`
por membro e/ou por documento:
```json theme={null}
{
"result": [
{
"beneficiary-type": "primary",
"name": "João Silva",
"tax-id": "12345678900",
"company-tax-id": "12345678000190",
"offenses": ["invalid-tax-id", "missing-mothers-name"]
}
]
}
```
Consulte a lista completa em [Ofensas](/docs/referencia/error-handling/ofensas).
## Testando em homologação
O parâmetro de query opcional `auto-resolve-enrollments` permite resolver a movimentação
automaticamente: `approve` aprova, `reject` rejeita. **Esta opção existe apenas no ambiente de
Homologação, para testes.**
```http theme={null}
POST /v1/enrollment/inclusion?auto-resolve-enrollments=approve
```