> ## Documentation Index
> Fetch the complete documentation index at: https://docs.piposaude.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções

> Regras que valem para toda requisição e resposta da API.

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.

| Valor        | Enviar como |
| ------------ | ----------- |
| R\$ 1.234,56 | `123456`    |
| R\$ 0,34     | `34`        |
| R\$ 15,00    | `1500`      |

## 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.

| Medida | Valor real      | Enviar como |
| ------ | --------------- | ----------- |
| Altura | 1,75 m (175 cm) | `17500`     |
| Peso   | 70,45 kg        | `7045`      |

## Datas

* Datas seguem o [formato ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) — `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](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_\(random\)).
* **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.

<Warning>
  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.
</Warning>

```mermaid theme={null}
sequenceDiagram
    participant C as Cliente
    participant P as Pipo API
    participant S as File Storage
    C->>P: POST /v1/enrollment/document-upload-url
    P-->>C: JSON { document-id, upload-url }
    C->>S: POST ou PUT https://<upload-url> com o arquivo
    S-->>C: 200 OK
    C->>P: POST movimentação com documents: [{ document-id, document-type }]
    P-->>C: { request-id }
```

Veja nossos guias de [inclusão](/docs/guias/inclusao) e [exclusão](/docs/guias/exclusao) 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Regra de retroatividade">
    A data de admissão (`admission-date`) informada é **anterior** à data de início do período de faturamento atual.
  </Step>
</Steps>

<Info>
  **Exemplo**

  Perí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.
</Info>