Integração e homologação da API Mensal

01Visão geral

Na API Mensal o parceiro precisa conhecer duas ações: incluir e inativar uma vida. Não existe período trabalhado: a vida entra, fica coberta todos os dias e é cobrada em cada fechamento mensal até ser inativada.

Objeto	O que é	Frequência	Chave
Pessoa	Cadastro do segurado. Criada ou reaproveitada pelo CPF na inclusão.	Uma vez por CPF	`person_id`
Vida	Contrato do segurado dentro do contrato corporativo mensal do parceiro, com cobertura diária automática.	Uma por CPF ativo (renova a cada ano)	`contract.id`
Requisição	Inclusão enfileirada, para envio em volume.	Opcional, a cada inclusão assíncrona	`id` da requisição

Ciclo de vida

POST /insureds ──► active ──POST /insureds/{id}/inactivate──► inactivation_scheduled ──(fim do mês)──► inactive
                     ▲                                               │                                     │
                     └───────────── POST /insureds ──────────────────┴────────── POST /insureds ───────────┘
                               (inactivation_cancelled)                            (reactivated)

Princípio

A inclusão é a única porta de entrada. O parceiro não precisa saber em que estado a vida está: manda o CPF e a API decide se cria, se devolve a vida já ativa, se cancela uma inativação agendada ou se reativa. Não existe rota de reativar nem de cancelar inativação.

02Ambientes e URLs base

Todas as rotas da API Mensal ficam sob o prefixo /api/integrations/monthly. A URL base de cada ambiente é o host somado a esse prefixo:

Ambiente	URL base	Uso
Homologação	`https://intermittent-web-api.hml.iza.com.vc/api/integrations/monthly`	Implementação, carga e conciliação
Produção	`https://intermittent-web-api.iza.com.vc/api/integrations/monthly`	Somente após aprovação na conciliação

Montando um endpoint completo: /insureds em homologação fica

https://intermittent-web-api.hml.iza.com.vc/api/integrations/monthly/insureds

Atenção

As credenciais são por ambiente: a credencial de homologação não funciona em produção e vice-versa. Deixe o host e a credencial em variável de ambiente, nunca fixos no código. Assim a virada para produção é só uma troca de configuração.

Todo tráfego é obrigatoriamente HTTPS.

Primeiro teste de conectividade

Confirme que a credencial responde no ambiente certo antes de escrever qualquer código. 200 valida a credencial e a modalidade mensal; 401 indica problema na credencial; 403 indica que a organização não tem contrato mensal.

$ curl -i "https://intermittent-web-api.hml.iza.com.vc/api/integrations/monthly/insureds?page_size=1" \
    -u "$USER_API_ID:$SECRET_KEY"

03Autenticação

Todos os endpoints exigem autenticação Basic. A IZA entrega, na contratação, um User API ID e uma Secret Key. O token é o Base64 dos dois separados por dois-pontos.

# credenciais recebidas da IZA
USER_API_ID=df888dae-6a05-400b-94c2-6962c09f7842
SECRET_KEY=la903yX1Hw+r27RZL5DfOCIvFq0qKvhq...

# token = base64("USER_API_ID:SECRET_KEY")
$ printf '%s:%s' "$USER_API_ID" "$SECRET_KEY" | base64

# enviado em toda requisição
Authorization: Basic ZGY4ODhkYWUtNmEwNS00MDBiLTk0YzItNjk2MmMwOWY3ODQyOmxhOTAz...
Content-Type: application/json

A credencial resolve sozinha a organização e o contrato corporativo do parceiro: não existe parâmetro de organização nos payloads, e todas as consultas enxergam apenas as vidas desse contrato. Guarde a Secret Key em cofre de senhas ou storage criptografado.

Duas barreiras

Status	Quando
401	Credencial ausente, inválida ou de outro ambiente.
403	A credencial é válida, mas a organização não tem contrato corporativo mensal. Uma credencial de intermitente, por exemplo, não usa esta API.

// 403
{ "errors": { "detail": "credential modality not allowed: this API is only available for monthly contracts" } }

04Endpoints

Caminhos relativos à URL base do ambiente. Todos exigem o header Authorization. O {id} das rotas de vida é sempre o contract.id devolvido na inclusão, não o person_id.

Inclusão

POST/insuredsIncluir vida (síncrono)

Cria a pessoa ou reaproveita a de mesmo CPF. Nome e e-mail são atualizados; o telefone só é gravado se a pessoa ainda não tiver um.

{
  "name": "Maria da Silva",        // obrigatório — até 300 caracteres
  "cpf": "529.982.247-25",         // obrigatório — com ou sem pontuação
  "birth_date": "1990-05-20",      // obrigatório — idade entre 14 e 80 anos
  "email": "maria@email.com",      // opcional
  "phone": "11987654321"           // opcional — celular com DDD, aceita o 55
}

