Para programadores
Ligue o seu HRIS e ATS à Paritir
A API de integração permite que os seus sistemas enviem dados de trabalhadores e de anúncios de emprego para a Paritir de forma programada, para que a análise da disparidade remuneratória assente em dados atuais sem importação manual de CSV. Destina-se a quem faz o trabalho de integração: uma consultora, a equipa de TI do cliente ou os próprios engenheiros da Paritir.
O que faz
Três tarefas, uma API
Lotes de trabalhadores
Envie os registos de trabalhadores em lotes. A Paritir identifica cada um pelo seu ID externo e, depois, pelo e-mail, atualiza o que mudou e deduz o histórico salarial e de funções a partir dessas alterações, pelo que nunca tem de enviar o histórico.
Mapeie os campos uma vez
Envie algumas linhas de exemplo e a Paritir propõe a correspondência entre os campos do seu HRIS e os seus. Uma pessoa confirma o mapeamento uma única vez e este é guardado como perfil de origem. As sincronizações seguintes aplicam-no tal como foi guardado e retêm um lote se a estrutura da origem mudar.
Anúncios entram, conformidade sai
Envie anúncios de emprego a partir do seu ATS. A Paritir verifica cada um face às regras de transparência remuneratória do país da sua sede, e pode consultar o resultado de cada anúncio.
Acesso
OAuth 2.0, limitado a uma organização
Credenciais de cliente
O seu sistema troca um ID de cliente e um segredo por um token de acesso. Os tokens são válidos durante 15 minutos; quando expiram, basta pedir um novo. Não existem chaves de API estáticas.
Uma organização por credencial
Um token lê e escreve apenas na organização que emitiu a respetiva credencial. A organização é determinada pela credencial, nunca pelo pedido.
Apenas os âmbitos concedidos
Cada credencial tem os âmbitos escolhidos no momento da sua criação, como escrever trabalhadores ou ler anúncios. Uma chamada fora desses âmbitos é recusada.
Criadas e revogadas na aplicação
O Proprietário ou o Administrador de uma organização cria credenciais em Definições → Integrações. O segredo é mostrado uma única vez e guardado apenas como hash. Revogar uma credencial invalida de imediato os respetivos tokens.
Obter um token e enviar um lote
POST https://app.paritir.com/v1/oauth/token
Content-Type: application/json
{ "grant_type": "client_credentials",
"client_id": "ptir_…", "client_secret": "…" }
→ { "access_token": "…", "token_type": "Bearer",
"expires_in": 900, "scope": "workforce:write" }POST https://app.paritir.com/v1/employees:batch
Authorization: Bearer …
Idempotency-Key: …
Content-Type: application/json
{ "employees": [
{ "external_id": "E-1042", "full_name": "…", "email": "…" }
] }
→ { "sync_run_id": "…", "inserted": 1, "updated": 0,
"unchanged": 0, "errors": 0, … }Referência
Os endpoints disponíveis hoje
Os pedidos e as respostas são em JSON. Cada chamada fica registada na sua organização.
URL base https://app.paritir.com/v1
| Método | Caminho | Âmbito | O que faz |
|---|---|---|---|
| POST | /oauth/token | — | Troca credenciais de cliente por um token de acesso válido durante 15 minutos. |
| POST | /employees:batch | workforce:write | Cria ou atualiza trabalhadores num único lote. |
| POST | /employees:map-preview | workforce:write | Propõe um mapeamento de campos a partir de linhas de exemplo. Não escreve nada. |
| POST | /postings:batch | postings:write | Cria ou atualiza anúncios de emprego num único lote. |
| GET | /postings | postings:read | Lista os anúncios com o respetivo resultado de conformidade, do mais recente para o mais antigo. |
| GET | /postings/{posting_reference} | postings:read | Lê um anúncio pela sua própria referência. |
Reenvio seguro
Envie um cabeçalho Idempotency-Key com cada lote. Repetir a chave devolve o primeiro resultado sem voltar a escrever; uma chave cuja execução ainda decorre recebe HTTP 409.
Paginação e filtros
A lista de anúncios é paginada com limit e um cursor opaco, e filtra por status e por updated_since.
Erros e limites
Os erros são devolvidos em JSON com uma mensagem. A validação indica os campos com erro e nunca repete os valores enviados. As chamadas têm um limite de taxa por organização; acima do limite, recebe HTTP 429.
Estado
O que a API ainda não faz
A API recebe dados e devolve anúncios de emprego. Os resultados da disparidade remuneratória, os relatórios e as avaliações conjuntas das remunerações ficam, por agora, na aplicação. Ainda não existem webhooks nem ambiente de testes (sandbox), pelo que uma nova integração é configurada numa organização real, com a nossa ajuda.
O acesso à API vem com uma conta
A Paritir funciona apenas por convite enquanto trabalhamos com os nossos primeiros clientes e consultoras. Depois de a sua organização estar configurada, o respetivo Proprietário ou Administrador pode criar credenciais de API.