Referência REST - Orquestrador de Benefícios

Visão geral

Esta é a API recomendada para integrar com o Orquestrador de Benefícios da Izii. Cada movimentação cadastral é expressa pelo verbo HTTP e por um recurso próprio, em vez de um único POST com um campo movimento.

Todos os exemplos deste guia foram executados em homologação (SulAmérica), com protocolos reais gerados.

A especificação OpenAPI completa está no portal em /izzi-rest, com playground Try It Out.

Ambiente

1. Autenticação

Troque client_id/client_secret por um token JWT (validade 2 horas):

TOK=$(curl -s -X POST https://apigw-dev.izii.app.br/v1/auth/token \  -H 'content-type: application/json' \  -d '{"client_id":"<SEU_CLIENT_ID>","client_secret":"<SEU_CLIENT_SECRET>"}' \  | python3 -c 'import sys,json;print(json.load(sys.stdin)["access_token"])')

A resposta traz access_token, token_type e expires_in (7200s). Envie o token em todas as demais chamadas:

Authorization: Bearer <access_token>X-Cnpj-Provedor: 01685053000156

Sem token, o gateway responde 401 na borda. Token vencido (>2h) também.

Em produção, toda chamada leva também a credencial do Portal Empresa nos headers X-Portal-Login e X-Portal-Senha (seção 2).

No console do portal, cole somente o token (sem escrever Bearer na frente; o prefixo é adicionado automaticamente).

2. Inclusão de beneficiário

POST /v1/beneficiarios → HTTP 200 com protocolo e beneficiario.matriculaProvedor. Guarde os dois: o protocolo rastreia a movimentação e a matriculaProvedor é exigida na exclusão. São identificadores diferentes e não são intercambiáveis (seção 3).

Se a matriculaProvedor não tiver sido guardada, dá para recuperá-la: nas consultas ela volta nula e o mesmo valor aparece em beneficiario.matriculaFamilia, tanto na busca por CPF (GET /v1/beneficiarios/{cpf}) quanto na consulta por protocolo.

Com mais de um vínculo, cada um tem a sua matriculaFamilia. beneficiario traz a do vínculo mais recente, que é o ativo sempre que existe um (o ativo vem com dataExclusao igual a 9999-12-31). Os outros continuam em vinculos, na ordem em que a operadora devolveu, caso precise de um deles.

A operadora autentica cada requisição, consulta ou escrita, com a credencial do Portal Empresa da empresa cuja vida está sendo movimentada ou consultada. Ela vai nos headers X-Portal-Login e X-Portal-Senha, em qualquer rota:

X-Portal-Login: <login do Portal Empresa>X-Portal-Senha: <senha do Portal Empresa>

Nas escritas (inclusão, alteração, exclusão) os campos login/senha do corpo também são aceitos e, quando os dois canais chegam juntos, o corpo vence. Envie o par inteiro no mesmo lugar: login num canal e senha no outro não se combinam. A credencial nunca é ecoada na resposta (mascarada ***).

Em homologação a credencial é opcional. Omitida, a operadora autentica com um usuário fixo do ambiente. Preenchida, vale só se for esse usuário: qualquer outra, inclusive uma válida de produção, é recusada pela operadora. Campo só com espaços conta como ausente; já uma credencial preenchida vai exatamente como enviada, sem aparar espaços.

Em produção ela é necessária em toda requisição. Lá não existe usuário fixo de ambiente: sem a credencial a operadora recusa a autenticação e a requisição não retorna dados.

Isso é independente do client_id/client_secret da seção 1, que é fixo por ambiente e não muda por empresa. Detalhes do formato na spec em /izzi-rest.

Regras medidas em homologação (a operadora critica se violar):

• nome e nomeAbreviado sem acentos: acento gera A1034 e A1046, junto com A1080, que já sugere um nome abreviado aceito;
• matriculaFuncionario não pode repetir uma já usada no contrato → A015;
• CPF já cadastrado → A041.

Inclusão em lote. O corpo aceita um array de vidas, além do objeto único. As vidas seguem juntas numa só chamada ao Orquestrador, sem desmembramento:

curl -s -X POST https://apigw-dev.izii.app.br/v1/beneficiarios \  -H "authorization: Bearer $TOK" \  -H "X-Cnpj-Provedor: 01685053000156" \  -H 'content-type: application/json' \  -d '[ {"nome":"VIDA UM", "...": "..."}, {"nome":"VIDA DOIS", "...": "..."} ]'

A resposta traz resultados, um item por vida enviada, cada um com o seu codigoMovimentacao (protocolo). O protocolo e o beneficiario do topo seguem apontando para a primeira vida, por compatibilidade com o envio avulso: em lote, use a lista. Crítica de uma vida específica chega em validacoes, identificada por nomeBeneficiario e matriculaFuncionario.

O lote típico é uma família (titular e dependentes), que é o uso previsto pela operadora. O corpo tem teto de 1 MB (cerca de 2.500 vidas); acima disso a resposta é 413 com o schema Erro. Abaixo desse teto, quem limita é o Orquestrador e a operadora: como cada vida tem custo de processamento, lotes grandes podem estourar o tempo da chamada e devolver 502 com repetir: false, caso em que não reenvie, consulte as vidas por CPF antes.

nome e nomeAbreviado podem ser diferentes, e dadosBancarios não é obrigatório: os dois casos foram testados e a inclusão passou sem críticas.

Dependente: a matrícula é a do titular. Em matriculaFuncionario vai a matrícula do titular, não uma do dependente: é ela que liga o dependente à família. O formato não importa, a operadora normaliza: enviamos 7992 e ela gravou 00007992, e 7992, 07992 e 00007992 foram todos aceitos no mesmo titular. grauParentesco, varrido de 0 a 9 para seguro saúde: 1 = cônjuge e 2 = filho(a) são os únicos que entram sozinhos; 3 a 6 (companheiro, pais, agregados, enteados, outros) exigem documento comprobatório e caem em A1032; 7 a 9 não existem para saúde (A1019); e 0 numa matrícula que já tem titular dá A1081. dataAdmissao é obrigatória também no dependente (A034/A035).

O lote é tudo ou nada: com uma vida recusada nenhuma entra, nem as corretas (medido com A005 e A1019 na segunda de três vidas, e confirmado por consulta). A regra é da operadora: o Orquestrador envia as vidas num POST único para o endpoint de inclusões da SulAmérica, que recusa a movimentação inteira apontando só a vida com problema. Nem esta API nem o Orquestrador decidem isso. validacoes diz qual vida caiu e por quê; o reenvio é do lote inteiro.

Grupo familiar: mande todos num array, titular na frente. Não existe campo de dependentes dentro do corpo, cada vida é um registro, mas a inclusão aceita um array. Medido em 05/10/2026: três vidas numa requisição, um item em resultados por vida, mesma matriculaProvedor, sequencial 01/02/10, nenhuma crítica.

Enviando um por vez, o dependente é recusado logo após a inclusão do titular e aceito algum tempo depois, com o payload idêntico. statusMovimentacao: Liberada não basta: em três famílias medidas a sequência foi A015 (0s) → A015 (22s, já Liberada) → A1083 → aceito entre 44s e 72s. Não construa retry em cima desses números: num quarto titular, igualmente liberado e com matriculaFamilia atribuída, a A015 persistiu por mais de dez minutos. Até lá a recusa vem como A1083 ("Titular não encontrado") ou, pior, como A015 ("Código da matrícula ... diferente do código de matrícula do titular"), ainda que a matrícula esteja correta: medimos a mesma requisição recusada com A015 e aceita minutos depois, sem mudar um byte. Se você bateu nessa crítica com a matrícula correta, não procure no payload, mande a família junta. Há exemplos titular e dependente prontos no schema da operação.

Plano é por empresa. produto.codigo precisa ser um plano válido para aquele estipulante; outro plano devolve A7008 ("Plano inválido"), ainda que o código exista.

Payload real executado com sucesso (protocolo 2190831):

curl -s -X POST https://apigw-dev.izii.app.br/v1/beneficiarios \  -H "authorization: Bearer $TOK" \  -H "X-Cnpj-Provedor: 01685053000156" \  -H 'content-type: application/json' \  -d '{"nome":"Teste Beneficiario Um","nomeAbreviado":"Teste Beneficiario Um","cpf":"36442421430","matricula":"7700","matriculaFuncionario":"7700","dataNascimento":"1990-01-01","grauParentesco":"0","estadoCivil":"S","sexo":"M","nomeMae":"Mae Teste","pisPasep":"12056412300","cns":"700000000000000","dataAdesao":"2026-04-19","dataAdmissao":"2026-01-15","dataEvento":"2026-04-19","dataVigencia":"2026-04-19","local":1,"codigoSegurado":"1","certificado":"1","endereco":{"cep":"01310100","logradouro":"Av Paulista","numero":"1000","bairro":"Bela Vista","municipio":"Sao Paulo","uf":"SP"},"contato":{"email":"teste@mds.com","dddCelular":"11","celular":"999999999"},"dadosBancarios":{"banco":"001","agencia":"1234","digitoAgencia":"5","conta":"567890","digitoConta":"1","digito":"1","tipoConta":"1"},"produto":{"contrato":"78043","subContrato":"8UV4F","codigo":"66181"},"apolice":{"cia":"570","numero":"78043"},"tipoProduto":"SAUDE"}'

Resposta real (campos null/vazios omitidos por brevidade - o contrato completo, com validacoes, criticas, requestJson etc., está no schema em /izzi-rest):

{  "status": 200,  "protocolo": "2190831",  "statusMovimentacao": "1",  "beneficiario": {    "codigoMovimentacao": "2190831",    "tipoMovimentacao": "INCLUSAO",    "cpf": "36442421430",    "matriculaProvedor": "484229630",    "sequencial": "01",    "status": "1"  }}

O processamento é assíncrono: statusMovimentacao: "1" significa "em processamento". Acompanhe pelo protocolo (seção 4).

Grau de parentesco

É a origem mais comum de dependente cadastrado errado, então vale a tabela inteira:

Atenção: filho é 3. O 1 é cônjuge, e mandar 1 para um filho cadastra a vida com o vínculo errado, sem crítica nenhuma.

3. Exclusão de beneficiário

DELETE /v1/beneficiarios/{cpf} com corpo JSON. Na rota vai o CPF, não o protocolo. Regras críticas:

• quem identifica a vida é matriculaEmpresa + produto, não o CPF da rota (um CPF divergente não impede a exclusão). O produto.subContrato é a empresa onde a matrícula é procurada, então envie o mesmo produto e o mesmo codigoRDP da inclusão daquela vida;
• matriculaEmpresa é a matriculaProvedor da inclusão, nunca o protocolo. Se não a guardou, ela aparece como beneficiario.matriculaFamilia em duas consultas: por CPF (GET /v1/beneficiarios/{cpf}) ou por protocolo (GET /v1/movimentacoes/{protocolo}). Com mais de um vínculo, a consulta por CPF traz a do mais recente, que é o ativo quando há um; os demais ficam em vinculos;
• só dá para excluir depois que a inclusão foi liberada. O sinal é a carteirinha emitida;
• dataExclusao deve ser uma data de corte permitida. Data inválida retorna M21001 listando as aceitas. A matrícula é resolvida antes da data, então A02011 nunca é problema de data (ver o catálogo na seção 6).

Payload real executado com sucesso (protocolo 2190832):

curl -s -X DELETE https://apigw-dev.izii.app.br/v1/beneficiarios/36442421430 \  -H "authorization: Bearer $TOK" \  -H "X-Cnpj-Provedor: 01685053000156" \  -H 'content-type: application/json' \  -d '{"motivoExclusao":"1","dataExclusao":"2026-07-19","matriculaEmpresa":"484229630","codigoRDP":"01","tipoProduto":"SAUDE","flagContributario":false,"produto":{"contrato":"78043","subContrato":"8UV4F","codigo":"66181"}}'

Resposta real: status: 200, protocolo: "2190832", beneficiario.tipoMovimentacao: "EXCLUSAO".

4. Tracking: consulta por protocolo (caminho oficial)

GET /v1/movimentacoes/{protocolo}:

curl -s https://apigw-dev.izii.app.br/v1/movimentacoes/2190831 \  -H "authorization: Bearer $TOK" \  -H "X-Cnpj-Provedor: 01685053000156"

Resposta real (beneficiário aprovado; campos omitidos por brevidade, exceto matriculaProvedor, mostrado de propósito por vir nulo):

{  "status": 200,  "protocolo": "2190831",  "statusMovimentacao": "Liberada",  "beneficiario": {    "tipoMovimentacao": "INCLUSAO",    "cpf": "36442421430",    "carteirinha": "56788888484229630016",    "matriculaFamilia": "484229630",    "matriculaProvedor": null,    "status": "Liberada",    "nome": "TESTE BENEFICIARIO UM"  }}

Repare no par de matrículas. Na consulta, matriculaProvedor volta nula e o valor está em matriculaFamilia. É esse número (484229630 acima) que a exclusão exige em matriculaEmpresa (seção 3), e é o mesmo que a inclusão devolveu em matriculaProvedor.

Por que por protocolo? É a via recomendada para acompanhar uma movimentação. A busca por CPF localiza apenas quem já consta no cadastro consolidado da operadora, então uma vida ainda em análise volta vazia mesmo com o CPF correto. Para tracking, use o protocolo.

Não encontrado é HTTP 200, não 404. Esta API não devolve 404 em consulta: quando o registro não é localizado, a resposta é 200 com beneficiario: null (e protocolo/statusMovimentacao nulos, criticas: []). Trate ausência lendo o corpo, nunca o status. Vale para a consulta por CPF e para a consulta por protocolo.

statusMovimentacao observados: "1" / "Em Processamento" (aceite), "Aguardando Analise Operação" (análise automática de elegibilidade; pode vir com crítica não bloqueante como a 2401: não é rejeição, não reenvie), "Liberada" e "Liberada com Critica" (aprovada, carteirinha emitida mesmo com crítica presente). Cada item de criticas traz o campo bloqueante (true/false/null), derivado do wrapper de validacoes. O prazo de liberação em homologação varia de minutos a ~2-3 dias.

5. Desfecho da movimentação (assíncrono)

O processamento é assíncrono: a inclusão/exclusão devolve o protocolo na hora com statusMovimentacao: "1" (em processamento). Para obter o desfecho, faça polling por protocolo (seção 4): GET /v1/movimentacoes/{protocolo} até "Liberada" (ou uma crítica bloqueante). Não há webhook da API para o consumidor; o cliente é responsável por acompanhar pelo protocolo.

6. Catálogo de críticas conhecidas

7. Fluxos em homologação

Valide em homologação antes de usar em produção: alteração (PATCH), busca de beneficiários, locais e faturas.

Checklist de integração

1. Obter token (/v1/auth/token), renovar antes de expirar (2h).
2. Incluir beneficiário com o payload completo (seção 2); guardar protocolo e matriculaProvedor (são coisas distintas: o protocolo serve para tracking, a matrícula para a exclusão).
3. Acompanhar por GET /v1/movimentacoes/{protocolo} até Liberada ou Liberada com Critica (carteirinha emitida), ou crítica bloqueante (criticas[].bloqueante: true: corrigir e reenviar). Sugestão de cadência: a cada 30-60 min; não reenvie movimentação em análise.
4. Excluir só depois da liberação: CPF na rota, matriculaEmpresa = a matrícula (nunca o protocolo) e data de corte permitida (seção 3).
5. Tratar críticas pelo catálogo (seção 6).