Criar um Usuário Participante

Descrição: Cria um novo usuário participante.

Endpoint

POST/api/v1/integration/guest-users/-/producers/{producer_id}

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
email	E-mail de contato	String	Sim	Formatação de e-mail com @ e provedor e deve ser único
social_security	CPF do usuário	String	Sim	Até 12 caracteres, padrão [a-zA-Z0-9]* — aceita letras e números, não só dígitos.
identity_card	RG do usuário	String	Não	Até 30 caracteres / Verifica a Regex
marital_status	Estado civil	Enum	Não	NOT_MARRIED, MARRIED, SEPARATE, DIVORCED, WIDOWER
name	Nome Completo	String	Sim	Até 50 caracteres
phone	Número de celular para contato	String	Não	Atender ao formato +5511999999999. Obrigatório quando `signer.auth` é `SMS` ou `WHATSAPP`
company_id	Identificador da empresa	String	Não	-
address	Endereço do usuário	Object	Não	Objeto opcional. Quando enviado, os campos street, number, neighborhood, zip_code, city, state e country tornam-se obrigatórios.
address.city	Cidade	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 100 caracteres.
address.country	País	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 50 caracteres.
address.neighborhood	Bairro	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 100 caracteres.
address.number	Número	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 10 caracteres.
address.state	Estado	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Sigla da UF, até 2 caracteres (ex: `MT`).
address.street	Rua	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 255 caracteres.
address.complement	Complemento	String	Não	Opcional em qualquer caso. Até 100 caracteres.
address.address_type	Tipo do endereço	String	Não	Opcional em qualquer caso. Valores aceitos: `FARM`, `SUPPLIER`, `SUPPLIER_FARM`, `WAREHOUSE`, `USER`, `COOPERATIVE`, `PRODUCER`. Esta API não rejeita valor fora da lista, mas o serviço de cadastros recusa a requisição a jusante e o erro é repassado.
address.zip_code	CEP	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Deve ter de 5 a 8 dígitos, opcionalmente seguidos de `-` e mais 3 dígitos (ex: `78890000` ou `78890-000`). Outros separadores são recusados com 400 `message.zipCode.invalid.format`.
signer	Dados do signatário	Object	Sim	Objeto obrigatório. É validado em conjunto com o corpo da requisição.
signer.default_signer	Usuário é o signatário padrão	Bool	Sim	Apenas valores booleanos
signer.sign_as	Papel com que o usuário assina o documento	Enum	Sim	SIGN, APPROVE, PARTY, WITNESS, INTERVENING, RECEIPT, ENDORSER, ENDORSEE, ADMINISTRATOR, GUARANTOR, TRANSFEROR, TRANSFEREE, CONTRACTEE, CONTRACTOR, JOINT_DEBTOR, ISSUER, MANAGER, BUYER, SELLER, ATTORNEY, LEGAL_REPRESENTATIVE, CO_RESPONSIBLE, VALIDATOR, RATIFY, LESSOR, LESSEE, SURETY
signer.auth	Tipo de autenticação exigida para confirmação do usuário no momento da assinatura do contrato	Enum	Sim	EMAIL, SMS, WHATSAPP, API
signer.delivery	Informa como o signatário receberá as notificações de confirmação de assinatura e de documento finalizado	Enum	Não	Ignorado. O servico sempre grava `EMAIL`.
signer.identity_id	Identificador da identidade já existente a vincular	String	Não	Ignorado. O servico grava o `email` da raiz do corpo.
signer.company_id	Identificador da empresa do signatário	UUID	Não	Ignorado. O servico grava o identificador da Companhia Produtora do caminho.
signer.name	Nome do signatário	String	Não	Ignorado. O servico grava o `name` da raiz do corpo.
signer.type	Tipo do signatário	Enum	Não	Ignorado. O servico sempre grava `EXTERNAL`.
signer.email	E-mail do signatário	String	Não	Ignorado. O servico grava o `email` da raiz do corpo.
signer.default_auth	Indica se é a autenticação padrão do signatário	Boolean	Não	Ignorado. O servico sempre grava `true`.
signer.has_documentation	Indica se o signatário possui documentação anexada	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.selfie_enabled	Habilita a captura de selfie na assinatura	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.handwritten_enabled	Habilita a assinatura manuscrita	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.official_document_enabled	Exige documento oficial na assinatura	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.phone_number	Telefone do signatário	String	Não	Ignorado. O servico grava o `phone` da raiz do corpo.

