Pular para o conteúdo principal

Guia: Identidade

Fluxos para consultar e manter usuários internos da cooperativa e de companhias produtoras. Usuários da cooperativa são somente consulta; usuários de Companhia Produtora têm ciclo de vida completo na API (criar, atualizar e desvincular).

Tipos de usuário​

  • Usuário da Cooperativa: funcionário da comercializadora/cooperativa. Buscado diretamente pelo CPF.
  • Usuário Produtor: usuário interno de uma Companhia Produtora. A busca exige o producer_id e o CPF do usuário.
  • Todas as rotas de usuário produtor ficam sob /api/v1/integration/producer-users; as de usuário da cooperativa, sob /api/v1/integration/cooperative-users.

1. Buscar usuário da cooperativa por CPF​

Endpoint: GET /api/v1/integration/cooperative-users/-/{social_id}:findBySocialId

curl -X GET \
  https://api.merx.tech/api/v1/integration/cooperative-users/-/98765432100:findBySocialId \
  -H "Authorization: {SUA_API_KEY}"

social_id é o CPF (somente números) do usuário interno. Retorna id, username, given_name, family_name, email, role, social_id, além de flags como enabled, email_verified, first_access.

Detalhes em Buscar usuário interno por CPF.

2. Listar usuários de uma Companhia Produtora​

Endpoint: GET /api/v1/integration/producer-users/-/producers/{producer_id}

Retorna todos os usuários internos vinculados a um produtor.

curl -X GET \
  https://api.merx.tech/api/v1/integration/producer-users/-/producers/{producer_id} \
  -H "Authorization: {SUA_API_KEY}"

Detalhes em Listar usuários da Companhia Produtora.

3. Buscar usuário da Companhia Produtora por CPF​

Endpoint: GET /api/v1/integration/producer-users/-/producers/{producer_id}/{social_id}:findBySocialId

Exige ambos producer_id e social_id no path.

curl -X GET \
  https://api.merx.tech/api/v1/integration/producer-users/-/producers/{producer_id}/98765432100:findBySocialId \
  -H "Authorization: {SUA_API_KEY}"

Detalhes em Buscar usuário da Companhia Produtora por CPF.

4. Criar usuário de Companhia Produtora​

Endpoint: POST /api/v1/integration/producer-users/-/producers/{producer_id}

Obrigatórios: full_name (até 255 caracteres), phone_number, social_id (somente dígitos, até 20), auth, delivery, default_signer (Boolean) e sign_as.

email é opcional, mas há uma regra condicional: quando email não é informado, phone_number passa a ser exigido — na prática phone_number já é obrigatório em qualquer cenário.

curl -X POST \
  https://api.merx.tech/api/v1/integration/producer-users/-/producers/{producer_id} \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Maria Oliveira",
    "email": "maria.oliveira@parceiro.com.br",
    "phone_number": "+5511999999999",
    "social_id": "98765432100",
    "auth": "EMAIL",
    "delivery": "EMAIL",
    "default_signer": true,
    "sign_as": "LEGAL_REPRESENTATIVE"
  }'

auth: EMAIL, SMS, WHATSAPP, API. delivery: EMAIL, NONE. type (opcional): ORIGINATOR, PRODUCER, EXTERNAL. sign_as aceita a mesma lista completa de papéis de assinatura descrita em Cadastros §5.

Response: {"id": "uuid-do-usuário"}.

5. Atualizar e desvincular​

  • PUT /api/v1/integration/producer-users/{producer_user_id}/producers/{producer_id} — atualiza o usuário. Response: 204 No Content.
  • DELETE /api/v1/integration/producer-users/{producer_user_id}/producers/{producer_id} — remove o vínculo do usuário com a Companhia Produtora. Response: 204 No Content.

Observações​

  • Usuários da cooperativa são somente leitura na API de integração: só existe o GET por CPF. O provisionamento desses usuários é feito pelos canais administrativos da plataforma Merx.
  • Para cadastrar um participante/signatário vinculado a uma Companhia Produtora (usado em fluxos de assinatura de contratos), consulte Cadastros §5.