Clientes · miCore

O que é

Clientes é o cadastro central de clientes e contatos do miCore — a base que pedidos, CRM, atendimento e publicações usam para saber de quem é cada coisa. Pela API, você lê e mantém esse cadastro com a mesma base que o painel usa por dentro.

Na prática: você lista e consulta clientes, cria novos (inclusive já com o contato de WhatsApp) e atualiza dados — tudo em nome de um usuário responsável, respeitando as permissões dele.

O que dá para fazer hoje

Listar e consultar clientes, com filtros e busca.
Criar um cliente (pessoa física ou jurídica).
Atualizar os dados de um cliente.
Desativar um cliente (baixa por status, sem apagar).
Ligar a pessoa (CPF) às empresas (CNPJ) que ela representa, para comprar em nome delas na loja e no app.

Importante

Cada cliente é pessoa física (pf) ou jurídica (pj); PJ exige o tipo de contribuinte.
O contato é sempre uma pessoa: a empresa é representada por pessoas vinculadas a ela, cada uma com um papel (sócio, administrador, comprador ou financeiro).
O e-mail é único na base; CPF e CNPJ são guardados só com dígitos.
Tipo e documento são identidade do cadastro e não são editáveis pela API v1 — ajuste pelo painel.

Disponibilidade na API

Endpoints de Clientes

Consulte e gerencie os clientes do cadastro central do miCore. Os exemplos abaixo são gerados pelo contrato OpenAPI oficial.

GET /api/v1/clients

Lista clientes do cadastro

Exige o escopo `clients:read`.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`kind`query	string	Não	Filtra por cliente efetivo ou lead.
`type`query	string	Não	—
`status`query	boolean	Não	Ativo (true) ou inativo (false).
`group_id`query	integer	Não	—
`search`query	string	Não	Busca livre por nome, e-mail, CPF ou CNPJ.
`per_page`query	integer	Não	—

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/clients" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": [
        {
            "id": 42,
            "kind": "client",
            "type": "pf",
            "name": "Maria Oliveira",
            "name_pj": null,
            "document": {
                "type": "cpf",
                "value": "12345678909"
            },
            "ie": null,
            "email": "maria@exemplo.com",
            "email_nf": null,
            "status": true,
            "group_id": 1,
            "seller_id": null,
            "newsletter": true,
            "birth": "1990-05-12",
            "created_at": "2026-10-17T09:00:00-03:00",
            "updated_at": "2026-10-17T09:00:00-03:00"
        }
    ],
    "links": [],
    "meta": []
}

Respostas possíveis

200 Página de clientes401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

POST /api/v1/clients

Cria um cliente

Exige `clients:write` e a permissão de criar em Clientes. Para pessoa jurídica, `contributor_type` é obrigatório.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`Idempotency-Key`header	string	Sim	Identificador único da mutação, com 8 a 100 caracteres. O resultado fica reutilizável por 24 horas e a chave não pode ser reutilizada depois de expirar.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Valores: pf, pj.
`name`	string	Sim	Nome da pessoa ou nome fantasia da empresa. Até 100 caracteres.
`name_pj`	string \| null	Não	Razão social, para pessoa jurídica. Até 100 caracteres.
`email`	string (email)	Sim	Único na base. Até 150 caracteres.
`email_nf`	string \| null	Não	Até 255 caracteres.
`is_client`	boolean \| null	Não	true para cliente (padrão), false para lead.
`cpf`	string \| null	Não	Com ou sem máscara; guardado só com dígitos.
`cnpj`	string \| null	Não	Com ou sem máscara; guardado só com dígitos.
`ie`	string \| null	Não	Até 25 caracteres.
`contributor_type`	string \| null	Não	Obrigatório para PJ. '1' = Contribuinte ICMS. Até 1 caracteres.
`phone`	string \| null	Não	Número do WhatsApp; cria o contato do cliente.
`phone_ddd`	string \| null	Não	DDI do WhatsApp; assume 55 (Brasil) quando ausente.
`birth`	string \| null (date)	Não	—
`group_id`	integer \| null	Não	—
`seller_id`	integer \| null	Não	—
`newsletter`	boolean \| null	Não	—

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/clients" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: board-request-0001" \
  -H "Content-Type: application/json" \
  -d '{"type":"pf","name":"string","name_pj":null,"email":"string","email_nf":null,"is_client":true,"cpf":null,"cnpj":null,"ie":null,"contributor_type":null,"phone":null,"phone_ddd":null,"birth":"2026-10-20","group_id":1,"seller_id":1,"newsletter":true}'

Exemplo de resposta JSON

Resposta · 201

