Guia: Cadastros

Fluxo para cadastrar os elementos fundamentais da plataforma Merx.

Mapa de dependências

Cada seta A → B significa "B precisa do ID de A para ser criado". Entidades sem seta de entrada são independentes.

Leitura rápida:

• Produtor é a raiz — Fazenda, Armazém, Participante e Códigos ERP são todos cadastrados via endpoints aninhados em /producers/:id.
• Carteira é independente do Produtor na criação, mas precisa ser vinculada posteriormente.
• Local de Entrega não tem dependência nenhuma — pode ser cadastrado a qualquer momento.

Sequência recomendada

1. Cadastrar produtor

Dependência: nenhuma — é a raiz.

Verifique se o produtor já existe pelo CPF/CNPJ antes de criar:

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

Se retornar 404, crie o produtor. trading_name e social_identity são obrigatórios; os demais são opcionais.

curl -X POST \
  https://api.merx.tech/api/v1/integration/producers \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "trading_name": "João Silva",
    "social_identity": "12345678901",
    "company_name": "João Silva MEI",
    "email": "joao@exemplo.com.br",
    "date_of_birth": "1980-01-15"
  }'

Response: {"id": "uuid-do-produtor"} — guarde este producer_id.

Adicione o endereço (o CEP precisa vir com hífen):

curl -X POST \
  https://api.merx.tech/api/v1/integration/producers/{producer_id}/address \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "street": "Rua das Palmeiras",
    "number": "100",
    "neighborhood": "Centro",
    "zip_code": "14400-000",
    "city": "Franca",
    "state": "SP",
    "country": "Brasil"
  }'

Detalhes em Cadastrar Companhia Produtora e Cadastrar endereço.

2. Cadastrar fazenda

Dependência: producer_id (passo 1) — vai no path, não no body.

curl -X POST \
  https://api.merx.tech/api/v1/integration/farms/-/producers/{producer_id} \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "car": "MT-5107925-A1B2C3D4E5F6G7H8I9J0K1L2M3N4",
    "name": "Fazenda Boa Vista",
    "own": true,
    "state_subscription": "123456-MT",
    "registration": "REG-001",
    "area": "1500.00"
  }'

Campos obrigatórios: car, name, own (Boolean — true para própria, false para alugada). area é String.

Response: {"id": "uuid-da-fazenda"}. Detalhes em Criar Fazenda.

3. Cadastrar armazém

Dependência: producer_id (passo 1) — vai no path.

O armazém exige document (CNPJ do armazém) e um objeto address completo.

curl -X POST \
  https://api.merx.tech/api/v1/integration/warehouses/-/producers/{producer_id} \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Armazém Central MT",
    "document": "12345678000190",
    "capacity": 5000.00,
    "state_subscription": "123456-MT",
    "state_subscription_uf": "MT",
    "address": {
      "street": "Av. das Indústrias",
      "number": "1000",
      "complement": "Galpão 3",
      "neighborhood": "Distrito Industrial",
      "zip_code": "78705-060",
      "city": "Sorriso",
      "state": "MT",
      "country": "Brasil"
    }
  }'

Response: {"id": "uuid-do-armazém"}. Detalhes em Cadastrar Armazém.

4. Criar carteira e vincular produtor

Dependência na criação: owner_id — UUID do usuário dono da carteira. Dependência no vínculo: wallet_id + producer_id, ambos no path.

Crie a carteira:

curl -X POST \
  https://api.merx.tech/api/v1/integration/wallets \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carteira Spot Soja",
    "description": "Operações de venda de soja spot",
    "owner_id": "{user_owner_id}"
  }'

Response: {"id": "uuid-da-carteira"}

Vincule o produtor (endpoint sem body — os IDs vão no path):

curl -X POST \
  https://api.merx.tech/api/v1/integration/wallets/{wallet_id}/producers/{producer_id} \
  -H "Authorization: {SUA_API_KEY}"

Response: 204 No Content. Detalhes em Cadastrar Carteira e Adicionar Produtora à Carteira.

5. Cadastrar participante (guest user)

Dependência: producer_id (passo 1) — vai no path. O participante é sempre associado a um produtor.

Obrigatórios: name, social_security (CPF), email e o objeto signer completo.

curl -X POST \
  https://api.merx.tech/api/v1/integration/guest-users/-/producers/{producer_id} \
  -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"
    }
  }'

signer.auth: EMAIL, SMS, WHATSAPP. signer.delivery: EMAIL, NONE. signer.sign_as: WITNESS, LEGAL_REPRESENTATIVE.

Response: {"id": "uuid-do-participante"}. Detalhes em Criar Usuário Participante.

6. Cadastrar local de entrega

Dependência: nenhuma.

Os campos são place (nome) e description. Não há city/state neste endpoint.

curl -X POST \
  https://api.merx.tech/api/v1/integration/delivery-places \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "place": "Porto de Embarque Norte",
    "description": "Unidade de entrega para região norte de MT"
  }'

Response: {"id": "uuid-do-local"}. Detalhes em Criar Unidade de Entrega.

7. Cadastrar códigos ERP do produtor

Dependência: producer_id (passo 1) — vai no path. Os códigos são enviados como array no body.

curl -X POST \
  https://api.merx.tech/api/v1/integration/producers/{producer_id}/erp \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "erp_codes": [
      { "id": "777", "description": "Código ERP principal" },
      { "id": "888", "description": "Código ERP secundário" }
    ]
  }'

Response: 204 No Content. Detalhes em Criar Código ERP.

Onde cada entidade é consumida

Entidade criada aqui	Usada em
producer_id	Comercial (negociação, rastreabilidade), Financeiro (requester), Identidade
CPF/CNPJ do produtor + código CAR	Compliance Ambiental, Financeiro — identificação via documento e CAR, não por ID
wallet_id (com produtor vinculado)	Comercial (negociação)
delivery_place_id	Comercial (negociação)
guest_user_id	Processos de assinatura digital de contratos

Erros comuns

Erro	Causa	Solução
{"messages": ["message.producer.already-exists"]}	CPF/CNPJ já cadastrado	Use GET por documento primeiro
{"messages": ["message.producer.not-found"]}	producer_id inválido no path	Verifique o UUID retornado no POST do passo 1
{"messages": ["message.wallet.not-found"]}	wallet_id inválido no vínculo	Crie a carteira (passo 4) antes de vincular
401 sem body	Header Authorization ausente ou inválido	Inclua o header Authorization em todas as requisições