O campo result diz o que aconteceu com a vida:

Situação da vida	`result`	Status
Sem contrato vigente: cria contrato e coberturas, vigência a partir de hoje	`created`	201
Já ativa: devolve o contrato existente	`already_active`	200
Inativação agendada: cancela o agendamento e mantém a ativação original	`inactivation_cancelled`	200
Inativa: reativa	`reactivated`	200

// 201 Created — guarde o contract.id, é ele que consulta e inativa a vida
{
  "result": "created",
  "person_id": "0b7c2d4e-8f1a-4c3b-9d2e-5f6a7b8c9d0e",
  "contract": {
    "id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "proposal_number": 123456,
    "status": "opened",
    "date_begin": "2026-10-09",
    "date_end": "2027-10-09"
  },
  "hpc": {
    "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "active": true,
    "fulldiaries": true,
    "activated_on": "2026-10-09T13:00:00",
    "inactivated_on": null,
    "scheduling_date_deactive": null
  }
}

Erro	Status
Campo obrigatório ausente ou malformado	400
CPF inválido	422
Idade fora da faixa de 14 a 80 anos	422
E-mail ou telefone inválido	422

// formato de 400 e 422 — a chave de errors é o campo com problema
{ "status": "failure", "errors": { "cpf": ["is invalid"] } }

Chamadas simultâneas com o mesmo CPF geram um único contrato. Um retry nunca duplica a vida.

POST/insureds/requestsIncluir vida (assíncrono)

Mesmo body e mesmas regras da inclusão síncrona. O payload é validado na hora e a inclusão roda em fila. Payload válido devolve 202 com status: "pending"; payload inválido devolve 400 ou 422 e nada é enfileirado.

Idempotência: header opcional x-idempotency-key. Repetir a chamada com a mesma chave devolve a mesma requisição. Mesmo sem a chave, cada requisição é processada uma única vez e nunca gera um segundo contrato.

// 202 Accepted
{
  "id": "9b0c3f5e-3d6a-4f1e-9a51-2a7e2b1c4d10",
  "status": "pending",
  "result": null,
  "contract_id": null,
  "errors": null,
  "processed_at": null,
  "inserted_at": "2026-10-16T13:00:00"
}

GET/insureds/requests/{id}Consultar inclusão enfileirada

Devolve o mesmo formato acima.

`status`	Significado
`pending`	Na fila
`processing`	Em processamento
`succeeded`	Final. `result` e `contract_id` preenchidos
`failed`	Final. `errors` traz o motivo

Erro de negócio vira failed sem nova tentativa. Erro inesperado é tentado até 5 vezes; na última, a requisição fica failed com {"detail": "internal error"}. Requisição inexistente ou de outra organização: 404.

Consulta

GET/insuredsListar vidas

Lista as vidas do contrato mensal da credencial, contratos mais recentes primeiro. Um CPF renovado ou reincluído após cancelamento aparece uma vez por contrato.

Filtro	Regra
`cpf`	Com ou sem pontuação.
`life_status`	`active`, `inactivation_scheduled` ou `inactive`.
`page`	Padrão 1, mínimo 1.
`page_size`	Padrão 10, de 1 a 100.

Valor inválido em qualquer filtro devolve 422.

{
  "page_number": 1,
  "page_size": 10,
  "total_pages": 1,
  "total_entries": 1,
  "entries": [ /* mesmo formato do detalhe abaixo */ ]
}

Conciliação

Este é o endpoint da conciliação. É por ele que o parceiro confere, do próprio lado, quantas vidas a IZA tem em cada situação.

GET/insureds/{id}Detalhes da vida

{
  "life_status": "inactivation_scheduled",
  "person": {
    "id": "9c8b7a6d-5e4f-4321-8a9b-0c1d2e3f4a5b",
    "name": "Maria da Silva",
    "cpf": "12345678909",
    "birth_date": "1990-05-20",
    "email": "maria@example.com",
    "phone": "11999998888"
  },
  "contract": {
    "id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "proposal_number": "202610000123",
    "sies_id": 123456,
    "status": "active",
    "date_begin": "2026-10-09",
    "date_end": "2027-10-09"
  },
  "hpc": {
    "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "active": false,
    "fulldiaries": true,
    "activated_on": "2026-10-09T13:00:00",
    "inactivated_on": "2026-11-01T02:59:59",
    "scheduling_date_deactive": "2026-10-31T23:59:59"
  }
}

`life_status`	Significado
`active`	Vida coberta
`inactivation_scheduled`	Ainda coberta; sai em `hpc.scheduling_date_deactive`
`inactive`	Vida não está mais coberta

Use o life_status em vez de interpretar os campos de hpc: em inactivation_scheduled o hpc.active já vem false, mas a vida continua coberta até a data agendada. Vida que não pertence ao contrato mensal da credencial: 404.

