One Piece API logo
Referencia Técnica

Documentación de la API

Aprende a integrar la API definitiva sobre el lore de One Piece. Explora las convenciones de datos, endpoints de personajes y frutas, y sus estructuras JSON correspondientes.

# Resumen Rápido

La API de One Piece está diseñada bajo principios de arquitectura REST, entregando respuestas formateadas en JSON y optimizadas mediante caché interna.

URL BASE https://one-piece-api-azure.vercel.app/api/v1
FORMATO JSON (UTF-8)
AUTENTICACIÓN No Requerida (Acceso libre)

# Convenciones

Contenedor de Respuesta Estandarizado (Envelope)

Todas las respuestas que devuelven colecciones de recursos (ej: listados) están envueltas en un objeto JSON estándar que encapsula la data de respuesta y la paginación dentro del campo de metadatos `meta.pagination`.

Envelope Schema 
{
  "data": [ ... ],
  "meta": {
    "pagination": {
      "total": 102,
      "limit": 20,
      "offset": 0,
      "hasNext": true
    }
  }
}

Códigos de Estado y Manejo de Errores

La API utiliza códigos de estado HTTP estándar para informar sobre fallas o peticiones inválidas. Todos los errores devuelven un formato estructurado con el mensaje descriptivo:

404 Not Found

Retornado al buscar registros que no existen en base de datos.

{ "error": "Personaje no encontrado" }
429 Rate Limit Exceeded

Retornado cuando se supera el límite permitido de peticiones por minuto.

{ "error": "Rate limit exceeded" }

# Límites de Uso y Caché

Para mantener el servicio estable y gratuito, la API implementa límites de peticiones (Rate Limit) administrados mediante bases de datos Upstash Redis en memoria.

Cabeceras HTTP de Control de Flujo

Las respuestas devuelven las siguientes cabeceras que informan sobre tu cuota:

  • X-RateLimit-Limit: Número de peticiones permitidas por ventana temporal.
  • X-RateLimit-Remaining: Peticiones restantes disponibles en la ventana actual.
  • X-RateLimit-Reset: Tiempo Unix (en segundos) en el que se restablecerá tu cuota.

Políticas de Caché y ETags

Los resultados de las consultas se almacenan temporalmente en caché por 24 horas (TTL). Adicionalmente, las peticiones admiten la cabecera condicional de cliente ETag. Si la base de datos no ha cambiado, el servidor retornará un código 304 Not Modified sin volver a transferir el peso del JSON, ahorrando datos de red en tu aplicación móvil o web.

# Endpoints: Información General

GET /info

Obtiene metadatos generales de la API de One Piece, incluyendo la versión actual y enlaces a la documentación interactiva.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "name": "One Piece API",
  "version": "1.0.0",
  "docs": "https://one-piece-api-azure.vercel.app/api/v1",
  "api": "https://one-piece-api-azure.vercel.app/api/v1"
}
GET /health

Muestra el estado operativo de los servicios de la API y de las conexiones activas a la base de datos.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "status": "ok",
  "timestamp": "2026-05-23T00:00:00.000Z"
}

# Endpoints: Personajes

GET /personajes

Lista de forma paginada los personajes de la serie. Permite filtrado por nombre, raza, afiliación, ocupación, estado de vida y ordenación por recompensa.

Parámetros

Parámetro Tipo Requerido Default Descripción
limit number No 20 Cantidad máxima de registros a retornar (máximo 100).
offset number No 0 Número de registros a omitir para paginación.
raza string No - Filtro exacto por raza del personaje (ej: Humano, Mink, Cyborg).
tripulacion string No - Filtro exacto por nombre de tripulación o alianza (ej: Sombrero de Paja).
ocupacion string No - Filtro exacto por ocupación o rol (ej: Espadachín, Capitán).
fruta string No - Filtro exacto por nombre de fruta del diablo consumida.
estado string No - Estado vital (Vivo, Fallecido, Desconocido).
is_canon boolean No - Filtro de canonicidad (true/false).
q string No - Búsqueda parcial en nombre, romanización y nombre de nacimiento.
sort string No id Campo de ordenación: id, name, bounty.
order string No asc Sentido del orden: asc (ascendente), desc (descendente).

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": [
    {
      "id": 1,
      "name": "Monkey D. Luffy",
      "japaneseName": "モンキー・D・ルフィ",
      "romanizedName": "Monkī Dī Rufi",
      "race": "Humano",
      "status": "Vivo",
      "bounty": 3000000000,
      "bountyFormatted": "3,000,000,000",
      "imageUrl": "https://one-piece-api-azure.vercel.app/images/luffy.webp",
      "isCanon": true
    }
  ],
  "meta": {
    "pagination": {
      "total": 900,
      "limit": 1,
      "offset": 0,
      "hasNext": true
    }
  }
}
GET /personajes/buscar/{nombre}

