Documentação da API Axenya

Como funciona

A axenya-public-api é uma camada pública de ingestão que fica na frente dos backends internos da Axenya (HR Portal e Landing Zone). Toda chamada autenticada por API key passa por cinco etapas no servidor:

                       TLS + API Key
  Sua empresa  ───────────────────────────►  axenya-public-api
   (sistema de RH)                              │ 1. autentica a API key (hash em repouso)
                                                │ 2. resolve tenant + scopes da key
                                                │ 3. valida o JSON contra o schema gerado
                                                │ 4. cria uma "submission" (recibo) — async
                                                │ 5. chama o backend interno injetando
                                                ▼    o tenant resolvido
                                ┌───────────────┼───────────────────────────┐
                                ▼               │                            ▼
                         hr-portal-api  ◄───────┘                   landing-zone backend
                    (movimentação de vidas)                     (file-types / signed URL GCS)

Grupos e unidades — visão consolidada

Um grupo reúne várias unidades (tenants) sob a mesma gestão de TI. Além da key por unidade, a Axenya emite keys de grupo, que dão visão consolidada sobre todas as unidades do grupo — sem precisar orquestrar N keys manualmente.

Primeiros passos

Em menos de cinco minutos você faz a primeira consulta e a primeira movimentação. Você só precisa de uma API key do seu tenant (fornecida pela Axenya).

1. Configure o ambiente Exporte a URL base e sua API key. A empresa é resolvida pela key — não precisa de mais nada.
   bash

   export AXENYA_API="https://api.axenya.com/v1"
   export AXENYA_KEY="axk_live_3f8a...e21"   # resolve sua empresa no servidor

2. Encontre uma vida pelo CPF Toda operação de RH normalmente começa achando a vida. O CPF (document) é a chave natural de matching.
   bash

   curl -sS "$AXENYA_API/beneficiaries?document=39053344705" \
     -H "Authorization: Bearer $AXENYA_KEY"

   json · 200

   {
     "data": [
       {
         "id": "ben_01HZX...",
         "name": "Maria Silva",
         "document": "390.533.447-05",
         "subscriberType": "HOLDER",
         "status": "ACTIVE"
       }
     ],
     "meta": { "totalItems": 1 }
   }

3. Envie sua primeira movimentação Escritas exigem o header Idempotency-Key e respondem 202 com um recibo. Acompanhe o processamento depois.
   bash

   curl -sS -X POST "$AXENYA_API/movements" \
     -H "Authorization: Bearer $AXENYA_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: adm-2026-0001-maria" \
     -d '{
       "movementType": "INSERT",
       "effectiveDate": "2026-07-01",
       "policyId": "pol_saude_123",
       "planId": "plan_premium",
       "beneficiary": {
         "subscriberType": "HOLDER",
         "name": "Maria Silva",
         "document": "39053344705",
         "birthDate": "1990-04-12",
         "gender": "FEMALE"
       }
     }'

4. Acompanhe o recibo Use o submissionId retornado para checar o status — ou receba um webhook quando processar.
   bash

   curl -sS "$AXENYA_API/movements/mov_01J2K..." \
     -H "Authorization: Bearer $AXENYA_KEY"

Autenticação

A autenticação é máquina-a-máquina (M2M) por API keys por tenant. Cada chamada leva o header Authorization: Bearer <sua-key>.

Formato da key

As keys têm prefixo de ambiente e são exibidas uma única vez no momento da criação. Guarde-as em um cofre de segredos (Secret Manager, Vault) — a Axenya armazena apenas o hash.

Uma key pode ser de unidade (um único tenant) ou de grupo (várias unidades do grupo, com visão consolidada). O tipo é definido na emissão da key, não no payload.

Scopes

Cada key carrega um conjunto de scopes. Use o princípio do menor privilégio.

Boas práticas de segurança

• Rotação sem downtime: até 2 keys ativas por tenant. Crie a nova, migre, revogue a antiga.
• Revogação imediata e expiresAt por key; lastUsedAt para auditoria.
• TLS 1.2+ obrigatório; IP allowlist opcional por key.
• Rate limit e quota aplicados por key.
• Nunca registre a key em logs, URLs ou repositórios.

Modelo de operação de RH

Não existe um endpoint por tarefa de RH. Toda a operação se reduz a 4 primitivas de movimentação, combinadas com consultas (GET) para encontrar a vida e o plano certos.

A chave de matching é sempre CPF (document) + apólice — sua empresa não conhece o identificador interno (bid) da Axenya, e não precisa. Os campos válidos de cada primitiva vêm do schema gerado daquele movementType.

Os 7 cenários de RH

