Skip to main content
Esta página reúne as regras e convenções que se aplicam a todos os endpoints. Leia antes de construir sua integração.

​
Nomenclatura dos campos

Todos os campos de payload usam kebab-case (ex.: company-tax-id, member-tax-id, start-option, access-token). Preserve os nomes exatamente como documentados — não converta para camelCase nem snake_case.

​
Valores monetários

Sempre em centavos (inteiros), sem separador decimal.

​
Números decimais

Valores decimais são representados em seus centésimos (inteiros). Isso vale inclusive para altura (em centímetros) e peso (em quilogramas): multiplique o valor por 100 e envie como inteiro.

​
Datas

  • Datas seguem o formato ISO 8601 — YYYY-MM-DD.
  • Datas com horário incluem timezone (UTC recomendado), ex.: 2024-01-15T10:30:00Z.

​
IDs únicos

  • Todos os IDs internos são UUID versão 4.
  • CPF/CNPJ podem ser enviados apenas com dígitos (12345678900) ou com a formatação padrão (123.456.789-00).

​
Envio de documentos em uma movimentação

Alguns fluxos aceitam documentos. O envio é feito em duas etapas: primeiro você obtém uma URL de upload, faz o upload do arquivo nela, e então referencia o document-id retornado dentro do payload da movimentação.
A URL fica habilitada para receber o upload (via POST ou PUT) por 30 minutos após ter sido gerada, ou até receber algum dado — o que ocorrer primeiro. Faça o upload e utilize o document-id na movimentação dentro desse prazo.
Veja nossos guias de inclusão e exclusão para o uso do campo documents.

​
Regra de uso da opção on-current-billing-period

Esta é uma opção especial de start-option criada para lidar com admissões retroativas. Se um membro foi admitido antes do início do ciclo atual, mas só está sendo incluído na plataforma agora, essa opção permite enquadrá-lo no período de faturamento vigente (mês atual) em vez de esperar pelo próximo. Para evitar erros de validação, só envie on-current-billing-period se ambas as condições forem verdadeiras:
1

Configuração do produto

O produto contratado pela empresa possui a opção on-next-billing-period habilitada/permitida. Não existe configuração própria para on-current-billing-period: ela é liberada implicitamente quando on-next-billing-period está habilitada.
2

Regra de retroatividade

A data de admissão (admission-date) informada é anterior à data de início do período de faturamento atual.
ExemploPeríodo de faturamento inicia no dia 01 de cada mês e hoje é 15 de agosto. Admissão do membro foi em 20 de julho (mês passado).Como a admissão (20/07) é anterior ao início do período atual (01/08), você pode enviar on-current-billing-period: o benefício iniciará em 01/08, garantindo cobertura imediata.