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 com sucesso em homologação (SulAmérica) em 16/07/2026, com protocolos reais gerados. O que ainda não foi homologado está explicitamente marcado.

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

Ambiente

Status dos endpoints (verificado em 16/07/2026)

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.

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

• dadosBancarios é obrigatório na prática (sem ele o Orquestrador retorna erro 500);
• nomeAbreviado deve ser igual a nome (crítica A1079);
• nome sem acentos (crítica A1034);
• CPF já cadastrado → crítica A041.

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 Marcos Fluxo","nomeAbreviado":"Teste Marcos Fluxo","cpf":"36442421430","matricula":"7700","matriculaFuncionario":"7700","dataNascimento":"1990-01-01","grauParentesco":"0","estadoCivil":"S","sexo":"M","nomeMae":"Mae Teste","pis":"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:

{  "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).

3. Exclusão de beneficiário

DELETE /v1/beneficiarios/{cpf} com corpo JSON. Duas regras críticas:

• matriculaEmpresa = a matriculaProvedor retornada na inclusão;
• dataExclusao deve ser uma data de corte permitida pela operadora. Data inválida retorna a crítica M21001 listando as datas aceitas.

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):

{  "status": 200,  "protocolo": "2190831",  "statusMovimentacao": "Liberada",  "beneficiario": {    "tipoMovimentacao": "INCLUSAO",    "cpf": "36442421430",    "carteirinha": "56788888484229630016",    "status": "Liberada",    "nome": "TESTE MARCOS FLUXO"  }}

Por que por protocolo? Verificado em 16/07/2026 (inclusive direto no backend): o Orquestrador só aplica o filtro por código da movimentação. O filtro ?cpf= de GET /v1/movimentacoes é ignorado e retorna um registro default antigo. Não use a listagem para tracking.

statusMovimentacao observados: "1" (em processamento) e "Liberada" (aprovada, carteirinha emitida). Movimentações podem passar por "análise interna" na operadora (críticas não bloqueantes 212, 79, 329, 334).

5. Webhook (callback da operadora)

POST /v1/webhooks/operadoras/{operadora} é o endpoint público que a operadora chama. O receptor apenas confirma o recebimento ({"received": true}) e registra o evento. Ele não propaga status. Para o desfecho da movimentação, use a consulta por protocolo (seção 4).

6. Catálogo de críticas conhecidas

7. Não homologados (não desenvolva sem validar antes)

• Alteração (PATCH): crítica A02003 em toda tentativa, mesmo com beneficiário ativo. Campo de matrícula em validação com a Izii.
• Busca de beneficiários (GET /v1/beneficiarios): erro 400 persistente no backend.
• Locais (GET /v1/locais): 502 persistente no backend.
• Faturas (POST /v1/faturas/*): dependem de integração Protheus do lado da Izii; nunca testadas.

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.
3. Acompanhar por GET /v1/movimentacoes/{protocolo} até Liberada (ou crítica bloqueante).
4. Excluir com matriculaEmpresa + data de corte (seção 3).
5. Tratar críticas pelo catálogo (seção 6).