GET/insureds/{id}/historyHistórico da vida

Movimentações da vida neste contrato, mais recentes primeiro. Datas em UTC.

{
  "contract_id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "history": [
    { "event": "inactivation_cancelled", "occurred_at": "2026-10-25T12:00:00", "registered_at": "2026-10-25T12:00:00" },
    { "event": "inactivation_scheduled", "occurred_at": "2026-11-01T02:59:59", "registered_at": "2026-10-20T13:12:00" },
    { "event": "activated",              "occurred_at": "2026-10-09T13:00:00", "registered_at": "2026-10-09T13:00:00" }
  ]
}

`event`	Significado
`activated`	Vida incluída
`inactivation_scheduled`	Inativação pedida. `occurred_at` é quando passa a valer; `registered_at` é quando foi pedida
`inactivation_cancelled`	Agendamento cancelado por uma nova inclusão
`reactivated`	Vida inativa incluída de novo

Vidas incluídas antes da existência do histórico, ou fora desta API, podem vir sem movimentações.

Inativação

POST/insureds/{id}/inactivateInativar vida

Sem body. Agenda a saída da vida para o fechamento mensal: último dia do mês corrente, 23:59:59, horário de Brasília. Até lá a vida continua coberta.

// 200 OK
{
  "result": "scheduled",
  "effective_on": "2026-10-31T23:59:59",
  "contract": { "id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "active" },
  "hpc": {
    "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
    "active": false,
    "fulldiaries": true,
    "activated_on": "2026-10-09T13:00:00",
    "inactivated_on": "2026-11-01T02:59:59",
    "scheduling_date_deactive": "2026-10-31T23:59:59"
  }
}

Situação	Retorno	Status
Vida ativa: agenda	`scheduled`	200
Já agendada: devolve a mesma data	`already_scheduled`	200
Vida inativa ou contrato cancelado	—	409
Vida fora do contrato mensal da credencial	—	404

Para desistir da inativação ou reativar a vida, basta incluí-la de novo com POST /insureds.

05Regras do contrato mensal

Regra	Valor	Observação
Idade aceita	14 a 80 anos	Validada na inclusão e na renovação anual
Início da cobertura	Data da inclusão	Não há inclusão retroativa nem futura
Saída da vida	Último dia do mês, 23:59:59 (Brasília)	Não existe inativação imediata
Cobrança	Mês cheio, sem pro rata	Toda vida ativa no fechamento é cobrada
Vigência do contrato da vida	1 ano	Renova automaticamente no vencimento

Por que a saída é no fim do mês

O contrato mensal não é cobrado de forma proporcional. Tirar a vida no meio do mês não reduz a cobrança daquele mês e deixaria a pessoa descoberta pelos dias já pagos. Por isso a inativação é sempre agendada para o fechamento.

Renovação anual

Enquanto a vida estiver ativa, o parceiro não precisa fazer nada: no vencimento, a IZA encerra o contrato da vida e cria um novo, com novo contract.id. A partir daí o mesmo CPF aparece duas vezes na listagem, uma por contrato. A renovação é recusada quando:

o contrato corporativo do parceiro não está ativo;
a pessoa é reprovada na validação, por exemplo idade acima de 80 anos;
a vida está inativa há 90 dias ou mais.

Vida inativa há menos de 90 dias renova, mas o contrato novo já nasce com a vida inativa. Para voltar, basta incluí-la de novo.

Regras que valem para todos

Uma vida por CPF: incluir de novo um CPF ativo devolve o mesmo contrato com already_active.
Telefone nunca é sobrescrito: nome e e-mail são atualizados a cada inclusão; o telefone só é gravado na primeira vez.
Fusos: scheduling_date_deactive e effective_on estão no horário de Brasília; inactivated_on e as datas do histórico estão em UTC. 2026-10-31T23:59:59 em Brasília e 2026-11-01T02:59:59 em UTC são o mesmo instante.
Síncrona ou assíncrona: use a síncrona para inclusões pontuais, quando você precisa do contract.id na resposta. Use a assíncrona para carga em volume ou integração em lote.

Requisito de log

Guarde por no mínimo 30 dias os logs de toda requisição que resultar em erro inesperado, com URL, payload enviado e corpo da resposta. Sem esses três campos, divergências apontadas na conciliação não têm como ser investigadas.

06Homologação

As fases são sequenciais e a homologação é concluída na conciliação. É a partir dela que a credencial de produção é liberada.

Fase 01

Credencial e conectividade

A IZA envia o User API ID e a Secret Key de homologação, já vinculados a um contrato corporativo mensal.

GET /insureds?page_size=1 em homologação retorna 200, e não 401 ou 403.
Host e credencial estão em variável de ambiente, não no código.

Fase 02

Implementação da integração

Desenvolvimento no ambiente de homologação, cobrindo o ciclo completo da vida. A lista abaixo é o que a conciliação vai olhar depois.

Inclusão de vida tratando os quatro result como sucesso.
contract.id persistido junto ao colaborador no seu sistema.
Erros 400 e 422 exibidos ou registrados por campo, a partir de errors.
Desligamento do colaborador disparando POST /insureds/{id}/inactivate, com a data de effective_on registrada.
Readmissão ou desistência tratada com nova inclusão, sem chamar rota de reativação.
Se usar a inclusão assíncrona: x-idempotency-key enviado e consulta da requisição até succeeded ou failed.
Renovação anual absorvida: o contract.id do colaborador é atualizado quando a listagem trouxer um contrato mais recente para o mesmo CPF.
Retentativa com backoff para 5xx e timeouts.
Log de erros com URL, payload e resposta, retido por 30 dias.

Recomendação

Guarde o contract.id como chave de negócio no seu lado: é ele que permite consultar, inativar e explicar qualquer divergência depois.

Fase 03

Carga da base e movimentações

Com a integração pronta, carregue em homologação uma amostra representativa da sua base e execute as movimentações do dia a dia: admissões, desligamentos, readmissões e desistências de desligamento.

Carga inicial com volume representativo, não apenas alguns casos felizes.
Ao menos um caso de cada result da inclusão: created, already_active, inactivation_cancelled e reactivated.
Ao menos uma inativação agendada e uma repetida (already_scheduled).
Início e fim da carga anotados e informados à IZA, com o fuso.
Seus próprios contadores ligados: inclusões por result, inativações agendadas e erros.

Fase 04

Conciliação de vidas

Encerrada a carga, comparamos os números: você extrai os totais do seu sistema e a IZA levanta os mesmos totais pela credencial usada no teste.

Métrica	Lado do parceiro	Lado da IZA
Vidas ativas	Colaboradores ativos enviados com sucesso	Vidas com `life_status = active`
Inativações agendadas	Chamadas de inativação com 200 ainda dentro do mês	Vidas com `life_status = inactivation_scheduled`
Vidas inativas	Desligamentos com fechamento já passado	Vidas com `life_status = inactive`
Inclusões novas	Inclusões com `result = created`	Contratos de vida criados na janela

Você pode adiantar a conferência sem esperar a IZA, lendo o total_entries de cada situação:

GET /insureds?life_status=active&page_size=1
GET /insureds?life_status=inactivation_scheduled&page_size=1
GET /insureds?life_status=inactive&page_size=1

Para conferir CPF a CPF, pagine a listagem completa com page_size=100 e compare com a sua base.

Se os números não fecharem, não é reprovação: com os logs dos erros em mãos identificamos a causa juntos, você faz o ajuste e repete a carga.

Depois da aprovação

Fechada a conciliação, a IZA emite a credencial de produção.

07Entrada em produção

Aprovada a conciliação, a IZA emite a credencial de produção.

Novo User API ID e Secret Key de produção recebidos e guardados em cofre.
URL base trocada para o host de produção, conforme Ambientes.
GET /insureds?page_size=1 em produção retorna 200.
Carga inicial da base de produção feita, de preferência pela inclusão assíncrona.
Primeira vida real conferida via GET /insureds/{id}.
Monitoramento e alerta de erro ligados sobre as chamadas à IZA.
Retenção de logs de 30 dias ativa em produção.

Primeiros fechamentos

Nos dois primeiros fechamentos mensais, compare o total de vidas ativas da listagem com a sua base de colaboradores ativos antes do último dia do mês. É o indicador que denuncia mais cedo uma inclusão ou um desligamento que não chegou à IZA.

08Erros comuns e como tratar

Status	Causa	Tratamento
401	Credencial inválida ou de outro ambiente	Conferir o Base64 de `id:secret` e o host do ambiente. Não repetir a chamada.
403	`credential modality not allowed`	A organização não tem contrato mensal. Acionar a IZA; não é problema de código.
400	Campo obrigatório ausente ou malformado	Conferir `name`, `cpf` e `birth_date` (formato `AAAA-MM-DD`).
422	CPF, idade, e-mail ou telefone inválido	Ler o campo dentro de `errors` e corrigir o cadastro. Não repetir sem ajuste.
422	Filtro inválido na listagem	`life_status` fora da lista ou `page_size` acima de 100.
404	Vida ou requisição não encontrada	Conferir se o `{id}` é o `contract.id`, e não o `person_id`, e se foi criado com a mesma credencial.
409	Inativar vida já inativa ou contrato cancelado	Nada a fazer. Para reativar, incluir de novo.
200	`already_active` ou `already_scheduled`	Sucesso. Seguir o fluxo.
5xx	Indisponibilidade momentânea	Retentar com backoff. A inclusão não duplica vidas.