Estes são os fluxos do dia a dia de um time de benefícios. Cada um é uma combinação das 4 primitivas com as consultas necessárias.

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: adm-2026-0001-maria" \
  -d '{
    "movementType": "INSERT",
    "effectiveDate": "2026-07-01",
    "policyId": "pol_saude_123",
    "planId": "plan_premium",
    "coparticipation": { "mode": "PARCIAL" },
    "beneficiary": {
      "subscriberType": "HOLDER",
      "name": "Maria Silva", "document": "39053344705",
      "enrollmentNumber": "0012345", "birthDate": "1990-04-12",
      "admissionDate": "2026-07-01", "gender": "FEMALE",
      "maritalStatus": "SOLTEIRO", "phone": "+5511999998888"
    }
  }'

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dep-2026-0001-joao" \
  -d '{
    "movementType": "INSERT",
    "effectiveDate": "2026-07-01",
    "policyId": "pol_saude_123",
    "beneficiary": {
      "subscriberType": "DEPENDENT",
      "holder": { "document": "39053344705" },
      "dependencyRelation": "CONJUGE",
      "name": "João Silva", "document": "12345678909",
      "birthDate": "1989-02-03", "gender": "MALE"
    }
  }'

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: end-2026-0001-maria" \
  -d '{
    "movementType": "REGISTRATION_UPDATE",
    "effectiveDate": "2026-07-01",
    "beneficiary": { "document": "39053344705" },
    "registration": {
      "address": {
        "zipCode": "01310100", "street": "Av. Paulista", "number": "1000",
        "complement": "Conj. 51", "neighborhood": "Bela Vista",
        "city": "São Paulo", "state": "SP"
      }
    }
  }'

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cc-2026-0001-maria" \
  -d '{
    "movementType": "REGISTRATION_UPDATE",
    "effectiveDate": "2026-07-01",
    "beneficiary": { "document": "39053344705" },
    "registration": { "costCenter": "CC-OPS-2026" }
  }'

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: plan-2026-0001-maria" \
  -d '{
    "movementType": "UPDATE",
    "effectiveDate": "2026-08-01",
    "policyId": "pol_saude_123",
    "beneficiary": { "document": "39053344705" },
    "fromPlanId": "plan_basic", "toPlanId": "plan_premium"
  }'

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: del-dep-2026-0001-joao" \
  -d '{
    "movementType": "DELETE",
    "effectiveDate": "2026-07-31",
    "beneficiary": { "document": "12345678909" },
    "reason": "EXCLUSAO_DEPENDENTE"
  }'

curl -sS -X POST "$AXENYA_API/movements" \
  -H "Authorization: Bearer $AXENYA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deslig-2026-0001-maria" \
  -d '{
    "movementType": "DELETE",
    "effectiveDate": "2026-07-31",
    "beneficiary": { "document": "39053344705" },
    "reason": "DESLIGAMENTO",
    "deactivationDelayDays": 30,
    "cascadeDependents": true
  }'

Sync de folha de pagamento (reconciliação)

Tudo que vimos até aqui é imperativo: você diz a movimentação ("exclua o CPF X"). A folha de pagamento é o oposto — é declarativa. Você envia o retrato de quem deve estar ativo e a Axenya calcula as movimentações pela diferença contra o estado atual. É o mesmo padrão de reconciliação por estado desejado do Kubernetes: você não manda o delta, manda o alvo, e o motor deriva o delta.

Folha (estado desejado)  ─┐
                          ├─► motor de diff ─► plano de reconciliação ─► (aprova) ─► /movements
Estado atual na Axenya   ─┘   (desired vs current)   (preview das mov.)              (pipeline existente)

O motor de diff → as 4 primitivas

A diferença entre folha e estado atual (chave = CPF) gera exatamente as primitivas que já existem:

A armadilha crítica: exclusão por omissão

O quadrante perigoso é "ausente na folha → DELETE". Uma folha truncada, um arquivo parcial ou um erro de export poderiam desligar gente em massa. Sem proteção, isso é um incidente. Por isso os controles abaixo são obrigatórios.

Quais dos 7 cenários derivam da folha?

Honestidade importante: depende das colunas que a folha carrega.

Em resumo: a folha resolve muito bem admissão, desligamento, centro de custo e cadastro de titulares; plano e dependentes dependem do conteúdo do arquivo.

Fluxo: preview → apply

Dois passos, pela segurança. Primeiro você envia a folha e revisa o plano derivado; só então aplica.