{
    "data": {
        "id": 42,
        "kind": "client",
        "type": "pf",
        "name": "Maria Oliveira",
        "name_pj": null,
        "document": {
            "type": "cpf",
            "value": "12345678909"
        },
        "ie": null,
        "email": "maria@exemplo.com",
        "email_nf": null,
        "status": true,
        "group_id": 1,
        "seller_id": null,
        "newsletter": true,
        "birth": "1990-05-12",
        "created_at": "2026-10-17T09:00:00-03:00",
        "updated_at": "2026-10-17T09:00:00-03:00"
    }
}

Respostas possíveis

201 Cliente criado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente409 Chave em processamento ou reutilizada com outro conteúdo422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

GET /api/v1/clients/{client}

Exibe um cliente

Exige o escopo `clients:read`.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`client`path	integer	Sim	—

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/clients/{client}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 42,
        "kind": "client",
        "type": "pf",
        "name": "Maria Oliveira",
        "name_pj": null,
        "document": {
            "type": "cpf",
            "value": "12345678909"
        },
        "ie": null,
        "email": "maria@exemplo.com",
        "email_nf": null,
        "status": true,
        "group_id": 1,
        "seller_id": null,
        "newsletter": true,
        "birth": "1990-05-12",
        "created_at": "2026-10-17T09:00:00-03:00",
        "updated_at": "2026-10-17T09:00:00-03:00"
    }
}

Respostas possíveis

200 Cliente encontrado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

PATCH /api/v1/clients/{client}

Atualiza um cliente

Exige `clients:write` e a permissão de editar em Clientes. Tipo e documento não são editáveis na v1.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`client`path	integer	Sim	—

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	Até 100 caracteres.
`name_pj`	string \| null	Não	Até 100 caracteres.
`email`	string (email)	Não	Até 150 caracteres.
`email_nf`	string \| null	Não	Até 255 caracteres.
`is_client`	boolean	Não	—
`ie`	string \| null	Não	Até 25 caracteres.
`contributor_type`	string \| null	Não	Até 1 caracteres.
`birth`	string \| null (date)	Não	—
`group_id`	integer	Não	—
`seller_id`	integer \| null	Não	—
`newsletter`	boolean	Não	—

Exemplo de requisição

cURL

curl -X PATCH "$MICORE_BASE_URL/clients/{client}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","name_pj":null,"email":"string","email_nf":null,"is_client":true,"ie":null,"contributor_type":null,"birth":"2026-10-20","group_id":1,"seller_id":1,"newsletter":true}'

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 42,
        "kind": "client",
        "type": "pf",
        "name": "Maria Oliveira",
        "name_pj": null,
        "document": {
            "type": "cpf",
            "value": "12345678909"
        },
        "ie": null,
        "email": "maria@exemplo.com",
        "email_nf": null,
        "status": true,
        "group_id": 1,
        "seller_id": null,
        "newsletter": true,
        "birth": "1990-05-12",
        "created_at": "2026-10-17T09:00:00-03:00",
        "updated_at": "2026-10-17T09:00:00-03:00"
    }
}

Respostas possíveis

200 Cliente atualizado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado422 Dados inválidos429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

DELETE /api/v1/clients/{client}

Desativa um cliente

Exige `clients:write` e a permissão de excluir em Clientes. Desativa sem apagar; o status é dado e a reativação é pelo painel. Idempotente.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`client`path	integer	Sim	—

Exemplo de requisição

cURL

curl -X DELETE "$MICORE_BASE_URL/clients/{client}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 42,
        "kind": "client",
        "type": "pf",
        "name": "Maria Oliveira",
        "name_pj": null,
        "document": {
            "type": "cpf",
            "value": "12345678909"
        },
        "ie": null,
        "email": "maria@exemplo.com",
        "email_nf": null,
        "status": true,
        "group_id": 1,
        "seller_id": null,
        "newsletter": true,
        "birth": "1990-05-12",
        "created_at": "2026-10-17T09:00:00-03:00",
        "updated_at": "2026-10-17T09:00:00-03:00"
    }
}

Respostas possíveis

200 Cliente desativado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida503 O domínio não pôde ser associado com segurança a um tenant

GET /api/v1/clients/{clientId}/company-members

Lista os vínculos entre pessoa e empresas do cliente

Exige `clients:read` e a permissão Gestão de Cadastro (ver). Para uma pessoa (PF), devolve as empresas que ela representa; para uma empresa (PJ), as pessoas que a representam. Traz os ativos e os pendentes (pedidos pela loja ou pelo app esperando aprovação).

Exemplo de requisição

cURL

