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.

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.

Os corpos de escrita (inclusão, alteração, exclusão) aceitam também login/senha (opcionais): a credencial do Portal Empresa da empresa cuja vida está sendo movimentada. Quando informados e não-vazios, o valor é repassado à operadora sem alteração e, se preenchido, nunca é ecoado na resposta (mascarado ***; vazio continua vazio).

Em homologação, login e senha são opcionais. Omitidos, a operadora autentica com um usuário fixo do ambiente. Preenchidos, valem só se forem esse usuário: qualquer outra credencial, inclusive uma válida de produção, é recusada com "Parametros obrigatórios de requisição indefinidos ou não enviados", depois de cerca de 17 segundos. Campo só com espaços ("login": " ") conta como ausente e cai no usuário fixo do ambiente; já uma credencial preenchida vai exatamente como enviada, sem aparar espaços.

Em produção eles serão obrigatórios. Lá não existe usuário fixo de ambiente, então cada movimentação precisa da credencial do Portal Empresa da empresa daquela vida. Vale planejar o armazenamento dessas credenciais desde já, porque sem elas nenhuma escrita conclui.

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"), que culpa a matrícula sem razão: 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});
• 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).