Busca un personaje específico por su nombre (permite búsquedas parciales e insensibles a mayúsculas). Retorna el primer personaje que coincida.

Parámetros

Parámetro Tipo Requerido Default Descripción
nombre string Sí - Nombre (parcial o completo) del personaje a buscar en la base de datos.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": {
    "id": 1,
    "name": "Monkey D. Luffy",
    "japaneseName": "モンキー・D・ルフィ",
    "romanizedName": "Monkī Dī Rufi",
    "birthName": "Monkey D. Luffy",
    "race": "Humano",
    "origin": "Villa Foosha",
    "residence": "Barco Thousand Sunny",
    "status": "Vivo",
    "age": "19",
    "ageAtDeath": null,
    "birthday": "5 de mayo",
    "height": "1.74 m",
    "bloodType": "F",
    "bounty": 3000000000,
    "bountyFormatted": "3,000,000,000",
    "firstChapter": "Capítulo 1",
    "firstEpisode": "Episodio 1",
    "firstYear": 1997,
    "voiceActorJa": "Mayumi Tanaka",
    "voiceActorEsLa": "Diana Pérez / Mireya Mendoza",
    "imageUrl": "https://one-piece-api-azure.vercel.app/images/luffy.webp",
    "notes": "Protagonista principal de One Piece.",
    "isCanon": true,
    "devilFruits": [
      {
        "id": 1,
        "name": "Gomu Gomu no Mi",
        "type": "Paramecia",
        "status": "actual"
      }
    ],
    "affiliations": [
      {
        "id": 1,
        "name": "Piratas de Sombrero de Paja",
        "isFormer": false
      }
    ],
    "occupations": [
      {
        "id": 1,
        "name": "Capitán",
        "isFormer": false
      }
    ]
  }
}
GET /personajes/{id}

Obtiene la información técnica detallada de un personaje en base a su ID único. Incluye listado de frutas consumidas, afiliaciones y ocupaciones.

Parámetros

Parámetro Tipo Requerido Default Descripción
id number Sí - ID único y positivo del personaje.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": {
    "id": 1,
    "name": "Monkey D. Luffy",
    "japaneseName": "モンキー・D・ルフィ",
    "romanizedName": "Monkī Dī Rufi",
    "birthName": "Monkey D. Luffy",
    "race": "Humano",
    "origin": "Villa Foosha",
    "residence": "Barco Thousand Sunny",
    "status": "Vivo",
    "age": "19",
    "ageAtDeath": null,
    "birthday": "5 de mayo",
    "height": "1.74 m",
    "bloodType": "F",
    "bounty": 3000000000,
    "bountyFormatted": "3,000,000,000",
    "firstChapter": "Capítulo 1",
    "firstEpisode": "Episodio 1",
    "firstYear": 1997,
    "voiceActorJa": "Mayumi Tanaka",
    "voiceActorEsLa": "Diana Pérez / Mireya Mendoza",
    "imageUrl": "https://one-piece-api-azure.vercel.app/images/luffy.webp",
    "notes": "Protagonista principal de One Piece.",
    "isCanon": true,
    "devilFruits": [
      {
        "id": 1,
        "name": "Gomu Gomu no Mi",
        "type": "Paramecia",
        "status": "actual"
      }
    ],
    "affiliations": [
      {
        "id": 1,
        "name": "Piratas de Sombrero de Paja",
        "isFormer": false
      }
    ],
    "occupations": [
      {
        "id": 1,
        "name": "Capitán",
        "isFormer": false
      }
    ]
  }
}

# Endpoints: Frutas del Diablo

GET /frutas

Retorna la lista de las Frutas del Diablo registradas en el universo de One Piece, con soporte de filtrado por tipo, subtipo Zoan y búsqueda parcial.

Parámetros