curl "$MICORE_BASE_URL/clients/{clientId}/company-members" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": [
        {
            "id": 1,
            "person": {
                "id": 1,
                "name": "string",
                "cpf": "string"
            },
            "company": {
                "id": 1,
                "name": "string",
                "name_pj": "string",
                "cnpj": "string"
            },
            "role": "partner",
            "status": "active",
            "source": "panel",
            "approved_at": "2026-10-20T10:00:00-03:00",
            "created_at": "2026-10-20T10:00:00-03:00",
            "updated_at": "2026-10-20T10:00:00-03:00"
        }
    ]
}

Respostas possíveis

200 Vínculos do cliente401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado

POST /api/v1/clients/{clientId}/company-members

Vincula uma pessoa a uma empresa

Exige `clients:write` e a permissão Gestão de Cadastro (editar). Funciona pelos dois lados: na rota da pessoa, `client_id` é a empresa; na rota da empresa, `client_id` é a pessoa. A pessoa precisa ser PF com CPF e a empresa, PJ. O vínculo feito pela API já nasce ativo; se havia um pedido pendente, ele é aprovado com o papel enviado. Vínculo já ativo devolve 409.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`client_id`	integer	Sim	O outro lado do vínculo: a empresa (na rota da pessoa) ou a pessoa (na rota da empresa).
`role`	string	Sim	Valores: partner, administrator, buyer, financial.

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/clients/{clientId}/company-members" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"client_id":1,"role":"partner"}'

Exemplo de resposta JSON

Resposta · 201

{
    "data": {
        "id": 1,
        "person": {
            "id": 1,
            "name": "string",
            "cpf": "string"
        },
        "company": {
            "id": 1,
            "name": "string",
            "name_pj": "string",
            "cnpj": "string"
        },
        "role": "partner",
        "status": "active",
        "source": "panel",
        "approved_at": "2026-10-20T10:00:00-03:00",
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

201 Vínculo criado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado409 Chave em processamento ou reutilizada com outro conteúdo, ou ação não permitida no estado atual do recurso (`invalid_transition`)422 Dados inválidos429 Cota por minuto da credencial excedida

PATCH /api/v1/client-company-members/{memberId}

Troca o papel da pessoa na empresa

Exige `clients:write` e a permissão Gestão de Cadastro (editar). Só o papel muda; situação e origem ficam como estão (a situação muda pela ação de aprovar).

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`role`	string	Sim	Valores: partner, administrator, buyer, financial.

Exemplo de requisição

cURL

curl -X PATCH "$MICORE_BASE_URL/client-company-members/{memberId}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"role":"partner"}'

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "person": {
            "id": 1,
            "name": "string",
            "cpf": "string"
        },
        "company": {
            "id": 1,
            "name": "string",
            "name_pj": "string",
            "cnpj": "string"
        },
        "role": "partner",
        "status": "active",
        "source": "panel",
        "approved_at": "2026-10-20T10:00:00-03:00",
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Vínculo atualizado401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado422 Dados inválidos429 Cota por minuto da credencial excedida

DELETE /api/v1/client-company-members/{memberId}

Desfaz o vínculo (ou recusa o pedido pendente)

Exige `clients:write` e a permissão Gestão de Cadastro (editar). A pessoa deixa de comprar e de ver pedidos e notas da empresa na loja e no app.

Exemplo de requisição

cURL

curl -X DELETE "$MICORE_BASE_URL/client-company-members/{memberId}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Respostas possíveis

204 Vínculo desfeito401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida

POST /api/v1/client-company-members/{memberId}/approve

Aprova o vínculo pedido pela loja ou pelo app

Exige `clients:write` e a permissão Gestão de Cadastro (editar). O pedido pendente passa a valer, aprovado pelo usuário responsável pela credencial. Aprovar um vínculo já ativo não muda nada.

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/client-company-members/{memberId}/approve" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json"

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 1,
        "person": {
            "id": 1,
            "name": "string",
            "cpf": "string"
        },
        "company": {
            "id": 1,
            "name": "string",
            "name_pj": "string",
            "cnpj": "string"
        },
        "role": "partner",
        "status": "active",
        "source": "panel",
        "approved_at": "2026-10-20T10:00:00-03:00",
        "created_at": "2026-10-20T10:00:00-03:00",
        "updated_at": "2026-10-20T10:00:00-03:00"
    }
}

Respostas possíveis

200 Vínculo ativo401 Token ausente, inválido, expirado ou revogado403 Escopo, assinatura, módulo ou permissão insuficiente404 Recurso não encontrado429 Cota por minuto da credencial excedida