Fornecedores · miCore

O que é

Fornecedores é o cadastro de quem vende para a empresa: nome, razão social, contatos, vendedor e endereço. O miCore usa esse cadastro nas compras e nas contas a pagar e a receber.

Na prática: você consulta os fornecedores, cadastra um novo ao trazer o catálogo dele para o sistema e mantém os dados de contato em dia.

O que dá para fazer hoje

Listar e consultar fornecedores, com busca por nome, razão social ou CNPJ.
Cadastrar um fornecedor, de forma idempotente.
Atualizar os dados de um fornecedor (edição parcial).
Desativar um fornecedor (sem apagar).

Importante

O nome é único no cadastro.
A inscrição estadual é guardada só com números.
Leitura exige suppliers:read; cadastrar, editar e desativar exigem suppliers:write e a permissão correspondente em Fornecedores.

Disponibilidade na API

Endpoints de Fornecedores

Consulte e mantenha o cadastro de fornecedores do miCore. Os exemplos abaixo são gerados pelo contrato OpenAPI oficial.

GET /api/v1/suppliers

Lista os fornecedores

Exige o escopo `suppliers:read` e a permissão de ver em Fornecedores.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`status`query	boolean	Não	—
`search`query	string	Não	Busca por nome, razão social ou CNPJ.
`per_page`query	integer	Não	—

Exemplo de requisição

cURL

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

Exemplo de resposta JSON

Resposta · 200

{
    "data": [
        {
            "id": 12,
            "name": "TinTec",
            "name_pj": "TinTec Co., Ltd.",
            "cnpj": null,
            "ie": null,
            "phone_1": "+82 70 0000 0000",
            "phone_2": null,
            "email": "vendas@fornecedor.example",
            "instagram": null,
            "description": "Chaves chipless, CISS e tintas",
            "seller_name": "Agente comercial",
            "seller_email": "agente@fornecedor.example",
            "seller_phone": null,
            "street": null,
            "number": null,
            "complement": null,
            "neighborhood": null,
            "city_id": null,
            "state_id": null,
            "country_id": null,
            "zip": null,
            "observations": "Preços ExWorks Coreia",
            "status": true,
            "created_at": "2026-11-03T10:00:00-03:00",
            "updated_at": "2026-11-03T10:00:00-03:00"
        }
    ],
    "links": [],
    "meta": []
}

Respostas possíveis

200 Página de fornecedores401 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/suppliers

Cadastra um fornecedor

Exige `suppliers:write` e a permissão de criar em Fornecedores. Criação idempotente (envie um Idempotency-Key). O nome é único (422 quando já existe).

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
`name`	string	Sim	Até 255 caracteres.
`name_pj`	string \| null	Não	Até 255 caracteres.
`cnpj`	string \| null	Não	Até 255 caracteres.
`ie`	string \| null	Não	Até 255 caracteres.
`phone_1`	string \| null	Não	Até 255 caracteres.
`phone_2`	string \| null	Não	Até 255 caracteres.
`email`	string \| null (email)	Não	—
`instagram`	string \| null	Não	Até 255 caracteres.
`description`	string \| null	Não	Até 255 caracteres.
`seller_name`	string \| null	Não	Até 255 caracteres.
`seller_email`	string \| null (email)	Não	—
`seller_phone`	string \| null	Não	Até 255 caracteres.
`street`	string \| null	Não	Até 255 caracteres.
`number`	string \| null	Não	Até 255 caracteres.
`complement`	string \| null	Não	Até 255 caracteres.
`neighborhood`	string \| null	Não	Até 255 caracteres.
`city_id`	integer \| null	Não	—
`state_id`	integer \| null	Não	—
`country_id`	integer \| null	Não	—
`zip`	string \| null	Não	Até 255 caracteres.
`observations`	string \| null	Não	—
`status`	boolean \| null	Não	—

Exemplo de requisição

cURL

curl -X POST "$MICORE_BASE_URL/suppliers" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: board-request-0001" \
  -H "Content-Type: application/json" \
  -d '{"name":"TinTec","name_pj":"TinTec Co., Ltd.","email":"vendas@fornecedor.example","observations":"Preços ExWorks Coreia"}'

Exemplo de resposta JSON

Resposta · 201

{
    "data": {
        "id": 12,
        "name": "TinTec",
        "name_pj": "TinTec Co., Ltd.",
        "cnpj": null,
        "ie": null,
        "phone_1": "+82 70 0000 0000",
        "phone_2": null,
        "email": "vendas@fornecedor.example",
        "instagram": null,
        "description": "Chaves chipless, CISS e tintas",
        "seller_name": "Agente comercial",
        "seller_email": "agente@fornecedor.example",
        "seller_phone": null,
        "street": null,
        "number": null,
        "complement": null,
        "neighborhood": null,
        "city_id": null,
        "state_id": null,
        "country_id": null,
        "zip": null,
        "observations": "Preços ExWorks Coreia",
        "status": true,
        "created_at": "2026-11-03T10:00:00-03:00",
        "updated_at": "2026-11-03T10:00:00-03:00"
    }
}

