---
name: faktura-verificar-la-api-key
description: "Verificar la API key con la API de Faktura (facturación electrónica SUNAT, Perú). Devuelve la empresa emisora y el entorno de la API key usada. Úsalo para comprobar que tu integración se conecta bien y si tu empresa ya está lista para prod… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Verificar la API key — Faktura API

## Propósito

Le da a tu asistente el contexto para **verificar la API key** con la API de Faktura: Devuelve la empresa emisora y el entorno de la API key usada. Úsalo para comprobar que tu integración se conecta bien y si tu empresa ya está lista para prod…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-verificar-la-api-key/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/endpoints/me/

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/me` |
| Producción | `GET https://faktura.cgallardo.me/v1/me` |

## Autenticación y cabeceras

- `Authorization: Bearer <api key>`. En pruebas, una clave `sk_test_` (SUNAT beta, sin valor tributario); en producción, la `sk_live_`. El ambiente lo decide la clave.
- `Content-Type: application/json` en las peticiones con cuerpo.
- `Idempotency-Key` (recomendada al emitir): repetir la petición con la misma clave y el mismo cuerpo devuelve el mismo comprobante, sin duplicarlo.
- Errores: JSON `{ "reason": "<código>", "details": [...] }`. `401` clave inválida o vencida, `403` alcance insuficiente, `422` datos inválidos, `429` límite de 120 peticiones por minuto (respeta `Retry-After`), `500` solo con `traceId`.

```bash
curl https://faktura-test.cgallardo.me/v1/me -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK`

```json
{
  "company": {
    "id": "01a1d52b-90eb-7207-b415-4e3f2ba3f9bd",
    "ruc": "20000000001",
    "legal_name": "FAKTURA BETA S.A.C.",
    "trade_name": null,
    "has_certificate": true,
    "has_sol_credentials": true,
    "certificate_valid_until": "2027-11-13T23:59:59+00:00"
  },
  "api_key": { "prefix": "sk_test_ec829766c02e", "environment": "test", "scope": "full", "expires_at": null },
  "sunat_environment": "beta"
}
```

| Campo | Descripción |
| --- | --- |
| `company.has_certificate` | Tu certificado digital ya está cargado. |
| `company.has_sol_credentials` | Tu usuario SOL secundario ya está configurado. Ambos son necesarios para emitir con una clave `live`. |
| `company.certificate_valid_until` | Vencimiento de tu certificado digital (`null` si no hay). Renuévalo antes: vencido, la firma deja de ser válida y SUNAT rechaza los envíos. |
| `api_key.environment` | `test` o `live`. |
| `api_key.scope` | `full` (emitir y consultar) o `lookup` (solo consultas de RUC y DNI). |
| `api_key.expires_at` | Vencimiento de la clave (`null` si no vence). Los accesos de prueba vencen: desde ese momento toda llamada responde `401` y hay que pedir otra clave. |
| `sunat_environment` | `beta` o `production`: adónde se envían los comprobantes de esta clave. |

## Respuestas y errores

| Estado | `reason` | Significado |
| --- | --- | --- |
| `200` | — | Devuelve los datos del emisor y de la API key. |
| `401` | `Unauthenticated` | Falta la API key, es inválida, fue revocada o venció. |
| `429` | `TooManyRequests` | Superaste las 120 peticiones por minuto. |

## Reglas generales de la API

- Montos en las respuestas como texto decimal (`"16.00"`); en las peticiones, número o texto.
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`); identificadores UUID.
- Un comprobante emitido responde `201` con `status: "pending"`: el número ya es tuyo. El resultado de SUNAT llega después (webhook o `GET /v1/documents/{id}`).
- Documentación completa: https://faktura-doc.cgallardo.me/ · Toda la API en una skill: https://faktura-doc.cgallardo.me/skills/faktura-api.md