Só três campos do signer chegam ao cadastro

O serviço reconstrói o objeto signer antes de gravar. Dele, apenas auth, default_signer e sign_as vêm do que você enviou. Os demais são fixos (delivery = EMAIL, type = EXTERNAL, default_auth = true, os quatro sinalizadores de assinatura = false) ou copiados da raiz do corpo (name, email, phone) e do caminho (a Companhia Produtora). Enviar valor diferente neles não produz erro — só não tem efeito.

phone deixa de ser opcional em dois casos

Quando signer.auth é SMS ou WHATSAPP, o campo phone da raiz do corpo passa a ser obrigatório. Sem ele a requisição é recusada com 400 e a chave message.phone-number.mandatory-to-auth-SMS-or-Whatsapp.

Exemplo de Requisição

cURL
Java
JavaScript
Python
SDK Java

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Oliveira",
    "social_security": "98765432100",
    "email": "maria.oliveira@parceiro.com.br",
    "phone": "+5511999999999",
    "identity_card": "MG1234567",
    "marital_status": "NOT_MARRIED",
    "signer": {
      "auth": "EMAIL",
      "delivery": "EMAIL",
      "default_signer": true,
      "sign_as": "LEGAL_REPRESENTATIVE"
    }
  }' \
  "https://api.merx.tech/api/v1/integration/guest-users/-/producers/{producer_id}"

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String body = "{\"name\": \"Maria Oliveira\", \"social_security\": \"98765432100\", \"email\": \"maria.oliveira@parceiro.com.br\", \"phone\": \"+5511999999999\", \"signer\": {\"auth\": \"EMAIL\", \"delivery\": \"EMAIL\", \"default_signer\": true, \"sign_as\": \"LEGAL_REPRESENTATIVE\"}}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/guest-users/-/producers/{producer_id}"))
    .header("Authorization", "{SUA_API_KEY}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpClient client = HttpClient.newHttpClient();
try {
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
} catch (Exception e) {
    e.printStackTrace();
}

const response = await fetch(
  'https://api.merx.tech/api/v1/integration/guest-users/-/producers/{producer_id}',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Maria Oliveira',
      social_security: '98765432100',
      email: 'maria.oliveira@parceiro.com.br',
      phone: '+5511999999999',
      identity_card: 'MG1234567',
      marital_status: 'NOT_MARRIED',
      signer: {
        auth: 'EMAIL',
        delivery: 'EMAIL',
        default_signer: true,
        sign_as: 'LEGAL_REPRESENTATIVE',
      },
    }),
  }
);
const data = await response.json();
console.log(data);

import requests

url = "https://api.merx.tech/api/v1/integration/guest-users/-/producers/{producer_id}"