Respostas possíveis

201 Fornecedor cadastrado401 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/suppliers/{supplier}

Exibe um fornecedor

Exige o escopo `suppliers:read`.

Parâmetros

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

Exemplo de requisição

cURL

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

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 12,
        "name": "TinTec",
        "name_pj": "TinTec Co., Ltd.",
        "cnpj": null,
        "ie": null,
        "phone_1": "+82 70 0000 0000",
        "phone_2": null,
        "email": "vendas@fornecedor.example",
        "instagram": null,
        "description": "Chaves chipless, CISS e tintas",
        "seller_name": "Agente comercial",
        "seller_email": "agente@fornecedor.example",
        "seller_phone": null,
        "street": null,
        "number": null,
        "complement": null,
        "neighborhood": null,
        "city_id": null,
        "state_id": null,
        "country_id": null,
        "zip": null,
        "observations": "Preços ExWorks Coreia",
        "status": true,
        "created_at": "2026-11-03T10:00:00-03:00",
        "updated_at": "2026-11-03T10:00:00-03:00"
    }
}

Respostas possíveis

200 Fornecedor 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/suppliers/{supplier}

Edita um fornecedor

Exige `suppliers:write` e a permissão de editar em Fornecedores. Edição parcial - só os campos enviados mudam.

Parâmetros

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

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	Até 255 caracteres.
`name_pj`	string \| null	Não	Até 255 caracteres.
`cnpj`	string \| null	Não	Até 255 caracteres.
`ie`	string \| null	Não	Até 255 caracteres.
`phone_1`	string \| null	Não	Até 255 caracteres.
`phone_2`	string \| null	Não	Até 255 caracteres.
`email`	string \| null (email)	Não	—
`instagram`	string \| null	Não	Até 255 caracteres.
`description`	string \| null	Não	Até 255 caracteres.
`seller_name`	string \| null	Não	Até 255 caracteres.
`seller_email`	string \| null (email)	Não	—
`seller_phone`	string \| null	Não	Até 255 caracteres.
`street`	string \| null	Não	Até 255 caracteres.
`number`	string \| null	Não	Até 255 caracteres.
`complement`	string \| null	Não	Até 255 caracteres.
`neighborhood`	string \| null	Não	Até 255 caracteres.
`city_id`	integer \| null	Não	—
`state_id`	integer \| null	Não	—
`country_id`	integer \| null	Não	—
`zip`	string \| null	Não	Até 255 caracteres.
`observations`	string \| null	Não	—
`status`	boolean \| null	Não	—

Exemplo de requisição

cURL

curl -X PATCH "$MICORE_BASE_URL/suppliers/{supplier}" \
  -H "Authorization: Bearer $MICORE_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"novo@fornecedor.example"}'

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 12,
        "name": "TinTec",
        "name_pj": "TinTec Co., Ltd.",
        "cnpj": null,
        "ie": null,
        "phone_1": "+82 70 0000 0000",
        "phone_2": null,
        "email": "vendas@fornecedor.example",
        "instagram": null,
        "description": "Chaves chipless, CISS e tintas",
        "seller_name": "Agente comercial",
        "seller_email": "agente@fornecedor.example",
        "seller_phone": null,
        "street": null,
        "number": null,
        "complement": null,
        "neighborhood": null,
        "city_id": null,
        "state_id": null,
        "country_id": null,
        "zip": null,
        "observations": "Preços ExWorks Coreia",
        "status": true,
        "created_at": "2026-11-03T10:00:00-03:00",
        "updated_at": "2026-11-03T10:00:00-03:00"
    }
}

Respostas possíveis

200 Fornecedor 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/suppliers/{supplier}

Desativa um fornecedor

Exige `suppliers:write` e a permissão de desabilitar em Fornecedores. Desativa sem apagar; reativar é pelo painel. Idempotente.

Parâmetros

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

Exemplo de requisição

cURL

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

Exemplo de resposta JSON

Resposta · 200

{
    "data": {
        "id": 12,
        "name": "TinTec",
        "name_pj": "TinTec Co., Ltd.",
        "cnpj": null,
        "ie": null,
        "phone_1": "+82 70 0000 0000",
        "phone_2": null,
        "email": "vendas@fornecedor.example",
        "instagram": null,
        "description": "Chaves chipless, CISS e tintas",
        "seller_name": "Agente comercial",
        "seller_email": "agente@fornecedor.example",
        "seller_phone": null,
        "street": null,
        "number": null,
        "complement": null,
        "neighborhood": null,
        "city_id": null,
        "state_id": null,
        "country_id": null,
        "zip": null,
        "observations": "Preços ExWorks Coreia",
        "status": true,
        "created_at": "2026-11-03T10:00:00-03:00",
        "updated_at": "2026-11-03T10:00:00-03:00"
    }
}

Respostas possíveis

200 Fornecedor 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