Look a RUC up in the hosted SUNAT padrón — informational, never a validation
Answers what SUNAT's published padrón says about a RUC: the legal name, the literal estado del contribuyente and condición de domicilio, and a coarse classification of each. THIS DOES NOT VALIDATE ANYTHING AND DOES NOT AFFECT ISSUANCE. A RUC this route reports as not registered can still be invoiced, and doing so is neither an error nor a warning: no create, no trigger and no dispatch decision reads this catalogue. The copy is a snapshot and is therefore ALWAYS behind — a company registered since the snapshot was cut is absent from it while being entirely able to receive a comprobante — so treat the answer as information for a human, not as a gate. THERE ARE THREE OUTCOMES AND ONLY TWO OF THEM ARE ABOUT THE TAXPAYER: 200 with registered=true, 200 with registered=false (a snapshot is loaded and this RUC is not in it), and 503 TAXPAYER_REGISTRY_UNAVAILABLE (no snapshot is loaded at all, which is a statement about this service). A client that folds the 503 into registered=false reports an outage of ours as a fact about somebody's customer. Both the literal SUNAT value and the classification are returned: the literal is authoritative and the classification is ours and may be UNKNOWN, so a value SUNAT adds tomorrow is visible rather than silently mapped. registry.publishedOn dates the snapshot the answer came from and is SUNAT's own publication date, never the time this API ingested it. Requires consultations:read, which is disjoint from every documents:* capability: asking who a RUC belongs to must not require a credential that can issue a comprobante.
Answers what SUNAT's published padrón says about a RUC: the legal name, the literal estado del contribuyente and condición de domicilio, and a coarse classification of each. THIS DOES NOT VALIDATE ANYTHING AND DOES NOT AFFECT ISSUANCE. A RUC this route reports as not registered can still be invoiced, and doing so is neither an error nor a warning: no create, no trigger and no dispatch decision reads this catalogue. The copy is a snapshot and is therefore ALWAYS behind — a company registered since the snapshot was cut is absent from it while being entirely able to receive a comprobante — so treat the answer as information for a human, not as a gate. THERE ARE THREE OUTCOMES AND ONLY TWO OF THEM ARE ABOUT THE TAXPAYER: 200 with registered=true, 200 with registered=false (a snapshot is loaded and this RUC is not in it), and 503 TAXPAYER_REGISTRY_UNAVAILABLE (no snapshot is loaded at all, which is a statement about this service). A client that folds the 503 into registered=false reports an outage of ours as a fact about somebody's customer. Both the literal SUNAT value and the classification are returned: the literal is authoritative and the classification is ours and may be UNKNOWN, so a value SUNAT adds tomorrow is visible rather than silently mapped. registry.publishedOn dates the snapshot the answer came from and is SUNAT's own publication date, never the time this API ingested it. Requires consultations:read, which is disjoint from every documents:* capability: asking who a RUC belongs to must not require a credential that can issue a comprobante.
Authorization
bearerAuth Tenant-bound, scoped and expiring Apifact credential. Migrated legacy credentials are accepted only on deprecated v1 writes and tenant-scoped v2 read, poll and download routes. Each operation names the single scope it requires in x-required-scope; the scope array of the security requirement itself is empty because OpenAPI 3.0 requires it to be for a non-oauth2 scheme.
In: header
Path Parameters
Exactly eleven digits. Anything else is 422 INVALID_RUC and is never reported as an unregistered taxpayer.
^[0-9]{11}$Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v2/consultations/ruc/string" \ -H "Authorization: Bearer apf_v2_tu_credencial"{ "schemaVersion": "2.0", "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6", "ruc": "string", "registered": true, "registry": { "publishedOn": "2019-08-24", "rowCount": 0 }, "taxpayer": { "ruc": "string", "legalName": "string", "status": "string", "statusClass": "ACTIVE", "condition": "string", "conditionClass": "HABIDO" }}Read one client company, its capabilities, its certificate and its credentials GET GET
Everything needed to answer 'can this client bill, and if not why not'. THE THREE FAILURES ARE ONE ANSWER: a company belonging to another organization, a company that does not exist and an INACTIVE company all return the identical 404, decided by a single SELECT rather than by three branches, so this route cannot be used to discover that a RUC is registered elsewhere. Requires organizations:read; a credential holding companies:manage satisfies it, and one holding only organizations:read can create nothing, mint nothing and enrol nothing.
Resolve the published exchange rate that applies on a given date GET GET
Returns the rate to apply to an operation on the requested date, following the rule in D.S. 29-94-EF artículo 5 numeral 17: the rate published on that date, or, on a day with no publication, EL ÚLTIMO PUBLICADO — the last one published on or before it. It never resolves forward and never interpolates. THE DATE IS A REQUIRED PATH SEGMENT WITH NO DEFAULT, on purpose: this service runs on UTC and Peru is UTC-05:00, so a server-side 'today' would resolve to tomorrow's date for every request sent after 19:00 in Lima, and the último-publicado rule would then hand back a rate labelled with a date the caller never asked about. The caller knows its comprobante's issue date; this service does not. BECAUSE THE ANSWER MAY COME FROM ANOTHER DAY, read rateDate, fallback and stalenessDays before displaying anything: fallback=true means rateDate differs from requestedOn, and stalenessDays is how far back the answer was taken from — 2 over a weekend is normal and correct under the rule, while 40 is not a market fact but a loader that stopped running. No ceiling is imposed here, because the norm has none; reporting is this API's half of the job and deciding is the caller's. Both sides are returned: for IGV the answer is sellRate ('promedio ponderado venta', for sales and purchases alike), while buyRate exists because the Impuesto a la Renta rule splits compra/venta by activo/pasivo. Rates are STRINGS with six decimals and must be parsed as decimals — routing a rate that gets multiplied into money through a binary float is the one place a fiscal figure can change value. Informational, like the padrón route: nothing here validates or blocks a document. Requires consultations:read.