Convenções
Nomenclatura JSON
Todos os campos JSON usam camelCase (ex.: contractNumber, firstDueDate). Documentos (CPF, CNPJ) trafegam somente dígitos, sem pontuação.
Tipos de dado
| Tipo | Representação JSON |
|---|---|
| Identificador | string (UUID) |
| Data sem hora | string no formato YYYY-MM-DD (ex.: disbursementDate, firstDueDate) |
| Data com hora | string ISO 8601 em UTC, com sufixo Z (ex.: 2026-09-15T07:45Z) |
Valor monetário (campos terminados em Amount) | number decimal, sempre com 6 casas decimais nas respostas (ex.: 2215.840000, 0.000000) |
Taxa (*Rate, cet) | number em fração: 0.018 significa 1,8% |
| Inteiro | number |
| Booleano | boolean, pode aceitar null |
| Lista | array (vazio [], nunca null, nas respostas) |
Casas decimais dos valores monetários
Nas respostas, todo campo cujo nome termina em Amount — em qualquer nível do JSON, inclusive em installments[], disbursementOptions[] e nas consultas Dataprev — é escrito com exatamente seis casas decimais: 50.000000, 2141.570000. Campos Amount nulos continuam null. Os demais números (taxas, prazos, quantidades) não seguem essa regra e saem com a precisão do próprio valor.
Leia esses campos como número decimal, sem depender da quantidade de casas, e arredonde só na exibição. Nas requisições, qualquer quantidade de casas é aceita (50, 50.00 e 50.000000 são equivalentes).
Identificadores
Cada recurso carrega até três identificadores:
| Campo | Tipo | Uso |
|---|---|---|
id | string (uuid) | Identificador principal. É o que você usa nas rotas (/v5/loans/{id}). |
code | integer | Número sequencial legível por empresa. Não use em rotas. |
key | string (uuid) | Chave pública alternativa. Alguns recursos permitem busca por ela (/v5/authorization-terms/key/{key}). |
Alguns recursos ainda expõem nid (inteiro interno) e contractNumber (empréstimos). Guarde sempre o id.
Campos de domínio
Valores de lista (tipos, papéis, métodos) nunca são strings soltas nas respostas: chegam como CodeKeyName { code, key, name }. Ao enviar, informe apenas a key como string ("paymentMethod": "direct_loan"). Um campo de domínio não preenchido vem como objeto com valores nulos ou zero ({ "code": 0, "key": null, "name": null }), e não como null — trate key == null como "não informado".
Padrão de rotas
| Rota | Verbo | Descrição |
|---|---|---|
/v5/<recurso> | POST | Cria um registro (ou executa uma consulta persistida). 201 Created. |
/v5/<recurso>/{id} | GET | Busca por id. |
/v5/<recurso>/key/{key} | GET | Busca pela chave pública (onde suportado). |
/v5/<recurso>/{id}/<transição> | PUT | Executa uma transição de estado (signatures, disbursements, endorsements). 200 OK com o recurso atualizado. |
/v5/<recurso>/{id}/<pedido> | POST | Registra um pedido processado em segundo plano (ex.: signature-requests). 201 Created com o pedido, não com o resultado final. |
/v5/<recurso>/{id}/<pedido>/current | GET | Último pedido ou registro daquele tipo, para acompanhamento (ex.: document-requests/current). 404 sem corpo quando ainda não existe. |
Busca paginada, filtros, edição e exclusão lógica dos registros ficam nas aplicações web da Semear e não são expostos na API de integração.
Processamento em segundo plano
Várias operações não terminam na chamada: consultas e averbação na Dataprev, formalização (CCB e assinatura), envio do contrato e desaverbação. A chamada valida o que pode ser validado na hora, registra o trabalho e responde com o registro em um status intermediário (pending, processing, endorsement_processing). O resultado chega por eventos de webhook ou pela rota de leitura do recurso, quando existe. Erros que só aparecem no processamento ficam gravados no próprio registro (status.note, lastError ou o campo de mensagem do recurso), e não na resposta da chamada original.
Consultas persistidas
Vínculos, dados do trabalhador, saldo FGTS e simulações são consultas persistidas: cada POST chama o provedor (ou o motor de cálculo), grava o resultado com id/code próprios e devolve 201 Created. Isso cria um histórico auditável e permite recuperar o resultado depois sem nova chamada ao provedor.
Referências entre entidades (RefField)
Campos que referenciam outra entidade (product, lender, fund, payrollEntity) armazenam apenas o identificador; code e name são resolvidos na leitura. Ao enviar, informe só o identificador ou a key (ex.: "product": "private_payroll"). Ver Referências organizacionais.
As respostas de termos, consultas Dataprev, simulações e empréstimos não trazem a hierarquia organizacional (company, unit, partner, branch, agent, user) nem o log de auditoria (log); quando um recurso traz esses blocos, a página dele indica (ver Referências organizacionais e Log de auditoria).