headers = {
    "Authorization": "{SUA_API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "name": "Maria Oliveira",
    "social_security": "98765432100",
    "email": "maria.oliveira@parceiro.com.br",
    "phone": "+5511999999999",
    "identity_card": "MG1234567",
    "marital_status": "NOT_MARRIED",
    "signer": {
        "auth": "EMAIL",
        "delivery": "EMAIL",
        "default_signer": True,
        "sign_as": "LEGAL_REPRESENTATIVE"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;
import com.merx.sdk.model.baseline.guestUser.CreateGuestUserRequest;
import com.merx.sdk.model.common.IdResponse;
import java.util.UUID;

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .environment(Environment.SANDBOX)
    .build();

IdResponse guest = merx.guestUsers().create(UUID.fromString("00000000-0000-0000-0000-000000000000"), CreateGuestUserRequest.builder()
    .name("Joao da Silva")
    .email("joao@exemplo.com")
    .socialSecurity("12345678901")
    .build());
System.out.println(guest.getId());

Parâmetros

Parâmetros de Caminho:

Nome	Descrição	Tipo	Obrigatório
producer_id	Identificador da Companhia Produtora	String	Sim

Parâmetros de Cabeçalho

Nome	Descrição	Tipo	Obrigatório
Authorization	Chave de API obtida via support-api@merx.tech	String	Sim
Content-Type	application/json	String	Sim

Parâmetros do Corpo

Nome	Descrição	Tipo	Obrigatório	Validações / Enumeradores
name	Nome completo	String	Sim	Até 50 caracteres
social_security	CPF do usuário	String	Sim	Até 12 caracteres, padrão [a-zA-Z0-9]* — aceita letras e números, não só dígitos.
email	E-mail	String	Sim	Formato e-mail válido
phone	Número de celular	String	Condicional	Formato +5511999999999. Obrigatório quando `signer.auth` é `SMS` ou `WHATSAPP`
identity_card	Cartão de identidade (RG)	String	Não	Até 30 caracteres
marital_status	Estado civil	Enum	Não	NOT_MARRIED, MARRIED, SEPARATE, DIVORCED, WIDOWER
company_id	Identificador da empresa	String	Não	-
address	Endereço	Object	Não	Objeto opcional. Quando enviado, os campos street, number, neighborhood, zip_code, city, state e country tornam-se obrigatórios.
address.street	Rua	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 255 caracteres.
address.number	Número	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 10 caracteres.
address.complement	Complemento	String	Não	Opcional em qualquer caso. Até 100 caracteres.
address.address_type	Tipo do endereço	String	Não	Opcional em qualquer caso. Valores aceitos: `FARM`, `SUPPLIER`, `SUPPLIER_FARM`, `WAREHOUSE`, `USER`, `COOPERATIVE`, `PRODUCER`. Esta API não rejeita valor fora da lista, mas o serviço de cadastros recusa a requisição a jusante e o erro é repassado.
address.neighborhood	Bairro	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 100 caracteres.
address.zip_code	CEP	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Deve ter de 5 a 8 dígitos, opcionalmente seguidos de `-` e mais 3 dígitos (ex: `78890000` ou `78890-000`). Outros separadores são recusados com 400 `message.zipCode.invalid.format`.
address.city	Cidade	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 100 caracteres.
address.state	Estado	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Sigla da UF, até 2 caracteres (ex: `MT`).
address.country	País	String	Não	Opcional. Se o objeto `address` for enviado, este campo passa a ser obrigatório. Até 50 caracteres.
signer	Dados do signatário	Object	Sim	Objeto obrigatório. É validado em conjunto com o corpo da requisição.
signer.default_signer	Signatário padrão	Boolean	Sim	-
signer.sign_as	Papel com que o usuário assina o documento	Enum	Sim	SIGN, APPROVE, PARTY, WITNESS, INTERVENING, RECEIPT, ENDORSER, ENDORSEE, ADMINISTRATOR, GUARANTOR, TRANSFEROR, TRANSFEREE, CONTRACTEE, CONTRACTOR, JOINT_DEBTOR, ISSUER, MANAGER, BUYER, SELLER, ATTORNEY, LEGAL_REPRESENTATIVE, CO_RESPONSIBLE, VALIDATOR, RATIFY, LESSOR, LESSEE, SURETY
signer.auth	Tipo de autenticação	Enum	Sim	EMAIL, SMS, WHATSAPP, API
signer.delivery	Entrega de notificações	Enum	Não	Ignorado. O servico sempre grava `EMAIL`.
signer.identity_id	Identificador da identidade já existente a vincular	String	Não	Ignorado. O servico grava o `email` da raiz do corpo.
signer.company_id	Identificador da empresa do signatário	UUID	Não	Ignorado. O servico grava o identificador da Companhia Produtora do caminho.
signer.name	Nome do signatário	String	Não	Ignorado. O servico grava o `name` da raiz do corpo.
signer.type	Tipo do signatário	Enum	Não	Ignorado. O servico sempre grava `EXTERNAL`.
signer.email	E-mail do signatário	String	Não	Ignorado. O servico grava o `email` da raiz do corpo.
signer.default_auth	Indica se é a autenticação padrão do signatário	Boolean	Não	Ignorado. O servico sempre grava `true`.
signer.has_documentation	Indica se o signatário possui documentação anexada	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.selfie_enabled	Habilita a captura de selfie na assinatura	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.handwritten_enabled	Habilita a assinatura manuscrita	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.official_document_enabled	Exige documento oficial na assinatura	Boolean	Não	Ignorado. O servico sempre grava `false`.
signer.phone_number	Telefone do signatário	String	Não	Ignorado. O servico grava o `phone` da raiz do corpo.

Respostas

200 - Ok

{
    "id": "string"
}

400 - Bad Request

{
  "messages": ["message.entidade.campo-inválido"]
}

401 - Unauthorized
404 - NotFound

Criar um Usuário Participante

Endpoint​

Regras​

Exemplo de Requisição​

Parâmetros​

Parâmetros de Caminho:​

Parâmetros de Cabeçalho​

Parâmetros do Corpo​

Respostas​