Parámetro Tipo Requerido Default Descripción
limit number No 20 Cantidad máxima de frutas a retornar (máximo 100).
offset number No 0 Desplazamiento para paginación.
tipo string No - Filtro por tipo de fruta (Paramecia, Logia, Zoan).
tipo_zoan string No - Subtipo de fruta Zoan (ej: Mítica, Prehistórica).
q string No - Búsqueda parcial en el nombre, significado o romanización.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": [
    {
      "id": 1,
      "name": "Gomu Gomu no Mi",
      "japaneseName": "ゴムゴムの実",
      "romanizedName": "Gomu Gomu no Mi",
      "meaning": "Goma",
      "type": "Paramecia",
      "typeZoan": null,
      "firstAppearance": "Capítulo 1",
      "imageUrl": "https://one-piece-api-azure.vercel.app/images/gomu_gomu.webp"
    }
  ],
  "meta": {
    "pagination": {
      "total": 120,
      "limit": 1,
      "offset": 0,
      "hasNext": true
    }
  }
}
GET /frutas/buscar/{nombre}

Busca una Fruta del Diablo específica a partir de su nombre común (ej: Gomu Gomu).

Parámetros

Parámetro Tipo Requerido Default Descripción
nombre string Sí - Nombre (parcial o completo) de la fruta a buscar.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": {
    "id": 1,
    "name": "Gomu Gomu no Mi",
    "japaneseName": "ゴムゴムの実",
    "romanizedName": "Gomu Gomu no Mi",
    "meaning": "Goma",
    "type": "Paramecia",
    "typeZoan": null,
    "firstAppearance": "Capítulo 1",
    "imageUrl": "https://one-piece-api-azure.vercel.app/images/gomu_gomu.webp",
    "description": "Permite al consumidor estirarse como la goma.",
    "consumers": [
      {
        "id": 1,
        "name": "Monkey D. Luffy",
        "status": "actual"
      }
    ]
  }
}
GET /frutas/{id}

Retorna la información completa de una fruta del diablo por su ID numérico, incluyendo su descripción y listado de consumidores históricos.

Parámetros

Parámetro Tipo Requerido Default Descripción
id number Sí - ID único y positivo de la fruta del diablo.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": {
    "id": 1,
    "name": "Gomu Gomu no Mi",
    "japaneseName": "ゴムゴムの実",
    "romanizedName": "Gomu Gomu no Mi",
    "meaning": "Goma",
    "type": "Paramecia",
    "typeZoan": null,
    "firstAppearance": "Capítulo 1",
    "imageUrl": "https://one-piece-api-azure.vercel.app/images/gomu_gomu.webp",
    "description": "Permite al consumidor estirarse como la goma.",
    "consumers": [
      {
        "id": 1,
        "name": "Monkey D. Luffy",
        "status": "actual"
      }
    ]
  }
}

# Endpoints: Colecciones Auxiliares

GET /afiliaciones

Retorna la lista completa de tripulaciones y facciones registradas en la API. Útil para poblar campos de filtrado del frontend.

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": [
    {
      "id": 1,
      "name": "Piratas de Sombrero de Paja"
    },
    {
      "id": 2,
      "name": "Piratas de Heart"
    }
  ]
}
GET /ocupaciones

Retorna la lista completa de los roles y ocupaciones de la serie (ej: Arqueólogo, Francotirador, Capitán).

Ejemplo de Respuesta (200 OK)

JSON Response 
{
  "data": [
    {
      "id": 1,
      "name": "Arqueólogo"
    },
    {
      "id": 2,
      "name": "Capitán"
    }
  ]
}

# Modelos de Datos: Character

FormattedCharacter

Modelo extendido que representa los datos unificados del personaje e incluye arreglos anidados de sus frutas del diablo, afiliaciones y ocupaciones.

Esquema de Propiedades