1. Abra o sync e envie a folha Mesmo padrão de signed URL — o arquivo não passa pela API.
   bash

   curl -sS -X POST "$AXENYA_API/payroll-syncs:initiate" \
     -H "Authorization: Bearer $AXENYA_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: folha-2026-07" \
     -d '{
       "referenceMonth": "2026-07",
       "effectiveDate": "2026-07-01",
       "mode": "full",
       "scope": "HOLDERS"
     }'
   # -> { "syncId": "pyr_01J...", "uploadUrl": "https://storage.googleapis.com/...",
   #      "requiredHeaders": { ... } }

   Depois, faça o PUT do arquivo na uploadUrl (como em qualquer fluxo de arquivo).

2. Consulte o plano derivado (dry-run) Quando status = planned, o sync devolve o plano completo com summary e guardrails.
   bash

   curl -sS "$AXENYA_API/payroll-syncs/pyr_01J..." \
     -H "Authorization: Bearer $AXENYA_KEY"

   json · 200

   {
     "syncId": "pyr_01J...",
     "status": "planned",
     "mode": "full", "scope": "HOLDERS",
     "summary": {
       "inserts": 12, "deletes": 3, "planChanges": 5,
       "registrationUpdates": 8, "noops": 940, "unmatched": 2
     },
     "guardrails": { "deleteRatio": 0.003, "blocked": false },
     "movements": [
       { "movementType": "INSERT", "beneficiary": { "document": "111...", "name": "..." }, "source": { "row": 14 } },
       { "movementType": "DELETE", "beneficiary": { "document": "222...", "name": "..." }, "reason": "ABSENT_IN_PAYROLL" },
       { "movementType": "UPDATE", "beneficiary": { "document": "333..." }, "fromPlanId": "basic", "toPlanId": "premium" }
     ],
     "unmatched": [ { "row": 87, "document": "999...", "issue": "CPF inválido" } ]
   }

3. Aplique o plano Depois de revisar (ou automaticamente se os guardrails estiverem ok). Cada movimentação vira um submission rastreável.
   bash

   curl -sS -X POST "$AXENYA_API/payroll-syncs/pyr_01J...:apply" \
     -H "Authorization: Bearer $AXENYA_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "confirm": true, "acknowledgeDeletes": 3 }'
   # -> status: applying -> completed

   O campo acknowledgeDeletes precisa bater com o número de exclusões do plano — uma trava extra contra desligamento acidental em massa.

Endpoints

Como a folha é mapeada

Aqui aparece o único ponto que exige mais do que o template canônico: toda folha/ERP exporta diferente. Duas saídas:

Classificações que exigem cuidado

• CPF novo pode ser re-admissão de alguém INACTIVE → reativação, não inclusão nova (checar status atual).
• CPF ausente pode ser afastamento, não desligamento → por isso mode + limiares.
• Mesmo CPF com nome diferente → correção cadastral, não pessoa nova.

Recibos & status

Como a ingestão é assíncrona, toda escrita responde 202 Accepted com um objeto submission — o recibo. Guarde o id para acompanhar.

{
  "submission": {
    "id": "mov_01J2K...",
    "movementType": "INSERT",
    "schemaVersion": "2026-06-01",
    "status": "received",
    "createdAt": "2026-06-04T13:20:00Z"
  }
}

Ciclo de vida do status

Consultar o status

curl -sS "$AXENYA_API/movements/mov_01J2K..." \
  -H "Authorization: Bearer $AXENYA_KEY"

{
  "id": "mov_01J2K...",
  "status": "rejected",
  "schemaVersion": "2026-06-01",
  "result": {
    "accepted": 0,
    "rejected": 1,
    "errors": [
      {
        "row": 1,
        "field": "beneficiary.document",
        "code": "BENEFICIARY_NOT_FOUND",
        "message": "Nenhuma vida ativa com este CPF na apólice."
      }
    ]
  }
}

Webhooks

Em vez de fazer polling no status, registre um endpoint para receber eventos quando uma movimentação for processada. Os webhooks são assinados via HMAC e têm retry com backoff.

Verificando a assinatura

Cada entrega traz um header com a assinatura HMAC-SHA256 do corpo. Recompute com seu segredo de webhook e compare em tempo constante antes de confiar no payload.

