Fornecedores

O recurso Fornecedores (/suppliers) mantém o cadastro de fornecedores do tenant. Ele é o espelho de Clientes: a mesma estrutura de pessoa física/jurídica, tax_id, contatos, dados bancários e extensões por país (br_data, us_data). Fornecedores são a ponta de origem do fluxo de compras — notas de compra e contas a pagar.

Permissão exigida: suppliers (ações create, read, update, delete).

Conceitos e campos-chave

A estrutura é idêntica à de clientes, inclusive na geografia de entrada: país, estado e cidade vão por texto ou por código, com as mesmas regras. A diferença está na resposta: o país vem como country_code (string), e não como o objeto country de clientes.

O tax_id segue a mesma regra de Clientes: normalizado (pontuação ignorada) e sem validação de dígitos verificadores. Na resposta, o país vem como country_code (string), e city/state como objetos resolvidos.

Criar um fornecedor

curl -X POST https://api.biterp.ai/suppliers \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "tax_id": "98.765.432/0001-10",
    "tax_id_type": "CNPJ",
    "legal_name": "Fornecedora Industrial S.A.",
    "trade_name": "FornInd",
    "country_code": "BR",
    "emails": ["compras@fornind.com.br"],
    "address_street": "Rua da Indústria",
    "address_number": "500",
    "address_district": "Distrito Industrial",
    "postal_code": "04500-000",
    "state": "SP",
    "city": "São Paulo",
    "br_data": {
      "ie": "111222333444",
      "cnae_primary": "4671100",
      "pix_key": "98765432000110",
      "pix_key_type": "cnpj"
    }
  }'

Cidade e estado podem ir por texto (city, state), que a API resolve para o catálogo interno, ou por código: city_id aceita o ID do catálogo ou o código IBGE do município, e state_id o ID do catálogo (obtidos via Dados de referência). Nome ambíguo, ID inexistente ou country_code não resolvível retorna 422 Unprocessable Entity, com o campo em details.fields. No PATCH, sem country_code, o país não muda, e estado e cidade são resolvidos dentro do país já gravado no fornecedor.

Buscar fornecedores

Além da listagem paginada (GET /suppliers, com filtros e paginação):

Campos filtráveis em GET /suppliers: legal_name, trade_name, tax_id, type, city, state, country_code, is_active, reference_code, tags, created_at, updated_at. Ordenação por id, legal_name, trade_name, reference_code, created_at, updated_at.

Remover

DELETE /suppliers/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints