% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/classify-smartsolos.R
\name{classify_via_smartsolos_api}
\alias{classify_via_smartsolos_api}
\title{Classify a PedonRecord via Embrapa's SmartSolosExpert REST API}
\usage{
classify_via_smartsolos_api(
  pedon,
  api_key = Sys.getenv("AGROAPI_TOKEN"),
  endpoint = c("classification", "verification"),
  drenagem = NULL,
  reference_sibcs = NULL,
  base_url = "https://api.cnptia.embrapa.br/smartsolos/expert/v1",
  timeout_seconds = 30,
  post_fn = NULL,
  verbose = TRUE
)
}
\arguments{
\item{pedon}{A \code{\link{PedonRecord}}.}

\item{api_key}{Bearer token. Defaults to
\code{Sys.getenv("AGROAPI_TOKEN")}. Required unless
\code{post_fn} is supplied (test injection).}

\item{endpoint}{One of \code{"classification"} (default; classify
only) or \code{"verification"} (classify + compare against
user-supplied \code{reference_sibcs}).}

\item{drenagem}{Optional drainage class. Integer 1..8 or
Portuguese string (\code{"bem drenado"} etc.).}

\item{reference_sibcs}{Optional named list (\code{ordem,
subordem, gde_grupo, subgrupo}) used by the
\code{"verification"} endpoint as the user's reference.}

\item{base_url}{Override base URL. Default
\code{"https://api.cnptia.embrapa.br/smartsolos/expert/v1"}.}

\item{timeout_seconds}{HTTP timeout (default 30).}

\item{post_fn}{Internal: function with signature
\code{function(payload) -> response_list} for unit
tests. When supplied, the network is bypassed.}

\item{verbose}{If \code{TRUE} (default), emits a one-line summary.}
}
\value{
A \code{\link{ClassificationResult}} with
        \code{system = "SiBCS 5a edicao (SmartSolosExpert API)"}
        and the four taxonomic levels in
        \code{rsg_or_order} (Ordem) and \code{qualifiers}
        (Subordem / GdeGrupo / Subgrupo). Verification-mode
        responses additionally carry \code{trace$smartsolos_summary}
        (the per-level match counters \code{L0..L4}).
}
\description{
Sends a soilKey \code{\link{PedonRecord}} to the SmartSolosExpert
REST endpoint maintained by Embrapa (Glauber Vaz's PROLOG-based
implementation of the SiBCS classifier) and returns the resulting
four-level classification (Ordem / Subordem / Grande Grupo /
Subgrupo) wrapped in a soilKey
\code{\link{ClassificationResult}}.
}
\details{
This is an **external classifier** -- the package does not host or
replicate the PROLOG rules. The function exists so soilKey users
can cross-validate the local classifier against an authoritative
Embrapa-hosted reference. Use the \code{"verification"} endpoint to
compare against your own user-supplied reference classification
(the API returns a per-level match \code{summary} with counters
\code{L0..L4}).

Authentication: register a free AgroAPI account at
\url{https://www.agroapi.cnptia.embrapa.br/portal/}, subscribe to
the SmartSolosExpert API and generate an access token. Pass it via
the \code{AGROAPI_TOKEN} environment variable or the
\code{api_key} argument.
}
\examples{
\donttest{
# Needs a SmartSolos Expert API token (set AGROAPI_TOKEN) and
# network access; the example no-ops on CRAN.
if (nzchar(Sys.getenv("AGROAPI_TOKEN")) &&
      requireNamespace("httr", quietly = TRUE)) {
  res <- try(classify_via_smartsolos_api(make_argissolo_canonical()),
             silent = TRUE)
  if (!inherits(res, "try-error")) {
    res$rsg_or_order      # "ARGISSOLO"
    res$qualifiers
  }
}
}
}
\references{
Vaz, G. J., Silva Neto, L. de F. da, & Barbedo, J. G. A. (2025).
SmartSolos Expert: an expert system for Brazilian soil
classification. \emph{Smart Agricultural Technology}, 10, 100735.
\doi{10.1016/j.atech.2024.100735}.

Vaz, G. J., Silva Neto, L. de F. da, Lima, R. N., & Oliveira,
S. R. de M. (2019). Uma API para a classificacao de solos do
Brasil. In \emph{Anais do 12 Congresso Brasileiro de
Agroinformatica} (SBIAGRO 2019), pp. 63-72. Ponta Grossa.

Vaz, G. J., Silva Jr, A. F., & Silva Neto, L. de F. da (2023).
Brazilian soil data for taxonomic classification. \emph{Redape},
V1. \doi{10.48432/PYKKA7}.
}
\seealso{
\code{\link{classify_sibcs}} for the local PROLOG-free
         classifier; \code{\link{compare_smartsolos}} for a
         side-by-side comparison helper;
         \code{\link{benchmark_redape}} for the gold-standard
         curated dataset published by the same authors.
}
