openapi: 3.1.0 info: title: API Thestral version: 1.0.0 description: |- Thestral es la API REST de Nerivia para integraciones externas: un solo host HTTPS, cuerpos JSON y un mismo esquema de firma para todos los productos. Nerivia no es custodial: nunca retiene tus fondos. ## Autenticación Thestral no usa tokens bearer: cada solicitud va firmada, así nadie puede reenviarla ni alterarla. Cada clave de API tiene dos valores: - `api_key_uuid`: el ID público de la clave, que envías en cada solicitud. - `api_key_signing_secret`: el secreto con el que firmas. Se muestra una sola vez, al crear la clave, y nunca vuelve a enviarse a Nerivia. Envía estos tres encabezados en cada solicitud: | Encabezado | Valor | | --- | --- | | `X-Nerivia-Key-Id` | Tu `api_key_uuid`. | | `X-Nerivia-Timestamp` | La hora Unix actual, en segundos. | | `X-Nerivia-Signature` | El HMAC-SHA256 del mensaje firmado, en hexadecimal y minúsculas, con tu `api_key_signing_secret` como clave. | El mensaje firmado es la marca de tiempo, un punto y el cuerpo exacto de la solicitud, en UTF-8: ```text . ``` - Firma exactamente los bytes que envías. Cualquier diferencia, incluso un espacio o el orden de las claves, invalida la firma. - Una solicitud sin cuerpo firma solo `.` - La marca de tiempo debe estar a menos de cinco minutos de la hora del servidor, así que mantén tu reloj sincronizado. Una firma inválida, una marca de tiempo desfasada, una clave revocada o expirada, o un espacio suspendido devuelven `401` con un código de error específico. Revoca una clave o define su vencimiento en el [panel de Nerivia](https://app.nerivia.io/). ## Espacios de trabajo Un espacio de trabajo reúne tu configuración, tus claves de API y tus pedidos, y nada pasa de un espacio a otro. Cada cuenta tiene dos: - **Producción**: pagos reales. - **Pruebas**: los mismos flujos en redes de prueba, para ensayar tu integración. Cada clave de API pertenece a un solo espacio, y Nerivia lo identifica a partir de esa clave: ninguna URL ni cuerpo lo nombra. Para pasar de pruebas a producción, firma con la clave del otro espacio. ## Errores Todos los errores tienen la misma forma: ```json { "errors": [ { "code": "neripay_order_amount_out_of_range", "field": null, "message": "El monto del pedido está fuera del rango aceptado." } ] } ``` - `code`: un ID estable y legible por máquinas. Basa tu lógica en él, nunca en el mensaje. - `field`: el campo de la solicitud que causó el error, o `null`. - `message`: una explicación legible en el idioma de `Accept-Language`, inglés o español. La lista `errors` trae un elemento por cada problema. El código de estado indica el tipo de falla: `400` para una solicitud inválida, `401` para una falla de autenticación, `403` para una falta de permisos y `404` para un objeto al que hace referencia la solicitud y que no existe en tu espacio. ## Webhooks En vez de consultar la API una y otra vez, registra la URL de tu endpoint en el panel y elige los eventos que quieres recibir. Cada suscripción tiene su propio secreto de firma. Nerivia envía un POST con un cuerpo JSON a tu endpoint, firmado igual que una solicitud: `X-Nerivia-Timestamp` y `X-Nerivia-Signature`, calculados sobre el cuerpo exacto con el secreto de esa suscripción. Verifica la firma antes de confiar en un envío y responde con cualquier estado `2xx` para confirmarlo. Si respondes con otro estado o no respondes a tiempo, Nerivia reintenta un número limitado de veces. ## Soporte ¿Necesitas ayuda? Escríbenos por WhatsApp al +593 963 187 317. servers: - url: https://api.nerivia.io/v1/thestral/neripay security: - keyId: [] timestamp: [] signature: [] tags: - name: Asset Ledger Configs x-displayName: Configuraciones de activo y red description: |- Una configuración de activo y red es un activo en una red blockchain (ledger) que tu espacio acepta, como USDT en Polygon, con su dirección de recepción, su comisión y sus montos mínimo y máximo. Las configuras en el panel y la API las consulta. - name: Orders x-displayName: Pedidos description: |- Un pedido le pide a un cliente pagar un monto en un activo sobre una red, a una dirección exclusiva de ese pedido. Pasa por estos estados por sí solo: | Estado | Significado | | --- | --- | | `awaiting_payment` | Creado y en espera del pago del cliente hasta `expires_at`. | | `paid` | Pago confirmado en la blockchain. Entrega el pedido en este punto. | | `settling` | Nerivia está enviando los fondos a tu dirección de recepción. | | `completed` | Los fondos llegaron a tu dirección de recepción. | | `expired` | No llegó ningún pago antes de `expires_at`. | | `settlement_failed` | Falló el envío de los fondos a tu dirección de recepción. | Suscríbete al evento de webhook `neripay.order.status.change` para seguir estos cambios, o consulta Listar pedidos con el `uuid` del pedido como filtro. components: securitySchemes: keyId: type: apiKey in: header name: X-Nerivia-Key-Id description: |- Tu `api_key_uuid`. timestamp: type: apiKey in: header name: X-Nerivia-Timestamp description: |- La hora Unix actual, en segundos. signature: type: apiKey in: header name: X-Nerivia-Signature description: |- El HMAC-SHA256 de `.`, en hexadecimal y minúsculas, con tu `api_key_signing_secret` como clave. parameters: limit: &limitParam name: limit in: query required: false description: |- Elementos por página. Por defecto, `10`, valor que también se usa si el que envías no es válido. schema: type: integer default: 10 offset: &offsetParam name: offset in: query required: false description: |- Elementos que se omiten antes de empezar la página. Por defecto, `0`, valor que también se usa si el que envías no es válido. schema: type: integer default: 0 asset: &assetParam name: asset in: query required: false description: |- Solo configuraciones de este `uuid` de activo, en cada red donde esté configurado. schema: type: string format: uuid ledger: &ledgerParam name: ledger in: query required: false description: |- Solo configuraciones en este `uuid` de red, para cada activo configurado en ella. schema: type: string format: uuid status: &statusParam name: status in: query required: false description: |- Solo pedidos en este estado. schema: type: string enum: - awaiting_payment - paid - settling - completed - expired - settlement_failed uuid: &uuidFilterParam name: uuid in: query required: false description: |- Solo el pedido con este ID. schema: type: string format: uuid created_at__gte: &createdAtGteParam name: created_at__gte in: query required: false description: |- Solo pedidos creados en este momento o después. Un valor sin zona horaria se interpreta en UTC. schema: type: string format: date-time created_at__lte: &createdAtLteParam name: created_at__lte in: query required: false description: |- Solo pedidos creados en este momento o antes. Un valor sin zona horaria se interpreta en UTC. schema: type: string format: date-time responses: BadRequest: &BadRequest description: |- La solicitud no es válida. `errors` lista cada problema. content: application/json: schema: &errorEnvelopeSchema type: object properties: errors: type: array description: |- Un elemento por cada problema. items: type: object properties: code: type: string description: |- Un ID de error estable y legible por máquinas. Basa tu lógica en él, nunca en `message`. field: type: [string, 'null'] description: |- El campo de la solicitud que causó el error, o `null`. message: type: string description: |- Una explicación legible en el idioma de `Accept-Language`. example: errors: - code: neripay_order_amount_out_of_range field: null message: El monto del pedido está fuera del rango aceptado. Unauthorized: &Unauthorized description: |- Falló la autenticación: firma inválida, marca de tiempo desfasada, clave revocada o expirada, o espacio suspendido. content: application/json: schema: *errorEnvelopeSchema Forbidden: &Forbidden description: |- La clave no tiene permiso para esta acción. content: application/json: schema: *errorEnvelopeSchema NotFound: &NotFound description: |- Un objeto al que hace referencia la solicitud no existe en tu espacio. content: application/json: schema: *errorEnvelopeSchema paths: /workspace-config/asset-ledger-configs/: get: summary: Listar configuraciones de activo y red description: |- Devuelve las configuraciones **activas** de tu espacio, de la más reciente a la más antigua: cada par de activo y red en el que puedes crear pedidos ahora mismo. Las inactivas nunca aparecen y ningún filtro las incluye. Filtra por activo o por red con los UUID dentro del objeto `asset_ledger` de un elemento, nunca con el `uuid` de la configuración. Si usas varios filtros, se aplican todos a la vez. Un valor que la API no puede leer, como un UUID mal formado, devuelve una lista vacía, nunca la lista sin filtrar. Un espacio sin configuraciones activas recibe un `200` con la lista `results` vacía: configura una en el panel antes de crear pedidos. tags: - Asset Ledger Configs parameters: - *assetParam - *ledgerParam - *limitParam - *offsetParam responses: '200': description: |- Tus configuraciones de activo y red activas. content: application/json: schema: type: object properties: count: type: integer description: |- Elementos que coinciden con tus filtros, en todas las páginas. next: type: [string, 'null'] format: uri description: |- URL de la página siguiente, o `null` en la última. previous: type: [string, 'null'] format: uri description: |- URL de la página anterior, o `null` en la primera. results: type: array description: |- Los elementos de esta página, del más reciente al más antiguo. items: type: object properties: uuid: type: string description: |- El ID de la configuración. No es el valor que envías al crear un pedido. is_active: type: boolean description: |- Si el par acepta pedidos. Aquí siempre es `true`. commission_rate: type: string format: decimal description: |- La comisión de Nerivia en porcentaje: `"2.50"` significa 2.50%. Cada pedido nuevo conserva la tasa vigente al crearse. min_amount: type: string format: decimal description: |- El monto mínimo aceptado por pedido, en unidades del activo. max_amount: type: string format: decimal description: |- El monto máximo aceptado por pedido, en unidades del activo. receiving_address: type: string description: |- La dirección a la que se envía tu parte de cada pedido liquidado. Revísala después de cualquier cambio en el panel. asset_ledger: type: object description: |- El activo y la red de esta configuración. properties: uuid: type: string description: |- ID del par de activo y red. Envíalo como `asset_ledger` al crear un pedido. contract_address: type: [string, 'null'] description: |- La dirección del contrato del token en esta red, o `null` si es el activo nativo de la red. No es donde paga el cliente. asset: type: object description: |- El activo, como Tether USD. properties: uuid: type: string description: |- El ID del activo. name: type: string description: |- El nombre del activo, como Tether USD. code: type: string description: |- El código del activo, como `USDT`. decimals: type: integer description: |- Los decimales que admite el activo, que limitan la precisión del monto de un pedido. ledger: type: object description: |- La red blockchain (ledger), como Polygon. properties: uuid: type: string description: |- El ID de la red. name: type: string description: |- El nombre de la red, como Polygon Amoy. code: type: string description: |- El código de la red, como `polygon-amoy`. address_regex: type: [string, 'null'] description: |- El patrón que debe cumplir una dirección en esta red, o `null` si no se conoce. example: count: 1 next: null previous: null results: - uuid: 59a13b02-a4b5-4d42-9d20-19d42be990e9 is_active: true commission_rate: '2.50' min_amount: '1.000000000000000000' max_amount: '10000.000000000000000000' receiving_address: '0xf59fedB5D38CD00995AC1D8256f4CfeF46FD58a3' asset_ledger: uuid: 37caa3f8-79f3-48a3-bde2-840636f50df2 contract_address: '0x0502986e4Be5d3e0A98D68A0fD0f7683F9968843' asset: uuid: 46588bb4-600b-4e41-a5c0-95071166f41d name: Tether USD code: USDT decimals: 2 ledger: uuid: 85a198fd-4ee6-4f17-bbeb-040ff46896dc name: Polygon Amoy code: polygon-amoy address_regex: ^0x[0-9a-fA-F]{40}$ '401': *Unauthorized '403': *Forbidden /orders/: get: summary: Listar pedidos description: |- Devuelve los pedidos de tu espacio, del más reciente al más antiguo. Filtra por `created_at` con los dos parámetros de fecha, que incluyen sus límites; la respuesta no incluye ese campo. Si usas varios filtros, se aplican todos a la vez. Un valor que la API no puede leer, como un UUID mal formado, devuelve una lista vacía, nunca la lista sin filtrar. Los elementos de la lista no traen `checkout_url`: tómalo de la respuesta de creación. tags: - Orders parameters: - *statusParam - *uuidFilterParam - *createdAtGteParam - *createdAtLteParam - *limitParam - *offsetParam responses: '200': description: |- Tus pedidos. content: application/json: schema: type: object properties: count: type: integer description: |- Elementos que coinciden con tus filtros, en todas las páginas. next: type: [string, 'null'] format: uri description: |- URL de la página siguiente, o `null` en la última. previous: type: [string, 'null'] format: uri description: |- URL de la página anterior, o `null` en la primera. results: type: array description: |- Los elementos de esta página, del más reciente al más antiguo. items: type: object properties: uuid: type: string description: |- El ID del pedido. Guárdalo para encontrar el pedido después con el filtro `uuid`. amount: type: string format: decimal description: |- Lo que paga el cliente, en unidades del activo. La comisión de Nerivia se descuenta de este monto, no se suma. commission_rate: type: string format: decimal description: |- La comisión de Nerivia en porcentaje, fijada al crear el pedido. status: type: string description: |- El estado actual del pedido, como `awaiting_payment` o `paid`. expires_at: type: string format: date-time description: |- Cuándo deja de aceptar pagos el pedido. Basa tu cuenta regresiva en este valor en vez de asumir un plazo fijo. contract_address: type: string description: |- La dirección de liquidación propia del pedido, donde paga el cliente. Úsala solo para este pedido. asset_ledger: type: object description: |- El activo y la red en que se cobra el pedido. properties: uuid: type: string description: |- ID del par de activo y red. asset: type: object description: |- El activo, como Tether USD. properties: uuid: type: string description: |- El ID del activo. name: type: string description: |- El nombre del activo, como Tether USD. code: type: string description: |- El código del activo, como `USDT`. decimals: type: integer description: |- Los decimales que admite el activo, que limitan la precisión del monto de un pedido. ledger: type: object description: |- La red blockchain (ledger), como Polygon. properties: uuid: type: string description: |- El ID de la red. name: type: string description: |- El nombre de la red, como Polygon Amoy. code: type: string description: |- El código de la red, como `polygon-amoy`. address_regex: type: [string, 'null'] description: |- El patrón que debe cumplir una dirección en esta red, o `null` si no se conoce. contract_address: type: [string, 'null'] description: |- La dirección del contrato del token en esta red, o `null` si es el activo nativo de la red. No es donde paga el cliente. external_reference: type: [string, 'null'] description: |- Tu propio ID del pedido, o `null` si se creó desde el panel. example: count: 1 next: null previous: null results: - uuid: e75f7105-d903-4d69-b1ea-17bbfbd7f777 amount: '10.000000000000000000' commission_rate: '2.50' status: settlement_failed expires_at: '2026-09-11T05:44:18.988829Z' contract_address: '0x0146a0AA378044be8a59e2aee97B00Cac073539C' asset_ledger: uuid: 37caa3f8-79f3-48a3-bde2-840636f50df2 asset: uuid: 46588bb4-600b-4e41-a5c0-95071166f41d name: Tether USD code: USDT decimals: 2 ledger: uuid: 85a198fd-4ee6-4f17-bbeb-040ff46896dc name: Polygon Amoy code: polygon-amoy address_regex: ^0x[0-9a-fA-F]{40}$ contract_address: '0x0502986e4Be5d3e0A98D68A0fD0f7683F9968843' external_reference: null '401': *Unauthorized '403': *Forbidden post: summary: Crear pedido description: |- Crea un pedido de pago por un monto en un activo sobre una red. Nerivia le asigna al pedido su propia dirección de liquidación, empieza a vigilarla y devuelve el pedido con un `checkout_url`: una página de pago alojada a la que puedes enviar a tu cliente en lugar de crear la tuya. Un pedido nuevo empieza en `awaiting_payment`, y su plazo de pago comienza en cuanto esta llamada tiene éxito. #### Después de crearlo Muéstrale a tu cliente `contract_address` y `amount`, o envíalo a `checkout_url`. Nerivia confirma el pago, marca el pedido como `paid`, envía los fondos a tu dirección de recepción y lo marca como `completed`, sin que tengas que hacer otra llamada. Entrega el pedido al llegar a `paid`, no a `completed`: `paid` significa que tu cliente ya pagó, y `completed` solo indica que los fondos ya te llegaron. tags: - Orders requestBody: description: |- El pedido que se va a crear. Los tres campos son obligatorios y cualquier otro campo se ignora. content: application/json: schema: type: object required: - asset_ledger - amount - external_reference properties: asset_ledger: type: string description: |- El `asset_ledger.uuid` de una configuración de activo y red activa en el espacio de tu clave. amount: type: string format: decimal description: |- Lo que paga el cliente, como decimal en texto y en unidades del activo, por ejemplo `"25.50"`. Debe estar entre el `min_amount` y el `max_amount` de la configuración, no tener más decimales de los que admite el activo y tener como máximo 36 dígitos y 18 decimales. external_reference: type: string description: |- Tu propio ID del pedido, como un número de factura. Hasta 36 caracteres y único en tu espacio, así un reintento nunca duplica un cobro. example: asset_ledger: 37caa3f8-79f3-48a3-bde2-840636f50df2 amount: '100.00' external_reference: AAA-000-000-003 responses: '201': description: |- El pedido creado. content: application/json: schema: type: object properties: uuid: type: string description: |- El ID del pedido. Guárdalo para encontrar el pedido después con el filtro `uuid`. amount: type: string format: decimal description: |- Lo que paga el cliente, en unidades del activo. La comisión de Nerivia se descuenta de este monto, no se suma. commission_rate: type: string format: decimal description: |- La comisión de Nerivia en porcentaje, fijada al crear el pedido. status: type: string description: |- El estado actual del pedido, como `awaiting_payment` o `paid`. expires_at: type: string format: date-time description: |- Cuándo deja de aceptar pagos el pedido. Basa tu cuenta regresiva en este valor en vez de asumir un plazo fijo. contract_address: type: string description: |- La dirección de liquidación propia del pedido, donde paga el cliente. Úsala solo para este pedido. asset_ledger: type: object description: |- El activo y la red en que se cobra el pedido. properties: uuid: type: string description: |- ID del par de activo y red. asset: type: object description: |- El activo, como Tether USD. properties: uuid: type: string description: |- El ID del activo. name: type: string description: |- El nombre del activo, como Tether USD. code: type: string description: |- El código del activo, como `USDT`. decimals: type: integer description: |- Los decimales que admite el activo, que limitan la precisión del monto de un pedido. ledger: type: object description: |- La red blockchain (ledger), como Polygon. properties: uuid: type: string description: |- El ID de la red. name: type: string description: |- El nombre de la red, como Polygon Amoy. code: type: string description: |- El código de la red, como `polygon-amoy`. address_regex: type: [string, 'null'] description: |- El patrón que debe cumplir una dirección en esta red, o `null` si no se conoce. contract_address: type: [string, 'null'] description: |- La dirección del contrato del token en esta red, o `null` si es el activo nativo de la red. No es donde paga el cliente. external_reference: type: string description: |- Tu propio ID del pedido, tal como lo enviaste. checkout_url: type: string format: uri description: |- Una página de pago alojada por Nerivia solo para este pedido, que puedes compartir con tu cliente. example: uuid: 9ba6ade8-416a-495b-8cf6-6eeac215ab08 amount: '100.000000000000000000' commission_rate: '2.50' status: awaiting_payment expires_at: '2026-09-11T21:45:03.204571Z' contract_address: '0x23BDBDbAD94Bb5CD2D8AD44645523D4A5Bd1aeD9' asset_ledger: uuid: 37caa3f8-79f3-48a3-bde2-840636f50df2 asset: uuid: 46588bb4-600b-4e41-a5c0-95071166f41d name: Tether USD code: USDT decimals: 2 ledger: uuid: 85a198fd-4ee6-4f17-bbeb-040ff46896dc name: Polygon Amoy code: polygon-amoy address_regex: ^0x[0-9a-fA-F]{40}$ contract_address: '0x0502986e4Be5d3e0A98D68A0fD0f7683F9968843' external_reference: AAA-000-000-001 checkout_url: https://app.nerivia.io/neripay/checkout/9ba6ade8-416a-495b-8cf6-6eeac215ab08 '400': *BadRequest '401': *Unauthorized '403': *Forbidden '404': *NotFound