Construa integrações
com confiança e velocidade

API **RESTful** do Orquestrador de Benefícios da Izii — o *Hub de Integração (Facade/Adapter)* que abstrai a comunicação com as operadoras de saúde e odontológicas (Bradesco, SulAmérica, Unimed, Amil, etc.). Esta especificação é a versão **100% REST** do contrato descrito no *Manual de Orientação Técnica — API Orquestrador*. Em vez de um único endpoint `POST` com um campo `movimento` (I/A/E/C), cada intenção de movimentação cadastral é expressa pelo **verbo HTTP** e por um **recurso** próprio: | Movimento (legado) | Verbo REST | Recurso | |---------------------------|------------|-------------------------------------------| | `I` Inclusão | `POST` | `/v1/beneficiarios` | | `A` Alteração | `PATCH` | `/v1/beneficiarios/{id}` | | `E` Exclusão | `DELETE` | `/v1/beneficiarios/{id}` | | `C` Consulta (cadastro) | `GET` | `/v1/beneficiarios` · `/v1/beneficiarios/{id}` | | Buscar movimentações | `GET` | `/v1/movimentacoes` · `/v1/movimentacoes/{id}` | > Troca de Plano (`T`) e Reativação (`R`) ainda não são suportadas pelo > Orquestrador (retornam "Movimento inválido"); serão expostas quando o > backend habilitar. ## Autenticação Envie `client_id` e `client_secret` em `POST /v1/auth/token` para obter um **token JWT** (`access_token`, validade de 2 horas). O token deve ser enviado no header `Authorization: Bearer <token>` em todos os endpoints de negócio (sem token o gateway responde **401**). ## Roteamento por operadora - A **operadora de destino** é informada no header `X-Cnpj-Provedor` (CNPJ da operadora — ex. SulAmérica `01685053000156`), obrigatório em todos os endpoints de dados. - O inquilino (tenant) é resolvido do lado do servidor a partir da credencial; não é enviado pelo consumidor. ## Padronização de respostas Operações de escrita retornam um `MovimentacaoResultado` com `protocolo`, `status` e listas de `validacoes`/`criticas` (validações de negócio da operadora). Erros seguem o schema `Erro`. As respostas de escrita chegam com **HTTP 200** e o desfecho definitivo da movimentação é assíncrono: guarde o `protocolo` e acompanhe em `GET /v1/movimentacoes/{protocolo}`. ## Críticas conhecidas (observadas em homologação SulAmérica) | Código | Mensagem/Significado | Ação | |--------|----------------------|------| | A041 | CPF já cadastrado | Use outro CPF ou trate como duplicidade | | A1034 | Nome com caracteres inválidos | Envie `nome` sem acentos | | A1079 | Nome abreviado divergente | `nomeAbreviado` deve ser igual a `nome` | | A02003 | Matrícula preenchimento obrigatório (alteração) | Em validação com a Izii; PATCH indisponível | | M21001 | Data de exclusão inválida | Use a data de corte permitida (a crítica lista as datas) | | 212/79/329/334 | Movimentação encaminhada para análise interna | Não bloqueante; aguarde o processamento | ## Status por endpoint (ambiente dev, verificado em 16/07/2026) Funcionais: auth, inclusão, exclusão, consulta por protocolo, webhook. Indisponíveis/instáveis no upstream: alteração (A02003), busca de beneficiários (erro 400 interno), locais (502). Não homologados: faturas (dependem de Protheus). Detalhe em cada endpoint.