# pseudo-verificação
expected=$(printf '%s' "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary \
  | base64)
# compare 'expected' com o header X-Axenya-Signature

Convenções

Regras transversais que valem para toda a API.

Idempotência

Reenviar uma requisição com a mesma Idempotency-Key retorna o mesmo recibo, sem duplicar a movimentação. Use uma chave estável e única por operação (ex.: adm-2026-0001-maria). Isso torna seus retries seguros.

Consultas (GET)

Endpoints de leitura para encontrar vidas, planos e templates antes de movimentar. Requerem o scope submissions:read.

Movimentações (HR Portal)

Escrita de movimentações de beneficiários. Requer o scope movements:write (exceto a consulta de status).

Tipos de movimentação

Alternativa por arquivo

Para volumes grandes, use o fluxo de upload nativo do backend. O template canônico vem do mesmo schema (veja Templates).

1. Peça a URL de upload
   bash

   curl -sS -X POST "$AXENYA_API/movements:initiate" \
     -H "Authorization: Bearer $AXENYA_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: file-2026-0001" \
     -d '{
       "movementType": "INSERT",
       "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
     }'

2. Envie o arquivo direto ao GCS (não passa pela API)
   bash

   curl -sS -X PUT "<uploadUrl>" \
     -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
     -H "x-goog-meta-movementtype: INSERT" \
     --upload-file inclusoes-julho.xlsx

3. Acompanhe com GET /movements/{submissionId}.

Arquivos (Landing Zone)

Submissão de arquivos de compliance por fileType + período. Requer files:write.

O fluxo é o mesmo padrão de signed URL: você pede a URL, envia o arquivo direto ao storage e confirma. A validação (incluindo antivírus) acontece de forma assíncrona — acompanhe pelo status ou pelo webhook file.validated.

Templates & schema

O cliente B2B nunca mantém um template à mão. O hr-portal-api expõe a definição estruturada de cada movementType (colunas, tipos, obrigatórios, enums, versão); a camada pública consome e gera o JSON Schema canônico. Coluna nova no backend aparece sozinha no schema — sem drift, sem variante por operadora.

hr-portal-api                       axenya-public-api                       cliente
─────────────                       ─────────────────                       ───────
definição estruturada ─(fetch+cache)─► gera JSON Schema ─(serve)─► GET /movement-templates/{type}
do template (por tipo)                 canônico + versão
                                            │
POST /movements (JSON) ─────────────────────┤ valida o JSON contra o schema
                                            │ transforma JSON → colunas/linhas
       upload existente ◄────────────────────┤ alimenta o fluxo de upload
       valida (autoritativo)                 │
       failed-rows (coluna/linha) ──────────►│ reverte p/ o caminho JSON e devolve no recibo

Uma definição, três usos

A mesma definição alimenta:

• O JSON Schema da API (validação e DX);
• O XLSX canônico (?format=xlsx, para o modo arquivo);
• A planilha em branco da própria UI da Axenya.

Obtendo o schema de um tipo

# JSON Schema canônico
curl -sS "$AXENYA_API/movement-templates/INSERT" \
  -H "Authorization: Bearer $AXENYA_KEY"

# Planilha XLSX equivalente
curl -sS "$AXENYA_API/movement-templates/INSERT?format=xlsx" \
  -H "Authorization: Bearer $AXENYA_KEY" --output insert.xlsx

Definição estruturada (contrato interno)

Exemplo do que o backend devolve por tipo — fonte da verdade de colunas, tipos, obrigatórios e enums:

{
  "movementType": "INSERT",
  "version": "2026-06-01",
  "columns": [
    { "key": "cpf",              "type": "string", "required": true,  "pattern": "^\\d{11}$" },
    { "key": "nome",             "type": "string", "required": true },
    { "key": "dataNascimento",   "type": "date",   "required": true },
    { "key": "dataAdmissao",     "type": "date",   "required": false },
    { "key": "sexo",             "type": "enum",   "required": true,  "enum": ["M", "F"] },
    { "key": "tipoBeneficiario", "type": "enum",   "required": true,  "enum": ["TITULAR", "DEPENDENTE"] },
    { "key": "cpfTitular",       "type": "string", "required": false },
    { "key": "grauParentesco",   "type": "enum",   "required": false, "enum": ["CONJUGE", "FILHO", "..."] }
  ]
}

Regras de geração

• key do backend → camelCase no JSON, com um dicionário enxuto de apelidos (ex.: dataNascimento → birthDate).
• Agrupamento por convenção: cpf/nome/… → beneficiary.*, cep/rua/… → registration.address.*.
• required/type/enum/pattern viram restrições do JSON Schema.
• version propaga para o schema e é ecoada como schemaVersion no recibo.

Erros

Erros de protocolo seguem RFC 7807 (application/problem+json). Erros por item de uma movimentação vêm em result.errors[] no recibo.

{
  "type": "https://docs.axenya.com/errors/insufficient-scope",
  "title": "Scope insuficiente",
  "status": 403,
  "detail": "A API key não possui o scope movements:write.",
  "instance": "/v1/movements"
}

Glossário