Campo Tipo Nulo Descripción
id number No ID único del personaje.
name string No Nombre común en español.
japaneseName string null Nombre escrito en caracteres japoneses (Kanji/Kana).
romanizedName string null Nombre transliterado al alfabeto latino.
birthName string null Nombre de nacimiento oficial.
race string null Raza (Humano, Gyojin, Mink, Cyborg, etc.).
origin string null Lugar de procedencia o isla natal.
residence string null Base o residencia actual.
status string No Estado vital (Vivo, Fallecido, Desconocido).
age string null Edad actual registrada en el manga.
ageAtDeath string null Edad al momento de su muerte, si aplica.
birthday string null Cumpleaños (día/mes).
height string null Estatura expresada con unidades métricas.
bloodType string null Grupo sanguíneo oficial.
bounty number null Monto de la recompensa activa (número entero).
bountyFormatted string null Recompensa con formato numérico de millares.
firstChapter string null Capítulo del manga del debut.
firstEpisode string null Episodio del anime del debut.
firstYear number null Año de su debut real en el manga.
voiceActorJa string null Actor de voz japonés (Seiyū).
voiceActorEsLa string null Actor de voz latinoamericano.
imageUrl string null Enlace absoluto a la ilustración oficial.
notes string null Comentarios o notas de lore del personaje.
isCanon boolean No Indica si el personaje pertenece al canon del manga.
devilFruits array null Lista de frutas consumidas con su tipo y estatus de posesión (actual/pasado).
affiliations array null Lista de tripulaciones con indicador de si la membresía es antigua.
occupations array null Lista de ocupaciones con indicador de si la ocupación es antigua.
Estructura JSON Completa
schema-instance.json 
{
  "id": 1,
  "name": "Monkey D. Luffy",
  "japaneseName": "モンキー・D・ルフィ",
  "romanizedName": "Monkī Dī Rufi",
  "birthName": "Monkey D. Luffy",
  "race": "Humano",
  "origin": "Villa Foosha",
  "residence": "Barco Thousand Sunny",
  "status": "Vivo",
  "age": "19",
  "ageAtDeath": null,
  "birthday": "5 de mayo",
  "height": "1.74 m",
  "bloodType": "F",
  "bounty": 3000000000,
  "bountyFormatted": "3,000,000,000",
  "firstChapter": "Capítulo 1",
  "firstEpisode": "Episodio 1",
  "firstYear": 1997,
  "voiceActorJa": "Mayumi Tanaka",
  "voiceActorEsLa": "Diana Pérez / Mireya Mendoza",
  "imageUrl": "https://one-piece-api-azure.vercel.app/images/luffy.webp",
  "notes": "Protagonista principal de One Piece.",
  "isCanon": true,
  "devilFruits": [
    {
      "id": 1,
      "name": "Gomu Gomu no Mi",
      "type": "Paramecia",
      "status": "actual"
    }
  ],
  "affiliations": [
    {
      "id": 1,
      "name": "Piratas de Sombrero de Paja",
      "isFormer": false
    }
  ],
  "occupations": [
    {
      "id": 1,
      "name": "Capitán",
      "isFormer": false
    }
  ]
}

# Modelos de Datos: DevilFruit

FormattedFruit

Representa la información oficial de una Fruta del Diablo y la lista de personajes que la han consumido.

Esquema de Propiedades

Campo Tipo Nulo Descripción
id number No ID único de la fruta.
name string No Nombre de la Fruta del Diablo.
japaneseName string null Nombre escrito en caracteres japoneses.
romanizedName string null Nombre de la fruta transliterado.
meaning string null Significado traducido del nombre de la fruta.
type string No Tipo de fruta: Paramecia, Logia, Zoan.
typeZoan string null Subtipo de fruta Zoan (Mítica, Prehistórica, etc.), de lo contrario nulo.
firstAppearance string null Capítulo/Episodio en el que aparece por primera vez.
imageUrl string null Enlace absoluto al diseño de la fruta.
description string null Efecto detallado que otorga la fruta.
consumers array null Lista de consumidores conocidos y si su posesión es actual.
Estructura JSON Completa
schema-instance.json 
{
  "id": 1,
  "name": "Gomu Gomu no Mi",
  "japaneseName": "ゴムゴムの実",
  "romanizedName": "Gomu Gomu no Mi",
  "meaning": "Goma",
  "type": "Paramecia",
  "typeZoan": null,
  "firstAppearance": "Capítulo 1",
  "imageUrl": "https://one-piece-api-azure.vercel.app/images/gomu_gomu.webp",
  "description": "Permite al consumidor estirarse como la goma.",
  "consumers": [
    {
      "id": 1,
      "name": "Monkey D. Luffy",
      "status": "actual"
    }
  ]
}

# Modelos de Datos: Affiliation

Affiliation

Representación de una tripulación pirata, facción militar u organización militar en el universo de la serie.

Esquema de Propiedades

Campo Tipo Nulo Descripción
id number No ID único de la afiliación.
name string No Nombre de la tripulación o facción.
Estructura JSON Completa
schema-instance.json 
{
  "id": 1,
  "name": "Piratas de Sombrero de Paja"
}

# Modelos de Datos: Occupation

Occupation

Representación de un oficio, profesión o rango militar asignado a un personaje.

Esquema de Propiedades

Campo Tipo Nulo Descripción
id number No ID único del rol u ocupación.
name string No Nombre del puesto de trabajo.
Estructura JSON Completa
schema-instance.json 
{
  "id": 2,
  "name": "Capitán"
}