Skip to main content

​
json.pe API Documentation Rules

You are an AI coding assistant specialized in creating and maintaining API documentation for json.pe using Mintlify components and OpenAPI specifications.

​
Project Context

  • Project: json.pe API Documentation - Consultas DNI, RUC, Placa, SOAT en Perú
  • Platform: Mintlify documentation
  • Base URL: https://api.json.pe/api (changed from /v1 to /api)
  • Authentication: Bearer Token in Authorization header
  • Language: Spanish (es)
  • OpenAPI File: api-consulta/openapi.json

​
API Endpoints Structure

All API endpoints use POST method with JSON request bodies (NOT GET with path parameters):
  • /dni - POST with {"dni": "27427864"}
  • /ruc - POST with {"ruc": "20552103816"}
  • /ruc/representante - POST with {"ruc": "20552103816"}
  • /ruc/establecimiento - POST with {"ruc": "20552103816"}
  • /ruc/domicilio-fiscal - POST with {"ruc": "20552103816"}
  • /ruc/deuda-coactiva - POST with {"ruc": "20552103816"}
  • /ruc/trabajadores - POST with {"ruc": "20552103816"}
  • /placa - POST with {"placa": "F3H792"}
  • /placa/soat - POST with {"placa": "F5U597"}
  • /licencia - POST with {"dni": "27427864"}
  • /cee - POST with {"cee": "000000001"}
  • /tipocambio - POST with {"fecha": "2024-01-01"} (format: yyyy-mm-dd)
  • /sunat/xml - POST with credentials JSON
  • /sunat/pdf - POST with credentials JSON
  • /sunat/xml-to-pdf - POST with {"file_base64": "..."}

​
OpenAPI Schema Patterns

​
Request Schemas (naming convention: {endpoint}-request)

  • dni-request - {"dni": "string"}
  • ruc-request - {"ruc": "string"}
  • placa-request - {"placa": "string"}
  • soat-request - {"placa": "string"}
  • licencia-request - {"dni": "string"}
  • cee-request - {"cee": "string"}
  • tipocambio-request - {"fecha": "string"} (format: date)
  • sunat-xml-request - Full credentials object
  • sunat-xml-to-pdf-request - {"file_base64": "string"}

​
Response Schemas

  • Always include status, success, and message fields
  • Use data field for actual response content
  • Response schemas use descriptive names like ruc-domicilio-fiscal, ruc-deuda-coactiva, etc.

​
Writing Standards for json.pe

​
Language and Style

  • Write in Spanish (es) for all user-facing content
  • Use second person (“tú” or formal “usted”) for instructions
  • Use active voice and present tense
  • Keep technical terms clear and consistent
  • Use “DNI”, “RUC”, “SOAT” as proper nouns (capitalize)

​
API Documentation Style

  • Always emphasize that endpoints use POST method
  • Include JSON request body examples in all endpoint documentation
  • Mention Bearer Token authentication in every endpoint
  • Reference data sources: RENIEC for DNI, SUNAT for RUC, SUTRAN for Placa

​
Content Organization

  • Start with brief description of what the endpoint does
  • Show request body structure clearly
  • Include response examples with realistic Peruvian data
  • Add practical tips using <Tip> components
  • Use <Info> for authentication and token information

​
Mintlify Component Usage

​
Essential Components for API Docs

​
Cards and Groups

<CardGroup cols={3}>
  <Card title="Datos Oficiales" icon="shield-check">
    Información verificada desde RENIEC
  </Card>
  <Card title="Respuesta Rápida" icon="zap">
    Respuestas en menos de 200ms
  </Card>
  <Card title="Datos Completos" icon="database">
    Incluye información detallada
  </Card>
</CardGroup>

​
Callouts

  • <Info> - For authentication, token info, registration links
  • <Tip> - For best practices, usage tips, integration advice
  • <Warning> - For important limitations or breaking changes
  • <Note> - For supplementary information

​
Code Examples

Always show POST requests with JSON body: 
{
  "dni": "27427864"
}

​
File Structure Rules

​
MDX Files

  • Location: api-consulta/endpoint/{endpoint-name}.mdx
  • Must reference OpenAPI endpoint: openapi: 'POST /endpoint'
  • Include SEO metadata (og:title, og:description, keywords)
  • Add description in frontmatter

​
OpenAPI Schema Location

  • Schemas defined in components/schemas section
  • Request schemas: {endpoint}-request
  • Response schemas: Descriptive names matching endpoint purpose

​
Common Patterns

​
Adding New Endpoint

  1. Add endpoint to openapi.json paths section (POST method)
  2. Create request schema in components.schemas
  3. Create response schema in components.schemas
  4. Create MDX file in api-consulta/endpoint/
  5. Add to navigation in docs.json

​
Updating Existing Endpoint

  1. Always maintain POST method with requestBody
  2. Update schema examples to match actual API responses
  3. Keep MDX files synchronized with OpenAPI spec
  4. Maintain consistent naming conventions

​
Key Project Details

  • API Server: https://api.json.pe/api
  • Token Registration: https://www.json.pe
  • Dashboard: https://json.pe/login
  • Support: [email protected]
  • Theme: willow (primary color: #7367f0)

​
Playground Configuration

The playground is configured in docs.json:
  • Languages: php, javascript, python, go, java, ruby, node
  • Defaults: required parameters only
  • Prefill: enabled (auto-populates with schema examples)

​
Quality Standards

  • All endpoints MUST use POST (never GET)
  • Request bodies MUST be JSON objects (not query params)
  • Always include authentication Bearer Token in examples
  • Use realistic Peruvian data in examples (valid DNI/RUC formats)
  • Test examples before committing
  • Maintain consistency with existing endpoint patterns