Lookup sunat · aduanet by RUC

GET https://api.latinfo.dev/pe/sunat/aduanet/ruc/{ruc}

One goods series of an import/export declaration; a company can have many records. Coverage: Legal-entity declarations in the imported weekly official customs files. Lookup by ruc as a string, preserving leading zeros. Accepted syntax and normalization are defined by the contract below. FOB is USD and net weight is kg. Do not sum repeated declarations without series/file deduplication. Returns all records as an array. Import time is not observation time; inspect freshness headers. Add limit (1–500) and offset to retrieve an explicit page; without them the complete original array is returned. X-Total-Count gives the exact row count; follow Link rel=next to retrieve all pages.

Contrato de la fuente

Publicador: SUNAT / ADUANET, Peru
Cobertura: Legal-entity declarations in the imported weekly official customs files.
Qué representa un registro: One goods series of an import/export declaration; a company can have many records.
Identificador: Lookup by ruc as a string, preserving leading zeros. Accepted syntax and normalization are defined by the contract below.
Patrón admitido: ^20\d{9}$
Cantidad de registros: many
Licencia: No se ha verificado el permiso de reutilización. El acceso público no equivale a una licencia de reutilización.

Limitaciones conocidas

FOB is USD and net weight is kg. Do not sum repeated declarations without series/file deduplication.

Contrato de la fuente para agentes · Documentación de la fuente

Requiere autenticación. Las solicitudes REST usan una clave de api de Latinfo. La consola agrega el encabezado de autorización y no guarda la clave.

Parámetros

rucstringpathobligatorio

RUC in the source's normalized format. Keep identifiers as strings; preserve leading zeros.

Example: 20509208361

limitintegerquery

Optional page size. Supplying limit or offset enables explicit pagination; default page size is 100.

offsetintegerquery

Row offset, default 0. Keep the same source generation while collecting pages.

generationstringquery

Opaque source-generation guard, automatically included in the next-page Link. A changed generation returns 409; restart retrieval.

Ejemplo de solicitud

curl https://api.latinfo.dev/pe/sunat/aduanet/ruc/20509208361 \
  -H "Authorization: Bearer $LATINFO_API_KEY"

Respuestas

200Published source records. Missing data is not a clearance or a negative finding.

Encabezados de la respuesta

X-Latinfo-Imported-At

Import time, not the date of the government observation.

X-Source-Updated-At

Publisher update time, when known.

X-Latest-Observation-At

Latest date in returned records, when known.

X-Freshness-Status

string

CURRENT · DELAYED · STALE · UNKNOWN

X-Credits-Cost

Actual credits charged for this request.

X-Source-Generation

Opaque immutable source generation. Follow the guarded next-page Link when collecting a history.

X-Total-Count

Exact row count for this identifier when pagination is requested.

X-Page-Offset

integer

X-Page-Limit

integer

Link

Next page URL, rel=next. Absent at the end.

Content-Type: application/json

Campos de la respuesta

[].ruc string obligatorio

Lookup by ruc as a string, preserving leading zeros. Accepted syntax and normalization are defined by the contract below.

[].operation_type string obligatorio

import for MA/MAM formats; export for X formats.

[].declaration string obligatorio

Composite customs-office/year/declaration identifier.

[].customs_office string obligatorio

ADUANET customs office code.

[].declaration_year string obligatorio

Declaration year.

[].declaration_number string obligatorio

Declaration number; retain leading zeros.

[].declaration_date string obligatorio

Published declaration date date. Format: YYYYMMDD.

[].operation_date string obligatorio

Published operation date date. Format: YYYYMMDD.

[].series string obligatorio

Goods series within a declaration; not a distinct company.

[].hs_code string obligatorio

Ten-digit national tariff/NANDINA code.

[].description string obligatorio

Published description.

[].country string obligatorio

Origin country for imports; destination country for exports.

[].fob_usd string obligatorio

Published FOB value; no currency conversion is applied. Unit: USD.

USD

[].net_weight_kg string obligatorio

Published net goods weight. Unit: kg.

kg

[].source_file string obligatorio

Original upstream weekly ZIP name for lineage.

Esquema de respuesta

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "ruc": {
        "type": "string",
        "description": "Lookup by ruc as a string, preserving leading zeros. Accepted syntax and normalization are defined by the contract below."
      },
      "operation_type": {
        "type": "string",
        "description": "import for MA/MAM formats; export for X formats.",
        "x-latinfo-meaning": "text"
      },
      "declaration": {
        "type": "string",
        "description": "Composite customs-office/year/declaration identifier.",
        "x-latinfo-meaning": "identifier"
      },
      "customs_office": {
        "type": "string",
        "description": "ADUANET customs office code.",
        "x-latinfo-meaning": "code"
      },
      "declaration_year": {
        "type": "string",
        "description": "Declaration year.",
        "x-latinfo-meaning": "text"
      },
      "declaration_number": {
        "type": "string",
        "description": "Declaration number; retain leading zeros.",
        "x-latinfo-meaning": "identifier"
      },
      "declaration_date": {
        "type": "string",
        "description": "Published declaration date date. Format: YYYYMMDD.",
        "x-latinfo-meaning": "date"
      },
      "operation_date": {
        "type": "string",
        "description": "Published operation date date. Format: YYYYMMDD.",
        "x-latinfo-meaning": "date"
      },
      "series": {
        "type": "string",
        "description": "Goods series within a declaration; not a distinct company.",
        "x-latinfo-meaning": "text"
      },
      "hs_code": {
        "type": "string",
        "description": "Ten-digit national tariff/NANDINA code.",
        "x-latinfo-meaning": "code"
      },
      "description": {
        "type": "string",
        "description": "Published description.",
        "x-latinfo-meaning": "text"
      },
      "country": {
        "type": "string",
        "description": "Origin country for imports; destination country for exports.",
        "x-latinfo-meaning": "text"
      },
      "fob_usd": {
        "type": "string",
        "description": "Published FOB value; no currency conversion is applied. Unit: USD.",
        "x-latinfo-meaning": "amount",
        "x-latinfo-unit": "USD"
      },
      "net_weight_kg": {
        "type": "string",
        "description": "Published net goods weight. Unit: kg.",
        "x-latinfo-meaning": "quantity",
        "x-latinfo-unit": "kg"
      },
      "source_file": {
        "type": "string",
        "description": "Original upstream weekly ZIP name for lineage.",
        "x-latinfo-meaning": "text"
      }
    },
    "required": [
      "ruc",
      "operation_type",
      "declaration",
      "customs_office",
      "declaration_year",
      "declaration_number",
      "declaration_date",
      "operation_date",
      "series",
      "hs_code",
      "description",
      "country",
      "fob_usd",
      "net_weight_kg",
      "source_file"
    ],
    "additionalProperties": false
  }
}

400Invalid identifier or query. Correct the input before retrying.