API de Onboarding - Contrato para Backend

Visão Geral

Rota pública autenticada por token JWT na URL. O token identifica o prestador e o contrato/contexto do onboarding. Não usa o sistema de auth padrão da aplicação.

O token JWT deve conter no payload: contractId, providerId, borrowerId, exp (expiração).

---

Endpoints

1. GET /onboarding/:token

Retorna os dados do onboarding para o prestador.

Headers:

Authorization: Bearer {token}

Response 200:

{
  "data": {
    "borrower": {
      "id": "uuid",
      "name": "Empresa Tomadora LTDA",
      "tradeName": "Tomadora",
      "cnpj": "12.345.678/0001-00",
      "role": "borrower"
    },
    "provider": {
      "id": "uuid",
      "name": "Empresa Prestadora LTDA",
      "tradeName": "Prestadora",
      "cnpj": "98.765.432/0001-00",
      "role": "provider"
    },
    "documents": [
      {
        "id": "uuid",
        "name": "Exame Clínico Ocupacional",
        "description": "Atestado de saúde ocupacional válido",
        "isRequired": true,
        "acceptedFormats": ["pdf", "jpg", "png"],
        "maxFileSize": 10,
        "status": "waiting",
        "rejectionReason": null,
        "fileUrl": null,
        "fileName": null,
        "uploadedAt": null
      },
      {
        "id": "uuid",
        "name": "Certidão de Regularidade",
        "description": null,
        "isRequired": true,
        "acceptedFormats": ["pdf"],
        "maxFileSize": 5,
        "status": "rejected",
        "rejectionReason": "Documento ilegível, favor reenviar",
        "fileUrl": "https://storage.example.com/file.pdf",
        "fileName": "certidao.pdf",
        "uploadedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "uuid",
        "name": "Comprovante de Endereço",
        "description": null,
        "isRequired": false,
        "acceptedFormats": ["pdf", "jpg", "png"],
        "maxFileSize": 5,
        "status": "validated",
        "rejectionReason": null,
        "fileUrl": "https://storage.example.com/file2.pdf",
        "fileName": "comprovante.pdf",
        "uploadedAt": "2024-01-14T08:00:00Z"
      }
    ],
    "downloadDocuments": [
      {
        "id": "uuid",
        "name": "Contrato de Prestação de Serviços",
        "description": "Contrato assinado entre as partes",
        "fileUrl": "https://storage.example.com/contrato.pdf",
        "fileName": "contrato-prestacao-servicos.pdf"
      }
    ],
    "formFields": [
      {
        "id": "uuid",
        "label": "Data do exame",
        "type": "date",
        "required": true,
        "value": null,
        "options": null,
        "placeholder": null
      },
      {
        "id": "uuid",
        "label": "Tipo de evento",
        "type": "select",
        "required": true,
        "value": null,
        "options": [
          { "label": "Admissional", "value": "admissional" },
          { "label": "Periódico", "value": "periodico" },
          { "label": "Demissional", "value": "demissional" }
        ],
        "placeholder": "Selecione o tipo"
      },
      {
        "id": "uuid",
        "label": "Observações",
        "type": "textarea",
        "required": false,
        "value": null,
        "options": null,
        "placeholder": "Observações adicionais"
      }
    ],
    "expiresAt": "2024-02-15T23:59:59Z",
    "contractId": "uuid",
    "message": "Por favor, envie todos os documentos até a data de expiração."
  }
}

Response 401 (token inválido/expirado):

{
  "message": "Token inválido ou expirado"
}

Response 404:

{
  "message": "Onboarding não encontrado"
}

---

2. POST /onboarding/:token/documents/:documentId/upload

Upload de arquivo para um documento específico.

Headers:

Authorization: Bearer {token}
Content-Type: multipart/form-data

Body: FormData com campo file

Regras:

• Só permite upload se status do documento for waiting ou rejected
• Valida formato e tamanho conforme configuração do documento
• Após upload, status muda para uploaded

Response 200:

{
  "data": {
    "id": "uuid",
    "documentId": "uuid",
    "fileName": "exame.pdf",
    "fileUrl": "https://storage.example.com/uploaded-file.pdf",
    "status": "uploaded",
    "uploadedAt": "2024-01-20T14:30:00Z"
  }
}

Response 400:

{
  "message": "Formato de arquivo não aceito"
}

Response 409:

{
  "message": "Documento já enviado e aguardando validação. Não é possível alterar."
}

---

3. DELETE /onboarding/:token/documents/:documentId/file

Remove o arquivo de um documento (apenas se status for waiting ou rejected).

Headers:

Authorization: Bearer {token}

Regras:

• Só permite remoção se status for waiting ou rejected
• Documentos com status uploaded ou validated não podem ser removidos

Response 200:

{
  "data": {
    "documentId": "uuid",
    "status": "waiting"
  }
}

Response 409:

{
  "message": "Não é possível remover arquivo em validação"
}

---

4. PUT /onboarding/:token/form

Salva os campos do formulário dinâmico.

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Body:

{
  "fields": [
    { "id": "uuid", "value": "2024-01-20" },
    { "id": "uuid", "value": "admissional" },
    { "id": "uuid", "value": "Sem observações" }
  ]
}

Regras:

• Valida campos obrigatórios
• Valida tipo do valor conforme type do campo
• Permite salvar parcialmente (sem validar obrigatoriedade, apenas na submissão final)

Response 200:

{
  "data": {
    "message": "Formulário salvo com sucesso"
  }
}

---

5. POST /onboarding/:token/submit

Submissão final do onboarding.

Headers:

Authorization: Bearer {token}

Regras:

• Todos os documentos obrigatórios devem estar com status uploaded ou validated
• Todos os campos obrigatórios do formulário devem estar preenchidos
• Após submissão, o tomador é notificado para revisão

Response 200:

{
  "data": {
    "message": "Onboarding enviado com sucesso"
  }
}

Response 422:

{
  "message": "Documentos obrigatórios pendentes",
  "details": {
    "missingDocuments": ["uuid1", "uuid2"],
    "missingFields": ["uuid3"]
  }
}

---

Status dos Documentos - Fluxo

waiting → (prestador faz upload) → uploaded → (tomador valida) → validated
                                            → (tomador rejeita) → rejected → (prestador reenvia) → uploaded

Regras por status:

Status	Upload permitido	Remoção permitida	Ação do prestador
waiting	Sim	N/A	Fazer upload
uploaded	Não	Não	Aguardar validação
validated	Não	Não	Nenhuma (concluído)
rejected	Sim	Sim	Reenviar arquivo

---

Token JWT

Payload esperado:

{
  "contractId": "uuid",
  "providerId": "uuid",
  "borrowerId": "uuid",
  "type": "onboarding",
  "exp": 1708041599
}

Validade sugerida: 7 a 30 dias (configurável pelo tomador).

Geração: O tomador gera o link de onboarding no sistema, que cria o token JWT e retorna a URL completa para compartilhar com o prestador.