{
  "titulo": "YOUK — Documentação da API",
  "descricao": "A API do YOUK permite que o sistema do parceiro (folha de pagamento, RH, ponto ou qualquer outro) envie documentos aos colaboradores de forma automática. Cada documento enviado é entregue ao colaborador diretamente no aplicativo YOUK, onde ele pode visualizar e, quando necessário, assinar digitalmente.",
  "base_url": "https://api.youk.com.br/v1",
  "documentacao_html": "https://api.youk.com.br/",
  "autenticacao": {
    "tipo": "Bearer",
    "header": "Authorization: Bearer <token>",
    "como_obter": "O token é obtido pelo gestor da empresa na página administrativa do YOUK (https://manager.youk.com.br), na área de integrações.",
    "pagina_administrativa": "https://manager.youk.com.br",
    "observacoes": [
      "Todos os endpoints, exceto GET /v1/health, exigem o token de acesso.",
      "Gerar um novo token na página administrativa invalida o token anterior.",
      "Não exponha o token em aplicações de front-end nem em repositórios de código.",
      "No erro de token inválido, o campo code do corpo difere do status HTTP retornado; utilize o status HTTP como referência."
    ],
    "erros": [
      {
        "situacao": "Cabeçalho Authorization ausente",
        "status": 403,
        "corpo": {
          "message": "Acesso não permitido."
        }
      },
      {
        "situacao": "Token inválido, expirado ou revogado",
        "status": 401,
        "corpo": {
          "code": 403,
          "message": "Autenticação não é válida ou está expirada."
        }
      }
    ]
  },
  "status_http": [
    {
      "status": 200,
      "significado": "Requisição processada com sucesso."
    },
    {
      "status": 400,
      "significado": "Dados inválidos no payload. Corrija os campos apontados antes de reenviar."
    },
    {
      "status": 401,
      "significado": "Token de acesso inválido, expirado ou revogado."
    },
    {
      "status": 403,
      "significado": "Acesso não permitido (sem token, conta desativada ou recurso de outro integrador)."
    },
    {
      "status": 404,
      "significado": "Recurso não encontrado."
    },
    {
      "status": 409,
      "significado": "Conflito com o estado atual do recurso."
    },
    {
      "status": 500,
      "significado": "Falha interna. Tente novamente; se persistir, contate o suporte do YOUK."
    }
  ],
  "erros_validacao": {
    "descricao": "Quando o payload possui campos inválidos, a resposta traz status 400 e a lista completa de erros em details.erros. Cada item indica o campo em field, usando notação com ponto para campos aninhados (por exemplo, colaborador.nome) e prefixo com o número do item para listas (por exemplo, [1]grupos.descricao).",
    "exemplo": {
      "code": 400,
      "message": "Evento inválido",
      "details": {
        "valid": false,
        "erros": [
          {
            "code": 400,
            "message": "colaborador.nome - Precisa ter entre 2 e 120 caracteres",
            "field": "colaborador.nome"
          }
        ]
      }
    }
  },
  "erro_url_nao_encontrada": {
    "code": 404,
    "message": "Endereço '/v1/caminho-invalido' não encontrado.",
    "details": {
      "metodo": "GET"
    }
  },
  "tipos_documento": [
    {
      "valor": "PAGAMENTO",
      "descricao_padrao": "Recibo de pagamento",
      "formato_data_referencia": "yyyy-mm"
    },
    {
      "valor": "PAGAMENTO_COMPLEMENTAR",
      "descricao_padrao": "Recibo pagamento complementar",
      "formato_data_referencia": "yyyy-mm"
    },
    {
      "valor": "FERIAS",
      "descricao_padrao": "Recibo de férias",
      "formato_data_referencia": "yyyy"
    },
    {
      "valor": "DECIMO_TERCEIRO",
      "descricao_padrao": "Recibo de 13º",
      "formato_data_referencia": "yyyy"
    },
    {
      "valor": "INFORME_RENDIMENTOS",
      "descricao_padrao": "Informe de rendimentos",
      "formato_data_referencia": "yyyy"
    },
    {
      "valor": "ESPELHO_FOLHA_PONTO",
      "descricao_padrao": "Espelho de folha de ponto",
      "formato_data_referencia": "yyyy-mm"
    },
    {
      "valor": "NOTIFICACAO_ADVERTENCIA",
      "descricao_padrao": "Notificação de advertência",
      "formato_data_referencia": "yyyy-mm-dd"
    },
    {
      "valor": "CUSTOMIZADO",
      "descricao_padrao": "Customizado",
      "formato_data_referencia": "yyyy-mm-dd"
    }
  ],
  "endpoints": [
    {
      "metodo": "GET",
      "caminho": "/v1/health",
      "titulo": "Status da API",
      "descricao": "Verifica se a API está disponível. Não exige autenticação e pode ser usado em monitoramentos e testes de conectividade.",
      "autenticacao": false,
      "resposta_sucesso": {
        "status": "ok"
      }
    },
    {
      "metodo": "POST",
      "caminho": "/v1/eventos",
      "titulo": "Enviar documento",
      "descricao": "Envia um documento em PDF para um colaborador. O documento é entregue no aplicativo YOUK e, quando marcado como assinável, o colaborador é solicitado a assiná-lo digitalmente. Se o colaborador, o departamento ou os grupos ainda não existirem, eles são criados automaticamente com os dados do payload; se já existirem, são atualizados. O tipo do documento é criado automaticamente quando não existe; quando já existe (localizado pela descrição), é reutilizado sem alterações. A empresa deve estar cadastrada previamente no manager.youk.com.br.",
      "autenticacao": true,
      "campos": [
        {
          "campo": "arquivo_base64",
          "tipo": "string",
          "obrigatorio": true,
          "descricao": "Conteúdo do PDF codificado em base64. Precisa ser um PDF válido (o conteúdo codificado inicia com JVBERi0) com no máximo 5 MB."
        },
        {
          "campo": "data_referencia",
          "tipo": "string",
          "obrigatorio": true,
          "descricao": "Data de referência (competência) do documento. O formato depende do tipo do documento — veja a tabela em Tipo do documento."
        },
        {
          "campo": "tipo",
          "tipo": "objeto",
          "obrigatorio": false,
          "padrao": "CUSTOMIZADO",
          "descricao": "Tipo do documento enviado. Quando não informado, o documento é tratado como CUSTOMIZADO. Veja Tipo do documento."
        },
        {
          "campo": "colaborador",
          "tipo": "objeto",
          "obrigatorio": true,
          "descricao": "Colaborador que receberá o documento. Veja Colaborador."
        },
        {
          "campo": "externo_id",
          "tipo": "string",
          "obrigatorio": false,
          "descricao": "Identificador do documento no sistema parceiro, com 1 a 128 caracteres. Recomendado para facilitar o rastreio."
        },
        {
          "campo": "periodo",
          "tipo": "objeto",
          "obrigatorio": false,
          "descricao": "Período de referência do documento. Quando informado, os campos inicial e final são obrigatórios, no formato yyyy-mm para o tipo FERIAS e yyyy para os demais tipos."
        },
        {
          "campo": "opcoes.assinavel",
          "tipo": "boolean",
          "obrigatorio": false,
          "padrao": "true",
          "descricao": "Quando true, o colaborador deverá assinar o documento no aplicativo."
        },
        {
          "campo": "opcoes.retificar_anteriores",
          "tipo": "boolean",
          "obrigatorio": false,
          "padrao": "true",
          "descricao": "Quando true, documentos anteriores equivalentes (mesmo colaborador, tipo e referência) são retificados, ou seja, substituídos por este envio."
        }
      ],
      "objetos": {
        "tipo": [
          {
            "campo": "tipo",
            "tipo": "string",
            "obrigatorio": false,
            "padrao": "CUSTOMIZADO",
            "descricao": "Um dos valores da tabela abaixo. Valores não informados ou desconhecidos são tratados como CUSTOMIZADO."
          },
          {
            "campo": "descricao",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Nome do documento exibido ao colaborador, com 2 a 60 caracteres. Quando não informado, usa a descrição padrão do tipo (tabela abaixo)."
          },
          {
            "campo": "observacao",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Observação complementar, com até 200 caracteres."
          },
          {
            "campo": "externo_id",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador do tipo no sistema parceiro."
          },
          {
            "campo": "uid",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador do tipo no YOUK."
          }
        ],
        "colaborador": [
          {
            "campo": "nome",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Nome completo do colaborador, com 2 a 120 caracteres."
          },
          {
            "campo": "documento",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "CPF válido do colaborador, com ou sem formatação. Não pode ser alterado depois do cadastro."
          },
          {
            "campo": "documento_tipo",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Aceito apenas CPF."
          },
          {
            "campo": "empresa",
            "tipo": "objeto",
            "obrigatorio": true,
            "descricao": "Empresa do colaborador, já cadastrada no YOUK. A empresa de um colaborador já cadastrado não pode ser alterada. Veja Empresa."
          },
          {
            "campo": "externo_id",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador do colaborador no sistema parceiro. Recomendado para manter a sincronização; não pode ser alterado enquanto o colaborador estiver ativo."
          },
          {
            "campo": "uid",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador do colaborador no YOUK."
          },
          {
            "campo": "ativo",
            "tipo": "boolean",
            "obrigatorio": false,
            "padrao": "true",
            "descricao": "Colaborador inativo não pode receber documentos."
          },
          {
            "campo": "data_admissao",
            "tipo": "string",
            "obrigatorio": false,
            "padrao": "data atual",
            "descricao": "Data de admissão no formato yyyy-mm-dd."
          },
          {
            "campo": "data_desligamento",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Data de desligamento no formato yyyy-mm-dd, menor ou igual à data atual. Quando informada, o colaborador é marcado como inativo."
          },
          {
            "campo": "codigo_cartao_ponto",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Código do cartão de ponto do colaborador."
          },
          {
            "campo": "contato.telefone",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Telefone de contato, com até 20 caracteres."
          },
          {
            "campo": "endereco",
            "tipo": "objeto",
            "obrigatorio": false,
            "descricao": "Endereço do colaborador. Veja Endereço."
          },
          {
            "campo": "departamento",
            "tipo": "objeto",
            "obrigatorio": false,
            "descricao": "Departamento do colaborador. Veja Departamento e grupos."
          },
          {
            "campo": "grupos",
            "tipo": "lista de objetos",
            "obrigatorio": false,
            "descricao": "Grupos do colaborador, com no máximo 5 grupos. Veja Departamento e grupos."
          }
        ],
        "empresa": [
          {
            "campo": "nome_razao",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Razão social da empresa, com 2 a 120 caracteres."
          },
          {
            "campo": "documento",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Documento da empresa, validado conforme o documento_tipo. Exemplo de CNPJ: 11.222.333/0001-81."
          },
          {
            "campo": "documento_tipo",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Aceitos: CPF, CNPJ, CAEPF e CNO."
          },
          {
            "campo": "externo_id",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador da empresa no sistema parceiro."
          },
          {
            "campo": "uid",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador da empresa no YOUK."
          },
          {
            "campo": "nome_fantasia",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Nome fantasia, com 2 a 120 caracteres."
          }
        ],
        "endereco": [
          {
            "campo": "logradouro",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Menos de 120 caracteres."
          },
          {
            "campo": "numero",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Menos de 60 caracteres."
          },
          {
            "campo": "bairro",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Menos de 120 caracteres."
          },
          {
            "campo": "cidade",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Menos de 120 caracteres."
          },
          {
            "campo": "estado_sigla",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Sigla de um estado brasileiro, com 2 caracteres (ex.: SP, RJ)."
          },
          {
            "campo": "pais",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "País do endereço. Aceito Brasil."
          },
          {
            "campo": "complemento",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Menos de 120 caracteres."
          },
          {
            "campo": "cep",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "CEP formatado, no padrão 00000-000 (ex.: 25710-140)."
          }
        ],
        "departamento_grupo": [
          {
            "campo": "descricao",
            "tipo": "string",
            "obrigatorio": true,
            "descricao": "Nome do departamento ou grupo exibido no YOUK, com 2 a 60 caracteres."
          },
          {
            "campo": "externo_id",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador no sistema parceiro. Recomendado para manter a sincronização."
          },
          {
            "campo": "observacao",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Até 200 caracteres."
          },
          {
            "campo": "uid",
            "tipo": "string",
            "obrigatorio": false,
            "descricao": "Identificador no YOUK."
          }
        ]
      },
      "exemplo_request": {
        "externo_id": "REC-2025-06-0001",
        "tipo": {
          "externo_id": "1",
          "tipo": "PAGAMENTO"
        },
        "data_referencia": "2025-06",
        "arquivo_base64": "JVBERi0xLjQK...",
        "colaborador": {
          "externo_id": "12345",
          "nome": "João da Silva",
          "documento": "111.444.777-35",
          "documento_tipo": "CPF",
          "data_admissao": "2024-01-15",
          "contato": {
            "telefone": "(21) 99999-0000"
          },
          "endereco": {
            "logradouro": "Rua das Flores",
            "numero": "12",
            "bairro": "Centro",
            "cidade": "Teresópolis",
            "estado_sigla": "RJ",
            "pais": "Brasil",
            "complemento": "Fundos",
            "cep": "25710-140"
          },
          "empresa": {
            "externo_id": "77",
            "nome_razao": "Empresa Exemplo LTDA",
            "documento": "11.222.333/0001-81",
            "documento_tipo": "CNPJ"
          },
          "departamento": {
            "externo_id": "10",
            "descricao": "Comercial"
          },
          "grupos": [
            {
              "externo_id": "5",
              "descricao": "Supervisores"
            }
          ]
        },
        "opcoes": {
          "assinavel": true,
          "retificar_anteriores": true
        }
      },
      "resposta_sucesso": {
        "uid": "kr7e9QlVOZsR6Qws0hmp"
      },
      "erros": [
        {
          "status": 400,
          "situacao": "Payload inválido — a lista de campos com problema é retornada em details.erros (veja Erros)."
        },
        {
          "status": 400,
          "situacao": "O colaborador está inativo, a empresa está desativada ou o tipo do documento está desativado."
        },
        {
          "status": 404,
          "situacao": "Empresa não encontrada com os dados informados."
        },
        {
          "status": 403,
          "situacao": "Conta desativada ou limite de colaboradores da licença atingido."
        },
        {
          "status": 409,
          "situacao": "Conflito ao tentar alterar o externo_id de um departamento ou grupo já existente."
        },
        {
          "status": 500,
          "situacao": "Falha interna ao salvar o documento."
        }
      ]
    },
    {
      "metodo": "GET",
      "caminho": "/v1/eventos/:id",
      "titulo": "Consultar documento",
      "descricao": "Consulta a situação de um documento enviado: se já foi entregue ao colaborador e, quando assinável, se já foi assinado. Substitua :id pelo uid retornado no envio do documento.",
      "autenticacao": true,
      "campos_resposta": [
        {
          "campo": "id",
          "tipo": "string",
          "descricao": "Identificador do documento no YOUK."
        },
        {
          "campo": "status_entrega",
          "tipo": "string",
          "descricao": "Situação da entrega ao colaborador (tabela abaixo)."
        },
        {
          "campo": "assinatura.assinavel",
          "tipo": "boolean",
          "descricao": "Indica se o documento exige assinatura do colaborador."
        },
        {
          "campo": "assinatura.status",
          "tipo": "string",
          "descricao": "Situação da assinatura: PENDENTE, REJEITADO ou ASSINADO. Não é retornado quando o documento não é assinável."
        }
      ],
      "status_entrega": [
        {
          "valor": "AGUARDANDO_APROVACAO",
          "significado": "O colaborador ainda não aceitou o vínculo com a empresa; o documento fica aguardando essa etapa para ser enviado."
        },
        {
          "valor": "REJEITADO",
          "significado": "O colaborador rejeitou o vínculo com a empresa; o documento fica retido até que o vínculo seja aceito."
        },
        {
          "valor": "ENTREGUE",
          "significado": "Documento entregue ao colaborador e disponível no aplicativo YOUK."
        }
      ],
      "status_assinatura": [
        {
          "valor": "PENDENTE",
          "significado": "Aguardando a assinatura do colaborador no aplicativo."
        },
        {
          "valor": "REJEITADO",
          "significado": "Documento rejeitado pelo colaborador; em processo de ajuste com o gestor."
        },
        {
          "valor": "ASSINADO",
          "significado": "Documento assinado; o PDF assinado está disponível para download."
        }
      ],
      "resposta_sucesso": {
        "id": "kr7e9QlVOZsR6Qws0hmp",
        "status_entrega": "ENTREGUE",
        "assinatura": {
          "assinavel": true,
          "status": "PENDENTE"
        }
      },
      "erros": [
        {
          "status": 404,
          "situacao": "Documento não encontrado, cancelado, ou já retificado/removido por um envio mais recente."
        },
        {
          "status": 403,
          "situacao": "O documento não pertence a esta integração — a consulta só está disponível para documentos enviados pela mesma integração."
        },
        {
          "status": 500,
          "situacao": "Falha interna na consulta."
        }
      ]
    },
    {
      "metodo": "GET",
      "caminho": "/v1/eventos/:id/download_assinado",
      "titulo": "Baixar documento assinado",
      "descricao": "Baixa o PDF assinado pelo colaborador, codificado em base64 no campo arquivo. Disponível apenas para documentos enviados como assináveis (opcoes.assinavel = true) e que já foram assinados. Substitua :id pelo uid retornado no envio do documento.",
      "autenticacao": true,
      "resposta_sucesso": {
        "arquivo": "JVBERi0xLjQK..."
      },
      "erros": [
        {
          "status": 400,
          "situacao": "O documento não é assinável."
        },
        {
          "status": 400,
          "situacao": "O documento ainda não foi assinado pelo colaborador."
        },
        {
          "status": 404,
          "situacao": "Documento não encontrado, cancelado, já retificado/removido, ou arquivo assinado indisponível."
        },
        {
          "status": 403,
          "situacao": "O documento não pertence a esta integração."
        },
        {
          "status": 500,
          "situacao": "Falha interna no download."
        }
      ]
    }
  ]
}